kargo: document how to try it

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 <<EOF > 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

organization-repo-jeff.cue

@@ -0,0 +1,4 @@
+@if(jeff)
+package holos
+
+Organization: RepoURL: "https://github.com/jeffmccune/bank-of-holos.git"

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 <<EOF > 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