1 // Package status provides common K8s status conditions, reasons, and other 2 // utilities for building controllers with consistent statuses that are compatible 3 // with kstatus (https://github.com/kubernetes-sigs/cli-utils/tree/master/pkg/kstatus). 4 // 5 // This is useful because there are community packages (eg, fluxcd/pkg/ssa) that 6 // leverage kstatus for aggregating status of batch operations, a common use case 7 // in many controllers. 8 // This package contains forked code from https://github.com/kubernetes-sigs/cli-utils/blob/master/pkg/kstatus/status/status.go 9 // so that our code can rely on consistent string constants without importing all 10 // of the dependencies in the kubernetes-sigs/cli-utils module. 11 package v1alpha1 12 13 // These constants define generic Condition types. 14 // 15 // from: https://github.com/fluxcd/pkg/blob/24666ee7787ac10b8dabadaf49d33f8d8c9e7f7e/apis/meta/conditions.go#L23 16 // 17 // The ReadyCondition SHOULD be implemented by all components' Kubernetes resources 18 // to indicate they have been fully reconciled by their respective reconciler. 19 // This MAY suffice for simple resources, e.g. a resource that just declares 20 // state once and is not expected to receive any updates afterwards. 21 // 22 // For Kubernetes resources that are expected to receive spec updates over time, 23 // take a longer time to reconcile, or deal with more complex logic in which for 24 // example a finite error state can be observed, it is RECOMMENDED to implement 25 // the StalledCondition and ReconcilingCondition. 26 // 27 // By doing this, observers making use of kstatus to determine the current state 28 // of the resource will have a better experience while they are e.g. waiting for 29 // a change to be reconciled, and will be able to stop waiting for a change if a 30 // StalledCondition is observed, without having to rely on a timeout. 31 // 32 // For more information on kstatus, see: 33 // https://github.com/kubernetes-sigs/cli-utils/blob/v0.25.0/pkg/kstatus/README.md 34 const ( 35 // ReadyCondition indicates the resource is ready and fully reconciled. 36 // If the Condition is False, the resource SHOULD be considered to be in the 37 // process of reconciling and not a representation of actual state. 38 ReadyCondition string = "Ready" 39 40 // StalledCondition indicates the reconciliation of the resource has stalled, 41 // e.g. because the controller has encountered an error during the reconcile 42 // process or it has made insufficient progress (timeout). The Condition 43 // adheres to an "abnormal-true" polarity pattern, and MUST only be present on 44 // the resource if theCondition is True. For more information about polarity 45 // patterns, see: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties 46 StalledCondition string = "Stalled" 47 48 // ReconcilingCondition indicates the controller is currently working on 49 // reconciling the latest changes. This MAY be True for multiple 50 // reconciliation attempts, e.g. when an transient error occurred. 51 // The Condition adheres to an "abnormal-true" polarity pattern, and MUST only 52 // be present on the resource if the Condition is True. 53 // For more information about polarity patterns, see: 54 // https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties 55 ReconcilingCondition string = "Reconciling" 56 ) 57 58 // These constants define generic Condition reasons. 59 // 60 // taken from: https://github.com/fluxcd/pkg/blob/24666ee7787ac10b8dabadaf49d33f8d8c9e7f7e/apis/meta/conditions.go#L62 61 // 62 // Making use of a generic Reason is RECOMMENDED whenever it can be applied to a 63 // Condition in which it provides sufficient context together with the type to 64 // summarize the meaning of the Condition cause. 65 // 66 // Where any of the generic Condition reasons does not suffice, components can 67 // introduce new reasons to their API specification, or use an arbitrary 68 // PascalCase string when setting the Condition. Declaration of domain common 69 // Condition reasons in the API specification is RECOMMENDED, as it eases 70 // observations for user and computer. 71 // 72 // For more information on Condition reason conventions, see: 73 // https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties 74 const ( 75 // SucceededReason indicates a condition or event observed a success, for 76 // example when declared desired state matches actual state, or a performed 77 // action succeeded. 78 // 79 // More information about the reason of success MAY be available as additional 80 // metadata in an attached message. 81 SucceededReason string = "Succeeded" 82 83 // FailedReason indicates a condition or event observed a failure, for 84 // example when declared state does not match actual state, or a performed 85 // action failed. 86 // 87 // More information about the reason of failure MAY be available as additional 88 // metadata in an attached message. 89 FailedReason string = "Failed" 90 91 // ProgressingReason indicates a condition or event observed progression, for 92 // example when the reconciliation of a resource or an action has started. 93 // 94 // When this reason is given, other conditions and types MAY no longer be 95 // considered as an up-to-date observation. Producers of the specific condition 96 // type or event SHOULD provide more information about the expectations and 97 // precise meaning in their API specification. 98 // 99 // More information about the reason or the current state of the progression 100 // MAY be available as additional metadata in an attached message. 101 ProgressingReason string = "Progressing" 102 ) 103 104 // These constants define dependency-specific Condition reasons, inspired by: 105 // https://cloud.google.com/config-connector/docs/how-to/monitoring-your-resources 106 const ( 107 // Occurs when a referenced resource is not ready. 108 DependencyNotReadyReason string = "DependencyNotReady" 109 110 // Occurs when a referenced resource or Kubernetes Secret is not found. 111 DependencyNotFoundReason string = "DependencyNotFound" 112 113 // Occurs when a reference is invalid. 114 // For example, suppose a resource that references a Kubernetes Secret. 115 // If the Secret exists, but if it does not contain the key that is being referenced, then the reference is said to be invalid. 116 DependencyInvalidReason string = "DependencyInvalid" 117 ) 118