Skip to content

Commit b6f2427

Browse files
lahinsonlahinson
authored
Merge pull request #108044 from wgabor0427/OSDOCS-17771
OSDOCS-17771 updated customizing ESO
2 parents 4c021ee + 506a3f7 commit b6f2427

4 files changed

Lines changed: 252 additions & 1 deletion

‎modules/external-secrets-operator-adding-custom-annotations.adoc‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-log-levels.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-enable-operator-adding-custom-annotations_{context}"]
7+
= Adding custom annotations to external-secrets resources
8+
9+
[role="_abstract"]
10+
To customize your resources, you can define up to 20 custom annotations in the custom resource (CR). The Operator merges the annotations with the defaults, prioritizes them, and safely preserves annotations set by external systems.
11+
12+
When an annotation is removed from the CR, the Operator automatically removes it from all managed resources during the next reconciliation. Annotations set by external sources, such as Kubernetes system annotations or annotations added by other controllers, are preserved and are not affected by the Operator.
13+
14+
Annotation keys containing the following reserved domain prefixes are not allowed and are rejected by validation if applied:
15+
16+
* `kubernetes.io/` (including subdomains such as `*.kubernetes.io/`)
17+
18+
* `k8s.io/` (including subdomains such as `*.k8s.io/`)
19+
20+
* `openshift.io/` (including subdomains such as `*.openshift.io/`)
21+
22+
* `cert-manager.io/`
23+
24+
.Prerequisites
25+
26+
* You have access to the cluster with `cluster-admin` privileges.
27+
28+
* You have created the `ExternalSecretsConfig` custom resource.
29+
30+
.Procedure
31+
32+
. Edit the `ExternalSecretsConfig` CR by running the following command:
33+
+
34+
[source,terminal]
35+
----
36+
$ oc edit externalsecretsconfigs.operator.openshift.io cluster
37+
----
38+
39+
. Add the `annotations` field under `spec.controllerConfig` as follows:
40+
+
41+
[source,yaml]
42+
----
43+
apiVersion: operator.openshift.io/v1alpha1
44+
kind: ExternalSecretsConfig
45+
metadata:
46+
name: cluster
47+
spec:
48+
controllerConfig:
49+
annotations:
50+
prometheus.io/scrape: "true"
51+
example.com/environment: "production"
52+
----
53+
54+
.Verification
55+
56+
. Verify that annotations are applied to the external-secrets deployment by running the following command:
57+
+
58+
[source,terminal]
59+
----
60+
$ oc get deployment external-secrets -n external-secrets -o jsonpath='{.metadata.annotations}' | jq .
61+
----
62+
+
63+
The output should include the custom annotations you specified.
64+
65+
. Verify that annotations are applied to the pod template by running the following command:
66+
+
67+
[source,terminal]
68+
----
69+
$ oc get deployment external-secrets -n external-secrets -o jsonpath='{.spec.template.metadata.annotations}' | jq .
70+
----
71+
+
72+
The output should include the custom annotations you specified.
73+
74+
. Verify that annotations are applied to other managed resources such as Services by running the following command:
75+
+
76+
[source,terminal]
77+
----
78+
$ oc get service external-secrets-webhook -n external-secrets -o jsonpath='{.metadata.annotations}' | jq .
79+
----
80+
+
81+
The output should include the custom annotations you specified.
82+

‎modules/external-secrets-operator-configure-history-limit.adoc‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-log-levels.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-enable-operator-configure-history-limit_{context}"]
7+
= Configuring the revisionHistoryLimit for external-secrets components
8+
9+
[role="_abstract"]
10+
Configure the number of old `ReplicaSet` objects retained for rollback by setting the `revisionHistoryLimit` parameter for `external-secrets` components.
11+
12+
The following components can be configured:
13+
14+
[cols="1,1",options="header"]
15+
|===
16+
| Component name
17+
| Description
18+
19+
| `ExternalSecretsCoreController`
20+
| The main `external-secrets` controller.
21+
22+
| `Webhook`
23+
| The `external-secrets` webhook server.
24+
25+
| `CertController`
26+
| The certificate controller for webhook TLS.
27+
28+
| `BitwardenSDKServer`
29+
| The Bitwarden SDK server plugin.
30+
|===
31+
32+
Each component can only have one configuration entry. A maximum of 4 component configuration entries are allowed, one per component.
33+
34+
.Prerequisites
35+
36+
* You have access to the cluster with `cluster-admin` privileges.
37+
38+
* You have created the `ExternalSecretsConfig` custom resource.
39+
40+
.Procedure
41+
42+
. Edit the `ExternalSecretsConfig` CR by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc edit externalsecretsconfigs.operator.openshift.io cluster
47+
----
48+
49+
. Add the `componentConfigs` field under `spec.controllerConfig` as follows:
50+
+
51+
[source,yaml]
52+
----
53+
apiVersion: operator.openshift.io/v1alpha1
54+
kind: ExternalSecretsConfig
55+
metadata:
56+
name: cluster
57+
spec:
58+
controllerConfig:
59+
componentConfigs:
60+
- componentName: ExternalSecretsCoreController
61+
deploymentConfigs:
62+
revisionHistoryLimit: 5
63+
- componentName: Webhook
64+
deploymentConfigs:
65+
revisionHistoryLimit: 3
66+
----
67+
+
68+
where
69+
70+
`spec.controllerConfig.componentConfigs.componentName.deploymentConfigs.revisionHistoryLimit`:: Specifies the number of old `ReplicaSet` objects to retain for rollback. The value must be at least 1 to ensure rollback capability. The maximum value is 50. If not specified, the default is 10.
71+
72+
.Verification
73+
74+
* Verify that the `revisionHistoryLimit` parameter is applied to the deployment by running the following command:
75+
+
76+
[source,terminal]
77+
----
78+
$ oc get deployment external-secrets -n external-secrets -o jsonpath='{.spec.revisionHistoryLimit}'
79+
----
80+
+
81+
The output should display the value you configured.

‎modules/external-secrets-operator-set-custom-variables.adoc‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-log-levels.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-operator-set-custom-variables_{context}"]
7+
= Setting custom environment variables for external-secrets components
8+
9+
[role="_abstract"]
10+
To configure component behavior at runtime or integrate with external services, set custom environment variables for individual `external-secrets` components.
11+
12+
Custom environment variables are merged with the default environment variables set by the Operator. User-specified variables take precedence in case of conflicts with the Operator defaults. A maximum of 50 custom environment variables can be specified per component.
13+
14+
The environment variable names starting with the following prefixes are reserved:
15+
16+
* `HOSTNAME`
17+
18+
* `KUBERNETES_`
19+
20+
* `EXTERNAL_SECRETS_`
21+
22+
.Prerequisites
23+
24+
* You have access to the cluster with `cluster-admin` privileges.
25+
26+
* You have created the `ExternalSecretsConfig` custom resource.
27+
28+
.Procedure
29+
30+
. Edit the `ExternalSecretsConfig` CR by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc edit externalsecretsconfigs.operator.openshift.io cluster
35+
----
36+
37+
. Add the `overrideEnv` field under the desired component in the `spec.controllerConfig.componentConfigs` stanza as follows:
38+
+
39+
[source,yaml]
40+
----
41+
apiVersion: operator.openshift.io/v1alpha1
42+
kind: ExternalSecretsConfig
43+
metadata:
44+
name: cluster
45+
spec:
46+
controllerConfig:
47+
componentConfigs:
48+
- componentName: ExternalSecretsCoreController
49+
overrideEnv:
50+
- name: Example
51+
value: "4"
52+
----
53+
+
54+
where
55+
56+
`spec.controllerConfig.componentConfigs.overrideEnv.name`:: Specifies the name of the environment variable. Environment variable names starting with `HOSTNAME`, `KUBERNETES_`, or `EXTERNAL_SECRETS_` are reserved and are not allowed.
57+
58+
`spec.controllerConfig.componentConfigs.overrideEnv.value`:: Specifies the value of the environment variable.
59+
60+
.Verification
61+
62+
* Verify that the environment variable is set on the deployment by running the following command:
63+
+
64+
[source,terminal]
65+
----
66+
$ oc set env deployment/external-secrets -n external-secrets --list
67+
----
68+
+
69+
The output should include the custom environment variable you specified.
70+

‎security/external_secrets_operator/external-secrets-log-levels.adoc‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,16 @@ include::_attributes/common-attributes.adoc[]
77
toc::[]
88

99
[role="_abstract"]
10-
After the {external-secrets-operator} is installed, you can customize its behavior by editing the `ExternalSecretsConfig` custom resource (CR). This lets you modify components like the external-secrets controller, the cert-controller, the webhook, and the `bitwardenSecretManagerProvider` plugin and also lets you set environment variables for the Operator pod.
10+
You can customize the behavior of the {external-secrets-operator} operand components by configuring custom annotations, deployment lifecycle settings, and environment variables through the `ExternalSecretsConfig` custom resource (CR).
11+
12+
These configurations provide administrators with fine-grained control over the external-secrets deployment.
13+
14+
You can customize the {external-secrets-operator} operand by using the `ExternalSecretsConfig` custom resource (CR). The CR supports a set of deployment and runtime options, such as custom annotations, revision history limits, environment variables, resource limits, tolerations, and proxy settings—so you can control how the operand is deployed and run without editing the operand resources directly.
15+
16+
All supported options are defined in the `ExternalSecretsConfig` CR (for example under the `spec.controllerConfig` for controller-related settings). The Operator reconciles the operand from this CR. Changes made directly to operand resources are overwritten. Use the `ExternalSecretsConfig` CR as the only supported way to customize the operand.
17+
18+
For the complete list of fields and allowed values, see the `ExternalSecretsConfig` API reference in the {external-secrets-operator} documentation.
19+
1120

1221
[role="_additional-resources"]
1322
.Additional resources
@@ -33,3 +42,12 @@ include::modules/external-secrets-cert-manager-config.adoc[leveloffset=+1]
3342
3443
// configuring bitwarden
3544
include::modules/external-secrets-bit-warden-config.adoc[leveloffset=+1]
45+
46+
// add custom annotations
47+
include::modules/external-secrets-operator-adding-custom-annotations.adoc[leveloffset=+1]
48+
49+
// configure history limit
50+
include::modules/external-secrets-operator-configure-history-limit.adoc[leveloffset=+1]
51+
52+
// Set custom environment variables
53+
include::modules/external-secrets-operator-set-custom-variables.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)