From add1e45ec93799e249826a74e352d17d6a735378 Mon Sep 17 00:00:00 2001 From: Jeff McCune Date: Thu, 5 Dec 2024 09:57:16 -0800 Subject: [PATCH] kargo: document how to try it --- docs/kargo.md | 156 +++++++++++++++++++++++++++++++++++++ organization-jeff.cue | 6 -- organization-repo-jeff.cue | 4 + scripts/kargo-git-creds | 47 +++++++++++ 4 files changed, 207 insertions(+), 6 deletions(-) create mode 100644 docs/kargo.md delete mode 100644 organization-jeff.cue create mode 100644 organization-repo-jeff.cue create mode 100755 scripts/kargo-git-creds diff --git a/docs/kargo.md b/docs/kargo.md new file mode 100644 index 00000000..9398a78e --- /dev/null +++ b/docs/kargo.md @@ -0,0 +1,156 @@ +# Kargo Demo + +Kargo requires git credentials to promote artifacts. Follow these steps to +setup you [Local Cluster] with these credentials. + +## Process + +We'll create a GitHub App, install the app with write permission to our own fork +of the bank-of-holos repo, and store the private key in "$(mkcert +-CAROOT)/kargo.yaml" so it's automatically restored by the [reset-cluster] +script. + +### GitHub App + +#### GitHub App Authentication + +[Create a GitHub App](https://github.com/settings/apps/new) in the user or +organization where your bank-of-holos fork resides. + +In the `GitHub App name` field, specify a unique name, for example `Holos - Local Cluster 1733418802` produced by: + +```bash +echo -n "Holos - Local Cluster $(date +%s)" | pbcopy +``` + +Set the `Homepage URL` to `https://holos.run/docs/local-cluster/`. + +Under `Webhook`, de-select `Active`. + +Under `Permissions` → `Repository permissions` → `Contents`, select `Read and +write` permissions. _The App will receive these permissions on all repositories +into which it is installed._ + +Under `Where can this GitHub App be installed?`, leave `Only on this account` +selected. + +Click `Create GitHub App`. + +Take note of the `App ID`. In your shell store it for use later using: + +```bash +export BANK_OF_HOLOS_APP_ID=9999999 +``` + +Scroll to the bottom of the page and click `Generate a private key`. The +resulting key will be downloaded immediately. Record the path to this file for +use later using: + +```bash +export BANK_OF_HOLOS_APP_KEY="$(ls -lr1 ~/Downloads/holos-local-cluster*.private-key.pem | tail -1)" +``` + +On the left-hand side of the page, click `Install App`. + +Choose an account to install the App into by clicking `Install`. + +Select `Only select repositories` and choose your `bank-of-holos` fork. +Remember that the App will receive the permissions you selected earlier for all +repositories you grant access. + +Click `Install`. + +In your browser's address bar, take note of the numeric identifier at the end of +the current page's URL. This is the `Installation ID`. Save the installation id +for later. + +For example, `https://github.com/settings/installations/99999999` is saved as: + +```shell +export BANK_OF_HOLOS_INSTALL_ID=99999999 +``` + +#### GitHub App Secret + +Generate a Kubernetes Secret to store the Kargo git credentials. We put this in +`mkcert -CAROOT` so `reset-cluster` restores it each time the local cluster is +reset. + +Record the Git URL, the same as you set for `Organization.RepoURL` + +```shell +export BANK_OF_HOLOS_REPO_URL="https://github.com/${USER}/bank-of-holos.git" +``` + +At this point you should have the following values, for example: + +```shell +env | grep BANK_OF_HOLOS +``` + +```shell +BANK_OF_HOLOS_APP_ID=1079195 +BANK_OF_HOLOS_APP_KEY=/Users/jeff/Downloads/holos-local-cluster-1733419264.2024-12-05.private-key.pem +BANK_OF_HOLOS_INSTALL_ID=58021430 +BANK_OF_HOLOS_REPO_URL=https://github.com/jeffmccune/bank-of-holos.git +``` + +Generate the secret: + +```shell +./scripts/kargo-git-creds +``` + +```txt +Secret created, apply with: + kubectl apply -f '/Users/jeff/Library/Application Support/mkcert/kargo.yaml' + +The reset-cluster script will automatically apply this secret going forward. +``` + +And apply it or reset your cluster. + +```shell +kubectl apply -f '/Users/jeff/Library/Application Support/mkcert/kargo.yaml' +``` + +## Verification + +Make sure you've configured Holos to use your `bank-of-holos` fork. + +```shell +cat < organization-repo-${USER}.cue +``` +```cue showLineNumbers +@if($USER) +package holos + +Organization: RepoURL: "${BANK_OF_HOLOS_REPO_URL}" +``` +```shell +EOF +``` + +Then reset the cluster fully. (Note this will delete and re-create your local +k3d cluster) + +```bash +./scripts/full-reset +``` + +After a couple of minutes you should be able to log into https://kargo.holos.localhost with the admin password obtained with: + +```shell +kubectl get secret -n kargo admin-credentials -o json \ + | jq --exit-status -r '.data.password | @base64d' +``` + +Make sure to commit to `main` and push it to your fork, then try and promote the +bank frontend. + +ArgoCD is available at https://argocd.holos.localhost Most apps except those +which have previously been promoted in your fork should be in sync after a full +reset. + +[Local Cluster]: https://holos.run/docs/local-cluster/ +[reset-cluster]: ../scripts/reset-cluster diff --git a/organization-jeff.cue b/organization-jeff.cue deleted file mode 100644 index 60e0126b..00000000 --- a/organization-jeff.cue +++ /dev/null @@ -1,6 +0,0 @@ -@if(jeff) -package holos - -Organization: #Organization & { - RepoURL: "https://github.com/jeffmccune/bank-of-holos.git" -} diff --git a/organization-repo-jeff.cue b/organization-repo-jeff.cue new file mode 100644 index 00000000..d331341a --- /dev/null +++ b/organization-repo-jeff.cue @@ -0,0 +1,4 @@ +@if(jeff) +package holos + +Organization: RepoURL: "https://github.com/jeffmccune/bank-of-holos.git" diff --git a/scripts/kargo-git-creds b/scripts/kargo-git-creds new file mode 100755 index 00000000..17e4b923 --- /dev/null +++ b/scripts/kargo-git-creds @@ -0,0 +1,47 @@ +#! /bin/bash +# +# Store GitHub App Creds +# https://docs.kargo.io/how-to-guides/managing-credentials/#github-app-authentication + + +CAROOT="$(mkcert -CAROOT)" + +tmpdir="$(mktemp -d)" +finish() { + rm -rf "$tmpdir" +} +trap finish EXIT + +cd "$tmpdir" + +set -euo pipefail + +cat < kargo.yaml +apiVersion: v1 +kind: Namespace +metadata: + labels: + kubernetes.io/metadata.name: kargo + name: kargo +--- +kind: Secret +apiVersion: v1 +metadata: + labels: + kargo.akuity.io/cred-type: git + name: bank-of-holos-git-creds + namespace: kargo +type: Opaque +stringData: + githubAppID: "${BANK_OF_HOLOS_APP_ID}" + githubAppInstallationID: "${BANK_OF_HOLOS_INSTALL_ID}" + githubAppPrivateKey: "$(base64 < $BANK_OF_HOLOS_APP_KEY)" + repoURL: "${BANK_OF_HOLOS_REPO_URL}" +EOF + +cp kargo.yaml "${CAROOT}/kargo.yaml" + +echo "Secret created, apply with:" >&2 +echo " kubectl apply -f '${CAROOT}/kargo.yaml'" >&2 +echo >&2 +echo "The reset-cluster script will automatically apply this secret going forward." >&2