From 6c7f0656fc07f4abdefb87eb7aac8dc970a15219 Mon Sep 17 00:00:00 2001
From: William Gabor <wgabor@redhat.com>
Date: Mon, 22 Jun 2026 13:54:42 -0400
Subject: [PATCH] OSDOCS-20291 created enabling optional features module

---
 ...ets-operator-enable-optional-features.adoc | 104 ++++++++++++++++++
 .../external-secrets-log-levels.adoc          |   3 +
 2 files changed, 107 insertions(+)
 create mode 100644 modules/external-secrets-operator-enable-optional-features.adoc

diff --git a/modules/external-secrets-operator-enable-optional-features.adoc b/modules/external-secrets-operator-enable-optional-features.adoc
new file mode 100644
index 000000000000..dd7e1799ca6a
--- /dev/null
+++ b/modules/external-secrets-operator-enable-optional-features.adoc
@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+//
+// * security/external_secrets_operator/external-secrets-log-levels.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="external-secrets-operator-enable-optional-features_{context}"]
+= Enabling optional features for {external-secrets-operator}
+
+[role="_abstract"]
+The {external-secrets-operator} supports optional capabilities that can be enabled cluster-wide through the `ExternalSecretsManager` custom resource (CR). Features are disabled by default and must be explicitly enabled.
+
+You can enable or disable a feature at any time. The Operator reconciles the core controller deployment when the feature state changes, without requiring a restart or reinstallation.
+
+
+[WARNING]
+====
+`UnsafeAllowGenericTargets` is a pre-release feature. It is not recommended for production use. Enabling this feature allows `ExternalSecret` resources to write secret data to arbitrary Kubernetes resource types beyond Secret objects. This might cause data managed by other controllers to be overwritten and can expose sensitive values through non-secret resources. This feature provides no additional access control beyond standard Kubernetes role-based access control (RBAC).
+====
+
+When enabled, `ExternalSecret` resources can target arbitrary Kubernetes resource types as their sync destination, instead of being limited to `Secret` objects.
+
+The Operator passes the `--unsafe-allow-generic-targets=true` flag to the core `external-secrets` controller. The webhook and cert-controller are not affected.
+
+.Prerequisites
+
+* You have access to the cluster with `cluster-admin` privileges.
+* You have installed the {external-secrets-operator} and created the `ExternalSecretsConfig` CR.
+
+.Procedure
+
+. Edit the `ExternalSecretsManager` CR by running the following command:
++
+[source,terminal]
+----
+$ oc edit externalsecretsmanagers.operator.openshift.io cluster
+----
+
+. Add the `features` field under `spec` and set the desired feature mode:
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: ExternalSecretsManager
+metadata:
+  name: cluster
+spec:
+  features:
+    - name: UnsafeAllowGenericTargets
+      mode: Enabled
+----
++
+To disable the feature, set `mode: Disabled` or remove the entry from the features list.
+
+.Verification
+
+. Verify that the feature flag is passed to the core controller by running the following command:
++
+[source,terminal]
+----
+$ oc get deployment external-secrets \
+  -n external-secrets \
+  -o jsonpath='{.spec.template.spec.containers[0].args}' | jq .
+----
++
+.Example output
++
+[source,json]
+----
+[
+  "--concurrent=1",
+  "--metrics-addr=:8080",
+  "--loglevel=warn",
+  "--zap-time-encoding=epoch",
+  "--enable-leader-election=true",
+  "--enable-push-secret-reconciler=true",
+  "--enable-cluster-store-reconciler=true",
+  "--enable-cluster-external-secret-reconciler=true",
+  "--unsafe-allow-generic-targets=true"
+]
+----
+
++
+When the feature is enabled, the output includes `--unsafe-allow-generic-targets=true`. When disabled or not configured, the flag is absent.
+
+. Verify that the `ExternalSecretsManager` CR reflects the configured feature by running the following command:
++
+[source,terminal]
+----
+$ oc get externalsecretsmanagers.operator.openshift.io cluster -o jsonpath='{.spec.features}' | jq .
+----
++
+.Example output
++
+[source,json]
+----
+[
+  {
+    "mode": "Enabled",
+    "name": "UnsafeAllowGenericTargets"
+  }
+]
+----
+
+
diff --git a/security/external_secrets_operator/external-secrets-log-levels.adoc b/security/external_secrets_operator/external-secrets-log-levels.adoc
index 9750a0dfd4fa..07eb5bb4abcc 100644
--- a/security/external_secrets_operator/external-secrets-log-levels.adoc
+++ b/security/external_secrets_operator/external-secrets-log-levels.adoc
@@ -51,3 +51,6 @@ include::modules/external-secrets-operator-configure-history-limit.adoc[leveloff
 
 // Set custom environment variables
 include::modules/external-secrets-operator-set-custom-variables.adoc[leveloffset=+1]
+
+// Set custom environment variables
+include::modules/external-secrets-operator-enable-optional-features.adoc[leveloffset=+1]