docs: migrate from an ApplicationSet blog post

.gitignore

@@ -12,3 +12,4 @@ tmp/
 /holos-k3d/
 /holos-infra/
 node_modules/
+.tmp/

doc/website/.gitignore

@@ -18,3 +18,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Auto-generated doc examples
+multi-sources-example/
+kargo-demo/

doc/website/blog/_migrate_appset/examples/01-clone.txtar

@@ -0,0 +1,37 @@
+# This doc tested with holos version...
+exec bash -c 'bash -euo pipefail $WORK/version.sh 2>&1'
+cmp stdout version.txt
+
+# Remove the directory if it already exists
+exec rm -rf multi-sources-example
+# Clone the repository
+exec bash -c 'bash -euo pipefail $WORK/clone.sh 2>&1'
+cmp stdout clone.txt
+
+# Get the git commit
+cd multi-sources-example
+exec git rev-parse --verify origin/HEAD
+cp stdout $WORK/git.commit
+
+# Reset to TFA 4-final recommendation
+exec bash -c 'bash -euo pipefail $WORK/reset.sh 2>&1'
+cmp stdout $WORK/reset.txt
+
+# Set the committer
+exec git config user.email [email protected]
+exec git config user.name 'go test'
+
+-- version.sh --
+holos --version
+-- version.txt --
+0.103.0
+-- clone.sh --
+git clone https://github.com/holos-run/multi-sources-example.git
+cd multi-sources-example
+-- clone.txt --
+Cloning into 'multi-sources-example'...
+-- reset.sh --
+git branch -f work start
+git checkout work
+-- reset.txt --
+Switched to branch 'work'

doc/website/blog/_migrate_appset/examples/02-layers-of-complexity.txtar

@@ -0,0 +1,25 @@
+# Work in the root of the example repo
+cd ../script-01-clone/multi-sources-example
+
+# Reset to where 01-clone left us.
+exec git clean -fdx
+exec git reset --hard start
+
+# Consider the ApplicationSet from the final recommendation...
+exec bash -c 'cat $(<$WORK/appset.path)'
+cp stdout $WORK/appset.yaml
+
+# The Deployment
+exec bash -c 'cat $(<$WORK/deployment.path)'
+cp stdout $WORK/deployment.yaml
+
+# The Service
+exec bash -c 'cat $(<$WORK/service.path)'
+cp stdout $WORK/service.yaml
+
+-- appset.path --
+appsets/4-final/all-my-envs-appset-with-version.yaml
+-- service.path --
+my-chart/templates/service.yaml
+-- deployment.path --
+my-chart/templates/deployment.yaml

doc/website/blog/_migrate_appset/examples/03-holos-structure.txtar

@@ -0,0 +1,83 @@
+# Work in the root of the example repo
+cd ../script-01-clone/multi-sources-example
+
+# 7ce4feb initialize the platform
+exec bash -c 'bash -euo pipefail $WORK/holos-init.sh 2>&1'
+
+# f7102d6 reorganize to conventional holos layout 
+exec bash -c 'bash -euo pipefail $WORK/move-files-around.sh 2>&1'
+
+# 49183ca git mv appsets/4-final/env-config config/environments
+# Note, the v0.3.0 tag contains the environments.cue prior to being updated to
+# fix the duplicated config.json file.  Commit 1a73e77b fixes this issue as a
+# later migration step.
+exec cat $WORK/environments-header.sh $WORK/environments.cue $WORK/environments-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Inspect the structure
+exec bash -c 'bash -euo pipefail $WORK/inspect-environments.sh 2>&1'
+cp stdout $WORK/inspect-environments.txt
+
+-- holos-init.sh --
+holos init platform v1alpha5 --force
+-- move-files-around.sh --
+# First, we'll move my-chart the original article vendored in
+# Git to the conventional location Holos uses to vendor charts.
+mkdir -p components/my-chart/vendor/0.1.0
+git mv my-chart components/my-chart/vendor/0.1.0/my-chart
+
+# Helm value files move into the directory that will contain
+# my-chart component definition.  components/my-chart is
+# conventionally called the "my-chart component directory"
+git mv my-values components/my-chart/my-values
+
+# The config.json files are moved without changing their folder structure.
+# We'll package the data up into an "environments config package" for reuse.
+mkdir config
+git mv appsets/4-final/env-config config/environments
+
+# All of our components will reside in the components directory so
+# the CUE files `holos init` produced may be moved to keep the
+# repository root tidy.
+mv *.cue components/
+
+# The following files and directories from the original article and
+# holos init are no longer relevant after the migration.
+mkdir not-used
+git mv appsets not-used/appsets
+git mv example-apps not-used/example-apps
+rm -f platform.metadata.json
+
+# Make the commit
+git add platform components cue.mod .gitignore
+git commit -m 'reorganize to conventional holos layout'
+-- environments-header.sh --
+cat <<'EOF' > config/environments/environments.cue
+-- environments.cue --
+@extern(embed)
+package environments
+
+// We use cue embed functionality as an equivalent replacement for
+// ApplicationSet generators.
+config: _ @embed(glob=*/config.json)
+config: _ @embed(glob=staging/*/config.json)
+config: _ @embed(glob=prod/*/config.json)
+config: _ @embed(glob=integration/*/config.json)
+
+// With CUE we can constrain the data with a schema.
+config: [FILEPATH=string]: #Config
+
+// #Config defines the schema of each config.json file.
+#Config: {
+	env:     "qa" | "integration-gpu" | "integration-non-gpu" | "staging-us" | "staging-eu" | "prod-us" | "prod-eu"
+	region:  "us" | "eu"
+	type:    "prod" | "non-prod"
+	version: "qa" | "staging" | "prod"
+	chart:   =~"^[0-9]+\\.[0-9]+\\.[0-9]+$"
+}
+-- environments-trailer.sh --
+EOF
+-- inspect-environments.sh --
+CUE_EXPERIMENT=embed holos cue export --out=yaml \
+  ./config/environments

doc/website/blog/_migrate_appset/examples/04-helm-component.txtar

@@ -0,0 +1,205 @@
+# Work in the root of the example repo
+cd ../script-01-clone/multi-sources-example
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# 987df87 add platform components to replace ApplicationSets.spec.generators
+exec cat $WORK/platform-my-chart-header.sh $WORK/platform-my-chart.cue $WORK/platform-my-chart-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+exec diff platform/my-chart.cue $WORK/platform-my-chart.cue
+
+# Configure where manifests are written.
+exec cat $WORK/componentconfig-header.sh $WORK/componentconfig.cue $WORK/componentconfig-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+exec diff components/componentconfig.cue $WORK/componentconfig.cue
+
+# Show the platform
+exec bash -c 'bash -euo pipefail $WORK/holos-show-platform.sh 2>&1'
+cp stdout $WORK/holos-show-platform.txt
+
+# Component Definition
+exec cat $WORK/component-my-chart-header.sh $WORK/component-my-chart.cue $WORK/component-my-chart-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+exec diff components/my-chart/my-chart.cue $WORK/component-my-chart.cue
+
+# Show the BuildPlans
+exec bash -c 'bash -euo pipefail $WORK/show-buildplans.sh 2>&1'
+cp stdout $WORK/show-buildplans.txt
+
+# Inspect the values
+exec bash -c 'bash -euo pipefail $WORK/inspect-value-files.sh 2>&1'
+cp stdout $WORK/inspect-value-files.txt
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/render.txt
+
+exec bash -c 'bash -euo pipefail $WORK/tree-deploy.sh 2>&1'
+cp stdout $WORK/tree-deploy.txt
+
+# Make a commit
+exec git add .
+exec git commit -m '04-helm-component.txtar'
+
+-- tree-deploy.sh --
+tree deploy
+-- render.sh --
+holos render platform
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- show-buildplans.sh --
+holos show buildplans
+-- inspect-value-files.sh --
+ CUE_EXPERIMENT=embed holos cue export --out=yaml \
+   ./components/my-chart \
+   -e valueFiles 
+-- component-my-chart-header.sh --
+cat <<'EOF' > components/my-chart/my-chart.cue
+-- component-my-chart-trailer.sh --
+EOF
+-- component-my-chart.cue --
+@extern(embed)
+package holos
+
+import "holos.example/config/environments"
+
+parameters: {
+	environments.#Config & {
+		env:     _ @tag(env)
+		region:  _ @tag(region)
+		type:    _ @tag(type)
+		version: _ @tag(version)
+		chart:   _ @tag(chart)
+	}
+}
+
+// component represents the holos component definition, which produces a
+// BuildPlan for holos to execute, rendering the manifests.
+component: #Helm & {
+	Chart: {
+		// Migrated from https://github.com/holos-run/multi-sources-example/blob/v0.1.0/appsets/4-final/all-my-envs-appset-with-version.yaml#L25
+		version: parameters.chart
+		repository: {
+			name: "multi-sources-example"
+			// Migrated from https://github.com/holos-run/multi-sources-example/blob/v0.1.0/appsets/4-final/all-my-envs-appset-with-version.yaml#L23
+			url: "https://kostis-codefresh.github.io/multi-sources-example"
+		}
+	}
+
+	// Migrated from https://github.com/holos-run/multi-sources-example/blob/v0.1.0/appsets/4-final/all-my-envs-appset-with-version.yaml#L40
+	// We use kustomize to manage the namespace, similar to how the original
+	// article uses the ApplicationSet template to specify the namespace.
+	KustomizeConfig: Kustomization: namespace: parameters.env
+
+	// Migrate the Helm Hierarchy preserving the behavior of over writing values.
+	// Migrated from [valueFiles].  Later files win.
+	//
+	// [valueFiles]: https://github.com/holos-run/multi-sources-example/blob/v0.1.0/appsets/4-final/all-my-envs-appset-with-version.yaml#L27-L32
+	ValueFiles: [{
+		name:   "common-values.yaml"
+		values: valueFiles["my-values/common-values.yaml"]
+	}, {
+		name:   "version-values.yaml"
+		values: valueFiles["my-values/app-version/\(parameters.version)-values.yaml"]
+	}, {
+		name:   "type-values.yaml"
+		values: valueFiles["my-values/env-type/\(parameters.type)-values.yaml"]
+	}, {
+		name:   "region-values.yaml"
+		values: valueFiles["my-values/regions/\(parameters.region)-values.yaml"]
+	}, {
+		name:   "env-values.yaml"
+		values: valueFiles["my-values/envs/\(parameters.env)-values.yaml"]
+	}]
+}
+
+// holos represents the output for the holos command line to process.  The holos
+// command line processes a BuildPlan to render the helm chart component.
+//
+// Use the holos show buildplans command to see the BuildPlans that holos render
+// platform renders.
+holos: component.BuildPlan
+
+// Migrated from https://github.com/holos-run/multi-sources-example/blob/v0.1.0/appsets/4-final/all-my-envs-appset-with-version.yaml#L27-L32
+valueFiles: _ @embed(glob=my-values/*.yaml)
+valueFiles: _ @embed(glob=my-values/*/*-values.yaml)
+-- holos-show-platform.sh --
+holos show platform
+-- componentconfig-header.sh --
+cat <<'EOF' > components/componentconfig.cue
+-- componentconfig-trailer.sh --
+EOF
+-- componentconfig.cue --
+package holos
+
+#ComponentConfig: {
+	// Inject the output base directory from platform component parameters.
+	OutputBaseDir: string | *"" @tag(outputBaseDir, type=string)
+}
+-- platform-my-chart-header.sh --
+cat <<'EOF' > platform/my-chart.cue
+-- platform-my-chart-trailer.sh --
+EOF
+-- platform-my-chart.cue --
+package holos
+
+// Imports ./config/environments/*.cue as the environments cue package.  The
+// package exposes ./config/environments/**/config.json files via the
+// environments.config struct
+import "holos.example/config/environments"
+
+// Manage my-chart for each of the three environments.  Platform components are
+// rendered by the holos render platform command.
+//
+// Use the following command command to inspect the Platform spec holos render
+// platform processes.
+//
+//  holos show platform
+//
+// CONFIG represents each migrated environments/**/config.json file.
+for CONFIG in environments.config {
+	// Add one holos component for each config.json file to the
+	// Platform.spec.components list.
+	Platform: Components: "\(CONFIG.env)-my-chart": #MyChart & {
+		parameters: {
+			env:     CONFIG.env
+			region:  CONFIG.region
+			type:    CONFIG.type
+			version: CONFIG.version
+			chart:   CONFIG.chart
+		}
+	}
+}
+
+// #MyChart defines a re-usable way to manage my-chart across qa, staging, and
+// production.
+#MyChart: {
+	name: "my-chart"
+	path: "components/my-chart"
+	// CUE supports constraints, here we constrain environment to one of three
+	// possible values.
+	parameters: {
+		// Embed the config.json schema (env, region, type, version, chart fields)
+		environments.#Config
+
+		// Define the env field here as any value (_) so we can refer to it.
+		// Otherwise cue complains #MyChart.parameters.outputBaseDir: reference
+		// "env" not found
+		env: _
+		// Write output manifests organized by environment env in this case refers
+		// to the env field defined by environments.#Config
+		outputBaseDir: "environments/\(env)"
+	}
+	// CUE supports string substitution.
+	annotations: "app.holos.run/description": "my-chart \(parameters.chart) for environment \(parameters.env)"
+	// Selector labels
+	labels: env: parameters.env
+}