Skip to content

Status Conditions

This document describes the standardized status conditions used across all Bindy CRDs.

Condition Types

All Bindy custom resources (Bind9Instance, DNSZone, and all DNS record types) use the following standardized condition types:

Ready

  • Description: Indicates whether the resource is fully operational and ready to serve its intended purpose
  • Common Use: Primary condition type used by all reconcilers
  • Status Values:
  • True: Resource is ready and operational
  • False: Resource is not ready (error or in progress)
  • Unknown: Status cannot be determined

Available

  • Description: Indicates whether the resource is available for use
  • Common Use: Used to distinguish between "ready" and "available" when resources may be ready but not yet serving traffic
  • Status Values:
  • True: Resource is available
  • False: Resource is not available
  • Unknown: Availability cannot be determined

Progressing

  • Description: Indicates whether the resource is currently being worked on
  • Common Use: During initial creation or updates
  • Status Values:
  • True: Resource is being created or updated
  • False: Resource is not currently progressing
  • Unknown: Progress status cannot be determined

Degraded

  • Description: Indicates that the resource is functioning but in a degraded state
  • Common Use: When some replicas are down but service continues, or when non-critical features are unavailable
  • Status Values:
  • True: Resource is degraded
  • False: Resource is not degraded
  • Unknown: Degradation status cannot be determined

Failed

  • Description: Indicates that the resource has failed and cannot fulfill its purpose
  • Common Use: Permanent failures that require intervention
  • Status Values:
  • True: Resource has failed
  • False: Resource has not failed
  • Unknown: Failure status cannot be determined

Condition Structure

All conditions follow this structure:

status:
  conditions:
    - type: Ready              # One of: Ready, Available, Progressing, Degraded, Failed
      status: "True"           # One of: "True", "False", "Unknown"
      reason: Ready            # Machine-readable reason (typically same as type)
      message: "Bind9Instance configured with 2 replicas"  # Human-readable message
      lastTransitionTime: "2024-11-26T10:00:00Z"          # RFC3339 timestamp
  observedGeneration: 1        # Generation last observed by operator
  # Resource-specific fields (replicas, recordCount, etc.)

Current Usage

Bind9Instance

  • Uses Ready condition type
  • Status True when Deployment, Service, and ConfigMap are successfully created
  • Status False when resource creation fails
  • Status False with reason ConfigurationInvalid when the rendered BIND9 configuration does not parse, so the operator did not publish it (the pods keep the last published configuration; see Configuration Not Published). A Bind9Cluster reports the same for its shared configuration
  • A Rollout condition appears while there is something to report about a staggered rollout (ADR-0018):
  • Rollout=False, reason RolloutQueued: a pod-template change waits for the instance named in the message (which shares a zone or a cluster with this one) to finish rolling out. Ready is unaffected: the current pods keep serving the previous configuration, and observedGeneration stays at the last generation applied;
  • Rollout=True, reason RolloutPeerStalled: the instance rolled out without waiting for the named instance, whose rollout exceeded its progressDeadlineSeconds
  • Additional status fields:
  • replicas: Total number of replicas
  • readyReplicas: Number of ready replicas

DNSZone

  • Uses Ready condition type
  • Status True when zone file is created and instances are matched
  • Status False when zone creation fails
  • Additional status fields:
  • recordCount: Number of records in the zone
  • observedGeneration: Last observed generation
  • records: List of associated DNS records (v1beta1 only)
    • Each entry contains apiVersion, kind, and name of the record resource
    • Automatically populated by record reconcilers after successful reconciliation
    • Provides real-time inventory of all DNS records associated with the zone
  • transferPeers: the zone-transfer peers last pushed to every server (ADR-0019): primaries (admitted primary pod IPs a secondary transfers from), secondaries (secondary pod IPs in every primary's allow-transfer) and notify (secondary Service ClusterIPs in every primary's also-notify, port 53). Updated only once every server took the new lists.
  • Ready=True requires every secondary to have the zone loaded, not only configured. Degraded reasons from zone transfers: SecondaryNotLoaded (a secondary has the zone configured but no data; the message names the instance and endpoint), NotifyTargetPending (a secondary instance's Service has no ClusterIP yet, so NOTIFY has nowhere to go; rechecked every 3 s), TransferPeersNotUpdated (a primary's allow-transfer / also-notify could not be rewritten) and NoTransferSource (no primary pod has its zones loaded yet). Records: RecordDeletionPending (a deleted or unselected record's data is not yet confirmed gone from every pod that holds the zone).

DNS Records (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)

  • All use Ready condition type
  • Status True when record is successfully added to zone
  • Status False when record creation fails
  • Additional status fields:
  • observedGeneration: Last observed generation

Best Practices

  1. Always set the condition type: Use one of the five standardized types
  2. Include timestamps: Set lastTransitionTime when condition status changes
  3. Provide clear messages: The message field should be human-readable and actionable
  4. Use appropriate reasons: The reason field should be machine-readable and consistent
  5. Update observedGeneration: Always update to match the resource's current generation
  6. Multiple conditions: Resources can have multiple conditions simultaneously (e.g., Ready: True and Degraded: True)

Examples

Successful Bind9Instance

status:
  conditions:
    - type: Ready
      status: "True"
      reason: Ready
      message: "Bind9Instance configured with 2 replicas"
      lastTransitionTime: "2024-11-26T10:00:00Z"
  observedGeneration: 1
  replicas: 2
  readyReplicas: 2

Failed DNSZone

status:
  conditions:
    - type: Ready
      status: "False"
      reason: Failed
      message: "No Bind9Instances matched selector"
      lastTransitionTime: "2024-11-26T10:00:00Z"
  observedGeneration: 1
  recordCount: 0
  records: []

DNSZone with Associated Records (v1beta1)

status:
  conditions:
    - type: Ready
      status: "True"
      reason: Ready
      message: "Configured on 2 primary server(s)"
      lastTransitionTime: "2024-11-26T10:00:00Z"
  observedGeneration: 1
  recordCount: 4
  records:
    - apiVersion: bindy.firestoned.io/v1beta1
      kind: ARecord
      name: web-server
    - apiVersion: bindy.firestoned.io/v1beta1
      kind: AAAARecord
      name: web-server-ipv6
    - apiVersion: bindy.firestoned.io/v1beta1
      kind: CNAMERecord
      name: www-alias
    - apiVersion: bindy.firestoned.io/v1beta1
      kind: MXRecord
      name: mail-server

Note: The records field is only available in v1beta1 and provides real-time visibility into all DNS records associated with the zone.

Progressing Deployment

status:
  conditions:
    - type: Ready
      status: "False"
      reason: PartiallyReady
      message: "1/2 pods are ready"
      lastTransitionTime: "2024-11-26T10:00:00Z"
  observedGeneration: 2
  replicas: 2
  readyReplicas: 1

Validation

All condition types are enforced via CRD validation. Attempting to use a condition type not in the enum will result in a validation error:

$ kubectl apply -f invalid-condition.yaml
Error from server (Invalid): error when creating "invalid-condition.yaml":
Bind9Instance.bindy.firestoned.io "test" is invalid:
status.conditions[0].type: Unsupported value: "CustomType":
supported values: "Ready", "Available", "Progressing", "Degraded", "Failed"