1 /* 2 Copyright 2017 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 apiextensions 18 19 import ( 20 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 ) 22 23 // ConversionStrategyType describes different conversion types. 24 type ConversionStrategyType string 25 26 const ( 27 // NoneConverter is a converter that only sets apiversion of the CR and leave everything else unchanged. 28 NoneConverter ConversionStrategyType = "None" 29 // WebhookConverter is a converter that calls to an external webhook to convert the CR. 30 WebhookConverter ConversionStrategyType = "Webhook" 31 ) 32 33 // CustomResourceDefinitionSpec describes how a user wants their resource to appear 34 type CustomResourceDefinitionSpec struct { 35 // Group is the group this resource belongs in 36 Group string 37 // Version is the version this resource belongs in 38 // Should be always first item in Versions field if provided. 39 // Optional, but at least one of Version or Versions must be set. 40 // Deprecated: Please use `Versions`. 41 Version string 42 // Names are the names used to describe this custom resource 43 Names CustomResourceDefinitionNames 44 // Scope indicates whether this resource is cluster or namespace scoped. Default is namespaced 45 Scope ResourceScope 46 // Validation describes the validation methods for CustomResources 47 // Optional, the global validation schema for all versions. 48 // Top-level and per-version schemas are mutually exclusive. 49 // +optional 50 Validation *CustomResourceValidation 51 // Subresources describes the subresources for CustomResource 52 // Optional, the global subresources for all versions. 53 // Top-level and per-version subresources are mutually exclusive. 54 // +optional 55 Subresources *CustomResourceSubresources 56 // Versions is the list of all supported versions for this resource. 57 // If Version field is provided, this field is optional. 58 // Validation: All versions must use the same validation schema for now. i.e., top 59 // level Validation field is applied to all of these versions. 60 // Order: The version name will be used to compute the order. 61 // If the version string is "kube-like", it will sort above non "kube-like" version strings, which are ordered 62 // lexicographically. "Kube-like" versions start with a "v", then are followed by a number (the major version), 63 // then optionally the string "alpha" or "beta" and another number (the minor version). These are sorted first 64 // by GA > beta > alpha (where GA is a version with no suffix such as beta or alpha), and then by comparing 65 // major version, then minor version. An example sorted list of versions: 66 // v10, v2, v1, v11beta2, v10beta3, v3beta1, v12alpha1, v11alpha2, foo1, foo10. 67 Versions []CustomResourceDefinitionVersion 68 // AdditionalPrinterColumns are additional columns shown e.g. in kubectl next to the name. Defaults to a created-at column. 69 // Optional, the global columns for all versions. 70 // Top-level and per-version columns are mutually exclusive. 71 // +optional 72 AdditionalPrinterColumns []CustomResourceColumnDefinition 73 // selectableFields specifies paths to fields that may be used as field selectors. 74 // A maximum of 8 selectable fields are allowed. 75 // See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors 76 // Top-level and per-version columns are mutually exclusive. 77 // +optional 78 SelectableFields []SelectableField 79 80 // `conversion` defines conversion settings for the CRD. 81 Conversion *CustomResourceConversion 82 83 // preserveUnknownFields disables pruning of object fields which are not 84 // specified in the OpenAPI schema. apiVersion, kind, metadata and known 85 // fields inside metadata are always preserved. 86 // Defaults to true in v1beta and will default to false in v1. 87 PreserveUnknownFields *bool 88 } 89 90 // CustomResourceConversion describes how to convert different versions of a CR. 91 type CustomResourceConversion struct { 92 // `strategy` specifies the conversion strategy. Allowed values are: 93 // - `None`: The converter only change the apiVersion and would not touch any other field in the CR. 94 // - `Webhook`: API Server will call to an external webhook to do the conversion. Additional information 95 // is needed for this option. This requires spec.preserveUnknownFields to be false. 96 Strategy ConversionStrategyType 97 98 // `webhookClientConfig` is the instructions for how to call the webhook if strategy is `Webhook`. 99 WebhookClientConfig *WebhookClientConfig 100 101 // ConversionReviewVersions is an ordered list of preferred `ConversionReview` 102 // versions the Webhook expects. API server will try to use first version in 103 // the list which it supports. If none of the versions specified in this list 104 // supported by API server, conversion will fail for this object. 105 // If a persisted Webhook configuration specifies allowed versions and does not 106 // include any versions known to the API Server, calls to the webhook will fail. 107 // +optional 108 ConversionReviewVersions []string 109 } 110 111 // WebhookClientConfig contains the information to make a TLS 112 // connection with the webhook. It has the same field as admissionregistration.internal.WebhookClientConfig. 113 type WebhookClientConfig struct { 114 // `url` gives the location of the webhook, in standard URL form 115 // (`scheme://host:port/path`). Exactly one of `url` or `service` 116 // must be specified. 117 // 118 // The `host` should not refer to a service running in the cluster; use 119 // the `service` field instead. The host might be resolved via external 120 // DNS in some apiservers (e.g., `kube-apiserver` cannot resolve 121 // in-cluster DNS as that would be a layering violation). `host` may 122 // also be an IP address. 123 // 124 // Please note that using `localhost` or `127.0.0.1` as a `host` is 125 // risky unless you take great care to run this webhook on all hosts 126 // which run an apiserver which might need to make calls to this 127 // webhook. Such installs are likely to be non-portable, i.e., not easy 128 // to turn up in a new cluster. 129 // 130 // The scheme must be "https"; the URL must begin with "https://". 131 // 132 // A path is optional, and if present may be any string permissible in 133 // a URL. You may use the path to pass an arbitrary string to the 134 // webhook, for example, a cluster identifier. 135 // 136 // Attempting to use a user or basic auth e.g. "user:password@" is not 137 // allowed. Fragments ("#...") and query parameters ("?...") are not 138 // allowed, either. 139 // 140 // +optional 141 URL *string 142 143 // `service` is a reference to the service for this webhook. Either 144 // `service` or `url` must be specified. 145 // 146 // If the webhook is running within the cluster, then you should use `service`. 147 // 148 // +optional 149 Service *ServiceReference 150 151 // `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. 152 // If unspecified, system trust roots on the apiserver are used. 153 // +optional 154 CABundle []byte 155 } 156 157 // ServiceReference holds a reference to Service.legacy.k8s.io 158 type ServiceReference struct { 159 // `namespace` is the namespace of the service. 160 // Required 161 Namespace string 162 // `name` is the name of the service. 163 // Required 164 Name string 165 166 // `path` is an optional URL path which will be sent in any request to 167 // this service. 168 // +optional 169 Path *string 170 171 // If specified, the port on the service that hosting webhook. 172 // `port` should be a valid port number (1-65535, inclusive). 173 // +optional 174 Port int32 175 } 176 177 // CustomResourceDefinitionVersion describes a version for CRD. 178 type CustomResourceDefinitionVersion struct { 179 // Name is the version name, e.g. “v1”, “v2beta1”, etc. 180 Name string 181 // Served is a flag enabling/disabling this version from being served via REST APIs 182 Served bool 183 // Storage flags the version as storage version. There must be exactly one flagged 184 // as storage version. 185 Storage bool 186 // deprecated indicates this version of the custom resource API is deprecated. 187 // When set to true, API requests to this version receive a warning header in the server response. 188 // Defaults to false. 189 Deprecated bool 190 // deprecationWarning overrides the default warning returned to API clients. 191 // May only be set when `deprecated` is true. 192 // The default warning indicates this version is deprecated and recommends use 193 // of the newest served version of equal or greater stability, if one exists. 194 DeprecationWarning *string 195 // Schema describes the schema for CustomResource used in validation, pruning, and defaulting. 196 // Top-level and per-version schemas are mutually exclusive. 197 // Per-version schemas must not all be set to identical values (top-level validation schema should be used instead) 198 // This field is alpha-level and is only honored by servers that enable the CustomResourceWebhookConversion feature. 199 // +optional 200 Schema *CustomResourceValidation 201 // Subresources describes the subresources for CustomResource 202 // Top-level and per-version subresources are mutually exclusive. 203 // Per-version subresources must not all be set to identical values (top-level subresources should be used instead) 204 // This field is alpha-level and is only honored by servers that enable the CustomResourceWebhookConversion feature. 205 // +optional 206 Subresources *CustomResourceSubresources 207 // AdditionalPrinterColumns are additional columns shown e.g. in kubectl next to the name. Defaults to a created-at column. 208 // Top-level and per-version columns are mutually exclusive. 209 // Per-version columns must not all be set to identical values (top-level columns should be used instead) 210 // This field is alpha-level and is only honored by servers that enable the CustomResourceWebhookConversion feature. 211 // NOTE: CRDs created prior to 1.13 populated the top-level additionalPrinterColumns field by default. To apply an 212 // update that changes to per-version additionalPrinterColumns, the top-level additionalPrinterColumns field must 213 // be explicitly set to null 214 // +optional 215 AdditionalPrinterColumns []CustomResourceColumnDefinition 216 217 // selectableFields specifies paths to fields that may be used as field selectors. 218 // A maximum of 8 selectable fields are allowed. 219 // See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors 220 // +optional 221 SelectableFields []SelectableField 222 } 223 224 // SelectableField specifies the JSON path of a field that may be used with field selectors. 225 type SelectableField struct { 226 // jsonPath is a simple JSON path which is evaluated against each custom resource to produce a 227 // field selector value. 228 // Only JSON paths without the array notation are allowed. 229 // Must point to a field of type string, boolean or integer. Types with enum values 230 // and strings with formats are allowed. 231 // If jsonPath refers to absent field in a resource, the jsonPath evaluates to an empty string. 232 // Must not point to metdata fields. 233 // Required. 234 JSONPath string 235 } 236 237 // CustomResourceColumnDefinition specifies a column for server side printing. 238 type CustomResourceColumnDefinition struct { 239 // name is a human readable name for the column. 240 Name string 241 // type is an OpenAPI type definition for this column. 242 // See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more. 243 Type string 244 // format is an optional OpenAPI type definition for this column. The 'name' format is applied 245 // to the primary identifier column to assist in clients identifying column is the resource name. 246 // See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more. 247 Format string 248 // description is a human readable description of this column. 249 Description string 250 // priority is an integer defining the relative importance of this column compared to others. Lower 251 // numbers are considered higher priority. Columns that may be omitted in limited space scenarios 252 // should be given a higher priority. 253 Priority int32 254 255 // JSONPath is a simple JSON path, i.e. without array notation. 256 JSONPath string 257 } 258 259 // CustomResourceDefinitionNames indicates the names to serve this CustomResourceDefinition 260 type CustomResourceDefinitionNames struct { 261 // Plural is the plural name of the resource to serve. It must match the name of the CustomResourceDefinition-registration 262 // too: plural.group and it must be all lowercase. 263 Plural string 264 // Singular is the singular name of the resource. It must be all lowercase Defaults to lowercased <kind> 265 Singular string 266 // ShortNames are short names for the resource. It must be all lowercase. 267 ShortNames []string 268 // Kind is the serialized kind of the resource. It is normally CamelCase and singular. 269 Kind string 270 // ListKind is the serialized kind of the list for this resource. Defaults to <kind>List. 271 ListKind string 272 // Categories is a list of grouped resources custom resources belong to (e.g. 'all') 273 // +optional 274 Categories []string 275 } 276 277 // ResourceScope is an enum defining the different scopes available to a custom resource 278 type ResourceScope string 279 280 const ( 281 ClusterScoped ResourceScope = "Cluster" 282 NamespaceScoped ResourceScope = "Namespaced" 283 ) 284 285 type ConditionStatus string 286 287 // These are valid condition statuses. "ConditionTrue" means a resource is in the condition. 288 // "ConditionFalse" means a resource is not in the condition. "ConditionUnknown" means kubernetes 289 // can't decide if a resource is in the condition or not. In the future, we could add other 290 // intermediate conditions, e.g. ConditionDegraded. 291 const ( 292 ConditionTrue ConditionStatus = "True" 293 ConditionFalse ConditionStatus = "False" 294 ConditionUnknown ConditionStatus = "Unknown" 295 ) 296 297 // CustomResourceDefinitionConditionType is a valid value for CustomResourceDefinitionCondition.Type 298 type CustomResourceDefinitionConditionType string 299 300 const ( 301 // Established means that the resource has become active. A resource is established when all names are 302 // accepted without a conflict for the first time. A resource stays established until deleted, even during 303 // a later NamesAccepted due to changed names. Note that not all names can be changed. 304 Established CustomResourceDefinitionConditionType = "Established" 305 // NamesAccepted means the names chosen for this CustomResourceDefinition do not conflict with others in 306 // the group and are therefore accepted. 307 NamesAccepted CustomResourceDefinitionConditionType = "NamesAccepted" 308 // NonStructuralSchema means that one or more OpenAPI schema is not structural. 309 // 310 // A schema is structural if it specifies types for all values, with the only exceptions of those with 311 // - x-kubernetes-int-or-string: true — for fields which can be integer or string 312 // - x-kubernetes-preserve-unknown-fields: true — for raw, unspecified JSON values 313 // and there is no type, additionalProperties, default, nullable or x-kubernetes-* vendor extenions 314 // specified under allOf, anyOf, oneOf or not. 315 // 316 // Non-structural schemas will not be allowed anymore in v1 API groups. Moreover, new features will not be 317 // available for non-structural CRDs: 318 // - pruning 319 // - defaulting 320 // - read-only 321 // - OpenAPI publishing 322 // - webhook conversion 323 NonStructuralSchema CustomResourceDefinitionConditionType = "NonStructuralSchema" 324 // Terminating means that the CustomResourceDefinition has been deleted and is cleaning up. 325 Terminating CustomResourceDefinitionConditionType = "Terminating" 326 // KubernetesAPIApprovalPolicyConformant indicates that an API in *.k8s.io or *.kubernetes.io is or is not approved. For CRDs 327 // outside those groups, this condition will not be set. For CRDs inside those groups, the condition will 328 // be true if .metadata.annotations["api-approved.kubernetes.io"] is set to a URL, otherwise it will be false. 329 // See https://github.com/kubernetes/enhancements/pull/1111 for more details. 330 KubernetesAPIApprovalPolicyConformant CustomResourceDefinitionConditionType = "KubernetesAPIApprovalPolicyConformant" 331 ) 332 333 // CustomResourceDefinitionCondition contains details for the current condition of this pod. 334 type CustomResourceDefinitionCondition struct { 335 // Type is the type of the condition. Types include Established, NamesAccepted and Terminating. 336 Type CustomResourceDefinitionConditionType 337 // Status is the status of the condition. 338 // Can be True, False, Unknown. 339 Status ConditionStatus 340 // Last time the condition transitioned from one status to another. 341 // +optional 342 LastTransitionTime metav1.Time 343 // Unique, one-word, CamelCase reason for the condition's last transition. 344 // +optional 345 Reason string 346 // Human-readable message indicating details about last transition. 347 // +optional 348 Message string 349 } 350 351 // CustomResourceDefinitionStatus indicates the state of the CustomResourceDefinition 352 type CustomResourceDefinitionStatus struct { 353 // Conditions indicate state for particular aspects of a CustomResourceDefinition 354 // +listType=map 355 // +listMapKey=type 356 Conditions []CustomResourceDefinitionCondition 357 358 // AcceptedNames are the names that are actually being used to serve discovery 359 // They may be different than the names in spec. 360 AcceptedNames CustomResourceDefinitionNames 361 362 // StoredVersions are all versions of CustomResources that were ever persisted. Tracking these 363 // versions allows a migration path for stored versions in etcd. The field is mutable 364 // so the migration controller can first finish a migration to another version (i.e. 365 // that no old objects are left in the storage), and then remove the rest of the 366 // versions from this list. 367 // None of the versions in this list can be removed from the spec.Versions field. 368 StoredVersions []string 369 } 370 371 // CustomResourceCleanupFinalizer is the name of the finalizer which will delete instances of 372 // a CustomResourceDefinition 373 const CustomResourceCleanupFinalizer = "customresourcecleanup.apiextensions.k8s.io" 374 375 // +genclient 376 // +genclient:nonNamespaced 377 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 378 379 // CustomResourceDefinition represents a resource that should be exposed on the API server. Its name MUST be in the format 380 // <.spec.name>.<.spec.group>. 381 type CustomResourceDefinition struct { 382 metav1.TypeMeta 383 metav1.ObjectMeta 384 385 // Spec describes how the user wants the resources to appear 386 Spec CustomResourceDefinitionSpec 387 // Status indicates the actual state of the CustomResourceDefinition 388 Status CustomResourceDefinitionStatus 389 } 390 391 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 392 393 // CustomResourceDefinitionList is a list of CustomResourceDefinition objects. 394 type CustomResourceDefinitionList struct { 395 metav1.TypeMeta 396 metav1.ListMeta 397 398 // Items individual CustomResourceDefinitions 399 Items []CustomResourceDefinition 400 } 401 402 // CustomResourceValidation is a list of validation methods for CustomResources. 403 type CustomResourceValidation struct { 404 // OpenAPIV3Schema is the OpenAPI v3 schema to be validated against. 405 OpenAPIV3Schema *JSONSchemaProps 406 } 407 408 // CustomResourceSubresources defines the status and scale subresources for CustomResources. 409 type CustomResourceSubresources struct { 410 // Status denotes the status subresource for CustomResources 411 Status *CustomResourceSubresourceStatus 412 // Scale denotes the scale subresource for CustomResources 413 Scale *CustomResourceSubresourceScale 414 } 415 416 // CustomResourceSubresourceStatus defines how to serve the status subresource for CustomResources. 417 // Status is represented by the `.status` JSON path inside of a CustomResource. When set, 418 // * exposes a /status subresource for the custom resource 419 // * PUT requests to the /status subresource take a custom resource object, and ignore changes to anything except the status stanza 420 // * PUT/POST/PATCH requests to the custom resource ignore changes to the status stanza 421 type CustomResourceSubresourceStatus struct{} 422 423 // CustomResourceSubresourceScale defines how to serve the scale subresource for CustomResources. 424 type CustomResourceSubresourceScale struct { 425 // SpecReplicasPath defines the JSON path inside of a CustomResource that corresponds to Scale.Spec.Replicas. 426 // Only JSON paths without the array notation are allowed. 427 // Must be a JSON Path under .spec. 428 // If there is no value under the given path in the CustomResource, the /scale subresource will return an error on GET. 429 SpecReplicasPath string 430 // StatusReplicasPath defines the JSON path inside of a CustomResource that corresponds to Scale.Status.Replicas. 431 // Only JSON paths without the array notation are allowed. 432 // Must be a JSON Path under .status. 433 // If there is no value under the given path in the CustomResource, the status replica value in the /scale subresource 434 // will default to 0. 435 StatusReplicasPath string 436 // LabelSelectorPath defines the JSON path inside of a CustomResource that corresponds to Scale.Status.Selector. 437 // Only JSON paths without the array notation are allowed. 438 // Must be a JSON Path under .status or .spec. 439 // Must be set to work with HPA. 440 // The field pointed by this JSON path must be a string field (not a complex selector struct) 441 // which contains a serialized label selector in string form. 442 // More info: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions#scale-subresource 443 // If there is no value under the given path in the CustomResource, the status label selector value in the /scale 444 // subresource will default to the empty string. 445 // +optional 446 LabelSelectorPath *string 447 } 448