1 /* 2 Copyright 2020 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package v1 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 ) 22 23 // +genclient 24 // +genclient:nonNamespaced 25 // +kubebuilder:object:root=true 26 // +kubebuilder:resource:categories=gateway-api,scope=Cluster,shortName=gc 27 // +kubebuilder:subresource:status 28 // +kubebuilder:printcolumn:name="Controller",type=string,JSONPath=`.spec.controllerName` 29 // +kubebuilder:printcolumn:name="Accepted",type=string,JSONPath=`.status.conditions[?(@.type=="Accepted")].status` 30 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` 31 // +kubebuilder:printcolumn:name="Description",type=string,JSONPath=`.spec.description`,priority=1 32 33 // GatewayClass describes a class of Gateways available to the user for creating 34 // Gateway resources. 35 // 36 // It is recommended that this resource be used as a template for Gateways. This 37 // means that a Gateway is based on the state of the GatewayClass at the time it 38 // was created and changes to the GatewayClass or associated parameters are not 39 // propagated down to existing Gateways. This recommendation is intended to 40 // limit the blast radius of changes to GatewayClass or associated parameters. 41 // If implementations choose to propagate GatewayClass changes to existing 42 // Gateways, that MUST be clearly documented by the implementation. 43 // 44 // Whenever one or more Gateways are using a GatewayClass, implementations SHOULD 45 // add the `gateway-exists-finalizer.gateway.networking.k8s.io` finalizer on the 46 // associated GatewayClass. This ensures that a GatewayClass associated with a 47 // Gateway is not deleted while in use. 48 // 49 // GatewayClass is a Cluster level resource. 50 type GatewayClass struct { 51 metav1.TypeMeta `json:",inline"` 52 metav1.ObjectMeta `json:"metadata,omitempty"` 53 54 // Spec defines the desired state of GatewayClass. 55 Spec GatewayClassSpec `json:"spec"` 56 57 // Status defines the current state of GatewayClass. 58 // 59 // Implementations MUST populate status on all GatewayClass resources which 60 // specify their controller name. 61 // 62 // +kubebuilder:default={conditions: {{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Waiting", lastTransitionTime: "1970-01-01T00:00:00Z"}}} 63 Status GatewayClassStatus `json:"status,omitempty"` 64 } 65 66 const ( 67 // GatewayClassFinalizerGatewaysExist should be added as a finalizer to the 68 // GatewayClass whenever there are provisioned Gateways using a 69 // GatewayClass. 70 GatewayClassFinalizerGatewaysExist = "gateway-exists-finalizer.gateway.networking.k8s.io" 71 ) 72 73 // GatewayClassSpec reflects the configuration of a class of Gateways. 74 type GatewayClassSpec struct { 75 // ControllerName is the name of the controller that is managing Gateways of 76 // this class. The value of this field MUST be a domain prefixed path. 77 // 78 // Example: "example.net/gateway-controller". 79 // 80 // This field is not mutable and cannot be empty. 81 // 82 // Support: Core 83 // 84 // +kubebuilder:validation:XValidation:message="Value is immutable",rule="self == oldSelf" 85 ControllerName GatewayController `json:"controllerName"` 86 87 // ParametersRef is a reference to a resource that contains the configuration 88 // parameters corresponding to the GatewayClass. This is optional if the 89 // controller does not require any additional configuration. 90 // 91 // ParametersRef can reference a standard Kubernetes resource, i.e. ConfigMap, 92 // or an implementation-specific custom resource. The resource can be 93 // cluster-scoped or namespace-scoped. 94 // 95 // If the referent cannot be found, the GatewayClass's "InvalidParameters" 96 // status condition will be true. 97 // 98 // Support: Implementation-specific 99 // 100 // +optional 101 ParametersRef *ParametersReference `json:"parametersRef,omitempty"` 102 103 // Description helps describe a GatewayClass with more details. 104 // 105 // +kubebuilder:validation:MaxLength=64 106 // +optional 107 Description *string `json:"description,omitempty"` 108 } 109 110 // ParametersReference identifies an API object containing controller-specific 111 // configuration resource within the cluster. 112 type ParametersReference struct { 113 // Group is the group of the referent. 114 Group Group `json:"group"` 115 116 // Kind is kind of the referent. 117 Kind Kind `json:"kind"` 118 119 // Name is the name of the referent. 120 // 121 // +kubebuilder:validation:MinLength=1 122 // +kubebuilder:validation:MaxLength=253 123 Name string `json:"name"` 124 125 // Namespace is the namespace of the referent. 126 // This field is required when referring to a Namespace-scoped resource and 127 // MUST be unset when referring to a Cluster-scoped resource. 128 // 129 // +optional 130 Namespace *Namespace `json:"namespace,omitempty"` 131 } 132 133 // GatewayClassConditionType is the type for status conditions on 134 // Gateway resources. This type should be used with the 135 // GatewayClassStatus.Conditions field. 136 type GatewayClassConditionType string 137 138 // GatewayClassConditionReason defines the set of reasons that explain why a 139 // particular GatewayClass condition type has been raised. 140 type GatewayClassConditionReason string 141 142 const ( 143 // This condition indicates whether the GatewayClass has been accepted by 144 // the controller requested in the `spec.controller` field. 145 // 146 // This condition defaults to Unknown, and MUST be set by a controller when 147 // it sees a GatewayClass using its controller string. The status of this 148 // condition MUST be set to True if the controller will support provisioning 149 // Gateways using this class. Otherwise, this status MUST be set to False. 150 // If the status is set to False, the controller SHOULD set a Message and 151 // Reason as an explanation. 152 // 153 // Possible reasons for this condition to be true are: 154 // 155 // * "Accepted" 156 // 157 // Possible reasons for this condition to be False are: 158 // 159 // * "InvalidParameters" 160 // * "UnsupportedVersion" 161 // 162 // Possible reasons for this condition to be Unknown are: 163 // 164 // * "Pending" 165 // 166 // Controllers should prefer to use the values of GatewayClassConditionReason 167 // for the corresponding Reason, where appropriate. 168 GatewayClassConditionStatusAccepted GatewayClassConditionType = "Accepted" 169 170 // This reason is used with the "Accepted" condition when the condition is 171 // true. 172 GatewayClassReasonAccepted GatewayClassConditionReason = "Accepted" 173 174 // This reason is used with the "Accepted" condition when the 175 // GatewayClass was not accepted because the parametersRef field 176 // was invalid, with more detail in the message. 177 GatewayClassReasonInvalidParameters GatewayClassConditionReason = "InvalidParameters" 178 179 // This reason is used with the "Accepted" condition when the 180 // requested controller has not yet made a decision about whether 181 // to admit the GatewayClass. It is the default Reason on a new 182 // GatewayClass. 183 GatewayClassReasonPending GatewayClassConditionReason = "Pending" 184 185 // Deprecated: Use "Pending" instead. 186 GatewayClassReasonWaiting GatewayClassConditionReason = "Waiting" 187 ) 188 189 const ( 190 // This condition indicates whether the GatewayClass supports the version(s) 191 // of Gateway API CRDs present in the cluster. This condition MUST be set by 192 // a controller when it marks a GatewayClass "Accepted". 193 // 194 // The version of a Gateway API CRD is defined by the 195 // gateway.networking.k8s.io/bundle-version annotation on the CRD. If 196 // implementations detect any Gateway API CRDs that either do not have this 197 // annotation set, or have it set to a version that is not recognized or 198 // supported by the implementation, this condition MUST be set to false. 199 // 200 // Implementations MAY choose to either provide "best effort" support when 201 // an unrecognized CRD version is present. This would be communicated by 202 // setting the "Accepted" condition to true and the "SupportedVersion" 203 // condition to false. 204 // 205 // Alternatively, implementations MAY choose not to support CRDs with 206 // unrecognized versions. This would be communicated by setting the 207 // "Accepted" condition to false with the reason "UnsupportedVersions". 208 // 209 // Possible reasons for this condition to be true are: 210 // 211 // * "SupportedVersion" 212 // 213 // Possible reasons for this condition to be False are: 214 // 215 // * "UnsupportedVersion" 216 // 217 // Controllers should prefer to use the values of GatewayClassConditionReason 218 // for the corresponding Reason, where appropriate. 219 // 220 // <gateway:experimental> 221 GatewayClassConditionStatusSupportedVersion GatewayClassConditionType = "SupportedVersion" 222 223 // This reason is used with the "SupportedVersion" condition when the 224 // condition is true. 225 GatewayClassReasonSupportedVersion GatewayClassConditionReason = "SupportedVersion" 226 227 // This reason is used with the "SupportedVersion" or "Accepted" condition 228 // when the condition is false. A message SHOULD be included in this 229 // condition that includes the detected CRD version(s) present in the 230 // cluster and the CRD version(s) that are supported by the GatewayClass. 231 GatewayClassReasonUnsupportedVersion GatewayClassConditionReason = "UnsupportedVersion" 232 ) 233 234 // GatewayClassStatus is the current status for the GatewayClass. 235 type GatewayClassStatus struct { 236 // Conditions is the current status from the controller for 237 // this GatewayClass. 238 // 239 // Controllers should prefer to publish conditions using values 240 // of GatewayClassConditionType for the type of each Condition. 241 // 242 // +optional 243 // +listType=map 244 // +listMapKey=type 245 // +kubebuilder:validation:MaxItems=8 246 // +kubebuilder:default={{type: "Accepted", status: "Unknown", message: "Waiting for controller", reason: "Pending", lastTransitionTime: "1970-01-01T00:00:00Z"}} 247 Conditions []metav1.Condition `json:"conditions,omitempty"` 248 249 // SupportedFeatures is the set of features the GatewayClass support. 250 // It MUST be sorted in ascending alphabetical order. 251 // +optional 252 // +listType=set 253 // <gateway:experimental> 254 // +kubebuilder:validation:MaxItems=64 255 SupportedFeatures []SupportedFeature `json:"supportedFeatures,omitempty"` 256 } 257 258 // +kubebuilder:object:root=true 259 260 // GatewayClassList contains a list of GatewayClass 261 type GatewayClassList struct { 262 metav1.TypeMeta `json:",inline"` 263 metav1.ListMeta `json:"metadata,omitempty"` 264 Items []GatewayClass `json:"items"` 265 } 266 267 // SupportedFeature is used to describe distinct features that are covered by 268 // conformance tests. 269 // +kubebuilder:validation:Enum=Gateway;GatewayPort8080;GatewayStaticAddresses;HTTPRoute;HTTPRouteDestinationPortMatching;HTTPRouteHostRewrite;HTTPRouteMethodMatching;HTTPRoutePathRedirect;HTTPRoutePathRewrite;HTTPRoutePortRedirect;HTTPRouteQueryParamMatching;HTTPRouteRequestMirror;HTTPRouteRequestMultipleMirrors;HTTPRouteResponseHeaderModification;HTTPRouteSchemeRedirect;Mesh;ReferenceGrant;TLSRoute 270 type SupportedFeature string 271