Helm Operator CRD Reference

Complete field reference for HelmRepository and HelmRelease custom resource definitions

Overview

The Helm Operator manages two Custom Resource Definitions (CRDs) in the cluster. PodWarden creates and updates these resources when you deploy Helm chart stacks. The operator watches them and reconciles the actual Helm releases.

Both CRDs live in the helm.podwarden.com API group.

HelmRepository

A HelmRepository represents a Helm chart repository that the operator periodically syncs to discover available charts and versions.

apiVersion: helm.podwarden.com/v1alpha1
kind: HelmRepository
metadata:
  name: bitnami
  namespace: default
spec:
  url: "https://charts.bitnami.com/bitnami"
  type: default
  interval: 10m
status:
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-03-15T10:00:00Z"
      reason: Succeeded
      message: "Repository index fetched successfully"
  lastSyncTime: "2026-03-15T10:00:00Z"
  chartCount: 142
  artifact:
    url: "https://charts.bitnami.com/bitnami/index.yaml"
    digest: "sha256:abc123..."
    lastUpdateTime: "2026-03-15T10:00:00Z"

spec

Field	Type	Required	Default	Description
`url`	string	Yes	—	HTTPS URL of the Helm chart repository index
`type`	string	No	`default`	Repository type. Only `default` (standard Helm repo) is currently supported.
`interval`	duration	No	`10m`	How often the operator re-fetches the repository index to check for new chart versions

status

Field	Type	Description
`conditions`	[]Condition	Standard Kubernetes conditions (see Conditions below)
`lastSyncTime`	timestamp	When the repository index was last successfully fetched
`chartCount`	integer	Number of charts found in the repository index
`artifact`	object	Details about the fetched index artifact
`artifact.url`	string	URL of the repository index that was fetched
`artifact.digest`	string	SHA256 digest of the fetched index
`artifact.lastUpdateTime`	timestamp	When the index was last modified upstream

HelmRelease

A HelmRelease describes a Helm chart to install (or upgrade) in the cluster, including the chart reference, values, and lifecycle policies.

apiVersion: helm.podwarden.com/v1alpha1
kind: HelmRelease
metadata:
  name: prometheus-stack
  namespace: monitoring
  annotations:
    helm.podwarden.com/dry-run: "false"
    helm.podwarden.com/values-hash: "sha256:def456..."
spec:
  chart:
    name: kube-prometheus-stack
    version: "65.1.0"
    sourceRef:
      kind: HelmRepository
      name: prometheus-community
      namespace: monitoring
  values:
    grafana:
      adminPassword: "changeme"
      persistence:
        enabled: true
    prometheus:
      prometheusSpec:
        retention: 15d
  install:
    createNamespace: true
    timeout: 10m
    remediation:
      retries: 3
  upgrade:
    timeout: 10m
    remediation:
      retries: 3
      strategy: rollback
  uninstall:
    keepHistory: false
    timeout: 5m
  interval: 5m
status:
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-03-15T10:05:00Z"
      reason: InstallSucceeded
      message: "Helm install succeeded"
    - type: Released
      status: "True"
      lastTransitionTime: "2026-03-15T10:05:00Z"
      reason: InstallSucceeded
      message: "Release prometheus-stack installed"
  revisions:
    current: 1
    previous: 0
    history:
      - revision: 1
        chartVersion: "65.1.0"
        status: deployed
        createdAt: "2026-03-15T10:05:00Z"
        valuesHash: "sha256:def456..."
  resources:
    - apiVersion: apps/v1
      kind: Deployment
      name: prometheus-stack-grafana
      namespace: monitoring
      ready: true
    - apiVersion: apps/v1
      kind: StatefulSet
      name: prometheus-prometheus-stack-prometheus
      namespace: monitoring
      ready: true
    - apiVersion: v1
      kind: Service
      name: prometheus-stack-grafana
      namespace: monitoring
      ready: true
  clusterScopedResources:
    - apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      name: prometheus-stack-grafana-clusterrole
    - apiVersion: apiextensions.k8s.io/v1
      kind: CustomResourceDefinition
      name: prometheuses.monitoring.coreos.com

spec.chart

Field	Type	Required	Description
`name`	string	Yes	Chart name within the repository
`version`	string	Yes	Exact chart version to install
`sourceRef.kind`	string	Yes	Must be `HelmRepository`
`sourceRef.name`	string	Yes	Name of the HelmRepository resource
`sourceRef.namespace`	string	No	Namespace of the HelmRepository (defaults to the HelmRelease namespace)

spec.values

Field	Type	Required	Description
`values`	object	No	Arbitrary YAML values passed to `helm install/upgrade --values`. These are the merged result of the template's `default_values` and operator-configured `env_schema` values.

spec.install

Field	Type	Required	Default	Description
`createNamespace`	boolean	No	`false`	Create the target namespace if it doesn't exist
`timeout`	duration	No	`5m`	Maximum time to wait for the install to complete
`remediation.retries`	integer	No	`0`	Number of times to retry a failed install

spec.upgrade

Field	Type	Required	Default	Description
`timeout`	duration	No	`5m`	Maximum time to wait for the upgrade to complete
`remediation.retries`	integer	No	`0`	Number of times to retry a failed upgrade
`remediation.strategy`	string	No	`rollback`	What to do on failure: `rollback` (revert to previous revision) or `uninstall`

spec.uninstall

Field	Type	Required	Default	Description
`keepHistory`	boolean	No	`false`	Retain Helm release history after uninstall
`timeout`	duration	No	`5m`	Maximum time to wait for uninstall to complete

spec.interval

Field	Type	Required	Default	Description
`interval`	duration	No	`5m`	How often the operator checks if the release needs reconciliation (e.g., drift detection)

status.conditions

Standard Kubernetes conditions reported by the operator:

Type	Description
`Ready`	Whether the release is in a healthy, reconciled state
`Released`	Whether the Helm install/upgrade completed

Each condition has:

Field	Type	Description
`type`	string	Condition type
`status`	string	`True`, `False`, or `Unknown`
`lastTransitionTime`	timestamp	When the condition last changed
`reason`	string	Machine-readable reason (e.g., `InstallSucceeded`, `UpgradeFailed`)
`message`	string	Human-readable detail

status.revisions

Field	Type	Description
`current`	integer	Current active revision number
`previous`	integer	Previous revision number (0 if first install)
`history`	[]RevisionEntry	List of all revisions

Each revision entry:

Field	Type	Description
`revision`	integer	Revision number
`chartVersion`	string	Chart version used for this revision
`status`	string	`deployed`, `failed`, `superseded`
`createdAt`	timestamp	When this revision was created
`valuesHash`	string	SHA256 hash of the values used

status.resources

Array of Kubernetes resources managed by this release (namespace-scoped):

Field	Type	Description
`apiVersion`	string	Resource API version
`kind`	string	Resource kind (Deployment, Service, etc.)
`name`	string	Resource name
`namespace`	string	Resource namespace
`ready`	boolean	Whether the resource is in a ready/healthy state

status.clusterScopedResources

Array of cluster-scoped resources created by this release. Same fields as resources except no namespace or ready field:

Field	Type	Description
`apiVersion`	string	Resource API version
`kind`	string	Resource kind (ClusterRole, CRD, etc.)
`name`	string	Resource name

Annotations

The operator recognizes these annotations on HelmRelease resources:

Annotation	Type	Description
`helm.podwarden.com/dry-run`	`"true"` / `"false"`	When `"true"`, the operator renders templates and populates `status.resources` without actually installing. PodWarden sets this during dry-run preview.
`helm.podwarden.com/values-hash`	string	SHA256 hash of the values object. PodWarden sets this to detect value changes and trigger reconciliation.

System App ConfigMap

The Helm Operator registers itself via a ConfigMap with the podwarden.com/system-app=true label. PodWarden reads this ConfigMap to detect operator presence and capabilities.

apiVersion: v1
kind: ConfigMap
metadata:
  name: helm-operator
  namespace: podwarden-system
  labels:
    podwarden.com/system-app: "true"
data:
  name: helm-operator
  version: "1.0.0"
  capabilities: |
    - helmRepository
    - helmRelease
    - dryRun
    - upgradeRollback

Capabilities

Capability	Description
`helmRepository`	Can manage HelmRepository CRDs
`helmRelease`	Can manage HelmRelease CRDs (install, upgrade, uninstall)
`dryRun`	Supports dry-run rendering of chart templates
`upgradeRollback`	Supports automatic rollback on failed upgrades

PodWarden uses these capabilities to enable or disable UI features. For example, if dryRun is not listed, the dry-run toggle is hidden in the deploy form.