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.
Charts in this repository fall into two categories: application charts and 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.
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.
Charts are distributed as OCI artifacts 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:
# 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-chartsEach 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 is added to this repository for each release. See CONTRIBUTING.md for full details.
Development workflows are driven by uv. Install it before anything else.
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-dependencieswhen chart files change - helm lint — lints all non-deprecated charts
- helm unittest — runs
make unit-tests-affectedwhen chart files change - helm-docs — regenerates
README.mdfiles from.gotmpltemplates
Install with:
uv tool install pre-commitHelm is required to run unit tests and render charts locally.
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 validates rendered manifests against Kubernetes and GKE CRD schemas. Required only if running make kubeconform.
Run make install to configure pre-commit hooks and install/update the helm unittest plugin:
make installThis assumes uv, pre-commit, and helm are already installed.
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:
make update-dependencies
make update-dependencies DRY_RUN=1Runs the full unit test suite across all application charts. If chart dependencies are missing, they are updated automatically before tests run.
make unit-testsTo run tests and update snapshots (required when template output changes intentionally):
make unit-tests UPDATE_SNAPSHOTS=1Runs 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:
make unit-tests-affected
make unit-tests-affected UPDATE_SNAPSHOTS=1Warning
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:
make bump-charts
make bump-charts mozcloud-gateway-libValidates rendered test snapshot manifests against upstream Kubernetes and GKE CRD schemas. Useful for catching API version drift or schema regressions:
make kubeconformRemoves all downloaded chart dependency directories (charts/):
make cleanSee CONTRIBUTING.md for contribution workflows, unit testing standards, JSON schema conventions, and general chart authoring standards.
Tests live in each chart's tests/ directory and are written using 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.yamlfile. 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 for conventions on how to write them.