1package v1
  2
  3import "cue.dev/x/k8s.io/apimachinery/pkg/apis/meta/v1"
  4
  5// CertificateSigningRequest objects provide a mechanism to obtain x509
  6// certificates by submitting a certificate signing request, and having it
  7// asynchronously approved and issued.
  8//
  9// Kubelets use this API to obtain:
 10// 1. client certificates to authenticate to kube-apiserver (with the
 11// "kubernetes.io/kube-apiserver-client-kubelet" signerName).
 12// 2. serving certificates for TLS endpoints kube-apiserver can connect to
 13// securely (with the "kubernetes.io/kubelet-serving" signerName).
 14//
 15// This API can be used to request client certificates to authenticate to
 16// kube-apiserver (with the "kubernetes.io/kube-apiserver-client" signerName),
 17// or to obtain certificates from custom non-Kubernetes signers.
 18#CertificateSigningRequest: {
 19	// APIVersion defines the versioned schema of this representation of an object.
 20	// Servers should convert recognized schemas to the latest internal value, and
 21	// may reject unrecognized values. More info:
 22	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
 23	"apiVersion": "certificates.k8s.io/v1"
 24
 25	// Kind is a string value representing the REST resource this object represents.
 26	// Servers may infer this from the endpoint the client submits requests to.
 27	// Cannot be updated. In CamelCase. More info:
 28	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
 29	"kind":      "CertificateSigningRequest"
 30	"metadata"?: v1.#ObjectMeta
 31
 32	// spec contains the certificate request, and is immutable after creation. Only
 33	// the request, signerName, expirationSeconds, and usages fields can be set on
 34	// creation. Other fields are derived by Kubernetes and cannot be modified by
 35	// users.
 36	"spec"!: #CertificateSigningRequestSpec
 37
 38	// status contains information about whether the request is approved or denied,
 39	// and the certificate issued by the signer, or the failure condition
 40	// indicating signer failure.
 41	"status"?: #CertificateSigningRequestStatus
 42}
 43
 44// CertificateSigningRequestCondition describes a condition of a CertificateSigningRequest object
 45#CertificateSigningRequestCondition: {
 46	// lastTransitionTime is the time the condition last transitioned from one
 47	// status to another. If unset, when a new condition type is added or an
 48	// existing condition's status is changed, the server defaults this to the
 49	// current time.
 50	"lastTransitionTime"?: v1.#Time
 51
 52	// lastUpdateTime is the time of the last update to this condition
 53	"lastUpdateTime"?: v1.#Time
 54
 55	// message contains a human readable message with details about the request state
 56	"message"?: string
 57
 58	// reason indicates a brief reason for the request state
 59	"reason"?: string
 60
 61	// status of the condition, one of True, False, Unknown. Approved, Denied, and
 62	// Failed conditions may not be "False" or "Unknown".
 63	"status"!: string
 64
 65	// type of the condition. Known conditions are "Approved", "Denied", and "Failed".
 66	//
 67	// An "Approved" condition is added via the /approval subresource, indicating
 68	// the request was approved and should be issued by the signer.
 69	//
 70	// A "Denied" condition is added via the /approval subresource, indicating the
 71	// request was denied and should not be issued by the signer.
 72	//
 73	// A "Failed" condition is added via the /status subresource, indicating the
 74	// signer failed to issue the certificate.
 75	//
 76	// Approved and Denied conditions are mutually exclusive. Approved, Denied, and
 77	// Failed conditions cannot be removed once added.
 78	//
 79	// Only one condition of a given type is allowed.
 80	"type"!: string
 81}
 82
 83// CertificateSigningRequestList is a collection of CertificateSigningRequest objects
 84#CertificateSigningRequestList: {
 85	// APIVersion defines the versioned schema of this representation of an object.
 86	// Servers should convert recognized schemas to the latest internal value, and
 87	// may reject unrecognized values. More info:
 88	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
 89	"apiVersion": "certificates.k8s.io/v1"
 90
 91	// items is a collection of CertificateSigningRequest objects
 92	"items"!: [...#CertificateSigningRequest]
 93
 94	// Kind is a string value representing the REST resource this object represents.
 95	// Servers may infer this from the endpoint the client submits requests to.
 96	// Cannot be updated. In CamelCase. More info:
 97	// https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
 98	"kind":      "CertificateSigningRequestList"
 99	"metadata"?: v1.#ListMeta
100}
101
102// CertificateSigningRequestSpec contains the certificate request.
103#CertificateSigningRequestSpec: {
104	// expirationSeconds is the requested duration of validity of the issued
105	// certificate. The certificate signer may issue a certificate with a different
106	// validity duration so a client must check the delta between the notBefore and
107	// and notAfter fields in the issued certificate to determine the actual
108	// duration.
109	//
110	// The v1.22+ in-tree implementations of the well-known Kubernetes signers will
111	// honor this field as long as the requested duration is not greater than the
112	// maximum duration they will honor per the --cluster-signing-duration CLI flag
113	// to the Kubernetes controller manager.
114	//
115	// Certificate signers may not honor this field for various reasons:
116	//
117	// 1. Old signer that is unaware of the field (such as the in-tree
118	// implementations prior to v1.22)
119	// 2. Signer whose configured maximum is shorter than the requested duration
120	// 3. Signer whose configured minimum is longer than the requested duration
121	//
122	// The minimum valid value for expirationSeconds is 600, i.e. 10 minutes.
123	"expirationSeconds"?: int32 & int
124
125	// extra contains extra attributes of the user that created the
126	// CertificateSigningRequest. Populated by the API server on creation and
127	// immutable.
128	"extra"?: [string]: [...string]
129
130	// groups contains group membership of the user that created the
131	// CertificateSigningRequest. Populated by the API server on creation and
132	// immutable.
133	"groups"?: [...string]
134
135	// request contains an x509 certificate signing request encoded in a
136	// "CERTIFICATE REQUEST" PEM block. When serialized as JSON or YAML, the data
137	// is additionally base64-encoded.
138	"request"!: string
139
140	// signerName indicates the requested signer, and is a qualified name.
141	//
142	// List/watch requests for CertificateSigningRequests can filter on this field
143	// using a "spec.signerName=NAME" fieldSelector.
144	//
145	// Well-known Kubernetes signers are:
146	// 1. "kubernetes.io/kube-apiserver-client": issues client certificates that can
147	// be used to authenticate to kube-apiserver.
148	// Requests for this signer are never auto-approved by kube-controller-manager,
149	// can be issued by the "csrsigning" controller in kube-controller-manager.
150	// 2. "kubernetes.io/kube-apiserver-client-kubelet": issues client certificates
151	// that kubelets use to authenticate to kube-apiserver.
152	// Requests for this signer can be auto-approved by the "csrapproving"
153	// controller in kube-controller-manager, and can be issued by the "csrsigning"
154	// controller in kube-controller-manager.
155	// 3. "kubernetes.io/kubelet-serving" issues serving certificates that kubelets
156	// use to serve TLS endpoints, which kube-apiserver can connect to securely.
157	// Requests for this signer are never auto-approved by kube-controller-manager,
158	// and can be issued by the "csrsigning" controller in kube-controller-manager.
159	//
160	// More details are available at
161	// https://k8s.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers
162	//
163	// Custom signerNames can also be specified. The signer defines:
164	// 1. Trust distribution: how trust (CA bundles) are distributed.
165	// 2. Permitted subjects: and behavior when a disallowed subject is requested.
166	// 3. Required, permitted, or forbidden x509 extensions in the request
167	// (including whether subjectAltNames are allowed, which types, restrictions on
168	// allowed values) and behavior when a disallowed extension is requested.
169	// 4. Required, permitted, or forbidden key usages / extended key usages.
170	// 5. Expiration/certificate lifetime: whether it is fixed by the signer, configurable by the admin.
171	// 6. Whether or not requests for CA certificates are allowed.
172	"signerName"!: string
173
174	// uid contains the uid of the user that created the CertificateSigningRequest.
175	// Populated by the API server on creation and immutable.
176	"uid"?: string
177
178	// usages specifies a set of key usages requested in the issued certificate.
179	//
180	// Requests for TLS client certificates typically request: "digital signature",
181	// "key encipherment", "client auth".
182	//
183	// Requests for TLS serving certificates typically request: "key encipherment",
184	// "digital signature", "server auth".
185	//
186	// Valid values are:
187	// "signing", "digital signature", "content commitment",
188	// "key encipherment", "key agreement", "data encipherment",
189	// "cert sign", "crl sign", "encipher only", "decipher only", "any",
190	// "server auth", "client auth",
191	// "code signing", "email protection", "s/mime",
192	// "ipsec end system", "ipsec tunnel", "ipsec user",
193	// "timestamping", "ocsp signing", "microsoft sgc", "netscape sgc"
194	"usages"?: [...string]
195
196	// username contains the name of the user that created the
197	// CertificateSigningRequest. Populated by the API server on creation and
198	// immutable.
199	"username"?: string
200}
201
202// CertificateSigningRequestStatus contains conditions used to indicate
203// approved/denied/failed status of the request, and the issued certificate.
204#CertificateSigningRequestStatus: {
205	// certificate is populated with an issued certificate by the signer after an
206	// Approved condition is present. This field is set via the /status
207	// subresource. Once populated, this field is immutable.
208	//
209	// If the certificate signing request is denied, a condition of type "Denied" is
210	// added and this field remains empty. If the signer cannot issue the
211	// certificate, a condition of type "Failed" is added and this field remains
212	// empty.
213	//
214	// Validation requirements:
215	// 1. certificate must contain one or more PEM blocks.
216	// 2. All PEM blocks must have the "CERTIFICATE" label, contain no headers, and the encoded data
217	// must be a BER-encoded ASN.1 Certificate structure as described in section 4 of RFC5280.
218	// 3. Non-PEM content may appear before or after the "CERTIFICATE" PEM blocks and is unvalidated,
219	// to allow for explanatory text as described in section 5.2 of RFC7468.
220	//
221	// If more than one PEM block is present, and the definition of the requested
222	// spec.signerName does not indicate otherwise, the first block is the issued
223	// certificate, and subsequent blocks should be treated as intermediate
224	// certificates and presented in TLS handshakes.
225	//
226	// The certificate is encoded in PEM format.
227	//
228	// When serialized as JSON or YAML, the data is additionally base64-encoded, so it consists of:
229	//
230	// base64(
231	// -----BEGIN CERTIFICATE-----
232	// ...
233	// -----END CERTIFICATE-----
234	// )
235	"certificate"?: string
236
237	// conditions applied to the request. Known conditions are "Approved", "Denied", and "Failed".
238	"conditions"?: [...#CertificateSigningRequestCondition]
239}