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