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, but not the cert-manager CertificateRequest resource, and they still wish for certificates to be signed through cert-manager.

CertificateSigningRequests reference a SignerName or signer as the entity it wishes to sign its request from. For cert-manager, a signer can be mapped to either an Issuer or ClusterIssuer.

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.

Requester annotations:

• 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. Some signers such as Venafi or ACME typically do not allow requesting a duration.

• 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/private-key-secret-name: Set by the requester. Required only for the SelfSigned signer. Used to reference a Secret which contains the PEM encoded private key of the requester's X.509 certificate signing request at key tls.key. Used to sign the requester's request.

• venafi.experimental.cert-manager.io/custom-fields: Set by the requester. Optional for only the Venafi signer. Used for adding custom fields to the Venafi request. This will only work with Venafi TPP v19.3 and higher. The value is a JSON array with objects containing the name and value keys, for example:

  venafi.experimental.cert-manager.io/custom-fields: |-
    [
      {"name": "field-name", "value": "field value"},
      {"name": "field-name-2", "value": "field value 2"}
    ]
  

Signer annotations:

• venafi.experimental.cert-manager.io/pickup-id: Set by the signer. Only used for the Venafi signer. Used to record the Venafi Pickup ID of a certificate signing request that has been submitted to the Venafi API for collection during issuance.

Usage¶

CertificateSigningRequests can be manually created using cmctl. This command takes a manifest file containing a Certificate resource as input. This generates a private key and creates a CertificateSigningRequest. CertificateSigningRequests are not approved by default, so you will likely need to approve it manually:

$ kubectl certificate approve <name>