Merge pull request #1586 from StackVista/stac-22206

STAC-22206: Document changes to agent external secrets setup [MERGE ON NEXT AGENT RELEASE]

Author: craffit

SUMMARY.md

@@ -86,6 +86,7 @@
   * [Proxy Configuration](setup/agent/k8s-network-configuration-proxy.md)
 * [Using a custom registry](k8s-suse-rancher-prime-agent-air-gapped.md)
 * [Custom Secret Management](setup/agent/k8s-custom-secrets-setup.md)
+  * [Custom Secret Management (Deprecated)](setup/agent/k8s-custom-secrets-setup-deprecated.md)
 * [Request tracing](setup/agent/k8sTs-agent-request-tracing.md)
   * [Certificates for sidecar injection](setup/agent/k8sTs-agent-request-tracing-certificates.md)
 

setup/agent/k8s-custom-secrets-setup-deprecated.md

@@ -0,0 +1,43 @@
+## Custom Secret Management (Deprecated)
+
+### Overview
+
+The SUSE Observability agent supports specifying the name of a custom secret that contains the API key and cluster authorization token. This feature is useful for users who wish to manage their own secrets and avoid the automatic creation of secrets by the Helm chart. 
+
+{% hint style="warning" %}
+**This method of customizing secrets is deprecated and is incompatible with the RBAC feature.**
+
+Please use [the new method](./k8s-custom-secrets-setup.md) for using external secrets.
+{% endhint %}
+
+### Regarding the Helm Chart
+
+#### Configuration Options
+
+- `stackstate.manageOwnSecrets`: A boolean flag that determines whether the user wishes to manage their own secrets. Default value is `false`.
+- `stackstate.customSecretName`: (Optional) Name of the custom secret to be created by the user. Required if `stackstate.manageOwnSecrets` is set to `true`.
+- `stackstate.customApiKeySecretKey`: (Optional) Key name for the API key within the custom secret. Required if `stackstate.manageOwnSecrets` is set to `true`.
+- `stackstate.customClusterAuthTokenSecretKey`: (Optional) Key name for the cluster authorization token within the custom secret. Required if `stackstate.manageOwnSecrets` is set to `true`.
+
+#### Behavior Description
+
+- **Automatic Secret Creation**: By default, the chart continues to automatically create secrets as before if `stackstate.manageOwnSecrets` is set to `false`.
+- **Custom Secret Management**: If `stackstate.manageOwnSecrets` is set to `true`, the chart expects the user to provide the name of the custom secret (`stackstate.customSecretName`) along with the keys for the API key and authorization token (`stackstate.customApiKeySecretKey` and `stackstate.customClusterAuthTokenSecretKey`, respectively).
+- **Implied Omission**: When specifying that you would like to manage your own secrets, the chart will ignore values for `stackstate.apiKey` and `stackstate.cluster.authToken`.
+### How to Use in values.yaml
+
+1. **Using Automatic Secret Creation (Default)**:
+    ```yaml
+    stackstate:
+      manageOwnSecrets: false
+      apiKey: "<your api key>"
+    ```
+
+2. **Managing Own Secrets**:
+    ```yaml
+    stackstate:
+      manageOwnSecrets: true
+      customSecretName: my-custom-secret
+      customApiKeySecretKey: api-key
+      customClusterAuthTokenSecretKey: auth-token
+    ```

setup/agent/k8s-custom-secrets-setup.md

@@ -1,37 +1,40 @@
 ## Custom Secret Management
 
+
 ### Overview
 
-The stackstate/stackstate-k8s-agent (starting from version 1.0.79) supports specifying the name of a custom secret that contains the API key and cluster authorization token. This feature is useful for users who wish to manage their own secrets and avoid the automatic creation of secrets by the Helm chart. 
+The SUSE Observability Agent supports specifying the name of a custom secret that contains the API key and cluster authorization token. This feature is useful for users who wish to manage their own secrets and avoid the automatic creation of secrets by the Helm chart.
+
+{% hint style="info" %}
+**There was a previous method of specifying this that is now deprecated, see the [deprecated method](./k8s-custom-secrets-setup-deprecated.md) .**
+{% endhint %}
 
 ### Regarding the Helm Chart
 
 #### Configuration Options
 
-- `stackstate.manageOwnSecrets`: A boolean flag that determines whether the user wishes to manage their own secrets. Default value is `false`.
-- `stackstate.customSecretName`: (Optional) Name of the custom secret to be created by the user. Required if `stackstate.manageOwnSecrets` is set to `true`.
-- `stackstate.customApiKeySecretKey`: (Optional) Key name for the API key within the custom secret. Required if `stackstate.manageOwnSecrets` is set to `true`.
-- `stackstate.customClusterAuthTokenSecretKey`: (Optional) Key name for the cluster authorization token within the custom secret. Required if `stackstate.manageOwnSecrets` is set to `true`.
+- `global.apiKey.fromSecret`: Specify a pre-existing secret name residing in the same namespace which contains an `STS_API_KEY` field containing the api key.
+- `global.clusterAgentAuthToken.fromSecret`: Specify a pre-existing secret name residing in the same namespace which contains an `STS_CLUSTER_AGENT_AUTH_TOKEN` field containing a token for securing connections between the cluster and node agents.
 
 #### Behavior Description
 
-- **Automatic Secret Creation**: By default, the chart continues to automatically create secrets as before if `stackstate.manageOwnSecrets` is set to `false`.
-- **Custom Secret Management**: If `stackstate.manageOwnSecrets` is set to `true`, the chart expects the user to provide the name of the custom secret (`stackstate.customSecretName`) along with the keys for the API key and authorization token (`stackstate.customApiKeySecretKey` and `stackstate.customClusterAuthTokenSecretKey`, respectively).
+- **Automatic Secret Creation**: By default, the chart requires an `stackstate.apiKey` to be specified and will create a secret by itself. The `STS_CLUSTER_AGENT_AUTH_TOKEN` is generated automatically.
+- **Custom Secret Management**: When overriding the `fromSecret` fields, the api key and cluster auth token will be taken from those secrets. 
 - **Implied Omission**: When specifying that you would like to manage your own secrets, the chart will ignore values for `stackstate.apiKey` and `stackstate.cluster.authToken`.
+
 ### How to Use in values.yaml
 
 1. **Using Automatic Secret Creation (Default)**:
     ```yaml
     stackstate:
-      manageOwnSecrets: false
       apiKey: "<your api key>"
     ```
 
 2. **Managing Own Secrets**:
     ```yaml
-    stackstate:
-      manageOwnSecrets: true
-      customSecretName: my-custom-secret
-      customApiKeySecretKey: api-key
-      customClusterAuthTokenSecretKey: auth-token
+    global:
+      apiKey:
+        fromSecret: "name-of-my-api-key-secret"
+      clusterAgentAuthToken:
+        fromSecret: "name-of-my-cluster-agent-auth-token-secret"
     ```