DOC-734 Add --secrets CLI flag (#101)

Author: asimms41

modules/configuration/pages/secrets.adoc

@@ -1,10 +1,11 @@
 = Secrets
+description: Methods for adding secrets to your Redpanda configuration without exposing them.
 
 This topic outlines how to add secrets to a Redpanda Connect configuration without exposing them.
 
-== Using environment variables
+== Store secrets in environment variables
 
-One of the most prolific approaches to providing secrets to a service is via environment variables. Redpanda Connect allows you to inject the values of environment variables into a configuration with the interpolation syntax `+${FOO}+`, within a configuration it looks like this:
+A common way to securely pass secrets to a service is to use environment variables. Redpanda Connect allows you to inject the values of environment variables into a configuration with the interpolation syntax `+${SECRET}+`. For example:
 
 [source,yml]
 ----
@@ -15,14 +16,53 @@ thing:
 [NOTE]
 .Use quotes
 ====
-Note that it would be valid to have `+super_secret: ${SECRET}+` above (without the quotes), but if `SECRET` is unset then the configuration becomes structurally different. Therefore, it's always best to wrap environment variable interpolations with quotes so that when the variable is unset you still have a valid configuration (with an empty string).
+It is valid to have `+super_secret: ${SECRET}+` above (without the quotes), but if `SECRET` is unset then the configuration becomes structurally different. Therefore, it's always best to wrap environment variable interpolations within quotes so that when the variable is unset you still have a valid configuration (with an empty string).
 ====
 
-More information about this syntax can be found on the xref:configuration:interpolation.adoc[interpolation field page].
+For more information about this syntax, see the xref:configuration:interpolation.adoc[interpolation field page].
 
-== Using CLI flags
+== Look up secrets on a remote system at runtime
 
-As an alternative to environment variables, you can set specific fields within a configuration using the CLI flag `--set`, where the syntax is a `<path>=<value>` pair:
+Starting with version 4.39.0, you can use the `rpk connect` CLI flag `--secrets` to look up secrets values on a remote system at runtime (for example, in your secrets management solution). This means that Redpanda Connect resolves interpolations in your configuration at runtime without setting environment variables.
+
+
+For example, you could run the following command to retrieve the value for `"$\{SECRET}"`, when the secret is stored on a Redis server.
+
+```bash
+
+rpk connect run ./config.yaml --secrets redis://secret:[email protected]
+
+```
+The command tries to load the secret value from the specified Uniform Resource Name (URN) using the format `scheme://secret:server_address`.
+
+You can specify multiple URNs separated by commas, which are tried in turn until a secrets value is successfully returned.
+
+=== Supported remote systems
+
+You can retrieve secrets from all of the following remote systems.
+
+|===
+| Remote system | URN format
+
+| AWS
+| `aws://region/prefix` + 
+For example: `aws://eu-west-1/redpanda/`
+
+| AZURE
+| `az://vault-uri/prefix`. The `vault-uri` value should not contain a `https://` prefix.
+
+| GCP
+| `gcp://projectID/prefix` + 
+For example: `gcp://project-id/redpanda-`
+
+| Redis
+| `redis://secret:[email protected]`
+
+|===
+
+== Set secrets using shell commands
+
+You can set specific fields within a configuration using the CLI flag `--set`, where the syntax is a `<path>=<value>` pair:
 
 * `<path>`: A placeholder for the xref:configuration:field_paths.adoc[dot-separated path to the field being set].
 * `<value>`: The value you want to set the field to. 
@@ -59,7 +99,7 @@ rpk connect run ./config.yaml \
 
 Using this method lets you inject the secret into the configuration without leaking it into an environment variable.
 
-== Avoiding leaked secrets
+== Avoid leaked secrets
 
 There are a few ways in which configurations parsed by Redpanda Connect can be exported back out of the service. In all of these cases Redpanda Connect will attempt to scrub any field values within the config that are known secrets (any field marked as a secret in the docs).