# Helm components

> Install opinionated Helm releases onto a deployment space from a curated catalog; observability, networking, security, data.

Source: https://zop.dev/docs/zopday/provisioning/components

---

ZopDay ships with a curated Helm catalog you can install onto any registered [deployment space](https://zop.dev/docs/zopday/concepts/deployment-spaces) in one click. Components are tested, version-pinned, and configured with sensible defaults; useful when you want monitoring or ingress on a fresh cluster without spending a day on YAML.

## Where the catalog lives

The catalog is defined in `configs/components.yaml` in the content repo. Each entry declares:

| Field | What it is |
|---|---|
| `id` | Stable identifier (e.g. `prometheus`, `cert-manager`) |
| `name` | Display name |
| `chart` | Helm chart reference (repo + chart name) |
| `version` | Pinned chart version |
| `valuesTemplate` | Default values, parameterised |
| `requiredPolicies` | Cluster RBAC policies the component needs |
| `defaultOnCreate` | If true, installed automatically when ZopDay provisions a cluster |
| `tags` | Categorisation (observability, networking, security, data, …) |

The catalog is editable per org; your platform team can fork the default catalog and add internally-vetted components.

## Default-on-create components

For clusters ZopDay provisions, this set lands automatically during `stepBootstrapComponents`:

| Component | Purpose |
|---|---|
| Cluster Autoscaler | Scales node groups based on pending pod pressure |
| Cloud-native ingress controller | AWS LB Controller / GKE Ingress / Azure App Gateway Ingress |
| Cert-manager | Auto-rotated TLS certificates via Let's Encrypt or your cloud CA |
| External-DNS | Auto-creates Route 53 / Cloud DNS / Azure DNS records from Ingress resources |
| Metrics-server | Required for HPA / autoscaler decisions |
| Pod Security Standards admission controller | Enforces the restricted profile by default |
| Calico (AWS, GCP) / Azure CNI (Azure) | Network Policy enforcement |

For BYOC clusters (registered via [Cluster registration](https://zop.dev/docs/zopday/cloud-setup/cluster-registration)), none of these install automatically; you opt in to each one from the catalog.

## Browse the catalog

```
GET /catalog/components
```

Returns the full catalog with metadata. Filter via query params:

| Param | Filters by |
|---|---|
| `tag` | One of `observability`, `networking`, `security`, `data`, etc. |
| `provider` | `aws` / `gcp` / `azure`; some components are provider-specific |
| `defaultOnCreate` | `true` to see only the auto-install set |

## Install a component

```
POST /provisioning-jobs/install-component
{
  "spaceId": "<space-uuid>",
  "componentId": "prometheus",
  "values": { ... }   // optional overrides on the default values template
}
```

This creates a provisioning job with `kind=provisioning`, `resourceType=helm_component`. The job validates the space and the component, merges your overrides on top of the catalog's default values template, calls `helm install` via the Helm SDK using a kubeauth-minted kubeconfig, then polls the release's primary workload for readiness.

Install time varies by component; typically 1–5 minutes. Components with admission webhooks tend to be slower because the install blocks on the webhook being reachable from the API server.

If an install fails, the job is marked failed in the Provisioning Jobs view with the failing step and error. Components that block on an admission webhook being reachable will fail here if the webhook never comes up (for example, missing RBAC or a networking restriction between the API server and the webhook service). Fix the cause and retry, or uninstall the partial release and reinstall.

## Catalog scope

The catalog covers components in categories like observability (metrics, logs, dashboards), networking (ingress, service mesh, network policy), security (admission controllers, runtime detection), secrets management (cloud-vault integration), backup / disaster recovery, and provider-specific autoscalers. Browse the catalog from Provisioning → Catalog in the app for the current set and their default values.

Your platform team can extend the catalog with internally-vetted components; see [Catalog editing](#catalog-editing-platform-team) below.

## Custom values

The wizard's "Customise" tab exposes the chart's values that the catalog template parameterises. Anything outside the parameterised set requires editing the catalog (your platform team's job).

Use the API directly for arbitrary overrides:

```
POST /provisioning-jobs/install-component
{
  "spaceId": "<space-uuid>",
  "componentId": "prometheus",
  "values": {
    "alertmanager": {
      "enabled": true,
      "config": {
        "global": {
          "slack_api_url": "https://hooks.slack.com/services/..."
        }
      }
    },
    "prometheus": {
      "prometheusSpec": {
        "retention": "30d"
      }
    }
  }
}
```

The override is merged on top of the catalog defaults. ZopDay does **not** allow `--set-file` or templated values that pull from the filesystem at install time; values must be JSON-serialisable.

## Versioning

Catalog entries pin chart versions. Updating a component to a newer chart version is a catalog edit, not a per-install choice:

1. Update the version in `configs/components.yaml` (your platform team)
2. New installs use the new version
3. Existing installs **do not auto-upgrade**: run `Update` on each one to roll forward

This is deliberate. Auto-upgrading every Prometheus install in every cluster because someone bumped the catalog would be too easy to break.

## Update / Uninstall

```
PATCH /provisioning-jobs/{id}      # for component-install jobs, accepts new values
DELETE /provisioning-jobs/{id}     # helm uninstall, clean up CRDs as appropriate
```

Uninstall removes the Helm release. **Custom resources (CRDs) installed by the component are not removed by default**: many components install CRDs at the cluster level and removing them would delete custom resources that depend on them across all namespaces. Set `removeCrds: true` in the delete request body to opt into CRD removal.

## Catalog editing (platform team)

The catalog is a YAML file in the content repo. Add a component by:

1. Edit `configs/components.yaml`
2. Add the entry with all required fields
3. Open a PR to the content repo
4. After merge, the catalog refreshes on the next content sync (within minutes)

Once that sync completes, components added this way are available to every org. For internal-only components, scope them with the `orgIds: [...]` field.