Documents
_index
_index
Type
External
Status
Published
Created
Feb 19, 2026
Updated
Feb 19, 2026
Source
View

To enable kpt to calculate the reconcile status for CRDs, this
document provides additional conventions for status conditions following the
Kubernetes API Guideline.
Custom controllers should use the following conditions types to signal whether a resource has been fully reconciled, and
whether it has encountered any problems:

  • Reconciling: Indicates that the resource does not yet match its spec. i.e.
    the desired state as expressed in the resource spec object has not been fully
    realized in the cluster. A value of "True" means the controller is in the
    process of reconciling the resource while a value of "False" means there are
    no work left for the controller.
  • Stalled: Indicates that the controller is not able to make the expected
    progress towards reconciling the resource. The cause of this status can be
    either that the controller observes an actual problem (like a pod not being
    able to start), or that something is taking longer than expected (similar to
    the progressDeadlineSeconds timeout on Deployments). If this condition is
    "True", it should be interpreted that something might be wrong. It does not
    mean that the resource will never be reconciled. Most process in Kubernetes
    retry forever, so this should not be considered a terminal state.

CRDs should also set the observedGeneration field in the status object, a
pattern already common in the built-in types. The controller should update this
field every time it sees a new generation of the resource. This allows the kpt
library to distinguish between resources that do not have any conditions set
because they are fully reconciled, from resources that have no conditions set
because they have just been created.

An example of a resource where the latest change has been observed by the
controller which is currently in the process of reconciling would be:

apiVersion: example.com
kind: Foo
metadata:
  generation: 12
  name: bar
spec:
  replicas: 1
status:
  observedGeneration: 12
  conditions:
    - lastTransitionTime: "2020-03-25T21:20:38Z"
      lastUpdateTime: "2020-03-25T21:20:38Z"
      message: Resource is reconciling
      reason: Reconciling
      status: "True"
      type: Reconciling
    - lastTransitionTime: "2020-03-25T21:20:27Z"
      lastUpdateTime: "2020-03-25T21:20:39Z"
      status: "False"
      type: Stalled

The calculated reconcile status for this resource is InProgress.