|
| 1 | +# Install the Kadras Engineering Platform |
| 2 | + |
| 3 | +## 1. Prerequisites |
| 4 | + |
| 5 | +* Kubernetes 1.24+ |
| 6 | +* Carvel [`kctrl`](https://carvel.dev/kapp-controller/docs/latest/install/#installing-kapp-controller-cli-kctrl) CLI. |
| 7 | +* Sigstore [`cosign`](https://docs.sigstore.dev/cosign/installation/) CLI. |
| 8 | +* Carvel [kapp-controller](https://carvel.dev/kapp-controller) deployed in your Kubernetes cluster. You can install it with Carvel [`kapp`](https://carvel.dev/kapp/docs/latest/install) (recommended choice) or `kubectl`. |
| 9 | + |
| 10 | + ```shell |
| 11 | + kapp deploy -a kapp-controller -y \ |
| 12 | + -f https://github.com/carvel-dev/kapp-controller/releases/latest/download/release.yml |
| 13 | + ``` |
| 14 | + |
| 15 | +## 2. Add the Kadras Repository |
| 16 | + |
| 17 | +Add the Kadras repository to make all Kadras packages available to the cluster. |
| 18 | + |
| 19 | + ```shell |
| 20 | + kubectl create namespace kadras-packages |
| 21 | + kctrl package repository add -r kadras-packages \ |
| 22 | + --url ghcr.io/kadras-io/kadras-packages \ |
| 23 | + -n kadras-packages |
| 24 | + ``` |
| 25 | + |
| 26 | +You can check the full list of available packages as follows. |
| 27 | + |
| 28 | + ```shell |
| 29 | + kctrl package available list -n kadras-packages |
| 30 | + ``` |
| 31 | + |
| 32 | +## 3. Create Secret for OCI Registry |
| 33 | + |
| 34 | +First, create a Secret with the credentials to access your container registry in read/write mode. It will be used by the platform to publish and consume OCI artifacts. |
| 35 | + |
| 36 | + ```shell |
| 37 | + export SUPPLY_CHAIN_REGISTRY_HOSTNAME=<hostname> |
| 38 | + export SUPPLY_CHAIN_REGISTRY_USERNAME=<username> |
| 39 | + export SUPPLY_CHAIN_REGISTRY_TOKEN=<token> |
| 40 | + ``` |
| 41 | + |
| 42 | +* `<hostname>` is the server hosting the OCI registry. For example, `ghcr.io`, `gcr.io`, `quay.io`, `index.docker.io`. |
| 43 | +* `<username>` is the username to access the OCI registry. Use `_json_key` if the hostname is `gcr.io`. |
| 44 | +* `<token>` is a token with read/write permissions to access the OCI registry. Use the contents of the service account key json if the hostname is `gcr.io`. |
| 45 | + |
| 46 | + ```shell |
| 47 | + kubectl create secret docker-registry supply-chain-registry-credentials \ |
| 48 | + --docker-server="${SUPPLY_CHAIN_REGISTRY_HOSTNAME}" \ |
| 49 | + --docker-username="${SUPPLY_CHAIN_REGISTRY_USERNAME}" \ |
| 50 | + --docker-password="${SUPPLY_CHAIN_REGISTRY_TOKEN}" \ |
| 51 | + --namespace=kadras-packages |
| 52 | + ``` |
| 53 | + |
| 54 | +## 4. Create Secret for Cosign |
| 55 | + |
| 56 | +Next, use Cosign to generate a key-pair that will be used by the platform to sign and verify OCI artifacts. |
| 57 | + |
| 58 | + ```shell |
| 59 | + cosign generate-key-pair k8s://kadras-packages/supply-chain-cosign-key-pair |
| 60 | + ``` |
| 61 | + |
| 62 | +The previous command will create a cosign.pub file in the current directory. That's the public key you can use the verify OCI artifacts built and signed by the platform. |
| 63 | + |
| 64 | +## 5. Configure the Platform |
| 65 | + |
| 66 | +The installation of the Kadras Engineering Platform can be configured via YAML. Create a `values.yml` file with any configuration you need for the platform. The following is a minimal configuration example. |
| 67 | + |
| 68 | +```yaml |
| 69 | +platform: |
| 70 | + ingress: |
| 71 | + domain: <domain> |
| 72 | + |
| 73 | + oci_registry: |
| 74 | + server: <oci-server> |
| 75 | + repository: <oci-repository> |
| 76 | + |
| 77 | +workspace_provisioner: |
| 78 | + namespaces: |
| 79 | + - name: default |
| 80 | + git: |
| 81 | + credentials: |
| 82 | + username: <github-username> |
| 83 | + password: <github-token> |
| 84 | +``` |
| 85 | +
|
| 86 | +* `<domain>` is the base domain name the platform will use to configure the Ingress controller. It must be a valid DNS name. For example, `lab.thomasvitale.com`. |
| 87 | +* `<oci-server>` is the server of the OCI registry where the platform will publish and consume OCI images. It must be the same used in step 3 when creating a Secret with the OCI registry credentials. For example, `ghcr.io`, `gcr.io`, `quay.io`, `index.docker.io`. |
| 88 | +* `<oci-repository>` is the repository in the OCI registry where the platform will publish and consume OCI images. It must be the same used in step 3 when creating a Secret with the OCI registry credentials. For example, it might be your username or organization name depending on which OCI server you're using. |
| 89 | +* `<github-username>` is your username to access your Git repositories on GitHub. It's not needed if you won't use the GitOps workflows offered by the platform and only use public Git repositories. |
| 90 | +* `<github-token>` is a token with read/write permissions to access your Git repositories on GitHub. It's not needed if you won't use the GitOps workflows offered by the platform and only use public Git repositories. |
| 91 | + |
| 92 | +## 6. Install the Platform |
| 93 | + |
| 94 | +Reference the `values.yml` file you created in the previous step and install the Kadras Engineering Platform. |
| 95 | + |
| 96 | + ```shell |
| 97 | + kctrl package install -i engineering-platform \ |
| 98 | + -p engineering-platform.packages.kadras.io \ |
| 99 | + -v ${VERSION} \ |
| 100 | + -n kadras-packages \ |
| 101 | + --values-file values.yml |
| 102 | + ``` |
| 103 | + |
| 104 | +You can find the `${VERSION}` value by retrieving the list of package versions available in the Kadras package repository installed on your cluster. |
| 105 | + |
| 106 | + ```shell |
| 107 | + kctrl package available list -p engineering-platform.packages.kadras.io -n kadras-packages |
| 108 | + ``` |
| 109 | + |
| 110 | +## 7. Verify the Installation |
| 111 | + |
| 112 | +Verify that all the platform components have been installed and properly reconciled. |
| 113 | + |
| 114 | + ```shell |
| 115 | + kctrl package installed list -n kadras-packages |
| 116 | + ``` |
0 commit comments