Kubernetes CertificateSigningRequests

Kubernetes has an in-built CertificateSigningRequest resource. This resource is similar to the cert-manager CertificateRequest in that it is used to request an X.509 signed certificate from a referenced Certificate Authority (CA).

Using this resource may be useful for users who are using an application that supports this resource, and not the cert-manager CertificateRequest resource, but they still wish for certificates to be signed through cert-manager.

Feature State

This feature is currently in an experimental state, and its behavior is subject to change in further releases.

--feature-gates=ExperimentalCertificateSigningRequestControllers=true

$ helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set featureGates="ExperimentalCertificateSigningRequestControllers=true" \
  # --set installCRDs=true

Signer Name

CertificateSigningRequests contain a spec.signerName field to reference a CA to sign the request. cert-manager Issuers or ClusterIssuers are referenced in the following form:

<resource type>.cert-manager.io/<signer namespace (if namespaced)>.<signer name>

For example, a namespaced Issuer in the namespace sandbox with the name my-issuer would be referenced via:

signerName: issuers.cert-manager.io/sandbox.my-issuer

A ClusterIssuer with the name my-cluster-issuer would be referenced via:

signerName: clusterissuers.cert-manager.io/my-cluster-issuer

Referencing Namespaced Issuers

Unlike CertificateRequests, CertificateSigningRequests are cluster scoped resources. To prevent users from requesting certificates from a namespaced Issuer in a namespace that they otherwise would not have access to, cert-manager performs a SubjectAccessReview. This review ensures that the requesting user has the permission to reference the signers resource in the given namespace. The name should be either the name of the Issuer, or "*" to reference all Issuers in that namespace.

An example Role to give permissions to reference Issuers in the sandbox namespace would look like the following:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: cert-manager-referencer:my-issuer
  namespace: sandbox
rules:
- apiGroups: ["cert-manager.io"]
  resources: ["signers"]
  verbs:     ["reference"]
  resourceNames:
  - "my-issuer" # To give permission to _only_ reference Issuers with the name 'my-issuer'
  - "*" # To give permission to reference Issuers with any name in this namespace

Annotations

To keep feature parity with CertificateRequests, annotations are used to store values that do not exist as spec or status fields on the CertificateSigningRequest resource. These fields are either set by the requester or by the signer as labelled below.

• experimental.cert-manager.io/request-duration: Set by the requester. Accepts a Go time duration string specifying the requested certificate duration. Defaults to 90 days.

• experimental.cert-manager.io/request-is-ca: Set by the requester. If set to "true", will request for a CA certificate.

• experimental.cert-manager.io/ca: Set by the signer. Once signed, the signer will populate this annotation with the base 64 encode CA certificate of the signing chain.