Skip to content

Reference: Certificate CRD

A Certificate declares the X.509 certificate you want for your application. The Certificates service requests the certificate from the issuer you reference, stores the signed certificate and private key in a Kubernetes Secret in your namespace, and renews it before it expires.

You do not always need to create a Certificate yourself. When you add the cert-manager.io/cluster-issuer annotation to a Service Proxy resource, the service creates the Certificate for you, as described in the getting started guide. Create a Certificate directly when you need a certificate without a Service Proxy resource, for example for internal service-to-service TLS, or when you need settings that the annotation does not expose.

  • apiVersion: cert-manager.io/v1
  • kind: Certificate
  • Scope: Namespaced
  • Short names: cert, certs

This page documents cert-manager 1.21.3.

Example

The following Certificate requests a public certificate from Let's Encrypt for two hostnames, uses an ECDSA key, and labels the resulting Secret.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app
  namespace: your-namespace
spec:
  # cert-manager creates and updates this Secret in the same namespace.
  secretName: my-app-tls-secret

  # Let's Encrypt only uses the subject alternative names.
  dnsNames:
    - app.example.com
    - www.app.example.com

  # Renew when 25% of the issued lifetime remains. A percentage works for
  # any lifetime the issuer returns.
  renewBeforePercentage: 25

  privateKey:
    algorithm: ECDSA
    size: 256
    rotationPolicy: Always

  secretTemplate:
    labels:
      app.kubernetes.io/name: my-app

  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
    group: cert-manager.io

The Secret named my-app-tls-secret contains the following keys:

  • tls.crt: the signed certificate followed by the issuer's chain.
  • tls.key: the private key.
  • ca.crt: the certificate authority (CA) certificate, when the issuer provides one.

Specification (spec)

Field Type Description
secretName string Required. Name of the Secret that cert-manager creates and manages. The Secret holds the private key and the signed certificate, and lives in the same namespace as the Certificate.
issuerRef object Required. The issuer that signs the certificate. See spec.issuerRef.
dnsNames []string Optional. DNS subject alternative names (SANs) to request.
ipAddresses []string Optional. IP address SANs to request.
uris []string Optional. URI SANs to request.
emailAddresses []string Optional. Email address SANs to request.
otherNames []object Optional. Other SANs with a UTF-8 string value, such as a User Principal Name (UPN). See spec.otherNames[].
commonName string Optional. Common name (CN) attribute of the certificate subject. TLS clients ignore the CN when any SAN is set. Keep it at 64 characters or fewer to avoid invalid certificate signing requests (CSRs). Cannot be set together with literalSubject.
subject object Optional. Additional X.509 subject attributes. See spec.subject. Cannot be set together with literalSubject.
literalSubject string Optional. The complete X.509 subject as an LDAP distinguished name string (RFC 4514), for example CN=foo,DC=corp,DC=example,DC=com. The attribute order in the string is preserved, which matters for LDAP authentication. Cannot be set together with subject or commonName.
duration string Optional. Requested lifetime of the certificate, as a Go duration such as 2160h. Defaults to 90 days (2160h). Minimum 1h. The issuer may ignore the requested lifetime.
renewBefore string Optional. How long before expiry cert-manager renews the certificate, as a Go duration such as 720h. cert-manager calculates this from the lifetime of the certificate it receives, not the requested duration. Defaults to one third of the lifetime. Minimum 5m. Cannot be set together with renewBeforePercentage.
renewBeforePercentage integer Optional. Like renewBefore, but as a percentage of the issued certificate's lifetime. Allowed values are 1 to 99. The resulting renewal time must be at least 5 minutes before expiry. Cannot be set together with renewBefore.
renewal object Optional. Disables automatic renewal or restricts it to time windows. See spec.renewal.
privateKey object Optional. Private key algorithm, size, encoding and rotation. See spec.privateKey.
signatureAlgorithm string Optional. Signature algorithm to request. Allowed values for RSA keys are SHA256WithRSA, SHA384WithRSA and SHA512WithRSA. Allowed values for ECDSA keys are ECDSAWithSHA256, ECDSAWithSHA384 and ECDSAWithSHA512. The allowed value for Ed25519 keys is PureEd25519.
usages []string Optional. Key usages and extended key usages to request. Defaults to digital signature and key encipherment. See Allowed usages.
encodeUsagesInRequest boolean Optional. Whether to encode the usages as KeyUsage and ExtKeyUsage extensions in the CSR. Defaults to true. Set it to false only if the issuer rejects CSRs that contain these extensions.
isCA boolean Optional. Requests a CA certificate (basic constraints isCA). Setting it to true adds the cert sign usage. The issuer may ignore the request.
nameConstraints object Optional. X.509 name constraints for a CA certificate. Only valid when isCA is true. See spec.nameConstraints.
secretTemplate object Optional. Labels and annotations that cert-manager copies to the Secret. See spec.secretTemplate.
additionalOutputFormats []object Optional. Extra formats of the key and certificate to write to the Secret. See spec.additionalOutputFormats[].
keystores object Optional. Java KeyStore (JKS) and PKCS#12 keystores to write to the Secret. See spec.keystores.
revisionHistoryLimit integer Optional. Number of CertificateRequest revisions to keep for this Certificate. cert-manager removes the oldest first. Minimum 1. Defaults to 1.

spec.issuerRef

Field Type Description
name string Required. Name of the issuer.
kind string Optional. Kind of the issuer, Issuer or ClusterIssuer. Defaults to Issuer. Set it to ClusterIssuer to use an issuer that the platform provides.
group string Optional. API group of the issuer. Defaults to cert-manager.io.

A namespaced Issuer must be in the same namespace as the Certificate. A ClusterIssuer works from any namespace.

spec.subject

All fields are optional. Each list field sets one or more values of the corresponding subject attribute. Set the common name with spec.commonName.

Field Type Description
organizations []string Organization (O).
organizationalUnits []string Organizational unit (OU).
countries []string Country (C).
provinces []string State or province (ST).
localities []string City (L).
streetAddresses []string Street address.
postalCodes []string Postal code.
serialNumber string Subject serial number attribute.

spec.otherNames[]

Each entry adds one otherName SAN with a UTF-8 string value. cert-manager does not check that the OID accepts a UTF-8 string, so you must ensure it does.

Field Type Description
oid string Optional. Object identifier as a dotted string. The most common value is 1.3.6.1.4.1.311.20.2.3 for a UPN.
utf8Value string Optional. The UTF-8 string value of the SAN.

spec.privateKey

Field Type Description
algorithm string Optional. Key algorithm. Allowed values are RSA, ECDSA and Ed25519. Defaults to RSA.
size integer Optional. Key size in bits. For RSA, allowed values are 2048, 4096 and 8192, and the default is 2048. For ECDSA, allowed values are 256, 384 and 521, and the default is 256. Ignored for Ed25519.
encoding string Optional. Encoding of the private key in tls.key. Allowed values are PKCS1 and PKCS8. Defaults to PKCS1.
rotationPolicy string Optional. Whether cert-manager generates a new private key on each issuance. Always generates a new key on every renewal or reissue. Never reuses the key in the Secret and only creates one if none exists. If the existing key has the wrong algorithm or size, cert-manager raises a warning and waits for you to act. Defaults to Always.

spec.renewal

Field Type Description
policy string Optional. Allowed values are RenewBefore and Disabled. RenewBefore renews according to renewBefore or renewBeforePercentage. Disabled turns off automatic renewal.
windows []object Optional. Time windows in which renewal may happen. See spec.renewal.windows[].

spec.renewal.windows[]

Field Type Description
cron string Required. Standard five-field cron expression (minute, hour, day of month, month, day of week) that opens a renewal window.
windowDuration string Required. How long each window stays open, as a Go duration using s, m or h, for example 2h or 90m.
timezone string Optional. IANA time zone for cron, for example Europe/Copenhagen. Defaults to UTC.

The following example allows renewal only on weekdays between 08:00 and 10:00 Copenhagen time:

spec:
  renewal:
    policy: RenewBefore
    windows:
      - cron: "0 8 * * 1-5"
        windowDuration: 2h
        timezone: Europe/Copenhagen

spec.nameConstraints

Name constraints restrict which names a CA certificate can sign for. You can only set them when isCA is true. In cert-manager 1.21 this is a beta feature that is enabled by default.

Field Type Description
critical boolean Optional. Marks the name constraints extension as critical.
permitted object Optional. Names that certificates signed by this CA must fall within. See the subfields below.
excluded object Optional. Names that certificates signed by this CA must not use, regardless of permitted. See the subfields below.

Both permitted and excluded have the following fields:

Field Type Description
dnsDomains []string Optional. DNS domains.
ipRanges []string Optional. IP ranges in CIDR notation.
emailAddresses []string Optional. Email addresses.
uriDomains []string Optional. URI domains.

spec.secretTemplate

Field Type Description
labels map[string]string Optional. Labels to set on the Secret.
annotations map[string]string Optional. Annotations to set on the Secret. They cannot overwrite the annotations that cert-manager sets itself.

cert-manager adds and removes labels and annotations on the Secret as you change secretTemplate.

spec.additionalOutputFormats[]

Field Type Description
type string Required. Allowed values are DER and CombinedPEM. DER writes the private key in DER format to the key.der entry. CombinedPEM writes the private key followed by the certificate chain in PEM format to the tls-combined.pem entry.

spec.keystores

Field Type Description
jks object Optional. Writes a Java KeyStore. See spec.keystores.jks.
pkcs12 object Optional. Writes a PKCS#12 keystore. See spec.keystores.pkcs12.

Each keystore needs a password with a non-zero length. Set exactly one of password or passwordSecretRef. Use passwordSecretRef when your manifests live in Git, so the password is not stored in the repository.

spec.keystores.jks

Field Type Description
create boolean Required. When true, cert-manager writes keystore.jks to the Secret. If the issuer provides a CA certificate, it also writes truststore.jks.
alias string Optional. Alias of the key in the keystore. Defaults to certificate.
passwordSecretRef object Optional. Reference to a key in a Secret in the same namespace that holds the keystore password. See passwordSecretRef.
password string Optional. Literal keystore password.

spec.keystores.pkcs12

Field Type Description
create boolean Required. When true, cert-manager writes keystore.p12 to the Secret. If the issuer provides a CA certificate, it also writes truststore.p12.
profile string Optional. Encryption and MAC algorithms for the keystore. Defaults to LegacyRC2. See PKCS#12 profiles.
passwordSecretRef object Optional. Reference to a key in a Secret in the same namespace that holds the keystore password. See passwordSecretRef.
password string Optional. Literal keystore password.

PKCS#12 Profiles

Value Description
LegacyRC2 Default, kept for backward compatibility. Deprecated upstream. OpenSSL 3 and Java 20 do not read it by default.
LegacyDES Less secure. Use it for maximum compatibility.
Modern2023 Secure algorithms. Use it if a policy requires secure algorithms.
Modern2026 PBES2 with PBKDF2-HMAC-SHA-256 and AES-256-CBC, and a PBMAC1 MAC. Meets FIPS 140-3 requirements. Requires OpenSSL 3.4.0 or later, Java 26 or later, or a compatible Bouncy Castle version.

The keystore encryption does not add much protection, because the Secret also holds the unencrypted key and certificate.

passwordSecretRef

Field Type Description
name string Required. Name of the Secret.
key string Optional. Key in the Secret's data that holds the password.

Allowed Usages

spec.usages accepts the following values:

  • Key usages: signing, digital signature, content commitment, key encipherment, key agreement, data encipherment, cert sign, crl sign, encipher only, decipher only.
  • Extended key usages: any, server auth, client auth, code signing, email protection, s/mime, ipsec end system, ipsec tunnel, ipsec user, timestamping, ocsp signing, microsoft sgc, netscape sgc.

For a certificate used for mutual TLS (mTLS), request both server auth and client auth together with digital signature and key encipherment.

Status (status)

Field Type Description
conditions []object Conditions of type Ready and Issuing. Ready=True means the Secret holds a valid, up-to-date certificate. Issuing=True means an issuance is in progress. Check reason and message when a condition is False.
notBefore string Start of the validity period of the current certificate.
notAfter string Expiry time of the current certificate.
renewalTime string When cert-manager renews the certificate next. Unset if no renewal is scheduled.
revision integer Current revision of the issued certificate. It increases by one with each issuance.
failedIssuanceAttempts integer Number of consecutive failed issuance attempts. cert-manager waits 1h × 2^(failedIssuanceAttempts - 1) before it tries again. Removed after a successful issuance.
lastFailureTime string Time of the last failed issuance. Unset after a successful issuance.
nextPrivateKeySecretName string Name of the temporary Secret that holds the private key for the issuance in progress.

kubectl get certificate shows the Ready status and the Secret name. Add -o wide to also see the issuer and the status message.

Platform Notes

  • Issuers: The platform provides the issuers as ClusterIssuer resources, so you do not create or manage them. Reference them with kind: ClusterIssuer in spec.issuerRef:
    • letsencrypt-prod issues publicly trusted certificates from Let's Encrypt.
    • letsencrypt-staging issues untrusted test certificates from the Let's Encrypt staging environment.
    • openbao-pki issues certificates from the platform's private PKI, which is powered by OpenBao. These certificates are trusted within the platform but not by browsers or operating systems. See Using the Private PKI.
  • Domain validation: For Let's Encrypt certificates, the Certificates service validates domain ownership through DNS records that our DNS service manages.
  • Service Proxy: When you use the cert-manager.io/cluster-issuer annotation on an HTTPProxy, the service creates the Certificate for you and names it after the secretName.
  • Managed service: We install, configure and maintain cert-manager for you.

Further Reading