instruction: How do you configure advanced Kubernetes ingress patterns?
output: Annotated Ingress resource - cert-manager Documentation Project Documentation Announcements Support Search Get started Project Documentation Announcements Support Search Get started NEW: Get project updates on Twitter and Mastodon Docs Menu Introduction Getting Started Releases Supported Releases 1.18 Upgrade 1.17 to 1.18 1.17 Upgrade 1.16 to 1.17 1.16 Upgrading from 1.12 1.12 Older releases Notes on Ingress Class Compatibility Migrating Deprecated API Resources Upgrade 1.15 to 1.16 1.15 Upgrade 1.14 to 1.15 1.14 Upgrade 1.13 to 1.14 1.13 Upgrade 1.11 to 1.12 1.11 Upgrade 1.10 to 1.11 1.10 Upgrade 1.9 to 1.10 1.9 Upgrade 1.8 to 1.9 1.8 Upgrade 1.7 to 1.8 1.7 Upgrade 1.6 to 1.7 1.6 Upgrade 1.5 to 1.6 1.5 Upgrade 1.4 to 1.5 1.4 Upgrade 1.3 to 1.4 1.3 Upgrade 1.2 to 1.3 1.2 Upgrade 1.1 to 1.2 1.1 Upgrade 1.0 to 1.1 1.0 Upgrade 0.16 to 1.0 0.16 Upgrade 0.15 to 0.16 0.15 Upgrade 0.14 to 0.15 0.14 Upgrade 0.13 to 0.14 0.13 Upgrade 0.12 to 0.13 0.12 Upgrade 0.11 to 0.12 0.11 Upgrade 0.10 to 0.11 0.10 Upgrade 0.9 to 0.10 0.9 Upgrade 0.8 to 0.9 0.8 Upgrade 0.7 to 0.8 0.7 Upgrade 0.6 to 0.7 0.6 Upgrade 0.5 to 0.6 0.5 Upgrade 0.4 to 0.5 0.4 Upgrade 0.3 to 0.4 0.3 Upgrade 0.2 to 0.3 0.2 0.1 0. Installation Introduction a. kubectl apply b. Helm d. Continuous Deployment Configuring Components Upgrade Reinstall Uninstall Signature Verification 1. Configuring Issuers Introduction Issuers In-tree Issuer Config SelfSigned CA Vault CyberArk ACME Introduction HTTP01 Introduction External Load Balancer DNS01 Introduction ACMEDNS Akamai AzureDNS Cloudflare DigitalOcean Google CloudDNS RFC-2136 Route53 Webhook 2. Requesting Certificates Introduction Certificate CertificateRequest Ingress Gateway CertificateSigningRequests Service Mesh istio-csr Installation Usage CSI Driver Introduction csi-driver Installation Usage csi-driver-spiffe Installation Usage 3. Distributing Trust Introduction trust-manager Installation Usage API Reference 4. Defining Policy Introduction Defaulting Approval Introduction approver-policy Installation Usage API Reference Issuing Tutorials Introduction Securing NGINX-ingress GKE + Ingress + Let&#x27;s Encrypt AKS + LoadBalancer + Let&#x27;s Encrypt AWS + LoadBalancer + Let&#x27;s Encrypt Migrating from Kube-LEGO DNS Validation HTTP Validation Pomerium Ingress EKS + Ingress + CyberArk Securing Ingresses with ZeroSSL Managing public trust in kubernetes with trust-manager Setting default certificate values DevOps Tips Installing on a Cloud Provider Prometheus Metrics Backup and Restore Resources Syncing Secrets Across Namespaces Best Practice Installation Options Scaling cert-manager Troubleshooting &amp; FAQ Introduction Frequently Asked Questions Troubleshooting ACME / Let&#x27;s Encrypt Certificates Troubleshooting webhook Contributing Introduction Projects Feature Policy Building cert-manager Contributing Flow CRDs DNS Providers Running End-to-End Tests OSS-Fuzz Tests Implementing External Issuers DCO Sign Off Release Process Developing with Kind Feature gates Google Season of Docs Introduction 2022 Introduction Improve the Navigation and Structure of the cert-manager Website Reporting Security Issues Coding Conventions Third Party Code Donations Signing Keys API compatibility Importing cert-manager in Go Reference Introduction Command Line Tool (cmctl) TLS Terminology Components / Docker Images Introduction acmesolver cainjector cmctl controller webhook startupapicheck API Reference Annotations Concepts Introduction Issuer ACME Orders and Challenges Webhook CA Injector version: latest Annotated Ingress resource apiVersion: networking.k8s.io/v1 kind: Ingress A common use-case for cert-manager is requesting TLS signed certificates to secure your ingress resources. This can be done by simply adding annotations to your Ingress resources and cert-manager will facilitate creating the Certificate resource for you. A small sub-component of cert-manager, ingress-shim, is responsible for this. How It Works The sub-component ingress-shim watches Ingress resources across your cluster. If it observes an Ingress with annotations described in the Supported Annotations section, it will ensure a Certificate resource with the name provided in the tls.secretName field and configured as described on the Ingress exists in the Ingress &#x27;s namespace. For example: apiVersion : networking.k8s.io/v1 kind : Ingress metadata : annotations : # add an annotation indicating the issuer to use. cert-manager.io/cluster-issuer : nameOfClusterIssuer name : myIngress namespace : myIngress spec : rules : - host : example.com http : paths : - pathType : Prefix path : / backend : service : name : myservice port : number : 80 tls : # &lt; placing a host in the TLS config will determine what ends up in the cert&#x27;s subjectAltNames - hosts : - example.com secretName : myingress - cert # &lt; cert-manager will store the created certificate in this secret. Supported Annotations You can specify the following annotations on Ingress resources in order to trigger Certificate resources to be automatically created: cert-manager.io/issuer : the name of the Issuer that should issue the certificate required for this Ingress . ⚠️ This annotation does not assume a namespace scoped issuer. It will default to cert-manager.io Issuer , however in case of external issuer types, this should be used for both namespaced and cluster scoped issuer types. ⚠️ If a namespace scoped issuer is used then the issuer must be in the same namespace as the Ingress resource. cert-manager.io/cluster-issuer : the name of a cert-manager.io ClusterIssuer to acquire the certificate required for this Ingress . It does not matter in which namespace your Ingress resides, as ClusterIssuers are non-namespaced resources. ⚠️ This annotation is a shortcut to refer to to cert-manager.io ClusterIssuer without having to specify group and kind. It is not intended to be used to specify an external cluster-scoped issuer- please use cert-manager.io/issuer annotation for those. cert-manager.io/issuer-kind : the kind of the external issuer resource, for example AWSPCAIssuer . This is only necessary for out-of-tree issuers. cert-manager.io/issuer-group : the API group of the external issuer controller, for example awspca.cert-manager.io . This is only necessary for out-of-tree issuers. kubernetes.io/tls-acme: &quot;true&quot; : this annotation requires additional configuration of the ingress-shim see below . Namely, a default Issuer must be specified as arguments to the ingress-shim container. acme.cert-manager.io/http01-ingress-class : this annotation allows you to configure the ingress class that will be used to solve challenges for this ingress. Customizing this is useful when you are trying to secure internal services, and need to solve challenges using a different ingress class to that of the ingress. If not specified and the acme-http01-edit-in-place annotation is not set, this defaults to the ingress class defined in the Issuer resource. acme.cert-manager.io/http01-edit-in-place: &quot;true&quot; : this controls whether the ingress is modified &#x27;in-place&#x27;, or a new one is created specifically for the HTTP01 challenge. If present, and set to &quot;true&quot;, the existing ingress will be modified. Any other value, or the absence of the annotation assumes &quot;false&quot;. This annotation will also add the annotation &quot;cert-manager.io/issue-temporary-certificate&quot;: &quot;true&quot; onto created certificates which will cause a temporary certificate to be set on the resulting Secret until the final signed certificate has been returned. This is useful for keeping compatibility with the ingress-gce component. cert-manager.io/common-name : (optional) this annotation allows you to configure spec.commonName for the Certificate to be generated. cert-manager.io/email-sans : (optional) this annotation allows you to configure spec.emailAddresses field for the Certificate to be generated. Supports comma-separated values e.g. &quot; me@example.com , you@example.com &quot; cert-manager.io/subject-organizations : (optional) this annotation allows you to configure spec.subject.organizations field for the Certificate to be generated. Supports comma-separated values e.g. &quot;Company 1,Company 2&quot; cert-manager.io/subject-organizationalunits : (optional) this annotation allows you to configure spec.subject.organizationalUnits field for the Certificate to be generated. Supports comma-separated values e.g. &quot;IT Services,Cloud Services&quot; cert-manager.io/subject-countries : (optional) this annotation allows you to configure spec.subject.countries field for the Certificate to be generated. Supports comma-separated values e.g. &quot;Country 1,Country 2&quot; cert-manager.io/subject-provinces : (optional) this annotation allows you to configure spec.subject.provinces field for the Certificate to be generated. Supports comma-separated values e.g. &quot;Province 1,Province 2&quot; cert-manager.io/subject-localities : (optional) this annotation allows you to configure spec.subject.localities field for the Certificate to be generated. Supports comma-separated values e.g. &quot;City 1,City 2&quot; cert-manager.io/subject-postalcodes : (optional) this annotation allows you to configure spec.subject.postalCodes field for the Certificate to be generated. Supports comma-separated values e.g. &quot;123ABC,456DEF&quot; cert-manager.io/subject-streetaddresses : (optional) this annotation allows you to configure spec.subject.streetAddresses field for the Certificate to be generated. Supports comma-separated values e.g. &quot;123 Example St,456 Other Blvd&quot; cert-manager.io/subject-serialnumber : (optional) this annotation allows you to configure spec.subject.serialNumber field for the Certificate to be generated. Supports comma-separated values e.g. &quot;10978342379280287615,1111144445555522228888&quot; cert-manager.io/duration : (optional) this annotation allows you to configure spec.duration field for the Certificate to be generated. cert-manager.io/renew-before : (optional) this annotation allows you to configure spec.renewBefore field for the Certificate to be generated. cert-manager.io/usages : (optional) this annotation allows you to configure spec.usages field for the Certificate to be generated. Pass a string with comma-separated values i.e &quot;key agreement,digital signature, server auth&quot; cert-manager.io/revision-history-limit : (optional) this annotation allows you to configure spec.revisionHistoryLimit field to limit the number of CertificateRequests to be kept for a Certificate. Minimum value is 1. If unset all CertificateRequests will be kept. cert-manager.io/private-key-algorithm : (optional) this annotation allows you to configure spec.privateKey.algorithm field to set the algorithm for private key generation for a Certificate. Valid values are RSA , ECDSA and Ed25519 . If unset an algorithm RSA will be used. cert-manager.io/private-key-encoding : (optional) this annotation allows you to configure spec.privateKey.encoding field to set the encoding for private key generation for a Certificate. Valid values are PKCS1 and PKCS8 . If unset an algorithm PKCS1 will be used. cert-manager.io/private-key-size : (optional) this annotation allows you to configure spec.privateKey.size field to set the size of the private key for a Certificate. If algorithm is set to RSA , valid values are 2048 , 4096 or 8192 , and will default to 2048 if not specified. If algorithm is set to ECDSA , valid values are 256 , 384 or 521 , and will default to 256 if not specified. If algorithm is set to Ed25519 , size is ignored. cert-manager.io/private-key-rotation-policy : (optional) this annotation allows you to configure spec.privateKey.rotationPolicy field to set the rotation policy of the private key for a Certificate. Valid values are Never and Always . If unset a rotation policy Always will be used. Copying annotations to the Certificate ℹ️ This feature was added in cert-manager v1.18.0 . It is possible to copy any specific custom annotation into the generated Certificate objects. For example, to copy the annotation: venafi.cert-manager.io/custom-fields from the Ingress to the Certificate, you must first redeploy the cert-manager controller with the following extra argument: --extra-certificate-annotations=venafi.cert-manager.io/custom-fields Or if you use Helm, supply the following values: # values.yaml config : ingressShimConfig : extraCertificateAnnotations : - venafi.cert - manager.io/custom - fields Then you can add the annotation to the Ingress resource: apiVersion : networking.k8s.io/v1 kind : Ingress metadata : annotations : # custom configuration venafi.cert-manager.io/custom-fields : ` [ { &quot;name&quot; : &quot;field-name&quot; , &quot;value&quot; : &quot;field value&quot; } ] ` name : myIngress namespace : myIngress Generate multiple certificates with multiple ingresses If you need to generate certificates from multiple ingresses make sure it has the issuer annotation. Besides the annotation, it is necessary that each ingress possess a unique tls.secretName Optional Configuration The ingress-shim sub-component is deployed automatically as part of installation. The old kube-lego kubernetes.io/tls-acme: &quot;true&quot; annotation is an alternate method to fully automated TLS. If this annotation is set, the other annotations are not needed, but in order to use it you will need to configure a default Issuer when deploying cert-manager. This can be done by adding the following --set when deploying using Helm: --set ingressShim.defaultIssuerName = letsencrypt-prod \ --set ingressShim.defaultIssuerKind = ClusterIssuer \ --set ingressShim.defaultIssuerGroup = cert-manager.io Or by adding the following arguments to the cert-manager deployment podTemplate container arguments: - --default-issuer-name=letsencrypt-prod - --default-issuer-kind=ClusterIssuer - --default-issuer-group=cert-manager.io In the above example, cert-manager will create Certificate resources that reference the ClusterIssuer letsencrypt-prod for all Ingresses that have a kubernetes.io/tls-acme: &quot;true&quot; annotation. Issuers configured via specific annotations have a preference over the default issuer. If a default issuer is configured via CLI flags and a cert-manager.io/cluster-issuer or cert-manager.io/issuer annotation also has been added to an Ingress , the created Certificate will refer to the issuer configured via annotation. When kubernetes.io/tls-acme: &quot;true&quot; hasn&#x27;t been set, automatic certificate deployment may still occur based on the cert-manager.io/issuer , cert-manager.io/issuer-kind , and cert-manager.io/issuer-group annotations. If all annotations are absent, then manual deployment is necessary: create Certificate resources directly, and assign the resulting Secret to the Ingress . For more information on deploying cert-manager, read the installation guide . Troubleshooting If you do not see a Certificate resource being created after applying the ingress-shim annotations check that at least cert-manager.io/issuer or cert-manager.io/cluster-issuer is set. If you want to use kubernetes.io/tls-acme: &quot;true&quot; make sure to have checked all steps above and you might want to look for errors in the cert-manager pod logs if not resolved. Inner workings diagram for developers [1] https://cert-manager.io/docs/usage/certificate On this page How It Works Supported Annotations Copying annotations to the Certificate Generate multiple certificates with multiple ingresses Optional Configuration Troubleshooting Inner workings diagram for developers © 2025 The cert-manager Authors. © 2025 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.