AWS cloud-map documentation change
Summary
Replaced DNS-based service discovery with API-driven custom attribute discovery and removed public DNS configuration steps.
Security assessment
The shift from public DNS to API-driven discovery reduces exposure of service metadata publicly, but the diff does not explicitly state this as a security improvement. This is a functional change rather than a direct response to a documented vulnerability.
Diff
diff --git a/cloud-map/latest/dg/tutorial-microservices.md b/cloud-map/latest/dg/tutorial-microservices.md index e69488d56..aae6c0d73 100644 --- a//cloud-map/latest/dg/tutorial-microservices.md +++ b//cloud-map/latest/dg/tutorial-microservices.md @@ -5 +5 @@ -PrerequisitesStep 1: Create a namespaceStep 2: Create the servicesStep 3: Create the service instancesStep 4: Discover the service instancesStep 5: Clean up +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 @@ -7 +7 @@ PrerequisitesStep 1: Create a namespaceStep 2: Create the servicesStep 3: Create -# Learn how to use AWS Cloud Map service discovery with DNS queries and API calls +# Learn how to use AWS Cloud Map service discovery with custom attributes @@ -9 +9 @@ PrerequisitesStep 1: Create a namespaceStep 2: Create the servicesStep 3: Create -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. +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. @@ -11 +11 @@ The following tutorial simulates a microservice architecture with two backend se -###### Note +###### Important @@ -13 +13 @@ The following tutorial simulates a microservice architecture with two backend se -The resource details, like domain names and IP addresses, are for simulation purposes only. They can't be resolved over the internet. +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. @@ -17 +17 @@ The resource details, like domain names and IP addresses, are for simulation pur -The following prerequisites must be met to complete the tutorial successfully. +Before you begin, complete the steps in [Set up to use AWS Cloud Map](./setting-up-cloud-map.html). @@ -19 +19 @@ The following prerequisites must be met to complete the tutorial successfully. - * Before you begin, complete the steps in [Set up to use AWS Cloud Map](./setting-up-cloud-map.html). +## Step 1: Create an AWS Cloud Map namespace @@ -21 +21 @@ The following prerequisites must be met to complete the tutorial successfully. - * 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. +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. @@ -23 +23 @@ The following prerequisites must be met to complete the tutorial successfully. -The tutorial requires a command line terminal or shell to run commands. In Linux and macOS, use your preferred shell and package manager. + 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/). @@ -25 +25 @@ The tutorial requires a command line terminal or shell to run commands. In Linux -###### Note + 2. Choose **Create namespace**. @@ -27 +27 @@ The tutorial requires a command line terminal or shell to run commands. In Linux -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). + 3. For **Namespace name** , specify `cloudmap-tutorial`. @@ -29 +29 @@ In Windows, some Bash CLI commands that you commonly use with Lambda (such as `z - * 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). + 4. (Optional) For **Namespace description** , specify a description for what you intend to use the namespace for. @@ -30,0 +31 @@ In Windows, some Bash CLI commands that you commonly use with Lambda (such as `z + 5. For **Instance discovery** , select **API calls**. @@ -31,0 +33 @@ In Windows, some Bash CLI commands that you commonly use with Lambda (such as `z + 6. Leave the rest of the default values and choose **Create namespace**. @@ -34 +35,0 @@ In Windows, some Bash CLI commands that you commonly use with Lambda (such as `z -## Step 1: Create an AWS Cloud Map namespace @@ -36 +36,0 @@ In Windows, some Bash CLI commands that you commonly use with Lambda (such as `z -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. @@ -38 +38 @@ In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates - 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/). +## Step 2: Create a DynamoDB table @@ -40 +40 @@ In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates - 2. Choose **Create namespace**. +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. @@ -42 +42 @@ In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates - 3. For **Namespace name** , specify `cloudmap-tutorial.com`. +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. @@ -44 +44,4 @@ In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates -###### Note +Option | Value +---|--- +Table name | cloudmap +Partition key | id @@ -46 +49 @@ In this step, you create a public AWS Cloud Map namespace. AWS Cloud Map creates -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. +Keep the default values for the rest of the settings and create the table. @@ -48 +51 @@ If you were going to use this in production, you'd want to ensure that you speci - 4. (Optional) For **Namespace description** , specify a description for what you intend to use the namespace for. +## Step 3: Create an AWS Cloud Map data service and register DynamoDB table as an instance @@ -50 +53 @@ If you were going to use this in production, you'd want to ensure that you speci - 5. For **Instance discovery** , select **API calls and public DNS queries**. +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. @@ -52 +55 @@ If you were going to use this in production, you'd want to ensure that you speci - 6. Leave the rest of the default values and choose **Create namespace**. + 1. Open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/) @@ -53,0 +57 @@ If you were going to use this in production, you'd want to ensure that you speci + 2. From the list of namespaces, select the `cloudmap-tutorial` namespace and choose **View details**. @@ -54,0 +59 @@ If you were going to use this in production, you'd want to ensure that you speci + 3. In the **Services** section, choose **Create service** and do the following. @@ -55,0 +61 @@ If you were going to use this in production, you'd want to ensure that you speci + 1. For **Service name** , enter `data-service`. @@ -57 +63 @@ If you were going to use this in production, you'd want to ensure that you speci -## Step 2: Create the AWS Cloud Map services + 2. Leave the rest of the default values and choose **Create service**. @@ -59 +65 @@ If you were going to use this in production, you'd want to ensure that you speci -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. + 4. In the **Services** section, select the `data-service` service and choose **View details**. @@ -61 +67 @@ In this step, you create two services. The first service will be discoverable us - 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/). + 5. In the **Service instances** section, choose **Register service instance**. @@ -63 +69 @@ In this step, you create two services. The first service will be discoverable us - 2. In the left navigation pane, choose **Namespaces** to list the namespaces you've created. + 6. On the **Register service instance** page, do the following. @@ -65 +71 @@ In this step, you create two services. The first service will be discoverable us - 3. From the list of namespaces, select the `cloudmap-tutorial.com` namespace and choose **View details**. + 1. For **Instance type** , select **Identifying information for another resource**. @@ -67 +73 @@ In this step, you create two services. The first service will be discoverable us - 4. In the **Services** section, choose **Create service** and do the following to create the first service. + 2. For **Service instance id** , specify `data-instance`. @@ -69 +75 @@ In this step, you create two services. The first service will be discoverable us - 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>``. + 3. In the **Custom attributes** section, specify the following key-value pair: **key** = `tablename`, **value** = `cloudmap`. @@ -71 +76,0 @@ In this step, you create two services. The first service will be discoverable us - 2. For **Service Discovery Configuration** , select **API and DNS**. @@ -73 +77,0 @@ In this step, you create two services. The first service will be discoverable us - 3. In the **DNS configuration** section, for **Routing policy** , select **Multivalue answer routing**. @@ -75 +78,0 @@ In this step, you create two services. The first service will be discoverable us -###### Note @@ -77 +80 @@ In this step, you create two services. The first service will be discoverable us -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_. +## Step 4: Create an AWS Lambda execution role @@ -79 +82 @@ The console will translate this to **MULTIVALUE** after it is selected. For more - 4. Leave the rest of the default values and choose **Create service** which will return you to the namespace details page. +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. @@ -81 +84 @@ The console will translate this to **MULTIVALUE** after it is selected. For more - 5. In the **Services** section, choose **Create service** and do the following to create the second service. +###### To create the service role for Lambda (IAM console) @@ -83 +86 @@ The console will translate this to **MULTIVALUE** after it is selected. For more - 1. For **Service name** , enter `backend-service`. + 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/). @@ -85 +88 @@ The console will translate this to **MULTIVALUE** after it is selected. For more - 2. For **Service Discovery Configuration** , select **API only**. + 2. In the navigation pane of the IAM console, choose **Roles** , and then choose **Create role**. @@ -87 +90 @@ The console will translate this to **MULTIVALUE** after it is selected. For more - 3. Leave the rest of the default values and choose **Create service**. + 3. For **Trusted entity type** , choose **AWS service**. @@ -88,0 +92 @@ The console will translate this to **MULTIVALUE** after it is selected. For more + 4. For **Service or use case** , choose **Lambda** , and then choose the **Lambda** use case. @@ -89,0 +94 @@ The console will translate this to **MULTIVALUE** after it is selected. For more + 5. Choose **Next**. @@ -90,0 +96 @@ The console will translate this to **MULTIVALUE** after it is selected. For more + 6. Search for, and select the box next to, the `PowerUserAccess` policy and then choose **Next**. @@ -92 +98 @@ The console will translate this to **MULTIVALUE** after it is selected. For more -## Step 3: Register the AWS Cloud Map service instances + 7. Choose **Next**. @@ -94 +100 @@ The console will translate this to **MULTIVALUE** after it is selected. For more -In this step, you create two service instances, one for each service in our namespace. + 8. For **Role name** , specify `cloudmap-tutorial-role`. @@ -96 +102 @@ In this step, you create two service instances, one for each service in our name - 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/). + 9. Review the role, and then choose **Create role**. @@ -98 +103,0 @@ In this step, you create two service instances, one for each service in our name - 2. From the list of namespaces, select the namespace you created in step 1 and choose **View details**. @@ -100 +104,0 @@ In this step, you create two service instances, one for each service in our name - 3. On the namespace details page, from the list of services, select the `public-service` service and choose **View details**. @@ -102 +105,0 @@ In this step, you create two service instances, one for each service in our name - 4. In the **Service instances** section, choose **Register service instance** and do the following to create the first service instance. @@ -104 +107 @@ In this step, you create two service instances, one for each service in our name - 1. For **Service instance ID** , specify `first`. +## Step 5: Create the Lambda function to write data @@ -106 +109 @@ In this step, you create two service instances, one for each service in our name - 2. For **IPv4 address** , specify `192.168.2.1`. +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. @@ -108 +111 @@ In this step, you create two service instances, one for each service in our name - 3. Leave the rest of the default values and choose **Register service instance**. +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. @@ -110 +113,7 @@ In this step, you create two service instances, one for each service in our name - 5. Using the breadcrumb at the top of the page, select **cloudmap-tutorial.com** to navigate back to the namespace detail page. +Option | Value +---|--- +Function name | writefunction +Runtime | Python 3.12 +Architecture | x86_64 +Permissions | Use an existing role +Existing role | cloudmap-tutorial-role @@ -112 +121 @@ In this step, you create two service instances, one for each service in our name - 6. On the namespace details page, from the list of services, select the **backend-service** service and choose **View details**. +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. @@ -114 +122,0 @@ In this step, you create two service instances, one for each service in our name - 7. In the **Service instances** section, choose **Register service instance** and do the following to create the second service instance. @@ -116 +124,3 @@ In this step, you create two service instances, one for each service in our name - 1. For **Service instance ID** , specify `second` to indicate that this is the second service instance. + import json + import boto3 + import random @@ -118 +128 @@ In this step, you create two service instances, one for each service in our name - 2. For **Instance type** , select **Identifying information for another resource**. + def lambda_handler(event, context): @@ -120 +130 @@ In this step, you create two service instances, one for each service in our name - 3. For **Custom attributes** , add a key-value pair with `service-name` as the key and `backend` as the value. + serviceclient = boto3.client('servicediscovery') @@ -122 +132,3 @@ In this step, you create two service instances, one for each service in our name - 4. Choose **Register service instance**. + response = serviceclient.discover_instances( + NamespaceName='cloudmap-tutorial', + ServiceName='data-service') @@ -123,0 +136 @@ In this step, you create two service instances, one for each service in our name + tablename = response["Instances"][0]["Attributes"]["tablename"] @@ -124,0 +138 @@ In this step, you create two service instances, one for each service in our name + dynamodbclient = boto3.resource('dynamodb') @@ -125,0 +140 @@ In this step, you create two service instances, one for each service in our name + table = dynamodbclient.Table(tablename) @@ -127 +142,2 @@ In this step, you create two service instances, one for each service in our name -## Step 4: Discover the AWS Cloud Map service instances + response = table.put_item( + Item={ 'id': str(random.randint(1,100)), 'todo': event }) @@ -129 +145,4 @@ In this step, you create two service instances, one for each service in our name -Now that the AWS Cloud Map namespace, services, and service instances are created, you can verify everything is working by discovering the instances. Use the `dig` command to verify the public DNS settings and the AWS Cloud Map API to verify the backend service. 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). + return { + 'statusCode': 200,