Update Cue tutorial to use testscript

PROBLEM:

The "Cue" tutorial has hardcoded code blocks and hasn't been
updated to use the automated testscript workflow.

NOTE: This is slightly more complex than normal because we need
to make sure Timoni is installed when we execute the testscripts
due to the fact that we need to execute `timoni mod vendor crds ...`
and capture the output.

SOLUTION:

* Add Timoni as one of the packages that are installed via `make go-deps`.
* Update the testing GH Action to install all go dependencies before executing the tests.
* Create a test for the Cue tutorial.
* Create a testscript for the Cue test.
* Update the Cue MDX file to load in data from the testscript directory.

OUTCOME:

The code content in the Cue tutorial now comes directly from the
testscript workflow.

.gitignore

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

Makefile

@@ -124,6 +124,7 @@ go-deps: ## tool versions pinned in tools.go
 	go install golang.org/x/tools/cmd/godoc
 	go install github.com/princjef/gomarkdoc/cmd/gomarkdoc
 	go install github.com/google/ko
+	go install github.com/stefanprodan/timoni/cmd/timoni@v0.23.0
 	# curl https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | bash
 
 .PHONY: frontend-deps
@@ -154,6 +155,10 @@ website: ## Build website
 unity: ## https://cuelabs.dev/unity/
 	./scripts/unity
 
+.PHONY: update-docs
+update-docs: ## Update doc examples
+	HOLOS_UPDATE_SCRIPTS=1 go test -v ./doc/md/...
+
 .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)

api/author/v1alpha5/definitions.go

@@ -84,6 +84,9 @@ type Helm struct {
 	Chart core.Chart
 	// Values represents data to marshal into a values.yaml for helm.
 	Values core.Values
+	// ValueFiles represents value files for migration from helm value
+	// hierarchies.  Use Values instead.
+	ValueFiles []core.ValueFile `json:",omitempty"`
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	EnableHooks bool `cue:"true | *false"`
 	// Namespace sets the helm chart namespace flag if provided.

api/core/v1alpha5/types.go

@@ -118,8 +118,12 @@ type Helm struct {
 	// Chart represents a helm chart to manage.
 	Chart Chart `json:"chart" yaml:"chart"`
 	// Values represents values for holos to marshal into values.yaml when
-	// rendering the chart.
+	// rendering the chart.  Values follow ValueFiles when both are provided.
 	Values Values `json:"values" yaml:"values"`
+	// ValueFiles represents hierarchial value files passed in order to the helm
+	// template -f flag.  Useful for migration from an ApplicationSet.  Use Values
+	// instead.  ValueFiles precede Values when both are provided.
+	ValueFiles []ValueFile `json:"valueFiles,omitempty" yaml:"valueFiles,omitempty"`
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	EnableHooks bool `json:"enableHooks,omitempty" yaml:"enableHooks,omitempty"`
 	// Namespace represents the helm namespace flag
@@ -130,6 +134,17 @@ type Helm struct {
 	KubeVersion string `json:"kubeVersion,omitempty" yaml:"kubeVersion,omitempty"`
 }
 
+// ValueFile represents one Helm value file produced from CUE.
+type ValueFile struct {
+	// Name represents the file name, e.g. "region-values.yaml"
+	Name string `json:"name" yaml:"name"`
+	// Kind is a discriminator.
+	Kind string `json:"kind" yaml:"kind" cue:"\"Values\""`
+	// Values represents values for holos to marshal into the file name specified
+	// by Name when rendering the chart.
+	Values Values `json:"values,omitempty" yaml:"values,omitempty"`
+}
+
 // Values represents [Helm] Chart values generated from CUE.
 type Values map[string]any
 

cmd/holos/tests/v1alpha5/schemas/capabilities.txt

@@ -1,7 +1,9 @@
 # https://github.com/holos-run/holos/issues/330
 exec holos init platform v1alpha5 --force
+# Make sure the helm chart works with plain helm
 exec helm template ./components/capabilities/vendor/0.1.0/capabilities
-cmp stdout want/helm-template.yaml
+stdout 'name: has-foo-v1beta1'
+stdout 'kubeVersion: v'
 exec holos render platform ./platform
 # When no capabilities are specified
 cmp deploy/components/capabilities/capabilities.gen.yaml want/when-no-capabilities-specified.yaml

doc/md/api/author.md

@@ -86,6 +86,9 @@ type Helm struct {
     Chart core.Chart
     // Values represents data to marshal into a values.yaml for helm.
     Values core.Values
+    // ValueFiles represents value files for migration from helm value
+    // hierarchies.  Use Values instead.
+    ValueFiles []core.ValueFile `json:",omitempty"`
     // EnableHooks enables helm hooks when executing the `helm template` command.
     EnableHooks bool `cue:"true | *false"`
     // Namespace sets the helm chart namespace flag if provided.

doc/md/api/core.md

@@ -43,6 +43,7 @@ Package core contains schemas for a [Platform](<#Platform>) and [BuildPlan](<#Bu
 - [type Resources](<#Resources>)
 - [type Transformer](<#Transformer>)
 - [type Validator](<#Validator>)
+- [type ValueFile](<#ValueFile>)
 - [type Values](<#Values>)
 
 
@@ -283,8 +284,12 @@ type Helm struct {
     // Chart represents a helm chart to manage.
     Chart Chart `json:"chart" yaml:"chart"`
     // Values represents values for holos to marshal into values.yaml when
-    // rendering the chart.
+    // rendering the chart.  Values follow ValueFiles when both are provided.
     Values Values `json:"values" yaml:"values"`
+    // ValueFiles represents hierarchial value files passed in order to the helm
+    // template -f flag.  Useful for migration from an ApplicationSet.  Use Values
+    // instead.  ValueFiles precede Values when both are provided.
+    ValueFiles []ValueFile `json:"valueFiles,omitempty" yaml:"valueFiles,omitempty"`
     // EnableHooks enables helm hooks when executing the `helm template` command.
     EnableHooks bool `json:"enableHooks,omitempty" yaml:"enableHooks,omitempty"`
     // Namespace represents the helm namespace flag
@@ -493,6 +498,23 @@ type Validator struct {
 }
 ```
 
+<a name="ValueFile"></a>
+## type ValueFile {#ValueFile}
+
+ValueFile represents one Helm value file produced from CUE.
+
+```go
+type ValueFile struct {
+    // Name represents the file name, e.g. "region-values.yaml"
+    Name string `json:"name" yaml:"name"`
+    // Kind is a discriminator.
+    Kind string `json:"kind" yaml:"kind" cue:"\"Values\""`
+    // Values represents values for holos to marshal into the file name specified
+    // by Name when rendering the chart.
+    Values Values `json:"values,omitempty" yaml:"values,omitempty"`
+}
+```
+
 <a name="Values"></a>
 ## type Values {#Values}
 

doc/md/tutorial/_cue/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_cue/examples/02-cue.txt

@@ -0,0 +1,166 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-cue-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail mkdir-and-init.sh'
+cd holos-cue-tutorial
+
+# Create the components directory, then combine and execute the multiline
+# podinfo component header/body/trailer files
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+exec cat $WORK/podinfo-component-header.sh $WORK/podinfo-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files.
+exec cat $WORK/register-components-header.sh $WORK/register-components-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render and capture output
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Git init and commit
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+
+# Combine and execute the mixin component header/body/trailer files
+exec cat $WORK/mixin-component-header.sh $WORK/mixin-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Import CRDs with Timoni
+exec bash -c 'bash -euo pipefail $WORK/import-crds.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/timoni-vendor.txt
+
+# Render platform
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+
+# Git diff and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-cue-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-cue-tutorial && cd holos-cue-tutorial
+holos init platform v1alpha5
+-- mkdir-components.sh --
+mkdir -p components/podinfo
+-- import-crds.sh --
+timoni mod vendor crds -f https://raw.githubusercontent.com/external-secrets/external-secrets/v0.10.5/deploy/crds/bundle.yaml
+-- podinfo-component-header.sh --
+cat <<EOF > components/podinfo/podinfo.cue
+-- podinfo-component-body.cue --
+package holos
+
+// export the component build plan to holos
+holos: Component.BuildPlan
+
+// Component is a Helm chart
+Component: #Helm & {
+	Name:      "podinfo"
+	Namespace: "default"
+	// Add metadata.namespace to all resources with kustomize.
+	KustomizeConfig: Kustomization: namespace: Namespace
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- register-components-header.sh --
+cat <<EOF > platform/podinfo.cue
+-- register-components-body.cue --
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+}
+-- render.sh --
+holos render platform
+-- git-init.sh --
+git init . && git add . && git commit -m initial
+-- mixin-component-header.sh --
+cat <<EOF > components/podinfo/mixins.cue
+-- mixin-component-body.cue --
+package holos
+
+// Component fields are unified with podinfo.cue
+Component: {
+	// Concrete values are defined in podinfo.cue
+	Name:      string
+	Namespace: string
+
+	// Resources represents mix-in resources organized as a struct.
+	Resources: ExternalSecret: (Name): {
+		// Name is consistent with the component name.
+		metadata: name: Name
+		// Namespace is consistent with the component namespace.
+		metadata: namespace: Namespace
+		spec: {
+			// Ensure the target secret name is consistent.
+			target: name: metadata.name
+			// Ensure the name in the SecretStore is consistent.
+			dataFrom: [{extract: {key: metadata.name}}]
+			refreshInterval: "30s"
+			secretStoreRef: kind: "SecretStore"
+			secretStoreRef: name: "default"
+		}
+	}
+}
+-- git-diff.sh --
+git diff deploy
+-- git.diff --
+diff --git a/deploy/components/podinfo/podinfo.gen.yaml b/deploy/components/podinfo/podinfo.gen.yaml
+index 6e4aec0..f79e9d0 100644
+--- a/deploy/components/podinfo/podinfo.gen.yaml
++++ b/deploy/components/podinfo/podinfo.gen.yaml
+@@ -112,3 +112,19 @@ spec:
+       volumes:
+       - emptyDir: {}
+         name: data
++---
++apiVersion: external-secrets.io/v1beta1
++kind: ExternalSecret
++metadata:
++  name: podinfo
++  namespace: default
++spec:
++  dataFrom:
++  - extract:
++      key: podinfo
++  refreshInterval: 30s
++  secretStoreRef:
++    kind: SecretStore
++    name: default
++  target:
++    name: podinfo

doc/md/tutorial/_cue/script-01-holos-version/command.sh

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

doc/md/tutorial/_cue/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_cue/script-02-cue/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_cue/script-02-cue/git-diff.sh

@@ -0,0 +1 @@
+git diff deploy

doc/md/tutorial/_cue/script-02-cue/git-init.sh

@@ -0,0 +1 @@
+git init . && git add . && git commit -m initial

doc/md/tutorial/_cue/script-02-cue/git.diff

@@ -0,0 +1,24 @@
+diff --git a/deploy/components/podinfo/podinfo.gen.yaml b/deploy/components/podinfo/podinfo.gen.yaml
+index 6e4aec0..f79e9d0 100644
+--- a/deploy/components/podinfo/podinfo.gen.yaml
++++ b/deploy/components/podinfo/podinfo.gen.yaml
+@@ -112,3 +112,19 @@ spec:
+       volumes:
+       - emptyDir: {}
+         name: data
++---
++apiVersion: external-secrets.io/v1beta1
++kind: ExternalSecret
++metadata:
++  name: podinfo
++  namespace: default
++spec:
++  dataFrom:
++  - extract:
++      key: podinfo
++  refreshInterval: 30s
++  secretStoreRef:
++    kind: SecretStore
++    name: default
++  target:
++    name: podinfo

doc/md/tutorial/_cue/script-02-cue/import-crds.sh

@@ -0,0 +1 @@
+timoni mod vendor crds -f https://raw.githubusercontent.com/external-secrets/external-secrets/v0.10.5/deploy/crds/bundle.yaml

doc/md/tutorial/_cue/script-02-cue/mixin-component-body.cue

@@ -0,0 +1,25 @@
+package holos
+
+// Component fields are unified with podinfo.cue
+Component: {
+	// Concrete values are defined in podinfo.cue
+	Name:      string
+	Namespace: string
+
+	// Resources represents mix-in resources organized as a struct.
+	Resources: ExternalSecret: (Name): {
+		// Name is consistent with the component name.
+		metadata: name: Name
+		// Namespace is consistent with the component namespace.
+		metadata: namespace: Namespace
+		spec: {
+			// Ensure the target secret name is consistent.
+			target: name: metadata.name
+			// Ensure the name in the SecretStore is consistent.
+			dataFrom: [{extract: {key: metadata.name}}]
+			refreshInterval: "30s"
+			secretStoreRef: kind: "SecretStore"
+			secretStoreRef: name: "default"
+		}
+	}
+}

doc/md/tutorial/_cue/script-02-cue/mixin-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/mixins.cue

doc/md/tutorial/_cue/script-02-cue/mkdir-and-init.sh

@@ -0,0 +1,2 @@
+mkdir holos-cue-tutorial && cd holos-cue-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_cue/script-02-cue/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/podinfo

doc/md/tutorial/_cue/script-02-cue/podinfo-component-body.cue

@@ -0,0 +1,19 @@
+package holos
+
+// export the component build plan to holos
+holos: Component.BuildPlan
+
+// Component is a Helm chart
+Component: #Helm & {
+	Name:      "podinfo"
+	Namespace: "default"
+	// Add metadata.namespace to all resources with kustomize.
+	KustomizeConfig: Kustomization: namespace: Namespace
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+}

doc/md/tutorial/_cue/script-02-cue/podinfo-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/podinfo.cue

doc/md/tutorial/_cue/script-02-cue/register-components-body.cue

@@ -0,0 +1,6 @@
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+}

doc/md/tutorial/_cue/script-02-cue/register-components-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/podinfo.cue

doc/md/tutorial/_cue/script-02-cue/register-components-output.txt

@@ -0,0 +1,3 @@
+cached podinfo 6.6.2
+rendered podinfo in 1.938665041s
+rendered platform in 1.938759417s

doc/md/tutorial/_cue/script-02-cue/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_cue/script-02-cue/timoni-vendor.txt

@@ -0,0 +1,17 @@
+3:20PM INF schemas vendored: external-secrets.io/clusterexternalsecret/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/clustersecretstore/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/clustersecretstore/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/externalsecret/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/externalsecret/v1beta1
+3:20PM INF schemas vendored: external-secrets.io/pushsecret/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/secretstore/v1alpha1
+3:20PM INF schemas vendored: external-secrets.io/secretstore/v1beta1
+3:20PM INF schemas vendored: generators.external-secrets.io/acraccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/ecrauthorizationtoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/fake/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/gcraccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/githubaccesstoken/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/password/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/uuid/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/vaultdynamicsecret/v1alpha1
+3:20PM INF schemas vendored: generators.external-secrets.io/webhook/v1alpha1

doc/md/tutorial/_cue/script-02-cue/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_hello-holos/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_hello-holos/examples/02-hello-holos.txt

@@ -0,0 +1,126 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail $WORK/mkdir-and-init.sh'
+cd holos-tutorial
+
+# Create the components directory
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+
+# Combine and execute the multiline podinfo component header/body/trailer files
+exec cat $WORK/podinfo-component-header.sh ../podinfo-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files
+exec cat $WORK/register-podinfo-header.sh ../register-podinfo-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Generate and update the tree of the tutorial directory (omitting the cue.mod directory)
+exec bash -c 'bash -euo pipefail $WORK/tree.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/tree.txt
+
+# Split the rendered manifest into two separate files to display separately
+exec bash -c 'bash -euo pipefail $WORK/split-rendered-manifest.sh $WORK/holos-tutorial/deploy/components/podinfo/podinfo.gen.yaml $WORK'
+
+# Grep for the Hello Holos message and write the output file
+exec bash -c 'bash -euo pipefail $WORK/grep-for-message.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/grepped-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-tutorial && cd holos-tutorial
+holos init platform v1alpha5
+-- tree.sh --
+tree -L 3 -I cue.mod .
+-- mkdir-components.sh --
+mkdir -p components/podinfo
+-- podinfo-component-header.sh --
+cat <<EOF > components/podinfo/podinfo.cue
+-- podinfo-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: HelmChart.BuildPlan
+
+HelmChart: #Helm & {
+	Name: "podinfo"
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	// Holos marshals Values into values.yaml for Helm.
+	Values: {
+		// message is a string with a default value.  @tag indicates a value may
+		// be injected from the platform spec component parameters.
+		ui: {
+			message: string | *"Hello World" @tag(greeting, type=string)
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- register-podinfo-header.sh --
+cat <<EOF > platform/podinfo.cue
+-- register-podinfo-body.cue --
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+	// Inject a value into the component.
+	parameters: greeting: "Hello Holos!"
+}
+-- render.sh --
+holos render platform
+-- register-components-output.txt --
+cached podinfo 6.6.2
+rendered podinfo in 1.938665041s
+rendered platform in 1.938759417s
+-- podinfo-rendered-path.sh --
+deploy/components/podinfo/podinfo.gen.yaml
+-- split-rendered-manifest.sh --
+awk 'BEGIN {RS="---"} NR==1 {print > "service.yaml"} NR==2 {print > "deployment.yaml"}' $1
+mv service.yaml $2/rendered-service.yaml
+mv deployment.yaml $2/rendered-deployment.yaml
+-- grep-for-message.sh --
+grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml
+-- grepped-output.txt --
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!

doc/md/tutorial/_hello-holos/script-01-holos-version/command.sh

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

doc/md/tutorial/_hello-holos/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_hello-holos/script-02-hello-holos/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_hello-holos/script-02-hello-holos/grep-for-message.sh

@@ -0,0 +1 @@
+grep -B2 Hello deploy/components/podinfo/podinfo.gen.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/grepped-output.txt

@@ -0,0 +1,3 @@
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!

doc/md/tutorial/_hello-holos/script-02-hello-holos/mkdir-and-init.sh

@@ -0,0 +1,2 @@
+mkdir holos-tutorial && cd holos-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_hello-holos/script-02-hello-holos/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/podinfo

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-component-body.cue

@@ -0,0 +1,23 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: HelmChart.BuildPlan
+
+HelmChart: #Helm & {
+	Name: "podinfo"
+	Chart: {
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	// Holos marshals Values into values.yaml for Helm.
+	Values: {
+		// message is a string with a default value.  @tag indicates a value may
+		// be injected from the platform spec component parameters.
+		ui: {
+			message: string | *"Hello World" @tag(greeting, type=string)
+		}
+	}
+}

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/podinfo/podinfo.cue

doc/md/tutorial/_hello-holos/script-02-hello-holos/podinfo-rendered-path.sh

@@ -0,0 +1 @@
+deploy/components/podinfo/podinfo.gen.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-components-output.txt

@@ -0,0 +1,2 @@
+rendered podinfo in 544.501875ms
+rendered platform in 544.608125ms

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-podinfo-body.cue

@@ -0,0 +1,8 @@
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo"
+	path: "components/podinfo"
+	// Inject a value into the component.
+	parameters: greeting: "Hello Holos!"
+}

doc/md/tutorial/_hello-holos/script-02-hello-holos/register-podinfo-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/podinfo.cue

doc/md/tutorial/_hello-holos/script-02-hello-holos/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_hello-holos/script-02-hello-holos/rendered-deployment.yaml

@@ -0,0 +1,93 @@
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: Helm
+    app.kubernetes.io/name: podinfo
+    app.kubernetes.io/version: 6.6.2
+    helm.sh/chart: podinfo-6.6.2
+  name: podinfo
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: podinfo
+  strategy:
+    rollingUpdate:
+      maxUnavailable: 1
+    type: RollingUpdate
+  template:
+    metadata:
+      annotations:
+        prometheus.io/port: "9898"
+        prometheus.io/scrape: "true"
+      labels:
+        app.kubernetes.io/name: podinfo
+    spec:
+      containers:
+      - command:
+        - ./podinfo
+        - --port=9898
+        - --cert-path=/data/cert
+        - --port-metrics=9797
+        - --grpc-port=9999
+        - --grpc-service-name=podinfo
+        - --level=info
+        - --random-delay=false
+        - --random-error=false
+        env:
+        - name: PODINFO_UI_MESSAGE
+          value: Hello Holos!
+        - name: PODINFO_UI_COLOR
+          value: '#34577c'
+        image: ghcr.io/stefanprodan/podinfo:6.6.2
+        imagePullPolicy: IfNotPresent
+        livenessProbe:
+          exec:
+            command:
+            - podcli
+            - check
+            - http
+            - localhost:9898/healthz
+          failureThreshold: 3
+          initialDelaySeconds: 1
+          periodSeconds: 10
+          successThreshold: 1
+          timeoutSeconds: 5
+        name: podinfo
+        ports:
+        - containerPort: 9898
+          name: http
+          protocol: TCP
+        - containerPort: 9797
+          name: http-metrics
+          protocol: TCP
+        - containerPort: 9999
+          name: grpc
+          protocol: TCP
+        readinessProbe:
+          exec:
+            command:
+            - podcli
+            - check
+            - http
+            - localhost:9898/readyz
+          failureThreshold: 3
+          initialDelaySeconds: 1
+          periodSeconds: 10
+          successThreshold: 1
+          timeoutSeconds: 5
+        resources:
+          limits: null
+          requests:
+            cpu: 1m
+            memory: 16Mi
+        volumeMounts:
+        - mountPath: /data
+          name: data
+      terminationGracePeriodSeconds: 30
+      volumes:
+      - emptyDir: {}
+        name: data
+

doc/md/tutorial/_hello-holos/script-02-hello-holos/rendered-service.yaml

@@ -0,0 +1,23 @@
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: Helm
+    app.kubernetes.io/name: podinfo
+    app.kubernetes.io/version: 6.6.2
+    helm.sh/chart: podinfo-6.6.2
+  name: podinfo
+spec:
+  ports:
+  - name: http
+    port: 9898
+    protocol: TCP
+    targetPort: http
+  - name: grpc
+    port: 9999
+    protocol: TCP
+    targetPort: grpc
+  selector:
+    app.kubernetes.io/name: podinfo
+  type: ClusterIP
+

doc/md/tutorial/_hello-holos/script-02-hello-holos/split-rendered-manifest.sh

@@ -0,0 +1,3 @@
+awk 'BEGIN {RS="---"} NR==1 {print > "service.yaml"} NR==2 {print > "deployment.yaml"}' $1
+mv service.yaml $2/rendered-service.yaml
+mv deployment.yaml $2/rendered-deployment.yaml

doc/md/tutorial/_hello-holos/script-02-hello-holos/tree.sh

@@ -0,0 +1 @@
+tree -L 3 -I cue.mod .

doc/md/tutorial/_hello-holos/script-02-hello-holos/tree.txt

@@ -0,0 +1,17 @@
+.
+|-- components
+|   `-- podinfo
+|       |-- podinfo.cue
+|       `-- vendor
+|-- deploy
+|   `-- components
+|       `-- podinfo
+|-- platform
+|   |-- platform.gen.cue
+|   `-- podinfo.cue
+|-- platform.metadata.json
+|-- resources.cue
+|-- schema.cue
+`-- tags.cue
+
+8 directories, 7 files

doc/md/tutorial/_hello-holos/script-02-hello-holos/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_helm-values/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_helm-values/examples/02-helm-values.txt

@@ -0,0 +1,374 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-helm-values-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail mkdir-and-init.sh'
+cd holos-helm-values-tutorial
+
+# Git init and create the component directories
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+
+# Combine and execute the multiline prometheus/blackbox component header/body/trailer files
+exec cat $WORK/prometheus-component-header.sh ../prometheus-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+exec cat $WORK/blackbox-component-header.sh ../blackbox-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files.
+exec cat $WORK/register-components-header.sh ../register-components-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Commit and conditionally update the output file
+exec bash -c 'bash -euo pipefail $WORK/register-components-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/register-components-git-commit-output.txt
+
+# Import values
+exec bash -c 'bash -euo pipefail $WORK/import-prometheus-values.sh'
+exec bash -c 'bash -euo pipefail $WORK/import-blackbox-values.sh'
+
+# Render, update the output file, commit, and update the commit output file.
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/import-values-render-output.txt
+exec bash -c 'bash -euo pipefail $WORK/import-values-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/import-values-git-output.txt
+
+# Create the common configuration path
+exec bash -c 'bash -euo pipefail $WORK/mkdir-common-config.sh'
+
+# Combine and execute the common configuration header/body/trailer to write the cue file.
+exec cat $WORK/blackbox-common-config-header.sh ../blackbox-common-config-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Git commit blackbox common config
+exec bash -c 'bash -euo pipefail $WORK/blackbox-common-config-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/blackbox-common-config-git-output.txt
+
+# Patch the common config values file and write to output file.
+#
+# NOTE: Using a symlink here because the patch script references values.patch
+# within the same directory, but it actually lives one directory up in the
+# testscript $WORK dir.
+exec ln -s $WORK/values.patch values.patch
+exec bash -c 'bash -euo pipefail $WORK/common-config-patch.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/common-config-patch.txt
+
+# Remove patch and commit changes
+exec bash -c 'bash -euo pipefail $WORK/common-config-rm.sh'
+exec bash -c 'bash -euo pipefail $WORK/common-config-git.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/common-config-git-output.txt
+
+# Final render and update of output file.
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/reviewing-changes-git-output.txt
+
+# Git diff and write to output file.
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Final commit and write to output file
+exec bash -c 'bash -euo pipefail $WORK/reviewing-changes-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/reviewing-changes-git-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-helm-values-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-helm-values-tutorial
+cd holos-helm-values-tutorial
+holos init platform v1alpha5
+-- git-init.sh --
+git init . && git add . && git commit -m "initial commit"
+-- mkdir-components.sh --
+mkdir -p components/prometheus components/blackbox
+-- prometheus-component-header.sh --
+cat <<EOF > components/prometheus/prometheus.cue
+-- prometheus-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus"
+		version: "25.27.0"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- blackbox-component-header.sh --
+cat <<EOF > components/blackbox/blackbox.cue
+-- blackbox-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus-blackbox-exporter"
+		version: "9.0.1"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}
+-- register-components-header.sh --
+cat <<EOF > platform/prometheus.cue
+-- register-components-body.cue --
+package holos
+
+Platform: Components: {
+	prometheus: {
+		name: "prometheus"
+		path: "components/prometheus"
+	}
+	blackbox: {
+		name: "blackbox"
+		path: "components/blackbox"
+	}
+}
+-- render.sh --
+holos render platform
+-- register-components-output.txt --
+cached prometheus-blackbox-exporter 9.0.1
+rendered blackbox in 3.825430417s
+cached prometheus 25.27.0
+rendered prometheus in 4.840089667s
+rendered platform in 4.840137792s
+-- register-components-git-commit.sh --
+git add . && git commit -m 'add blackbox and prometheus'
+-- register-components-git-commit-output.txt --
+[main b5df111] add blackbox and prometheus
+ 5 files changed, 1550 insertions(+)
+ create mode 100644 components/blackbox/blackbox.cue
+ create mode 100644 components/prometheus/prometheus.cue
+ create mode 100644 deploy/components/blackbox/blackbox.gen.yaml
+ create mode 100644 deploy/components/prometheus/prometheus.gen.yaml
+ create mode 100644 platform/prometheus.cue
+-- import-prometheus-values.sh --
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/prometheus/values.cue \
+  components/prometheus/vendor/25.27.0/prometheus/values.yaml
+-- import-blackbox-values.sh --
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/blackbox/values.cue \
+  components/blackbox/vendor/9.0.1/prometheus-blackbox-exporter/values.yaml
+-- import-values-render-output.txt --
+rendered blackbox in 365.936792ms
+rendered prometheus in 371.855875ms
+rendered platform in 372.109916ms
+-- import-values-git-commit.sh --
+git add . && git commit -m 'import values'
+-- import-values-git-output.txt --
+[main 52e90ea] import values
+ 2 files changed, 1815 insertions(+)
+ create mode 100644 components/blackbox/values.cue
+ create mode 100644 components/prometheus/values.cue
+-- mkdir-common-config.sh --
+mkdir -p config/prometheus
+-- blackbox-common-config-header.sh --
+cat <<EOF > config/prometheus/blackbox.cue
+-- blackbox-common-config-body.cue --
+package prometheus
+
+// Schema Definition
+#Blackbox: {
+	// host constrained to a lower case dns label
+	host: string & =~"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
+	// port constrained to a valid range
+	port: int & >0 & <=65535
+}
+
+// Concrete values must validate against the schema.
+blackbox: #Blackbox & {
+	host: "blackbox"
+	port: 9115
+}
+-- blackbox-common-config-git-commit.sh --
+git add . && git commit -m 'add blackbox configuration'
+-- blackbox-common-config-git-output.txt --
+[main 1adcd08] add blackbox configuration
+ 1 file changed, 15 insertions(+)
+ create mode 100644 components/blackbox.cue
+-- common-config-patch.sh --
+patch -p1 < values.patch
+-- values.patch --
+--- a/components/blackbox/values.cue
++++ b/components/blackbox/values.cue
+@@ -1,6 +1,11 @@
+ package holos
+ 
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
++	fullnameOverride: prometheus.blackbox.host
++
+ 	global: {
+ 		//# Global image registry to use if it needs to be overriden for some specific use cases (e.g local registries, custom images, ...)
+ 		//#
+@@ -192,7 +197,7 @@ Helm: Values: {
+ 		annotations: {}
+ 		labels: {}
+ 		type: "ClusterIP"
+-		port: 9115
++		port: prometheus.blackbox.port
+ 		ipDualStack: {
+ 			enabled: false
+ 			ipFamilies: ["IPv6", "IPv4"]
+--- a/components/prometheus/values.cue
++++ b/components/prometheus/values.cue
+@@ -1,5 +1,8 @@
+ package holos
+
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
+        // yaml-language-server: $schema=values.schema.json
+        // Default values for prometheus.
+@@ -1083,7 +1086,7 @@ Helm: Values: {
+ 					target_label: "__param_target"
+ 				}, {
+ 					target_label: "__address__"
+-					replacement:  "blackbox"
++					replacement:  "\(prometheus.blackbox.host):\(prometheus.blackbox.port)"
+ 				}, {
+ 					source_labels: ["__param_target"]
+ 					target_label: "instance"
+-- common-config-patch.txt --
+patching file 'components/blackbox/values.cue'
+patching file 'components/prometheus/values.cue'
+-- common-config-rm.sh --
+rm values.patch
+-- common-config-git.sh --
+git add . && git commit -m 'integrate blackbox and prometheus together'
+-- common-config-git-output.txt --
+[main 4221803] integrate blackbox and prometheus together
+ 2 files changed, 4 insertions(+), 2 deletions(-)
+-- reviewing-changes-render-output.txt --
+rendered blackbox in 374.810666ms
+rendered prometheus in 382.899334ms
+rendered platform in 383.270625ms
+-- git-diff.sh --
+git diff
+-- git.diff --
+diff --git a/deploy/components/blackbox/blackbox.gen.yaml b/deploy/components/blackbox/blackbox.gen.yaml
+index 3db20cd..5336f44 100644
+--- a/deploy/components/blackbox/blackbox.gen.yaml
++++ b/deploy/components/blackbox/blackbox.gen.yaml
+@@ -7,7 +7,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -31,7 +31,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -43,7 +43,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   ports:
+@@ -65,7 +65,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   replicas: 1
+@@ -119,8 +119,8 @@ spec:
+           name: config
+       hostNetwork: false
+       restartPolicy: Always
+-      serviceAccountName: prometheus-blackbox-exporter
++      serviceAccountName: blackbox
+       volumes:
+       - configMap:
+-          name: prometheus-blackbox-exporter
++          name: blackbox
+         name: config
+diff --git a/deploy/components/prometheus/prometheus.gen.yaml b/deploy/components/prometheus/prometheus.gen.yaml
+index 9e02bce..ab638f0 100644
+--- a/deploy/components/prometheus/prometheus.gen.yaml
++++ b/deploy/components/prometheus/prometheus.gen.yaml
+@@ -589,7 +589,7 @@ data:
+       - source_labels:
+         - __address__
+         target_label: __param_target
+-      - replacement: blackbox
++      - replacement: blackbox:9115
+         target_label: __address__
+       - source_labels:
+         - __param_target
+-- reviewing-changes-git-commit.sh --
+git add . && git commit -m 'render integrated blackbox and prometheus manifests'
+-- reviewing-changes-git-output.txt --
+[main 67efe0d] render integrated blackbox and prometheus manifests
+ 2 files changed, 7 insertions(+), 7 deletions(-)

doc/md/tutorial/_helm-values/script-01-holos-version/command.sh

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

doc/md/tutorial/_helm-values/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-body.cue

@@ -0,0 +1,15 @@
+package prometheus
+
+// Schema Definition
+#Blackbox: {
+	// host constrained to a lower case dns label
+	host: string & =~"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
+	// port constrained to a valid range
+	port: int & >0 & <=65535
+}
+
+// Concrete values must validate against the schema.
+blackbox: #Blackbox & {
+	host: "blackbox"
+	port: 9115
+}

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add blackbox configuration'

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-output.txt

@@ -0,0 +1,3 @@
+[main 1adcd08] add blackbox configuration
+ 1 file changed, 15 insertions(+)
+ create mode 100644 components/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-header.sh

@@ -0,0 +1 @@
+cat <<EOF > config/prometheus/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-body.cue

@@ -0,0 +1,15 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus-blackbox-exporter"
+		version: "9.0.1"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/blackbox/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git-output.txt

@@ -0,0 +1,2 @@
+[main 4221803] integrate blackbox and prometheus together
+ 2 files changed, 4 insertions(+), 2 deletions(-)

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'integrate blackbox and prometheus together'

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.sh

@@ -0,0 +1 @@
+patch -p1 < values.patch

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.txt

@@ -0,0 +1,2 @@
+patching file 'components/blackbox/values.cue'
+patching file 'components/prometheus/values.cue'

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-rm.sh

@@ -0,0 +1 @@
+rm values.patch

doc/md/tutorial/_helm-values/script-02-helm-values/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_helm-values/script-02-helm-values/git-diff.sh

@@ -0,0 +1 @@
+git diff

doc/md/tutorial/_helm-values/script-02-helm-values/git-init.sh

@@ -0,0 +1 @@
+git init . && git add . && git commit -m "initial commit"

doc/md/tutorial/_helm-values/script-02-helm-values/git.diff

@@ -0,0 +1,64 @@
+diff --git a/deploy/components/blackbox/blackbox.gen.yaml b/deploy/components/blackbox/blackbox.gen.yaml
+index 3db20cd..5336f44 100644
+--- a/deploy/components/blackbox/blackbox.gen.yaml
++++ b/deploy/components/blackbox/blackbox.gen.yaml
+@@ -7,7 +7,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -31,7 +31,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -43,7 +43,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   ports:
+@@ -65,7 +65,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   replicas: 1
+@@ -119,8 +119,8 @@ spec:
+           name: config
+       hostNetwork: false
+       restartPolicy: Always
+-      serviceAccountName: prometheus-blackbox-exporter
++      serviceAccountName: blackbox
+       volumes:
+       - configMap:
+-          name: prometheus-blackbox-exporter
++          name: blackbox
+         name: config
+diff --git a/deploy/components/prometheus/prometheus.gen.yaml b/deploy/components/prometheus/prometheus.gen.yaml
+index 9e02bce..ab638f0 100644
+--- a/deploy/components/prometheus/prometheus.gen.yaml
++++ b/deploy/components/prometheus/prometheus.gen.yaml
+@@ -589,7 +589,7 @@ data:
+       - source_labels:
+         - __address__
+         target_label: __param_target
+-      - replacement: blackbox
++      - replacement: blackbox:9115
+         target_label: __address__
+       - source_labels:
+         - __param_target

doc/md/tutorial/_helm-values/script-02-helm-values/import-blackbox-values.sh

@@ -0,0 +1,5 @@
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/blackbox/values.cue \
+  components/blackbox/vendor/9.0.1/prometheus-blackbox-exporter/values.yaml

doc/md/tutorial/_helm-values/script-02-helm-values/import-prometheus-values.sh

@@ -0,0 +1,5 @@
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/prometheus/values.cue \
+  components/prometheus/vendor/25.27.0/prometheus/values.yaml

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'import values'

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-output.txt

@@ -0,0 +1,4 @@
+[main 52e90ea] import values
+ 2 files changed, 1815 insertions(+)
+ create mode 100644 components/blackbox/values.cue
+ create mode 100644 components/prometheus/values.cue

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-render-output.txt

@@ -0,0 +1,3 @@
+rendered blackbox in 365.936792ms
+rendered prometheus in 371.855875ms
+rendered platform in 372.109916ms

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-and-init.sh

@@ -0,0 +1,3 @@
+mkdir holos-helm-values-tutorial
+cd holos-helm-values-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-common-config.sh

@@ -0,0 +1 @@
+mkdir -p config/prometheus

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/prometheus components/blackbox

doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-body.cue

@@ -0,0 +1,15 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus"
+		version: "25.27.0"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/prometheus/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-body.cue

@@ -0,0 +1,12 @@
+package holos
+
+Platform: Components: {
+	prometheus: {
+		name: "prometheus"
+		path: "components/prometheus"
+	}
+	blackbox: {
+		name: "blackbox"
+		path: "components/blackbox"
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit-output.txt

@@ -0,0 +1,7 @@
+[main b5df111] add blackbox and prometheus
+ 5 files changed, 1550 insertions(+)
+ create mode 100644 components/blackbox/blackbox.cue
+ create mode 100644 components/prometheus/prometheus.cue
+ create mode 100644 deploy/components/blackbox/blackbox.gen.yaml
+ create mode 100644 deploy/components/prometheus/prometheus.gen.yaml
+ create mode 100644 platform/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add blackbox and prometheus'

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-output.txt

@@ -0,0 +1,5 @@
+cached prometheus-blackbox-exporter 9.0.1
+rendered blackbox in 3.825430417s
+cached prometheus 25.27.0
+rendered prometheus in 4.840089667s
+rendered platform in 4.840137792s

doc/md/tutorial/_helm-values/script-02-helm-values/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'render integrated blackbox and prometheus manifests'

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-output.txt

@@ -0,0 +1,2 @@
+[main 67efe0d] render integrated blackbox and prometheus manifests
+ 2 files changed, 7 insertions(+), 7 deletions(-)

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-render-output.txt

@@ -0,0 +1,3 @@
+rendered blackbox in 374.810666ms
+rendered prometheus in 382.899334ms
+rendered platform in 383.270625ms

doc/md/tutorial/_helm-values/script-02-helm-values/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_helm-values/script-02-helm-values/values.patch

@@ -0,0 +1,43 @@
+--- a/components/blackbox/values.cue
++++ b/components/blackbox/values.cue
+@@ -1,6 +1,11 @@
+ package holos
+ 
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
++	fullnameOverride: prometheus.blackbox.host
++
+ 	global: {
+ 		//# Global image registry to use if it needs to be overriden for some specific use cases (e.g local registries, custom images, ...)
+ 		//#
+@@ -192,7 +197,7 @@ Helm: Values: {
+ 		annotations: {}
+ 		labels: {}
+ 		type: "ClusterIP"
+-		port: 9115
++		port: prometheus.blackbox.port
+ 		ipDualStack: {
+ 			enabled: false
+ 			ipFamilies: ["IPv6", "IPv4"]
+--- a/components/prometheus/values.cue
++++ b/components/prometheus/values.cue
+@@ -1,5 +1,8 @@
+ package holos
+
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
+        // yaml-language-server: $schema=values.schema.json
+        // Default values for prometheus.
+@@ -1083,7 +1086,7 @@ Helm: Values: {
+ 					target_label: "__param_target"
+ 				}, {
+ 					target_label: "__address__"
+-					replacement:  "blackbox"
++					replacement:  "\(prometheus.blackbox.host):\(prometheus.blackbox.port)"
+ 				}, {
+ 					source_labels: ["__param_target"]
+ 					target_label: "instance"

doc/md/tutorial/_kustomize/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_kustomize/examples/02-kustomize.txt

@@ -0,0 +1,226 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-kustomize-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail $WORK/mkdir-and-init.sh'
+cd holos-kustomize-tutorial
+
+# Initialize git
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+
+# Create the component directory
+exec bash -c 'bash -euo pipefail $WORK/mkdir-component.sh'
+
+# Combine and execute the multiline httpbin component header/body/trailer files
+exec cat $WORK/httpbin-component-header.sh $WORK/httpbin-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline httpbin yaml header/body/trailer files
+exec cat $WORK/httpbin-yaml-header.sh $WORK/httpbin-yaml-body.yaml $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline registration header/body/trailer files
+exec cat $WORK/register-component-header.sh $WORK/register-component-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-component-output.txt
+
+# Git commit and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-commit-component.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git-commit-component-output.txt
+
+# Export Build Plan and capture output
+exec bash -c 'bash -euo pipefail $WORK/cue-export.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/buildplan-output.cue
+
+# Combine and execute the multiline kustomize patch header/body/trailer files
+exec cat $WORK/httpbin-patch-header.sh $WORK/httpbin-patch-body.cue $WORK/eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform and capture output
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/kustomize-patch-render-output.txt
+
+# Git diff and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Git commit and capture output
+exec bash -c 'bash -euo pipefail $WORK/git-commit-final.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git-commit-final-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-kustomize-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-kustomize-tutorial
+cd holos-kustomize-tutorial
+holos init platform v1alpha5
+-- git-init.sh --
+git init . && git add . && git commit -m initial
+-- mkdir-component.sh --
+mkdir -p components/httpbin
+-- httpbin-component-header.sh --
+cat <<EOF > components/httpbin/httpbin.cue
+-- httpbin-component-body.cue --
+package holos
+
+// Produce a Kustomize BuildPlan for Holos
+holos: Kustomize.BuildPlan
+
+// https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/README.md
+Kustomize: #Kustomize & {
+	KustomizeConfig: {
+		// Files tells Holos to copy the file from the component path to the
+		// temporary directory Holos uses for BuildPlan execution.
+		Files: {
+			"httpbin.yaml": _
+		}
+		CommonLabels: {
+			"app.kubernetes.io/name": "httpbin"
+		}
+		// Kustomization represents a kustomization.yaml file in CUE.  Holos
+		// marshals this field into a `kustomization.yaml` while processing a
+		// BuildPlan.  See
+		// https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
+		Kustomization: {
+			images: [{name: "mccutchen/go-httpbin"}]
+			// Use a hidden field to compose patches easily with a struct.  Hidden
+			// fields are not included in exported structures.
+			_patches: {}
+			// Convert the hidden struct to a list.
+			patches: [for x in _patches {x}]
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- httpbin-yaml-header.sh --
+cat <<EOF > components/httpbin/httpbin.yaml
+-- httpbin-yaml-body.yaml --
+# https://github.com/mccutchen/go-httpbin/blob/v2.15.0/kustomize/resources.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: httpbin
+spec:
+  template:
+    spec:
+      containers:
+        - name: httpbin
+          image: mccutchen/go-httpbin
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          readinessProbe:
+            httpGet:
+              path: /status/200
+              port: http
+          resources: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin
+spec:
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+      appProtocol: http
+-- register-component-header.sh --
+cat <<EOF > platform/httpbin.cue
+-- register-component-body.cue --
+package holos
+
+Platform: Components: {
+	httpbin: {
+		name: "httpbin"
+		path: "components/httpbin"
+	}
+}
+-- git-commit-component.sh --
+git add . && git commit -m 'add httpbin'
+-- cue-export.sh --
+holos cue export --expression holos --out=yaml ./components/httpbin
+-- httpbin-patch-header.sh --
+cat <<EOF > components/httpbin/patches.cue
+-- httpbin-patch-body.cue --
+package holos
+
+import "encoding/yaml"
+
+// Mix in a Kustomize patch to the configuration.
+Kustomize: KustomizeConfig: Kustomization: _patches: {
+	probe: {
+		target: kind: "Service"
+		target: name: "httpbin"
+		patch: yaml.Marshal([{
+			op:    "add"
+			path:  "/metadata/annotations/prometheus.io~1probe"
+			value: "true"
+		}])
+	}
+}
+-- httpbin-component-output.txt --
+rendered httpbin in 197.030208ms
+rendered platform in 197.416416ms
+-- render.sh --
+holos render platform
+-- git-diff.sh --
+git diff
+-- git.diff --
+diff --git a/deploy/components/httpbin/httpbin.gen.yaml b/deploy/components/httpbin/httpbin.gen.yaml
+index 298b9a8..a16bd1a 100644
+--- a/deploy/components/httpbin/httpbin.gen.yaml
++++ b/deploy/components/httpbin/httpbin.gen.yaml
+@@ -1,6 +1,8 @@
+ apiVersion: v1
+ kind: Service
+ metadata:
++  annotations:
++    prometheus.io/probe: "true"
+   labels:
+     app.kubernetes.io/name: httpbin
+   name: httpbin
+-- git-commit-final.sh --
+git add . && git commit -m 'annotate httpbin for prometheus probes'

doc/md/tutorial/_kustomize/script-01-holos-version/command.sh

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

doc/md/tutorial/_kustomize/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.103.0

doc/md/tutorial/_kustomize/script-02-kustomize/buildplan-output.cue

@@ -0,0 +1,36 @@
+kind: BuildPlan
+apiVersion: v1alpha5
+metadata:
+  name: no-name
+spec:
+  artifacts:
+    - artifact: components/no-name/no-name.gen.yaml
+      generators:
+        - kind: Resources
+          output: resources.gen.yaml
+          resources: {}
+        - kind: File
+          output: httpbin.yaml
+          file:
+            source: httpbin.yaml
+      validators: []
+      transformers:
+        - kind: Kustomize
+          inputs:
+            - resources.gen.yaml
+            - httpbin.yaml
+          output: components/no-name/no-name.gen.yaml
+          kustomize:
+            kustomization:
+              labels:
+                - includeSelectors: false
+                  pairs:
+                    app.kubernetes.io/name: httpbin
+              patches: []
+              images:
+                - name: mccutchen/go-httpbin
+              resources:
+                - resources.gen.yaml
+                - httpbin.yaml
+              kind: Kustomization
+              apiVersion: kustomize.config.k8s.io/v1beta1

doc/md/tutorial/_kustomize/script-02-kustomize/cue-export.sh

@@ -0,0 +1 @@
+holos cue export --expression holos --out=yaml ./components/httpbin

doc/md/tutorial/_kustomize/script-02-kustomize/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-component-output.txt

@@ -0,0 +1,6 @@
+[main f0dd632] add httpbin
+ 4 files changed, 113 insertions(+)
+ create mode 100644 components/httpbin/httpbin.cue
+ create mode 100644 components/httpbin/httpbin.yaml
+ create mode 100644 deploy/components/httpbin/httpbin.gen.yaml
+ create mode 100644 platform/httpbin.cue

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-component.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add httpbin'

doc/md/tutorial/_kustomize/script-02-kustomize/git-commit-final-output.txt

@@ -0,0 +1,3 @@
+[main b120712] annotate httpbin for prometheus probes
+ 2 files changed, 18 insertions(+)
+ create mode 100644 components/httpbin/patches.cue