How-To: Portable Resources

Signed-off-by: jasonviviano <[email protected]>

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

@@ -0,0 +1,75 @@
+---
+type: docs
+title: "How-To: Author a portable resources"
+linkTitle: "Author a portable resource"
+description: "Learn how to author portable resources in Radius"
+weight: 200
+categories: "How-To"
+tags: ["portability"]
+---
+
+This guide will provide an overview of 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:
+
+- [Radius initialized with `rad init`]({{< ref getting-started >}})
+- [Radius Bicep VSCode extension]({{< ref "installation#step-2-install-the-radius-bicep-extension" >}})
+
+## Step 1: Define a container resource
+
+Create a 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 2: Define your portable resource
+
+{{< tabs Recipe Manual >}}
+
+{{% codetab %}}
+
+Recipes enable a separation of concerns between infrastructure operators and developers by automating infrastructure deployment. To learn more visit the [Recipes overview]({{< ref "/guides/recipes/overview" >}})
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+Find the schema needed for the supported Radius resource by visiting the [Radius resource schema docs]({{< ref resource-schema >}}). For this example you can follow along and define a RedisCache resource:
+
+{{< rad file="snippets/app-redis-manual.bicep" embed=true marker="//MANUAL" >}}
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Step 3: Accessing your portable resource
+
+Users can leverage their portable resources and establish connections to their container resources by adding accessing properties:
+
+{{< 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:
+
+   <img 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 portable-resources >}})
+- [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,132 @@
+import radius as radius
+
+import kubernetes as kubernetes {
+  kubeConfig: ''
+  namespace: namespace
+}
+
+@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: 'radius.azurecr.io/tutorial/webapp:edge'
+      ports: {
+        web: {
+          containerPort: 3000
+        }
+      }
+      livenessProbe: {
+        kind: 'httpGet'
+        containerPort: 3000
+        path: '/healthz'
+        initialDelaySeconds: 10
+      }
+    }
+    connections: {
+      redis: {
+        source: portableRedis.id
+      }
+    }
+  }
+}
+//CONTAINER
+
+//MANUAL
+resource redis 'apps/Deployment@v1' = {
+  metadata: {
+    name: 'redis-${uniqueString(application)}'
+  }
+  spec: {
+    selector: {
+      matchLabels: {
+        app: 'redis'
+        resource: portableRedis.name
+      }
+    }
+    template: {
+      metadata: {
+        labels: {
+          app: 'redis'
+          resource: portableRedis.name
+
+          // Label pods with the application name so `rad run` can find the logs.
+          'radapp.io/application': application == null ? '' : application
+        }
+      }
+      spec: {
+        containers: [
+          {
+            // This container is the running redis instance.
+            name: 'redis'
+            image: 'redis'
+            ports: [
+              {
+                containerPort: 6379
+              }
+            ]
+          }
+          {
+            // This container will connect to redis and stream logs to stdout for aid in development.
+            name: 'redis-monitor'
+            image: 'redis'
+            args: [
+              'redis-cli'
+              '-h'
+              'localhost'
+              'MONITOR'
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+
+resource svc 'core/Service@v1' = {
+  metadata: {
+    name: 'redis-${uniqueString(application)}'
+  }
+  spec: {
+    type: 'ClusterIP'
+    selector: {
+      app: 'redis'
+      resource: portableRedis.name
+    }
+    ports: [
+      {
+        port: 6379
+      }
+    ]
+  }
+}
+
+resource portableRedis 'Applications.Datastores/redisCaches@2023-10-01-preview' = {
+  name: 'redisCache'
+  properties: {
+    environment: environment
+    application: application
+    resourceProvisioning: 'manual'
+    resources: [{
+      id: '/planes/kubernetes/local/namespaces/${svc.metadata.namespace}/providers/core/Service/${svc.metadata.name}'
+    }
+    {
+      id: '/planes/kubernetes/local/namespaces/${redis.metadata.namespace}/providers/apps/Deployment/${redis.metadata.name}'
+    }
+    ]
+    username: 'myusername'
+    host: '${svc.metadata.name}.${svc.metadata.namespace}.svc.cluster.local'
+    port: svc.ports[0].port
+  }
+}
+//MANUAL

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: 'radius.azurecr.io/tutorial/webapp:edge'
+    }
+  }
+}
+//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"]
 ---