Skip to content

Commit 7ee2e2f

Browse files
liggittliggitt
committed
Update v1 CSR field types, API docs
1 parent 595adc4 commit 7ee2e2f

File tree

4 files changed

+168
-66
lines changed

4 files changed

+168
-66
lines changed

‎pkg/apis/certificates/v1/register.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ func Resource(resource string) schema.GroupResource {
3939

4040
var (
4141
localSchemeBuilder = &certificatesv1.SchemeBuilder
42-
AddToScheme = localSchemeBuilder.AddToScheme
42+
43+
// AddToScheme is a global function that registers this API group & version to a scheme
44+
AddToScheme = localSchemeBuilder.AddToScheme
4345
)
4446

4547
func init() {

‎staging/src/k8s.io/api/certificates/v1/register.go‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,13 @@ func Resource(resource string) schema.GroupResource {
3939
}
4040

4141
var (
42-
// TODO: move SchemeBuilder with zz_generated.deepcopy.go to k8s.io/api.
43-
// localSchemeBuilder and AddToScheme will stay in k8s.io/kubernetes.
44-
SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
42+
// SchemeBuilder is the scheme builder with scheme init functions to run for this API package
43+
SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
44+
4545
localSchemeBuilder = &SchemeBuilder
46-
AddToScheme = localSchemeBuilder.AddToScheme
46+
47+
// AddToScheme is a global function that registers this API group & version to a scheme
48+
AddToScheme = localSchemeBuilder.AddToScheme
4749
)
4850

4951
// Adds the list of known types to the given scheme.

‎staging/src/k8s.io/api/certificates/v1/types.go‎

Lines changed: 135 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -28,88 +28,115 @@ import (
2828
// +genclient:method=UpdateApproval,verb=update,subresource=approval,input=k8s.io/api/certificates/v1.CertificateSigningRequest,result=k8s.io/api/certificates/v1.CertificateSigningRequest
2929
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
3030

31-
// Describes a certificate signing request
31+
// CertificateSigningRequest objects provide a mechanism to obtain x509 certificates
32+
// by submitting a certificate signing request, and having it asynchronously approved and issued.
33+
//
34+
// Kubelets use this API to obtain:
35+
// 1. client certificates to authenticate to kube-apiserver (with the "kubernetes.io/kube-apiserver-client-kubelet" signerName).
36+
// 2. serving certificates for TLS endpoints kube-apiserver can connect to securely (with the "kubernetes.io/kubelet-serving" signerName).
37+
//
38+
// This API can be used to request client certificates to authenticate to kube-apiserver
39+
// (with the "kubernetes.io/kube-apiserver-client" signerName),
40+
// or to obtain certificates from custom non-Kubernetes signers.
3241
type CertificateSigningRequest struct {
3342
metav1.TypeMeta `json:",inline"`
3443
// +optional
3544
metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
3645

37-
// The certificate request itself and any additional information.
38-
// +optional
39-
Spec CertificateSigningRequestSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
46+
// spec contains the certificate request, and is immutable after creation.
47+
// Only the request, signerName, and usages fields can be set on creation.
48+
// Other fields are derived by Kubernetes and cannot be modified by users.
49+
Spec CertificateSigningRequestSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
4050

41-
// Derived information about the request.
51+
// status contains information about whether the request is approved or denied,
52+
// and the certificate issued by the signer, or the failure condition indicating signer failure.
4253
// +optional
4354
Status CertificateSigningRequestStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`
4455
}
4556

46-
// This information is immutable after the request is created. Only the Request
47-
// and Usages fields can be set on creation, other fields are derived by
48-
// Kubernetes and cannot be modified by users.
57+
// CertificateSigningRequestSpec contains the certificate request.
4958
type CertificateSigningRequestSpec struct {
50-
// Base64-encoded PKCS#10 CSR data
59+
// request contains an x509 certificate signing request encoded in a "CERTIFICATE REQUEST" PEM block.
60+
// When serialized as JSON or YAML, the data is additionally base64-encoded.
5161
// +listType=atomic
5262
Request []byte `json:"request" protobuf:"bytes,1,opt,name=request"`
5363

54-
// Requested signer for the request. It is a qualified name in the form:
55-
// `scope-hostname.io/name`.
56-
// If empty, it will be defaulted:
57-
// 1. If it's a kubelet client certificate, it is assigned
58-
// "kubernetes.io/kube-apiserver-client-kubelet".
59-
// 2. If it's a kubelet serving certificate, it is assigned
60-
// "kubernetes.io/kubelet-serving".
61-
// 3. Otherwise, it is assigned "kubernetes.io/legacy-unknown".
62-
// Distribution of trust for signers happens out of band.
63-
// You can select on this field using `spec.signerName`.
64-
// +optional
65-
SignerName *string `json:"signerName,omitempty" protobuf:"bytes,7,opt,name=signerName"`
64+
// signerName indicates the requested signer, and is a qualified name.
65+
//
66+
// List/watch requests for CertificateSigningRequests can filter on this field using a "spec.signerName=NAME" fieldSelector.
67+
//
68+
// Well-known Kubernetes signers are:
69+
// 1. "kubernetes.io/kube-apiserver-client": issues client certificates that can be used to authenticate to kube-apiserver.
70+
// Requests for this signer are never auto-approved by kube-controller-manager, can be issued by the "csrsigning" controller in kube-controller-manager.
71+
// 2. "kubernetes.io/kube-apiserver-client-kubelet": issues client certificates that kubelets use to authenticate to kube-apiserver.
72+
// Requests for this signer can be auto-approved by the "csrapproving" controller in kube-controller-manager, and can be issued by the "csrsigning" controller in kube-controller-manager.
73+
// 3. "kubernetes.io/kubelet-serving" issues serving certificates that kubelets use to serve TLS endpoints, which kube-apiserver can connect to securely.
74+
// Requests for this signer are never auto-approved by kube-controller-manager, and can be issued by the "csrsigning" controller in kube-controller-manager.
75+
//
76+
// More details are available at https://k8s.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers
77+
//
78+
// Custom signerNames can also be specified. The signer defines:
79+
// 1. Trust distribution: how trust (CA bundles) are distributed.
80+
// 2. Permitted subjects: and behavior when a disallowed subject is requested.
81+
// 3. Required, permitted, or forbidden x509 extensions in the request (including whether subjectAltNames are allowed, which types, restrictions on allowed values) and behavior when a disallowed extension is requested.
82+
// 4. Required, permitted, or forbidden key usages / extended key usages.
83+
// 5. Expiration/certificate lifetime: whether it is fixed by the signer, configurable by the admin.
84+
// 6. Whether or not requests for CA certificates are allowed.
85+
SignerName string `json:"signerName" protobuf:"bytes,7,opt,name=signerName"`
6686

67-
// allowedUsages specifies a set of usage contexts the key will be
68-
// valid for.
69-
// See: https://tools.ietf.org/html/rfc5280#section-4.2.1.3
70-
// https://tools.ietf.org/html/rfc5280#section-4.2.1.12
87+
// usages specifies a set of key usages requested in the issued certificate.
88+
//
89+
// Requests for TLS client certificates typically request: "digital signature", "key encipherment", "client auth".
90+
//
91+
// Requests for TLS serving certificates typically request: "key encipherment", "digital signature", "server auth".
92+
//
93+
// Valid values are:
94+
// "signing", "digital signature", "content commitment",
95+
// "key encipherment", "key agreement", "data encipherment",
96+
// "cert sign", "crl sign", "encipher only", "decipher only", "any",
97+
// "server auth", "client auth",
98+
// "code signing", "email protection", "s/mime",
99+
// "ipsec end system", "ipsec tunnel", "ipsec user",
100+
// "timestamping", "ocsp signing", "microsoft sgc", "netscape sgc"
71101
// +listType=atomic
72102
Usages []KeyUsage `json:"usages,omitempty" protobuf:"bytes,5,opt,name=usages"`
73103

74-
// Information about the requesting user.
75-
// See user.Info interface for details.
104+
// username contains the name of the user that created the CertificateSigningRequest.
105+
// Populated by the API server on creation and immutable.
76106
// +optional
77107
Username string `json:"username,omitempty" protobuf:"bytes,2,opt,name=username"`
78-
// UID information about the requesting user.
79-
// See user.Info interface for details.
108+
// uid contains the uid of the user that created the CertificateSigningRequest.
109+
// Populated by the API server on creation and immutable.
80110
// +optional
81111
UID string `json:"uid,omitempty" protobuf:"bytes,3,opt,name=uid"`
82-
// Group information about the requesting user.
83-
// See user.Info interface for details.
112+
// groups contains group membership of the user that created the CertificateSigningRequest.
113+
// Populated by the API server on creation and immutable.
84114
// +listType=atomic
85115
// +optional
86116
Groups []string `json:"groups,omitempty" protobuf:"bytes,4,rep,name=groups"`
87-
// Extra information about the requesting user.
88-
// See user.Info interface for details.
117+
// extra contains extra attributes of the user that created the CertificateSigningRequest.
118+
// Populated by the API server on creation and immutable.
89119
// +optional
90120
Extra map[string]ExtraValue `json:"extra,omitempty" protobuf:"bytes,6,rep,name=extra"`
91121
}
92122

93-
// Built in signerName values that are honoured by kube-controller-manager.
94-
// None of these usages are related to ServiceAccount token secrets
95-
// `.data[ca.crt]` in any way.
123+
// Built in signerName values that are honored by kube-controller-manager.
96124
const (
97-
// Signs certificates that will be honored as client-certs by the
98-
// kube-apiserver. Never auto-approved by kube-controller-manager.
125+
// "kubernetes.io/kube-apiserver-client" signer issues client certificates that can be used to authenticate to kube-apiserver.
126+
// Never auto-approved by kube-controller-manager.
127+
// Can be issued by the "csrsigning" controller in kube-controller-manager.
99128
KubeAPIServerClientSignerName = "kubernetes.io/kube-apiserver-client"
100129

101-
// Signs client certificates that will be honored as client-certs by the
102-
// kube-apiserver for a kubelet.
103-
// May be auto-approved by kube-controller-manager.
130+
// "kubernetes.io/kube-apiserver-client-kubelet" issues client certificates that kubelets use to authenticate to kube-apiserver.
131+
// Can be auto-approved by the "csrapproving" controller in kube-controller-manager.
132+
// Can be issued by the "csrsigning" controller in kube-controller-manager.
104133
KubeAPIServerClientKubeletSignerName = "kubernetes.io/kube-apiserver-client-kubelet"
105134

106-
// Signs serving certificates that are honored as a valid kubelet serving
107-
// certificate by the kube-apiserver, but has no other guarantees.
135+
// "kubernetes.io/kubelet-serving" issues serving certificates that kubelets use to serve TLS endpoints,
136+
// which kube-apiserver can connect to securely.
137+
// Never auto-approved by kube-controller-manager.
138+
// Can be issued by the "csrsigning" controller in kube-controller-manager.
108139
KubeletServingSignerName = "kubernetes.io/kubelet-serving"
109-
110-
// Has no guarantees for trust at all. Some distributions may honor these
111-
// as client certs, but that behavior is not standard kubernetes behavior.
112-
LegacyUnknownSignerName = "kubernetes.io/legacy-unknown"
113140
)
114141

115142
// ExtraValue masks the value so protobuf can generate
@@ -121,44 +148,88 @@ func (t ExtraValue) String() string {
121148
return fmt.Sprintf("%v", []string(t))
122149
}
123150

151+
// CertificateSigningRequestStatus contains conditions used to indicate
152+
// approved/denied/failed status of the request, and the issued certificate.
124153
type CertificateSigningRequestStatus struct {
125-
// Conditions applied to the request, such as approval or denial.
154+
// conditions applied to the request. Known conditions are "Approved", "Denied", and "Failed".
126155
// +listType=map
127156
// +listMapKey=type
128157
// +optional
129158
Conditions []CertificateSigningRequestCondition `json:"conditions,omitempty" protobuf:"bytes,1,rep,name=conditions"`
130159

131-
// If request was approved, the controller will place the issued certificate here.
160+
// certificate is populated with an issued certificate by the signer after an Approved condition is present.
161+
// This field is set via the /status subresource. Once populated, this field is immutable.
162+
//
163+
// If the certificate signing request is denied, a condition of type "Denied" is added and this field remains empty.
164+
// If the signer cannot issue the certificate, a condition of type "Failed" is added and this field remains empty.
165+
//
166+
// Validation requirements:
167+
// 1. certificate must contain one or more PEM blocks.
168+
// 2. All PEM blocks must have the "CERTIFICATE" label, contain no headers, and the encoded data
169+
// must be a BER-encoded ASN.1 Certificate structure as described in section 4 of RFC5280.
170+
// 3. Non-PEM content may appear before or after the "CERTIFICATE" PEM blocks and is unvalidated,
171+
// to allow for explanatory text as described in section 5.2 of RFC7468.
172+
//
173+
// If more than one PEM block is present, and the definition of the requested spec.signerName
174+
// does not indicate otherwise, the first block is the issued certificate,
175+
// and subsequent blocks should be treated as intermediate certificates and presented in TLS handshakes.
176+
//
177+
// The certificate is encoded in PEM format.
178+
//
179+
// When serialized as JSON or YAML, the data is additionally base64-encoded, so it consists of:
180+
//
181+
// base64(
182+
// -----BEGIN CERTIFICATE-----
183+
// ...
184+
// -----END CERTIFICATE-----
185+
// )
186+
//
132187
// +listType=atomic
133188
// +optional
134189
Certificate []byte `json:"certificate,omitempty" protobuf:"bytes,2,opt,name=certificate"`
135190
}
136191

192+
// RequestConditionType is the type of a CertificateSigningRequestCondition
137193
type RequestConditionType string
138194

139-
// These are the possible conditions for a certificate request.
195+
// Well-known condition types for certificate requests.
140196
const (
197+
// Approved indicates the request was approved and should be issued by the signer.
141198
CertificateApproved RequestConditionType = "Approved"
142-
CertificateDenied RequestConditionType = "Denied"
143-
CertificateFailed RequestConditionType = "Failed"
199+
// Denied indicates the request was denied and should not be issued by the signer.
200+
CertificateDenied RequestConditionType = "Denied"
201+
// Failed indicates the signer failed to issue the certificate.
202+
CertificateFailed RequestConditionType = "Failed"
144203
)
145204

205+
// CertificateSigningRequestCondition describes a condition of a CertificateSigningRequest object
146206
type CertificateSigningRequestCondition struct {
147-
// type of the condition. Known conditions include "Approved", "Denied", and "Failed".
207+
// type of the condition. Known conditions are "Approved", "Denied", and "Failed".
208+
//
209+
// An "Approved" condition is added via the /approval subresource,
210+
// indicating the request was approved and should be issued by the signer.
211+
//
212+
// A "Denied" condition is added via the /approval subresource,
213+
// indicating the request was denied and should not be issued by the signer.
214+
//
215+
// A "Failed" condition is added via the /status subresource,
216+
// indicating the signer failed to issue the certificate.
217+
//
218+
// Approved and Denied conditions are mutually exclusive.
219+
// Approved, Denied, and Failed conditions cannot be removed once added.
220+
//
221+
// Only one condition of a given type is allowed.
148222
Type RequestConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=RequestConditionType"`
149-
// Status of the condition, one of True, False, Unknown.
223+
// status of the condition, one of True, False, Unknown.
150224
// Approved, Denied, and Failed conditions may not be "False" or "Unknown".
151-
// Defaults to "True".
152-
// If unset, should be treated as "True".
153-
// +optional
154225
Status v1.ConditionStatus `json:"status" protobuf:"bytes,6,opt,name=status,casttype=k8s.io/api/core/v1.ConditionStatus"`
155-
// brief reason for the request state
226+
// reason indicates a brief reason for the request state
156227
// +optional
157228
Reason string `json:"reason,omitempty" protobuf:"bytes,2,opt,name=reason"`
158-
// human readable message with details about the request state
229+
// message contains a human readable message with details about the request state
159230
// +optional
160231
Message string `json:"message,omitempty" protobuf:"bytes,3,opt,name=message"`
161-
// timestamp for the last update to this condition
232+
// lastUpdateTime is the time of the last update to this condition
162233
// +optional
163234
LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty" protobuf:"bytes,4,opt,name=lastUpdateTime"`
164235
// lastTransitionTime is the time the condition last transitioned from one status to another.
@@ -170,19 +241,22 @@ type CertificateSigningRequestCondition struct {
170241

171242
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
172243

244+
// CertificateSigningRequestList is a collection of CertificateSigningRequest objects
173245
type CertificateSigningRequestList struct {
174246
metav1.TypeMeta `json:",inline"`
175247
// +optional
176248
metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
177249

250+
// items is a collection of CertificateSigningRequest objects
178251
Items []CertificateSigningRequest `json:"items" protobuf:"bytes,2,rep,name=items"`
179252
}
180253

181-
// KeyUsages specifies valid usage contexts for keys.
254+
// KeyUsage specifies valid usage contexts for keys.
182255
// See: https://tools.ietf.org/html/rfc5280#section-4.2.1.3
183256
// https://tools.ietf.org/html/rfc5280#section-4.2.1.12
184257
type KeyUsage string
185258

259+
// Valid key usages
186260
const (
187261
UsageSigning KeyUsage = "signing"
188262
UsageDigitalSignature KeyUsage = "digital signature"

‎staging/src/k8s.io/api/certificates/v1beta1/types.go‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,30 @@ type CertificateSigningRequestSpec struct {
6969
// valid for.
7070
// See: https://tools.ietf.org/html/rfc5280#section-4.2.1.3
7171
// https://tools.ietf.org/html/rfc5280#section-4.2.1.12
72+
// Valid values are:
73+
// "signing",
74+
// "digital signature",
75+
// "content commitment",
76+
// "key encipherment",
77+
// "key agreement",
78+
// "data encipherment",
79+
// "cert sign",
80+
// "crl sign",
81+
// "encipher only",
82+
// "decipher only",
83+
// "any",
84+
// "server auth",
85+
// "client auth",
86+
// "code signing",
87+
// "email protection",
88+
// "s/mime",
89+
// "ipsec end system",
90+
// "ipsec tunnel",
91+
// "ipsec user",
92+
// "timestamping",
93+
// "ocsp signing",
94+
// "microsoft sgc",
95+
// "netscape sgc"
7296
// +listType=atomic
7397
Usages []KeyUsage `json:"usages,omitempty" protobuf:"bytes,5,opt,name=usages"`
7498

0 commit comments

Comments
 (0)