diff --git a/.helmdocsignore b/.helmdocsignore index 9f8d550..e69de29 100644 --- a/.helmdocsignore +++ b/.helmdocsignore @@ -1 +0,0 @@ -deprecated diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9650817..ad02efa 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -45,3 +45,4 @@ repos: - id: helm-docs args: - --template-files=./_README.md.gotmpl + - --template-files=README.md.gotmpl diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..007d7f0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,251 @@ +# Contributing to helm-charts + +This document covers the standards and workflows that apply to all contributors. Whether you are fixing a bug, adding a feature, or introducing a new chart, the guidance here applies. + +For environment setup and available `make` targets, see the [README](README.md). + +--- + +## Contribution workflow + +The typical loop for any change: + +1. Make your changes. +2. Write or update unit tests to cover them. +3. Run `make update-dependencies && make unit-tests` to verify everything passes. +4. Stage your changes, then run `make bump-charts` to increment the version of any chart you touched. +5. Commit. Pre-commit hooks will verify versions and regenerate READMEs. + +--- + +## Version bumps + +Every change to a chart, including changes to its library dependencies, requires a version bump in that chart's `Chart.yaml`. The pre-commit hook will catch missing bumps, and `make bump-charts` will apply them automatically for staged files. + +When a library chart changes, bump the library chart's version **and** bump every application chart that depends on it, then update the dependency version reference in those dependent charts' `Chart.yaml` files. + +--- + +## Pre-commit hooks + +Running `make install` sets up pre-commit hooks that will: +- Verify chart versions have been bumped for any modified chart +- Regenerate `README.md` files via helm-docs + +If a hook fails, address the reported issue before committing. Do not skip hooks. + +--- + +## Unit tests + +Every addition or change to a chart must be covered by a unit test. Tests are written using [helm-unittest](https://github.com/helm-unittest/helm-unittest) and live in each chart's `tests/` directory. The `mozcloud/application` chart has the most comprehensive test suite in this repo and is the best reference for examples and conventions. For a full reference of available test syntax and assertion types, see the [helm-unittest documentation](https://github.com/helm-unittest/helm-unittest/blob/main/DOCUMENT.md). + +### Test file anatomy + +Each test file is a YAML document with the following top-level fields: + +```yaml +suite: "mozcloud: Descriptive suite name" +release: + name: mozcloud-test + namespace: mozcloud-test-dev +chart: + version: 1.0.0 # Pin to a fixed version to prevent snapshot churn on every chart bump +values: + - values/globals.yaml # Shared baseline values required by all tests + - values/my-scenario.yaml # Scenario-specific values for this suite +templates: + - workload/deployment.yaml # Limit rendering to only the templates under test + - workload/hpa.yaml +tests: + - it: Ensure no failures occur + asserts: + - notFailedTemplate: {} + - it: Configuration matches entire snapshot + asserts: + - matchSnapshot: {} + - it: Deployment has correct replica settings + template: workload/deployment.yaml + documentSelector: + path: $[?(@.kind == "Deployment")].metadata.name + value: my-workload + asserts: + - equal: + path: spec.replicas + value: 2 +``` + +Conventions to follow: + +- **Pin `chart.version` to `1.0.0`.** The labels library embeds the chart version in resource labels, so leaving it unpinned causes every snapshot to change on every chart bump, adding noise to PR diffs that is unrelated to the change being reviewed. +- **Always include `notFailedTemplate` as the first test in every suite.** This catches render errors before any other assertions run. +- **Always include `matchSnapshot`.** See [Snapshots](#snapshots) below. +- **Scope your `templates` list to only the templates relevant to the scenario.** Rendering every template in every suite adds noise and slows tests down. + +### Values organization + +Shared values that every test suite needs (e.g. global platform values the chart requires) live in `tests/values/globals.yaml`. Scenario-specific values live in separate named files: + +``` +tests/ + values/ + globals.yaml # Required by all suites + basic-configuration.yaml # Values for the basic workload test suite + multi-containers.yaml # Values for the multi-container test suite + ... + basic-workload-configuration_test.yaml + multi-containers_test.yaml + ... + __snapshot__/ # Auto-generated; do not edit by hand +``` + +Each scenario-specific values file should contain only the values that make that scenario distinct. Share as little as possible between scenarios so that test failures are easy to localize. + +### Assertions + +helm-unittest provides a range of assertion types. The most commonly used in this repo are listed below. For the full reference, see the [helm-unittest documentation](https://github.com/helm-unittest/helm-unittest/blob/main/DOCUMENT.md). + +| Assertion | What it checks | +|---|---| +| `notFailedTemplate` | Template renders without error | +| `failedTemplate` + `errorPattern` | Template fails with a specific error message | +| `matchSnapshot` | Full rendered output matches saved snapshot | +| `hasDocuments` | Number of rendered documents | +| `equal` | Exact value at a JSONPath | +| `isSubset` | Object at a JSONPath contains the expected keys (partial match) | +| `contains` | List at a JSONPath contains the expected element | +| `lengthEqual` | List at a JSONPath has the expected length | +| `exists` / `isNotNullOrEmpty` | Field is present and non-empty | + +Use `documentSelector` to target a specific document when a template renders multiple resources: + +```yaml +documentSelector: + path: $[?(@.kind == "Deployment")].metadata.name + value: my-workload +``` + +Use the inline `set` field to override a specific value for a single test case without creating a separate values file: + +```yaml +- it: Schema rejects invalid enum value + template: workload/deployment.yaml + set: + workloads.my-workload.type: invalid-type + asserts: + - failedTemplate: + errorPattern: "invalid-type" +``` + +### Snapshots + +Snapshots are the primary safety net for catching unintended changes. When tests run, helm-unittest renders the templates and compares the output against the saved snapshot files in `tests/__snapshot__/`. If the output differs from what was saved, the test fails. + +**A snapshot should only change when you intend to change the template output.** If you make a change that is not supposed to affect rendered manifests and a snapshot diff appears, treat that as a bug signal and investigate before proceeding. Do not update snapshots just to make the test pass without understanding why the output changed. + +Snapshot diffs appear in PR diffs and should be reviewed with the same care as code changes. Reviewers should verify that every line in a snapshot diff is a deliberate consequence of the change being made. + +When your change intentionally modifies rendered output, update snapshots explicitly: + +```sh +make unit-tests UPDATE_SNAPSHOTS=1 +``` + +Commit the updated snapshot files alongside your change so reviewers can see exactly what shifted. + +### Running tests + +Before opening a PR, run the full suite: + +```sh +make update-dependencies && make unit-tests +``` + +For a faster feedback loop while iterating on a specific chart: + +```sh +make unit-tests-affected +``` + +--- + +## JSON schema validation + +Every application chart ships a `values.schema.json` that Helm validates against when rendering the chart. **Any addition, removal, or rename of a key in `values.yaml` must be reflected in `values.schema.json`.** + +Letting the two files drift causes one of two problems: unrecognized keys silently pass through without validation, or valid keys are rejected with confusing errors. The schema also surfaces documentation in editor tooling (e.g. the VS Code YAML extension), so keeping it accurate and well-described benefits every team using the chart. + +### Schema conventions + +All application chart schemas in this repo target [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/schema) and follow these conventions: + +- **`additionalProperties: false`** is set on every object whose shape is fully known. This turns typos and unrecognized keys into hard errors rather than silent no-ops, which is one of the most effective ways to catch misconfiguration early. + +- **`$defs`** are used for schema fragments that appear in more than one place. Add a new `$def` whenever a type is referenced from two or more locations and reference it with `$ref: "#/$defs/"`. Do not copy-paste the same shape inline. + +- **`description`** fields are strongly encouraged on every user-facing property. Write descriptions as full sentences. + +- **`enum`** is used to constrain string fields to a known set of values wherever applicable. When adding a new string field that only accepts specific values, use `enum` rather than leaving the type open. + +- **`required`** lists the fields that must be present for a resource to be valid. Do not mark optional fields as required just because they have defaults. Rely on `default` for those instead. + +- **`default`** values in the schema should match the defaults in `values.yaml`. If they diverge, the schema governs validation but `values.yaml` governs rendering. Keep them in sync. + +### What to do when changing values + +| Change type | Schema action required | +|---|---| +| Add a new key | Add a matching property with type, description, and (if applicable) default | +| Remove a key | Remove its property from the schema (and from any `required` arrays) | +| Rename a key | Remove the old property, add the new one | +| Restrict a string to specific values | Add or update an `enum` constraint | +| Add a new collection type | Add an `additionalProperties` entry with the item shape (or a `$ref`) | +| Extract a repeated shape | Move it into `$defs` and replace inline copies with `$ref` | + +--- + +## General chart authoring standards + +The following standards apply to all charts in this repository. + +### Variable naming + +Local variables inside templates and helper functions must use `$camelCase`. + +### Type fidelity: prefer explicit keys over `toYaml` + +Avoid rendering entire config blocks with `{{ $variable | toYaml | nindent N }}` unless you specifically intend to pass an opaque blob. Prefer explicit key rendering: + +```yaml +# Preferred +resources: + cpu: {{ $container.resources.cpu }} + memory: {{ $container.resources.memory }} + +# Avoid (unless you have a good reason) +resources: {{ $container.resources | toYaml | nindent 2 }} +``` + +`toYaml` converts all values to strings, which can silently clobber typed values (integers, booleans). Explicit rendering preserves types and makes the schema contract visible in the template itself. + +The same principle applies to round-tripping through strings: avoid `toYaml` / `fromYaml` conversions unless you specifically need string serialization. + +### Collections: dicts over lists + +Collections that users configure should be defined as **dicts keyed by name**, not lists, wherever merging behavior matters. + +Helm can deep-merge dicts across values files (e.g. `values.yaml` + `values-prod.yaml`), but it replaces lists wholesale. Using dicts allows users to define a base configuration in `values.yaml` and selectively override individual items in environment-specific files without repeating the entire definition. + +#### Protected default keys + +Charts that use dict-based collections can designate a **protected key** per collection type to act as a chart-level defaults template. The key is stripped from the rendered output and its values are deep-merged as a base under each user-defined entry, with user values taking precedence. + +For example, the `mozcloud` chart defines `mozcloud-workload` as the protected key for the `workloads` collection and `mozcloud-container` for the `containers` collection. A user who defines a workload named `my-service` will automatically inherit all defaults from the `mozcloud-workload` entry without having to repeat them. The `mozcloud-gateway` chart similarly uses `mozcloud-gateway` as the protected key for the `gateway.gateways`, `httpRoute.httpRoutes`, and `backends` collections. + +Avoid naming your objects after a chart's protected keys, as those entries are treated as defaults rather than real objects (unless they are the only entry in the collection). The full list of protected keys for each application chart can be found in that chart's `README.md`, as applicable. + +--- + +## README generation + +`README.md` files for charts are generated by `helm-docs` and must not be edited by hand. Changes will be overwritten. To update a chart's README, edit its `README.md.gotmpl` file, or create one in the chart directory to override the root `_README.md.gotmpl`. READMEs are regenerated automatically by the pre-commit hook. diff --git a/README.md b/README.md index afc3536..d1e4bf8 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,200 @@ # helm-charts -Reusable Helm templates for Kubernetes workloads + +Helm charts for the MozCloud Internal Developer Platform (IDP). + +These charts are the primary mechanism by which application teams deploy workloads onto MozCloud Kubernetes clusters. Charts are rendered by Argo CD and applied as Kubernetes manifests. Teams do not interact with Helm directly. Instead, they define a tenant chart that declares this library as a dependency and configure their workloads through values files. + +--- + +## Chart overview + +Charts in this repository fall into two categories: **application charts** and **library charts**. + +### Application charts vs. library charts + +**Application charts** produce Kubernetes manifests. They are what tenant charts declare as dependencies and what Argo CD renders. Each application chart ships a `values.yaml` (with documented defaults), a `values.schema.json` (for validation), and a `README.md` (generated by helm-docs). + +**Library charts** (`type: library`) contain only named template definitions. They produce no manifests on their own and cannot be deployed directly. They exist to share reusable logic across application charts. A library chart is always consumed as a dependency of an application chart. + +### Chart map + +``` +mozcloud/ +└── application # Primary entry point for most users. Deploys workloads, + # jobs, cron jobs, config maps, external secrets, ingress, + # gateway routes, service accounts, PVCs, and more. + # Depends on mozcloud-gateway-lib, mozcloud-ingress-lib, + # and mozcloud-labels-lib. + +mozcloud-gateway/ +├── application # Standalone chart for teams that need to manage gateway +│ # resources independently of workloads. +└── library # (mozcloud-gateway-lib) Shared gateway templates consumed + # by mozcloud/application. + +mozcloud-ingress/ +├── application # Standalone chart for teams that need to manage ingress +│ # resources independently of workloads. +└── library # (mozcloud-ingress-lib) Shared ingress templates consumed + # by mozcloud/application. + +mozcloud-labels/ +└── library # (mozcloud-labels-lib) Standardized label definitions + # shared across all application charts. + +mozcloud-opentelemetry/ +└── application # Manages OpenTelemetry signals (instrumentation, collectors) + # for MozCloud workloads. + +mozcloud-service/ +└── library # (mozcloud-service-lib) Shared Kubernetes Service templates. + +mozcloud-fastly-ips/ +└── library # (mozcloud-fastly-ips-lib) Fastly origin IP ranges, used + # to restrict ingress traffic to Fastly CDN egress addresses. + +deprecated/ # Superseded charts. Do not use. Excluded from all tooling. +``` + +**Most users should start with `mozcloud/application`.** The specialized application charts (`mozcloud-gateway`, `mozcloud-ingress`, `mozcloud-opentelemetry`) exist for teams with requirements that fall outside the scope of the primary chart. + +--- + +## Using these charts + +Charts are distributed as [OCI artifacts](https://helm.sh/docs/topics/registries/) on Google Artifact Registry: + +``` +oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts +``` + +To use a chart, declare it as a dependency in your tenant chart: + +```yaml +# Chart.yaml +apiVersion: v2 +name: my-tenant-chart +version: 0.1.0 +type: application +dependencies: + - name: mozcloud + version: ~0.13.2 + repository: oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts +``` + +Each application chart ships a verbose `values.yaml` and a `values.schema.json`. These are the primary reference for understanding what a chart accepts. Start there before consulting any other documentation. + +New chart versions are published automatically via GitHub Actions when changes are merged. A corresponding [tag](https://github.com/mozilla/helm-charts/tags) is added to this repository for each release. Use the tags to browse chart code at a specific version. + +--- ## Requirements + ### `uv` -Development workflows require [`uv`](https://docs.astral.sh/uv/) +Development workflows are driven by [`uv`](https://docs.astral.sh/uv/). Install it before anything else. ### `pre-commit` -We use pre-commit to provide a useful signal that versions need to be bumped +Pre-commit hooks enforce version bumps and regenerate READMEs via helm-docs. Install with: ```sh uv tool install pre-commit ``` ### `helm` -[Helm](https://helm.sh/docs/intro/install/) must be installed for unit tests to run +[Helm](https://helm.sh/docs/intro/install/) is required to run unit tests and render charts locally. + +### `helm-docs` +`helm-docs` generates `README.md` files from `.gotmpl` templates. Required during pre-commit runs. +- macOS: `brew install norwoodj/tap/helm-docs` +- Other platforms: https://github.com/norwoodj/helm-docs -### helm-docs -`helm-docs` is required during pre-commit runs, installation methods vary by OS: -- MacOS: `brew install norwoodj/tap/helm-docs` -- Additional info available in repo: https://github.com/norwoodj/helm-docs +### `kubeconform` _(optional)_ +[`kubeconform`](https://github.com/yannh/kubeconform) validates rendered manifests against Kubernetes and GKE CRD schemas. Required only if running `make kubeconform`. + +--- ## Setup -Run `make install` to ensure `uv`, `pre-commit`, and `helm` are installed. -Additionally, this will install/update the `unittest` Helm plugin. +Run `make install` to configure pre-commit hooks and install/update the `helm unittest` plugin: + +```sh +make install +``` + +This assumes `uv`, `pre-commit`, and `helm` are already installed. + +--- -## Development Helpers +## Development helpers ### `make update-dependencies` -Update the helm dependencies of all the charts. Does a depth first travels of the depenency tree to update all chart dependencies. Can be dry-run by setting `DRY_RUN=1` +Updates Helm dependencies for all charts, performing a depth-first traversal of the dependency tree. Use `DRY_RUN=1` to preview what would change without modifying anything: ```sh +make update-dependencies make update-dependencies DRY_RUN=1 ``` -### `make bump-charts` -By default it will bump the chart versions of the charts that are staged to be committed. This works well in tandem with the `pre-commit` hook that checks if charts need a version bump. It is also possible to pass individual chart names to the make target. -Default: +### `make unit-tests` +Runs the full unit test suite across all application charts. If chart dependencies are missing, they are updated automatically before tests run. ```sh -make bump-charts +make unit-tests ``` -With arguments: + +To run tests and update snapshots (required when template output changes intentionally): ```sh -make bump-charts mozcloud-preview-lib +make unit-tests UPDATE_SNAPSHOTS=1 ``` -### `make unit-tests` -This will run the unit tests for all application charts. Run `make install` if the `unittest` Helm plugin is not installed. +### `make unit-tests-affected` +Runs unit tests only for charts that have staged changes, plus any charts that depend on them. Useful for a faster feedback loop during development without running the full suite: +```sh +make unit-tests-affected +make unit-tests-affected UPDATE_SNAPSHOTS=1 +``` -Run unit tests: +### `make bump-charts` +Bumps the version of charts that are staged for commit. Works in tandem with the pre-commit hook that checks whether a version bump is needed. Can also target specific charts by name: ```sh -make unit-tests +make bump-charts +make bump-charts mozcloud-gateway-lib +``` + +### `make kubeconform` +Validates rendered test snapshot manifests against upstream Kubernetes and GKE CRD schemas. Useful for catching API version drift or schema regressions: +```sh +make kubeconform ``` -Run unit tests and update snapshots: +### `make clean` +Removes all downloaded chart dependency directories (`charts/`): ```sh -make unit-tests UPDATE_SNAPSHOTS=1 # The following all translate as "true": 1, true, yes +make clean ``` + +--- + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflows, unit testing standards, JSON schema conventions, and general chart authoring standards. + +### Unit tests + +Tests live in each chart's `tests/` directory and are written using [helm-unittest](https://github.com/helm-unittest/helm-unittest). They generally fall into three categories: + +- **Scenario tests** verify that a given set of values renders the expected resources. Each scenario has its own values file under `tests/values/` and a corresponding `_test.yaml` file. Scenarios cover things like basic workload configuration, multiple containers, ingress and gateway setups, security contexts, preview environments, and so on. +- **Snapshot tests** capture the full rendered output of a scenario and store it in `tests/__snapshot__/`. They serve as a regression baseline: if a change unexpectedly alters rendered output, the snapshot diff surfaces it. +- **Schema validation tests** verify that the JSON schema correctly rejects invalid input by asserting that specific bad values cause a render failure. + +Every change to a chart should be accompanied by a test. See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions on how to write them. + +--- + +## Documentation + +- [MozCloud IDP documentation](https://mozilla-hub.atlassian.net/wiki/spaces/MOZCLOUD) +- [Helm documentation](https://helm.sh/docs/) +- [Helm chart best practices](https://helm.sh/docs/chart_best_practices/) +- [JSON Schema (draft 2020-12)](https://json-schema.org/draft/2020-12/schema) +- [helm-docs](https://github.com/norwoodj/helm-docs) +- [helm-unittest](https://github.com/helm-unittest/helm-unittest) +- [helm-unittest documentation](https://github.com/helm-unittest/helm-unittest/blob/main/DOCUMENT.md) +- [kubeconform](https://github.com/yannh/kubeconform) diff --git a/_README.md.gotmpl b/_README.md.gotmpl index 0878331..a36caa9 100644 --- a/_README.md.gotmpl +++ b/_README.md.gotmpl @@ -1,20 +1,10 @@ +{{- /* + mozcloud.readme.preamble + Renders everything from the chart header through the values section. + Called by mozcloud.readme and by application charts with custom Contributing sections. +*/ -}} +{{- define "mozcloud.readme.preamble" -}} {{ template "chart.header" . }} -{{- $deprecatedCharts := list - "mozcloud-job" - "mozcloud-job-lib" - "mozcloud-preview" - "mozcloud-preview-lib" - "mozcloud-workload" - "mozcloud-workload-core-lib" - "mozcloud-workload-stateless" - "mozcloud-workload-stateless-lib" -}} -{{- if and .Deprecated (has .Name $deprecatedCharts) }} -> [!CAUTION] -> **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). -{{- else }} -{{ template "chart.deprecationWarning" . }} -{{- end }} {{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }} @@ -40,11 +30,11 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. -{{ if eq .Type "application" }} +{{ if eq .Type "application" -}} Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). -{{ else if eq .Type "library" }} +{{ else if eq .Type "library" -}} Library chart templates can be included using the following format: ```go {{ "{{" }} include "template-name" . {{ "}}" }} @@ -54,7 +44,7 @@ If params other than the current context, specify those in place of the `.`: ```go {{ "{{" }} include "template-name" $myDict {{ "}}" }} ``` -{{- end }} +{{ end -}} > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -68,5 +58,60 @@ If params other than the current context, specify those in place of the `.`: {{ template "chart.requirementsSection" . }} {{ template "chart.valuesSection" . }} +{{- end -}} + +{{- /* + mozcloud.readme + Full standard README. Used by charts that do not need a custom Contributing section. +*/ -}} +{{- define "mozcloud.readme" -}} +{{ template "mozcloud.readme.preamble" . }} + +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. {{ template "helm-docs.versionFooter" . }} +{{- end -}} + +{{- /* + Shared partials. +*/ -}} + +{{- /* + deprecated.use-mozcloud + Standard deprecation notice for charts superseded by the unified mozcloud chart. + Prepend this to mozcloud.readme in a chart's README.md.gotmpl. + For a custom message, write the notice inline instead of calling this template. +*/ -}} +{{- define "deprecated.use-mozcloud" -}} +> [!CAUTION] +> **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +{{- end -}} + +{{- define "contributing.general-link" -}} +For general contribution workflows, unit testing conventions, JSON schema standards, and chart authoring standards that apply across all charts in this repository, see [CONTRIBUTING.md](../../CONTRIBUTING.md). +{{- end -}} + +{{- define "protected-keys-intro" -}} +This chart uses dict-based collections with a protected key per collection type that acts as a chart-level defaults template. The key is stripped from the rendered output and its values are deep-merged as a base under each user-defined entry. +{{- end -}} + +{{- define "json-schema-validation" }} +### JSON schema validation + +**Any change to `values.yaml` must be accompanied by a corresponding update to `values.schema.json`.** Letting the two files drift causes unrecognized keys to pass through silently or valid keys to be rejected with confusing errors. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for schema conventions. The quick reference for what to update when changing values: + +| Change type | Schema action required | +|---|---| +| Add a new key | Add a matching property with type, description, and (if applicable) default | +| Remove a key | Remove its property from the schema (and from any `required` arrays) | +| Rename a key | Remove the old property, add the new one | +| Restrict a string to specific values | Add or update an `enum` constraint | +| Add a new collection type | Add an `additionalProperties` entry with the item shape (or a `$ref`) | +| Extract a repeated shape | Move it into `$defs` and replace inline copies with `$ref` | +{{ end -}} diff --git a/deprecated/mozcloud-job/application/README.md b/deprecated/mozcloud-job/application/README.md index 3eb9067..48217c8 100644 --- a/deprecated/mozcloud-job/application/README.md +++ b/deprecated/mozcloud-job/application/README.md @@ -1,8 +1,8 @@ -# mozcloud-job - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-job + ![Version: 0.6.1](https://img.shields.io/badge/Version-0.6.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) A Helm chart that creates Kubernetes jobs and cron jobs. @@ -27,10 +27,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -51,5 +50,11 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | enabled | bool | `true` | | | jobs | object | `{}` | | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-job/application/README.md.gotmpl b/deprecated/mozcloud-job/application/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-job/application/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-job/library/README.md b/deprecated/mozcloud-job/library/README.md index 91c039a..eeb6a3e 100644 --- a/deprecated/mozcloud-job/library/README.md +++ b/deprecated/mozcloud-job/library/README.md @@ -1,8 +1,8 @@ -# mozcloud-job-lib - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-job-lib + ![Version: 0.6.1](https://img.shields.io/badge/Version-0.6.1-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) A library chart that creates Job and CronJob resources @@ -27,7 +27,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -38,7 +38,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -49,5 +48,11 @@ If params other than the current context, specify those in place of the `.`: | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | | file://../../mozcloud-workload-core/library | mozcloud-workload-core-lib | 0.6.23 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-job/library/README.md.gotmpl b/deprecated/mozcloud-job/library/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-job/library/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-preview/application/README.md b/deprecated/mozcloud-preview/application/README.md index e80caa7..50778e8 100644 --- a/deprecated/mozcloud-preview/application/README.md +++ b/deprecated/mozcloud-preview/application/README.md @@ -1,8 +1,8 @@ -# mozcloud-preview - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-preview + ![Version: 0.3.38](https://img.shields.io/badge/Version-0.3.38-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) A Helm chart for Kubernetes @@ -27,10 +27,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -59,5 +58,11 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | httpRoute.httpRoutes.mozcloud-gateway.rules[0].matches[0].path.type | string | `"PathPrefix"` | | | httpRoute.httpRoutes.mozcloud-gateway.rules[0].matches[0].path.value | string | `"/"` | | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-preview/application/README.md.gotmpl b/deprecated/mozcloud-preview/application/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-preview/application/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-preview/library/README.md b/deprecated/mozcloud-preview/library/README.md index e0a8a6e..a393331 100644 --- a/deprecated/mozcloud-preview/library/README.md +++ b/deprecated/mozcloud-preview/library/README.md @@ -1,8 +1,8 @@ -# mozcloud-preview-lib - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-preview-lib + ![Version: 0.2.38](https://img.shields.io/badge/Version-0.2.38-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) A library chart that creates preview http routes and supporting resources @@ -27,7 +27,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -38,7 +38,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -50,5 +49,11 @@ If params other than the current context, specify those in place of the `.`: | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | | file://../../mozcloud-service/library | mozcloud-service-lib | 0.2.22 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-preview/library/README.md.gotmpl b/deprecated/mozcloud-preview/library/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-preview/library/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-workload-core/library/README.md b/deprecated/mozcloud-workload-core/library/README.md index ee8325a..fead5ae 100644 --- a/deprecated/mozcloud-workload-core/library/README.md +++ b/deprecated/mozcloud-workload-core/library/README.md @@ -1,8 +1,8 @@ -# mozcloud-workload-core-lib - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-workload-core-lib + ![Version: 0.6.23](https://img.shields.io/badge/Version-0.6.23-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) A library chart that creates core components needed for MozCloud workloads @@ -27,7 +27,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -38,7 +38,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -48,5 +47,11 @@ If params other than the current context, specify those in place of the `.`: |------------|------|---------| | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-workload-core/library/README.md.gotmpl b/deprecated/mozcloud-workload-core/library/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-workload-core/library/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-workload-stateless/application/README.md b/deprecated/mozcloud-workload-stateless/application/README.md index 1c94daf..8031d95 100644 --- a/deprecated/mozcloud-workload-stateless/application/README.md +++ b/deprecated/mozcloud-workload-stateless/application/README.md @@ -1,8 +1,8 @@ -# mozcloud-workload-stateless - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-workload-stateless + ![Version: 0.4.26](https://img.shields.io/badge/Version-0.4.26-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) helm chart for building stateless workloads @@ -27,10 +27,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -53,5 +52,11 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | podMonitorings | object | `{}` | | | serviceAccounts | object | `{}` | | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-workload-stateless/application/README.md.gotmpl b/deprecated/mozcloud-workload-stateless/application/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-workload-stateless/application/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-workload-stateless/library/README.md b/deprecated/mozcloud-workload-stateless/library/README.md index 630094a..b9a8606 100644 --- a/deprecated/mozcloud-workload-stateless/library/README.md +++ b/deprecated/mozcloud-workload-stateless/library/README.md @@ -1,8 +1,8 @@ -# mozcloud-workload-stateless-lib - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-workload-stateless-lib + ![Version: 0.5.5](https://img.shields.io/badge/Version-0.5.5-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) helm chart for building stateless workloads @@ -27,7 +27,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -38,7 +38,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -49,5 +48,11 @@ If params other than the current context, specify those in place of the `.`: | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | | file://../../mozcloud-workload-core/library | mozcloud-workload-core-lib | 0.6.23 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-workload-stateless/library/README.md.gotmpl b/deprecated/mozcloud-workload-stateless/library/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-workload-stateless/library/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/deprecated/mozcloud-workload/application/README.md b/deprecated/mozcloud-workload/application/README.md index ac69996..5af6b76 100644 --- a/deprecated/mozcloud-workload/application/README.md +++ b/deprecated/mozcloud-workload/application/README.md @@ -1,8 +1,8 @@ -# mozcloud-workload - > [!CAUTION] > **This chart is deprecated.** Please use the mozcloud chart located [here](../../mozcloud/application). +# mozcloud-workload + ![Version: 0.5.1](https://img.shields.io/badge/Version-0.5.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) Opinionated application chart used to deploy MozCloud workloads and supporting resources @@ -27,10 +27,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -111,5 +110,11 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | workloads.mozcloud-workload.serviceAccount | object | `{}` | | | workloads.mozcloud-workload.strategy | string | `"RollingUpdate"` | | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/deprecated/mozcloud-workload/application/README.md.gotmpl b/deprecated/mozcloud-workload/application/README.md.gotmpl new file mode 100644 index 0000000..fa082aa --- /dev/null +++ b/deprecated/mozcloud-workload/application/README.md.gotmpl @@ -0,0 +1,3 @@ +{{ template "deprecated.use-mozcloud" . }} + +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-fastly-ips/library/README.md b/mozcloud-fastly-ips/library/README.md index 6f71967..36b6f2c 100644 --- a/mozcloud-fastly-ips/library/README.md +++ b/mozcloud-fastly-ips/library/README.md @@ -1,6 +1,8 @@ # mozcloud-fastly-ips-lib -This chart provides a list of Fastly origin IPs +![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) + +Fastly origin IPs ## Usage @@ -22,9 +24,25 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges — see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. -That’s it — subchart templates can now be included in your own chart. +Library chart templates can be included using the following format: +```go +{{ include "template-name" . }} +``` +If params other than the current context, specify those in place of the `.`: +```go +{{ include "template-name" $myDict }} +``` > [!TIP] -> We build OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or browse the chart's code for a specific version. +> We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. + +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-fastly-ips/library/README.md.gotmpl b/mozcloud-fastly-ips/library/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-fastly-ips/library/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-fastly-ips/library/values.yaml b/mozcloud-fastly-ips/library/values.yaml new file mode 100644 index 0000000..d675772 --- /dev/null +++ b/mozcloud-fastly-ips/library/values.yaml @@ -0,0 +1 @@ +# Empty -- created to generate Helm docs diff --git a/mozcloud-gateway/application/README.md b/mozcloud-gateway/application/README.md index 10edcf7..9ff9f46 100644 --- a/mozcloud-gateway/application/README.md +++ b/mozcloud-gateway/application/README.md @@ -24,10 +24,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -67,5 +66,38 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | httpRoute.httpRoutes.mozcloud-gateway.rules[0].backendRefs[0].port | int | `8080` | | | trafficDistributionPolicy | list | `[]` | | +--- + +## Contributing + +For general contribution workflows, unit testing conventions, JSON schema standards, and chart authoring standards that apply across all charts in this repository, see [CONTRIBUTING.md](../../CONTRIBUTING.md). + +### Protected default keys + +This chart uses dict-based collections with a protected key per collection type that acts as a chart-level defaults template. The key is stripped from the rendered output and its values are deep-merged as a base under each user-defined entry. + +| Collection | Protected key | +|---|---| +| `gateway.gateways` | `mozcloud-gateway` | +| `httpRoute.httpRoutes` | `mozcloud-gateway` | +| `backends` | `mozcloud-gateway` | + +Avoid naming your objects after these keys. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for a full explanation of how the protected key pattern works. + +### JSON schema validation + +**Any change to `values.yaml` must be accompanied by a corresponding update to `values.schema.json`.** Letting the two files drift causes unrecognized keys to pass through silently or valid keys to be rejected with confusing errors. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for schema conventions. The quick reference for what to update when changing values: + +| Change type | Schema action required | +|---|---| +| Add a new key | Add a matching property with type, description, and (if applicable) default | +| Remove a key | Remove its property from the schema (and from any `required` arrays) | +| Rename a key | Remove the old property, add the new one | +| Restrict a string to specific values | Add or update an `enum` constraint | +| Add a new collection type | Add an `additionalProperties` entry with the item shape (or a `$ref`) | +| Extract a repeated shape | Move it into `$defs` and replace inline copies with `$ref` | + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-gateway/application/README.md.gotmpl b/mozcloud-gateway/application/README.md.gotmpl new file mode 100644 index 0000000..900e471 --- /dev/null +++ b/mozcloud-gateway/application/README.md.gotmpl @@ -0,0 +1,23 @@ +{{ template "mozcloud.readme.preamble" . }} + +--- + +## Contributing + +{{ template "contributing.general-link" . }} + +### Protected default keys + +{{ template "protected-keys-intro" . }} + +| Collection | Protected key | +|---|---| +| `gateway.gateways` | `mozcloud-gateway` | +| `httpRoute.httpRoutes` | `mozcloud-gateway` | +| `backends` | `mozcloud-gateway` | + +Avoid naming your objects after these keys. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for a full explanation of how the protected key pattern works. + +{{ template "json-schema-validation" . }} + +{{ template "helm-docs.versionFooter" . }} diff --git a/mozcloud-gateway/library/README.md b/mozcloud-gateway/library/README.md index bd3de1b..8c73165 100644 --- a/mozcloud-gateway/library/README.md +++ b/mozcloud-gateway/library/README.md @@ -24,7 +24,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -35,7 +35,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -46,5 +45,11 @@ If params other than the current context, specify those in place of the `.`: | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | | file://../../mozcloud-service/library | mozcloud-service-lib | 0.2.22 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-gateway/library/README.md.gotmpl b/mozcloud-gateway/library/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-gateway/library/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-ingress/application/README.md b/mozcloud-ingress/application/README.md index 9893f7c..1e7569a 100644 --- a/mozcloud-ingress/application/README.md +++ b/mozcloud-ingress/application/README.md @@ -24,10 +24,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -58,5 +57,36 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | ingresses.mozcloud-ingress.tls.multipleHosts | bool | `true` | | | ingresses.mozcloud-ingress.tls.type | string | `"ManagedCertificate"` | | +--- + +## Contributing + +For general contribution workflows, unit testing conventions, JSON schema standards, and chart authoring standards that apply across all charts in this repository, see [CONTRIBUTING.md](../../CONTRIBUTING.md). + +### Protected default keys + +This chart uses dict-based collections with a protected key per collection type that acts as a chart-level defaults template. The key is stripped from the rendered output and its values are deep-merged as a base under each user-defined entry. + +| Collection | Protected key | +|---|---| +| `ingresses` | `mozcloud-ingress` | + +Avoid naming your objects after this key. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for a full explanation of how the protected key pattern works. + +### JSON schema validation + +**Any change to `values.yaml` must be accompanied by a corresponding update to `values.schema.json`.** Letting the two files drift causes unrecognized keys to pass through silently or valid keys to be rejected with confusing errors. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for schema conventions. The quick reference for what to update when changing values: + +| Change type | Schema action required | +|---|---| +| Add a new key | Add a matching property with type, description, and (if applicable) default | +| Remove a key | Remove its property from the schema (and from any `required` arrays) | +| Rename a key | Remove the old property, add the new one | +| Restrict a string to specific values | Add or update an `enum` constraint | +| Add a new collection type | Add an `additionalProperties` entry with the item shape (or a `$ref`) | +| Extract a repeated shape | Move it into `$defs` and replace inline copies with `$ref` | + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-ingress/application/README.md.gotmpl b/mozcloud-ingress/application/README.md.gotmpl new file mode 100644 index 0000000..1c3075a --- /dev/null +++ b/mozcloud-ingress/application/README.md.gotmpl @@ -0,0 +1,21 @@ +{{ template "mozcloud.readme.preamble" . }} + +--- + +## Contributing + +{{ template "contributing.general-link" . }} + +### Protected default keys + +{{ template "protected-keys-intro" . }} + +| Collection | Protected key | +|---|---| +| `ingresses` | `mozcloud-ingress` | + +Avoid naming your objects after this key. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for a full explanation of how the protected key pattern works. + +{{ template "json-schema-validation" . }} + +{{ template "helm-docs.versionFooter" . }} diff --git a/mozcloud-ingress/library/README.md b/mozcloud-ingress/library/README.md index b8414e3..0a27b89 100644 --- a/mozcloud-ingress/library/README.md +++ b/mozcloud-ingress/library/README.md @@ -24,7 +24,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -35,7 +35,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -46,5 +45,11 @@ If params other than the current context, specify those in place of the `.`: | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | | file://../../mozcloud-service/library | mozcloud-service-lib | 0.2.22 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-ingress/library/README.md.gotmpl b/mozcloud-ingress/library/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-ingress/library/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-labels/library/README.md b/mozcloud-labels/library/README.md index 4db8e50..6efe3e9 100644 --- a/mozcloud-labels/library/README.md +++ b/mozcloud-labels/library/README.md @@ -1,6 +1,8 @@ # mozcloud-labels-lib -This chart provides templates that render MozCloud labels suitable to be passed to e.g. resource `labels` or `selectorLabels` sections. +![Version: 0.3.16](https://img.shields.io/badge/Version-0.3.16-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square) + +Standardized labels for MozCloud Helm charts ## Usage @@ -17,14 +19,30 @@ version: 0.1.0 type: application dependencies: - name: mozcloud-labels-lib - version: ~0.3.4 + version: ~0.3.16 repository: oci://us-west1-docker.pkg.dev/moz-fx-platform-artifacts/mozcloud-charts ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges — see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. -That’s it — subchart templates can now be included in your own chart. +Library chart templates can be included using the following format: +```go +{{ include "template-name" . }} +``` +If params other than the current context, specify those in place of the `.`: +```go +{{ include "template-name" $myDict }} +``` > [!TIP] -> We build OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or browse the chart's code for a specific version. +> We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. + +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-labels/library/README.md.gotmpl b/mozcloud-labels/library/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-labels/library/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-labels/library/values.yaml b/mozcloud-labels/library/values.yaml new file mode 100644 index 0000000..d675772 --- /dev/null +++ b/mozcloud-labels/library/values.yaml @@ -0,0 +1 @@ +# Empty -- created to generate Helm docs diff --git a/mozcloud-opentelemetry/application/README.md b/mozcloud-opentelemetry/application/README.md index 9686d48..f007626 100644 --- a/mozcloud-opentelemetry/application/README.md +++ b/mozcloud-opentelemetry/application/README.md @@ -24,10 +24,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -82,5 +81,11 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | serviceAccount.create | bool | `true` | | | serviceAccount.name | string | `"mozcloud-otel-collector"` | | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-opentelemetry/application/README.md.gotmpl b/mozcloud-opentelemetry/application/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-opentelemetry/application/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud-service/library/README.md b/mozcloud-service/library/README.md index 48ef858..d9fb63a 100644 --- a/mozcloud-service/library/README.md +++ b/mozcloud-service/library/README.md @@ -24,7 +24,7 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Library chart templates can be included using the following format: ```go @@ -35,7 +35,6 @@ If params other than the current context, specify those in place of the `.`: ```go {{ include "template-name" $myDict }} ``` - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -45,5 +44,11 @@ If params other than the current context, specify those in place of the `.`: |------------|------|---------| | file://../../mozcloud-labels/library | mozcloud-labels-lib | 0.3.16 | +--- + +## Contributing + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution workflows, unit testing conventions, JSON schema standards, and general chart authoring standards. + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud-service/library/README.md.gotmpl b/mozcloud-service/library/README.md.gotmpl new file mode 100644 index 0000000..06ab2af --- /dev/null +++ b/mozcloud-service/library/README.md.gotmpl @@ -0,0 +1 @@ +{{ template "mozcloud.readme" . }} diff --git a/mozcloud/application/README.md b/mozcloud/application/README.md index 7c8749c..5c8fb4d 100644 --- a/mozcloud/application/README.md +++ b/mozcloud/application/README.md @@ -24,10 +24,9 @@ dependencies: ``` > [!IMPORTANT] -> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges, see [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. +> Make sure to set a valid version for your dependencies. Helm supports pinning exact versions as well as version ranges. See [chart best practices - dependencies - versions](https://helm.sh/docs/chart_best_practices/dependencies/#versions) for more details. Next, update your tenant's values. Shared charts are meant to be self-documented. We ship a verbose [values file](values.yaml) as well as a [JSON schema](values.schema.json). - > [!TIP] > We're building OCI artifacts automatically with [GHA](/.github/workflows/auto-push-tag-helm-charts.yaml). When a new artifact has been built, we add a matching [tag](https://github.com/mozilla/helm-charts/tags) to this repo as well. Use this to find out about available chart versions and/or to browse the chart's code for a specific version. @@ -171,5 +170,108 @@ Next, update your tenant's values. Shared charts are meant to be self-documented | workloads.mozcloud-workload.strategy | string | `"RollingUpdate"` | | | workloads.mozcloud-workload.type | string | `"deployment"` | | +--- + +## Contributing + +This section covers standards specific to this chart. For general contribution workflows, unit testing conventions, JSON schema standards, and chart authoring standards that apply across all charts in this repository, see [CONTRIBUTING.md](../../CONTRIBUTING.md). + +### Template organization + +Template folders must mirror top-level keys in `values.yaml`. For example, a `configMaps` key in values corresponds to a `templates/configmap/` folder; `workloads` corresponds to `templates/workload/`, and so on. This 1:1 mapping makes it straightforward to locate the template responsible for any given value. + +**Shared templates** that serve multiple resource types (annotations, labels, pod specs, formatters) live as `_.yaml` files directly in `templates/`. These are named template definitions used across multiple subfolders, not helpers in the traditional sense. + +**Resource-specific templates** (e.g. `deployment.yaml`, `cronjob.yaml`) live in the subfolder for their resource type. + +### Helper file placement + +Helper functions belong in a `_helpers.tpl` file located in the same folder as the templates they serve: + +- Helpers used only by workload templates: `templates/workload/_helpers.tpl` +- Helpers used only by task templates: `templates/task/_helpers.tpl` +- Helpers used chart-wide: `templates/_helpers.tpl` + +A helper should live in the most specific scope where it is used. Do not place a workload-specific helper in the root `_helpers.tpl` just because it seems "important". Scope it correctly. + +> [!NOTE] +> An exception applies for unusually complex logic that would make a template significantly harder to read on its own. In that case, extracting the logic into a helper is encouraged even if it is only called once. + +### When to write a helper vs. keep logic in a template + +Templates are the primary site of rendering and interpolation. They should be readable at a glance. + +If you find yourself writing loops, conditionals, or data transformations inside a template, first ask: + +1. **Can the data structure be simplified** so the template doesn't need to do that work? +2. **Should this be a helper** that returns a clean value the template can use directly? + +If neither applies, the logic can stay in the template. This should be the exception, not the rule. + +### Helper authoring standards + +- **Always use named parameters.** Helpers must accept a dict with named keys rather than relying on positional arguments or raw context. This makes call sites self-documenting. + + ```yaml + {{- include "mozcloud.myHelper" (dict "name" $name "context" $) }} + ``` + +- **Parameters must be single-purpose and non-overlapping.** Do not define both `config` and `jobConfig`, or both `workloadContainerConfig` and `jobContainerConfig`, as parameters to the same helper. Each parameter should have one clear role. + +- **Keep helpers concise.** A helper that spans many lines is usually doing too much. Break it into smaller, focused helpers if needed. + +- **Avoid accumulating too many helpers in a single file.** When a `_helpers.tpl` becomes hard to scan, consider whether the helpers can be split into more targeted shared templates (e.g. `_annotations.yaml`, `_labels.yaml`). + +- **Document every helper.** Each helper must have a block comment above its `define` statement that describes what it does, its parameters (name, type, required/optional), and its return value. Follow the established format used throughout this chart: + + ``` + {{- /* + Short description of what this helper does. + + Params: + paramName (type): (required|optional) What this parameter is for. + + Returns: + (type) What the helper produces. + */ -}} + ``` + +### Protected default keys + +This chart uses dict-based collections with a protected key per collection type that acts as a chart-level defaults template. The key is stripped from the rendered output and its values are deep-merged as a base under each user-defined entry. + +| Collection | Protected key | +|------------------|----------------------------| +| `workloads` | `mozcloud-workload` | +| `containers` | `mozcloud-container` | +| `initContainers` | `mozcloud-init-container` | +| `tasks.cronJobs` | `mozcloud-cronjob` | +| `tasks.jobs` | `mozcloud-job` | + +Users are instructed in `values.yaml` not to name their objects after these keys. If a protected key is the only entry in a collection (no user-defined entries), it is treated as a regular object and rendered as-is. + +When adding a new collection type, you must: + +1. Define a corresponding protected key in `values.yaml`. +2. Add a formatter helper (following the pattern in `templates/_formatter.yaml`) that applies the same strip-and-merge logic. +3. Call the formatter from the template before iterating over the collection. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for the general explanation of why this pattern exists. + +### JSON schema validation + +**Any change to `values.yaml` must be accompanied by a corresponding update to `values.schema.json`.** Letting the two files drift causes unrecognized keys to pass through silently or valid keys to be rejected with confusing errors. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for schema conventions. The quick reference for what to update when changing values: + +| Change type | Schema action required | +|---|---| +| Add a new key | Add a matching property with type, description, and (if applicable) default | +| Remove a key | Remove its property from the schema (and from any `required` arrays) | +| Rename a key | Remove the old property, add the new one | +| Restrict a string to specific values | Add or update an `enum` constraint | +| Add a new collection type | Add an `additionalProperties` entry with the item shape (or a `$ref`) | +| Extract a repeated shape | Move it into `$defs` and replace inline copies with `$ref` | + ---------------------------------------------- Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) diff --git a/mozcloud/application/README.md.gotmpl b/mozcloud/application/README.md.gotmpl new file mode 100644 index 0000000..1e8e645 --- /dev/null +++ b/mozcloud/application/README.md.gotmpl @@ -0,0 +1,93 @@ +{{ template "mozcloud.readme.preamble" . }} + +--- + +## Contributing + +This section covers standards specific to this chart. For general contribution workflows, unit testing conventions, JSON schema standards, and chart authoring standards that apply across all charts in this repository, see [CONTRIBUTING.md](../../CONTRIBUTING.md). + +### Template organization + +Template folders must mirror top-level keys in `values.yaml`. For example, a `configMaps` key in values corresponds to a `templates/configmap/` folder; `workloads` corresponds to `templates/workload/`, and so on. This 1:1 mapping makes it straightforward to locate the template responsible for any given value. + +**Shared templates** that serve multiple resource types (annotations, labels, pod specs, formatters) live as `_.yaml` files directly in `templates/`. These are named template definitions used across multiple subfolders, not helpers in the traditional sense. + +**Resource-specific templates** (e.g. `deployment.yaml`, `cronjob.yaml`) live in the subfolder for their resource type. + +### Helper file placement + +Helper functions belong in a `_helpers.tpl` file located in the same folder as the templates they serve: + +- Helpers used only by workload templates: `templates/workload/_helpers.tpl` +- Helpers used only by task templates: `templates/task/_helpers.tpl` +- Helpers used chart-wide: `templates/_helpers.tpl` + +A helper should live in the most specific scope where it is used. Do not place a workload-specific helper in the root `_helpers.tpl` just because it seems "important". Scope it correctly. + +> [!NOTE] +> An exception applies for unusually complex logic that would make a template significantly harder to read on its own. In that case, extracting the logic into a helper is encouraged even if it is only called once. + +### When to write a helper vs. keep logic in a template + +Templates are the primary site of rendering and interpolation. They should be readable at a glance. + +If you find yourself writing loops, conditionals, or data transformations inside a template, first ask: + +1. **Can the data structure be simplified** so the template doesn't need to do that work? +2. **Should this be a helper** that returns a clean value the template can use directly? + +If neither applies, the logic can stay in the template. This should be the exception, not the rule. + +### Helper authoring standards + +- **Always use named parameters.** Helpers must accept a dict with named keys rather than relying on positional arguments or raw context. This makes call sites self-documenting. + + ```yaml + {{ "{{" }}- include "mozcloud.myHelper" (dict "name" $name "context" $) {{ "}}" }} + ``` + +- **Parameters must be single-purpose and non-overlapping.** Do not define both `config` and `jobConfig`, or both `workloadContainerConfig` and `jobContainerConfig`, as parameters to the same helper. Each parameter should have one clear role. + +- **Keep helpers concise.** A helper that spans many lines is usually doing too much. Break it into smaller, focused helpers if needed. + +- **Avoid accumulating too many helpers in a single file.** When a `_helpers.tpl` becomes hard to scan, consider whether the helpers can be split into more targeted shared templates (e.g. `_annotations.yaml`, `_labels.yaml`). + +- **Document every helper.** Each helper must have a block comment above its `define` statement that describes what it does, its parameters (name, type, required/optional), and its return value. Follow the established format used throughout this chart: + + ``` + {{ "{{" }}- /* + Short description of what this helper does. + + Params: + paramName (type): (required|optional) What this parameter is for. + + Returns: + (type) What the helper produces. + */ -{{ "}}" }} + ``` + +### Protected default keys + +{{ template "protected-keys-intro" . }} + +| Collection | Protected key | +|------------------|----------------------------| +| `workloads` | `mozcloud-workload` | +| `containers` | `mozcloud-container` | +| `initContainers` | `mozcloud-init-container` | +| `tasks.cronJobs` | `mozcloud-cronjob` | +| `tasks.jobs` | `mozcloud-job` | + +Users are instructed in `values.yaml` not to name their objects after these keys. If a protected key is the only entry in a collection (no user-defined entries), it is treated as a regular object and rendered as-is. + +When adding a new collection type, you must: + +1. Define a corresponding protected key in `values.yaml`. +2. Add a formatter helper (following the pattern in `templates/_formatter.yaml`) that applies the same strip-and-merge logic. +3. Call the formatter from the template before iterating over the collection. + +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for the general explanation of why this pattern exists. + +{{ template "json-schema-validation" . }} + +{{ template "helm-docs.versionFooter" . }}