OSDOCS-14740 created migration documentation and added to topic map

_topic_maps/_topic_map.yml

@@ -1260,6 +1260,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 Red Hat External Secret Operator
+    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,171 @@
+// 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 `ExxternalSecretsConfig` 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.
+
+* 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: external-secrets-issuer
+    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 `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
+----
++
+[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
+----
++
+[source,yml]
+----
+aapiVersion: 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,80 @@
+// 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 upstream {external-secrets-operator} configoperator
+
+[role="_abstract"]
+You must delete the `operatorconfig` from the upstream {external-secrets-operator-short} because it creates a direct resource conflict with {external-secrets-operator} because the two operator versions use different methods for configuration.
+
+.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 upstream Operator's `namespace` by running the following command:
++
+[source,terminal]
+----
+$ oc get deployment -A | grep external-secrets
+----
++
+The following is example output from finding your `namespace`:
++
+[source,terminal]
+----
+external-secrets      external-secrets-webhook    1/1     1    1
+external-secrets      external-secrets            1/1     1    1
+----
+
+. Find the name of the `operatorconfig` resource within that namespace by running the following command:
++
+[source,terminal]
+----
+$ oc get operatorconfig -n _<operator-namespace>_
+----
++
+The following example provides output displaying the `operatorconfig` name:
++
+[source,terminal]
+----
+NAME                           AGE
+external-secrets               30d
+----
+
+. Delete the `operatorconfig` by running the following command:
++
+[source,terminal]
+----
+$ oc delete operatorconfig _<config-name>_ -n _<operator-namespace>_
+----
+
+.Verification
+
+. To verifiy that the `operatorconfig` was deleted, run the following command:
++
+[source,terminal]
+----
+$ oc get operatorconfig -n _<operator-namespace>_
+----
++
+The command should return `no resource found`.
+
+. To verify that the old webhooks are gone, run the following commands:
++
+[source,terminal]
+----
+$ oc get validatingwebhookconfigurations | grep external-secrets
+----
++
+[source,terminal]
+----
+oc get mutatingwebhookconfigurations | grep external-secrets
+----
++
+The commands should 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 upstream {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 upstream {external-secrets-operator}
+
+[role="_abstract"]
+You must uninstall the upstream {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,26 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="external-secrets-operator-migrate-downstream-upstream"]
+= Migrating from the community {external-secrets-operator-short} to {product-title} {external-secrets-operator}
+include::_attributes/common-attributes.adoc[]
+:context: external-secrets-operator-migrate-downstream-upstream
+
+toc::[]
+
+You can migrate from the community {external-secrets-operator-short} version 0.11.0 to the {external-secrets-operator}. 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.
+
+[NOTE]
+====
+The migration does not support rollbacks.
+====
+
+// 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]

security/external_secrets_operator/external-secrets-operator-uninstall.adoc

@@ -8,9 +8,6 @@ toc::[]
 
 You can remove the {external-secrets-operator} from {product-title} by uninstalling the Operator and removing its related resources.
 
-:FeatureName: The {external-secrets-operator}
-include::snippets/technology-preview.adoc[leveloffset=+1]
-
 // Uninstalling the {external-secrets-operator-short}
 include::modules/external-secrets-operator-uninstall-console.adoc[leveloffset=+1]