core: define generic command core type for all kinds of tasks

Previously the Command core type was only useful for Validators and was
a bit hacky in that Holos appends the directory to the end of the
argument vector.

This patch changes the Command type to represent a generic command for
use as a Generator, Transformer, or Validator.  The type is extended to
support the semantics of reading output from a file, directory, or
standard output pipe.

Go templates are used to fill in Holos managed data values, for example
the temporary directory associated with the pipeline task.  The TaskData
structu represents these values passed into the template engine.

.cspell.json

@@ -29,6 +29,7 @@
     "authpolicy",
     "authproxy",
     "authroutes",
+    "autoload",
     "automount",
     "automounting",
     "autoscaler",
@@ -36,6 +37,7 @@
     "blackbox",
     "buildplan",
     "buildplans",
+    "Buildx",
     "builtinpluginloadingoptions",
     "cachedir",
     "cadvisor",
@@ -44,6 +46,7 @@
     "certificaterequest",
     "certificaterequests",
     "certificatesigningrequests",
+    "chartmuseum",
     "clientset",
     "clsx",
     "clusterexternalsecret",
@@ -58,6 +61,7 @@
     "Cmds",
     "CNCF",
     "CODEOWNERS",
+    "compinit",
     "componentconfig",
     "configdir",
     "configmap",
@@ -71,6 +75,7 @@
     "creds",
     "crossplane",
     "crunchydata",
+    "ctxt",
     "cuecontext",
     "cuelang",
     "customresourcedefinition",
@@ -80,6 +85,7 @@
     "destinationrules",
     "devel",
     "devicecode",
+    "distroless",
     "dnsmasq",
     "dscacheutil",
     "ecrauthorizationtoken",
@@ -98,6 +104,7 @@
     "fieldmaskpb",
     "fieldspec",
     "flushcache",
+    "fluxcd",
     "fullname",
     "gatewayclass",
     "gatewayclasses",
@@ -151,6 +158,7 @@
     "jetstack",
     "jiralert",
     "Jsonnet",
+    "Kargo",
     "kfbh",
     "killall",
     "kubeadm",
@@ -188,6 +196,7 @@
     "mutatingwebhookconfigurations",
     "mvdan",
     "mxcl",
+    "mychart",
     "myhostname",
     "myRegistrKeySecretName",
     "mysecret",
@@ -274,6 +283,7 @@
     "serviceentries",
     "serviceentry",
     "servicemonitor",
+    "sigstore",
     "somevalue",
     "SOMEVAR",
     "sortoptions",
@@ -314,6 +324,7 @@
     "udev",
     "uibutton",
     "Unmarshal",
+    "unshallow",
     "unstage",
     "untar",
     "upbound",

.github/workflows/container.yaml

@@ -0,0 +1,143 @@
+name: Container
+
+# Only allow actors with write permission to the repository to trigger this
+# workflow.
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      git_ref:
+        description: 'Git ref to build (e.g., refs/tags/v1.2.3, refs/heads/main)'
+        required: true
+        type: string
+
+jobs:
+  buildx:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    steps:
+      - name: Set tag from trigger event
+        id: opts
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "ref=${{ inputs.git_ref }}" >> $GITHUB_OUTPUT
+          else
+            echo "ref=${GITHUB_REF}" >> $GITHUB_OUTPUT
+          fi
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.opts.outputs.ref }}
+      - name: SHA
+        id: sha
+        run: echo "sha=$(/usr/bin/git log -1 --format='%H')" >> $GITHUB_OUTPUT
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Fetch tags
+        run: git fetch --prune --unshallow --tags
+      - name: Set Tags
+        id: tags
+        run: |
+          echo "detail=$(/usr/bin/git describe --tags HEAD)" >> $GITHUB_OUTPUT
+          echo "suffix=$(test -n "$(git status --porcelain)" && echo '-dirty' || echo '')" >> $GITHUB_OUTPUT
+          echo "tag=$(/usr/bin/git describe --tags HEAD)$(test -n "$(git status --porcelain)" && echo '-dirty' || echo '')" >> $GITHUB_OUTPUT
+
+      - name: Login to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push container images
+        id: build-and-push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+            ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+      - name: Setup Cosign to sign container images
+        uses: sigstore/cosign-installer@v3.7.0
+      - name: Sign with GitHub OIDC Token
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          cosign sign --yes ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          cosign sign --yes ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          owner: ${{ github.repository_owner }}
+          app-id: ${{ vars.GORELEASER_APP_ID }}
+          private-key: ${{ secrets.GORELEASER_APP_PRIVATE_KEY }}
+      - name: Get GitHub App User ID
+        id: get-user-id
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      - run: |
+          git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+          git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+      - name: Update holos-run/holos-action
+        env:
+          IMAGE: ghcr.io/holos-run/holos:v0.102.1
+          VERSION: ${{ steps.tags.outputs.tag }}
+          USER_ID: ${{ steps.get-user-id.outputs.user-id }}
+          TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          git clone "https://github.com/holos-run/holos-action"
+          cd holos-action
+          git remote set-url origin https://${USER_ID}:${TOKEN}@github.com/holos-run/holos-action
+          docker pull --quiet "${IMAGE}"
+          docker run -v $(pwd):/app --workdir /app --rm "${IMAGE}"  \
+            holos cue export --out yaml action.cue -t "version=${VERSION}" > action.yml
+          git add action.yml
+          git commit -m "ci: update holos to ${VERSION} - https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" || (echo "No changes to commit"; exit 0)
+          git push origin HEAD:main HEAD:v0 HEAD:v1
+
+      - name: Login to quay.io
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USER }}
+          password: ${{ secrets.QUAY_TOKEN }}
+      - name: Push to quay.io
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          # docker push quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+          docker pull --quiet ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          docker tag ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST} \
+                     quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+          docker push quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+
+          docker pull --quiet ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+          docker tag ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST} \
+                     quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+          docker push quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+      - name: Sign quay.io image
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          cosign sign --yes quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          cosign sign --yes quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+
+    outputs:
+      tag: ${{ steps.tags.outputs.tag }}
+      detail: ${{ steps.tags.outputs.detail }}

.github/workflows/golangci-lint.yaml

@@ -27,4 +27,4 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v6
         with:
-          version: v1.60
+          version: v1.64.5

.github/workflows/lint.yaml

@@ -1,6 +1,5 @@
 ---
-# https://github.com/golangci/golangci-lint-action?tab=readme-ov-file#how-to-use
-name: Lint
+name: Spelling
 "on":
   push:
     branches:
@@ -8,35 +7,11 @@ name: Lint
       - test
   pull_request:
     types: [opened, synchronize]
-
 permissions:
   contents: read
-
 jobs:
-  lint:
-    name: lint
+  cspell:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: stable
-
-      ## Not needed on ubuntu-latest
-      # - name: Install Packages
-      #   run: sudo apt update && sudo apt -qq -y install git curl zip unzip tar bzip2 make
-
-      - name: Install Tools
-        run: make tools
-
-      - name: Lint
-        # golangci-lint runs in a separate workflow.
-        run: make lint -o golangci-lint
+      - uses: actions/checkout@v4
+      - run: ./hack/cspell

.github/workflows/test.yaml

@@ -28,19 +28,11 @@ jobs:
         with:
           go-version: stable
 
-      - name: Install Packages
-        run: sudo apt update && sudo apt -qq -y install git curl zip unzip tar bzip2 make
-
       - name: Set up Helm
         uses: azure/setup-helm@v4
 
       - name: Set up Kubectl
         uses: azure/setup-kubectl@v4
 
-      - name: Install Tools
-        run: |
-          set -x
-          make tools
-
       - name: Test
         run: ./scripts/test

.gitignore

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

Dockerfile

@@ -1,8 +1,31 @@
-FROM quay.io/holos-run/debian:bullseye AS final
-USER root
-WORKDIR /app
-ADD bin bin
-RUN chown -R app: /app
-# Kubernetes requires the user to be numeric
-USER 8192
-ENTRYPOINT bin/holos server
+FROM registry.k8s.io/kubectl:v1.31.0 AS kubectl
+# https://github.com/GoogleContainerTools/distroless
+FROM golang:1.23 AS build
+
+WORKDIR /go/src/app
+COPY . .
+
+RUN CGO_ENABLED=0 make install
+RUN CGO_ENABLED=0 go install sigs.k8s.io/kustomize/kustomize/v5
+
+# Install helm to /usr/local/bin/helm
+# https://helm.sh/docs/intro/install/#from-script
+# https://holos.run/docs/v1alpha5/tutorial/setup/#dependencies
+RUN curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 \
+  && chmod 700 get_helm.sh \
+  && DESIRED_VERSION=v3.16.2 ./get_helm.sh \
+  && rm -f get_helm.sh
+
+COPY --from=kubectl /bin/kubectl /usr/local/bin/
+
+# distroless
+FROM gcr.io/distroless/static-debian12 AS final
+COPY --from=build \
+     /go/bin/holos \
+     /go/bin/kustomize \
+     /usr/local/bin/kubectl \
+     /usr/local/bin/helm \
+     /bin/
+
+# Usage: docker run -v $(pwd):/app --workdir /app --rm -it quay.io/holos-run/holos holos render platform
+CMD ["/bin/holos"]

Makefile

@@ -32,17 +32,20 @@ bump: bumppatch
 .PHONY: bumppatch
 bumppatch: ## Bump the patch version.
 	scripts/bump patch
+	HOLOS_UPDATE_SCRIPTS=1 scripts/test
 
 .PHONY: bumpminor
 bumpminor: ## Bump the minor version.
 	scripts/bump minor
 	scripts/bump patch 0
+	HOLOS_UPDATE_SCRIPTS=1 scripts/test
 
 .PHONY: bumpmajor
 bumpmajor: ## Bump the major version.
 	scripts/bump major
 	scripts/bump minor 0
 	scripts/bump patch 0
+	HOLOS_UPDATE_SCRIPTS=1 scripts/test
 
 .PHONY: show-version
 show-version: ## Print the full version.
@@ -75,6 +78,12 @@ build: ## Build holos executable.
 	@echo "GOPATH=${GOPATH}"
 	go build -trimpath -o bin/$(BIN_NAME) -ldflags $(LD_FLAGS) $(REPO_PATH)/cmd/$(BIN_NAME)
 
+.PHONY: debug
+debug: ## Build debug executable.
+	@echo "building ${BIN_NAME}-debug ${VERSION}"
+	@echo "GOPATH=${GOPATH}"
+	go build -o bin/$(BIN_NAME)-debug $(REPO_PATH)/cmd/$(BIN_NAME)
+
 linux: ## Build holos executable for tilt.
 	@echo "building ${BIN_NAME}.linux ${VERSION}"
 	@echo "GOPATH=${GOPATH}"
@@ -154,6 +163,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)

README.md

@@ -119,12 +119,12 @@ here to help.
 
 Holos is licensed under Apache 2.0 as found in the [LICENSE file](LICENSE).
 
-[Holos]: https://holos.run
+[Holos]: https://holos.run/docs/overview/
 [rendered manifests pattern]: https://akuity.io/blog/the-rendered-manifests-pattern
 [CUE]: https://cuelang.org/
 [Discord]: https://discord.gg/JgDVbNpye7
 [GitHub discussions]: https://github.com/holos-run/holos/discussions
 [Why CUE for Configuration]: https://holos.run/blog/why-cue-for-configuration/
-[topics]: https://holos.run/docs/topics/
+[tutorial]: https://holos.run/docs/overview/
 [setup]: https://holos.run/docs/setup/
-[tutorial]: https://holos.run/docs/tutorial/
+[topics]: https://holos.run/docs/topics/

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
 
@@ -146,9 +161,26 @@ type Chart struct {
 }
 
 // Repository represents a [Helm] [Chart] repository.
+//
+// The Auth field is useful to configure http basic authentication to the Helm
+// repository.  Holos gets the username and password from the environment
+// variables represented by the Auth field.
 type Repository struct {
 	Name string `json:"name" yaml:"name"`
 	URL  string `json:"url" yaml:"url"`
+	Auth Auth   `json:"auth,omitempty" yaml:"auth,omitempty"`
+}
+
+// Auth represents environment variable names containing auth credentials.
+type Auth struct {
+	Username AuthSource `json:"username" yaml:"username"`
+	Password AuthSource `json:"password" yaml:"password"`
+}
+
+// AuthSource represents a source for the value of an [Auth] field.
+type AuthSource struct {
+	Value   string `json:"value,omitempty" yaml:"value,omitempty"`
+	FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
 }
 
 // Transformer combines multiple inputs from prior [Generator] or [Transformer]
@@ -158,11 +190,13 @@ type Repository struct {
 //  1. [Kustomize] - Patch and transform the output from prior generators or
 //     transformers.  See [Introduction to Kustomize].
 //  2. [Join] - Concatenate multiple prior outputs into one output.
+//  3. [Slice] - Slice an artifact into multiple artifacts using [kubectl-slice].
 //
 // [Introduction to Kustomize]: https://kubectl.docs.kubernetes.io/guides/config_management/introduction/
+// [kubectl-slice]: https://github.com/patrickdappollonio/kubectl-slice
 type Transformer struct {
 	// Kind represents the kind of transformer. Must be Kustomize, or Join.
-	Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\""`
+	Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\" | \"Slice\""`
 	// Inputs represents the files to transform. The Output of prior Generators
 	// and Transformers.
 	Inputs []FilePath `json:"inputs" yaml:"inputs"`
@@ -222,12 +256,46 @@ type Validator struct {
 	Command Command `json:"command,omitempty" yaml:"command,omitempty"`
 }
 
-// Command represents a command vetting one or more artifacts.  Holos appends
-// fully qualified input file paths to the end of the args list, then executes
-// the command.  Inputs are written into a temporary directory prior to
-// executing the command and removed afterwards.
+// Command represents a generic command for use as a Generator, Transformer, or
+// Validator.  Holos uses the Go template engine to render the Args field using
+// data provided by the TaskData field.  For example to fill in the fully
+// qualified temporary directory used to provide inputs to the task.
 type Command struct {
+	// DisplayName represents a friendly display name for the command.
+	DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty"`
+	// Args represents the complete command argument vector as a go template.
 	Args []string `json:"args,omitempty" yaml:"args,omitempty"`
+	// OutputRef references the source of the output data.
+	OutputRef OutputRef `json:"outputRef,omitempty" yaml:"outputRef,omitempty"`
+	// TaskData populated by Holos for template rendering.
+	TaskData TaskData `json:"taskData,omitempty" yaml:"taskData,omitempty"`
+	// TODO(jjm): add command environment variable support similar to args.
+}
+
+// TaskData represents data values associated with a pipeline task necessary to
+// execute the task.  For example, the randomly generated temporary directory
+// used to read and write artifact files when executing user defined task
+// commands.  Values of this struct are intended for the Go template engine.
+//
+// Holos populates this struct as needed.  Holos may treat user provided values
+// as an error condition.
+type TaskData struct {
+	// TempDir represents the temp directory holos manages for task artifacts.
+	TempDir string `json:"tempDir,omitempty" yaml:"tempDir,omitempty"`
+}
+
+// OutputRef represents a reference to the data source used as the output of a
+// task.  For example, a Generator output may be sourced from standard output or
+// a file path.
+type OutputRef struct {
+	// Kind represents the kind of output produced.
+	Kind string `json:"kind,omitempty" yaml:"kind,omitempty" cue:"string | *\"Pipe\" | \"Path\""`
+	// Pipe represents stdout or stderr.  Ignored unless kind is Pipe.
+	Pipe string `json:"pipe,omitempty" yaml:"pipe,omitempty" cue:"string | *\"stdout\" | \"stderr\""`
+	// Path represents an artifact path relative to the task temp directory.
+	// Ignored unless kind is Path.
+	Path string `json:"path,omitempty" yaml:"path,omitempty"`
+	// TODO(jjm): support jsonpath or cel references to the output data maybe?
 }
 
 // InternalLabel is an arbitrary unique identifier internal to holos itself.
@@ -246,7 +314,7 @@ type Metadata struct {
 	// Labels represents a resource selector.
 	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
 	// Annotations represents arbitrary non-identifying metadata.  For example
-	// holos uses the `cli.holos.run/description` annotation to log resources in a
+	// holos uses the `app.holos.run/description` annotation to log resources in a
 	// user customized way.
 	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
@@ -286,6 +354,10 @@ type Component struct {
 	// Path represents the path of the component relative to the platform root.
 	// Injected as the tag variable "holos_component_path".
 	Path string `json:"path" yaml:"path"`
+	// Instances represents additional cue instance paths to unify with Path.
+	// Useful to unify data files into a component BuildPlan.  Added in holos
+	// 0.101.7.
+	Instances []Instance `json:"instances,omitempty" yaml:"instances,omitempty"`
 	// WriteTo represents the holos render component --write-to flag.  If empty,
 	// the default value for the --write-to flag is used.
 	WriteTo string `json:"writeTo,omitempty" yaml:"writeTo,omitempty"`
@@ -299,6 +371,30 @@ type Component struct {
 	// resulting BuildPlan.
 	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
 	// Annotations represents arbitrary non-identifying metadata.  Use the
-	// `cli.holos.run/description` to customize the log message of each BuildPlan.
+	// `app.holos.run/description` to customize the log message of each BuildPlan.
 	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
+
+// Instance represents a data instance to unify with the configuration.
+//
+// Useful to unify json and yaml files with cue configuration files for
+// integration with other tools.  For example, executing holos render platform
+// from a pull request workflow after [Kargo] executes the [yaml update] and
+// [git wait for pr] promotion steps.
+//
+// [Kargo]: https://docs.kargo.io/
+// [yaml update]: https://docs.kargo.io/references/promotion-steps#yaml-update
+// [git wait for pr]: https://docs.kargo.io/references/promotion-steps#git-wait-for-pr
+type Instance struct {
+	// Kind is a discriminator.
+	Kind string `json:"kind" yaml:"kind" cue:"\"ExtractYAML\""`
+	// Ignored unless kind is ExtractYAML.
+	ExtractYAML ExtractYAML `json:"extractYAML,omitempty" yaml:"extractYAML,omitempty"`
+}
+
+// ExtractYAML represents a cue data instance encoded as yaml or json. If Path
+// refers to a directory all files in the directory are extracted
+// non-recursively.  Otherwise, path must refer to a file.
+type ExtractYAML struct {
+	Path string `json:"path" yaml:"path"`
+}

cmd/cmd.go

@@ -0,0 +1,63 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"runtime/pprof"
+	"runtime/trace"
+
+	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/internal/holos"
+)
+
+// MakeMain makes a main function for the cli or tests.
+func MakeMain(options ...holos.Option) func() int {
+	return func() (exitCode int) {
+		cfg := holos.New(options...)
+		slog.SetDefault(cfg.Logger())
+		ctx := context.Background()
+
+		if format := os.Getenv("HOLOS_CPU_PROFILE"); format != "" {
+			f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+			err := pprof.StartCPUProfile(f)
+			defer func() {
+				pprof.StopCPUProfile()
+				f.Close()
+			}()
+			if err != nil {
+				return cli.HandleError(ctx, err, cfg)
+			}
+		}
+		defer memProfile(ctx, cfg)
+
+		if format := os.Getenv("HOLOS_TRACE"); format != "" {
+			f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+			err := trace.Start(f)
+			defer func() {
+				trace.Stop()
+				f.Close()
+			}()
+			if err != nil {
+				return cli.HandleError(ctx, err, cfg)
+			}
+		}
+
+		feature := &holos.EnvFlagger{}
+		if err := cli.New(cfg, feature).ExecuteContext(ctx); err != nil {
+			return cli.HandleError(ctx, err, cfg)
+		}
+		return 0
+	}
+}
+
+func memProfile(ctx context.Context, cfg *holos.Config) {
+	if format := os.Getenv("HOLOS_MEM_PROFILE"); format != "" {
+		f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+		defer f.Close()
+		if err := pprof.WriteHeapProfile(f); err != nil {
+			_ = cli.HandleError(ctx, err, cfg)
+		}
+	}
+}

cmd/holos/main.go

@@ -3,9 +3,9 @@ package main
 import (
 	"os"
 
-	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/cmd"
 )
 
 func main() {
-	os.Exit(cli.MakeMain()())
+	os.Exit(cmd.MakeMain()())
 }

cmd/holos/main_test.go

@@ -6,15 +6,16 @@ import (
 	"testing"
 
 	cue "cuelang.org/go/cmd/cue/cmd"
-	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/cmd"
 	"github.com/rogpeppe/go-internal/testscript"
 )
 
 func TestMain(m *testing.M) {
-	os.Exit(testscript.RunMain(m, map[string]func() int{
-		"holos": cli.MakeMain(),
-		"cue":   cue.Main,
-	}))
+	holosMain := cmd.MakeMain()
+	testscript.Main(m, map[string]func(){
+		"holos": func() { os.Exit(holosMain()) },
+		"cue":   func() { os.Exit(cue.Main()) },
+	})
 }
 
 func TestGuides_v1alpha5(t *testing.T) {

cmd/holos/tests/v1alpha5/issues/helm-pull-errors.txt

@@ -1,38 +0,0 @@
-# https://github.com/holos-run/holos/issues/332
-env HOME=$WORK
-# Mock with a stub helm command
-env PATH=$WORK/bin:$PATH
-chmod 755 bin/helm
-# Initialize the platform
-exec holos init platform v1alpha5 --force
-# when helm update returns an error
-! exec holos render platform
-# holos should log the helm error to stderr
-stderr 'Error: chart "podinfo" matching 0.0.0 not found in podinfo index'
--- bin/helm --
-#! /bin/bash
-echo 'Error: chart "podinfo" matching 0.0.0 not found in podinfo index' >&2
-exit 2
--- platform/podinfo.cue --
-package holos
-
-Platform: Components: podinfo: {
-	name: "podinfo"
-	path: "components/podinfo"
-}
--- components/podinfo/podinfo.cue --
-package holos
-
-// Produce a helm chart build plan.
-holos: HelmChart.BuildPlan
-
-HelmChart: #Helm & {
-	Name: "podinfo"
-	Chart: {
-		version: "0.0.0"
-		repository: {
-			name: "podinfo"
-			url:  "https://stefanprodan.github.io/podinfo"
-		}
-	}
-}

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

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

@@ -31,7 +31,6 @@ spec:
         - kind: Resources
           output: resources.gen.yaml
           resources: {}
-      validators: []
       transformers:
         - kind: Kustomize
           inputs:
@@ -39,7 +38,8 @@ spec:
           output: components/no-name/no-name.gen.yaml
           kustomize:
             kustomization:
+              apiVersion: kustomize.config.k8s.io/v1beta1
+              kind: Kustomization
               resources:
                 - resources.gen.yaml
-              kind: Kustomization
-              apiVersion: kustomize.config.k8s.io/v1beta1
+      validators: []

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

@@ -15,30 +15,37 @@ Package core contains schemas for a [Platform](<#Platform>) and [BuildPlan](<#Bu
 ## Index
 
 - [type Artifact](<#Artifact>)
+- [type Auth](<#Auth>)
+- [type AuthSource](<#AuthSource>)
 - [type BuildPlan](<#BuildPlan>)
 - [type BuildPlanSpec](<#BuildPlanSpec>)
 - [type Chart](<#Chart>)
 - [type Command](<#Command>)
 - [type Component](<#Component>)
+- [type ExtractYAML](<#ExtractYAML>)
 - [type File](<#File>)
 - [type FileContent](<#FileContent>)
 - [type FileContentMap](<#FileContentMap>)
 - [type FilePath](<#FilePath>)
 - [type Generator](<#Generator>)
 - [type Helm](<#Helm>)
+- [type Instance](<#Instance>)
 - [type InternalLabel](<#InternalLabel>)
 - [type Join](<#Join>)
 - [type Kind](<#Kind>)
 - [type Kustomization](<#Kustomization>)
 - [type Kustomize](<#Kustomize>)
 - [type Metadata](<#Metadata>)
+- [type OutputRef](<#OutputRef>)
 - [type Platform](<#Platform>)
 - [type PlatformSpec](<#PlatformSpec>)
 - [type Repository](<#Repository>)
 - [type Resource](<#Resource>)
 - [type Resources](<#Resources>)
+- [type TaskData](<#TaskData>)
 - [type Transformer](<#Transformer>)
 - [type Validator](<#Validator>)
+- [type ValueFile](<#ValueFile>)
 - [type Values](<#Values>)
 
 
@@ -65,6 +72,30 @@ type Artifact struct {
 }
 ```
 
+<a name="Auth"></a>
+## type Auth {#Auth}
+
+Auth represents environment variable names containing auth credentials.
+
+```go
+type Auth struct {
+    Username AuthSource `json:"username" yaml:"username"`
+    Password AuthSource `json:"password" yaml:"password"`
+}
+```
+
+<a name="AuthSource"></a>
+## type AuthSource {#AuthSource}
+
+AuthSource represents a source for the value of an [Auth](<#Auth>) field.
+
+```go
+type AuthSource struct {
+    Value   string `json:"value,omitempty" yaml:"value,omitempty"`
+    FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
+}
+```
+
 <a name="BuildPlan"></a>
 ## type BuildPlan {#BuildPlan}
 
@@ -122,11 +153,18 @@ type Chart struct {
 <a name="Command"></a>
 ## type Command {#Command}
 
-Command represents a command vetting one or more artifacts. Holos appends fully qualified input file paths to the end of the args list, then executes the command. Inputs are written into a temporary directory prior to executing the command and removed afterwards.
+Command represents a generic command for use as a Generator, Transformer, or Validator. Holos uses the Go template engine to render the Args field using data provided by the TaskData field. For example to fill in the fully qualified temporary directory used to provide inputs to the task.
 
 ```go
 type Command struct {
+    // DisplayName represents a friendly display name for the command.
+    DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty"`
+    // Args represents the complete command argument vector as a go template.
     Args []string `json:"args,omitempty" yaml:"args,omitempty"`
+    // OutputRef references the source of the output data.
+    OutputRef OutputRef `json:"outputRef,omitempty" yaml:"outputRef,omitempty"`
+    // TaskData populated by Holos for template rendering.
+    TaskData TaskData `json:"taskData,omitempty" yaml:"taskData,omitempty"`
 }
 ```
 
@@ -143,6 +181,10 @@ type Component struct {
     // Path represents the path of the component relative to the platform root.
     // Injected as the tag variable "holos_component_path".
     Path string `json:"path" yaml:"path"`
+    // Instances represents additional cue instance paths to unify with Path.
+    // Useful to unify data files into a component BuildPlan.  Added in holos
+    // 0.101.7.
+    Instances []Instance `json:"instances,omitempty" yaml:"instances,omitempty"`
     // WriteTo represents the holos render component --write-to flag.  If empty,
     // the default value for the --write-to flag is used.
     WriteTo string `json:"writeTo,omitempty" yaml:"writeTo,omitempty"`
@@ -156,11 +198,22 @@ type Component struct {
     // resulting BuildPlan.
     Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
     // Annotations represents arbitrary non-identifying metadata.  Use the
-    // `cli.holos.run/description` to customize the log message of each BuildPlan.
+    // `app.holos.run/description` to customize the log message of each BuildPlan.
     Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
 ```
 
+<a name="ExtractYAML"></a>
+## type ExtractYAML {#ExtractYAML}
+
+ExtractYAML represents a cue data instance encoded as yaml or json. If Path refers to a directory all files in the directory are extracted non\-recursively. Otherwise, path must refer to a file.
+
+```go
+type ExtractYAML struct {
+    Path string `json:"path" yaml:"path"`
+}
+```
+
 <a name="File"></a>
 ## type File {#File}
 
@@ -240,8 +293,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
@@ -253,6 +310,22 @@ type Helm struct {
 }
 ```
 
+<a name="Instance"></a>
+## type Instance {#Instance}
+
+Instance represents a data instance to unify with the configuration.
+
+Useful to unify json and yaml files with cue configuration files for integration with other tools. For example, executing holos render platform from a pull request workflow after [Kargo](<https://docs.kargo.io/>) executes the [yaml update](<https://docs.kargo.io/references/promotion-steps#yaml-update>) and [git wait for pr](<https://docs.kargo.io/references/promotion-steps#git-wait-for-pr>) promotion steps.
+
+```go
+type Instance struct {
+    // Kind is a discriminator.
+    Kind string `json:"kind" yaml:"kind" cue:"\"ExtractYAML\""`
+    // Ignored unless kind is ExtractYAML.
+    ExtractYAML ExtractYAML `json:"extractYAML,omitempty" yaml:"extractYAML,omitempty"`
+}
+```
+
 <a name="InternalLabel"></a>
 ## type InternalLabel {#InternalLabel}
 
@@ -317,12 +390,29 @@ type Metadata struct {
     // Labels represents a resource selector.
     Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
     // Annotations represents arbitrary non-identifying metadata.  For example
-    // holos uses the `cli.holos.run/description` annotation to log resources in a
+    // holos uses the `app.holos.run/description` annotation to log resources in a
     // user customized way.
     Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
 ```
 
+<a name="OutputRef"></a>
+## type OutputRef {#OutputRef}
+
+OutputRef represents a reference to the data source used as the output of a task. For example, a Generator output may be sourced from standard output or a file path.
+
+```go
+type OutputRef struct {
+    // Kind represents the kind of output produced.
+    Kind string `json:"kind,omitempty" yaml:"kind,omitempty" cue:"string | *\"Pipe\" | \"Path\""`
+    // Pipe represents stdout or stderr.  Ignored unless kind is Pipe.
+    Pipe string `json:"pipe,omitempty" yaml:"pipe,omitempty" cue:"string | *\"stdout\" | \"stderr\""`
+    // Path represents an artifact path relative to the task temp directory.
+    // Ignored unless kind is Path.
+    Path string `json:"path,omitempty" yaml:"path,omitempty"`
+}
+```
+
 <a name="Platform"></a>
 ## type Platform {#Platform}
 
@@ -365,10 +455,13 @@ type PlatformSpec struct {
 
 Repository represents a [Helm](<#Helm>) [Chart](<#Chart>) repository.
 
+The Auth field is useful to configure http basic authentication to the Helm repository. Holos gets the username and password from the environment variables represented by the Auth field.
+
 ```go
 type Repository struct {
     Name string `json:"name" yaml:"name"`
     URL  string `json:"url" yaml:"url"`
+    Auth Auth   `json:"auth,omitempty" yaml:"auth,omitempty"`
 }
 ```
 
@@ -390,6 +483,20 @@ Resources represents Kubernetes resources. Most commonly used to mix resources i
 type Resources map[Kind]map[InternalLabel]Resource
 ```
 
+<a name="TaskData"></a>
+## type TaskData {#TaskData}
+
+TaskData represents data values associated with a pipeline task necessary to execute the task. For example, the randomly generated temporary directory used to read and write artifact files when executing user defined task commands. Values of this struct are intended for the Go template engine.
+
+Holos populates this struct as needed. Holos may treat user provided values as an error condition.
+
+```go
+type TaskData struct {
+    // TempDir represents the temp directory holos manages for task artifacts.
+    TempDir string `json:"tempDir,omitempty" yaml:"tempDir,omitempty"`
+}
+```
+
 <a name="Transformer"></a>
 ## type Transformer {#Transformer}
 
@@ -397,11 +504,12 @@ Transformer combines multiple inputs from prior [Generator](<#Generator>) or [Tr
 
 1. [Kustomize](<#Kustomize>) \- Patch and transform the output from prior generators or transformers. See [Introduction to Kustomize](<https://kubectl.docs.kubernetes.io/guides/config_management/introduction/>).
 2. [Join](<#Join>) \- Concatenate multiple prior outputs into one output.
+3. \[Slice\] \- Slice an artifact into multiple artifacts using [kubectl\\\-slice](<https://github.com/patrickdappollonio/kubectl-slice>).
 
 ```go
 type Transformer struct {
     // Kind represents the kind of transformer. Must be Kustomize, or Join.
-    Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\""`
+    Kind string `json:"kind" yaml:"kind" cue:"\"Kustomize\" | \"Join\" | \"Slice\""`
     // Inputs represents the files to transform. The Output of prior Generators
     // and Transformers.
     Inputs []FilePath `json:"inputs" yaml:"inputs"`
@@ -431,6 +539,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/topics/comparison.mdx

@@ -0,0 +1,57 @@
+---
+description: Holos compared to other tools
+sidebar_label: Comparison
+slug: comparison
+sidebar_position: 40
+---
+
+{/* cspell:ignore Prodan, rollouts */}
+
+# Holos compared to other tools
+
+## Timoni
+
+Holos and Timoni both aim to solve similar problems but approach them at
+different levels of the stack.
+
+Timoni focuses on managing applications by evaluating [CUE] stored in OCI
+containers. Its creator, Stephan Prodan, envisions a controller that applies the
+resulting manifests. In this process, Timoni defers to [Flux] for managing Helm
+charts within the cluster.
+
+In contrast, Holos implements the [Rendered Manifests Pattern] and takes a
+different approach, particularly in how it handles [Helm] charts. Like
+[ArgoCD], Holos renders Helm charts into manifests using the `helm template`
+command in its rendering pipeline. Holos differs from Timoni in several important
+ways:
+
+1. **Separation of Responsibilities:**  Holos stops short of applying
+rendered manifests to a cluster, leaving that task to existing tools like
+[ArgoCD], [Flux], or even basic `kubectl apply` commands.
+
+2. **Ecosystem Integration:**  By focusing solely on rendering Kubernetes
+manifests, Holos creates space for other tools to handle deployment and
+management. For instance, Holos integrates seamlessly with [Kargo] for
+progressive rollouts, as [Kargo] operates between Holos and the Kubernetes API.
+This approach ensures that you're not locked into any specific tool and can
+choose the best solution for each task.
+
+3. **Platform Integration:** Holos focuses on integrating multiple Components
+into a larger Platform. In Holos terminology, a Component refers to a wrapper
+for [Helm] charts, [Kustomize] bases, or raw YAML files, integrated into the
+rendering pipeline through [CUE].  A Platform represents the full combination of
+these components.
+
+4. **Explicit Rendering Pipeline:** Holos emphasizes flexibility in its
+rendering pipeline. The system allows any tool that generates Kubernetes
+manifests to be wrapped in a Generator, which can then feed into existing
+transformers like [Kustomize]. This explicit separation makes Holos highly
+adaptable for different workflows.
+
+[Kargo]: https://kargo.io/
+[Flux]: https://fluxcd.io
+[Helm]: https://helm.sh
+[ArgoCD]: https://argoproj.github.io/cd/
+[Kustomize]: https://kustomize.io/
+[CUE]: https://cuelang.org/
+[Rendered Manifests Pattern]: https://akuity.io/blog/the-rendered-manifests-pattern

doc/md/topics/gitops/flux-kustomization.mdx

@@ -0,0 +1,218 @@
+---
+slug: flux-kustomization
+title: Flux Kustomization
+description: Configuring a Kustomization for each Component.
+sidebar_position: 120
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CommonComponent from '../../common/example-component.mdx';
+import CommonComponentIntegrate from '../../common/example-component-integrate.mdx';
+
+# Flux Kustomization
+
+## Overview
+
+This topic covers how to mix in a Flux Kustomization to all components.  We'll
+use the `Artifacts` field of [ComponentConfig] defined by the author schema.
+
+## The Code
+
+### Generating the structure
+
+Use `holos` to generate a minimal platform directory structure.  Start by
+creating a blank directory to hold the platform configuration.
+
+```shell
+mkdir holos-flux-kustomization && cd holos-flux-kustomization
+```
+
+```shell
+holos init platform v1alpha5
+```
+
+### Creating an example Component
+
+<CommonComponent />
+<CommonComponentIntegrate />
+
+## Adding Flux Kustomizations
+
+Configure Holos to render a [Kustomization] by defining an [Artifact] for it in
+every BuildPlan holos produces.  We're unifying our custom configuration with
+the existing `#ComponentConfig` defined in `schema.cue`.
+
+```bash
+cat <<EOF >flux-kustomization.cue
+```
+```cue showLineNumbers
+package holos
+
+import (
+	"path"
+	flux "kustomize.toolkit.fluxcd.io/kustomization/v1"
+)
+
+#ComponentConfig: {
+	Name:          _
+	OutputBaseDir: _
+
+	let ArtifactPath = path.Join([OutputBaseDir, "gitops", "\(Name).kustomization.gen.yaml"], path.Unix)
+	let ResourcesPath = path.Join(["deploy", OutputBaseDir, "components", Name], path.Unix)
+
+	Artifacts: "\(Name)-kustomization": {
+		artifact: ArtifactPath
+		generators: [{
+			kind:   "Resources"
+			output: artifact
+			resources: Kustomization: (Name): flux.#Kustomization & {
+				metadata: name:      Name
+				metadata: namespace: "default"
+				spec: {
+					interval: "5m"
+					timeout:  "1m"
+					prune:    true
+					path:     ResourcesPath
+					sourceRef: {
+						kind: "GitRepository"
+						name: "webapp"
+					}
+				}
+			}
+		}]
+	}
+}
+```
+```bash
+EOF
+```
+
+## Inspecting the BuildPlan
+
+Our customized `#ComponentConfig` results in the following `BuildPlan`.
+
+:::note
+The second artifact around line 40 contains the configured `Kustomization`
+resource.
+:::
+
+<Tabs groupId="55075C71-02E8-4222-88C0-2D52C82D18FC">
+  <TabItem value="command" label="Command">
+```bash
+holos cue export --expression holos --out=yaml ./components/podinfo
+```
+  </TabItem>
+  <TabItem value="output" label="Output">
+```yaml showLineNumbers
+kind: BuildPlan
+apiVersion: v1alpha5
+metadata:
+  name: podinfo
+spec:
+  artifacts:
+    - artifact: components/podinfo/podinfo.gen.yaml
+      generators:
+        - kind: Helm
+          output: helm.gen.yaml
+          helm:
+            chart:
+              name: podinfo
+              version: 6.6.2
+              release: podinfo
+              repository:
+                name: podinfo
+                url: https://stefanprodan.github.io/podinfo
+            values:
+              ui:
+                message: Hello World
+            enableHooks: false
+        - kind: Resources
+          output: resources.gen.yaml
+          resources: {}
+      validators: []
+      transformers:
+        - kind: Kustomize
+          inputs:
+            - helm.gen.yaml
+            - resources.gen.yaml
+          output: components/podinfo/podinfo.gen.yaml
+          kustomize:
+            kustomization:
+              resources:
+                - helm.gen.yaml
+                - resources.gen.yaml
+              kind: Kustomization
+              apiVersion: kustomize.config.k8s.io/v1beta1
+    - artifact: gitops/podinfo.kustomization.gen.yaml
+      generators:
+        - kind: Resources
+          output: gitops/podinfo.kustomization.gen.yaml
+          resources:
+            Kustomization:
+              podinfo:
+                apiVersion: kustomize.toolkit.fluxcd.io/v1
+                kind: Kustomization
+                metadata:
+                  name: podinfo
+                  namespace: default
+                spec:
+                  interval: 5m
+                  path: deploy/components/podinfo
+                  prune: true
+                  sourceRef:
+                    kind: GitRepository
+                    name: webapp
+                  timeout: 1m
+```
+  </TabItem>
+</Tabs>
+
+## Rendering manifests
+
+<Tabs groupId="E150C802-7162-4FBF-82A7-77D9ADAEE847">
+  <TabItem value="command" label="Command">
+```bash
+holos render platform
+```
+  </TabItem>
+  <TabItem value="output" label="Output">
+```
+rendered podinfo in 140.341417ms
+rendered platform in 140.441333ms
+```
+  </TabItem>
+</Tabs>
+
+## Reviewing the Kustomization
+
+The Artifact we added to `#ComponentConfig` will produce a Flux Kustomization
+resource for every component in the platform.  The output in this example is
+located at:
+
+```txt
+deploy/gitops/podinfo.kustomization.gen.yaml
+```
+```yaml showLineNumbers
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+    name: podinfo
+    namespace: default
+spec:
+    interval: 5m
+    path: deploy/components/podinfo
+    prune: true
+    sourceRef:
+        kind: GitRepository
+        name: webapp
+    timeout: 1m
+```
+
+[podinfo]: https://github.com/stefanprodan/podinfo
+[CUE Module]: https://cuelang.org/docs/reference/modules/
+[CUE Tags]: https://cuelang.org/docs/howto/inject-value-into-evaluation-using-tag-attribute/
+[Kustomization]: https://fluxcd.io/flux/components/kustomize/kustomizations/
+[Platform]: ../../api/author.md#Platform
+[ComponentConfig]: ../../api/author.md#ComponentConfig
+[Artifact]: ../../api/core.md#Artifact

doc/md/topics/kargo.mdx

@@ -0,0 +1,20 @@
+---
+description: Kargo
+slug: kargo
+sidebar_position: 110
+---
+
+# Kargo
+
+Holos pairs nicely with [Kargo], offering a holistic solution for code
+promotion across stages.
+
+Watch this space for a more detailed write up of the integration being
+developed.
+
+If you're interested in this topic, please thumbs up the [Kargo
+Topic](https://github.com/holos-run/holos/issues/378) issue, or drop into
+[Discord] and let us know about your use case.
+
+[Kargo]: https://kargo.io/
+[Discord]: https://discord.gg/JgDVbNpye7

doc/md/topics/oci-helm-charts.mdx

@@ -0,0 +1,65 @@
+---
+description: OCI Helm Charts
+slug: oci-helm-charts
+sidebar_position: 710
+---
+
+# OCI Helm Charts
+
+Holos supports OCI Helm charts.  Use the following example to get started.
+
+```bash
+mkdir -p oci-helm && cd oci-helm
+holos init platform v1alpha5
+```
+
+```bash
+mkdir -p components/podinfo-oci
+cat <<EOF > components/podinfo-oci/podinfo-oci.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Chart: {
+		name:    "oci://ghcr.io/stefanprodan/charts/podinfo"
+		release: "podinfo"
+		version: "6.6.2"
+	}
+}
+```
+```bash
+EOF
+```
+
+Register the component with the platform.
+
+```bash
+cat <<EOF >platform/podinfo-oci.cue
+```
+```cue showLineNumbers
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo-oci"
+	path: "components/podinfo-oci"
+}
+```
+```bash
+EOF
+```
+
+The OCI chart is cached in the vendor directory and rendered.
+
+```bash
+holos render platform
+```
+
+```txt
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.2
+Digest: sha256:83295d47de6d6ca634ed4b952a7572fc176bcc38854d0c11ca0fa197bc5f1154
+rendered podinfo-oci in 7.21581325s
+rendered platform in 7.216199167s
+```

doc/md/topics/private-helm.mdx

@@ -0,0 +1,183 @@
+---
+description: Private Helm Repositories
+slug: private-helm
+sidebar_position: 700
+---
+
+# Private Helm
+
+Holos supports private Helm repositories accessed with http basic authentication
+since `v0.101.4`.  Use the following command to update your author and core
+schemas to support this configuration.
+
+```bash
+holos init platform v1alpha5 --force
+```
+
+## Configuration
+
+Holos uses the Helm SDK and defers to it for authentication to private
+repositories.  Each Helm Generator supports providing http basic authentication
+credentials from environment variables.
+
+For example, the following BuildPlan causes `holos` to get the admin username
+password from the `HOLOS_TEST_PASS` environment variable.
+
+```bash
+mkdir -p projects/holos/components/private-chart
+cat <<EOF > projects/holos/components/private-chart/private-chart.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+// Test holos can access a private repository with basic auth.
+// https://github.com/holos-run/holos/issues/370
+Component: #Helm & {
+	Chart: {
+		name:    "mychart"
+		version: "0.1.0"
+		repository: {
+			name: "holos-test"
+			url:  "https://charts.holos.localhost"
+			// auth: username: fromEnv:   "HOLOS_TEST_USER"
+			auth: username: value:   "admin"
+			auth: password: fromEnv: "HOLOS_TEST_PASS"
+		}
+	}
+}
+```
+```bash
+EOF
+```
+
+## Verification
+
+Verify `holos` can access a private Helm repository by setting [ChartMuseum] up
+on a [Local Cluster].  We'll use https with basic auth to authenticate to the
+chart repository.
+
+Using the [bank of holos] repository, deploy chart museum:
+
+```bash
+holos render platform -t ChartMuseum
+```
+
+Apply the manifests:
+
+```bash
+kubectl apply --server-side=true -f deploy/clusters/workload/projects/holos/components/chart-museum
+kubectl apply --server-side=true -f deploy/clusters/workload/projects/network/components/httproutes
+```
+
+Get the admin password:
+
+```bash
+kubectl get secret -n holos chartmuseum-auth -o json \
+  | jq --exit-status -r '.data.password | @base64d'
+```
+
+Add a local repo:
+
+```bash
+helm repo add holos-test https://charts.holos.localhost --username admin
+```
+```txt
+Password:
+"holos-test" has been added to your repositories
+```
+
+:::note
+Helm by default stores this password in `~/Library/Preferences/helm/repositories.yaml`
+:::
+
+Create a chart:
+
+```bash
+helm create mychart
+```
+```txt
+Creating mychart
+```
+
+Package it up.
+
+```bash
+helm package mychart
+```
+```txt
+Successfully packaged chart and saved it to: mychart-0.1.0.tgz
+```
+
+Publish it.
+
+```bash
+curl --user "admin:$(pbpaste)" --data-binary "@mychart-0.1.0.tgz" https://charts.holos.localhost/api/charts
+```
+```json
+{"saved":true}
+```
+
+Remove all cached charts:
+
+```bash
+find . -name vendor | xargs rm -rf
+```
+
+Render the chart:
+
+```bash
+cat <<EOF > test-private-repo.cue
+```
+```cue showLineNumbers
+@if(TestPrivateRepo)
+package holos
+
+// Test holos can access a private repository with basic auth.
+// https://github.com/holos-run/holos/issues/370
+Projects: holos: #ProjectBuilder & {
+        team: "holos-authors"
+
+        namespaces: holos:            _
+        _components: "private-chart": _
+}
+```
+```bash
+EOF
+```
+
+```
+time holos render platform -t TestPrivateRepo
+```
+
+Check the chart was pulled and cached:
+
+```shell
+tree ./projects/holos/components/private-chart/vendor
+```
+```txt
+./projects/holos/components/private-chart/vendor
+└── 0.1.0
+    ├── mychart
+    │   ├── Chart.yaml
+    │   ├── mychart-0.1.0.tgz
+    │   ├── templates
+    │   │   ├── NOTES.txt
+    │   │   ├── _helpers.tpl
+    │   │   ├── deployment.yaml
+    │   │   ├── hpa.yaml
+    │   │   ├── ingress.yaml
+    │   │   ├── service.yaml
+    │   │   ├── serviceaccount.yaml
+    │   │   └── tests
+    │   │       └── test-connection.yaml
+    │   └── values.yaml
+    └── mychart-0.1.0.tgz
+
+6 directories, 11 files
+```
+
+[Local Cluster]: ./local-cluster.mdx
+[ChartMuseum]: https://chartmuseum.com/docs/
+[bank of holos]: https://github.com/holos-run/bank-of-holos

doc/md/topics/structures/environments.mdx

@@ -45,7 +45,40 @@ holos init platform v1alpha5
 
 ### Using an example Component
 
-<CommonComponent />
+Create a directory for the example `podinfo` component we'll use to render
+platform manifests.
+
+```bash
+mkdir -p components/podinfo
+```
+
+Create the CUE configuration for the example `podinfo` component.
+
+```bash
+cat <<EOF >components/podinfo/podinfo.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Chart: {
+		name:    "podinfo"
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	Values: ui: {
+		message: string | *"Hello World" @tag(message, type=string)
+	}
+}
+```
+```bash
+EOF
+```
 
 We'll integrate the component with the platform after we define the
 configuration structures.
@@ -277,6 +310,9 @@ let ProdPodinfo = {
 	parameters: EnvironmentName:       "prod-\(_city)"
 }
 ```
+```
+EOF
+```
 
 ### Using the environment
 

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.104.1

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.104.1

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 312.472625ms
+rendered platform in 312.557375ms

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.104.1

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.104.1

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 aa9749e] add blackbox configuration
+ 1 file changed, 15 insertions(+)
+ create mode 100644 config/prometheus/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,3 @@
+[main 656d4ee] integrate blackbox and prometheus together
+ 3 files changed, 1348 insertions(+), 2 deletions(-)
+ create mode 100644 components/prometheus/values.cue.orig

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 3788921] 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 129.142708ms
+rendered prometheus in 165.260375ms
+rendered platform in 165.33ms

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 654ae06] 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,3 @@
+rendered blackbox in 1.096663084s
+rendered prometheus in 1.151784875s
+rendered platform in 1.151839916s

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 9bc0126] 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.104.1

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.104.1

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
+      transformers:
+        - kind: Kustomize
+          inputs:
+            - resources.gen.yaml
+            - httpbin.yaml
+          output: components/no-name/no-name.gen.yaml
+          kustomize:
+            kustomization:
+              apiVersion: kustomize.config.k8s.io/v1beta1
+              kind: Kustomization
+              labels:
+                - includeSelectors: false
+                  pairs:
+                    app.kubernetes.io/name: httpbin
+              patches: []
+              images:
+                - name: mccutchen/go-httpbin
+              resources:
+                - resources.gen.yaml
+                - httpbin.yaml
+      validators: []

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 823e136] 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 96f5f45] annotate httpbin for prometheus probes
+ 2 files changed, 18 insertions(+)
+ create mode 100644 components/httpbin/patches.cue

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

@@ -0,0 +1 @@
+git add . && git commit -m 'annotate httpbin for prometheus probes'

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

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

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

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