github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/site/reference/schema/crd-status-convention/README.md (about)

     1  # CRD Status Convention
     2  
     3  To enable kpt to calculate the [reconcile status] for CRDs, this document
     4  provides additional conventions for status conditions following the [Kubernetes
     5  API Guideline]. Custom controllers should use the following conditions types to
     6  signal whether a resource has been fully reconciled, and whether it has
     7  encountered any problems:
     8  
     9  - `Reconciling`: Indicates that the resource does not yet match its spec. i.e.
    10    the desired state as expressed in the resource spec object has not been fully
    11    realized in the cluster. A value of `"True"` means the controller is in the
    12    process of reconciling the resource while a value of `"False"` means there are
    13    no work left for the controller.
    14  - `Stalled`: Indicates that the controller is not able to make the expected
    15    progress towards reconciling the resource. The cause of this status can be
    16    either that the controller observes an actual problem (like a pod not being
    17    able to start), or that something is taking longer than expected (similar to
    18    the `progressDeadlineSeconds` timeout on Deployments). If this condition is
    19    `"True"`, it should be interpreted that something might be wrong. It does not
    20    mean that the resource will never be reconciled. Most process in Kubernetes
    21    retry forever, so this should not be considered a terminal state.
    22  
    23  CRDs should also set the `observedGeneration` field in the status object, a
    24  pattern already common in the built-in types. The controller should update this
    25  field every time it sees a new generation of the resource. This allows the kpt
    26  library to distinguish between resources that do not have any conditions set
    27  because they are fully reconciled, from resources that have no conditions set
    28  because they have just been created.
    29  
    30  An example of a resource where the latest change has been observed by the
    31  controller which is currently in the process of reconciling would be:
    32  
    33  ```yaml
    34  apiVersion: example.com
    35  kind: Foo
    36  metadata:
    37    generation: 12
    38    name: bar
    39  spec:
    40    replicas: 1
    41  status:
    42    observedGeneration: 12
    43    conditions:
    44      - lastTransitionTime: "2020-03-25T21:20:38Z"
    45        lastUpdateTime: "2020-03-25T21:20:38Z"
    46        message: Resource is reconciling
    47        reason: Reconciling
    48        status: "True"
    49        type: Reconciling
    50      - lastTransitionTime: "2020-03-25T21:20:27Z"
    51        lastUpdateTime: "2020-03-25T21:20:39Z"
    52        status: "False"
    53        type: Stalled
    54  ```
    55  
    56  The calculated reconcile status for this resource is `InProgress`.
    57  
    58  [kubernetes api guideline]:
    59    https://www.google.com/url?q=https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md%23typical-status-properties&sa=D&ust=1585160635349000&usg=AFQjCNE3ncANdus3xckLj3fkeupwFUoABw
    60  [reconcile status]: /book/06-deploying-packages/?id=reconcile-status