Project: kpt (Provisioning / Automation & Configuration)
File: porch-user-guide.md

This document is focused on using Porch via the `kpt` CLI. Installation of Porch, including prerequisites, is covered in a . To use Porch, you will need: (if running on GKE) Make sure that your `kubectl` context is set up for `kubectl` to interact with the correct Kubernetes instance (see or the guide for details). To check whether `kubectl` is configured with your Porch cluster (or local instance), run: ```sh kubectl api-resources | grep porch ``` You should see the following four resourceds listed: ``` repositories config.porch.kpt.dev/v1alpha1 true Repository packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision functions porch.kpt.dev/v1alpha1 true Function ``` Porch server manages the following resources: `repositories`: a repository (Git or OCI) can be registered with Porch to support discovery or management of KRM configuration packages in those repositories, or discovery of KRM functions in those repositories. `packagerevisions`: a specific revision of a KRM configuration package managed by Porch in one of the registered repositories. This resource represents a metadata view of the KRM configuration package. `packagerevisionresources`: this resource represents the contents of the configuration package (KRM resources contained in the package) `functions`: function resource represents a KRM function discovered in a repository registered with Porch. Functions are only supported with OCI repositories. Note that `packagerevisions` and `packagerevisionresources` represent different views of the same underlying KRM configuration package. `packagerevisions` represents the package metadata, and `packagerevisionresources` represents the package content. The matching resources share the same `name` (as well as API group and version: `porch.kpt.dev/v1alpha1`) and differ in resource kind (`PackageRevision` and `PackageRevisionResources` respectively). To use Porch with a Git repository, you will need: A Git repository for your blueprints. A (when using GitHub repository) for Porch to authenticate with the repository. Porch requires the 'repo' scope. Or Basic Auth credentials for Porch to authenticate with the repository. To use Porch with an OCI repository ( or ), first make sure to: Enable for Porch Assign appropriate roles to the Porch workload identity service account (`iam.gke.io/gcp-service-account=porch-server@$(GCPPROJECTID).iam.gserviceaccount.com`) to have appropriate level of access to your OCI repository. Use the `kpt alpha repo register` command to register your repository with Porch: ```sh GITHUB_USERNAME=<your github username> GITHUB_TOKEN=<GitHub Personal Access Token> $ kpt alpha repo register \ --namespace default \ --repo-basic-username=${GITHUB_USERNAME} \ --repo-basic-password=${GITHUB_TOKEN} \ https://github.com/${GITHUB_USERNAME}/blueprints.git ``` All command line flags supported: `--directory` - Directory within the repository where to look for packages. `--branch` - Branch in the repository where finalized packages are committed. (defaults to `main`) `--name` - Name of the package repository Kubernetes resource. If unspecified, will default to the name portion (last segment) of the repository URL (`blueprint` in the example above) `--description` - Brief description of the package repository. `--deployment` - Boolean value; If specified, repository is a deployment repository; published packages in a deployment repository are considered deployment-ready. `--repo-basic-username` - Username for repository authentication using basic auth. `--repo-basic-password` - Password for repository authentication using basic auth. Additionally, common `kubectl` command line flags for controlling aspects of interaction with the Kubernetes apiserver, logging, and more (this is true for all `kpt` CLI commands which interact with

Use the `kpt alpha repo get` command to query registered repositories: ```sh $ kpt alpha repo get NAME TYPE CONTENT DEPLOYMENT READY ADDRESS blueprints git Package True https://github.com/platkrm/blueprints.git deployments git Package true True https://github.com/platkrm/deployments.git ``` The `kpt alpha <group> get` commands support common `kubectl` to format output, for example `kpt alpha repo get --output=yaml`. The command `kpt alpha repo unregister` can be used to unregister a repository: ```sh $ kpt alpha repo unregister deployments --namespace default ``` The `kpt alpha rpkg` command group contains commands for interacting with packages managed by the Package Orchestration service. the `r` prefix used in the command group name stands for 'remote'. The `kpt alpha rpkg get` command list the packages in registered repositories: ```sh $ kpt alpha rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-0349d71330b89ee48ac85167598ef23021fd0484 basens main main false Published blueprints blueprints-2e47615fda05664491f72c58b8ab658683afa036 basens v1 v1 true Published blueprints blueprints-7e2fe44bfdbb744d49bdaaaeac596200102c5f7c istions main main false Published blueprints blueprints-ac6e872be4a4a3476922deca58cca3183b16a5f7 istions v1 v1 false Published blueprints blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints ... ``` The `LATEST` column indicates whether the package revision is the latest among the revisions of the same package. In the output above, `v2` is the latest revision of `istions` package and `v1` is the latest revision of `basens` package. The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Published`, `Draft` or `Proposed`. The `REVISION` column indicates the revision of the package. Revisions are assigned when a package is `Published` and starts at `v1`. The `WORKSPACENAME` column indicates the workspace name of the package. The workspace name is assigned when a draft revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be must be unique among package revisions in the same package. Note on package revision names. Packages exist in a hierarchical directory structure maintained by the underlying repository such as git, or in a filesystem bundle of OCI images. The hierarchical, filesystem-compatible names of packages do not satisfy the Kubernetes naming . Therefore, the names of the Kubernetes resources representing package revisions are computed as a hash. Simple filtering of package revisions by name (substring) and revision (exact match) is supported by the CLI using `--name` and `--revision` flags: ```sh $ kpt alpha rpkg get --name istio --revision=v2 NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints ``` The common `kubectl` flags that control output format are available as well: ```sh $ kpt alpha rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml apiVersion: porch.kpt.dev/v1alpha1 kind: PackageRevision metadata: labels: kpt.dev/latest-revision: "true" name: blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 namespace: default spec: lifecycle: Published packageName: istions repository: blueprints revision: v2 workspaceName: v2 ... ``` The `kpt alpha rpkg pull` command can be used to read the package resources. The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables evaluation of functions on the package revision pulled from the Package Orchestration server. ```sh $ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList items: apiVersion: kpt.dev/v1 kind: Kptfile metadata: name: istions ... ``` Or, the package contents can be saved on local disk for direct introspection or editing: ```sh $ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3

-ndefault $ find istions istions istions/istions.yaml istions/README.md istions/Kptfile istions/package-context.yaml ... ``` Several commands in the `kpt alpha rpkg` group support package authoring: `init` - Initializes a new package revision in the target repository. `clone` - Creates a clone of a source package in the target repository. `copy` - Creates a new package revision from an existing one. `push` - Pushes package resources into a remote package. `del` - Deletes one or more packages in registered repositories. The `kpt alpha rpkg init` command can be used to initialize a new package revision. Porch server will create and initialize a new package (as a draft) and save it in the specified repository. ```sh $ kpt alpha rpkg init new-package --repository=deployments --workspace=v1 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 created $ kpt alpha rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments ... ``` The new package is created in the `Draft` lifecycle stage. This is true also for all commands that create new package revision (`init`, `clone` and `copy`). Additional flags supported by the `kpt alpha rpkg init` command are: `--repository` - Repository in which the package will be created. `--workspace` - Workspace of the new package. `--description` - Short description of the package. `--keywords` - List of keywords for the package. `--site` - Link to page with information about the package. Use `kpt alpha rpkg clone` command to create a downstream package by cloning an upstream package: ```sh $ kpt alpha rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ --repository=deployments -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 created kpt alpha rpkg get deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 false Draft deployments ``` `kpt alpha rpkg clone` can also be used to clone packages that are in repositories not registered with Porch, for example: ```sh $ kpt alpha rpkg clone \ https://github.com/GoogleCloudPlatform/blueprints.git cloned-bucket \ --directory=catalog/bucket \ --ref=main \ --repository=deployments \ --namespace=default deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac created kpt alpha rpkg get deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments ``` The flags supported by the `kpt alpha rpkg clone` command are: `--directory` - Directory within the upstream repository where the upstream package is located. `--ref` - Ref in the upstream repository where the upstream package is located. This can be a branch, tag, or SHA. `--repository` - Repository to which package will be cloned (downstream repository). `--workspace` - Workspace to assign to the downstream package. `--strategy` - Update strategy that should be used when updating this package; one of: `resource-merge`, `fast-forward`, `force-delete-replace`. The `kpt alpha rpkg copy` command can be used to create a new revision of an existing package. It is a means to modifying an already published package revision. ```sh $ kpt alpha rpkg copy \ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 \ --workspace=v3 -ndefault $ kpt alpha rpkg get blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 istions v3 false Draft blueprints ``` The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package draft: ```sh $ kpt alpha rpkg pull \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault $ cat <<EOF >

apiVersion: v1 kind: ConfigMap metadata: name: example-config-map data: color: orange EOF $ kpt alpha rpkg push \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault $ kpt alpha rpkg pull deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList items: ... apiVersion: v1 kind: ConfigMap metadata: name: example-config-map data: color: orange ... ``` Package revision can be deleted using `kpt alpha rpkg del` command: ```sh $ kpt alpha rpkg del blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 deleted ``` Authoring is performed on the package revisions in the Draft lifecycle stage. Before a package can be deployed or cloned, it must be Published. The approval flow is the process by which the package is advanced from Draft state through Proposed state and finally to Published lifecycle stage. The commands used to manage package lifecycle stages include: `propose` - Proposes to finalize a package revision draft `approve` - Approves a proposal to finalize a package revision. `reject` - Rejects a proposal to finalize a package revision In the section above we created several draft packages and in this section we will create proposals for publishing some of them. ```sh $ kpt alpha rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 false Draft deployments deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments $ kpt alpha rpkg propose \ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 \ -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 proposed deployments-c32b851b591b860efda29ba0e006725c8c1f7764 proposed $ kpt alpha rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 false Proposed deployments deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Proposed deployments ``` At this point, a person in platform administrator role, or even an automated process, will review and either approve or reject the proposals. To aid with the decision, the platform administrator may inspect the package contents using the commands above, such as `kpt alpha rpkg pull`. ```sh $ kpt alpha rpkg approve deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 approved $ kpt alpha rpkg reject deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 rejected ``` Now the user can confirm lifecycle stages of the package revisions: ```sh $ kpt alpha rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 v1 true Published deployments deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments ``` Observe that the rejected proposal returned the package revision back to Draft lifecycle stage. The package whose proposal was approved is now in Published state. Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named `sync` to emphasize that Config Sync is the deploying mechanism and that configuration is being synchronized with the actuation target as a means of deployment) and include: `create` - Creates a sync of a package in the deployment cluster. `del` - Deletes the package RootSync. `get` - Gets a RootSync resource with which package was deployed. ```sh kubectl apply -f - <<EOF apiVersion: configmanagement.gke.io/v1 kind: ConfigManagement metadata: name: config-management spec: enableMultiRepo: true EOF $ kpt alpha sync create -ndefault \ --package=deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ sync-istions-clone Created RootSync config-management-system/sync-istions-clone $ kpt alpha sync get sync-istions-clone -oyaml apiVersion: configsync.gke.io/v1beta1 kind: RootSync metadata: name: sync-istions-clone namespace: config-management-system ... $ kpt alpha sync delete sync-istions-clone Deleting synced resources Waiting for deleted resources to be removed Sync sync-istions-clone successfully deleted ```