+
+## Prerequisites
+
+- [rad CLI]({{< ref "installation#step-1-install-the-rad-cli" >}})
+- [Helm](https://helm.sh/docs/intro/install/)
+- [Setup a supported Kubernetes cluster]({{< ref "/guides/operations/kubernetes/overview#supported-clusters" >}})
+
+## 1. Clone and open the sample code
+
+{{< tabs "Codespaces" "non-Codespaces" >}}
+
+{{% codetab %}}
+
+If you are using the Radius codespace you should already have the application cloned locally. Use the terminal to navigate to the `./demo/` directory:
+
+```bash
+cd ./demo
+```
+
+{{% /codetab %}}
+
+
+
+{{% codetab %}}
+Use the terminal to clone the `samples` repository locally and navigate to the `./samples/demo` directory:
+
+```bash
+git clone https://github.com/radius-project/samples.git
+cd ./samples/demo
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
+## 2. Initialize Radius
+
+Initialize Radius. For this example, answer **NO** when asked whether to set up an application:
+
+```bash
+rad init
+```
+
+ **Select 'No' when prompted to create an application.**
+
+
+## 3. Understand and deploy the application
+
+Navigate to the `./Chart` folder and browse its contents. This contains a Helm chart for the application that will we modify.
+
+Here are the contents of `./demo/Chart/templates/app.yaml`. This file is part of the Helm chart, and describes the container used for this tutorial:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: webapp
+ namespace: {{ .Release.Namespace }}
+spec:
+ selector:
+ matchLabels:
+ app: webapp
+ template:
+ metadata:
+ labels:
+ app: webapp
+ spec:
+ containers:
+ - name: webapp
+ image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
+ env:
+ - name: CONNECTION_REDIS_URL
+ valueFrom:
+ secretKeyRef:
+ name: redis-secret
+ key: url
+ ports:
+ - containerPort: 3000
+```
+
+The container that you will be working with is a TODO application that uses Redis as a database.
+
+- The container is configured to listen on port 3000.
+- The container will use the environment variable `CONNECTION_REDIS_URL` to connect to Redis.
+- This `CONNECTION_REDIS_URL` environment variable is populated by a Kubernetes Secret.
+
+We can deploy this application for the first time by following these steps:
+
+- Create the Kubernetes namespace `demo`
+- Create the Kubernetes Secret `redis-secret` holding the Redis URL.
+- Install the Helm chart.
+
+{{< alert title="💡 Redis" color="info" >}}
+For now you're not going to actually deploy Redis, the URL in this step is fake. You will deploy Redis using a Recipe later in the tutorial.
+{{< /alert >}}
+
+Complete these steps by running the following commands:
+
+```bash
+kubectl create namespace demo
+kubectl create secret generic --namespace demo --from-literal=url=redis://redis-master:6379 redis-secret
+helm upgrade demo ./Chart -n demo --install
+```
+
+The output should look similar to the following:
+
+```txt
+> kubectl create namespace demo
+namespace/demo created
+
+> kubectl create secret generic --namespace demo --from-literal=url=redis://redis-master:6379 redis-secret
+secret/redis-secret created
+
+> helm upgrade demo ./Chart -n demo --install
+Release "demo" does not exist. Installing it now.
+NAME: demo
+LAST DEPLOYED: Wed Sep 13 01:05:19 2023
+NAMESPACE: demo
+STATUS: deployed
+REVISION: 1
+TEST SUITE: None
+```
+
+{{< alert title="⚠️ Chart Directory" color="warning" >}}
+If you see an error message like **Error: path "./Chart" not found** then you are in the wrong directory. Make sure your terminal is in the `./demo` directory of the `samples` repository.
+{{< /alert >}}
+
+Run the following command to check if everything is running:
+
+```bash
+kubectl get all -n demo
+```
+
+The output should look similar to the following:
+
+```txt
+> kubectl get all -n demo
+NAME READY STATUS RESTARTS AGE
+pod/webapp-79d5dfb99-vhj9g 1/1 Running 0 2m48s
+
+NAME READY UP-TO-DATE AVAILABLE AGE
+deployment.apps/webapp 1/1 1 1 2m49s
+
+NAME DESIRED CURRENT READY AGE
+replicaset.apps/webapp-79d5dfb99 1 1 1 2m49s
+```
+
+The generated names and ages of the objects will be different in your output. Make sure you see the status of `Running` for the `pod/webapp-...` entry. If the status is not `Running`, try repeating the `kubectl get all -n demo` after waiting.
+
+At this point we've deployed the application but we have not actually used Radius yet. You will start doing that in the next step. You might also be wondering how we're going to use Redis as we have not set one up yet.
+
+The steps so far are similar to how many applications are managed today:
+
+- Dependencies like Redis are provisioned manually and separately from application deployment.
+- Connection information like passwords and addresses is manually stored in secret stores.
+- Applications access the connection information from those secret stores when they are deployed.
+
+Over the next few steps you will update this application to use Radius so that:
+
+- ✅ Dependencies like Redis are provisioned on-demand when they are needed.
+- ✅ Connection information is mananged automatically, secret stores are an implementation detail.
+- ✅ Applications have a documented relationship with the dependencies they connect to.
+
+From here you will go through a series of steps to incrementally add more of Radius' features to the application.
+
+## 5. Add Radius
+
+Make sure the `app.yaml` file from `./demo/Chart/templates/app.yaml` is open in your editor. You will make some edits to this file to enable Radius.
+
+Add the `annotations` property to `metadata`, and then add the `radapp.io/enabled: 'true'` annotation. The `'true'` must be surrounded in quotes.
+
+The example below shows the updated `metadata` section after making the changes.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: webapp
+ namespace: {{ .Release.Namespace }}
+ annotations:
+ radapp.io/enabled: 'true'
+spec:
+...
+```
+
+Adding the `radapp.io/enabled: 'true'` annotation enables Radius for the deployment.
+
+Now that you have made the edits, save the file, and deploy the application again using Helm. Since the namespace and secret have already been created, we only need to run the `helm` command.
+
+```bash
+helm upgrade demo ./Chart -n demo --install
+```
+
+The output should look like:
+
+```txt
+> helm upgrade demo ./Chart -n demo --install
+Release "demo" has been upgraded. Happy Helming!
+NAME: demo
+LAST DEPLOYED: Wed Sep 13 01:31:58 2023
+NAMESPACE: demo
+STATUS: deployed
+REVISION: 2
+TEST SUITE: None
+```
+
+You should confirm that your output contains `REVISION: 2`, that means that the changes were applied.
+
+Run the following command to check if everything is running:
+
+```bash
+kubectl get all -n demo
+```
+
+The output should look similar to the following:
+
+```txt
+> kubectl get all -n demo
+NAME READY STATUS RESTARTS AGE
+pod/webapp-79d5dfb99-mv6q9 1/1 Running 0 10m
+
+NAME READY UP-TO-DATE AVAILABLE AGE
+deployment.apps/webapp 1/1 1 1 10m
+
+NAME DESIRED CURRENT READY AGE
+replicaset.apps/webapp-79d5dfb99 1 1 1 10m
+```
+
+
+
+Now that we've enabled Radius, run this command to display the state of the Radius application:
+
+```bash
+rad app graph -a demo -g default-demo
+```
+
+The output should look like this:
+
+```txt
+> rad app graph -a demo -g default-demo
+Displaying application: demo
+
+Name: webapp (Applications.Core/containers)
+Connections: (none)
+Resources:
+ webapp (kubernetes: apps/Deployment)
+
+
+```
+
+Now Radius has found the Kubernetes `Deployment` running your container and cataloged it as part of the application.
+
+{{< alert title="💡 Application Name" color="info" >}}
+Radius will use the Kubernetes namespace as the application name by default.
+{{< /alert >}}
+
+## 6. Add Recipe
+
+This step will add a database (Redis Cache) to the application.
+
+You can create a Redis Cache using [Recipes]({{< ref "guides/recipes/overview" >}}) provided by Radius. The Radius community provides Recipes for running commonly used application dependencies, including Redis.
+
+In this step you will:
+
+- Add Redis to the application using a Recipe.
+- Update the Kubernetes secret with the connection information from Redis.
+
+First, check recipes installed in your environment by running:
+
+```
+rad recipe list
+```
+
+You will see output like this:
+
+```
+NAME TYPE TEMPLATE KIND TEMPLATE VERSION TEMPLATE
+default Applications.Datastores/sqlDatabases bicep radius.azurecr.io/recipes/local-dev/sqldatabases:latest
+default Applications.Messaging/rabbitMQQueues bicep radius.azurecr.io/recipes/local-dev/rabbitmqqueues:latest
+default Applications.Dapr/pubSubBrokers bicep radius.azurecr.io/recipes/local-dev/pubsubbrokers:latest
+default Applications.Dapr/secretStores bicep radius.azurecr.io/recipes/local-dev/secretstores:latest
+default Applications.Dapr/stateStores bicep radius.azurecr.io/recipes/local-dev/statestores:latest
+default Applications.Datastores/mongoDatabases bicep radius.azurecr.io/recipes/local-dev/mongodatabases:latest
+default Applications.Datastores/redisCaches bicep radius.azurecr.io/recipes/local-dev/rediscaches:latest
+```
+
+The recipe for `Applications.Datastores/redisCaches` is the one that will be used in this example.
+
+{{< alert title="💡 Recipes" color="info" >}}
+ Radius includes Recipes for local development when you use `rad init`. These **local-dev** Recipes run popular OSS technologies as containerized infrastructure without requiring a cloud account.
+
+ In a production environment you can substitute recipes that will create cloud or on-premises dependencies instead.
+{{< /alert >}}
+
+Make sure the `app.yaml` file from `./demo/Chart/templates/app.yaml` is open in your editor. At the bottom of the file add the following text, including the `---`:
+
+```yaml
+---
+apiVersion: radapp.io/v1alpha3
+kind: Recipe
+metadata:
+ name: db
+ namespace: {{ .Release.Namespace }}
+spec:
+ type: Applications.Datastores/redisCaches
+ secretName: redis-secret
+```
+
+Defining a `Recipe` object in Kubernetes will use a Radius Recipe to create dependencies for your application:
+
+- The `.spec.type` field defines the type of resource to create. `Applications.Datastores/redisCaches` is the type for a Redis Cache.
+- The `.spec.secretName` field tells Radius where to store connection information. This is optional, and should be used to interoperate with other Kubernetes technologies that read from secrets. In our case we're using the secret to populate an environment variable.
+
+Now that you have made the edits, save the file, and deploy the application again using Helm. Since the namespace and secret have already been created, we only need to run the `helm` command.
+
+```bash
+helm upgrade demo ./Chart -n demo --install
+```
+
+The output should look like:
+
+```txt
+> helm upgrade demo ./Chart -n demo --install
+Release "demo" has been upgraded. Happy Helming!
+NAME: demo
+LAST DEPLOYED: Wed Sep 13 01:44:04 2023
+NAMESPACE: demo
+STATUS: deployed
+REVISION: 3
+TEST SUITE: None
+```
+
+This time you should see `REVISION: 3`.
+
+Now that you are using a Recipe, you should see more resources running in Kubernetes. Run the following command:
+
+```bash
+kubectl get all -n demo
+```
+
+The output should look similar to the following:
+
+```txt
+> kubectl get all -n demo
+
+pod/redis-r5tcrra3d7uh6-7bcd8b8d8d-jmgn4 2/2 Running 0 51s
+pod/webapp-79d5dfb99-f6xgj 1/1 Running 0 52s
+
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+service/redis-r5tcrra3d7uh6 ClusterIP 10.43.104.63 
++ +Congrats! You're running your first Radius app. + +You can use the homepage to view information about the container and its settings. + +Navigate to the TODO List tab and test out the application. Using the TODO page will update the saved state in Redis. + +
++ +When you're ready to move on to the next step, use `CTRL+C` to exit the command. + +## Cleanup and next steps + +To delete your app, run the following command: + +```bash +helm uninstall demo -n demo +``` + +In this tutorial you saw hands-on how-to: + +- Enable Radius for a Helm or Kubernetes-based application to catalog your assets. +- Use Recipes to create dependencies either for development or production use. +- Use Connections to automate the management of connection information. + +
+{{< button text="Next step: Radius Tutorials" page="tutorials" >}} diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 000000000..6ab682576 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "docs", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}