1 /* 2 Copyright 2022 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 v2beta1 18 19 import ( 20 v1 "k8s.io/apimachinery/pkg/apis/meta/v1" 21 ) 22 23 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 24 // +k8s:prerelease-lifecycle-gen:introduced=1.26 25 // +k8s:prerelease-lifecycle-gen:deprecated=1.32 26 // +k8s:prerelease-lifecycle-gen:removed=1.35 27 // The deprecate and remove versions stated above are rough estimates and may be subject to change. We are estimating v2 types will be available in 1.28 and will support 4 versions where both v2beta1 and v2 are supported before deprecation. 28 29 // APIGroupDiscoveryList is a resource containing a list of APIGroupDiscovery. 30 // This is one of the types able to be returned from the /api and /apis endpoint and contains an aggregated 31 // list of API resources (built-ins, Custom Resource Definitions, resources from aggregated servers) 32 // that a cluster supports. 33 type APIGroupDiscoveryList struct { 34 v1.TypeMeta `json:",inline"` 35 // ResourceVersion will not be set, because this does not have a replayable ordering among multiple apiservers. 36 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 37 // +optional 38 v1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 39 // items is the list of groups for discovery. The groups are listed in priority order. 40 Items []APIGroupDiscovery `json:"items" protobuf:"bytes,2,rep,name=items"` 41 } 42 43 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 44 // +k8s:prerelease-lifecycle-gen:introduced=1.26 45 // +k8s:prerelease-lifecycle-gen:deprecated=1.32 46 // +k8s:prerelease-lifecycle-gen:removed=1.35 47 // The deprecate and remove versions stated above are rough estimates and may be subject to change. We are estimating v2 types will be available in 1.28 and will support 4 versions where both v2beta1 and v2 are supported before deprecation. 48 49 // APIGroupDiscovery holds information about which resources are being served for all version of the API Group. 50 // It contains a list of APIVersionDiscovery that holds a list of APIResourceDiscovery types served for a version. 51 // Versions are in descending order of preference, with the first version being the preferred entry. 52 type APIGroupDiscovery struct { 53 v1.TypeMeta `json:",inline"` 54 // Standard object's metadata. 55 // The only field completed will be name. For instance, resourceVersion will be empty. 56 // name is the name of the API group whose discovery information is presented here. 57 // name is allowed to be "" to represent the legacy, ungroupified resources. 58 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 59 // +optional 60 v1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 61 // versions are the versions supported in this group. They are sorted in descending order of preference, 62 // with the preferred version being the first entry. 63 // +listType=map 64 // +listMapKey=version 65 Versions []APIVersionDiscovery `json:"versions,omitempty" protobuf:"bytes,2,rep,name=versions"` 66 } 67 68 // APIVersionDiscovery holds a list of APIResourceDiscovery types that are served for a particular version within an API Group. 69 type APIVersionDiscovery struct { 70 // version is the name of the version within a group version. 71 Version string `json:"version" protobuf:"bytes,1,opt,name=version"` 72 // resources is a list of APIResourceDiscovery objects for the corresponding group version. 73 // +listType=map 74 // +listMapKey=resource 75 Resources []APIResourceDiscovery `json:"resources,omitempty" protobuf:"bytes,2,rep,name=resources"` 76 // freshness marks whether a group version's discovery document is up to date. 77 // "Current" indicates the discovery document was recently 78 // refreshed. "Stale" indicates the discovery document could not 79 // be retrieved and the returned discovery document may be 80 // significantly out of date. Clients that require the latest 81 // version of the discovery information be retrieved before 82 // performing an operation should not use the aggregated document 83 Freshness DiscoveryFreshness `json:"freshness,omitempty" protobuf:"bytes,3,opt,name=freshness"` 84 } 85 86 // APIResourceDiscovery provides information about an API resource for discovery. 87 type APIResourceDiscovery struct { 88 // resource is the plural name of the resource. This is used in the URL path and is the unique identifier 89 // for this resource across all versions in the API group. 90 // Resources with non-empty groups are located at /apis/<APIGroupDiscovery.objectMeta.name>/<APIVersionDiscovery.version>/<APIResourceDiscovery.Resource> 91 // Resources with empty groups are located at /api/v1/<APIResourceDiscovery.Resource> 92 Resource string `json:"resource" protobuf:"bytes,1,opt,name=resource"` 93 // responseKind describes the group, version, and kind of the serialization schema for the object type this endpoint typically returns. 94 // APIs may return other objects types at their discretion, such as error conditions, requests for alternate representations, or other operation specific behavior. 95 // This value will be null or empty if an APIService reports subresources but supports no operations on the parent resource 96 ResponseKind *v1.GroupVersionKind `json:"responseKind,omitempty" protobuf:"bytes,2,opt,name=responseKind"` 97 // scope indicates the scope of a resource, either Cluster or Namespaced 98 Scope ResourceScope `json:"scope" protobuf:"bytes,3,opt,name=scope"` 99 // singularResource is the singular name of the resource. This allows clients to handle plural and singular opaquely. 100 // For many clients the singular form of the resource will be more understandable to users reading messages and should be used when integrating the name of the resource into a sentence. 101 // The command line tool kubectl, for example, allows use of the singular resource name in place of plurals. 102 // The singular form of a resource should always be an optional element - when in doubt use the canonical resource name. 103 SingularResource string `json:"singularResource" protobuf:"bytes,4,opt,name=singularResource"` 104 // verbs is a list of supported API operation types (this includes 105 // but is not limited to get, list, watch, create, update, patch, 106 // delete, deletecollection, and proxy). 107 // +listType=set 108 Verbs []string `json:"verbs" protobuf:"bytes,5,opt,name=verbs"` 109 // shortNames is a list of suggested short names of the resource. 110 // +listType=set 111 ShortNames []string `json:"shortNames,omitempty" protobuf:"bytes,6,rep,name=shortNames"` 112 // categories is a list of the grouped resources this resource belongs to (e.g. 'all'). 113 // Clients may use this to simplify acting on multiple resource types at once. 114 // +listType=set 115 Categories []string `json:"categories,omitempty" protobuf:"bytes,7,rep,name=categories"` 116 // subresources is a list of subresources provided by this resource. Subresources are located at /apis/<APIGroupDiscovery.objectMeta.name>/<APIVersionDiscovery.version>/<APIResourceDiscovery.Resource>/name-of-instance/<APIResourceDiscovery.subresources[i].subresource> 117 // +listType=map 118 // +listMapKey=subresource 119 Subresources []APISubresourceDiscovery `json:"subresources,omitempty" protobuf:"bytes,8,rep,name=subresources"` 120 } 121 122 // ResourceScope is an enum defining the different scopes available to a resource. 123 type ResourceScope string 124 125 const ( 126 ScopeCluster ResourceScope = "Cluster" 127 ScopeNamespace ResourceScope = "Namespaced" 128 ) 129 130 // DiscoveryFreshness is an enum defining whether the Discovery document published by an apiservice is up to date (fresh). 131 type DiscoveryFreshness string 132 133 const ( 134 DiscoveryFreshnessCurrent DiscoveryFreshness = "Current" 135 DiscoveryFreshnessStale DiscoveryFreshness = "Stale" 136 ) 137 138 // APISubresourceDiscovery provides information about an API subresource for discovery. 139 type APISubresourceDiscovery struct { 140 // subresource is the name of the subresource. This is used in the URL path and is the unique identifier 141 // for this resource across all versions. 142 Subresource string `json:"subresource" protobuf:"bytes,1,opt,name=subresource"` 143 // responseKind describes the group, version, and kind of the serialization schema for the object type this endpoint typically returns. 144 // Some subresources do not return normal resources, these will have null or empty return types. 145 ResponseKind *v1.GroupVersionKind `json:"responseKind,omitempty" protobuf:"bytes,2,opt,name=responseKind"` 146 // acceptedTypes describes the kinds that this endpoint accepts. 147 // Subresources may accept the standard content types or define 148 // custom negotiation schemes. The list may not be exhaustive for 149 // all operations. 150 // +listType=map 151 // +listMapKey=group 152 // +listMapKey=version 153 // +listMapKey=kind 154 AcceptedTypes []v1.GroupVersionKind `json:"acceptedTypes,omitempty" protobuf:"bytes,3,rep,name=acceptedTypes"` 155 // verbs is a list of supported API operation types (this includes 156 // but is not limited to get, list, watch, create, update, patch, 157 // delete, deletecollection, and proxy). Subresources may define 158 // custom verbs outside the standard Kubernetes verb set. Clients 159 // should expect the behavior of standard verbs to align with 160 // Kubernetes interaction conventions. 161 // +listType=set 162 Verbs []string `json:"verbs" protobuf:"bytes,4,opt,name=verbs"` 163 } 164