porch-installation.md

Installing Porch

You can install Porch by either using one of the released versions, or building Porch from sources.

Prerequisites

Note: Porch should run on any kubernetes cluster and should work on any cloud. We have just started by documenting one known-good configuration: GCP and GKE. We would welcome comparable installation instructions or feedback from people that try it out on other clouds / configurations.

To run one of the released versions of Porch on GKE, you will need:

• A GCP Project
• gcloud
• kubectl; you can install it via gcloud components install kubectl
• kpt
• Command line utilities such as curl, tar

To build and run Porch on GKE, you will also need:

• A container registry which will work with your GKE cluster. Artifact Registry or Container Registry work well though you can use others too.
• go 1.17 or newer
• docker
• Configured docker credential helper
• git
• make

Getting Started

Make sure your gcloud is configured with your project (alternatively, you can augment all following gcloud commands below with --project flag):

gcloud config set project YOUR_GCP_PROJECT

Select a GKE cluster or create a new one:

gcloud services enable container.googleapis.com
gcloud container clusters create-auto --region us-central1 porch-dev

Note: For development of Porch, in particular for running Porch tests, Standard GKE cluster is currently preferable. Select a GCP region that works best for your needs:

gcloud services enable container.googleapis.com
gcloud container clusters create --region us-central1 porch-dev

And ensure kubectl is targeting your GKE cluster:

gcloud container clusters get-credentials --region us-central1 porch-dev

Run Released Version of Porch

To run a released version of Porch, download the release config bundle from Porch release page; please note you'll need to scroll past recent kpt releases to the most recent porch/... release.

Untar and apply the deployment-blueprint.tar.gz config bundle. This will install:

• Porch server
• Config Sync

mkdir porch-install
tar xzf ~/Downloads/deployment-blueprint.tar.gz -C porch-install
kubectl apply -f porch-install
kubectl wait deployment --for=condition=Available porch-server -n porch-system

You can verify that Porch is running by querying the api-resources:

kubectl api-resources | grep porch

Expected output will include:

repositories                                   config.porch.kpt.dev/v1alpha1          true         Repository
functions                                      porch.kpt.dev/v1alpha1                 true         Function
packagerevisionresources                       porch.kpt.dev/v1alpha1                 true         PackageRevisionResources
packagerevisions                               porch.kpt.dev/v1alpha1                 true         PackageRevision

To install ConfigSync:

echo "
apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  enableMultiRepo: true
" | kubectl apply -f -

You can start using Porch.

Run Custom Build of Porch

To run custom build of Porch, you will need additional prerequisites. The commands below use Google Container Registry.

Clone this repository into ${GOPATH}/src/github.com/GoogleContainerTools/kpt.

git clone https://github.com/GoogleContainerTools/kpt.git "${GOPATH}/src/github.com/GoogleContainerTools/kpt"

Configure docker credential helper for your repository

If your use case doesn't require Porch to interact with GCP container registries, you can build and deploy Porch by running the following command. It will build and push Porch Docker images into (by default) Google Container Registry named (example shown is the Porch server image):

gcr.io/YOUR-PROJECT-ID/porch-server:SHORT-COMMIT-SHA

IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa

If you want to use different repository, you can set IMAGE_REPO variable (see Makefile for details).

The make push-and-deploy-no-sa target will install Porch but not Config Sync. You can install Config Sync in your k8s cluster manually following the documentation.

Note: The -no-sa (no service account) targets create Porch deployment configuration which does not associate Kubernetes service accounts with GCP service accounts. This is sufficient for Porch to integate with Git repositories using Basic Auth, for example GitHub.

As above, you can verify that Porch is running by querying the api-resources:

kubectl api-resources | grep porch

And start using Porch if the Porch resources are available.

Workload Identity

Workload Identity is a simple way to access Google Cloud services from porch.

Google Cloud Source Repositories

Cloud Source Repositories can be access using workload identity, removing the need to store credentials in the cluster.

To set it up, create the necessary service accounts and give it the required roles:

GCP_PROJECT_ID=$(gcloud config get-value project)

# Create GCP service account (GSA) for Porch server.
gcloud iam service-accounts create porch-server

# We want to create and delete images. Assign IAM roles to allow repository
# administration.
gcloud projects add-iam-policy-binding ${GCP_PROJECT_ID} \
  --member "serviceAccount:porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/source.admin"

gcloud iam service-accounts add-iam-policy-binding porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-server]"

# We need to associate the Kubernetes Service Account (KSA)
# with the GSA by annotating the KSA.
kubectl annotate serviceaccount porch-server -n porch-system \
  iam.gke.io/gcp-service-account=porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com

Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity service account annotations:

IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy

As above, you can verify that Porch is running by querying the api-resources:

kubectl api-resources | grep porch

To register a repository, use the following command:

kpt alpha repo register --repo-workload-identity --namespace=default https://source.developers.google.com/p/<project>/r/<repo>

OCI

To integrate with OCI repositories such as Artifact Registry or Container Registry, Porch relies on workload identity.

For that use case, create service accounts and assign roles:

GCP_PROJECT_ID=$(gcloud config get-value project)

# Create GCP service account for Porch server.
gcloud iam service-accounts create porch-server
# Create GCP service account for Porch sync controller.
gcloud iam service-accounts create porch-sync

# We want to create and delete images. Assign IAM roles to allow repository
# administration.
gcloud projects add-iam-policy-binding ${GCP_PROJECT_ID} \
  --member "serviceAccount:porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.repoAdmin"

gcloud iam service-accounts add-iam-policy-binding porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-server]"

gcloud projects add-iam-policy-binding ${GCP_PROJECT_ID} \
  --member "serviceAccount:porch-sync@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]"

Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity service account annotations:

IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy

As above, you can verify that Porch is running by querying the api-resources:

kubectl api-resources | grep porch

And start using Porch if the Porch resources are available.