docs: make update-docs for version 0.103.0

* Convert all files with.period.separators to hyphen-separators.
* Rename and markdown_test.go to be specific to Helm Values.
* Move helm-values_test.go to be in the same directory as the Helm Values doc.
* Move Blackbox common configuration CUE file to `config/prometheus` so it can be imported as necessary.
* Use explicit import statements for Blackbox common config in `blackbox` and `prometheus` components.

Closes: #399

Makefile

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

api/author/v1alpha5/definitions.go

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

api/core/v1alpha5/types.go

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

doc/md/api/author.md

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

doc/md/api/core.md

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

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

@@ -4,4 +4,4 @@ cmp stdout $WORK/output.txt
 -- command.sh --
 holos --version
 -- output.txt --
-0.102.5
+0.103.0

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

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

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

@@ -1,2 +1,3 @@
-[main 4221803] integrate blackbox and prometheus together
- 2 files changed, 4 insertions(+), 2 deletions(-)
+[main 668706a] 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/import-values-git-output.txt

@@ -1,4 +1,4 @@
-[main 52e90ea] import values
+[main 7bc6772] 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

@@ -1,3 +1,3 @@
-rendered blackbox in 365.936792ms
-rendered prometheus in 371.855875ms
-rendered platform in 372.109916ms
+rendered blackbox in 146.654292ms
+rendered prometheus in 178.845292ms
+rendered platform in 178.9115ms

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

@@ -1,4 +1,4 @@
-[main b5df111] add blackbox and prometheus
+[main d144f24] add blackbox and prometheus
  5 files changed, 1550 insertions(+)
  create mode 100644 components/blackbox/blackbox.cue
  create mode 100644 components/prometheus/prometheus.cue

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

@@ -1,5 +1,3 @@
-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
+rendered blackbox in 1.794799666s
+rendered prometheus in 1.835097625s
+rendered platform in 1.835185792s

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

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

doc/website/static/_redirects

@@ -22,8 +22,12 @@
 /docs/comparison/    /docs/v1alpha5/topics/comparison/ 301
 /docs/support        /docs/v1alpha5/tutorial/overview/#getting-help 301
 /docs/support/       /docs/v1alpha5/tutorial/overview/#getting-help 301
+/docs/api/core       /docs/v1alpha5/api/core/ 301
+/docs/api/core/      /docs/v1alpha5/api/core/ 301
 /docs/api/author     /docs/v1alpha5/api/author/ 301
 /docs/api/author/    /docs/v1alpha5/api/author/ 301
 # Redirect to our own take on the pattern once we figure out what to call it.
 # See: https://discord.com/channels/1299051862418395216/1299055980738383882/1327347525354524805
 /blog/the-rendered-manifests-pattern https://akuity.io/blog/the-rendered-manifests-pattern 301
+# without the s which I always forget
+/blog/the-rendered-manifest-pattern  https://akuity.io/blog/the-rendered-manifests-pattern 301

internal/builder/v1alpha5/builder.go

@@ -219,13 +219,38 @@ func (t generatorTask) helm(ctx context.Context) error {
 		}
 	}
 
-	// Write values file
+	// Write value files
 	tempDir, err := os.MkdirTemp("", "holos.helm")
 	if err != nil {
 		return errors.Format("could not make temp dir: %w", err)
 	}
 	defer util.Remove(ctx, tempDir)
 
+	// valueFiles represents the ordered list of value files to pass to helm
+	// template -f
+	var valueFiles []string
+
+	// valueFiles for the use case of migration from helm value hierarchies.
+	for _, valueFile := range t.generator.Helm.ValueFiles {
+		var data []byte
+		switch valueFile.Kind {
+		case "Values":
+			if data, err = yaml.Marshal(valueFile.Values); err != nil {
+				return errors.Format("could not marshal value file %s: %w", valueFile.Name, err)
+			}
+		default:
+			return errors.Format("could not marshal value file %s: unknown kind %s", valueFile.Name, valueFile.Kind)
+		}
+
+		valuesPath := filepath.Join(tempDir, valueFile.Name)
+		if err := os.WriteFile(valuesPath, data, 0666); err != nil {
+			return errors.Wrap(fmt.Errorf("could not write value file %s: %w", valueFile.Name, err))
+		}
+		log.DebugContext(ctx, fmt.Sprintf("wrote: %s", valuesPath))
+		valueFiles = append(valueFiles, valuesPath)
+	}
+
+	// The final values files
 	data, err := yaml.Marshal(t.generator.Helm.Values)
 	if err != nil {
 		return errors.Format("could not marshal values: %w", err)
@@ -235,7 +260,8 @@ func (t generatorTask) helm(ctx context.Context) error {
 	if err := os.WriteFile(valuesPath, data, 0666); err != nil {
 		return errors.Wrap(fmt.Errorf("could not write values: %w", err))
 	}
-	log.DebugContext(ctx, "wrote"+valuesPath)
+	log.DebugContext(ctx, fmt.Sprintf("wrote: %s", valuesPath))
+	valueFiles = append(valueFiles, valuesPath)
 
 	// Run charts
 	args := []string{"template"}
@@ -248,9 +274,11 @@ func (t generatorTask) helm(ctx context.Context) error {
 	if kubeVersion := t.generator.Helm.KubeVersion; kubeVersion != "" {
 		args = append(args, "--kube-version", kubeVersion)
 	}
+	args = append(args, "--include-crds")
+	for _, valueFilePath := range valueFiles {
+		args = append(args, "--values", valueFilePath)
+	}
 	args = append(args,
-		"--include-crds",
-		"--values", valuesPath,
 		"--namespace", t.generator.Helm.Namespace,
 		"--kubeconfig", "/dev/null",
 		"--version", t.generator.Helm.Chart.Version,

internal/generate/platforms/cue.mod/gen/github.com/holos-run/holos/api/author/v1alpha5/definitions_go_gen.cue

@@ -95,6 +95,10 @@ import "github.com/holos-run/holos/api/core/v1alpha5:core"
 	// 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] @go(,[]core.ValueFile)
+
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	EnableHooks: bool & (true | *false)
 

internal/generate/platforms/cue.mod/gen/github.com/holos-run/holos/api/core/v1alpha5/types_go_gen.cue

@@ -129,9 +129,14 @@ package core
 	chart: #Chart @go(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 @go(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] @go(ValueFiles,[]ValueFile)
+
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	enableHooks?: bool @go(EnableHooks)
 
@@ -145,6 +150,19 @@ package core
 	kubeVersion?: string @go(KubeVersion)
 }
 
+// ValueFile represents one Helm value file produced from CUE.
+#ValueFile: {
+	// Name represents the file name, e.g. "region-values.yaml"
+	name: string @go(Name)
+
+	// Kind is a discriminator.
+	kind: string & "Values" @go(Kind)
+
+	// Values represents values for holos to marshal into the file name specified
+	// by Name when rendering the chart.
+	values?: #Values @go(Values)
+}
+
 // Values represents [Helm] Chart values generated from CUE.
 #Values: {...}
 

internal/generate/platforms/cue.mod/pkg/github.com/holos-run/holos/api/author/v1alpha5/definitions.cue

@@ -95,6 +95,7 @@ import (
 		release: string | *name
 	}
 	Values:       _
+	ValueFiles?:  _
 	EnableHooks:  _
 	Namespace?:   _
 	APIVersions?: _
@@ -110,8 +111,11 @@ import (
 					kind:   "Helm"
 					output: HelmOutput
 					helm: core.#Helm & {
-						chart:       Chart
-						values:      Values
+						chart:  Chart
+						values: Values
+						if ValueFiles != _|_ {
+							valueFiles: ValueFiles
+						}
 						enableHooks: EnableHooks
 						if Namespace != _|_ {
 							namespace: Namespace

version/embedded/minor

@@ -1 +1 @@
-102
+103

version/embedded/patch

@@ -1 +1 @@
-5
+0