Merge pull request #55 from otaviof/RHTAP-6544

Roming22 · web-flow · commit 049fbd410df5 · 2026-04-29T15:46:07.000-04:00
RHTAP-6544: Foundation &amp; Agent-Ready Documentation
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -100,7 +100,7 @@ The result is a `Topology` representing the sorted installation order. See [topo
 
 ### 3. Render Values Template
 
-The `engine.Engine` processes `values.yaml.tpl` using Go's `text/template` with:
+The `engine.Engine` processes `values.yaml.tpl` using Go's `html/template` with:
 
 - **Sprig Functions**: Full Sprig library
 - **Custom Functions**: `toYaml`, `fromYaml`, `fromYamlArray`, `toJson`, `fromJson`, `fromJsonArray`, `required`, `lookup`
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -72,6 +72,30 @@ Examples:
 - `Product A` → `Product_A`
 - `my-product` → `my_product`
 
+### The Triad
+
+Every product chart creates three linked identifiers that must stay consistent
+across config.yaml, Chart.yaml, and values.yaml.tpl:
+
+| Identifier | Source | Appears In |
+|---|---|---|
+| product name | config.yaml `name` field | Chart.yaml `product-name` annotation |
+| keyName | Sanitized product name (see [KeyName conversion](#product-name-and-keyname) above) | `.Installer.Products.<keyName>` in values.yaml.tpl |
+| root-key | Chart's values.yaml primary root attribute | values.yaml.tpl section header |
+
+The root-key is conventionally derived from the chart name (not the keyName).
+The naming style is project-level — use camelCase, snake_case, or lowercase
+consistently within a project. What matters is uniqueness across all charts:
+the framework passes the full rendered values to every chart, so each chart's
+templates access only their root key via `.Values.rootKey`.
+
+Infrastructure charts (no `product-name` annotation) are outside the triad —
+they have a root-key and a values.yaml.tpl section but no config.yaml entry.
+See [Topology: Infrastructure Charts](topology.md#infrastructure-charts--derived-products).
+
+When adding or modifying a product, update all three artifacts together:
+config.yaml, Chart.yaml annotation, and values.yaml.tpl section header.
+
 ### Namespace Resolution
 
 Products use the following namespace resolution order:
@@ -249,7 +273,7 @@ The `ApplyDefaults()` method propagates the installer namespace to products with
 
 ## Cross-References
 
-- [Topology](topology.md) — chart annotations, dependency resolution, and installation order
-- [Templating](templating.md) — values.yaml.tpl syntax and template functions
+- [Topology](topology.md) — chart annotations, dependency resolution, installation order, [infrastructure charts](topology.md#infrastructure-charts--derived-products)
+- [Templating](templating.md) — values.yaml.tpl syntax, template functions, [production patterns](templating.md#production-patterns)
 - [MCP Server](mcp.md) — configuration tools for AI-assisted workflows
 - [CLI Reference](cli-reference.md) — `config` command usage
diff --git a/docs/installer-structure.md b/docs/installer-structure.md
@@ -202,6 +202,82 @@ func NewAppFromTarball(
 3. Wrap in `ChartFS`: `chartfs.New(ofs)`
 4. Pass to `NewApp()` with all options applied
 
+## Build Pipeline
+
+The installer build process has a strict dependency: the tarball must be created before the Go binary is compiled, because `go:embed` requires the tarball file to exist at build time.
+
+### Makefile Targets
+
+| Target | Purpose | Notes |
+|---|---|---|
+| `installer-tarball` | Package installer directory into `installer.tar` | Must run before `build` |
+| `build` | Compile Go binary with version injection | Depends on `installer-tarball` |
+| `image` | Build container image | Multi-stage Containerfile |
+| `lint` | Run linters (`golangci-lint`) | Code quality checks |
+| `security` | Run security scanners (`govulncheck`) | Vulnerability detection |
+
+### Tarball-Before-Build Dependency
+
+The `installer-tarball` target must run before `go build`. The `build` target should declare this dependency explicitly:
+
+```makefile
+build: installer-tarball
+	go build -ldflags "-X main.version=$(VERSION) -X main.commitID=$(COMMIT_ID)" -o bin/my-app ./cmd
+```
+
+If `installer.tar` does not exist when `go build` runs, the `go:embed` directive in `embed.go` fails with a compilation error.
+
+### GNU tar on macOS
+
+On macOS, use GNU tar (`gtar`) instead of the system BSD tar for consistent behavior. BSD tar and GNU tar handle symlinks, permissions, and extended attributes differently. Install via `brew install gnu-tar`.
+
+### Container Image
+
+The Containerfile uses a multi-stage build:
+
+1. **Builder stage**: Compiles the Go binary with build args for `BUILD_VERSION` and `COMMIT_ID` injected via ldflags
+2. **Runtime stage**: Copies the compiled binary and required tools (`kubectl`, `oc`, `jq`) into a minimal base image
+
+Build args enable version tracking in the final image without carrying the full build toolchain.
+
+## Chart Provenance
+
+A Helmet installer is a **composition of Helm charts**. Most installers combine external charts (for products with existing Helm charts) and authored charts (for infrastructure and integration glue). The framework is chart-agnostic — it loads whatever is in the `charts/` directory.
+
+### Bringing External Charts
+
+The primary workflow for building an installer:
+
+1. **Copy** the chart directory into `charts/<name>/`
+2. **Add Helmet annotations** to `Chart.yaml` — `product-name`, `depends-on`, and integration annotations as needed
+3. **Set the root key** in `values.yaml` — conventionally derived from the chart name, must be unique across all charts
+4. **Add `__OVERWRITE_ME__` placeholders** in `values.yaml` for values that should be dynamically rendered by `values.yaml.tpl`
+5. **Wire up** a corresponding section in `values.yaml.tpl` and a product entry in `config.yaml` (if the chart maps to a product)
+
+**Helm `dependencies:` handling**: Upstream charts may use `dependencies:` in `Chart.yaml` for sub-chart resolution. The framework ignores this field for topology resolution — it reads `depends-on` annotations instead. However, Helm itself still processes `dependencies:` during install (pulling and rendering sub-charts with values merging). Only remove `dependencies:` entries when you intend to surface the sub-chart as a separate Helmet-managed topology node; otherwise, keep the upstream `dependencies:` so Helm continues to handle sub-chart rendering and values merging. Express inter-chart relationships via `depends-on` annotations regardless.
+
+### Authoring New Charts
+
+A secondary workflow for installer-specific charts that don't exist upstream:
+
+- **Namespace charts**: Create OpenShift projects, set labels and annotations
+- **Operator subscription charts**: Deploy OLM Subscriptions for operators the installer manages
+- **Integration aggregation charts**: Collect and validate integration Secrets
+- **Companion and test charts**: Validation or post-deploy checks for a product
+
+These charts are typically thin — a few templates, minimal values — and are authored from scratch. See [topology.md](topology.md#infrastructure-charts--derived-products) for infrastructure chart patterns.
+
+### Composition Model
+
+The filesystem is the composition mechanism. Copy charts into `charts/`, add annotations, wire up `config.yaml` and `values.yaml.tpl`. No catalog or registry feature is needed — the directory structure is the source of truth.
+
+A realistic installer combines both paths. Plan the composition by considering:
+
+- **Inventory**: What products does the installer deploy? Which have existing Helm charts?
+- **Gap analysis**: What infrastructure charts are needed (namespaces, operators, shared databases)?
+- **Dependency design**: How do the charts relate? What deployment order is required?
+- **Integration mapping**: Which charts provide or require integrations?
+
 ## The `instructions.md` File
 
 The optional `instructions.md` provides context to AI assistants when the installer runs as an MCP server. The MCP client (e.g., Claude Desktop, Cursor) receives this content, helping the AI understand available products, workflow phases, and tool usage.
@@ -212,7 +288,8 @@ See [mcp.md](mcp.md) for MCP server implementation details.
 
 ## Cross-References
 
-- [Configuration](configuration.md) — config.yaml schema and values rendering
-- [Topology](topology.md) — chart dependency resolution and deployment ordering
+- [Configuration](configuration.md) — config.yaml schema, values rendering, [the triad](configuration.md#the-triad)
+- [Topology](topology.md) — chart dependency resolution, deployment ordering, [infrastructure charts](topology.md#infrastructure-charts--derived-products)
+- [Templating](templating.md) — values.yaml.tpl syntax and [production patterns](templating.md#production-patterns)
 - [MCP Server](mcp.md) — Model Context Protocol server implementation
 - [Getting Started](getting-started.md) — building your first installer
diff --git a/docs/templating.md b/docs/templating.md
@@ -1,6 +1,6 @@
 # Templating
 
-The framework uses Go's `text/template` engine to render `values.yaml.tpl` into Helm values before chart installation. This enables dynamic value generation based on installer configuration, cluster introspection, and live Kubernetes resources.
+The framework uses Go's `html/template` engine to render `values.yaml.tpl` into Helm values before chart installation. This enables dynamic value generation based on installer configuration, cluster introspection, and live Kubernetes resources.
 
 This page covers the template context structure, available functions, rendering lifecycle, and common patterns. For configuration schema and ConfigMap storage, see [configuration.md](configuration.md). For installer directory layout and `values.yaml.tpl` placement, see [installer-structure.md](installer-structure.md).
 
@@ -310,11 +310,136 @@ foundation:
 {{- end }}
 ```
 
+## Production Patterns
+
+The patterns above show individual template features in isolation. This section covers how to structure a multi-product `values.yaml.tpl` at production scale — preambles, derived variables, YAML anchors, and cross-product logic.
+
+### Preamble Structure
+
+Production templates start with a preamble that extracts products and cluster state using `required()`, then derives shared variables:
+
+```yaml
+---
+{{- $productA := required "Product_A" .Installer.Products.Product_A -}}
+{{- $productB := required "Product_B" .Installer.Products.Product_B -}}
+{{- $domain := required "OpenShift domain" .OpenShift.Ingress.Domain -}}
+{{- $routerCA := required "OpenShift router CA" .OpenShift.Ingress.RouterCA -}}
+
+{{- $crc := dig "crc" false .Installer.Settings -}}
+{{- $protocol := "https" -}}
+{{- if $crc }}{{ $protocol = "http" }}{{ end -}}
+
+{{- $keycloakEnabled := or $productA.Enabled $productB.Enabled -}}
+```
+
+Use `required()` for values that must exist — template rendering fails early with a descriptive error instead of producing broken YAML.
+
+### Mid-File Variables
+
+Not all variables belong in the preamble. Variables scoped to a single section can be defined immediately before that section:
+
+```yaml
+{{- $databaseSecretName := dig "databaseSecret" "my-db-secret" $productA.Properties -}}
+
+#
+# product-a
+#
+productA:
+  database:
+    secretName: {{ $databaseSecretName }}
+```
+
+This is a pragmatic alternative to a monolithic preamble — variables stay near their usage, making maintenance easier.
+
+### Section Structure
+
+Each chart gets a comment block and root-key section. Fields are rendered from preamble or section-local variables:
+
+```yaml
+#
+# chart-name
+#
+rootKey:
+  enabled: {{ $productA.Enabled }}
+  namespace: {{ $productA.Namespace }}
+  url: {{ $protocol }}://app.{{ $domain }}
+```
+
+### YAML Anchors
+
+Use YAML anchors (`&name` / `*name`) for shared configuration blocks — database credentials, OIDC settings, ingress config. Anchors also bridge values across root keys for multi-component charts:
+
+```yaml
+trustedProfileAnalyzer:
+  database: &tpaDatabase
+    name:
+      valueFrom:
+        secretKeyRef:
+          name: {{ $databaseSecretName }}
+          key: dbname
+  createDatabase: *tpaDatabase
+  migrateDatabase: *tpaDatabase
+  storage: &tpaStorage
+    type: filesystem
+    size: 32Gi
+  oidc: &tpaOIDC
+    issuerUrl: {{ $oidcIssuerURL }}
+
+trustification:
+  storage: *tpaStorage
+  oidc: *tpaOIDC
+```
+
+Companion charts can inherit their parent's entire configuration via anchors (e.g., `acsTest: *acs`).
+
+### URL Composition
+
+Always compose URLs from `$protocol` + `$domain`. Never hardcode protocol or domain:
+
+```yaml
+appUrl: {{ $protocol }}://app.{{ $domain }}
+```
+
+This ensures CRC/development-mode toggles and domain changes propagate everywhere.
+
+### Cross-Product Conditionals
+
+Extract composite booleans to named variables instead of writing inline logic:
+
+```yaml
+{{- $keycloakEnabled := or $tpa.Enabled $tas.Enabled (and $rhdh.Enabled (eq $authProvider "oidc")) -}}
+```
+
+Use `and`/`or` (variadic Sprig functions), not `&&`/`||`.
+
+### Core Sprig Subset
+
+The following functions cover the vast majority of production templates: `required`, `dig`, `default`, `printf`, `indent`, `toYaml`, `and`, `or`, `not`, `eq`, `list`, `range`. Start with these and add others only when the pattern demands it. The full Sprig library is available — see [Sprig documentation](https://masterminds.github.io/sprig/) for edge cases.
+
+## Anti-Patterns
+
+Common mistakes to avoid in `values.yaml.tpl` authoring:
+
+| Anti-Pattern | Why It Breaks | Fix |
+|---|---|---|
+| Hardcoded URLs | Breaks CRC/dev mode, ignores domain config | Compose from `$protocol` + `$domain` |
+| Duplicated values across sections | Drift between copies, maintenance burden | Derive once in preamble or section-local variable |
+| Inline boolean logic | Unreadable, error-prone in complex cases | Extract to named variables (e.g., `$keycloakEnabled`) |
+| Missing `required()` for mandatory paths | Silent nil renders as `<nil>` in YAML | Wrap product and cluster extractions with `required()` |
+| Unfulfilled `__OVERWRITE_ME__` placeholders | Chart receives placeholder string at deploy time | Every placeholder in values.yaml must have a corresponding template expression |
+| `nindent` not last in pipeline | Indentation applied before serialization | Always: `toYaml \| nindent N` (serialization before indentation) |
+| `index` instead of `dig` | Errors or returns zero value on missing intermediate keys; no default value support | Use `dig` with a default value for safe deep access |
+| Unintentional multiple root keys | Chart receives values from wrong root | One primary root key per chart; secondary keys only for sub-components or debug flags |
+
+### Engine Caveat
+
+Helmet uses `html/template` (not `text/template`). HTML entities (`<`, `>`, `&`) are auto-escaped in all pipeline output — including strings returned by `toYaml` and `toJson`. In practice, this only affects values containing `<`, `>`, or `&` literals; most Kubernetes configuration values do not include these characters.
+
 ## Scope Boundaries
 
 This document covers template rendering mechanics and the `values.yaml.tpl` syntax. Related topics:
 
-- **Configuration schema**: See [configuration.md](configuration.md) for `config.yaml` structure, product specifications, and ConfigMap persistence
+- **Configuration schema**: See [configuration.md](configuration.md) for `config.yaml` structure, product specifications, [the triad](configuration.md#the-triad), and ConfigMap persistence
 - **Installer packaging**: See [installer-structure.md](installer-structure.md) for directory layout, embedding, and the overlay filesystem
-- **Dependency resolution**: See [topology.md](topology.md) for chart ordering and annotation-based dependencies
+- **Dependency resolution**: See [topology.md](topology.md) for chart ordering, annotation-based dependencies, and [companion chart patterns](topology.md#companion-charts--multi-root-key-patterns)
 - **OpenShift introspection**: Implemented in `internal/k8s/openshift.go`
diff --git a/docs/topology.md b/docs/topology.md
diff --git a/internal/resolver/topology_weight_test.go b/internal/resolver/topology_weight_test.go
