Add documentation for connection values and secrets to resource refer…

…ence pages (#659) * add more details about env variables Signed-off-by: Will Tsai <[email protected]> * add more details about env variables Signed-off-by: Will Tsai <[email protected]> * update spell check exceptions Signed-off-by: Will Tsai <[email protected]> * rebase to v0.23 Signed-off-by: Will Tsai <[email protected]> * changes added to new app graph page Signed-off-by: Will Tsai <[email protected]> * add environment variables related to connections Signed-off-by: Will Tsai <[email protected]> * address feedback Signed-off-by: Will Tsai <[email protected]> * add spellcheck excp Signed-off-by: Will Tsai <[email protected]> * correct Azure SQL connection string Signed-off-by: Will Tsai <[email protected]> * Apply suggestions from rynowak@ code review Co-authored-by: Ryan Nowak <[email protected]> * address rynowak@ feedback Signed-off-by: Will Tsai <[email protected]> * move connections content Signed-off-by: Will Tsai <[email protected]> * address feedback re: deployment simplification, fix tabs in delete-applications Signed-off-by: Will Tsai <[email protected]> --------- Signed-off-by: Will Tsai <[email protected]> Co-authored-by: Ryan Nowak <[email protected]>
radius-project · Aug 17, 2023 · fefc128 · fefc128
1 parent 59c2fb7
commit fefc128
Show file tree

Hide file tree

Showing 13 changed files with 122 additions and 28 deletions.
diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt
@@ -446,3 +446,7 @@ myregistry
 GCP
 Fargate
 untyped
+authSource
+mongodb
+MYCONNECTION
+VHOST
diff --git a/...ts/application-graph/graph-automation.png → ...hor-apps/application/graph-automation.png b/...ts/application-graph/graph-automation.png → ...hor-apps/application/graph-automation.png
diff --git a/docs/content/author-apps/application/index.md b/docs/content/author-apps/application/index.md
@@ -12,6 +12,12 @@ tags: ["applications"]
 
 An [application]({{< ref application-graph>}}) is the primary resource that contains all of your services and relationships.
 
+Because Radius has all the relationships and requirements of an application, deployments and configurations are simplified. Developers no longer need to specify all the identity, networking, or other configuration that is normally required, and operators don't need to write custom deployment scripts.
+
+For example, if you want a container to read from an Azure Storage Account without using Radius, this normally requires creating managed identities, RBAC roles, identity federation, Kubernetes service accounts, and more. With Radius, developers can define a single [connection]({{< ref "container#connections" >}}) from their container to a Storage Account, and Radius sets up all the required configuration automatically.
+
+<img src="graph-automation.png" alt="A diagram showing a connection from a Radius container to an Azure storage account resulting in managed identities, role-based access control, and CSI drivers." width=600px >
+
 ## Extensions
 
 Extensions allow you to customize how resources are generated or customized as part of deployment.

diff --git a/docs/content/author-apps/container/index.md b/docs/content/author-apps/container/index.md
@@ -70,9 +70,22 @@ Refer to the probes section of the [container resource schema]({{< ref "containe
 
 ### Connections
 
-Connections enable communication between your container and other resources, such as databases, message queues, and other services. A connection injects information about the resource you connect to as environment variables. This could be connection strings, access keys, password or other information needed for communication between the container and the resource it connects to. It also enables you to configure the RBAC permissions for the container to access the resource.
+When a connection between two resources is declared, Radius injects resource related information into environment variables that are then used to access the respective resource without having to hard code URIs, connection strings, access keys, or anything that application code needs to successfully communicate.
 
-Refer to the [connections schema] for containers({{< ref "container-schema#connections" >}}) for more details.
+These environment variables follow a naming convention that makes their use predictable. The naming pattern is derived from the connection name and resource type, which determines what values are required. This way the code that needs to read the values gets to define how they are named. Refer to the [reference documentation]({{< ref resource-schema >}}) of each resource for more information. 
+
+For example, adding a connection called `myconnection` that connects to a MongoDB resource would result in the following environment variables being injected:
+
+```sh
+# the connection string to the resource
+CONNECTION_MYCONNECTION_CONNECTIONSTRING="mongodb://mongo:27017/mongo?authSource=admin"
+# Database name of the target resource
+CONNECTION_MYCONNECTION_DATABASE="my-database"
+# Username of the target resource
+CONNECTION_MYCONNECTION_USERNAME="admin"
+```
+
+Alternatively, if you already have another convention you would like to follow or if you just prefer to be explicit, you may ignore the values generated by a connection and instead override it by setting your own environment variable values. Refer to the [environment variables quickstart]({{< ref quickstart-environment-variables >}}) for more details.
 
 ### Extensions
 

diff --git a/docs/content/concepts/application-graph/index.md b/docs/content/concepts/application-graph/index.md
@@ -14,18 +14,10 @@ Radius offers an [application resource]({{< ref "/author-apps/application" >}})
 
 ## Graphs are better than lists
 
-Within an application deployed with Radius, developers can express both the resources (_containers, databases, message queues, etc._), as well as all the relationships between them. This forms the Radius application graph. This graph is powerful because it allows Radius to understand the relationships between resources, and automate the deployment and configuration of your application. Plus, it allows you to visualize your application in a way that is more intuitive than a list of resources.
+Within an application deployed with Radius, developers can express both the resources (_containers, databases, message queues, etc._), as well as all the relationships between them. This forms the Radius application graph. This graph is powerful because it allows Radius to understand the relationships between resources, simplifying the [deployment]({{< ref "deploy-applications" >}}) and [configuration]({{< ref "application" >}}) of your application. Plus, it allows you to visualize your application in a way that is more intuitive than a list of resources.
 
 <img src="list-to-graph.png" alt="A diagram showing the move from a set of infrastructure lists to a graph of resources" width=600px >
 
-## Automate your application deployment
-
-Because Radius now has all the relationships and requirements of an application, it can be deployed and configured automatically. Developers no longer need to specify all the identity, networking, or other configuration that is normally required, and operators don’t need to write custom deployment scripts.
-
-For example, if you want a container to read from an Azure Storage Account without using Radius, this normally requires creating managed identities, RBAC roles, identity federation, Kubernetes service accounts, and more. With Radius, developers can define a single connection from their container to a Storage Account, and Radius sets up all the required configuration automatically.
-
-<img src="graph-automation.png" alt="A diagram showing a connection from a Radius container to an Azure storage account resulting in managed identities, role-based access control, and CSI drivers." width=600px >
-
 ## Self-documenting applications
 
 The Radius application graph also allows your application to be self-documenting, where developers and operators can query and reason about the same application definition. Instead of multiple views of logs, infrastructure, and code, Radius provides a single source of truth for your application.

diff --git a/docs/content/deploy-apps/delete-applications/index.md b/docs/content/deploy-apps/delete-applications/index.md
@@ -43,4 +43,4 @@ Azure resources can be deleted via the [Azure portal](https://portal.azure.com/)
 Kubernetes resources can be deleted via [kubectl delete](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#deleting-resources).
 {{% /codetab %}}
 
- 
+{{< /tabs >}}
diff --git a/docs/content/reference/resource-schema/link-schema/cache/redis/index.md b/docs/content/reference/resource-schema/link-schema/cache/redis/index.md
@@ -68,7 +68,7 @@ The `redislabs.com/Redis` link is a [portable link]({{< ref links-resources >}})
 
 | Property | Required | Description | Example(s) |
 |----------|:--------:|-------------|------------|
-| connectionString | n | The connection string for the Redis cache. Write only. | `https://mycache.redis.cache.windows.net,password=*****,....`
+| connectionString | n | The connection string for the Redis cache. Write only. | `contoso5.redis.cache.windows.net,ssl=true,password=...`
 | password | n | The password for the Redis cache. Write only. | `mypassword`
 | url | n | The connection URL for the Redis cache. Set automatically based on the values provided for `host`, `port`, `username`, and `password`. Can be explicitly set to override default behavior. Write only. | `redis://username:password@localhost:6380/0?ssl=true` |
 
@@ -90,4 +90,18 @@ When no Recipe configuration is set, Radius will use the currently registered Re
 
 ### Provision manually
 
-If you want to manually manage your infrastructure provisioning without the use of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values that enable Radius to deploy or connect to the desired infrastructure.
+If you want to manually manage your infrastructure provisioning without the use of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values that enable Radius to deploy or connect to the desired infrastructure.
+
+## Environment variables for connections
+
+Other Radius resources, such as [containers]({{< ref "container" >}}), may connect to a Redis resource via [connections]({{< ref "application-graph#connections-and-injected-values" >}}). When a connection to Redis named, for example, `myconnection` is declared, Radius injects values into environment variables that are then used to access the connected Redis resource:
+
+| Environment variable | Example(s) |
+|----------------------|------------|
+| CONNECTION_MYCONNECTION_HOST | `mycache.redis.cache.windows.net` |
+| CONNECTION_MYCONNECTION_PORT | `6379` |
+| CONNECTION_MYCONNECTION_TLS | `true` |
+| CONNECTION_MYCONNECTION_USERNAME | `admin` |
+| CONNECTION_MYCONNECTION_CONNECTIONSTRING | `contoso5.redis.cache.windows.net,ssl=true,password=...` |
+| CONNECTION_MYCONNECTION_PASSWORD | `mypassword` |
+| CONNECTION_MYCONNECTION_URL | `rediss://username:password@localhost:6380/0` |
diff --git a/...content/reference/resource-schema/link-schema/dapr-schema/dapr-pubsub/_index.md b/...content/reference/resource-schema/link-schema/dapr-schema/dapr-pubsub/_index.md
@@ -49,7 +49,7 @@ An `Applications.Link/daprPubSubBrokers` resource represents a [Dapr pub/sub](ht
 | type | n | The Dapr component type. Set only when resourceProvisioning is 'manual'. | `pubsub.kafka` |
 | metadata | n | Metadata object for the Dapr component. Schema must match [Dapr component](https://docs.dapr.io/reference/components-reference/supported-pubsub/). Set only when resourceProvisioning is 'manual'. | `{ brokers: kafkaRoute.properties.url }` |
 | version | n | The version of the Dapr component. See [Dapr components](https://docs.dapr.io/reference/components-reference/supported-pubsub/) for available versions. Set only when resourceProvisioning is 'manual'. | `v1` |
-| componentName | n | _(read-only)_ The name of the Dapr component that is generated and applied to the underlying system. Used by the Dapr SDKs or APIs to access the Dapr component. | `myapp-mypubsub` |
+| componentName | n | _(read-only)_ The name of the Dapr component that is generated and applied to the underlying system. Used by the Dapr SDKs or APIs to access the Dapr component. | `mypubsub` |
 
 #### Recipe
 
@@ -76,4 +76,12 @@ Parameters can also optionally be specified for the Recipe.
 
 ### Provision manually
 
-If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and specify `type`, `metadata`, and `version` for the Dapr component. These values must match the schema of the intended [Dapr component](https://docs.dapr.io/reference/components-reference/supported-pubsub/).
+If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and specify `type`, `metadata`, and `version` for the Dapr component. These values must match the schema of the intended [Dapr component](https://docs.dapr.io/reference/components-reference/supported-pubsub/).
+
+## Environment variables for connections
+
+Other Radius resources, such as [containers]({{< ref "container" >}}), may connect to a Dapr pub/sub resource via [connections]({{< ref "application-graph#connections-and-injected-values" >}}). When a connection to Dapr pub/sub named, for example, `myconnection` is declared, Radius injects values into environment variables that are then used to access the connected Dapr pub/sub resource:
+
+| Environment variable | Example(s) |
+|----------------------|------------|
+| CONNECTION_MYCONNECTION_COMPONENTNAME | `mypubsub` |
diff --git a/...nt/reference/resource-schema/link-schema/dapr-schema/dapr-secretstore/_index.md b/...nt/reference/resource-schema/link-schema/dapr-schema/dapr-secretstore/_index.md
@@ -74,4 +74,12 @@ When no Recipe configuration is set Radius will use the Recipe registered as the
 
 ### Provision manually
 
-If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values the enable Radius to deploy or connect to the desired infrastructure.
+If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values the enable Radius to deploy or connect to the desired infrastructure.
+
+## Environment variables for connections
+
+Other Radius resources, such as [containers]({{< ref "container" >}}), may connect to a Dapr secret store resource via [connections]({{< ref "application-graph#connections-and-injected-values" >}}). When a connection to Dapr secret store named, for example, `myconnection` is declared, Radius injects values into environment variables that are then used to access the connected Dapr secret store resource:
+
+| Environment variable | Example(s) |
+|----------------------|------------|
+| CONNECTION_MYCONNECTION_COMPONENTNAME | `mysecretstore` |
diff --git a/...ent/reference/resource-schema/link-schema/dapr-schema/dapr-statestore/_index.md b/...ent/reference/resource-schema/link-schema/dapr-schema/dapr-statestore/_index.md
@@ -76,4 +76,12 @@ When no Recipe configuration is set Radius will use the Recipe registered as the
 
 ### Provision manually
 
-If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values and values that enable Radius to deploy or connect to the desired infrastructure.
+If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values and values that enable Radius to deploy or connect to the desired infrastructure.
+
+## Environment variables for connections
+
+Other Radius resources, such as [containers]({{< ref "container" >}}), may connect to a Dapr state store resource via [connections]({{< ref "application-graph#connections-and-injected-values" >}}). When a connection to Dapr state store named, for example, `myconnection` is declared, Radius injects values into environment variables that are then used to access the connected Dapr state store resource:
+
+| Environment variable | Example(s) |
+|----------------------|------------|
+| CONNECTION_MYCONNECTION_COMPONENTNAME | `mystatestore` |
diff --git a/.../content/reference/resource-schema/link-schema/databases/microsoft-sql/index.md b/.../content/reference/resource-schema/link-schema/databases/microsoft-sql/index.md
@@ -45,8 +45,8 @@ This application showcases how Radius can use a user-manged Azure SQL Database.
 | [resourceProvisioning](#resource-provisioning) | n | Specifies how the underlying service/resource is provisioned and managed. Options are to provision automatically via 'recipe' or provision manually via 'manual'. Selection determines which set of fields to additionally require. Defaults to 'recipe'. | `manual`
 | [recipe](#recipe) | n | Configuration for the Recipe which will deploy the backing infrastructure. | [See below](#recipe)
 | [resources](#resources)  | n | An array of IDs of the underlying resources for the link. | [See below](#resources)
-| server | n | The fully qualified domain name of the SQL server. | `sql.hello.com`
-| database | n | The name of the SQL database. | `5000`
+| server | n | The fully qualified domain name of the SQL server. | `mydatabase.database.windows.net`
+| database | n | The name of the SQL database. | `mydatabase`
 | port | n | The SQL database port. | `1433`
 | username | n | The username for the SQL database. | `'myusername'`
 | [secrets](#secrets) | n | Secrets used when building the link from values. | [See below](#secrets)
@@ -55,8 +55,8 @@ This application showcases how Radius can use a user-manged Azure SQL Database.
 
 | Property | Required | Description | Example(s) |
 |----------|:--------:|-------------|------------|
-| connectionString | n | The connection string for the SQL database. Write only. | `'https://mysqlserver.cluster.svc.local,password=*****,....'`
-| password | n | The password for the SQL database. Write only. | `'mypassword'`
+| connectionString | n | The connection string for the SQL database. Write only. | `Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>...`
+| password | n | The password for the SQL database. Write only. | `mypassword`
 
 #### Recipe
 
@@ -80,4 +80,17 @@ When no Recipe configuration is set Radius will use the Recipe registered as the
 
 ### Provision manually
 
-If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values and values that enable Radius to deploy or connect to the desired infrastructure.
+If you want to manually manage your infrastructure provisioning outside of Recipes, you can set `resourceProvisioning` to `'manual'` and provide all necessary parameters and values and values that enable Radius to deploy or connect to the desired infrastructure.
+
+## Environment variables for connections
+
+Other Radius resources, such as [containers]({{< ref "container" >}}), may connect to a Azure SQL resource via [connections]({{< ref "application-graph#connections-and-injected-values" >}}). When a connection to Azure SQL named, for example, `myconnection` is declared, Radius injects values into environment variables that are then used to access the connected Azure SQL resource:
+
+| Environment variable | Example(s) |
+|----------------------|------------|
+| CONNECTION_MYCONNECTION_DATABASE | `mydatabase` |
+| CONNECTION_MYCONNECTION_SERVER | `mydatabase.database.windows.net` |
+| CONNECTION_MYCONNECTION_PORT | `1433` |
+| CONNECTION_MYCONNECTION_USERNAME | `myusername` |
+| CONNECTION_MYCONNECTION_PASSWORD | `mypassword` |
+| CONNECTION_MYCONNECTION_CONNECTIONSTRING | `Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>...` |