Integrations¶

HomeAssistantIntegration registers a Home Assistant integration through the Config Flow API — declaratively, as a Kubernetes resource. It does not deploy any containers; it only tells Home Assistant to configure an integration.

Use cases¶

Register MQTT broker after deploying Mosquitto via Helm
Configure ESPHome, recorder, or other single-step integrations
Adopt an integration that was configured manually in the HA UI

How it works¶

StartConfigFlow(domain) → SubmitConfigFlow(configuration) → save entryID in status

On subsequent reconciles the operator verifies the entry still exists in HA (idempotent). If spec.configuration changes, the operator removes the old entry and re-runs the flow.

Adopt pattern: if the integration already exists in HA (configured via UI) but the CR has no status.entryID, the operator adopts it without reconfiguring.

Requires a bootstrap API token.

MQTT example¶

# 1. Deploy broker (e.g. via Helm)
# helm install mosquitto eclipse-mosquitto/mosquitto

# 2. Register integration
apiVersion: ha.homeassistant.io/v1
kind: HomeAssistantIntegration
metadata:
  name: mqtt
spec:
  homeAssistantRef:
    name: home
  domain: mqtt
  configuration:
    broker:
      value: "mosquitto.default.svc.cluster.local"
    port:
      value: "1883"
    username:
      secretKeyRef:
        name: mqtt-credentials
        key: username
    password:
      secretKeyRef:
        name: mqtt-credentials
        key: password

Recorder example¶

apiVersion: ha.homeassistant.io/v1
kind: HomeAssistantIntegration
metadata:
  name: recorder
spec:
  homeAssistantRef:
    name: home
  domain: recorder
  configuration:
    db_url:
      secretKeyRef:
        name: database-credentials
        key: db_url

Spec reference¶

`spec.domain`¶

The integration domain as recognised by Home Assistant (e.g. mqtt, esphome, recorder).

`spec.configuration`¶

Key-value map of configuration values passed to the Config Flow. Each value is either:

Plain text: value: "some-string"
Secret reference: resolved from a Kubernetes Secret at reconcile time

configuration:
  broker:
    value: "mosquitto.default.svc.cluster.local"
  password:
    secretKeyRef:
      name: mqtt-credentials
      key: password

Status and conditions¶

kubectl get haint mqtt

NAME   HOMEASSISTANT   DOMAIN   READY   AGE
mqtt   home            mqtt     True    5m

kubectl describe haint mqtt

Status:
  Entry ID:     abc123def456
  Config Hash:  sha256:...
  Conditions:
    IntegrationReady: True (reason: IntegrationConfigured)

Condition reasons¶

Reason	Meaning
`IntegrationConfigured`	Config flow completed successfully
`AlreadyConfigured`	Integration existed in HA; adopted without reconfiguring
`TokenNotAvailable`	Bootstrap token not yet created; requeuing
`HANotReady`	HA instance not ready; requeuing
`ConfigFlowFailed`	Config Flow returned an error
`SecretResolutionFailed`	Referenced Kubernetes Secret not found

Events¶

Event	Type	Meaning
`IntegrationConfigured`	Normal	Config flow succeeded
`IntegrationAdopted`	Normal	Existing entry adopted
`IntegrationReconfigured`	Normal	Spec changed; re-registered
`IntegrationFailed`	Warning	Flow or API error
`IntegrationRemoved`	Normal	Entry deleted (finalizer)

Reconfiguring¶

To change the integration configuration, update spec.configuration. The operator detects the hash change, removes the existing config entry, and runs a new Config Flow.

kubectl patch haint mqtt --type=merge \
  -p '{"spec":{"configuration":{"port":{"value":"1884"}}}}'

Limitations¶

Only single-step Config Flows are supported (MQTT, ESPHome, recorder, etc.)
Multi-step flows (ZHA, Zigbee2MQTT) require physical device interaction — not automatable
The operator passes spec.configuration values as-is; field names must match what HA expects for that domain

Deleting an integration¶

kubectl delete haint mqtt

The finalizer calls DELETE /api/config/config_entries/entry/{entryID} before removing the CR. If HA is unavailable, the finalizer completes anyway (best-effort).