# helm-charts
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: ~1.0.0
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 when a PR is merged. The release type (`major`, `minor`, `patch`) is inferred from the PR title using conventional commit format and applied as a label. You can override the label at any time before merging. A `no-release` label skips publishing entirely. A corresponding [tag](https://github.com/mozilla/helm-charts/tags) is added to this repository for each release. See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
---
## Requirements
### `uv`
Development workflows are driven by [`uv`](https://docs.astral.sh/uv/). Install it before anything else.
### `pre-commit`
Pre-commit hooks run on commit and handle the following automatically:
- **ruff** — formats and lints Python/TOML files (with auto-fix)
- **helm update dependencies** — runs `make update-dependencies` when chart files change
- **helm lint** — lints all non-deprecated charts
- **helm unittest** — runs `make unit-tests-affected` when chart files change
- **helm-docs** — regenerates `README.md` files from `.gotmpl` templates
Install with:
```sh
uv tool install pre-commit
```
### `helm`
[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
### `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 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
### `make update-dependencies`
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 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 unit-tests
```
To run tests and update snapshots (required when template output changes intentionally):
```sh
make unit-tests UPDATE_SNAPSHOTS=1
```
### `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
```
### `make bump-charts`
> [!WARNING]
> Version bumps are handled automatically by CI when a PR is merged. Running this manually before merging will cause a version conflict — CI will attempt to bump again on top of your local bump. Only use this if you fully understand the release process and have a specific reason to bypass CI.
Bumps chart versions locally for staged files:
```sh
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
```
### `make clean`
Removes all downloaded chart dependency directories (`charts/`):
```sh
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. Describe scenarios in values files rather than inline `set:` blocks so they stay easy to find and reuse; both suites and individual test cases accept a `values:` list.
- **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
### Internal references
- [MozCloud Helm Charts](https://mozilla-hub.atlassian.net/wiki/spaces/SRE/pages/2060353541/MozCloud+Helm+Charts)
- [Getting Started](https://mozilla-hub.atlassian.net/wiki/spaces/SRE/pages/2059600542/How+To+Getting+Started+With+MozCloud+Charts)
### External references
- [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)