docs: Add kargo add-on promoter topic

This patch adds an Add-On Promoter topic to demonstrate how Holos pairs
nicely with Kargo for progressive rollouts.

Code examples are automatically tested and used in the doc using go test
and testscripts.

Update the examples using:

    HOLOS_UPDATE_SCRIPTS=1 go test ./doc/md/topics/kargo

Makefile

@@ -154,6 +154,10 @@ website: ## Build website
 unity: ## https://cuelabs.dev/unity/
 	./scripts/unity
 
+.PHONY: update-doc-examples
+update-docs: ## Update doc examples
+	HOLOS_UPDATE_SCRIPTS=1 go test -v ./doc/md/topics/kargo
+
 .PHONY: help
 help:  ## Display this help menu.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

doc/md/topics/kargo/.gitignore

@@ -0,0 +1,2 @@
+kargo-demo/
+.tmp/

doc/md/topics/kargo/_add-on-promoter/examples/01-clone.txtar

@@ -0,0 +1,17 @@
+env GH_USER=holos-run
+# Remove the directory if it already exists
+exec rm -rf kargo-demo
+# Clone your fork of the kargo-demo repository
+exec bash -c 'bash -euo pipefail command.sh 2>&1'
+cmp stdout output.txt
+
+# Get the git commit
+cd kargo-demo
+exec git rev-parse --verify origin/HEAD
+cp stdout $WORK/git.commit
+
+-- command.sh --
+git clone https://github.com/${GH_USER}/kargo-demo.git
+cd kargo-demo
+-- output.txt --
+Cloning into 'kargo-demo'...

doc/md/topics/kargo/_add-on-promoter/examples/10-cert-manager.txtar

@@ -0,0 +1,37 @@
+env GH_USER=jeffmccune
+cd ../script-01-clone/kargo-demo
+
+## Walk the reader from entrypoint to the deployment pipeline
+# holos render platform entrypoint
+exec bash -c 'cat $(<$WORK/entrypoint.path)'
+cp stdout $WORK/entrypoint.txt
+exec bash -c 'basename $(<$WORK/entrypoint.path)'
+cp stdout $WORK/entrypoint.basename
+
+# platform.stacks location
+exec bash -c 'cat $(<$WORK/stacks.path)'
+cp stdout $WORK/stacks.txt
+exec bash -c 'basename $(<$WORK/stacks.path)'
+cp stdout $WORK/stacks.basename
+
+# certmanager.config location
+exec bash -c 'cat $(<$WORK/config.path)'
+cp stdout $WORK/config.txt
+exec bash -c 'basename $(<$WORK/config.path)'
+cp stdout $WORK/config.basename
+
+# Cert Manager Component.
+exec bash -c 'cat $(<$WORK/component.path)'
+cp stdout $WORK/component.txt
+# Get the path basename for the docs.
+exec bash -c 'basename $(<$WORK/component.path)'
+cp stdout $WORK/component.basename
+
+-- config.path --
+config/certmanager/certmanager.cue
+-- stacks.path --
+config/platform/security.cue
+-- entrypoint.path --
+platform/stacks.cue
+-- component.path --
+stacks/security/components/cert-manager/cert-manager.cue

doc/md/topics/kargo/_add-on-promoter/examples/20-holos-version.txtar

@@ -0,0 +1,8 @@
+cd ../script-01-clone/kargo-demo
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.102.3

doc/md/topics/kargo/_add-on-promoter/examples/30-git-url.txtar

@@ -0,0 +1,56 @@
+env GH_USER=jeffmccune
+env HOME=$WORK/.tmp
+cd ../script-01-clone/kargo-demo
+chmod 0755 $WORK/update.sh
+
+# Combine the steps separated in the doc.
+exec cat $WORK/header.sh $WORK/body.txt $WORK/trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+cmp config/platform/organization_$GH_USER.cue $WORK/code.want.cue
+
+# Render the platform
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/output.txt
+
+# Get the diff
+exec bash -c 'bash -euo pipefail $WORK/diff.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/diff.patch
+
+# Set the author
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email '[email protected]'
+
+# Make the commit
+exec bash -c 'bash -euo pipefail $WORK/commit.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/commit.txt
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- header.sh --
+cat <<EOF > config/platform/organization_${GH_USER}.cue
+-- body.txt --
+@if(${GH_USER})
+package platform
+
+organization: repoURL: "https://github.com/${GH_USER}/kargo-demo.git"
+-- trailer.sh --
+EOF
+-- code.want.cue --
+@if(jeffmccune)
+package platform
+
+organization: repoURL: "https://github.com/jeffmccune/kargo-demo.git"
+-- command.sh --
+holos render platform -t ${GH_USER}
+-- commit.sh --
+git add .
+git commit -m "Switch to $GH_USER fork"
+-- diff.sh --
+git diff

doc/md/topics/kargo/_add-on-promoter/script-01-clone/command.sh

@@ -0,0 +1,2 @@
+git clone https://github.com/${GH_USER}/kargo-demo.git
+cd kargo-demo

doc/md/topics/kargo/_add-on-promoter/script-01-clone/git.commit

@@ -0,0 +1 @@
+238fe0403c99eeea4f4fb764a88b780554048414

doc/md/topics/kargo/_add-on-promoter/script-01-clone/output.txt

@@ -0,0 +1 @@
+Cloning into 'kargo-demo'...

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/component.basename

@@ -0,0 +1 @@
+cert-manager.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/component.path

@@ -0,0 +1 @@
+stacks/security/components/cert-manager/cert-manager.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/component.txt

@@ -0,0 +1,21 @@
+package holos
+
+import "holos.example/config/certmanager"
+
+// Produce a helm chart build plan.
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Name:      "cert-manager"
+	Namespace: certmanager.config.namespace
+	Chart:     certmanager.config.chart
+
+	EnableHooks: true
+
+	Values: #Values & {
+		crds: enabled:            true
+		startupapicheck: enabled: false
+		// https://github.com/cert-manager/cert-manager/issues/6716
+		global: leaderElection: namespace: Namespace
+	}
+}

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/config.basename

@@ -0,0 +1 @@
+certmanager.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/config.path

@@ -0,0 +1 @@
+config/certmanager/certmanager.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/config.txt

@@ -0,0 +1,30 @@
+@extern(embed)
+package certmanager
+
+import "github.com/holos-run/holos/api/core/v1alpha5:core"
+
+// Unify data from yaml for Kargo integration.
+_data: _ @embed(file=cert-manager.yaml)
+
+config: #Config & {
+	namespace: "cert-manager"
+	// datafile value must align to the embed file directive above for proper
+	// configuration of Kargo promotion stages.
+	datafile: "./config/certmanager/cert-manager.yaml"
+	chart: {
+		name:    "cert-manager"
+		version: _data.chart.version
+		repository: {
+			name: "jetstack"
+			url:  "https://charts.jetstack.io"
+		}
+	}
+}
+
+#Config: {
+	namespace: string
+	datafile:  string
+	chart: core.#Chart & {
+		version: =~"^v{0,1}[0-9]+\\.[0-9]+\\.[0-9]+$"
+	}
+}

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/entrypoint.basename

@@ -0,0 +1 @@
+stacks.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/entrypoint.path

@@ -0,0 +1 @@
+platform/stacks.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/entrypoint.txt

@@ -0,0 +1,8 @@
+package main
+
+import "holos.example/config/platform"
+
+// Register all stack components with the platform spec.
+for STACK in platform.stacks {
+	Platform: Components: STACK.components
+}

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/stacks.basename

@@ -0,0 +1 @@
+security.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/stacks.path

@@ -0,0 +1 @@
+config/platform/security.cue

doc/md/topics/kargo/_add-on-promoter/script-10-cert-manager/stacks.txt

@@ -0,0 +1,46 @@
+package platform
+
+import "holos.example/config/certmanager"
+
+stacks: security: (#StackBuilder & {
+	(#PromoterBuilder & {parameters: {
+		name: "cert-manager"
+		config: {
+			datafile: certmanager.config.datafile
+			chart:    certmanager.config.chart
+		}
+	}}).promoter
+
+	// Manage the external-secrets namespace.
+	stack: namespaces: "external-secrets": _
+
+	parameters: {
+		name: "security"
+		components: {
+			namespaces: {
+				path: "stacks/security/components/namespaces"
+				annotations: description: "configures namespaces for all stacks"
+			}
+			"external-secrets-crds": {
+				path: "stacks/security/components/external-secrets-crds"
+				annotations: description: "external secrets custom resource definitions"
+			}
+			"external-secrets": {
+				path: "stacks/security/components/external-secrets"
+				annotations: description: "external secrets custom resource definitions"
+			}
+			"cert-manager": {
+				path: "stacks/security/components/cert-manager"
+				annotations: description: "cert-manager operator and custom resource definitions"
+				parameters: {
+					kargoProject: "cert-manager"
+					kargoStage:   "main"
+				}
+			}
+			"local-ca": {
+				path: "stacks/security/components/local-ca"
+				annotations: description: "localhost mkcert certificate authority"
+			}
+		}
+	}
+}).stack

doc/md/topics/kargo/_add-on-promoter/script-20-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/topics/kargo/_add-on-promoter/script-20-holos-version/output.txt

@@ -0,0 +1 @@
+0.102.3

doc/md/topics/kargo/_add-on-promoter/script-30-git-url/body.txt

@@ -0,0 +1,4 @@
+@if(${GH_USER})
+package platform
+
+organization: repoURL: "https://github.com/${GH_USER}/kargo-demo.git"

doc/md/topics/kargo/_add-on-promoter/script-30-git-url/code.want.cue

@@ -0,0 +1,4 @@
+@if(jeffmccune)
+package platform
+
+organization: repoURL: "https://github.com/jeffmccune/kargo-demo.git"

doc/md/topics/kargo/_add-on-promoter/script-30-git-url/command.sh

@@ -0,0 +1 @@
+holos render platform -t ${GH_USER}

doc/md/topics/kargo/_add-on-promoter/script-30-git-url/commit.sh

@@ -0,0 +1,2 @@
+git add .
+git commit -m "Switch to $GH_USER fork"

doc/md/topics/kargo/_add-on-promoter/script-30-git-url/commit.txt

@@ -0,0 +1,3 @@
+[main b883807] Switch to jeffmccune fork
+ 43 files changed, 70 insertions(+), 66 deletions(-)
+ create mode 100644 config/platform/organization_jeffmccune.cue