From 0ade40cfb33db9c5a741750e2adde5e72ebcddad Mon Sep 17 00:00:00 2001 From: Zach Casper Date: Wed, 19 Aug 2026 12:08:16 -0500 Subject: [PATCH] Updated manage applications section to use sample app.bicep Signed-off-by: Zach Casper --- .../applications/connections/_index.md | 108 ++++------------ .../applications/definitions/_index.md | 118 +++++++----------- docs/content/applications/deploy/_index.md | 76 +++-------- docs/layouts/shortcodes/rad.html | 8 ++ 4 files changed, 88 insertions(+), 222 deletions(-) diff --git a/docs/content/applications/connections/_index.md b/docs/content/applications/connections/_index.md index e03f778a2..2097acc28 100644 --- a/docs/content/applications/connections/_index.md +++ b/docs/content/applications/connections/_index.md @@ -10,128 +10,62 @@ aliases: A connection is an explicit relationship between two resources in your [Application]({{< ref "/concepts/applications" >}}). Declaring a connection from a Container to another resource adds an edge to the Application graph and injects the connected resource's properties into the Container as environment variables. Your application then reads those variables instead of hard-coding hosts, ports, or credentials. -This guide adds a Redis cache to an application and connects a Container to it. It builds on the definition from [How to model an application definition]({{< ref "/applications/definitions" >}}). +This guide adds a Redis cache to an application and connects a Container to it. It builds on the definition from [How to model application resources]({{< ref "/applications/definitions" >}}). ## Step 1: Start from an application definition -Begin with a definition that declares an Application and a Container. The following `app.bicep` defines a `frontend` Container: - -```bicep -extension radius - -@description('The Radius Environment ID. Injected automatically by the rad CLI.') -param environment string - -resource app 'Radius.Core/applications@2025-08-01-preview' = { - name: 'my-app' - properties: { - environment: environment - } -} - -resource frontend 'Radius.Compute/containers@2025-08-01-preview' = { - name: 'frontend' - properties: { - environment: environment - application: app.id - containers: { - web: { - image: 'ghcr.io/radius-project/samples/demo:latest' - ports: { - web: { - containerPort: 3000 - } - } - } - } - } -} -``` - -See [How to model an application definition]({{< ref "/applications/definitions" >}}) to build this file from scratch. +Begin with the Radius Demo `app.bicep` from [How to model application resources]({{< ref "/applications/definitions" >}}). It declares a `demoApp` Application and a `demoContainer` Container, which the following steps connect to a Redis cache. ## Step 2: Add the resource to connect to -Add the dependency the Container needs. The following example adds a `Radius.Data/redisCaches` resource named `db` to the same Application: + +Add the dependency the Container needs. The demo's `app-redis.bicep` definition adds a `Radius.Data/redisCaches` resource named `redis` to the same Application: -```bicep -resource db 'Radius.Data/redisCaches@2025-08-01-preview' = { - name: 'db' - properties: { - environment: environment - application: app.id - } -} -``` +{{< rad file="/static/samples/demo/app-redis.bicep" embed=true startLine=40 endLine=47 >}} ## Step 3: Connect the Container to the resource Add a `connections` entry to the Container's `properties`. Each connection has a name and a `source` set to the target resource's `.id`: -```bicep -resource frontend 'Radius.Compute/containers@2025-08-01-preview' = { - name: 'frontend' - properties: { - environment: environment - application: app.id - containers: { - web: { - image: 'ghcr.io/radius-project/samples/demo:latest' - ports: { - web: { - containerPort: 3000 - } - } - } - } - connections: { - redis: { - source: db.id - } - } - } -} -``` +{{< rad file="/static/samples/demo/app-redis.bicep" embed=true startLine=17 endLine=38 markdownConfig=`{hl_lines=["16-20"]}` >}} -The connection name (`redis`) becomes the prefix of the environment variables Radius injects into the Container. Referencing `db.id` also orders the deployment so Radius creates the cache before the Container. +The connection name (`redis`) becomes the prefix of the environment variables Radius injects into the Container. Referencing `redis.id` also orders the deployment so Radius creates the cache before the Container. ## Step 4: Deploy the application -Deploy the updated definition with [`rad deploy`]({{< ref rad_deploy >}}): +Deploy the updated definition from its published URL with [`rad deploy`]({{< ref rad_deploy >}}): -```bash -rad deploy app.bicep -``` +{{< rad-deploy path="samples/demo/app-redis.bicep" >}} Radius provisions the Redis cache, injects its connection details into the Container, and records the connection in the Application graph. ## Step 5: Inspect the connection in the Application graph -Use [`rad application graph`]({{< ref rad_application_graph >}}) to view the resources and the connection between them: +Use [`rad application graph`]({{< ref rad_application_graph >}}) to view the resources and the connection between them. The sample includes the Environment name in its resource names; the following command uses the default Environment: ```bash -rad application graph --application my-app --preview +rad application graph --application demo-default --preview ``` -The output shows the `frontend` Container connected to the `db` cache, along with the infrastructure each resource created: +The output shows the `demo-default` Container connected to the `redis-default` cache, along with the infrastructure each resource created: ```text -Displaying application: my-app +Displaying application: demo-default -Name: frontend (Radius.Compute/containers) +Name: demo-default (Radius.Compute/containers) Connections: - frontend -> db (Radius.Data/redisCaches) + demo-default -> redis-default (Radius.Data/redisCaches) Resources: - frontend (kubernetes: apps/Deployment) - frontend (kubernetes: core/Service) + demo-default (kubernetes: apps/Deployment) + demo-default (kubernetes: core/Service) -Name: db (Radius.Data/redisCaches) +Name: redis-default (Radius.Data/redisCaches) Connections: - frontend (Radius.Compute/containers) -> db + demo-default (Radius.Compute/containers) -> redis-default Resources: - db (kubernetes: apps/Deployment) - db (kubernetes: core/Service) + redis-default (kubernetes: apps/Deployment) + redis-default (kubernetes: core/Service) ``` ## Connection environment variables diff --git a/docs/content/applications/definitions/_index.md b/docs/content/applications/definitions/_index.md index 3cf019955..8a80c1d7e 100644 --- a/docs/content/applications/definitions/_index.md +++ b/docs/content/applications/definitions/_index.md @@ -1,22 +1,20 @@ --- type: docs -title: "How to model an application definition" +title: "How to model application resources" linkTitle: "Model application resources" description: "Learn how to model an application using Bicep and Radius Resource Types" weight: 100 --- -An application definition is a Bicep file that declares your [Application]({{< ref "/concepts/applications" >}}) and the resources it is made of. You model each resource with a [Resource Type]({{< ref "/concepts/resource-types" >}}), and Radius provisions the backing infrastructure when you deploy the file. This guide builds an `app.bicep` definition from an empty file, adds resources, and references dependencies between them. +An application definition is a Bicep file that declares your [Application]({{< ref "/concepts/applications" >}}) and the resources it is made of. You model each resource with a [Resource Type]({{< ref "/concepts/resource-types" >}}), and Radius provisions the backing infrastructure when you deploy the file. This guide walks through the Radius Demo `app.bicep` definition and explains how it models resources and dependencies. When the definition is ready, see [How to deploy applications using Radius]({{< ref "/applications/deploy" >}}) to deploy it to an Environment. ## Step 1: Import the Radius extension -Create a Bicep file for your application and import the Radius Bicep extension. This guide uses `app.bicep`, but the file can have any name. The extension makes the Radius Resource Types available in Bicep: +Begin by importing the Radius Bicep extension. The extension makes the Radius Resource Types available in Bicep: -```bicep -extension radius -``` +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=1 endLine=1 >}} The `radius` extension is configured in the `bicepconfig.json` created by `rad initialize`. If you have custom resource types to use, see [Add custom resource types to bicepconfig.json]({{< ref "/installation/dev-workstation#configure-bicepconfigjson" >}}). @@ -24,60 +22,45 @@ The `radius` extension is configured in the `bicepconfig.json` created by `rad i Every Application targets a Radius [Environment]({{< ref "/concepts/environments" >}}). Declare an `environment` parameter so the Radius CLI can supply the selected Environment's resource ID when you deploy: -```bicep -@description('The Radius Environment ID. Injected automatically by the rad CLI.') -param environment string -``` +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=3 endLine=4 >}} -You do not set this value yourself. `rad deploy` passes the Environment from the current [Workspace]({{< ref "/management/workspaces" >}}), or from the `--environment` flag. +You do not set this value yourself. `rad deploy` passes the Environment ID from the current [Workspace]({{< ref "/management/workspaces" >}}), or from the `--environment` flag. -## Step 3: Define the Application resource +## Step 3: Name your resources -Declare a `Radius.Core/applications` resource to group the resources that make up your application. Set its `environment` property to the parameter: +Every resource in your definition needs a `name`, and names must be unique per Resource Type within a Resource Group. You have two options: -```bicep -resource app 'Radius.Core/applications@2025-08-01-preview' = { - name: 'my-app' - properties: { - environment: environment - } -} -``` +- **Static names.** Give each resource a simple, unique name per Resource Type. This works well when you deploy the application to a single Environment. +- **Environment-suffixed names.** If you deploy the same definition to multiple Environments that share a Resource Group, add the Environment name as a suffix so the names do not collide. + +The demo uses the second option. It derives the Environment name from the `environment` parameter's resource ID: + +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=11 endLine=11 >}} + +It then interpolates `environmentName` into each resource name, such as `demo-${environmentName}`, so the same definition deploys cleanly to `dev`, `test`, and `prod`. + +## Step 4: Define the Application resource + +Declare a `Radius.Core/applications` resource to group the resources that make up your application. Its name applies the pattern from the previous step: + +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=13 endLine=18 markdownConfig=`{hl_lines=[2]}` >}} The Application records the resources that belong to it and the relationships between them. Radius uses it to build the Application graph and to manage the resources together. -## Step 4: Add resources with Resource Types +## Step 5: Add resources with Resource Types Add the resources your application needs. Each resource uses a Resource Type and sets two properties that associate it with the Application: -- `environment` links the resource to the Radius Environment. -- `application` links the resource to the Application, using the Application's `.id`. - -The following example adds a container that runs the application's front end: - -```bicep -resource frontend 'Radius.Compute/containers@2025-08-01-preview' = { - name: 'frontend' - properties: { - environment: environment - application: app.id - containers: { - web: { - image: 'ghcr.io/radius-project/samples/demo:latest' - ports: { - web: { - containerPort: 3000 - } - } - } - } - } -} -``` - -Referencing `app.id` creates a symbolic dependency, so Radius creates the Application before the container. - -## Step 5: Choose the right Resource Type +- **`environment`** links the resource to the Radius Environment. Each resource sets this to the `environment` parameter, whose value the Radius CLI supplies at deploy time. +- **`application`** links the resource to the Application, using the Application's `.id`. + +The demo adds a container that runs the application's front end: + +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=20 endLine=36 markdownConfig=`{hl_lines=["4-5"]}` >}} + +Referencing `demoApp.id` creates a symbolic dependency, so Radius creates the Application before the container. + +## Step 6: Choose the right Resource Type Model each part of your application with the Resource Type that best represents it. Radius ships with a set of [out-of-the-box Resource Types]({{< ref "/reference/resources" >}}) for compute, data, messaging, and more, and your platform team can publish [custom Resource Types]({{< ref "/extensibility/resource-types" >}}) for anything specific to your organization. @@ -86,32 +69,15 @@ Model each part of your application with the Resource Type that best represents The Environment's [Recipe Packs]({{< ref "/concepts/recipe-packs" >}}) must contain a recipe for every Resource Type your definition uses. Without a matching recipe, the deployment fails because Radius does not know how to provision that resource. -## Step 6: Parameterize the definition - -Use Bicep parameters for values that change between Environments or deployments, such as an image tag or a resource size. Parameters keep a single definition reusable across `dev`, `test`, and `prod`: - -```bicep -@description('Container image tag to deploy.') -param imageTag string = 'latest' - -resource frontend 'Radius.Compute/containers@2025-08-01-preview' = { - name: 'frontend' - properties: { - environment: environment - application: app.id - containers: { - web: { - image: 'ghcr.io/radius-project/samples/demo:${imageTag}' - ports: { - web: { - containerPort: 3000 - } - } - } - } - } -} -``` +## Step 7: Parameterize the definition + +Use Bicep parameters for values that change between Environments or deployments, such as a container image or a resource size. Parameters keep a single definition reusable across `dev`, `test`, and `prod`. The demo declares an `image` parameter with the published image as its default: + +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=6 endLine=7 >}} + +The container uses the parameter instead of hard-coding the image: + +{{< rad file="/static/samples/demo/app.bicep" embed=true startLine=20 endLine=36 markdownConfig=`{hl_lines=[8]}` >}} Supply parameter values at deploy time with `--parameters`, or store them in a `.bicepparam` file. Keep the `environment` parameter as is; the Radius CLI supplies it automatically. diff --git a/docs/content/applications/deploy/_index.md b/docs/content/applications/deploy/_index.md index 6caef071c..1ad7a0dd4 100644 --- a/docs/content/applications/deploy/_index.md +++ b/docs/content/applications/deploy/_index.md @@ -12,65 +12,25 @@ An [Application]({{< ref "/concepts/applications" >}}) in Radius groups the reso ## Step 1: Create an application definition -Create a file named `app.bicep`. Import the Radius extension and declare an `environment` parameter. The Radius CLI supplies the selected Environment's resource ID when you deploy the file. - -Define a `Radius.Core/applications` resource, then add the resources that make up the Application. Set `environment` and `application` on each resource to associate it with the Application: - -```bicep -extension radius - -@description('The Radius Environment ID. Injected automatically by the rad CLI.') -param environment string - -resource app 'Radius.Core/applications@2025-08-01-preview' = { - name: 'my-app' - properties: { - environment: environment - } -} - -resource frontend 'Radius.Compute/containers@2025-08-01-preview' = { - name: 'frontend' - properties: { - environment: environment - application: app.id - containers: { - web: { - image: 'ghcr.io/radius-project/samples/demo:latest' - ports: { - web: { - containerPort: 3000 - } - } - } - } - } -} -``` - -Use any Resource Type installed in your Radius control plane. Review the [Resource Types reference]({{< ref "/reference/resources" >}}) for the available properties and examples. The Environment's Recipe Packs must contain a recipe for each Resource Type used by the Application. +Begin with the Radius Demo `app.bicep` from [How to model application resources]({{< ref "/applications/definitions" >}}). It declares a `demoApp` Application and a `demoContainer` Container. The target Environment's Recipe Packs must contain a recipe for each Resource Type the definition uses. ## Step 2: Deploy to an Environment -Deploy the application definition to an Environment with [`rad deploy`]({{< ref rad_deploy >}}): +Deploy the application definition from its published URL to an Environment with [`rad deploy`]({{< ref rad_deploy >}}): -```bash -rad deploy app.bicep -``` +{{< rad-deploy path="samples/demo/app.bicep" >}} Radius compiles the Bicep file, supplies the Environment configured in the current Workspace through the `environment` parameter, and creates or updates the Application and its resources. Use `--environment` to deploy to a different Environment: -```bash -rad deploy app.bicep --environment dev -``` +{{< rad-deploy path="samples/demo/app.bicep" args="--environment dev" >}} After the deployment succeeds, inspect the Application graph: ```bash -rad application graph --application my-app --preview +rad application graph --application demo-default --preview ``` The graph shows the Radius resources, infrastructure created by recipes, and relationships between resources. @@ -87,8 +47,8 @@ Use JSON output when you need the complete resource details: ```bash -rad application status my-app --preview --output json -rad application graph --application my-app --preview --output json +rad application status demo-default --preview --output json +rad application graph --application demo-default --preview --output json ``` If a recipe creates Kubernetes resources, inspect the target namespace for failed workloads and events: @@ -102,24 +62,22 @@ The Kubernetes namespace is configured on the Environment and may differ from th ## Prune removed resources -Removing a resource declaration from `app.bicep` and deploying the file again does not delete the existing resource. This prevents an accidental deletion when a declaration is removed or renamed. +Removing a resource declaration from your definition and deploying the file again does not delete the existing resource. This prevents an accidental deletion when a declaration is removed or renamed. -After removing the declaration, deploy the updated Application: +For example, if you added the `redis` cache in [How to model application dependencies using connections]({{< ref "/applications/connections" >}}), redeploy the original `app.bicep`, which does not declare the cache or its connection: -```bash -rad deploy app.bicep -``` +{{< rad-deploy path="samples/demo/app.bicep" >}} -List the resources that still belong to the Application: +Radius leaves the existing `redis-default` cache in place because its declaration is gone. List the Application's resources to confirm: ```bash -rad resource list --application my-app +rad resource list --application demo-default ``` -Delete the removed resource by its Resource Type and name. For example, delete the `frontend` Container: +Delete the removed resource by its Resource Type and name: ```bash -rad resource delete Radius.Compute/containers frontend +rad resource delete Radius.Data/redisCaches redis-default ``` The command prompts for confirmation, deletes the Radius resource, and runs its normal deletion lifecycle for infrastructure managed by that resource. @@ -130,7 +88,7 @@ Confirm that the removed resource no longer appears in the Application graph: ```bash -rad application graph --application my-app --preview +rad application graph --application demo-default --preview ``` ## Delete an Application @@ -139,10 +97,10 @@ Delete an Application when it and all of its owned resources are no longer neede ```bash -rad application delete my-app --preview +rad application delete demo-default --preview ``` -The command prompts for confirmation. Radius finds resources whose `application` property references `my-app`, deletes them, and then deletes the Application resource. Resources that are shared with or connected to the Application but are not owned by it are not deleted. +The command prompts for confirmation. Radius finds resources whose `application` property references `demo-default`, deletes them, and then deletes the Application resource. Resources that are shared with or connected to the Application but are not owned by it are not deleted. Deleting an Application can permanently delete managed infrastructure and data. Review the Application graph before confirming the operation. Use `--yes` to bypass confirmation in automation. diff --git a/docs/layouts/shortcodes/rad.html b/docs/layouts/shortcodes/rad.html index ce16fc930..ad607ca4b 100644 --- a/docs/layouts/shortcodes/rad.html +++ b/docs/layouts/shortcodes/rad.html @@ -6,6 +6,14 @@ {{ $embed := .Get "embed" | default false }} {{ $download := .Get "download" | default false }} {{ $markdownConfig := .Get "markdownConfig" | default "" }} +{{ $markdownConfig = cond (eq $markdownConfig "") "" (printf " %s" $markdownConfig) }} +{{ $startLine := int (.Get "startLine" | default 0) }} +{{ $endLine := int (.Get "endLine" | default 0) }} + +{{ if and (gt $startLine 0) (ge $endLine $startLine) }} + {{ $lines := split $fileContents "\n" }} + {{ $fileContents = delimit (first (add (sub $endLine $startLine) 1) (after (sub $startLine 1) $lines)) "\n" }} +{{ end }} {{ if $download }} Download Bicep file