docs: remove config.apiVersion/kind from Helm values examples by Copilot · Pull Request #2011 · cert-manager/website

Copilot · 2026-03-11T22:49:12Z

The cert-manager Helm chart now automatically defaults config.apiVersion and config.kind for controller configuration, so users no longer need to set them explicitly.

Changes

content/docs/usage/gateway.md — removed config.apiVersion + config.kind from both the Gateway API enablement section and the ListenerSet section (values.yaml snippets and --set flags)
content/docs/configuration/acme/http01/README.md — same removal from the Gateway API HTTP-01 solver section
content/docs/devops-tips/scaling-cert-manager.md — same removal from the rate-limiting and server-side apply config examples

Before / After

# Before
config:
  apiVersion: controller.config.cert-manager.io/v1alpha1
  kind: ControllerConfiguration
  enableGatewayAPI: true

# After
config:
  enableGatewayAPI: true

# Before
helm upgrade --install cert-manager ... \
  --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
  --set config.kind="ControllerConfiguration" \
  --set config.enableGatewayAPI=true

# After
helm upgrade --install cert-manager ... \
  --set config.enableGatewayAPI=true

Docs under content/v*-docs/ (previous versions) are intentionally left unchanged.

Original prompt

Create a PR in cert-manager/website (base branch: master) updating the docs to reflect that Helm chart now defaults the config object's apiVersion and kind, so users no longer need to set them.

Scope:

Only update docs where config is used as Helm values (either via values.yaml snippets or via helm --set ... flags).
Do NOT update docs for previous versions under content/v*-docs/.

Required doc updates:

content/docs/usage/gateway.md
- In the section enabling Gateway API support, update the config Helm values example to remove config.apiVersion and config.kind (or clearly mark them as optional/defaulted).
- Update the corresponding Helm command example to remove --set config.apiVersion=... and --set config.kind=... (or mark optional/defaulted).
- In the ListenerSet section, do the same for the values.yaml and Helm command examples.
content/docs/configuration/acme/http01/README.md
- Update the config Helm values example to remove config.apiVersion and config.kind (or mark optional/defaulted).
- Update the corresponding Helm command example to remove --set config.apiVersion=... and --set config.kind=... (or mark optional/defaulted).
content/docs/devops-tips/scaling-cert-manager.md
- Update the Helm values example to remove config.apiVersion and config.kind (or mark optional/defaulted).

Guidance:

Keep the examples valid YAML / valid Helm CLI.
Prefer removing the lines/flags entirely unless there is strong value in keeping them as commented optional fields.
Ensure consistency across docs.
Run/ensure any formatting/linting conventions the repo expects for Markdown.

Context:
This change reflects Helm chart behavior: defaulting config.apiVersion and config.kind for controller config. Similar defaulting exists for cainjector.config... and webhook.config..., but only update files where those are actually used as Helm values examples (none identified yet in non-versioned docs during the search).

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: We added a feature to the helm chart that will default config apiVersion and kind, for example you dont need to set "apiVersion: controller.config.cert-manager.io/v1alpha1" and "kind: ControllerConfiguration" anymore

This is also true for cainjector.config.cert-manager.io/v1alpha1 - CAInjectorConfiguration & webhook.config.cert-manager.io/v1alpha1 - WebhookConfiguration

Find all the places in the docs that need updating.

Dont bother looking at docs for previous versions (content/v-bla-docs)

Assistant: Places in cert-manager/website docs (excluding content/v*-docs/) that still tell users to set apiVersion and kind for Helm chart config values (and should be updated now that these default):

content/docs/usage/gateway.md

Mentions:
- config.apiVersion: controller.config.cert-manager.io/v1alpha1
- config.kind: ControllerConfiguration
- Also shows Helm CLI flags: --set config.apiVersion=... / --set config.kind=...

Ref:

website/content/docs/usage/gateway.md

Lines 42 to 143 in 0e54695

    
           ⚠️  **ListenerSet support** is now available in cert-manager v1.20.0-beta.0+. 
        
           This enables self-service TLS configuration for application developers without 
        
           requiring edit access to Gateway resources. See the [ListenerSet 
        
           section](#listenerset) below for details. 
        
           ::: 
        
           The Gateway resource holds the TLS configuration, as illustrated in the 
        
           following diagram (source: https://gateway-api.sigs.k8s.io): 
        
           ![Gateway vs. HTTPRoute](/images/gateway-roles.png) 
        
           :::info 
        
           📌  This feature requires the installation of the [Gateway API bundle](https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api) and passing an 
        
           additional flag to the cert-manager controller. 
        
           To install v1.4.1 Gateway API bundle (CRDs associated with a version of Gateway API), run the following command: 
        
           ```sh 
        
           kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml 
        
           ``` 
        
           Since cert-manager 1.15, the Gateway API support is no longer gated behind a 
        
           feature flag, but you still need to enable the Gateway API support. 
        
           To enable the Gateway API support, use the [file-based 
        
           configuration](../installation/configuring-components.md#configuration-file) using the 
        
           following `config` Helm value: 
        
           ```yaml 
        
           config: 
        
             apiVersion: controller.config.cert-manager.io/v1alpha1 
        
             kind: ControllerConfiguration 
        
             enableGatewayAPI: true 
        
           ``` 
        
           The corresponding Helm command is: 
        
           ```sh 
        
           helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager --namespace cert-manager \ 
        
             --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ 
        
             --set config.kind="ControllerConfiguration" \ 
        
             --set config.enableGatewayAPI=true 
        
           ``` 
        
           The Gateway API CRDs should either be installed before cert-manager starts or 
        
           the cert-manager Deployment should be restarted after installing the Gateway API 
        
           CRDs. This is important because some of the cert-manager components only perform 
        
           the Gateway API check on startup. You can restart cert-manager with the 
        
           following command: 
        
           ```sh 
        
           kubectl rollout restart deployment cert-manager -n cert-manager 
        
           ``` 
        
           ::: 
        
           The annotations `cert-manager.io/issuer` or `cert-manager.io/cluster-issuer` 
        
           tell cert-manager  to create a Certificate for a Gateway. For example, the 
        
           following Gateway will trigger the creation of a Certificate with the name 
        
           `example-com-tls`: 
        
           ```yaml 
        
           apiVersion: gateway.networking.k8s.io/v1 
        
           kind: Gateway 
        
           metadata: 
        
             name: example 
        
             annotations: 
        
               cert-manager.io/issuer: foo 
        
           spec: 
        
             gatewayClassName: foo 
        
             listeners: 
        
               - name: http 
        
                 hostname: example.com 
        
                 port: 443 
        
                 protocol: HTTPS 
        
                 allowedRoutes: 
        
                   namespaces: 
        
                     from: All 
        
                 tls: 
        
                   mode: Terminate 
        
                   certificateRefs: 
        
                     - name: example-com-tls 
        
           ``` 
        
           A few moments later, cert-manager will create a Certificate. The Certificate is 
        
           named after the Secret name `example-com-tls`. The `dnsNames` field is set with 
        
           the `hostname` field from the Gateway spec. 
        
           ```yaml 
        
           apiVersion: cert-manager.io/v1 
        
           kind: Certificate 
        
           metadata: 
        
             name: example-com-tls 
        
           spec: 
        
             issuerRef: 
        
               name: my-issuer 
        
               kind: Issuer 
        
               group: cert-manager.io 
        
             dnsNames:

Also appears again in the ListenerSet section:

Ref:

website/content/docs/usage/gateway.md

Lines 482 to 579 in 0e54695

    
               # custom configuration 
        
               venafi.cert-manager.io/custom-fields: `[ {"name": "field-name", "value": "field value"}]` 
        
           ``` 
        
           ## ListenerSet 
        
           **FEATURE STATE**: cert-manager 1.20 [alpha] 
        
           ### What is ListenerSet? 
        
           ListenerSet is a Gateway API resource introduced in 
        
           [GEP-1713](https://gateway-api.sigs.k8s.io/geps/gep-1713/) that solves a key 
        
           limitation when migrating from Ingress to Gateway API: the loss of self-service 
        
           TLS configuration for application developers. 
        
           With Ingress resources, developers could independently configure both routing 
        
           and TLS certificates using cert-manager annotations. When migrating to Gateway 
        
           API, TLS configuration moves to the Gateway resource, which is typically 
        
           controlled by cluster operators. This forces developers to ask for changes to 
        
           resources they do not own, losing the autonomy they had with Ingress. 
        
           ListenerSet restores self-service by allowing developers to create a ListenerSet 
        
           resource alongside their HTTPRoute. The same annotations as for Gateway can be 
        
           used on the ListenerSet to trigger the creation of a Certificate resource. 
        
           ### Enabling ListenerSet Support 
        
           ListenerSet support requires Gateway API v1.5+ (standard channel). The 
        
           instructions for installing the CRDs can be found in the Gateway API 
        
           documentation: [Installing Gateway API][install-gapi]. 
        
           [install-gapi]: https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api 
        
           To start using ListenerSet, you will have to enable the feature in cert-manager. 
        
           We recommend you use the [file-based 
        
           configuration](../installation/configuring-components.md#configuration-file). In 
        
           your `values.yaml`, add the following: 
        
           ```yaml 
        
           # values.yaml 
        
           config: 
        
             apiVersion: controller.config.cert-manager.io/v1alpha1 
        
             kind: ControllerConfiguration 
        
             enableGatewayAPI: true 
        
             enableGatewayAPIListenerSet: true 
        
             featureGates: 
        
               ListenerSets: true 
        
           ``` 
        
           The `enableGatewayAPI` setting tells cert-manager to reconcile the Gateway 
        
           resources, and `enableGatewayAPIListenerSet` tells cert-manager to also 
        
           reconcile ListenerSet resources. 
        
           The corresponding Helm command is: 
        
           ```sh 
        
           helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \ 
        
             --namespace cert-manager \ 
        
             --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ 
        
             --set config.kind="ControllerConfiguration" \ 
        
             --set config.enableGatewayAPI=true \ 
        
             --set config.enableGatewayAPIListenerSet=true \ 
        
             --set config.featureGates.ListenerSets=true 
        
           ``` 
        
           After installation, restart cert-manager to ensure it picks up the new CRDs: 
        
           ```sh 
        
           kubectl rollout restart deployment cert-manager -n cert-manager 
        
           ``` 
        
           ### Example: Self-Service TLS with ListenerSet and HTTP-01 
        
           Here's a complete example showing how application developers can manage their 
        
           own TLS configuration. Let's start with the shared ClusterIssuer and Gateway 
        
           created by the cluster operator: 
        
           ```yaml 
        
           kind: ClusterIssuer 
        
           apiVersion: cert-manager.io/v1 
        
           metadata: 
        
             name: letsencrypt 
        
           spec: 
        
             acme: 
        
               server: https://acme-v02.api.letsencrypt.org/directory 
        
               email: platformteam@example.com 
        
               privateKeySecretRef: 
        
                 name: letsencrypt-acc-key 
        
               solvers: 
        
                 - http01: 
        
                     gatewayHTTPRoute: {} 
        
           --- 
        
           apiVersion: gateway.networking.k8s.io/v1 
        
           kind: Gateway 
        
           metadata: 
        
             name: eg 
        
             namespace: envoy-gateway-system 
        
           spec:

content/docs/configuration/acme/http01/README.md

Mentions:
- config.apiVersion: controller.config.cert-manager.io/v1alpha1
- config.kind: ControllerConfiguration
- Also shows Helm CLI flags: --set config.apiVersion=... / --set config.kind=...

Ref:

website/content/docs/configuration/acme/http01/README.md

Lines 205 to 302 in 0e54695

    
                         annotations: 
        
                           "nginx.ingress.kubernetes.io/whitelist-source-range": "0.0.0.0/0,::/0" 
        
                           "nginx.org/mergeable-ingress-type": "minion" 
        
                           "traefik.ingress.kubernetes.io/frontend-entry-points": "http" 
        
           ``` 
        
           The added labels and annotations will merge on top of the cert-manager defaults, 
        
           overriding entries with the same key. 
        
           No other fields of the ingress can be edited. 
        
           ## Configuring the HTTP-01 Gateway API solver 
        
           **FEATURE STATE**: cert-manager 1.15 [beta] 
        
           The Gateway and HTTPRoute resources are part of the [Gateway API][gwapi], a set 
        
           of CRDs that you install on your Kubernetes cluster that provide various 
        
           improvements over the Ingress API. 
        
           [gwapi]: https://gateway-api.sigs.k8s.io 
        
           :::info 
        
           📌  This feature requires the installation of the [Gateway API bundle](https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api) and passing an 
        
           additional flag to the cert-manager controller. 
        
           To install v1.4.1 Gateway API bundle (CRDs associated with a version of Gateway API), run the following command: 
        
           ```sh 
        
           kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml 
        
           ``` 
        
           Since cert-manager 1.15, the Gateway API support is no longer gated behind a 
        
           feature flag, but you still need to enable the Gateway API support. 
        
           To enable the Gateway API support, use the [file-based 
        
           configuration](../../../installation/configuring-components.md#configuration-file) using the 
        
           following `config` Helm value: 
        
           ```yaml 
        
           config: 
        
             apiVersion: controller.config.cert-manager.io/v1alpha1 
        
             kind: ControllerConfiguration 
        
             enableGatewayAPI: true 
        
           ``` 
        
           The corresponding Helm command is: 
        
           ```sh 
        
           helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager --namespace cert-manager \ 
        
             --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \ 
        
             --set config.kind="ControllerConfiguration" \ 
        
             --set config.enableGatewayAPI=true 
        
           ``` 
        
           The Gateway API CRDs should either be installed before cert-manager starts or 
        
           the cert-manager Deployment should be restarted after installing the Gateway API 
        
           CRDs. This is important because some of the cert-manager components only perform 
        
           the Gateway API check on startup. You can restart cert-manager with the 
        
           following command: 
        
           ```sh 
        
           kubectl rollout restart deployment cert-manager -n cert-manager 
        
           ``` 
        
           ::: 
        
           :::info 
        
           🚧   cert-manager 1.14+ is tested with v1 Kubernetes Gateway API. It should also work 
        
           with v1beta1 and v1alpha2 because of resource conversion, but has not been tested with it. 
        
           ::: 
        
           The Gateway API HTTPRoute HTTP-01 solver creates a temporary HTTPRoute using the 
        
           given labels. These labels must match a Gateway that contains a listener on port 
        
           80. 
        
           Here is an example of a HTTP-01 ACME Issuer using the Gateway API: 
        
           ```yaml 
        
           apiVersion: cert-manager.io/v1 
        
           kind: Issuer 
        
           metadata: 
        
             name: letsencrypt 
        
             namespace: default 
        
           spec: 
        
             acme: 
        
               solvers: 
        
                 - http01: 
        
                     gatewayHTTPRoute: 
        
                       parentRefs: 
        
                         - name: traefik 
        
                           namespace: traefik 
        
                           kind: Gateway 
        
           ```

content/docs/devops-tips/scaling-cert-manager.md

Mentions (in Helm values example):
- config.apiVersion: controller.config.cert-manager.io/v1alpha1
- config.kind: ControllerConfiguration

Ref:

website/content/docs/devops-tips/scaling-cert-manager.md

Lines 20 to 73 in 0e54695

    
           key pairs. 
        
           Why? Because the cert-manager controller caches the entire content of these Secret resources in memory. 
        
           If large TLS keys are used (e.g. RSA 4096) the memory use will be higher than if smaller TLS keys are used (e.g. ECDSA). 
        
           The other Secrets in the cluster, such as those used for Helm chart configurations or for other workloads, 
        
           will not significantly increase the memory consumption, because cert-manager will only cache the metadata of these Secrets. 
        
           **When `CertificateRequest` resources are the dominant use-case**, 
        
           such as with csi-driver or with istio-csr, 
        
           the memory consumption of the cert-manager controller will be much lower, 
        
           because there will be fewer TLS Secrets and fewer resources to be cached. 
        
           > 📖️ Read [What Everyone Should Know About Kubernetes Memory Limits](https://home.robusta.dev/blog/kubernetes-memory-limit), 
        
           > to learn how to right-size the memory requests. 
        
           ## Disable client-side rate limiting for Kubernetes API requests 
        
           By default cert-manager [throttles the rate of requests to the Kubernetes API server](https://github.com/cert-manager/cert-manager/blob/b61de55abda95a4c273be0c8d3e6025fe8511573/internal/apis/config/controller/v1alpha1/defaults.go#L59-L60) to 20 queries per second. 
        
           Historically this was intended to prevent cert-manager from overwhelming the Kubernetes API server, 
        
           but modern versions of Kubernetes implement [API Priority and Fairness](https://kubernetes.io/docs/concepts/cluster-administration/flow-control/), 
        
           which obviates the need for client side throttling. 
        
           You can increase the threshold of the client-side rate limiter using the following helm values: 
        
           ```yaml 
        
           # helm-values.yaml 
        
           config: 
        
             apiVersion: controller.config.cert-manager.io/v1alpha1 
        
             kind: ControllerConfiguration 
        
             kubernetesAPIQPS: 10000 
        
             kubernetesAPIBurst: 10000 
        
           ``` 
        
           > ℹ️ This does not technically disable the client-side rate-limiting but configures the QPS and Burst values high enough that they are never reached. 
        
           > 
        
           > 🔗 Read [`cert-manager#6890`: Allow client-side rate-limiting to be disabled](https://github.com/cert-manager/cert-manager/issues/6890); 
        
           > a proposal for a cert-manager configuration option to disable client-side rate-limiting. 
        
           > 
        
           > 🔗 Read [`kubernetes#111880`: Disable client-side rate-limiting when AP&F is enabled](https://github.com/kubernetes/kubernetes/issues/111880); 
        
           > a proposal that the `kubernetes.io/client-go` module should automatically use server-side rate-limiting when it is enabled. 
        
           > 
        
           > 🔗 Read about other projects that disable client-side rate limiting: [Flux](https://github.com/fluxcd/pkg/issues/269). 
        
           > 
        
           > 📖 Read [API documentation for ControllerConfiguration](../reference/api-docs.md#controller.config.cert-manager.io/v1alpha1.ControllerConfiguration) for a description of the `kubernetesAPIQPS` and `kubernetesAPIBurst` configuration options. 
        
           ## Restrict the use of large RSA keys 
        
           Certificates with large RSA keys cause cert-manager to use more CPU resources. 
        
           When there are insufficient CPU resources, the reconcile queue length grows, 
        
           which delays the reconciliation of all Certificates. 
        
           A user who has permission to create a large number of RSA 4096 certificates, 
        
           might accidentally or maliciously cause a denial of service for other users on the cluster. 
        
           > 📖 Learn [how to enforce an Approval Policy](../policy/approval/README.md), to prevent the use of large RSA keys. 
        
           >

content/docs/installation/configuring-components.md

Contains example configuration files (not Helm values) that include:
- apiVersion: controller.config.cert-manager.io/v1alpha1 / kind: ControllerConfiguration
- apiVersion: webhook.config.cert-manager.io/v1alpha1 / kind: WebhookConfiguration
These may or may not need changes depending on whether your “defaults” change applies only to Helm values (config: / webhook.config:) vs also to literal YAML config files on disk (the docs here are “configuration file” examples, not Helm values examples).

Ref:

website/content/docs/installation/configuring-components.md

Lines 13 to 96 in 0e54695

    
           - cert-manager webhook: [webhook CLI flags](../cli/webhook.md) 
        
           - cert-manager cainjector: [cainjector CLI flags](../cli/cainjector.md) 
        
           - cert-manager acmesolver: [acmesolver CLI flags](../cli/acmesolver.md) 
        
           - cert-manager cmctl: [cmctl CLI flags](../cli/cmctl.md) 
        
           When using the Helm chart, the CLI flags can be specified in the `extraArgs`, `webhook.extraArgs`, `cainjector.extraArgs` and `acmesolver.extraArgs` values. 
        
           ## Configuration file 
        
           The configuration file is a YAML file that contains the configuration for the cert-manager components. 
        
           The configuration file can be specified using the `--config` CLI flag. When using the Helm chart, the 
        
           configuration file can be specified in the `config` and `webhook.config` values. 
        
           ### Controller configuration file 
        
           The webhook configuration API documentation can be found on the [ControllerConfiguration](../reference/api-docs.md#controller.config.cert-manager.io/v1alpha1.ControllerConfiguration) page. 
        
           This is an example configuration file for the controller component: 
        
           ```yaml 
        
           apiVersion: controller.config.cert-manager.io/v1alpha1 
        
           kind: ControllerConfiguration 
        
           logging: 
        
             verbosity: 2 
        
             format: text 
        
           leaderElectionConfig: 
        
             namespace: my-namespace 
        
           kubernetesAPIQPS: 10 
        
           kubernetesAPIBurst: 50 
        
           numberOfConcurrentWorkers: 200 
        
           enableGatewayAPI: true 
        
           featureGates: 
        
             AdditionalCertificateOutputFormats: true 
        
             ExperimentalCertificateSigningRequestControllers: true 
        
             ServerSideApply: true 
        
             LiteralCertificateSubject: true 
        
             UseCertificateRequestBasicConstraints: true 
        
             OtherNames: true 
        
             UseDomainQualifiedFinalizer: true 
        
           ``` 
        
           > **Note:** This is included as an example only and not intended to be used as default settings. 
        
           ### Webhook configuration file 
        
           The webhook configuration API documentation can be found on the [WebhookConfiguration](../reference/api-docs.md#webhook.config.cert-manager.io/v1alpha1.WebhookConfiguration) page. 
        
           Here is an example configuration file for the webhook component: 
        
           ```yaml 
        
           apiVersion: webhook.config.cert-manager.io/v1alpha1 
        
           kind: WebhookConfiguration 
        
           logging: 
        
             verbosity: 2 
        
             format: text 
        
           securePort: 6443 
        
           healthzPort: 6080 
        
           featureGates: 
        
             AdditionalCertificateOutputFormats: true 
        
             LiteralCertificateSubject: true 
        
             OtherNames: true 
        
           ``` 
        
           > **Note:** This is included as an example only and not intended to be used as default settings. 
        
           ## Feature gates 
        
           Feature gates can be used to enable or disable experimental features in cert-manager. 
        
           There are 2 levels of feature gates (more details in [Kubernetes definition of feature stages](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages)): 
        
           - **Alpha:** feature is not yet stable and might be removed or changed in the future. Alpha features are disabled by default and need to be explicitly enabled by the user (to test the feature). 
        
           - **Beta:** feature is almost stable but might still change in the future. Beta features are enabled by default and can be disabled by the user (if any issues are encountered). 
        
           Each cert-manager component has its own set of feature gates. They can be enabled/ disabled using the `--feature-gates` flag or the `featureGates` value in the config file. The available feature gates for each component can be found on the following pages:

Release notes call-out (ma...

This pull request was created from Copilot chat.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: ThatsMrTalbot <15379715+ThatsMrTalbot@users.noreply.github.com>

cert-manager-prow · 2026-03-11T22:51:30Z

Thanks for your pull request. Before we can look at it, you'll need to add a 'DCO signoff' to your commits.

📝 Please follow instructions in the contributing guide to update your commits with the DCO

Full details of the Developer Certificate of Origin can be found at developercertificate.org.

The list of commits missing DCO signoff:

9778be2 Initial plan
77e7bb6 docs: remove config.apiVersion and config.kind from Helm values examples

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

netlify · 2026-03-11T22:51:36Z

✅ Deploy Preview for cert-manager ready!

Name	Link
🔨 Latest commit	`9778be2`
🔍 Latest deploy log	https://app.netlify.com/projects/cert-manager/deploys/69b1f16b803b5000072756c9
😎 Deploy Preview	https://deploy-preview-2011--cert-manager.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-03-11T22:53:15Z

✅ Deploy Preview for cert-manager ready!

Name	Link
🔨 Latest commit	`77e7bb6`
🔍 Latest deploy log	https://app.netlify.com/projects/cert-manager/deploys/69b1f1effd87000008e396d8
😎 Deploy Preview	https://deploy-preview-2011--cert-manager.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ThatsMrTalbot · 2026-03-11T22:55:58Z

/override dco

cert-manager-prow · 2026-03-11T22:56:03Z

@ThatsMrTalbot: Overrode contexts on behalf of ThatsMrTalbot: dco

Details

In response to this:

/override dco

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

hjoshi123 · 2026-03-12T02:06:28Z

Seems sane to me given we set the defaults.. verified that we do set the defaults

/approve

cert-manager-prow · 2026-03-12T02:06:36Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: hjoshi123

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [hjoshi123]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

hjoshi123 · 2026-03-12T02:13:18Z

/lgtm

maelvls · 2026-03-12T08:50:23Z

What was the original idea behind versioning the config if we end up defaulting the version? Having this default means eventually changing it will be a nightmare, won't it?

ThatsMrTalbot · 2026-03-12T10:44:36Z

What was the original idea behind versioning the config if we end up defaulting the version? Having this default means eventually changing it will be a nightmare, won't it?

It would be complicated for sure. Bumping from v1alpha1 to v1beta1 and then v1 would be simple enough if they all have the same fields, but if we ever want to make a breaking change then it would have to be handled carefully. We would have to leave Helm defaulting to the old version to not break peoples deployments for example.

Initial plan

9778be2

Copilot AI assigned Copilot and ThatsMrTalbot Mar 11, 2026

cert-manager-prow bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 11, 2026

Copilot started work on behalf of ThatsMrTalbot March 11, 2026 22:49 View session

cert-manager-prow bot added dco-signoff: no Indicates that at least one commit in this pull request is missing the DCO sign-off message. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Mar 11, 2026

docs: remove config.apiVersion and config.kind from Helm values examples

77e7bb6

Co-authored-by: ThatsMrTalbot <15379715+ThatsMrTalbot@users.noreply.github.com>

cert-manager-prow bot removed the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Mar 11, 2026

cert-manager-prow bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Mar 11, 2026

Copilot AI changed the title ~~[WIP] Update docs for Helm chart default config values~~ docs: remove config.apiVersion/kind from Helm values examples Mar 11, 2026

Copilot finished work on behalf of ThatsMrTalbot March 11, 2026 22:51

ThatsMrTalbot marked this pull request as ready for review March 11, 2026 22:55

cert-manager-prow bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 11, 2026

ThatsMrTalbot added dco-signoff: yes Indicates that all commits in the pull request have the valid DCO sign-off message. and removed dco-signoff: no Indicates that at least one commit in this pull request is missing the DCO sign-off message. labels Mar 11, 2026

Copilot AI mentioned this pull request Mar 11, 2026

config: exempt Copilot-authored PRs from DCO requirement in Tide cert-manager/testing#1160

Draft

cert-manager-prow bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 12, 2026

cert-manager-prow bot added the lgtm Indicates that a PR is ready to be merged. label Mar 12, 2026

cert-manager-prow bot merged commit 875dbd5 into master Mar 12, 2026
7 checks passed

wallrj-cyberark deleted the copilot/update-helm-chart-docs branch March 12, 2026 07:34

maelvls mentioned this pull request Mar 12, 2026

gateway.md: remove apiVersion and kind from ListenerSet conf example #2013

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: remove config.apiVersion/kind from Helm values examples#2011

docs: remove config.apiVersion/kind from Helm values examples#2011
cert-manager-prow[bot] merged 2 commits intomasterfrom
copilot/update-helm-chart-docs

Copilot AI commented Mar 11, 2026 •

edited

Loading

Uh oh!

cert-manager-prow bot commented Mar 11, 2026

Uh oh!

netlify bot commented Mar 11, 2026

Uh oh!

netlify bot commented Mar 11, 2026

Uh oh!

ThatsMrTalbot commented Mar 11, 2026

Uh oh!

cert-manager-prow bot commented Mar 11, 2026

Uh oh!

hjoshi123 commented Mar 12, 2026

Uh oh!

cert-manager-prow bot commented Mar 12, 2026

Uh oh!

hjoshi123 commented Mar 12, 2026

Uh oh!

Uh oh!

maelvls commented Mar 12, 2026

Uh oh!

ThatsMrTalbot commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


	⚠️ ListenerSet support is now available in cert-manager v1.20.0-beta.0+.
	This enables self-service TLS configuration for application developers without
	requiring edit access to Gateway resources. See the [ListenerSet
	section](#listenerset) below for details.

	:::

	The Gateway resource holds the TLS configuration, as illustrated in the
	following diagram (source: https://gateway-api.sigs.k8s.io):

	![Gateway vs. HTTPRoute](/images/gateway-roles.png)

	:::info

	📌 This feature requires the installation of the [Gateway API bundle](https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api) and passing an
	additional flag to the cert-manager controller.

	To install v1.4.1 Gateway API bundle (CRDs associated with a version of Gateway API), run the following command:

	```sh
	kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml
	```

	Since cert-manager 1.15, the Gateway API support is no longer gated behind a
	feature flag, but you still need to enable the Gateway API support.

	To enable the Gateway API support, use the [file-based
	configuration](../installation/configuring-components.md#configuration-file) using the
	following `config` Helm value:

	```yaml
	config:
	apiVersion: controller.config.cert-manager.io/v1alpha1
	kind: ControllerConfiguration
	enableGatewayAPI: true
	```

	The corresponding Helm command is:

	```sh
	helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager --namespace cert-manager \
	--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
	--set config.kind="ControllerConfiguration" \
	--set config.enableGatewayAPI=true
	```

	The Gateway API CRDs should either be installed before cert-manager starts or
	the cert-manager Deployment should be restarted after installing the Gateway API
	CRDs. This is important because some of the cert-manager components only perform
	the Gateway API check on startup. You can restart cert-manager with the
	following command:

	```sh
	kubectl rollout restart deployment cert-manager -n cert-manager
	```

	:::

	The annotations `cert-manager.io/issuer` or `cert-manager.io/cluster-issuer`
	tell cert-manager to create a Certificate for a Gateway. For example, the
	following Gateway will trigger the creation of a Certificate with the name
	`example-com-tls`:

	```yaml
	apiVersion: gateway.networking.k8s.io/v1
	kind: Gateway
	metadata:
	name: example
	annotations:
	cert-manager.io/issuer: foo
	spec:
	gatewayClassName: foo
	listeners:
	- name: http
	hostname: example.com
	port: 443
	protocol: HTTPS
	allowedRoutes:
	namespaces:
	from: All
	tls:
	mode: Terminate
	certificateRefs:
	- name: example-com-tls
	```

	A few moments later, cert-manager will create a Certificate. The Certificate is
	named after the Secret name `example-com-tls`. The `dnsNames` field is set with
	the `hostname` field from the Gateway spec.

	```yaml
	apiVersion: cert-manager.io/v1
	kind: Certificate
	metadata:
	name: example-com-tls
	spec:
	issuerRef:
	name: my-issuer
	kind: Issuer
	group: cert-manager.io
	dnsNames:

	# custom configuration
	venafi.cert-manager.io/custom-fields: `[ {"name": "field-name", "value": "field value"}]`
	```

	## ListenerSet

	FEATURE STATE: cert-manager 1.20 [alpha]

	### What is ListenerSet?

	ListenerSet is a Gateway API resource introduced in
	[GEP-1713](https://gateway-api.sigs.k8s.io/geps/gep-1713/) that solves a key
	limitation when migrating from Ingress to Gateway API: the loss of self-service
	TLS configuration for application developers.

	With Ingress resources, developers could independently configure both routing
	and TLS certificates using cert-manager annotations. When migrating to Gateway
	API, TLS configuration moves to the Gateway resource, which is typically
	controlled by cluster operators. This forces developers to ask for changes to
	resources they do not own, losing the autonomy they had with Ingress.

	ListenerSet restores self-service by allowing developers to create a ListenerSet
	resource alongside their HTTPRoute. The same annotations as for Gateway can be
	used on the ListenerSet to trigger the creation of a Certificate resource.

	### Enabling ListenerSet Support

	ListenerSet support requires Gateway API v1.5+ (standard channel). The
	instructions for installing the CRDs can be found in the Gateway API
	documentation: [Installing Gateway API][install-gapi].

	[install-gapi]: https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api

	To start using ListenerSet, you will have to enable the feature in cert-manager.
	We recommend you use the [file-based
	configuration](../installation/configuring-components.md#configuration-file). In
	your `values.yaml`, add the following:

	```yaml
	# values.yaml
	config:
	apiVersion: controller.config.cert-manager.io/v1alpha1
	kind: ControllerConfiguration
	enableGatewayAPI: true
	enableGatewayAPIListenerSet: true
	featureGates:
	ListenerSets: true
	```

	The `enableGatewayAPI` setting tells cert-manager to reconcile the Gateway
	resources, and `enableGatewayAPIListenerSet` tells cert-manager to also
	reconcile ListenerSet resources.

	The corresponding Helm command is:

	```sh
	helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
	--namespace cert-manager \
	--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
	--set config.kind="ControllerConfiguration" \
	--set config.enableGatewayAPI=true \
	--set config.enableGatewayAPIListenerSet=true \
	--set config.featureGates.ListenerSets=true
	```

	After installation, restart cert-manager to ensure it picks up the new CRDs:

	```sh
	kubectl rollout restart deployment cert-manager -n cert-manager
	```

	### Example: Self-Service TLS with ListenerSet and HTTP-01

	Here's a complete example showing how application developers can manage their
	own TLS configuration. Let's start with the shared ClusterIssuer and Gateway
	created by the cluster operator:

	```yaml
	kind: ClusterIssuer
	apiVersion: cert-manager.io/v1
	metadata:
	name: letsencrypt
	spec:
	acme:
	server: https://acme-v02.api.letsencrypt.org/directory
	email: platformteam@example.com
	privateKeySecretRef:
	name: letsencrypt-acc-key
	solvers:
	- http01:
	gatewayHTTPRoute: {}
	---
	apiVersion: gateway.networking.k8s.io/v1
	kind: Gateway
	metadata:
	name: eg
	namespace: envoy-gateway-system
	spec:

	annotations:
	"nginx.ingress.kubernetes.io/whitelist-source-range": "0.0.0.0/0,::/0"
	"nginx.org/mergeable-ingress-type": "minion"
	"traefik.ingress.kubernetes.io/frontend-entry-points": "http"
	```

	The added labels and annotations will merge on top of the cert-manager defaults,
	overriding entries with the same key.

	No other fields of the ingress can be edited.

	## Configuring the HTTP-01 Gateway API solver

	FEATURE STATE: cert-manager 1.15 [beta]

	The Gateway and HTTPRoute resources are part of the [Gateway API][gwapi], a set
	of CRDs that you install on your Kubernetes cluster that provide various
	improvements over the Ingress API.

	[gwapi]: https://gateway-api.sigs.k8s.io

	:::info

	📌 This feature requires the installation of the [Gateway API bundle](https://gateway-api.sigs.k8s.io/guides/getting-started/#installing-gateway-api) and passing an
	additional flag to the cert-manager controller.

	To install v1.4.1 Gateway API bundle (CRDs associated with a version of Gateway API), run the following command:

	```sh
	kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml
	```

	Since cert-manager 1.15, the Gateway API support is no longer gated behind a
	feature flag, but you still need to enable the Gateway API support.

	To enable the Gateway API support, use the [file-based
	configuration](../../../installation/configuring-components.md#configuration-file) using the
	following `config` Helm value:

	```yaml
	config:
	apiVersion: controller.config.cert-manager.io/v1alpha1
	kind: ControllerConfiguration
	enableGatewayAPI: true
	```

	The corresponding Helm command is:

	```sh
	helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager --namespace cert-manager \
	--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
	--set config.kind="ControllerConfiguration" \
	--set config.enableGatewayAPI=true
	```

	The Gateway API CRDs should either be installed before cert-manager starts or
	the cert-manager Deployment should be restarted after installing the Gateway API
	CRDs. This is important because some of the cert-manager components only perform
	the Gateway API check on startup. You can restart cert-manager with the
	following command:

	```sh
	kubectl rollout restart deployment cert-manager -n cert-manager
	```

	:::


	:::info

	🚧 cert-manager 1.14+ is tested with v1 Kubernetes Gateway API. It should also work
	with v1beta1 and v1alpha2 because of resource conversion, but has not been tested with it.

	:::

	The Gateway API HTTPRoute HTTP-01 solver creates a temporary HTTPRoute using the
	given labels. These labels must match a Gateway that contains a listener on port
	80.

	Here is an example of a HTTP-01 ACME Issuer using the Gateway API:

	```yaml
	apiVersion: cert-manager.io/v1
	kind: Issuer
	metadata:
	name: letsencrypt
	namespace: default
	spec:
	acme:
	solvers:
	- http01:
	gatewayHTTPRoute:
	parentRefs:
	- name: traefik
	namespace: traefik
	kind: Gateway
	```

	key pairs.
	Why? Because the cert-manager controller caches the entire content of these Secret resources in memory.
	If large TLS keys are used (e.g. RSA 4096) the memory use will be higher than if smaller TLS keys are used (e.g. ECDSA).

	The other Secrets in the cluster, such as those used for Helm chart configurations or for other workloads,
	will not significantly increase the memory consumption, because cert-manager will only cache the metadata of these Secrets.

	When `CertificateRequest` resources are the dominant use-case,
	such as with csi-driver or with istio-csr,
	the memory consumption of the cert-manager controller will be much lower,
	because there will be fewer TLS Secrets and fewer resources to be cached.

	> 📖️ Read [What Everyone Should Know About Kubernetes Memory Limits](https://home.robusta.dev/blog/kubernetes-memory-limit),
	> to learn how to right-size the memory requests.

	## Disable client-side rate limiting for Kubernetes API requests

	By default cert-manager [throttles the rate of requests to the Kubernetes API server](https://github.com/cert-manager/cert-manager/blob/b61de55abda95a4c273be0c8d3e6025fe8511573/internal/apis/config/controller/v1alpha1/defaults.go#L59-L60) to 20 queries per second.
	Historically this was intended to prevent cert-manager from overwhelming the Kubernetes API server,
	but modern versions of Kubernetes implement [API Priority and Fairness](https://kubernetes.io/docs/concepts/cluster-administration/flow-control/),
	which obviates the need for client side throttling.
	You can increase the threshold of the client-side rate limiter using the following helm values:

	```yaml
	# helm-values.yaml
	config:
	apiVersion: controller.config.cert-manager.io/v1alpha1
	kind: ControllerConfiguration
	kubernetesAPIQPS: 10000
	kubernetesAPIBurst: 10000
	```

	> ℹ️ This does not technically disable the client-side rate-limiting but configures the QPS and Burst values high enough that they are never reached.
	>
	> 🔗 Read [`cert-manager#6890`: Allow client-side rate-limiting to be disabled](https://github.com/cert-manager/cert-manager/issues/6890);
	> a proposal for a cert-manager configuration option to disable client-side rate-limiting.
	>
	> 🔗 Read [`kubernetes#111880`: Disable client-side rate-limiting when AP&F is enabled](https://github.com/kubernetes/kubernetes/issues/111880);
	> a proposal that the `kubernetes.io/client-go` module should automatically use server-side rate-limiting when it is enabled.
	>
	> 🔗 Read about other projects that disable client-side rate limiting: [Flux](https://github.com/fluxcd/pkg/issues/269).
	>
	> 📖 Read [API documentation for ControllerConfiguration](../reference/api-docs.md#controller.config.cert-manager.io/v1alpha1.ControllerConfiguration) for a description of the `kubernetesAPIQPS` and `kubernetesAPIBurst` configuration options.

	## Restrict the use of large RSA keys

	Certificates with large RSA keys cause cert-manager to use more CPU resources.
	When there are insufficient CPU resources, the reconcile queue length grows,
	which delays the reconciliation of all Certificates.
	A user who has permission to create a large number of RSA 4096 certificates,
	might accidentally or maliciously cause a denial of service for other users on the cluster.

	> 📖 Learn [how to enforce an Approval Policy](../policy/approval/README.md), to prevent the use of large RSA keys.
	>

	- cert-manager webhook: [webhook CLI flags](../cli/webhook.md)
	- cert-manager cainjector: [cainjector CLI flags](../cli/cainjector.md)
	- cert-manager acmesolver: [acmesolver CLI flags](../cli/acmesolver.md)
	- cert-manager cmctl: [cmctl CLI flags](../cli/cmctl.md)

	When using the Helm chart, the CLI flags can be specified in the `extraArgs`, `webhook.extraArgs`, `cainjector.extraArgs` and `acmesolver.extraArgs` values.

	## Configuration file

	The configuration file is a YAML file that contains the configuration for the cert-manager components.
	The configuration file can be specified using the `--config` CLI flag. When using the Helm chart, the
	configuration file can be specified in the `config` and `webhook.config` values.

	### Controller configuration file

	The webhook configuration API documentation can be found on the [ControllerConfiguration](../reference/api-docs.md#controller.config.cert-manager.io/v1alpha1.ControllerConfiguration) page.

	This is an example configuration file for the controller component:

	```yaml
	apiVersion: controller.config.cert-manager.io/v1alpha1
	kind: ControllerConfiguration

	logging:
	verbosity: 2
	format: text

	leaderElectionConfig:
	namespace: my-namespace

	kubernetesAPIQPS: 10
	kubernetesAPIBurst: 50

	numberOfConcurrentWorkers: 200

	enableGatewayAPI: true

	featureGates:
	AdditionalCertificateOutputFormats: true
	ExperimentalCertificateSigningRequestControllers: true
	ServerSideApply: true
	LiteralCertificateSubject: true
	UseCertificateRequestBasicConstraints: true
	OtherNames: true
	UseDomainQualifiedFinalizer: true
	```

	> Note: This is included as an example only and not intended to be used as default settings.

	### Webhook configuration file

	The webhook configuration API documentation can be found on the [WebhookConfiguration](../reference/api-docs.md#webhook.config.cert-manager.io/v1alpha1.WebhookConfiguration) page.

	Here is an example configuration file for the webhook component:

	```yaml
	apiVersion: webhook.config.cert-manager.io/v1alpha1
	kind: WebhookConfiguration

	logging:
	verbosity: 2
	format: text

	securePort: 6443
	healthzPort: 6080

	featureGates:
	AdditionalCertificateOutputFormats: true
	LiteralCertificateSubject: true
	OtherNames: true
	```

	> Note: This is included as an example only and not intended to be used as default settings.

	## Feature gates

	Feature gates can be used to enable or disable experimental features in cert-manager.

	There are 2 levels of feature gates (more details in [Kubernetes definition of feature stages](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages)):
	- Alpha: feature is not yet stable and might be removed or changed in the future. Alpha features are disabled by default and need to be explicitly enabled by the user (to test the feature).
	- Beta: feature is almost stable but might still change in the future. Beta features are enabled by default and can be disabled by the user (if any issues are encountered).

	Each cert-manager component has its own set of feature gates. They can be enabled/ disabled using the `--feature-gates` flag or the `featureGates` value in the config file. The available feature gates for each component can be found on the following pages:

Conversation

Copilot AI commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Before / After

Uh oh!

cert-manager-prow bot commented Mar 11, 2026

Uh oh!

netlify bot commented Mar 11, 2026

✅ Deploy Preview for cert-manager ready!

Uh oh!

netlify bot commented Mar 11, 2026

✅ Deploy Preview for cert-manager ready!

Uh oh!

ThatsMrTalbot commented Mar 11, 2026

Uh oh!

cert-manager-prow bot commented Mar 11, 2026

Uh oh!

hjoshi123 commented Mar 12, 2026

Uh oh!

cert-manager-prow bot commented Mar 12, 2026

Uh oh!

hjoshi123 commented Mar 12, 2026

Uh oh!

Uh oh!

maelvls commented Mar 12, 2026

Uh oh!

ThatsMrTalbot commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Mar 11, 2026 •

edited

Loading