Skip to content

Commit 3cc8373

Browse files
snarayan-redhatsnarayan-redhat
authored
Merge pull request #101032 from wgabor0427/OSDOCS-14740
OSDOCS-14740 created migration documentation and added to topic map
2 parents 9ae5874 + 39633c5 commit 3cc8373

6 files changed

+374
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1264,6 +1264,8 @@ Topics:
12641264
File: external-secrets-operator-uninstall
12651265
- Name: External Secrets Operator APIs
12661266
File: external-secrets-operator-api
1267+
- Name: Migrating from the community External Secret Operator to the External Secret Operator For Red Hat OpenShift
1268+
File: external-secrets-operator-migrate-downstream-upstream
12671269
- Name: Viewing audit logs
12681270
File: audit-log-view
12691271
- Name: Configuring the audit log policy

‎modules/external-secrets-operator-create-externalsecretsconfig.adoc‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-operator-create-externalsecretsconfig_{context}"]
7+
= Creating the ExternalSecretsConfig Operator
8+
9+
[role="_abstract"]
10+
The purpose of creating the `ExternalSecretsConfig` is to install and configure the `external-secrets`. The configuration ensures that cert-manager and Bitwarden support are enabled.
11+
12+
.Prerequisites
13+
14+
* {external-secrets-operator} is installed.
15+
16+
* {cert-manager-operator} is installed.
17+
18+
* You have access to the cluster with `cluster-admin` privileges.
19+
20+
.Procedure
21+
22+
. Create an `externalsecretsconfig` file by defining a YAML file with the following content:
23+
+
24+
[source,yml]
25+
----
26+
apiVersion: operator.openshift.io/v1alpha1
27+
kind: ExternalSecretsConfig
28+
metadata:
29+
labels:
30+
app.kubernetes.io/name: cluster
31+
name: cluster
32+
spec:
33+
appConfig:
34+
logLevel: 3
35+
webhookConfig:
36+
certificateCheckInterval: 5m0s
37+
controllerConfig:
38+
certProvider:
39+
certManager:
40+
certificateDuration: 8760h0m0s
41+
certificateRenewBefore: 30m0s
42+
injectAnnotations: "true"
43+
issuerRef:
44+
group: cert-manager.io
45+
kind: Issuer
46+
name: _<created_issuer_name>_
47+
mode: Enabled
48+
networkPolicies:
49+
- componentName: ExternalSecretsCoreController
50+
egress:
51+
- ports:
52+
- port: 443
53+
protocol: TCP
54+
- port: 9998
55+
protocol: TCP
56+
name: allow-external-secrets-egress
57+
plugins:
58+
bitwardenSecretManagerProvider:
59+
mode: Enabled
60+
----
61+
62+
. Create the `ExternalSecretsConfig` object by running the following command:
63+
+
64+
[source,terminal]
65+
----
66+
$ oc create -f externalsecretsconfig.yaml
67+
----
68+
69+
.Verification
70+
71+
Verify that all custom resources (CRs) are present and that the APIs are using `v1` instead of `v1beta1`. There CRs are retained and automatically converted by the new Operator.
72+
73+
. To verify that the `external-secrets` pods are in a `running` state, run the following command:
74+
+
75+
[source,terminal]
76+
----
77+
$ oc get pods -n external-secret
78+
----
79+
+
80+
The following is example output that the `external-secrets` pods are in a `running` state
81+
+
82+
[source,terminal]
83+
----
84+
NAME READY STATUS RESTARTS AGE
85+
bitwarden-sdk-server-5b4cf48766-w7zp7 1/1 Running 0 5m
86+
external-secrets-5854b85dd5-m6zf9 1/1 Running 0 5m
87+
external-secrets-webhook-5cb85b8fdb-6jtqb 1/1 Running 0 5m
88+
----
89+
90+
. To verify that the `SecretStore` CR is present, run the following command:
91+
+
92+
[source,terminal]
93+
----
94+
$ oc get secretstores.external-secrets.io -A
95+
----
96+
+
97+
The following is example output from validating that the `SecretStore` is present:
98+
+
99+
[source,terminal]
100+
----
101+
NAMESPACE NAME AGE STATUS CAPABILITIES READY
102+
external-secrets-1 gcp-store 18min Valid ReadWrite True
103+
external-secrets-2 aws-secretstore 11min Valid ReadWrite True
104+
external-secrets bitwarden-secretsmanager 20min Valid Readwrite True
105+
----
106+
107+
. To verify that the `ExternalSecret` CR is present, run the following command:
108+
+
109+
[source,terminal]
110+
----
111+
$ oc get externalsecrets.external-secrets.io -A
112+
----
113+
+
114+
The following is example output from validating that the `SecretStore` is present:
115+
+
116+
[source,terminal]
117+
----
118+
NAMESPACE NAME STORE REFRESH INTERVAL STATUS READY
119+
external-secrets-1 gcp-externalsecret gcp-store 1hr SecretSynced True
120+
external-secrets-2 aws-external-secret aws-secret-store 1hr SecretSynced True
121+
external-secrets bitwarden bitwarden-secretsmanager 1hr SecretSynced True
122+
----
123+
124+
. To verify that the `SecretStore` is `apiVersion: external-secrets.io/v1`, run the following command:
125+
+
126+
[source,terminal]
127+
----
128+
$ oc get secretstores.external-secrets.io -n external-secrets-1 gcp-store -o yaml
129+
----
130+
+
131+
The following is example output that the `SecretStore` is `apiVersion: external-secrets.io/v1`.
132+
+
133+
[source,yml]
134+
----
135+
apiVersion: external-secrets.io/v1
136+
kind: SecretStore
137+
metadata:
138+
creationTimestamp: "2025-10-27T11:38:19Z"
139+
generation: 1
140+
name: gcp-store
141+
namespace: external-secrets-1
142+
resourceVersion: "104519"
143+
uid: 7bccb0cc-2557-4f4a-9caa-1577f0108f4b
144+
spec:
145+
.
146+
.
147+
.
148+
status:
149+
capabilities: ReadWrite
150+
conditions:
151+
- lastTransitionTime: "2025-10-27T11:38:19Z"
152+
message: store validated
153+
reason: Valid
154+
status: "True"
155+
type: Ready
156+
----
157+
158+
. To verify that the `ExternalSecret` is `apiVersion: external-secrets.io/v1`, run the following command:
159+
+
160+
[source,terminal]
161+
----
162+
$ oc get externalsecrets.external-secrets.io -n external-secrets-1 gcp-externalsecret -o yaml
163+
----
164+
+
165+
The following is example output that the `ExternalSecret` is `apiVersion: external-secrets.io/v1`.
166+
+
167+
[source,yml]
168+
----
169+
apiVersion: external-secrets.io/v1
170+
kind: ExternalSecret
171+
metadata:
172+
creationTimestamp: "2025-10-27T11:39:03Z"
173+
generation: 1
174+
name: gcp-externalsecret
175+
namespace: external-secrets-1
176+
resourceVersion: "104532"
177+
uid: 93a3295a-a3ad-4304-90e1-1328d951e5fb
178+
spec:
179+
.
180+
.
181+
.
182+
status:
183+
binding:
184+
name: k8s-secret-gcp
185+
conditions:
186+
- lastTransitionTime: "2025-10-27T11:39:03Z"
187+
message: secret synced
188+
reason: SecretSynced
189+
status: "True"
190+
type: Ready
191+
refreshTime: "2025-10-27T12:13:15Z"
192+
syncedResourceVersion: 1-f47fe3c0b255b6dd8047cdffa772587bb829efe7a1cb70febeda2eb2
193+
----
194+
195+

‎modules/external-secrets-operator-delete-upstream-operatorconfig.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-operator-delete-upstream-operatorconfig_{context}"]
7+
= Deleting the community {external-secrets-operator-short}
8+
9+
[role="_abstract"]
10+
You must delete the `operatorconfigs.operator.external-secrets.io` custom resource (CR) for the community {external-secrets-operator-short} to delete the `external-secrets` application installed by the community {external-secrets-operator-short}.
11+
12+
.Prerequisites
13+
14+
* You must be logged in as a user with the `cluster-admin` role.
15+
16+
* You must have the `oc` command-line tool installed and configured.
17+
18+
.Procedure
19+
20+
. Find your community Operator's `namespace` by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc get operatorconfigs.operator.external-secrets.io -A
25+
----
26+
+
27+
The following is an example of finding the `namespace`:
28+
+
29+
[source,terminal]
30+
----
31+
NAMESPACE NAME AGE
32+
external-secrets cluster 9m18s
33+
----
34+
35+
. Delete the `operatorconfig` by running the following command:
36+
+
37+
[source,terminal]
38+
----
39+
$ oc delete operatorconfig <config_name> -n <operator_namespace>
40+
----
41+
42+
.Verification
43+
44+
. To verify that the `operatorconfig` was deleted, run the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ oc get operatorconfig -n <operator_namespace>
49+
----
50+
+
51+
The command must return `no resource found`.
52+
53+
. To verify that the old webhooks are deleted, run the following commands:
54+
+
55+
[source,terminal]
56+
----
57+
$ oc get validatingwebhookconfigurations | grep external-secrets
58+
----
59+
+
60+
[source,terminal]
61+
----
62+
$ oc get mutatingwebhookconfigurations | grep external-secrets
63+
----
64+
+
65+
The commands must return no results.

‎modules/external-secrets-operator-eso-install.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-operator-eso-install_{context}"]
7+
= Installing the {external-secrets-operator}
8+
9+
Once the `operatorconfig` has been deleted and the community {external-secret-operator-short} has been deleted, you can install the {external-secrets-operator}. For more information, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#external-secrets-operator-install[Installing the External Secrets Operator for Red Hat OpenShift].

‎modules/external-secrets-operator-uninstall-upstream-eso.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="external-secrets-operator-uninstall-upstream-eso_{context}"]
7+
= Uninstalling the community {external-secrets-operator-short}
8+
9+
[role="_abstract"]
10+
You must uninstall the community {external-secrets-operator-short} to prevent it from being recreated or conflicting with the new one.
11+
12+
.Prerequisites
13+
14+
* You must be logged in as a user with the `cluster-admin` role.
15+
16+
* You must have deleted the `operatorconfig`.
17+
18+
.Procedure
19+
20+
. If you installed the community {external-secrets-operator-short} by an Operator Lifecycle Manager (OLM) subscription, delete the Operator by performing the following steps:
21+
22+
.. Find the subscription name by running the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc get subscription -n <operator_namespace> | grep external-secrets
27+
----
28+
29+
.. Delete the subscription by running the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ oc delete subscription <subscription_name> -n <operator_namespace>
34+
----
35+
36+
.. Delete the `ClusterServiceVersion` by running the following command:
37+
+
38+
[source,terminal]
39+
----
40+
$ oc delete csv <csv_name> -n <operator_namespace>
41+
----
42+
43+
. If you installed the community {external-secret-operator} by Helm, delete the Operator by running the following command:
44+
+
45+
[source,terminal]
46+
----
47+
$ helm uninstall <release_name> -n <operator_namespace>
48+
----
49+
50+
. If you installed the community {external-secret-operator} by raw manifests, delete the Operator by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc delete -f /path/to/your/old/manifests.yaml -n <operator_namespace>
55+
----

‎security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="external-secrets-operator-migrate-downstream-upstream"]
3+
= Migrating from the community {external-secrets-operator-short} to {external-secrets-operator}
4+
include::_attributes/common-attributes.adoc[]
5+
:context: external-secrets-operator-migrate-downstream-upstream
6+
7+
toc::[]
8+
9+
You can migrate from the community version of the {external-secrets-operator-short}. Migrating to {external-secrets-operator} provides you with an officially supported product giving you access to enterprise-grade support. It also provides you with seamless integration from installation to upgrades.
10+
11+
The following migration versions have been fully tested.
12+
13+
[cols="1,1,1",options="header"]
14+
|===
15+
| Upstream version
16+
| Installation method
17+
| Downstream version
18+
19+
| 0.11.0
20+
| OLM
21+
| v1.0.0 GA
22+
23+
| 0.19.0
24+
| Helm
25+
| v1.0.0 GA
26+
|===
27+
28+
[NOTE]
29+
====
30+
The migration does not support rollbacks.
31+
====
32+
33+
[NOTE]
34+
====
35+
{external-secrets-operator} is based on the upstream version 0.19.0. Do not attempt to migrate from a higher version of the {external-secrets-operator-short}.
36+
====
37+
38+
// Deleting the operatorconfig
39+
include::modules/external-secrets-operator-delete-upstream-operatorconfig.adoc[leveloffset=+1]
40+
41+
// Uninstalling the upstream {external-secrets-operator}
42+
include::modules/external-secrets-operator-uninstall-upstream-eso.adoc[leveloffset=+1]
43+
44+
// Removing {external-secrets-operator-short} using CLI
45+
include::modules/external-secrets-operator-eso-install.adoc[leveloffset=+1]
46+
47+
// Create externalsecretsconfig and verify everything is running
48+
include::modules/external-secrets-operator-create-externalsecretsconfig.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)