DOC-621 Contextual variables (#165)

* Contextual variables content

* minor rewording

* refactoring of content

* remove mention of environment variables

* docs review comments

modules/ROOT/nav.adoc

@@ -69,6 +69,7 @@
 *** xref:develop:connect/configuration/windowed_processing.adoc[]
 *** xref:develop:connect/configuration/metadata.adoc[]
 *** xref:develop:connect/configuration/error_handling.adoc[]
+*** xref:develop:connect/configuration/contextual-variables.adoc[]
 *** xref:develop:connect/configuration/interpolation.adoc[]
 *** xref:develop:connect/configuration/field_paths.adoc[]
 *** xref:develop:connect/configuration/secret-management.adoc[Manage Secrets]

modules/develop/pages/connect/configuration/contextual-variables.adoc

@@ -0,0 +1,87 @@
+= Contextual Variables
+:description: Learn about the advantages of using contextual variables, and how to add them to your data pipelines.
+
+{description}
+
+== Understanding contextual variables
+
+Contextual variables provide an easy way to access information about the environment in which a data pipeline is running and the pipeline itself. You can add any of the following contextual variables to your pipeline configurations:
+
+|===
+| Contextual variable name | Description
+
+| `$\{REDPANDA_BROKERS}`
+| The bootstrap server address of the cluster on which the data pipeline is running.
+
+| `$\{REDPANDA_ID}`
+| The ID of the cluster on which the data pipeline is running.
+
+| `$\{REDPANDA_REGION}`
+| The cloud region where the data pipeline is deployed.
+
+| `$\{REDPANDA_PIPELINE_ID}`
+| The ID of the data pipeline that is currently running.
+
+| `$\{REDPANDA_PIPELINE_NAME}`
+| The display name of the data pipeline that is currently running.
+
+| `$\{REDPANDA_SCHEMA_REGISTRY_URL}`
+| The URL of the Schema Registry associated with the cluster on which the data pipeline is running.
+
+|===
+
+Contextual variables are automatically set at runtime, which means that you can reuse them across multiple pipelines and development environments. For example, if you add the contextual variable `$\{REDPANDA_ID}` to a pipeline configuration, it’s always set to the ID of the cluster on which the data pipeline is running, whether the pipeline is in your development, user acceptance testing, or production environment. This increases the portability of pipeline configurations and reduces maintenance overheads.
+
+You can also use contextual variables to improve data traceability. See the <<example-pipeline-configuration,Example pipeline configuration>> for full details.
+
+== Add contextual variable to a data pipeline
+
+Add a contextual variable to any pipeline configuration using the notation `$\{CONTEXTUAL_VARIABLE_NAME}`, for example:
+
+[,yaml]
+----
+output:
+ kafka_franz:
+   seed_brokers:
+     - ${REDPANDA_BROKERS}
+----
+
+=== Example pipeline configuration
+
+For improved data traceability, the following pipeline configuration adds the data pipeline display name (`$\{REDPANDA_PIPELINE_NAME}`) and ID (`$\{REDPANDA_PIPELINE_ID}`) to all messages that are processed. 
+
+The configuration also uses the `$REDPANDA_BROKERS` contextual variable to automatically populate the bootstrap server address of the cluster on which the pipeline is run, which allows Redpanda Connect to write updated messages to the `data` topic defined in the `kafka_franz` output.
+
+[,yaml]
+----
+input:
+ generate:
+   mapping: |
+     root.data = "test message"
+   interval: 10s
+
+pipeline:
+ processors:
+ - bloblang: |
+     root = this
+     root.source = "${REDPANDA_PIPELINE_NAME}"
+     root.source_id = "${REDPANDA_PIPELINE_ID}"
+
+output:
+ kafka_franz:
+   seed_brokers:
+   - ${REDPANDA_BROKERS}
+   topic: data
+   tls:
+     enabled: true
+   sasl:
+   - mechanism: SCRAM-SHA-256
+     username: cluster-username
+     password: cluster-password
+----
+
+== Suggested reading
+
+* Learn how to xref:develop:connect/configuration/secret-management.adoc[add secrets to your pipeline].
+* Try one of our xref:cookbooks:index.adoc[Redpanda Connect cookbooks].
+* Choose xref:develop:connect/components/catalog.adoc[connectors for your use case].

modules/develop/pages/connect/connect-quickstart.adoc

@@ -117,7 +117,7 @@ output:
 
 +
 * Replace `<cluster-password>` with the password of the connect user you set up in <<before-you-start,Before you start>>. To avoid exposing secrets, Redpanda Connect also supports secret variables. For more information, see xref:develop:connect/configuration/secret-management.adoc[Manage Secrets].
-* `$\{REDPANDA_BROKERS}` is a contextual variable that references the bootstrap server address of your cluster. All Redpanda Cloud clusters automatically set this variable to the bootstrap server address so that you can add it to any of your pipelines.
+* `$\{REDPANDA_BROKERS}` is a xref:develop:connect/configuration/contextual-variables.adoc[contextual variable] that references the bootstrap server address of your cluster. All Redpanda Cloud clusters automatically set this variable to the bootstrap server address so that you can add it to any of your pipelines. 
 
 +
 NOTE: The Brave browser does not fully support code snippets.