AWS cloud-map documentation change
Summary
Complete restructuring of tutorial steps from 10-step DynamoDB/Lambda implementation to 5-step DNS/API discovery simulation. Removed AWS resource creation (DynamoDB, Lambda functions, IAM roles) and added CLI/dig command verification.
Security assessment
Changes focus on simplifying the tutorial methodology rather than addressing security vulnerabilities. The removal of IAM role creation steps reduces potential misconfiguration risks but doesn't directly fix a documented security issue. The added note about domain ownership in production is a best practice recommendation, not a security feature addition.
Diff
diff --git a/cloud-map/latest/dg/tutorial-private-namespace.md b/cloud-map/latest/dg/tutorial-private-namespace.md index 5c67eef6e..7ae45f97c 100644 --- a//cloud-map/latest/dg/tutorial-private-namespace.md +++ b//cloud-map/latest/dg/tutorial-private-namespace.md @@ -5 +5 @@ -PrerequisitesStep 1: Create a namespaceStep 2: Create a DynamoDB tableStep 3: Create the data serviceStep 4: Create an execution roleStep 5: Create the Lambda function to write dataStep 6: Create the app serviceStep 7: Create the Lambda function to read dataStep 8: Create a service instanceStep 9: Create and run client applicationsStep 10: Clean up +PrerequisitesStep 1: Create a namespaceStep 2: Create the servicesStep 3: Create the service instancesStep 4: Discover the service instancesStep 5: Clean up @@ -7 +7 @@ PrerequisitesStep 1: Create a namespaceStep 2: Create a DynamoDB tableStep 3: Cr -# Learn how to use AWS Cloud Map service discovery with custom attributes +# Learn how to use AWS Cloud Map service discovery with DNS queries and API calls @@ -9 +9 @@ PrerequisitesStep 1: Create a namespaceStep 2: Create a DynamoDB tableStep 3: Cr -The following tutorial demonstrates how you can use AWS Cloud Map service discovery with custom attributes that are discoverable using the AWS Cloud Map API. The tutorial walks you through creating and running client applications using AWS CloudShell. The applications use two Lambda functions to write data to a DynamoDB table and then read from the table. The Lambda functions and DynamoDB table are registered in AWS Cloud Map as service instances. The code in the client applications and Lambda functions uses AWS Cloud Map custom attributes to discover the resources needed to perform the job. +The following tutorial simulates a microservice architecture with two backend services. The first service will be discoverable using a DNS query. The second service will be discoverable using the AWS Cloud Map API only. @@ -11 +11 @@ The following tutorial demonstrates how you can use AWS Cloud Map service discov -###### Important +###### Note @@ -13 +13 @@ The following tutorial demonstrates how you can use AWS Cloud Map service discov -You will create AWS resources during the workshop which will incur a cost in your AWS account. It is recommended to clean-up the resources as soon as you finish the workshop to minimize the cost. +The resource details, like domain names and IP addresses, are for simulation purposes only. They can't be resolved over the internet. @@ -17 +17 @@ You will create AWS resources during the workshop which will incur a cost in you -Before you begin, complete the steps in [Set up to use AWS Cloud Map](./setting-up-cloud-map.html). +The following prerequisites must be met to complete the tutorial successfully. @@ -19,37 +19 @@ Before you begin, complete the steps in [Set up to use AWS Cloud Map](./setting- -## Step 1: Create an AWS Cloud Map namespace - -In this step, you create an AWS Cloud Map namespace. A namespace is a construct used to group services for an application. When you create the namespace, you specify how the resources will be discoverable. The resources created in the namespace created in this step will be discoverable with AWS Cloud Map API calls using custom attributes. - - 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). - - 2. Choose **Create namespace**. - - 3. For **Namespace name** , specify `cloudmap-tutorial`. - - 4. (Optional) For **Namespace description** , specify a description for what you intend to use the namespace for. - - 5. For **Instance discovery** , select **API calls**. - - 6. Leave the rest of the default values and choose **Create namespace**. - - - - -## Step 2: Create a DynamoDB table - -In this step, you create a DynamoDB table. The table is used to store and retrieve data for the sample application that you will create in the following steps. - -For information about how to create an DynamoDB, see [Step 1: Create a table in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html) in the _DynamoDB Developer Guide_ and use the following table to determine what options to specify. - -Option | Value ----|--- -Table name | cloudmap -Partition key | id - -Keep the default values for the rest of the settings and create the table. - -## Step 3: Create an AWS Cloud Map data service and register DynamoDB table as an instance - -In this step, you create a AWS Cloud Map service and then register the DynamoDB table created in the last step as a service instance. - - 1. Open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/) + * Before you begin, complete the steps in [Set up to use AWS Cloud Map](./setting-up-cloud-map.html). @@ -57 +21 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 2. From the list of namespaces, select the `cloudmap-tutorial` namespace and choose **View details**. + * If you have not yet installed the AWS Command Line Interface, follow the steps at [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to install it. @@ -59 +23 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 3. In the **Services** section, choose **Create service** and do the following. +The tutorial requires a command line terminal or shell to run commands. In Linux and macOS, use your preferred shell and package manager. @@ -61 +25 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 1. For **Service name** , enter `data-service`. +###### Note @@ -63 +27 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 2. Leave the rest of the default values and choose **Create service**. +In Windows, some Bash CLI commands that you commonly use with Lambda (such as `zip`) are not supported by the operating system's built-in terminals. To get a Windows-integrated version of Ubuntu and Bash, [install the Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install). @@ -65 +29 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 4. In the **Services** section, select the `data-service` service and choose **View details**. + * The tutorial requires a local environment with the `dig` DNS lookup utility command. For more information about the `dig` command, see [dig - DNS lookup utility](https://downloads.isc.org/isc/bind9/cur/9.19/doc/arm/html/manpages.html#dig-dns-lookup-utility). @@ -67 +30,0 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 5. In the **Service instances** section, choose **Register service instance**. @@ -69 +31,0 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 6. On the **Register service instance** page, do the following. @@ -71 +32,0 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 1. For **Instance type** , select **Identifying information for another resource**. @@ -73,8 +34 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB - 2. For **Service instance id** , specify `data-instance`. - - 3. In the **Custom attributes** section, specify the following key-value pair: **key** = `tablename`, **value** = `cloudmap`. - - - - -## Step 4: Create an AWS Lambda execution role +## Step 1: Create an AWS Cloud Map namespace @@ -82 +36 @@ In this step, you create a AWS Cloud Map service and then register the DynamoDB -In this step, you create an IAM role that the AWS Lambda function in the next step uses. You can name the IAM role `cloudmap-tutorial-role` and omit the permissions boundary because the role is only used for this tutorial, and you can delete it afterwards. +In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates a Route 53 hosted zone on your behalf with this same name. This gives you the ability to discover the service instances created in this namespace either using public DNS records or by using AWS Cloud Map API calls. @@ -84 +38 @@ In this step, you create an IAM role that the AWS Lambda function in the next st -###### To create the service role for Lambda (IAM console) + 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). @@ -86 +40 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). + 2. Choose **Create namespace**. @@ -88 +42 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 2. In the navigation pane of the IAM console, choose **Roles** , and then choose **Create role**. + 3. For **Namespace name** , specify `cloudmap-tutorial.com`. @@ -90 +44 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 3. For **Trusted entity type** , choose **AWS service**. +###### Note @@ -92 +46 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 4. For **Service or use case** , choose **Lambda** , and then choose the **Lambda** use case. +If you were going to use this in production, you'd want to ensure that you specified the name of a domain you owned or had access to. But for the purposes of this tuturial, it's not necessary for it to be an actual domain that's being used. @@ -94 +48 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 5. Choose **Next**. + 4. (Optional) For **Namespace description** , specify a description for what you intend to use the namespace for. @@ -96 +50 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 6. Search for, and select the box next to, the `PowerUserAccess` policy and then choose **Next**. + 5. For **Instance discovery** , select **API calls and public DNS queries**. @@ -98 +52 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 7. Choose **Next**. + 6. Leave the rest of the default values and choose **Create namespace**. @@ -100 +53,0 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 8. For **Role name** , specify `cloudmap-tutorial-role`. @@ -102 +54,0 @@ In this step, you create an IAM role that the AWS Lambda function in the next st - 9. Review the role, and then choose **Create role**. @@ -104,0 +57 @@ In this step, you create an IAM role that the AWS Lambda function in the next st +## Step 2: Create the AWS Cloud Map services @@ -105,0 +59 @@ In this step, you create an IAM role that the AWS Lambda function in the next st +In this step, you create two services. The first service will be discoverable using public DNS and API calls. The second service will be discoverable using API calls only. @@ -107 +61 @@ In this step, you create an IAM role that the AWS Lambda function in the next st -## Step 5: Create the Lambda function to write data + 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). @@ -109 +63 @@ In this step, you create an IAM role that the AWS Lambda function in the next st -In this step, you create a Lambda function authored from scratch that writes data to the DynamoDB table by using the AWS Cloud Map API to query the AWS Cloud Map service you created. + 2. In the left navigation pane, choose **Namespaces** to list the namespaces you've created. @@ -111 +65 @@ In this step, you create a Lambda function authored from scratch that writes dat -For information about creating a Lambda function, see [Create a Lambda function with the console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#getting-started-create-function) in the _AWS Lambda Developer Guide_ and use the following table to determine what options to specify or choose. + 3. From the list of namespaces, select the `cloudmap-tutorial.com` namespace and choose **View details**. @@ -113,7 +67 @@ For information about creating a Lambda function, see [Create a Lambda function -Option | Value ----|--- -Function name | writefunction -Runtime | Python 3.12 -Architecture | x86_64 -Permissions | Use an existing role -Existing role | cloudmap-tutorial-role + 4. In the **Services** section, choose **Create service** and do the following to create the first service. @@ -121 +69 @@ Existing role | cloudmap-tutorial-role -After you create the function, update the example code to reflect the following Python code, and then deploy the function. Note that you're specifying the `datatable` custom attribute you associated with the AWS Cloud Map service instance you created for the DynamoDB table. The function generates a key that is a random number between 1 and 100 and associates it with a value that is passed to the function when it is called. + 1. For **Service name** , enter `public-service`. The service name will be applied to the DNS records that AWS Cloud Map creates. The format that is used is ``<service-name>`.`<namespace-name>``. @@ -122,0 +71 @@ After you create the function, update the example code to reflect the following + 2. For **Service Discovery Configuration** , select **API and DNS**. @@ -124,3 +73 @@ After you create the function, update the example code to reflect the following - import json - import boto3 - import random + 3. In the **DNS configuration** section, for **Routing policy** , select **Multivalue answer routing**. @@ -128 +75 @@ After you create the function, update the example code to reflect the following - def lambda_handler(event, context): +###### Note @@ -130 +77 @@ After you create the function, update the example code to reflect the following - serviceclient = boto3.client('servicediscovery') +The console will translate this to **MULTIVALUE** after it is selected. For more information about available routing options, see [Choosing a routing policy](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) in the _Route 53 Developer Guide_. @@ -132,3 +79 @@ After you create the function, update the example code to reflect the following - response = serviceclient.discover_instances( - NamespaceName='cloudmap-tutorial', - ServiceName='data-service') + 4. Leave the rest of the default values and choose **Create service** which will return you to the namespace details page. @@ -136 +81 @@ After you create the function, update the example code to reflect the following - tablename = response["Instances"][0]["Attributes"]["tablename"] + 5. In the **Services** section, choose **Create service** and do the following to create the second service. @@ -138 +83 @@ After you create the function, update the example code to reflect the following - dynamodbclient = boto3.resource('dynamodb') + 1. For **Service name** , enter `backend-service`. @@ -140 +85 @@ After you create the function, update the example code to reflect the following - table = dynamodbclient.Table(tablename) + 2. For **Service Discovery Configuration** , select **API only**. @@ -142,2 +87 @@ After you create the function, update the example code to reflect the following - response = table.put_item( - Item={ 'id': str(random.randint(1,100)), 'todo': event }) + 3. Leave the rest of the default values and choose **Create service**. @@ -145,4 +88,0 @@ After you create the function, update the example code to reflect the following - return { - 'statusCode': 200, - 'body': json.dumps(response) - } @@ -150 +89,0 @@ After you create the function, update the example code to reflect the following -After deploying the function, to avoid timeout errors, update the function timeout to 5 seconds. For more information, see [Configure Lambda function timeout](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html) in the _AWS Lambda Developer Guide_. @@ -152 +90,0 @@ After deploying the function, to avoid timeout errors, update the function timeo -## Step 6: Create an AWS Cloud Map app service and register the Lambda write function as an instance @@ -154 +92 @@ After deploying the function, to avoid timeout errors, update the function timeo -In this step, you create an AWS Cloud Map service and then register the Lambda write function as a service instance. +## Step 3: Register the AWS Cloud Map service instances @@ -156 +94 @@ In this step, you create an AWS Cloud Map service and then register the Lambda w - 1. Open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/) +In this step, you create two service instances, one for each service in our namespace. @@ -158 +96 @@ In this step, you create an AWS Cloud Map service and then register the Lambda w - 2. In the left navigation, choose **Namespaces**. + 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). @@ -160 +98 @@ In this step, you create an AWS Cloud Map service and then register the Lambda w - 3. From the list of namespaces, select the `cloudmap-tutorial` namespace and choose **View details**. + 2. From the list of namespaces, select the namespace you created in step 1 and choose **View details**.