1 package v1 2 3 import ( 4 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 5 "k8s.io/apimachinery/pkg/runtime" 6 ) 7 8 // MyOperatorResource is an example operator configuration type 9 // 10 // Compatibility level 4: No compatibility is provided, the API can change at any point for any reason. These capabilities should not be used by applications needing long term support. 11 // +openshift:compatibility-gen:internal 12 type MyOperatorResource struct { 13 metav1.TypeMeta `json:",inline"` 14 15 // metadata is the standard object's metadata. 16 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 17 metav1.ObjectMeta `json:"metadata"` 18 19 // +kubebuilder:validation:Required 20 // +required 21 Spec MyOperatorResourceSpec `json:"spec"` 22 Status MyOperatorResourceStatus `json:"status"` 23 } 24 25 type MyOperatorResourceSpec struct { 26 OperatorSpec `json:",inline"` 27 } 28 29 type MyOperatorResourceStatus struct { 30 OperatorStatus `json:",inline"` 31 } 32 33 // +kubebuilder:validation:Pattern=`^(Managed|Unmanaged|Force|Removed)$` 34 type ManagementState string 35 36 var ( 37 // Force means that the operator is actively managing its resources but will not block an upgrade 38 // if unmet prereqs exist. This state puts the operator at risk for unsuccessful upgrades 39 Force ManagementState = "Force" 40 // Managed means that the operator is actively managing its resources and trying to keep the component active. 41 // It will only upgrade the component if it is safe to do so 42 Managed ManagementState = "Managed" 43 // Unmanaged means that the operator will not take any action related to the component 44 // Some operators might not support this management state as it might damage the cluster and lead to manual recovery. 45 Unmanaged ManagementState = "Unmanaged" 46 // Removed means that the operator is actively managing its resources and trying to remove all traces of the component 47 // Some operators (like kube-apiserver-operator) might not support this management state as removing the API server will 48 // brick the cluster. 49 Removed ManagementState = "Removed" 50 ) 51 52 // OperatorSpec contains common fields operators need. It is intended to be anonymous included 53 // inside of the Spec struct for your particular operator. 54 type OperatorSpec struct { 55 // managementState indicates whether and how the operator should manage the component 56 ManagementState ManagementState `json:"managementState"` 57 58 // logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a 59 // simple way to manage coarse grained logging choices that operators have to interpret for their operands. 60 // 61 // Valid values are: "Normal", "Debug", "Trace", "TraceAll". 62 // Defaults to "Normal". 63 // +optional 64 // +kubebuilder:default=Normal 65 LogLevel LogLevel `json:"logLevel,omitempty"` 66 67 // operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a 68 // simple way to manage coarse grained logging choices that operators have to interpret for themselves. 69 // 70 // Valid values are: "Normal", "Debug", "Trace", "TraceAll". 71 // Defaults to "Normal". 72 // +optional 73 // +kubebuilder:default=Normal 74 OperatorLogLevel LogLevel `json:"operatorLogLevel,omitempty"` 75 76 // unsupportedConfigOverrides overrides the final configuration that was computed by the operator. 77 // Red Hat does not support the use of this field. 78 // Misuse of this field could lead to unexpected behavior or conflict with other configuration options. 79 // Seek guidance from the Red Hat support before using this field. 80 // Use of this property blocks cluster upgrades, it must be removed before upgrading your cluster. 81 // +optional 82 // +nullable 83 // +kubebuilder:pruning:PreserveUnknownFields 84 UnsupportedConfigOverrides runtime.RawExtension `json:"unsupportedConfigOverrides"` 85 86 // observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because 87 // it is an input to the level for the operator 88 // +optional 89 // +nullable 90 // +kubebuilder:pruning:PreserveUnknownFields 91 ObservedConfig runtime.RawExtension `json:"observedConfig"` 92 } 93 94 // +kubebuilder:validation:Enum="";Normal;Debug;Trace;TraceAll 95 type LogLevel string 96 97 var ( 98 // Normal is the default. Normal, working log information, everything is fine, but helpful notices for auditing or common operations. In kube, this is probably glog=2. 99 Normal LogLevel = "Normal" 100 101 // Debug is used when something went wrong. Even common operations may be logged, and less helpful but more quantity of notices. In kube, this is probably glog=4. 102 Debug LogLevel = "Debug" 103 104 // Trace is used when something went really badly and even more verbose logs are needed. Logging every function call as part of a common operation, to tracing execution of a query. In kube, this is probably glog=6. 105 Trace LogLevel = "Trace" 106 107 // TraceAll is used when something is broken at the level of API content/decoding. It will dump complete body content. If you turn this on in a production cluster 108 // prepare from serious performance issues and massive amounts of logs. In kube, this is probably glog=8. 109 TraceAll LogLevel = "TraceAll" 110 ) 111 112 type OperatorStatus struct { 113 // observedGeneration is the last generation change you've dealt with 114 // +optional 115 ObservedGeneration int64 `json:"observedGeneration,omitempty"` 116 117 // conditions is a list of conditions and their status 118 // +optional 119 Conditions []OperatorCondition `json:"conditions,omitempty"` 120 121 // version is the level this availability applies to 122 // +optional 123 Version string `json:"version,omitempty"` 124 125 // readyReplicas indicates how many replicas are ready and at the desired state 126 ReadyReplicas int32 `json:"readyReplicas"` 127 128 // generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. 129 // +optional 130 Generations []GenerationStatus `json:"generations,omitempty"` 131 } 132 133 // GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. 134 type GenerationStatus struct { 135 // group is the group of the thing you're tracking 136 Group string `json:"group"` 137 // resource is the resource type of the thing you're tracking 138 Resource string `json:"resource"` 139 // namespace is where the thing you're tracking is 140 Namespace string `json:"namespace"` 141 // name is the name of the thing you're tracking 142 Name string `json:"name"` 143 // lastGeneration is the last generation of the workload controller involved 144 LastGeneration int64 `json:"lastGeneration"` 145 // hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps 146 Hash string `json:"hash"` 147 } 148 149 var ( 150 // Available indicates that the operand is present and accessible in the cluster 151 OperatorStatusTypeAvailable = "Available" 152 // Progressing indicates that the operator is trying to transition the operand to a different state 153 OperatorStatusTypeProgressing = "Progressing" 154 // Degraded indicates that the operator (not the operand) is unable to fulfill the user intent 155 OperatorStatusTypeDegraded = "Degraded" 156 // PrereqsSatisfied indicates that the things this operator depends on are present and at levels compatible with the 157 // current and desired states. 158 OperatorStatusTypePrereqsSatisfied = "PrereqsSatisfied" 159 // Upgradeable indicates that the operator configuration itself (not prereqs) can be auto-upgraded by the CVO 160 OperatorStatusTypeUpgradeable = "Upgradeable" 161 ) 162 163 // OperatorCondition is just the standard condition fields. 164 type OperatorCondition struct { 165 Type string `json:"type"` 166 Status ConditionStatus `json:"status"` 167 LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty"` 168 Reason string `json:"reason,omitempty"` 169 Message string `json:"message,omitempty"` 170 } 171 172 type ConditionStatus string 173 174 const ( 175 ConditionTrue ConditionStatus = "True" 176 ConditionFalse ConditionStatus = "False" 177 ConditionUnknown ConditionStatus = "Unknown" 178 ) 179 180 // StaticPodOperatorSpec is spec for controllers that manage static pods. 181 type StaticPodOperatorSpec struct { 182 OperatorSpec `json:",inline"` 183 184 // forceRedeploymentReason can be used to force the redeployment of the operand by providing a unique string. 185 // This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work 186 // this time instead of failing again on the same config. 187 ForceRedeploymentReason string `json:"forceRedeploymentReason"` 188 189 // failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api 190 // -1 = unlimited, 0 or unset = 5 (default) 191 FailedRevisionLimit int32 `json:"failedRevisionLimit,omitempty"` 192 // succeededRevisionLimit is the number of successful static pod installer revisions to keep on disk and in the api 193 // -1 = unlimited, 0 or unset = 5 (default) 194 SucceededRevisionLimit int32 `json:"succeededRevisionLimit,omitempty"` 195 } 196 197 // StaticPodOperatorStatus is status for controllers that manage static pods. There are different needs because individual 198 // node status must be tracked. 199 type StaticPodOperatorStatus struct { 200 OperatorStatus `json:",inline"` 201 202 // latestAvailableRevision is the deploymentID of the most recent deployment 203 // +optional 204 LatestAvailableRevision int32 `json:"latestAvailableRevision,omitEmpty"` 205 206 // latestAvailableRevisionReason describe the detailed reason for the most recent deployment 207 // +optional 208 LatestAvailableRevisionReason string `json:"latestAvailableRevisionReason,omitEmpty"` 209 210 // nodeStatuses track the deployment values and errors across individual nodes 211 // +optional 212 NodeStatuses []NodeStatus `json:"nodeStatuses,omitempty"` 213 } 214 215 // NodeStatus provides information about the current state of a particular node managed by this operator. 216 type NodeStatus struct { 217 // nodeName is the name of the node 218 NodeName string `json:"nodeName"` 219 220 // currentRevision is the generation of the most recently successful deployment 221 CurrentRevision int32 `json:"currentRevision"` 222 // targetRevision is the generation of the deployment we're trying to apply 223 TargetRevision int32 `json:"targetRevision,omitempty"` 224 225 // lastFailedRevision is the generation of the deployment we tried and failed to deploy. 226 LastFailedRevision int32 `json:"lastFailedRevision,omitempty"` 227 // lastFailedTime is the time the last failed revision failed the last time. 228 LastFailedTime *metav1.Time `json:"lastFailedTime,omitempty"` 229 // lastFailedReason is a machine readable failure reason string. 230 LastFailedReason string `json:"lastFailedReason,omitempty"` 231 // lastFailedCount is how often the installer pod of the last failed revision failed. 232 LastFailedCount int `json:"lastFailedCount,omitempty"` 233 // lastFallbackCount is how often a fallback to a previous revision happened. 234 LastFallbackCount int `json:"lastFallbackCount,omitempty"` 235 // lastFailedRevisionErrors is a list of human readable errors during the failed deployment referenced in lastFailedRevision. 236 LastFailedRevisionErrors []string `json:"lastFailedRevisionErrors,omitempty"` 237 } 238