diff --git a/pkg/apis/certificates/types.go b/pkg/apis/certificates/types.go index b616c000113..a2a15a68649 100644 --- a/pkg/apis/certificates/types.go +++ b/pkg/apis/certificates/types.go @@ -45,10 +45,27 @@ type CertificateSigningRequestSpec struct { // Base64-encoded PKCS#10 CSR data Request []byte - // Requested signer for the request. It is a qualified name in the form: - // `scope-hostname.io/name`. - // Distribution of trust for signers happens out of band. - // You can select on this field using `spec.signerName`. + // signerName indicates the requested signer, and is a qualified name. + // + // List/watch requests for CertificateSigningRequests can filter on this field using a "spec.signerName=NAME" fieldSelector. + // + // Well-known Kubernetes signers are: + // 1. "kubernetes.io/kube-apiserver-client": issues client certificates that can be used to authenticate to kube-apiserver. + // Requests for this signer are never auto-approved by kube-controller-manager, can be issued by the "csrsigning" controller in kube-controller-manager. + // 2. "kubernetes.io/kube-apiserver-client-kubelet": issues client certificates that kubelets use to authenticate to kube-apiserver. + // 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. + // 3. "kubernetes.io/kubelet-serving" issues serving certificates that kubelets use to serve TLS endpoints, which kube-apiserver can connect to securely. + // Requests for this signer are never auto-approved by kube-controller-manager, and can be issued by the "csrsigning" controller in kube-controller-manager. + // + // More details are available at https://k8s.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers + // + // Custom signerNames can also be specified. The signer defines: + // 1. Trust distribution: how trust (CA bundles) are distributed. + // 2. Permitted subjects: and behavior when a disallowed subject is requested. + // 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. + // 4. Required, permitted, or forbidden key usages / extended key usages. + // 5. Expiration/certificate lifetime: whether it is fixed by the signer, configurable by the admin. + // 6. Whether or not requests for CA certificates are allowed. SignerName string // usages specifies a set of usage contexts the key will be