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/v1kind: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
ClusterIssuerresources, so you do not create or manage them. Reference them withkind: ClusterIssuerinspec.issuerRef:letsencrypt-prodissues publicly trusted certificates from Let's Encrypt.letsencrypt-stagingissues untrusted test certificates from the Let's Encrypt staging environment.openbao-pkiissues 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-issuerannotation on anHTTPProxy, the service creates theCertificatefor you and names it after thesecretName. - Managed service: We install, configure and maintain cert-manager for you.