Skip to content

Commit 49d817e

Browse files
martinmalymartinmaly
authored
Update Porch Documentation (#3027)
* Add more details on how to run on GKE both using releases, and via building Porch images. * Add `make` targets that create configuration that doesn't require workload identity.
1 parent c9c17c3 commit 49d817e

File tree

3 files changed

+195
-17
lines changed

3 files changed

+195
-17
lines changed

‎porch/Makefile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ KUBECONFIG=$(CURDIR)/hack/local/kubeconfig
1616
BUILDDIR=$(CURDIR)/.build
1717
CACHEDIR=$(CURDIR)/.cache
1818
DEPLOYCONFIGDIR=$(BUILDDIR)/deploy
19+
DEPLOYCONFIG_NO_SA_DIR=$(BUILDDIR)/deploy-no-sa
1920

2021
# Modules are ordered in dependency order. A module precedes modules that depend on it.
2122
MODULES = \
@@ -195,3 +196,27 @@ deploy: deployment-config
195196

196197
.PHONY: push-and-deploy
197198
push-and-deploy: push-images deploy
199+
200+
# Builds deployment config without configuring GCP workload identity for
201+
# Porch server. This is sufficient for working with GitHub repositories.
202+
# Workload identity is currently required for Porch to integrate with GCP
203+
# Container and Artifact Registries; for those use cases, use the make
204+
# targets without the `-no-sa` suffix (i.e. `deployment-config`,
205+
# `push-and-deploy` etc.)
206+
.PHONY: deployment-config-no-sa
207+
deployment-config-no-sa:
208+
rm -rf $(DEPLOYCONFIG_NO_SA_DIR) || true
209+
mkdir -p $(DEPLOYCONFIG_NO_SA_DIR)
210+
./hack/create-deployment-blueprint.sh \
211+
--destination "$(DEPLOYCONFIG_NO_SA_DIR)" \
212+
--server-image "$(IMAGE_REPO)/$(PORCH_SERVER_IMAGE):$(IMAGE_TAG)" \
213+
--controllers-image "$(IMAGE_REPO)/$(PORCH_CONTROLLERS_IMAGE):$(IMAGE_TAG)" \
214+
--function-image "$(IMAGE_REPO)/$(PORCH_FUNCTION_RUNNER_IMAGE):$(IMAGE_TAG)" \
215+
--wrapper-server-image "$(IMAGE_REPO)/$(PORCH_WRAPPER_SERVER_IMAGE):$(IMAGE_TAG)"
216+
217+
.PHONY: deploy-no-sa
218+
deploy-no-sa: deployment-config-no-sa
219+
kubectl apply -R -f $(DEPLOYCONFIG_NO_SA_DIR)
220+
221+
.PHONY: push-and-deploy-no-sa
222+
push-and-deploy: push-images deploy-no-sa

‎porch/docs/running-locally.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ To run Porch locally, you will need:
77
* Linux machine (technically it is possible to run Porch locally on a Mac but
88
due to differences in Docker between Linux and Mac, the Porch scripts are
99
confirmed to work on Linux)
10-
* [go 1.17](https://go.dev/dl/)
10+
* [go 1.17](https://go.dev/dl/) or newer
1111
* [docker](https://docs.docker.com/get-docker/)
1212
* [git](https://git-scm.com/)
1313
* `make`

‎porch/docs/running-on-gke.md‎

Lines changed: 169 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,199 @@
11
# Running on GKE
22

3-
Create a GKE cluster:
3+
## Prerequisites
44

5-
**Note**: We need the release-channel=rapid as we depend on k8s 1.22 (because of priority and fairness APIs moving to beta2)
5+
To run one of the [released versions](https://github.com/GoogleContainerTools/kpt/releases)
6+
of Porch on GKE, you will need:
7+
8+
* A [GCP Project](https://console.cloud.google.com/projectcreate)
9+
* [gcloud](https://cloud.google.com/sdk/docs/install)
10+
* [kubectl](https://kubernetes.io/docs/tasks/tools/); you can install it via
11+
`gcloud components install kubectl`
12+
* [kpt](https://kpt.dev/)
13+
* Command line utilities such as `curl`, `tar`
14+
15+
To build and run Porch on GKE, you will also need:
16+
17+
* A container registry which will work with your GKE cluster.
18+
[Artifact Registry](https://console.cloud.google.com/artifacts)
19+
or [Container Registry](https://console.cloud.google.com/gcr) work well
20+
though you can use others too.
21+
* [go 1.17](https://go.dev/dl/) or newer
22+
* [docker](https://docs.docker.com/get-docker/)
23+
* [Configured docker credential helper](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker)
24+
* [git](https://git-scm.com/)
25+
* [make](https://www.gnu.org/software/make/)
26+
27+
## Getting Started
28+
29+
Make sure your `gcloud` is configured with your project (alternatively, you can
30+
augment all following `gcloud` commands below with `--project` flag):
31+
32+
```sh
33+
gcloud config set project YOUR_GCP_PROJECT
34+
```
35+
36+
Select a GKE cluster or create a new one:
637

738
```sh
8-
gcloud container clusters create-auto --region us-central1 --release-channel=rapid porch-dev
39+
gcloud container clusters create-auto --region us-central1 porch-dev
40+
```
41+
42+
**Note:** For development of Porch, in particular for running Porch tests,
43+
Standard GKE cluster is currently preferable. Select a
44+
[GCP region](https://cloud.google.com/compute/docs/regions-zones#available)
45+
that works best for your needs:
46+
47+
```sh
48+
gcloud container clusters create --region us-central1 porch-dev
949
```
1050

11-
Ensure you are targeting the GKE cluster:
51+
And ensure `kubectl` is targeting your GKE cluster:
52+
53+
Ensure you are targeting the GKE cluster. Make sure to substitute your
54+
specific region and cluster name:
55+
1256
```sh
1357
gcloud container clusters get-credentials --region us-central1 porch-dev
1458
```
1559

16-
Create service accounts and assign roles:
60+
## Run Released Version of Porch
61+
62+
To run a released version of Porch, download the release config bundle from
63+
[Porch release page](https://github.com/GoogleContainerTools/kpt/releases).
64+
65+
Untar and applly the config bundle. This will install:
66+
67+
* Porch server
68+
* [Config Sync](https://cloud.google.com/anthos-config-management/docs/config-sync-overview)
69+
70+
```sh
71+
mkdir porch-install
72+
tar xzf path-to-deployment-blueprint.tar.gz -C porch-install
73+
kubectl apply -f porch-install
74+
```
75+
76+
You can verify that Porch is running by querying the `api-resources`:
77+
78+
```sh
79+
kubectl api-resources | grep porch
80+
```
81+
Expected output will include:
82+
83+
```
84+
repositories config.porch.kpt.dev/v1alpha1 true Repository
85+
functions porch.kpt.dev/v1alpha1 true Function
86+
packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources
87+
packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision
88+
```
89+
90+
You can start [using Porch](../README.md#using-porch).
91+
92+
## Run Custom Build of Porch
93+
94+
To run custom build of Porch, you will need additional [prerequisites](#prerequisites).
95+
The commands below use [Google Container Registry](https://console.cloud.google.com/gcr).
96+
97+
Clone this repository into `${GOPATH}/src/github.com/GoogleContainerTools/kpt`.
98+
99+
```sh
100+
git clone https://github.com/GoogleContainerTools/kpt.git "${GOPATH}/src/github.com/GoogleContainerTools/kpt"
101+
```
102+
103+
[Configure](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker)
104+
docker credential helper for your repository
105+
106+
If your use case doesn't require Porch to interact with GCP container registries,
107+
you can build and deploy Porch by running the following command. It will build and
108+
push Porch Docker images into (by default) Google Container Registry named (example
109+
shown is the Porch server image):
110+
111+
`gcr.io/YOUR-PROJECT-ID/porch-server:SHORT-COMMIT-SHA`
112+
113+
114+
```sh
115+
IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa
116+
```
117+
118+
If you want to use different repository, you can set `IMAGE_REPO` variable
119+
(see [Makefile](https://github.com/GoogleContainerTools/kpt/blob/main/porch/Makefile#L28)
120+
for details).
121+
122+
The `make push-and-deploy-no-sa` target will install Porch but not Config Sync.
123+
You can install Config Sync in your k8s cluster manually following the
124+
[documentation](https://cloud.google.com/anthos-config-management/docs/how-to/installing-kubectl).
125+
126+
**Note**: The `-no-sa` (no service account) targets create Porch deployment
127+
configuration which does not associate Kubernetes service accounts with GCP
128+
service accounts. This is sufficient for Porch to integate with Git repositories
129+
using Basic Auth, for example GitHub.
130+
131+
As above, you can verify that Porch is running by querying the `api-resources`:
132+
133+
```sh
134+
kubectl api-resources | grep porch
135+
```
136+
137+
And start [using Porch](../README.md#using-porch) if the Porch resources are
138+
available.
139+
140+
### Workload Identity
141+
142+
To integrate with OCI repositories such as
143+
[Artifact Registry](https://console.cloud.google.com/artifacts) or
144+
[Container Registry](https://console.cloud.google.com/gcr), Porch relies on
145+
[workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).
146+
147+
For that use case, create service accounts and assign roles:
17148

18149
```sh
19150
GCP_PROJECT_ID=$(gcloud config get-value project)
151+
152+
# Create GCP service account for Porch server.
20153
gcloud iam service-accounts create porch-server
154+
# Create GCP service account for Porch sync controller.
21155
gcloud iam service-accounts create porch-sync
22156

23-
# We want to create and delete images
157+
# We want to create and delete images. Assign IAM roles to allow repository
158+
# administration.
24159
gcloud projects add-iam-policy-binding ${GCP_PROJECT_ID} \
25-
--member "serviceAccount:porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
26-
--role "roles/artifactregistry.repoAdmin"
160+
--member "serviceAccount:porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
161+
--role "roles/artifactregistry.repoAdmin"
162+
27163
gcloud iam service-accounts add-iam-policy-binding porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
28-
--role roles/iam.workloadIdentityUser \
29-
--member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-server]"
164+
--role roles/iam.workloadIdentityUser \
165+
--member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-server]"
30166

31167
gcloud projects add-iam-policy-binding ${GCP_PROJECT_ID} \
32-
--member "serviceAccount:porch-sync@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
33-
--role "roles/artifactregistry.reader"
168+
--member "serviceAccount:porch-sync@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
169+
--role "roles/artifactregistry.reader"
170+
34171
gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
35-
--role roles/iam.workloadIdentityUser \
36-
--member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]"
172+
--role roles/iam.workloadIdentityUser \
173+
--member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]"
37174
```
38175

39-
Build Porch, push images, and deploy porch server and controllers:
176+
Build Porch, push images, and deploy porch server and controllers using the
177+
`make` target that adds workload identity service account annotations:
40178

41179
```sh
42180
IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy
43181
```
44182

183+
As above, you can verify that Porch is running by querying the `api-resources`:
184+
185+
```sh
186+
kubectl api-resources | grep porch
187+
```
188+
189+
And start [using Porch](../README.md#using-porch) if the Porch resources are
190+
available.
191+
192+
## Deploying Configuration
193+
194+
**Note:** Rather than using Config Sync, this section uses a prototype sync
195+
controller.
196+
45197
Create some example repositories / packages:
46198

47199
```sh
@@ -60,5 +212,6 @@ To test out remoterootsync self-applying:
60212
kubectl apply -f controllers/remoterootsync/config/samples/hack-self-apply-rbac.yaml
61213

62214
# Apply the RemoteRootSyncSet
63-
cat controllers/remoterootsync/config/samples/hack-self-apply.yaml | sed -e s/example-google-project-id/${GCP_PROJECT_ID}/g | kubectl apply -f -
215+
cat controllers/remoterootsync/config/samples/hack-self-apply.yaml \
216+
| sed -e s/example-google-project-id/${GCP_PROJECT_ID}/g | kubectl apply -f -
64217
```

0 commit comments

Comments
 (0)