[enterprise-4.21] OSDOCS-14740 created migration documentation and added to topic map

_topic_maps/_topic_map.yml

@@ -1261,6 +1261,8 @@ Topics:
     File: external-secrets-operator-uninstall
   - Name: External Secrets Operator APIs
     File: external-secrets-operator-api
+  - Name: Migrating from the community External Secret Operator to the External Secret Operator For Red Hat OpenShift
+    File: external-secrets-operator-migrate-downstream-upstream
 - Name: Viewing audit logs
   File: audit-log-view
 - Name: Configuring the audit log policy

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

@@ -0,0 +1,195 @@
+// Module included in the following assemblies:
+//
+// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-secrets-operator-create-externalsecretsconfig_{context}"]
+= Creating the ExternalSecretsConfig Operator
+
+[role="_abstract"]
+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.
+
+.Prerequisites
+
+* {external-secrets-operator} is installed.
+
+* {cert-manager-operator} is installed.
+
+* You have access to the cluster with `cluster-admin` privileges.
+
+.Procedure
+
+. Create an `externalsecretsconfig` file by defining a YAML file with the following content:
++
+[source,yml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: ExternalSecretsConfig
+metadata:
+  labels:
+    app.kubernetes.io/name: cluster
+  name: cluster
+spec:
+  appConfig:
+    logLevel: 3
+  webhookConfig:
+    certificateCheckInterval: 5m0s
+  controllerConfig:
+    certProvider:
+      certManager:
+        certificateDuration: 8760h0m0s
+        certificateRenewBefore: 30m0s
+        injectAnnotations: "true"
+        issuerRef:
+          group: cert-manager.io
+          kind: Issuer
+          name: _<created_issuer_name>_
+    mode: Enabled
+    networkPolicies:
+    - componentName: ExternalSecretsCoreController
+      egress:
+      - ports:
+        - port: 443
+          protocol: TCP
+        - port: 9998
+          protocol: TCP
+        name: allow-external-secrets-egress
+    plugins:
+      bitwardenSecretManagerProvider:
+        mode: Enabled
+----
+
+. Create the `ExternalSecretsConfig` object by running the following command:
++
+[source,terminal]
+----
+$ oc create -f externalsecretsconfig.yaml
+----
+
+.Verification
+
+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.
+
+. To verify that the `external-secrets` pods are in a `running` state, run the following command:
++
+[source,terminal]
+----
+$ oc get pods -n external-secret
+----
++
+The following is example output that the `external-secrets` pods are in a `running` state
++
+[source,terminal]
+----
+NAME                                          READY        STATUS        RESTARTS     AGE
+bitwarden-sdk-server-5b4cf48766-w7zp7         1/1          Running       0            5m
+external-secrets-5854b85dd5-m6zf9             1/1          Running       0            5m
+external-secrets-webhook-5cb85b8fdb-6jtqb     1/1          Running       0            5m
+----
+
+. To verify that the `SecretStore` CR is present, run the following command:
++
+[source,terminal]
+----
+$ oc get secretstores.external-secrets.io -A
+----
++
+The following is example output from validating that the `SecretStore` is present:
++
+[source,terminal]
+----
+NAMESPACE               NAME                         AGE         STATUS      CAPABILITIES    READY
+external-secrets-1      gcp-store                    18min       Valid       ReadWrite       True
+external-secrets-2      aws-secretstore              11min       Valid       ReadWrite       True
+external-secrets        bitwarden-secretsmanager     20min       Valid       Readwrite       True
+----
+
+. To verify that the `ExternalSecret` CR is present, run the following command:
++
+[source,terminal]
+----
+$ oc get externalsecrets.external-secrets.io -A
+----
++
+The following is example output from validating that the `SecretStore` is present:
++
+[source,terminal]
+----
+NAMESPACE             NAME                    STORE                      REFRESH INTERVAL    STATUS          READY
+external-secrets-1    gcp-externalsecret      gcp-store                  1hr                 SecretSynced    True
+external-secrets-2    aws-external-secret     aws-secret-store           1hr                 SecretSynced    True
+external-secrets      bitwarden               bitwarden-secretsmanager   1hr                 SecretSynced    True
+----
+
+. To verify that the `SecretStore` is `apiVersion: external-secrets.io/v1`, run the following command:
++
+[source,terminal]
+----
+$ oc get secretstores.external-secrets.io -n external-secrets-1 gcp-store -o yaml
+----
++
+The following is example output that the `SecretStore` is `apiVersion: external-secrets.io/v1`.
++
+[source,yml]
+----
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  creationTimestamp: "2025-10-27T11:38:19Z"
+  generation: 1
+  name: gcp-store
+  namespace: external-secrets-1
+  resourceVersion: "104519"
+  uid: 7bccb0cc-2557-4f4a-9caa-1577f0108f4b
+spec:
+.
+.
+.
+status:
+  capabilities: ReadWrite
+  conditions:
+  - lastTransitionTime: "2025-10-27T11:38:19Z"
+    message: store validated
+    reason: Valid
+    status: "True"
+    type: Ready
+----
+
+. To verify that the `ExternalSecret` is `apiVersion: external-secrets.io/v1`, run the following command:
++
+[source,terminal]
+----
+$ oc get externalsecrets.external-secrets.io -n external-secrets-1 gcp-externalsecret -o yaml
+----
++
+The following is example output that the `ExternalSecret` is `apiVersion: external-secrets.io/v1`.
++
+[source,yml]
+----
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  creationTimestamp: "2025-10-27T11:39:03Z"
+  generation: 1
+  name: gcp-externalsecret
+  namespace: external-secrets-1
+  resourceVersion: "104532"
+  uid: 93a3295a-a3ad-4304-90e1-1328d951e5fb
+spec:
+.
+.
+.
+status:
+  binding:
+    name: k8s-secret-gcp
+  conditions:
+  - lastTransitionTime: "2025-10-27T11:39:03Z"
+    message: secret synced
+    reason: SecretSynced
+    status: "True"
+    type: Ready
+  refreshTime: "2025-10-27T12:13:15Z"
+  syncedResourceVersion: 1-f47fe3c0b255b6dd8047cdffa772587bb829efe7a1cb70febeda2eb2
+----
+
+

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

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-secrets-operator-delete-upstream-operatorconfig_{context}"]
+= Deleting the community {external-secrets-operator-short}
+
+[role="_abstract"]
+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}.
+
+.Prerequisites
+
+* You must be logged in as a user with the `cluster-admin` role.
+
+* You must have the `oc` command-line tool installed and configured.
+
+.Procedure
+
+. Find your community Operator's `namespace` by running the following command:
++
+[source,terminal]
+----
+$ oc get operatorconfigs.operator.external-secrets.io -A
+----
++
+The following is an example of finding the `namespace`:
++
+[source,terminal]
+----
+NAMESPACE             NAME        AGE
+external-secrets      cluster     9m18s
+----
+
+. Delete the `operatorconfig` by running the following command:
++
+[source,terminal]
+----
+$ oc delete operatorconfig <config_name> -n <operator_namespace>
+----
+
+.Verification
+
+. To verify that the `operatorconfig` was deleted, run the following command:
++
+[source,terminal]
+----
+$ oc get operatorconfig -n <operator_namespace>
+----
++
+The command must return `no resource found`.
+
+. To verify that the old webhooks are deleted, run the following commands:
++
+[source,terminal]
+----
+$ oc get validatingwebhookconfigurations | grep external-secrets
+----
++
+[source,terminal]
+----
+$ oc get mutatingwebhookconfigurations | grep external-secrets
+----
++
+The commands must return no results.

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

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-secrets-operator-eso-install_{context}"]
+= Installing the {external-secrets-operator}
+
+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

@@ -0,0 +1,55 @@
+// Module included in the following assemblies:
+//
+// * security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-secrets-operator-uninstall-upstream-eso_{context}"]
+= Uninstalling the community {external-secrets-operator-short}
+
+[role="_abstract"]
+You must uninstall the community {external-secrets-operator-short} to prevent it from being recreated or conflicting with the new one.
+
+.Prerequisites
+
+* You must be logged in as a user with the `cluster-admin` role.
+
+* You must have deleted the `operatorconfig`.
+
+.Procedure
+
+. If you installed the community {external-secrets-operator-short} by an Operator Lifecycle Manager (OLM) subscription, delete the Operator by performing the following steps:
+
+.. Find the subscription name by running the following command:
++
+[source,terminal]
+----
+$ oc get subscription -n <operator_namespace> | grep external-secrets
+----
+
+.. Delete the subscription by running the following command:
++
+[source,terminal]
+----
+$ oc delete subscription <subscription_name> -n <operator_namespace>
+----
+
+.. Delete the `ClusterServiceVersion` by running the following command:
++
+[source,terminal]
+----
+$ oc delete csv <csv_name> -n <operator_namespace>
+----
+
+. If you installed the community {external-secret-operator} by Helm, delete the Operator by running the following command:
++
+[source,terminal]
+----
+$ helm uninstall <release_name> -n <operator_namespace>
+----
+
+. If you installed the community {external-secret-operator} by raw manifests, delete the Operator by running the following command:
++
+[source,terminal]
+----
+$ oc delete -f /path/to/your/old/manifests.yaml -n <operator_namespace>
+----

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

@@ -0,0 +1,48 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="external-secrets-operator-migrate-downstream-upstream"]
+= Migrating from the community {external-secrets-operator-short} to {external-secrets-operator}
+include::_attributes/common-attributes.adoc[]
+:context: external-secrets-operator-migrate-downstream-upstream
+
+toc::[]
+
+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.
+
+The following migration versions have been fully tested.
+
+[cols="1,1,1",options="header"]
+|===
+| Upstream version
+| Installation method
+| Downstream version
+
+| 0.11.0
+| OLM
+| v1.0.0 GA
+
+| 0.19.0
+| Helm
+| v1.0.0 GA
+|===
+
+[NOTE]
+====
+The migration does not support rollbacks.
+====
+
+[NOTE]
+====
+{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}.
+====
+
+// Deleting the operatorconfig
+include::modules/external-secrets-operator-delete-upstream-operatorconfig.adoc[leveloffset=+1]
+
+// Uninstalling the upstream {external-secrets-operator}
+include::modules/external-secrets-operator-uninstall-upstream-eso.adoc[leveloffset=+1]
+
+// Removing {external-secrets-operator-short} using CLI
+include::modules/external-secrets-operator-eso-install.adoc[leveloffset=+1]
+
+// Create externalsecretsconfig and verify everything is running
+include::modules/external-secrets-operator-create-externalsecretsconfig.adoc[leveloffset=+1]