From a79e684a48587e19260b019504cb1928af45b4ea Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Wed, 1 Nov 2023 15:59:54 -0400 Subject: [PATCH] update s3 how-to with dynamodb Signed-off-by: Reshma Abdul Rahim --- .../aws/howto-aws-resources/index.md | 70 +++++----- .../snippets/dynamodb.bicep | 34 +++++ .../howto-aws-s3}/icon.png | Bin holding-pen/howto-aws-s3/index.md | 129 ++++++++++++++++++ .../howto-aws-s3}/s3app.png | Bin .../howto-aws-s3}/s3appdiagram.png | Bin .../howto-aws-s3}/snippets/app.bicep | 2 +- .../howto-aws-s3}/snippets/s3.bicep | 0 .../howto-aws-s3}/snippets/s3app.bicep | 2 +- 9 files changed, 197 insertions(+), 40 deletions(-) create mode 100644 docs/content/guides/author-apps/aws/howto-aws-resources/snippets/dynamodb.bicep rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/icon.png (100%) create mode 100644 holding-pen/howto-aws-s3/index.md rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/s3app.png (100%) rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/s3appdiagram.png (100%) rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/snippets/app.bicep (96%) rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/snippets/s3.bicep (100%) rename {docs/content/guides/author-apps/aws/howto-aws-resources => holding-pen/howto-aws-s3}/snippets/s3app.bicep (96%) diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/index.md b/docs/content/guides/author-apps/aws/howto-aws-resources/index.md index 78e1f0c00..32eb00781 100644 --- a/docs/content/guides/author-apps/aws/howto-aws-resources/index.md +++ b/docs/content/guides/author-apps/aws/howto-aws-resources/index.md @@ -10,10 +10,8 @@ weight: 200 This how-to guide will show you: -- How to model an AWS S3 resource in Bicep -- How to use a sample application to interact with AWS S3 bucket - - Screenshot of the sample application to interact with s3 bucket +- How to model an AWS Dynamo DB table in Bicep +- How to deploy an AWS resource in Radius ## Prerequisites @@ -52,53 +50,55 @@ Follow the prompts to install the [control plane services]({{< ref architecture- - **Add AWS provider** - An [AWS cloud provider]({{< ref "/guides/operations/providers/howto-aws-provider" >}}) allows you to deploy and manage AWS resources as part of your application. Enter 'y' and follow the instructions. Provide a valid AWS region and the values obtained for IAM Access Key ID and IAM Secret Access Keys. - **Environment name** - The name of the environment to create. You can specify any name with lowercase letters, such as `myawsenv`. -## Step 3: Create a Bicep file to model AWS Simple Storage Service (S3) +## Step 3: Create a Bicep file to model AWS Dynamo DB table -Create a new file called `app.bicep` and add the following bicep code to model an AWS S3 Bucket: +Create a new file called `dynamodb.bicep` and add the following bicep code to model a Dynamodb Table -{{< rad file="snippets/s3.bicep" embed=true >}} +{{< rad file="snippets/dynamodb.bicep" embed=true >}} Radius uses the [AWS Cloud Control API](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html) to interact with AWS resources. This means that you can model your AWS resources in Bicep and Radius will be able to deploy and manage them. You can find the list of supported AWS resources in the [AWS resource library]({{< ref "guides/author-apps/aws/overview#resource-library" >}}). -## Step 4: Add a Radius container to interact with the AWS S3 Bucket - -Open the `app.bicep` and append the following Radius resources: +## Step 5: Deploy the db to your environment -{{< rad file="snippets/s3app.bicep" embed=true marker="//S3APP" >}} +1. Deploy the db to your environment using the below command: -Your final `app.bicep` file should look like this + ```bash + rad deploy ./dynamodb.bicep + ``` + This will deploy the AWS Dynamo DB table to your environment. -{{< rad file="snippets/app.bicep" embed=true >}} + ``` + Building dynamodb.bicep... + Deploying template 'dynamodb.bicep' into environment 'aws' from workspace 'default'... -This creates a container that will be deployed to your Kubernetes cluster. This container will interact with the AWS S3 Bucket you created in the previous step. + Deployment In Progress... -## Step 5: Deploy the application + . demotable AWS.DynamoDB/GlobalTable -1. Deploy your application to your environment: + Deployment Complete - ```bash - rad deploy ./app.bicep -p aws_access_key_id= -p aws_secret_access_key= - ``` - > Replace `` and `` with the values obtained from the previous step. + Resources: + demotable AWS.DynamoDB/GlobalTable + ``` - {{% alert title="Warning" color="warning" %}}It is always recommended to have separate IAM credentials for your container to communicate with S3 or any other data store. - Radius is currently working on supporting direct connections to AWS resources so that your container can automatically communicate with the data store securely without having to manage separate credentials for data plane operations{{% /alert %}} +2. Verify that the AWS Dynamo DB table has been created via AWS Console / CLI -1. Port-forward the container to your machine with [`rad resource expose`]({{< ref rad_resource_expose >}}): +## Step 6: Cleanup - ```bash - rad resource expose containers frontend -a s3app --port 5234 - ``` +1. When you're done with testing, you can use the rad CLI to [delete an environment]({{< ref rad_env_delete.md >}}) to delete all Radius resources running on the EKS Cluster. -1. Visit [localhost:5234](http://localhost:5234/swagger/index.html) in your browser. This is a swagger doc for the sample application. You can use this to interact with the AWS S3 Bucket you created. For example, you can try to upload a file to the bucket via the `/upload` endpoint. +2. Cleanup AWS Resources - AWS resources are not deleted when deleting a Radius Environment, so make sure to delete all resources created in this reference app to prevent additional charges. You can delete these resources in the AWS Console or via the AWS CLI. - Screenshot of the sample application to interact with s3 bucket + ```bash + aws dynamodb delete-table --table-name demotable + ``` -## Step 6: Cleanup +## Further Reading -1. When you're done with testing, you can use the rad CLI to [delete an environment]({{< ref rad_env_delete.md >}}) to delete all Radius resources running on the EKS Cluster. +For further reference to examples of a sample Radius application that uses AWS resources, refer to the following tutorials: -2. Cleanup AWS Resources - AWS resources are not deleted when deleting a Radius Environment, so make sure to delete all resources created in this reference app to prevent additional charges. You can delete these resources in the AWS Console or via the AWS CLI. Instructions to delete an AWS S3 Bucket are available [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html). +1. [Deploy Recipes in your Radius Application]({{< ref "/tutorials/tutorial-recipe" >}}) +2. [eShop on containers]({{< ref "/tutorials/eshop" >}}) ## Troubleshooting @@ -118,12 +118,6 @@ If you have issues with the sample application, where the container doesn't conn 1. Use the below command to inspect logs from container: ```bash - rad resource logs containers frontend -a s3app + rad resource logs containers frontend -a ``` Also make sure to [open an Issue](https://github.com/radius-project/radius/issues/new/choose) if you encounter a generic `Internal server error` message or an error message that is not self-serviceable, so we can address the root error not being forwarded to the user. - -## Further Reading - -{{< categorizeby category="Overview" tag="AWS" >}} - -{{< categorizeby category="How-To" tag="AWS" >}} \ No newline at end of file diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/dynamodb.bicep b/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/dynamodb.bicep new file mode 100644 index 000000000..6c9c43205 --- /dev/null +++ b/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/dynamodb.bicep @@ -0,0 +1,34 @@ +import aws as aws + +resource dynamodb 'AWS.DynamoDB/GlobalTable@default'={ + properties: { + TableName:'demotable' + BillingMode: 'PAY_PER_REQUEST' + AttributeDefinitions: [ + { + AttributeName: 'order_id' + AttributeType: 'S' + } + { + AttributeName: 'quantity' + AttributeType: 'N' + } + ] + KeySchema: [ + { + AttributeName: 'order_id' + KeyType: 'HASH' + } + { + AttributeName: 'quantity' + KeyType: 'RANGE' + } + ] + Replicas: [ + { + Region: 'us-west-2' + } + ] + } + alias: 'dynamodb' +} diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/icon.png b/holding-pen/howto-aws-s3/icon.png similarity index 100% rename from docs/content/guides/author-apps/aws/howto-aws-resources/icon.png rename to holding-pen/howto-aws-s3/icon.png diff --git a/holding-pen/howto-aws-s3/index.md b/holding-pen/howto-aws-s3/index.md new file mode 100644 index 000000000..5aa3b5e4d --- /dev/null +++ b/holding-pen/howto-aws-s3/index.md @@ -0,0 +1,129 @@ +--- +type: docs +title: "How-To: Deploy AWS resources" +linkTitle: "Deploy AWS resources" +description: "Learn about how to add AWS resources to your application and deploy them with Radius" +categories: "How-To" +tags: ["AWS"] +weight: 200 +--- + +This how-to guide will show you: + +- How to model an AWS S3 resource in Bicep +- How to use a sample application to interact with AWS S3 bucket + + {{< image src="s3appdiagram.png" alt="Screenshot of the sample application to interact with s3 bucket " width=400 >}} + +## Prerequisites + +- Make sure you have an [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account) and an [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) + - [Create an IAM AWS access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) and copy the AWS Access Key ID and the AWS Secret Access Key to a secure location for use later. If you have already created an Access Key pair, you can use that instead. +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + - Configure your CLI with [`aws configure`](https://docs.aws.amazon.com/cli/latest/reference/configure/index.html), specifying your configuration values +- [eksctl CLI](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) +- [kubectl CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [rad CLI]({{< ref "installation#step-1-install-the-rad-cli" >}}) +- [Radius Bicep VSCode extension]({{< ref "installation#step-2-install-the-radius-bicep-extension" >}}) + +## Step 1: Create an EKS Cluster + +Create an EKS cluster by using the `eksctl` CLI. + +```bash +eksctl create cluster --name --region= +``` + +## Step 2: Create a Radius Environment with the AWS cloud provider + +Create a [Radius Environment]({{< ref "/guides/deploy-apps/environments/overview" >}}) where you will deploy your application. + +Run [`rad init --full`]({{< ref rad_init >}}) to initialize a new environment into your current kubectl context: + +```bash +rad init --full +``` + +Follow the prompts to install the [control plane services]({{< ref architecture-concept >}}), create an [environment resource]({{< ref "/guides/deploy-apps/environments" >}}), and create a [local workspace]({{< ref workspaces >}}). You will be asked for: + +- **Namespace** - When an application is deployed, this is the namespace where your containers and other Kubernetes resources will be run. By default, this will be in the `default` namespace. +{{% alert title="💡 About namespaces" color="success" %}} When you initialize a Radius Kubernetes environment, Radius installs the control plane resources within the `radius-system` namespace in your cluster, separate from your applications. The namespace specified in this step will be used for your application deployments. +{{% /alert %}} +- **Add AWS provider** - An [AWS cloud provider]({{< ref "/guides/operations/providers/howto-aws-provider" >}}) allows you to deploy and manage AWS resources as part of your application. Enter 'y' and follow the instructions. Provide a valid AWS region and the values obtained for IAM Access Key ID and IAM Secret Access Keys. +- **Environment name** - The name of the environment to create. You can specify any name with lowercase letters, such as `myawsenv`. + +## Step 3: Create a Bicep file to model AWS Simple Storage Service (S3) + +Create a new file called `app.bicep` and add the following bicep code to model an AWS S3 Bucket: + +{{< rad file="snippets/s3.bicep" embed=true >}} + +Radius uses the [AWS Cloud Control API](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html) to interact with AWS resources. This means that you can model your AWS resources in Bicep and Radius will be able to deploy and manage them. You can find the list of supported AWS resources in the [AWS resource library]({{< ref "guides/author-apps/aws/overview#resource-library" >}}). + +## Step 4: Add a Radius container to interact with the AWS S3 Bucket + +Open the `app.bicep` and append the following Radius resources: + +{{< rad file="snippets/s3app.bicep" embed=true marker="//S3APP" >}} + +Your final `app.bicep` file should look like this + +{{< rad file="snippets/app.bicep" embed=true >}} + +This creates a container that will be deployed to your Kubernetes cluster. This container will interact with the AWS S3 Bucket you created in the previous step. + +## Step 5: Deploy the application + +1. Deploy your application to your environment: + + ```bash + rad deploy ./app.bicep -p aws_access_key_id= -p aws_secret_access_key= + ``` + > Replace `` and `` with the values obtained from the previous step. + + {{% alert title="Warning" color="warning" %}}It is always recommended to have separate IAM credentials for your container to communicate with S3 or any other data store. + Radius is currently working on supporting direct connections to AWS resources so that your container can automatically communicate with the data store securely without having to manage separate credentials for data plane operations{{% /alert %}} + +1. Port-forward the container to your machine with [`rad resource expose`]({{< ref rad_resource_expose >}}): + + ```bash + rad resource expose containers frontend -a s3app --port 5234 + ``` + +1. Visit [localhost:5234](http://localhost:5234/swagger/index.html) in your browser. This is a swagger doc for the sample application. You can use this to interact with the AWS S3 Bucket you created. For example, you can try to upload a file to the bucket via the `/upload` endpoint. + + {{< image src="s3app.png" alt="Screenshot of the sample application to interact with s3 bucket " width=900 >}} + +## Step 6: Cleanup + +1. When you're done with testing, you can use the rad CLI to [delete an environment]({{< ref rad_env_delete.md >}}) to delete all Radius resources running on the EKS Cluster. + +2. Cleanup AWS Resources - AWS resources are not deleted when deleting a Radius Environment, so make sure to delete all resources created in this reference app to prevent additional charges. You can delete these resources in the AWS Console or via the AWS CLI. Instructions to delete an AWS S3 Bucket are available [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html). + +## Troubleshooting + +If you hit errors while deploying the application, please follow the steps below to troubleshoot: + +1. Check if the AWS credentials are valid. Login to the AWS console and check if the IAM access key and secret access key are valid and not expired. + +2. Look at the control plane logs to see if there are any errors. You can use the following command to view the logs: + + ```bash + rad debug-logs + ``` + Inspect the UCP logs to see if there are any errors + +If you have issues with the sample application, where the container doesn't connect with the S3 bucket, please follow the steps below to troubleshoot: + +1. Use the below command to inspect logs from container: + + ```bash + rad resource logs containers frontend -a s3app + ``` +Also make sure to [open an Issue](https://github.com/radius-project/radius/issues/new/choose) if you encounter a generic `Internal server error` message or an error message that is not self-serviceable, so we can address the root error not being forwarded to the user. + +## Further Reading + +{{< categorizeby category="Overview" tag="AWS" >}} + +{{< categorizeby category="How-To" tag="AWS" >}} \ No newline at end of file diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/s3app.png b/holding-pen/howto-aws-s3/s3app.png similarity index 100% rename from docs/content/guides/author-apps/aws/howto-aws-resources/s3app.png rename to holding-pen/howto-aws-s3/s3app.png diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/s3appdiagram.png b/holding-pen/howto-aws-s3/s3appdiagram.png similarity index 100% rename from docs/content/guides/author-apps/aws/howto-aws-resources/s3appdiagram.png rename to holding-pen/howto-aws-s3/s3appdiagram.png diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/app.bicep b/holding-pen/howto-aws-s3/snippets/app.bicep similarity index 96% rename from docs/content/guides/author-apps/aws/howto-aws-resources/snippets/app.bicep rename to holding-pen/howto-aws-s3/snippets/app.bicep index 70e2a1c43..0673c98a5 100644 --- a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/app.bicep +++ b/holding-pen/howto-aws-s3/snippets/app.bicep @@ -45,7 +45,7 @@ resource frontend 'Applications.Core/containers@2023-10-01-preview' = { AWS_SECRET_ACCESS_KEY: aws_secret_access_key AWS_DEFAULT_REGION: aws_region } - image: 'radius.azurecr.io/samples/aws:latest' + image: 'ghcr.io/radius-project/samples/aws:latest' } } } diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/s3.bicep b/holding-pen/howto-aws-s3/snippets/s3.bicep similarity index 100% rename from docs/content/guides/author-apps/aws/howto-aws-resources/snippets/s3.bicep rename to holding-pen/howto-aws-s3/snippets/s3.bicep diff --git a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/s3app.bicep b/holding-pen/howto-aws-s3/snippets/s3app.bicep similarity index 96% rename from docs/content/guides/author-apps/aws/howto-aws-resources/snippets/s3app.bicep rename to holding-pen/howto-aws-s3/snippets/s3app.bicep index 76a5f1cc4..53f425470 100644 --- a/docs/content/guides/author-apps/aws/howto-aws-resources/snippets/s3app.bicep +++ b/holding-pen/howto-aws-s3/snippets/s3app.bicep @@ -46,7 +46,7 @@ resource frontend 'Applications.Core/containers@2023-10-01-preview' = { AWS_SECRET_ACCESS_KEY: aws_secret_access_key AWS_DEFAULT_REGION: aws_region } - image: 'radius.azurecr.io/samples/aws:latest' + image: 'ghcr.io/radius-project/samples/aws:latest' } } }