wip - working on end to end walkthrough of holos render platform

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

@@ -0,0 +1,37 @@
+env GH_USER=jeffmccune
+cd ../script-setup/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/script-cert-manager/component.basename

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

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

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

doc/md/topics/kargo/_add-on-promoter/script-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-cert-manager/config.basename

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

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

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

doc/md/topics/kargo/_add-on-promoter/script-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-cert-manager/entrypoint.basename

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

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

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

doc/md/topics/kargo/_add-on-promoter/script-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-cert-manager/stacks.basename

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

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

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

doc/md/topics/kargo/_add-on-promoter/script-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-git-url/commit.txt

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

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

@@ -1,47 +1,47 @@
-rendered argocd-secrets for stack argocd in 414.44ms
-rendered kargo-project for project podinfo in 414.560458ms
-rendered rollouts for stack argocd in 416.403042ms
-rendered app-projects for stack argocd in 416.750417ms
-rendered kargo-secrets for stack argocd in 417.130416ms
-rendered kargo-promoter for stack argocd in 421.088792ms
-rendered kargo-stages for project podinfo in 421.607166ms
-rendered kargo-project for project httpbin in 422.029458ms
-rendered kargo-stages for project httpbin in 422.166791ms
-rendered gateway-api for stack network in 524.156667ms
-rendered istio-gateway for stack network in 238.222458ms
-rendered namespaces for stack security in 373.691792ms
-rendered rollouts-crds for stack argocd in 805.860291ms
-rendered local-ca for stack security in 170.724875ms
-rendered argocd-crds for stack argocd in 878.929208ms
-rendered external-secrets-crds for stack security in 504.312375ms
-rendered cert-manager-promoter for stack security in 186.718ms
-rendered dev-httpbin for project httpbin in 204.02775ms
-rendered test-httpbin for project httpbin in 208.622375ms
-rendered uat-httpbin for project httpbin in 253.336ms
-rendered prod-us-east-httpbin for project httpbin in 291.838375ms
-rendered prod-us-central-httpbin for project httpbin in 263.255833ms
-rendered prod-us-west-httpbin for project httpbin in 256.850292ms
-rendered istio-ztunnel for stack network in 944.060291ms
-rendered istio-cni for stack network in 946.895458ms
-rendered istiod for stack network in 1.000126292s
-rendered argocd for stack argocd in 1.587457083s
-rendered istio-base for stack network in 1.185511667s
-rendered cert-manager for stack security in 1.110636958s
-rendered httproutes for stack network in 1.261078125s
-rendered external-secrets for stack security in 1.464216625s
-Pulled: ghcr.io/stefanprodan/charts/podinfo:6.7.0
-Digest: sha256:104d101017e501c63b3aa71b20d5edd2ca6d5d58cbc57ff8163770110f92b9db
-rendered dev-podinfo for project podinfo in 1.135666375s
-rendered test-podinfo for project podinfo in 1.047599459s
-rendered uat-podinfo for project podinfo in 1.027484583s
-rendered prod-us-west-podinfo for project podinfo in 885.832083ms
+rendered argocd-secrets for stack argocd in 459.464791ms
+rendered kargo-project for project httpbin in 459.666792ms
+rendered kargo-secrets for stack argocd in 459.830541ms
+rendered app-projects for stack argocd in 460.253125ms
+rendered kargo-promoter for stack argocd in 461.218625ms
+rendered kargo-project for project podinfo in 464.508584ms
+rendered kargo-stages for project podinfo in 466.752875ms
+rendered rollouts for stack argocd in 466.887167ms
+rendered kargo-stages for project httpbin in 466.897ms
+rendered gateway-api for stack network in 642.040792ms
+rendered istio-gateway for stack network in 272.863375ms
+rendered rollouts-crds for stack argocd in 848.714208ms
+rendered local-ca for stack security in 212.097542ms
+rendered namespaces for stack security in 479.213084ms
+rendered argocd-crds for stack argocd in 986.06875ms
+rendered external-secrets-crds for stack security in 605.710667ms
+rendered cert-manager-promoter for stack security in 249.667625ms
+rendered test-httpbin for project httpbin in 238.4345ms
+rendered dev-httpbin for project httpbin in 239.346167ms
+rendered uat-httpbin for project httpbin in 246.3435ms
+rendered prod-us-east-httpbin for project httpbin in 274.906334ms
+rendered prod-us-central-httpbin for project httpbin in 289.92525ms
+rendered istio-cni for stack network in 956.059292ms
+rendered istio-ztunnel for stack network in 978.099083ms
+rendered istiod for stack network in 1.020891084s
 Pulled: ghcr.io/akuity/kargo-charts/kargo:1.1.1
 Digest: sha256:4055c72418db85b85979da2fe12136c0e275709efc2e36a505b158e8234ad443
-rendered kargo for stack argocd in 2.377781709s
-Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.1
-Digest: sha256:0cc9a8446c95009ef382f5eade883a67c257f77d50f84e78ecef2aac9428d1e5
-rendered prod-us-east-podinfo for project podinfo in 1.154370584s
+rendered kargo for stack argocd in 1.565166s
+rendered prod-us-west-httpbin for project httpbin in 380.777417ms
+rendered argocd for stack argocd in 1.628081709s
+rendered istio-base for stack network in 1.189544875s
+rendered cert-manager for stack security in 1.034896375s
+rendered httproutes for stack network in 1.40211875s
+rendered external-secrets for stack security in 1.601172458s
 Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.2
 Digest: sha256:83295d47de6d6ca634ed4b952a7572fc176bcc38854d0c11ca0fa197bc5f1154
-rendered prod-us-central-podinfo for project podinfo in 1.14709075s
-rendered platform in 2.414075334s
+rendered prod-us-central-podinfo for project podinfo in 986.887ms
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.1
+Digest: sha256:0cc9a8446c95009ef382f5eade883a67c257f77d50f84e78ecef2aac9428d1e5
+rendered prod-us-east-podinfo for project podinfo in 1.046128833s
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.7.0
+Digest: sha256:104d101017e501c63b3aa71b20d5edd2ca6d5d58cbc57ff8163770110f92b9db
+rendered dev-podinfo for project podinfo in 1.3339405s
+rendered uat-podinfo for project podinfo in 1.17540125s
+rendered test-podinfo for project podinfo in 1.316333333s
+rendered prod-us-west-podinfo for project podinfo in 1.123668042s
+rendered platform in 2.562303542s

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

@@ -0,0 +1 @@
+6eff957207b85f48d3f1f7c5eb91e72e389c5e7c

doc/md/topics/kargo/_add-on-promoter/setup/setup.txt

@@ -4,6 +4,12 @@ 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

doc/md/topics/kargo/add-on-promoter.mdx

@@ -1,5 +1,5 @@
 ---
-description: Learn how to automatically open pull requests when cluster addon updates are available.
+description: Automatic gitops pull requests for cluster add-on updates.
 sidebar_position: 100
 ---
 import useBaseUrl from '@docusaurus/useBaseUrl';
@@ -58,6 +58,59 @@ import SetupOutput from '!!raw-loader!./_add-on-promoter/script-setup/output.txt
   </TabItem>
 </Tabs>
 
+## Configuration Tour
+
+Let's review what happens when the `holos render platform` command renders the
+Kargo deployment pipeline configuration for `cert-manager`.
+
+import GitHubLink from '@site/src/components/GitHubLink';
+import GitCommit from '!!raw-loader!./_add-on-promoter/script-setup/git.commit';
+
+import CertManagerEntrypointPath from '!!raw-loader!./_add-on-promoter/script-cert-manager/entrypoint.path';
+import CertManagerEntrypointBaseName from '!!raw-loader!./_add-on-promoter/script-cert-manager/entrypoint.basename';
+import CertManagerEntrypointCode from '!!raw-loader!./_add-on-promoter/script-cert-manager/entrypoint.txt';
+
+import CertManagerStacksPath from '!!raw-loader!./_add-on-promoter/script-cert-manager/stacks.path';
+import CertManagerStacksBaseName from '!!raw-loader!./_add-on-promoter/script-cert-manager/stacks.basename';
+import CertManagerStacksCode from '!!raw-loader!./_add-on-promoter/script-cert-manager/stacks.txt';
+
+import CertManagerComponentPath from '!!raw-loader!./_add-on-promoter/script-cert-manager/component.path';
+import CertManagerComponentBaseName from '!!raw-loader!./_add-on-promoter/script-cert-manager/component.basename';
+import CertManagerComponentCode from '!!raw-loader!./_add-on-promoter/script-cert-manager/component.txt';
+
+import CertManagerConfigPath from '!!raw-loader!./_add-on-promoter/script-cert-manager/config.path';
+import CertManagerConfigBaseName from '!!raw-loader!./_add-on-promoter/script-cert-manager/config.basename';
+import CertManagerConfigCode from '!!raw-loader!./_add-on-promoter/script-cert-manager/config.txt';
+
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerEntrypointPath}>{CertManagerEntrypointPath}</GitHubLink> is the main entrypoint for the `holos render platform` command.  Each platform stack's components are composed into the Platform spec `holos` uses to render each component.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={`${CertManagerStacksPath}#L32-L39`}>{CertManagerStacksBaseName}</GitHubLink> in the platform config package is where cert-manager is added to the platform as a holos component.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerComponentPath}>{CertManagerComponentBaseName}</GitHubLink> is the component definition.  The component imports the certmanager config package to get the chart version.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerConfigPath}>{CertManagerConfigBaseName}</GitHubLink> in the certmanager config package defines configuration imported by multiple components.  This file uses the CUE embed feature to load data from a yaml file in the same directory.  Kargo promotion steps update the cert manager version in this file.
+
+Cert Manager is managed as a Holos Component wrapping the official helm chart.
+See 
+
+<Tabs groupId="render-git-url">
+  <TabItem value="entrypoint" label={CertManagerEntrypointBaseName}>
+    <CodeBlock language="txt">{CertManagerEntrypointPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerEntrypointCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="stacks" label={CertManagerStacksBaseName}>
+    <CodeBlock language="txt">{CertManagerStacksPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerStacksCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="component" label={CertManagerComponentBaseName}>
+    <CodeBlock language="txt">{CertManagerComponentPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerComponentCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="config" label={CertManagerConfigBaseName}>
+    <CodeBlock language="txt">{CertManagerConfigPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerConfigCode}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+
+
 ## Holos Version
 
 Ensure you have a current version of `holos` installed.  This document was

doc/md/topics/kargo/docs_test.go

@@ -32,6 +32,7 @@ func TestKargo(t *testing.T) {
 		{"Setup", "setup"},
 		{"HolosVersion", "holos-version"},
 		{"GitURL", "git-url"},
+		{"CertManager", "cert-manager"},
 	}
 
 	for _, tt := range addOnPromoterTests {

doc/website/src/components/GitHubLink/index.tsx

@@ -0,0 +1,6 @@
+export default function GitHubLink({ repo, tree, path, children }: { repo: string, commit: string, path: string, children: React.ReactNode }) {
+  const href = `https://github.com/${repo}/tree/${tree}/${path}`
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer">{children}</a>
+  );
+};