Add How-To: Portable Resources guide

.github/config/en-custom.txt

@@ -303,6 +303,7 @@ radapp
 radiuspublic
 rbac
 rediscaches
+RedisCache
 readinessProbe
 redis
 redisCaches
@@ -311,6 +312,7 @@ resourceGroup
 replacePrefix
 repo
 resourceGroupName
+RecipeSpecified
 resourceId
 resourcegroup
 rollout
@@ -618,6 +620,7 @@ ECS
 EFS
 EIP
 EMR
+EMPTYCONTAINER
 EMRContainers
 EMRServerless
 ElastiCache

docs/content/guides/author-apps/portable-resources/howto-author-portable-resources/index.md

@@ -0,0 +1,84 @@
+---
+type: docs
+title: "How-To: Author portable resources"
+linkTitle: "Author portable resources"
+description: "Learn how to author portable resources in Radius"
+weight: 200
+categories: "How-To"
+tags: ["portability"]
+---
+
+This guide will teach you how to author a portable resource for your [Radius Application]({{< ref "/guides/author-apps/application/overview" >}}).
+
+## Prerequisites
+
+Before you get started, you'll need to make sure you have the following tools and resources:
+- [rad CLI]({{< ref "installation#step-1-install-the-rad-cli" >}})
+- [Radius environment]({{< ref "installation#step-3-initialize-radius" >}})
+- [Radius Bicep VSCode extension]({{< ref "installation#step-2-install-the-vs-code-extension" >}})
+
+## Step 1: Choose how to define your portable resource
+
+Portable resources provide **abstraction** and **portability** to Radius Applications. Radius currently offers options to manually provision the resources or automatically provision them via Recipes.
+
+{{< tabs Recipe Manual >}}
+
+{{% codetab %}}
+
+Recipes enable a separation of concerns between infrastructure operators and developers by automating infrastructure deployment. You can run a default recipe registered in your environment or select the specific Recipe you want to run. 
+
+{{< rad file="snippets/app-redis-recipe.bicep" embed=true marker="//Recipe" >}}
+
+ To learn more visit the [Recipes overview]({{< ref "/guides/recipes/overview" >}}).
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+Add a RedisCache resource with the `resourceProvisioning` mode as `manual`. This enables you to configure the underlying Redis resource
+
+{{< rad file="snippets/app-redis-manual.bicep" embed=true marker="//MANUAL" >}}
+
+Refer to the [Redis resource schema]({{< ref "reference/resource-schema/cache/redis" >}}) for more details.
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Step 2: Define a container resource
+
+In your Bicep file `app.bicep`, add a container resource that will be leveraged by your portable resource later:
+
+{{< rad file="snippets/app.bicep" embed=true marker="//EMPTYCONTAINER" >}}
+
+## Step 3: Access your portable resources
+
+You can access the portable resource via [`connections`]({{< ref "guides/author-apps/containers#connections" >}}). Update your container definition to add a connection to the new Redis cache. This results in environment variables for connection information automatically set on the container.
+
+
+{{< rad file="snippets/app-redis-manual.bicep" embed=true marker="//CONTAINER" markdownConfig="{linenos=table,hl_lines=[\"19-22\"]}">}}
+
+## Step 4: Deploy your app
+
+1. Run your application in your environment:
+
+    ```bash
+    rad run ./app.bicep -a demo
+    ```
+
+1. Visit [localhost:3000](http://localhost:3000) in your browser. You should see the following page, now showing injected environment variables:
+
+   {{< image src="demo-with-redis-screenshot.png" alt="Screenshot of the demo app with all environment variables" width=1000px >}}
+
+## Cleanup
+
+Run `rad app delete` to cleanup your Radius application, container, and Redis cache:
+
+```bash
+rad app delete -a demo
+```
+
+## Further reading
+
+- [Portable resource overview]({{< ref "/guides/author-apps/portable-resources/overview" >}})
+- [Radius Application overview]({{< ref "/guides/author-apps/application/overview" >}})

docs/content/guides/author-apps/portable-resources/howto-author-portable-resources/snippets/app-redis-manual.bicep

@@ -0,0 +1,56 @@
+import radius as radius
+
+@description('Specifies the environment for resources.')
+param environment string
+
+@description('Specifies the application for resources.')
+param application string
+
+@description('Specifies the namespace for resources.')
+param namespace string
+
+//CONTAINER
+resource container 'Applications.Core/containers@2023-10-01-preview' = {
+  name: 'demo'
+  properties: {
+    application: application
+    container: {
+      image: 'ghcr.io/radius-project/samples/demo:latest'
+      ports: {
+        web: {
+          containerPort: 3000
+        }
+      }
+      livenessProbe: {
+        kind: 'httpGet'
+        containerPort: 3000
+        path: '/healthz'
+        initialDelaySeconds: 10
+      }
+    }
+    connections: {
+      redis: {
+        source: portableRedis.id
+      }
+    }
+  }
+}
+//CONTAINER
+
+//MANUAL
+resource portableRedis 'Applications.Datastores/redisCaches@2023-10-01-preview' = {
+  name: 'redisCache'
+  properties: {
+    environment: environment
+    application: application
+    resourceProvisioning: 'manual'
+    username: 'myusername'
+    host: 'mycache.contoso.com'
+    port: 8080
+    secrets: {
+      password: '******'
+    }
+  }
+}
+//MANUAL
+

docs/content/guides/author-apps/portable-resources/howto-author-portable-resources/snippets/app-redis-recipe.bicep

@@ -0,0 +1,62 @@
+import radius as radius
+
+@description('Specifies the environment for resources.')
+param environment string
+
+@description('Specifies the application for resources.')
+param application string
+
+@description('Specifies the namespace for resources.')
+param namespace string
+
+//CONTAINER
+resource container 'Applications.Core/containers@2023-10-01-preview' = {
+  name: 'demo'
+  properties: {
+    application: application
+    container: {
+      image: 'ghcr.io/radius-project/samples/demo:latest'
+      ports: {
+        web: {
+          containerPort: 3000
+        }
+      }
+      livenessProbe: {
+        kind: 'httpGet'
+        containerPort: 3000
+        path: '/healthz'
+        initialDelaySeconds: 10
+      }
+    }
+    connections: {
+      redis: {
+        source: recipeRedis.id
+      }
+    }
+  }
+}
+//CONTAINER
+
+//Recipe
+resource recipeRedis 'Applications.Datastores/redisCaches@2023-10-01-preview'= {
+  name: 'myresource'
+  properties: {
+    environment: environment
+    application: application
+  }
+}
+//Recipe
+
+//RecipeSpecified
+resource redis 'Applications.Datastores/redisCaches@2023-10-01-preview'= {
+  name: 'myresource'
+  properties: {
+    environment: environment
+    application: application
+    recipe: {
+      name: 'azure-prod'
+    }
+  }
+}
+//RecipeSpecified
+

docs/content/guides/author-apps/portable-resources/howto-author-portable-resources/snippets/app.bicep

@@ -0,0 +1,16 @@
+import radius as radius
+
+@description('Specifies the application for resources.')
+param application string
+
+//CONTAINER
+resource container 'Applications.Core/containers@2023-10-01-preview' = {
+  name: 'demo'
+  properties: {
+    application: application
+    container: {
+      image: 'ghcr.io/radius-project/samples/demo:latest'
+    }
+  }
+}
+//CONTAINER

docs/content/guides/author-apps/portable-resources/overview/index.md

@@ -3,7 +3,7 @@ type: docs
 title: "Overview: Portable Resources"
 linkTitle: "Overview"
 description: "Add portable resources to your Radius Application for infrastructure portability"
-weight: 600
+weight: 100
 categories: "Overview"
 tags: ["portability"]
 ---