diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index db497f062271..7ed2c7976e6b 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/modules/external-secrets-operator-create-externalsecretsconfig.adoc b/modules/external-secrets-operator-create-externalsecretsconfig.adoc new file mode 100644 index 000000000000..99561a408bd1 --- /dev/null +++ b/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: __ + 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 +---- + + diff --git a/modules/external-secrets-operator-delete-upstream-operatorconfig.adoc b/modules/external-secrets-operator-delete-upstream-operatorconfig.adoc new file mode 100644 index 000000000000..b5839b621400 --- /dev/null +++ b/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 -n +---- + +.Verification + +. To verify that the `operatorconfig` was deleted, run the following command: ++ +[source,terminal] +---- +$ oc get operatorconfig -n +---- ++ +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. diff --git a/modules/external-secrets-operator-eso-install.adoc b/modules/external-secrets-operator-eso-install.adoc new file mode 100644 index 000000000000..a492f1ff593f --- /dev/null +++ b/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]. \ No newline at end of file diff --git a/modules/external-secrets-operator-uninstall-upstream-eso.adoc b/modules/external-secrets-operator-uninstall-upstream-eso.adoc new file mode 100644 index 000000000000..e83dd7b9eadb --- /dev/null +++ b/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 | grep external-secrets +---- + +.. Delete the subscription by running the following command: ++ +[source,terminal] +---- +$ oc delete subscription -n +---- + +.. Delete the `ClusterServiceVersion` by running the following command: ++ +[source,terminal] +---- +$ oc delete csv -n +---- + +. If you installed the community {external-secret-operator} by Helm, delete the Operator by running the following command: ++ +[source,terminal] +---- +$ helm uninstall -n +---- + +. 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 +---- diff --git a/security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc b/security/external_secrets_operator/external-secrets-operator-migrate-downstream-upstream.adoc new file mode 100644 index 000000000000..6fa3c62cff14 --- /dev/null +++ b/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]