From 3d64a71aebb7403ed818fa1537a3608363e2e39f Mon Sep 17 00:00:00 2001 From: srir Date: Mon, 4 Aug 2025 14:27:18 +0530 Subject: [PATCH] OSDOCS#15157: Added new overridable arguments to the cert-manager controller --- .../cert-manager-configure-cpu-memory.adoc | 55 +++--- ...-explanation-of-certmanager-cr-fields.adoc | 178 ++++++++++++++++++ modules/cert-manager-override-arguments.adoc | 30 ++- ...anager-override-environment-variables.adoc | 5 + modules/cert-manager-override-scheduling.adoc | 25 +-- .../cert-manager-customizing-api-fields.adoc | 85 ++++++++- 6 files changed, 309 insertions(+), 69 deletions(-) create mode 100644 modules/cert-manager-explanation-of-certmanager-cr-fields.adoc diff --git a/modules/cert-manager-configure-cpu-memory.adoc b/modules/cert-manager-configure-cpu-memory.adoc index cfd51ff0ae..bf017fd7ef 100644 --- a/modules/cert-manager-configure-cpu-memory.adoc +++ b/modules/cert-manager-configure-cpu-memory.adoc @@ -6,7 +6,7 @@ [id="cert-manager-configure-cpu-memory_{context}"] = Overriding CPU and memory limits for the cert-manager components -After installing the {cert-manager-operator}, you can configure the CPU and memory limits from the {cert-manager-operator} API for the cert-manager components such as cert-manager controller, CA injector, and Webhook. +After installing the {cert-manager-operator}, you can configure the CPU and memory limits from the {cert-manager-operator} API for the cert-manager components, such as the cert-manager controller, CA injector, and Webhook. .Prerequisites @@ -80,48 +80,37 @@ $ oc get deployment -n cert-manager -o yaml . To configure the CPU and memory limits for the cert-manager controller, CA injector, and Webhook, enter the following command: + -[source,yaml] +[source,terminal] ---- $ oc patch certmanager.operator cluster --type=merge -p=" spec: controllerConfig: - overrideResources: - limits: <1> - cpu: 200m <2> - memory: 64Mi <3> - requests: <4> - cpu: 10m <2> - memory: 16Mi <3> + overrideResources: <1> + limits: + cpu: 200m + memory: 64Mi + requests: + cpu: 10m + memory: 16Mi webhookConfig: overrideResources: - limits: <5> - cpu: 200m <6> - memory: 64Mi <7> - requests: <8> - cpu: 10m <6> - memory: 16Mi <7> + limits: + cpu: 200m + memory: 64Mi + requests: + cpu: 10m + memory: 16Mi cainjectorConfig: overrideResources: - limits: <9> - cpu: 200m <10> - memory: 64Mi <11> - requests: <12> - cpu: 10m <10> - memory: 16Mi <11> + limits: + cpu: 200m + memory: 64Mi + requests: + cpu: 10m + memory: 16Mi " ---- -<1> Defines the maximum amount of CPU and memory that a single container in a cert-manager controller pod can request. -<2> You can specify the CPU limit that a cert-manager controller pod can request. The default value is `10m`. -<3> You can specify the memory limit that a cert-manager controller pod can request. The default value is `32Mi`. -<4> Defines the amount of CPU and memory set by scheduler for the cert-manager controller pod. -<5> Defines the maximum amount of CPU and memory that a single container in a CA injector pod can request. -<6> You can specify the CPU limit that a CA injector pod can request. The default value is `10m`. -<7> You can specify the memory limit that a CA injector pod can request. The default value is `32Mi`. -<8> Defines the amount of CPU and memory set by scheduler for the CA injector pod. -<9> Defines the maximum amount of CPU and memory Defines the maximum amount of CPU and memory that a single container in a Webhook pod can request. -<10> You can specify the CPU limit that a Webhook pod can request. The default value is `10m`. -<11> You can specify the memory limit that a Webhook pod can request. The default value is `32Mi`. -<12> Defines the amount of CPU and memory set by scheduler for the Webhook pod. +<1> For information about the overridable resource parameters, see "Overridable resource parameters for the cert-manager components" in "Explanation of fields in the CertManager custom resource". + .Example output [source,terminal] diff --git a/modules/cert-manager-explanation-of-certmanager-cr-fields.adoc b/modules/cert-manager-explanation-of-certmanager-cr-fields.adoc new file mode 100644 index 0000000000..86d7899104 --- /dev/null +++ b/modules/cert-manager-explanation-of-certmanager-cr-fields.adoc @@ -0,0 +1,178 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-customizing-api-fields.adoc + +:_mod-docs-content-type: CONCEPT +[id="cert-manager-explanation-of-certmanager-cr-fields_{context}"] += Explanation of fields in the CertManager custom resource + +You can use the `CertManager` custom resource (CR) to configure the following core components of the {cert-manager-operator}: + +* Cert-manager controller: You can use the `spec.controllerConfig` field to configure the cert‑manager controller pod. +* Webhook: You can use the `spec.webhookConfig` field to configure the webhook pod, which handles validation and mutation requests. +* CA injector: You can use the `spec.cainjectorConfig` field to configure the CA injector pod. + +[id="cert-manager-common-configuration-fields_{context}"] +== Common configurable fields in the CertManager CR for the cert-manager components + +The following table lists the common fields that you can configure in the `spec.controllerConfig`, `spec.webhookConfig`, and `spec.cainjectorConfig` sections in the `CertManager` CR. + +.Common configurable fields in the CertManager CR for the cert-manager components +[cols=".^2,.^2,.^6a",options="header"] +|==== + +|Field|Type|Description + +|`overrideArgs` +|`string` +|You can override the supported arguments for the cert-manager components. + +|`overrideEnv` +|`dict` +|You can override the supported environment variables for the cert-manager controller. This field is only supported for the cert-manager controller component. + +|`overrideResources` +|`object` +|You can configure the CPU and memory limits for the cert-manager components. + +|`overrideScheduling` +|`object` +|You can configure the pod scheduling constraints for the cert-manager components. + +|==== + +[id="cert-manager-overridable-arguments_{context}"] +== Overridable arguments for the cert-manager components + +You can configure the overridable arguments for the cert-manager components in the `spec.controllerConfig`, `spec.webhookConfig`, and `spec.cainjectorConfig` sections in the `CertManager` CR. + +The following table describes the overridable arguments for the cert-manager components: + +.Overridable arguments the cert-manager components +[cols=".^5a,.^2,.^4a",options="header"] +|==== + +|Argument|Component|Description + +|`--dns01-recursive-nameservers=` +|Controller +|Provide a comma-separated list of nameservers to query for the DNS-01 self check. The nameservers can be specified either as `:`, for example, `1.1.1.1:53`, or use DNS over HTTPS (DoH), for example, `\https://1.1.1.1/dns-query`. + +[NOTE] +==== +DNS over HTTPS (DoH) is supported starting only from {cert-manager-operator} version 1.13.0 and later. +==== + +|`--dns01-recursive-nameservers-only` +|Controller +|Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain. + +|`--acme-http01-solver-nameservers=:` +|Controller +|Provide a comma-separated list of `:` nameservers to query for the Automated Certificate Management Environment (ACME) HTTP01 self check. For example, `--acme-http01-solver-nameservers=1.1.1.1:53`. + +|`--metrics-listen-address=:` +|Controller +|Specify the host and port for the metrics endpoint. The default value is `--metrics-listen-address=0.0.0.0:9402`. + +|`--issuer-ambient-credentials` +|Controller +|You can use this argument to configure an ACME Issuer to solve DNS-01 challenges by using ambient credentials. + +|`--enable-certificate-owner-ref` +|Controller +|This argument sets the certificate resource as an owner of the secret where the TLS certificate is stored. For more information, see "Deleting a TLS secret automatically upon Certificate removal". + +|`--acme-http01-solver-resource-limits-cpu` +|Controller +|Defines the maximum CPU limit for ACME HTTP‑01 solver pods. The default value is `100m`. + +|`--acme-http01-solver-resource-limits-memory` +|Controller +|Defines the maximum memory limit for ACME HTTP‑01 solver pods. The default value is `64Mi`. + +|`--acme-http01-solver-resource-request-cpu` +|Controller +|Defines the minimum CPU request for ACME HTTP‑01 solver pods. The default value is `10m`. + +|`--acme-http01-solver-resource-request-memory` +|Controller +|Defines the minimum memory request for ACME HTTP‑01 solver pods. The default value is `64Mi`. + +|`--v=` +|Controller, Webhook, CA injector +|Specify the log level verbosity to determine the verbosity of log messages. + +|==== + +[id="cert-manager-overridable-env-variables_{context}"] +== Overridable environment variables for the cert-manager controller + +You can configure the overridable environment variables for the cert-manager controller in the `spec.controllerConfig.overrideEnv` field in the `CertManager` CR. + +The following table describes the overridable environment variables for the cert-manager controller: + +.Overridable environment variables for the cert-manager controller +[cols=".^2,.^2",options="header"] +|==== + +|Environment variable|Description + +|`HTTP_PROXY` +|Proxy server for outgoing HTTP requests. + +|`HTTPS_PROXY` +|Proxy server for outgoing HTTPS requests. + +|`NO_PROXY` +|Comma‑separated list of hosts that bypass the proxy. + +|==== + +[id="cert-manager-overridable-resource-parameters_{context}"] +== Overridable resource parameters for the cert-manager components + +You can configure the CPU and memory limits for the cert-manager components in the `spec.controllerConfig`, `spec.webhookConfig`, and `spec.cainjectorConfig` sections in the `CertManager` CR. + +The following table describes the overridable resource parameters for the cert-manager components: + +.Overridable resource parameters for the cert-manager components +[cols=".^2,.^2",options="header"] +|==== + +|Field|Description + +|`overrideResources.limits.cpu` +|Defines the maximum amount of CPU that a component pod can use. + +|`overrideResources.limits.memory` +|Defines the maximum amount of memory that a component pod can use. + +|`overrideResources.requests.cpu` +|Defines the minimum amount of CPU requested by the scheduler for a component pod. + +|`overrideResources.requests.memory` +|Defines the minimum amount of memory requested by the scheduler for a component pod. + +|==== + +[id="cert-manager-overridable-scheduling-parameters_{context}"] +== Overridable scheduling parameters for the cert-manager components + +You can configure the pod scheduling constrainsts for the cert-manager components in the `spec.controllerConfig`, `spec.webhookConfig` field, and `spec.cainjectorConfig` sections in the `CertManager` CR. + +The following table describes the pod scheduling parameters for the cert-manager components: + +.Overridable scheduling parameters for the cert-manager components +[cols=".^2,.^2",options="header"] +|==== + +|Field|Description + +|`overrideScheduling.nodeSelector` +|Key‑value pairs to constrain pods to specific nodes. + +|`overrideScheduling.tolerations` +|List of tolerations to schedule pods on tainted nodes. + +|==== \ No newline at end of file diff --git a/modules/cert-manager-override-arguments.adoc b/modules/cert-manager-override-arguments.adoc index 8fcec3826b..a1fbc78aed 100644 --- a/modules/cert-manager-override-arguments.adoc +++ b/modules/cert-manager-override-arguments.adoc @@ -35,29 +35,23 @@ spec: controllerConfig: overrideArgs: - '--dns01-recursive-nameservers=' <1> - - '--dns01-recursive-nameservers-only' <2> - - '--acme-http01-solver-nameservers=:' <3> - - '--v=' <4> - - '--metrics-listen-address=:' <5> - - '--issuer-ambient-credentials' <6> + - '--dns01-recursive-nameservers-only' + - '--acme-http01-solver-nameservers=:' + - '--v=' + - '--metrics-listen-address=:' + - '--issuer-ambient-credentials' + - '--acme-http01-solver-resource-limits-cpu=' + - '--acme-http01-solver-resource-limits-memory=' + - '--acme-http01-solver-resource-request-cpu=' + - '--acme-http01-solver-resource-request-memory=' webhookConfig: overrideArgs: - - '--v=4' <4> + - '--v=' cainjectorConfig: overrideArgs: - - '--v=2' <4> + - '--v=' ---- -<1> Provide a comma-separated list of nameservers to query for the DNS-01 self check. The nameservers can be specified either as `:`, for example, `1.1.1.1:53`, or use DNS over HTTPS (DoH), for example, `https://1.1.1.1/dns-query`. -<2> Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain. -<3> Provide a comma-separated list of `:` nameservers to query for the Automated Certificate Management Environment (ACME) HTTP01 self check. For example, `--acme-http01-solver-nameservers=1.1.1.1:53`. -<4> Specify to set the log level verbosity to determine the verbosity of log messages. -<5> Specify the host and port for the metrics endpoint. The default value is `--metrics-listen-address=0.0.0.0:9402`. -<6> You must use the `--issuer-ambient-credentials` argument when configuring an ACME Issuer to solve DNS-01 challenges by using ambient credentials. -+ -[NOTE] -==== -DNS over HTTPS (DoH) is supported starting only from {cert-manager-operator} version 1.13.0 and later. -==== +<1> For information about the overridable aruguments, see "Overridable arguments for the cert-manager components" in "Explanation of fields in the CertManager custom resource". . Save your changes and quit the text editor to apply your changes. diff --git a/modules/cert-manager-override-environment-variables.adoc b/modules/cert-manager-override-environment-variables.adoc index 5850ad5511..e7e07e4cf8 100644 --- a/modules/cert-manager-override-environment-variables.adoc +++ b/modules/cert-manager-override-environment-variables.adoc @@ -43,6 +43,11 @@ spec: ---- <1> Replace `` with the proxy server URL. <2> Replace `` with a comma separated list of domains. These domains are ignored by the proxy server. ++ +[NOTE] +==== +For more information about the overridable environment variables, see "Overridable environment variables for the cert-manager components" in "Explanation of fields in the CertManager custom resource". +==== . Save your changes and quit the text editor to apply your changes. diff --git a/modules/cert-manager-override-scheduling.adoc b/modules/cert-manager-override-scheduling.adoc index 7aea5c1332..8028dce8aa 100644 --- a/modules/cert-manager-override-scheduling.adoc +++ b/modules/cert-manager-override-scheduling.adoc @@ -6,7 +6,7 @@ [id="cert-manager-override-scheduling_{context}"] = Configuring scheduling overrides for cert-manager components -You can configure the pod scheduling from the {cert-manager-operator} API for the {cert-manager-operator} components such as cert-manager controller, CA injector, and Webhook. +You can configure the pod scheduling from the {cert-manager-operator} API for the {cert-manager-operator} components, such as the cert-manager controller, CA injector, and Webhook. .Prerequisites @@ -22,37 +22,32 @@ You can configure the pod scheduling from the {cert-manager-operator} API for th $ oc patch certmanager.operator cluster --type=merge -p=" spec: controllerConfig: - overrideScheduling: + overrideScheduling: <1> nodeSelector: - node-role.kubernetes.io/control-plane: '' <1> + node-role.kubernetes.io/control-plane: '' tolerations: - key: node-role.kubernetes.io/master operator: Exists - effect: NoSchedule <2> + effect: NoSchedule webhookConfig: overrideScheduling: nodeSelector: - node-role.kubernetes.io/control-plane: '' <3> + node-role.kubernetes.io/control-plane: '' tolerations: - key: node-role.kubernetes.io/master operator: Exists - effect: NoSchedule <4> + effect: NoSchedule cainjectorConfig: overrideScheduling: nodeSelector: - node-role.kubernetes.io/control-plane: '' <5> + node-role.kubernetes.io/control-plane: '' tolerations: - key: node-role.kubernetes.io/master operator: Exists - effect: NoSchedule" <6> + effect: NoSchedule" +" ---- -<1> Defines the `nodeSelector` for the cert-manager controller deployment. -<2> Defines the `tolerations` for the cert-manager controller deployment. -<3> Defines the `nodeSelector` for the cert-manager webhook deployment. -<4> Defines the `tolerations` for the cert-manager webhook deployment. -<5> Defines the `nodeSelector` for the cert-manager cainjector deployment. -<6> Defines the `tolerations` for the cert-manager cainjector deployment. - +<1> For information about the overridable scheduling parameters, see "Overridable scheduling parameters for the cert-manager components" in "Explanation of fields in the CertManager custom resource". .Verification diff --git a/security/cert_manager_operator/cert-manager-customizing-api-fields.adoc b/security/cert_manager_operator/cert-manager-customizing-api-fields.adoc index 28d6f4c566..0d7a2dde71 100644 --- a/security/cert_manager_operator/cert-manager-customizing-api-fields.adoc +++ b/security/cert_manager_operator/cert-manager-customizing-api-fields.adoc @@ -1,24 +1,103 @@ :_mod-docs-content-type: ASSEMBLY [id="cert-manager-customizing-api-fields"] -= Customizing cert-manager Operator API fields += Customizing the cert-manager Operator by using the CertManager custom resource include::_attributes/common-attributes.adoc[] :context: cert-manager-customizing-api-fields toc::[] -You can customize the {cert-manager-operator} API fields by overriding environment variables and arguments. +After installing the {cert-manager-operator}, you can perform the following actions by configuring the `CertManager` custom resource (CR): + +* Configure the arguments to modify the behavior of the cert-manager components, such as the cert-manager controller, CA injector, and Webhook. +* Set environment variables for the controller pod. +* Define resource requests and limits to manage CPU and memory usage. +* Configure scheduling rules to control where pods run in your cluster. + +.Example CertManager CR YAML file +[source,yaml] +---- +apiVersion: operator.openshift.io/v1alpha1 +kind: CertManager +metadata: + name: cluster +spec: + controllerConfig: + overrideArgs: + - "--dns01-recursive-nameservers=8.8.8.8:53,1.1.1.1:53" + overrideEnv: + - name: HTTP_PROXY + value: http://proxy.example.com:8080 + overrideResources: + limits: + cpu: "200m" + memory: "512Mi" + requests: + cpu: "100m" + memory: "256Mi" + overrideScheduling: + nodeSelector: + custom: "label" + tolerations: + - key: "key1" + operator: "Equal" + value: "value1" + effect: "NoSchedule" + + webhookConfig: + overrideArgs: +#... + overrideResources: +#... + overrideScheduling: +#... + + cainjectorConfig: + overrideArgs: +#... + overrideResources: +#... + overrideScheduling: +#... +---- [WARNING] ==== To override unsupported arguments, you can add `spec.unsupportedConfigOverrides` section in the `CertManager` resource, but using `spec.unsupportedConfigOverrides` is unsupported. ==== +include::modules/cert-manager-explanation-of-certmanager-cr-fields.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/cert-manager-customizing-api-fields.adoc#cert-manager-override-flag-controller_cert-manager-customizing-api-fields[Deleting a TLS secret automatically upon Certificate removal] + include::modules/cert-manager-override-environment-variables.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/cert-manager-customizing-api-fields.adoc#cert-manager-explanation-of-certmanager-cr-fields_cert-manager-customizing-api-fields[Explanation of fields in the CertManager custom resource] + include::modules/cert-manager-override-arguments.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/cert-manager-customizing-api-fields.adoc#cert-manager-explanation-of-certmanager-cr-fields_cert-manager-customizing-api-fields[Explanation of fields in the CertManager custom resource] + include::modules/cert-manager-override-flag-controller.adoc[leveloffset=+1] include::modules/cert-manager-configure-cpu-memory.adoc[leveloffset=+1] -include::modules/cert-manager-override-scheduling.adoc[leveloffset=+1] \ No newline at end of file +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/cert-manager-customizing-api-fields.adoc#cert-manager-explanation-of-certmanager-cr-fields_cert-manager-customizing-api-fields[Explanation of fields in the CertManager custom resource] + +include::modules/cert-manager-override-scheduling.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/cert-manager-customizing-api-fields.adoc#cert-manager-explanation-of-certmanager-cr-fields_cert-manager-customizing-api-fields[Explanation of fields in the CertManager custom resource] \ No newline at end of file