Learn how to use Amazon Cloud Map service discovery with custom attributes - Amazon Cloud Map
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
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Learn how to use Amazon Cloud Map service discovery with custom attributes

This tutorial demonstrates how you can use Amazon Cloud Map service discovery with custom attributes that are discoverable using the Amazon Cloud Map API. This tutorial walks you through creating and running client applications using Amazon 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 Amazon Cloud Map as service instances. The code in the client applications and Lambda functions uses Amazon Cloud Map custom attributes to discover the resources needed to perform the job.

Important

You will create Amazon resources during the workshop which will incur a cost in your Amazon account. It is recommended to clean-up the resources as soon as you finish the workshop to minimize the cost.

Prerequisites

Before you begin, complete the steps in Set up to use Amazon Cloud Map.

Step 1: Create an Amazon Cloud Map namespace

In this step, you create an Amazon 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. For this tutorial, the resources created in this namespace will be discoverable with Amazon Cloud Map API calls using custom attributes. You will learn about this more in a later step.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/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 which is used to store and retrieve data for the sample application created later in this tutorial.

For information about how to create an DynamoDB, see Step 1: Create a table in DynamoDB 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 Amazon Cloud Map data service and register DynamoDB table as an instance

In this step, you create a Amazon Cloud Map service and then register the DynamoDB table created in the last step as a service instance.

  1. Open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/

  2. From the list of namespaces, select the cloudmap-tutorial namespace and choose View details.

  3. In the Services section, choose Create service and do the following.

    1. For Service name, enter data-service.

    2. Leave the rest of the default values and choose Create service.

  4. In the Services section, select the data-service service and choose View details.

  5. In the Service instances section, choose Register service instance.

  6. On the Register service instance page, do the following.

    1. For Instance type, select Identifying information for another resource.

    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 Amazon Lambda execution role

In this step, you create an IAM role that the Amazon Lambda function we create in the next step uses. You can name the role cloudmap-tutorial-role and omit the permissions boundary as this IAM role is only used for this tutorial and you can delete it afterwards.

To create the service role for Lambda (IAM console)

  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane of the IAM console, choose Roles, and then choose Create role.

  3. For Trusted entity type, choose Amazon Web Services service.

  4. For Service or use case, choose Lambda, and then choose the Lambda use case.

  5. Choose Next.

  6. Search for, and select the box next to, the PowerUserAccess policy and then choose Next.

  7. Choose Next.

  8. For Role name, specify cloudmap-tutorial-role.

  9. Review the role, and then choose Create role.

Step 5: Create the Lambda function to write data

In this step, you create a Lambda function authored from scratch that writes data to the DynamoDB table by using the Amazon Cloud Map API to query the Amazon Cloud Map service you created.

For information about creating a Lambda function, see Create a Lambda function with the console in the Amazon Lambda Developer Guide and use the following table to determine what options to specify or choose.

Option Value

Function name

 writefunction
Runtime

Python 3.12
Architecture

x86_64
Permissions

Use an existing role
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 Amazon 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.

import json
import boto3
import random

def lambda_handler(event, context):
       
    serviceclient = boto3.client('servicediscovery')
    
    response = serviceclient.discover_instances(
        NamespaceName='cloudmap-tutorial',
        ServiceName='data-service')
       
    tablename = response["Instances"][0]["Attributes"]["tablename"]
       
    dynamodbclient = boto3.resource('dynamodb')
       
    table = dynamodbclient.Table(tablename)
       
    response = table.put_item(
        Item={ 'id': str(random.randint(1,100)), 'todo': event })
       
    return {
        'statusCode': 200,
        'body': json.dumps(response)
    }

After deploying the function, to avoid timeout errors, update the function timeout to 5 seconds. For more information, see Configure Lambda function timeout in the Amazon Lambda Developer Guide.

Step 6: Create an Amazon Cloud Map app service and register the Lambda write function as an instance

In this step, you create an Amazon Cloud Map service and then register the Lambda write function as a service instance.

  1. Open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/

  2. In the left navigation, choose Namespaces.

  3. From the list of namespaces, select the cloudmap-tutorial namespace and choose View details.

  4. In the Services section, choose Create service and do the following.

    1. For Service name, enter app-service.

    2. Leave the rest of the default values and choose Create service.

  5. In the Services section, select the app-service service and choose View details.

  6. In the Service instances section, choose Register service instance.

  7. On the Register service instance page, do the following.

    1. For Instance type, select Identifying information for another resource.

    2. For Service instance id, specify write-instance.

    3. In the Custom attributes section, specify the following key-value pairs.

      • key = action, value = write

      • key = functionname, value = writefunction

Step 7: Create the Lambda function to read data

In this step, you create a Lambda function authored from scratch that writes data to the DynamoDB table you created.

For information about creating a Lambda function, see Create a Lambda function with the console in the Amazon Lambda Developer Guide and use the following table to determine what options to specify or choose.

Option Value

Function name

 readfunction
Runtime

Python 3.12
Architecture

x86_64
Permissions

Use an existing role
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. The function scans the table amd returns all items.

import json
import boto3

def lambda_handler(event, context):
    serviceclient = boto3.client('servicediscovery')

    response = serviceclient.discover_instances(NamespaceName='cloudmap-tutorial', ServiceName='data-service')
       
    tablename = response["Instances"][0]["Attributes"]["tablename"]
       
    dynamodbclient = boto3.resource('dynamodb')
       
    table = dynamodbclient.Table(tablename)
       
    response = table.scan(Select='ALL_ATTRIBUTES')

    return {
        'statusCode': 200,
        'body': json.dumps(response)
    }

After deploying the function, to avoid timeout errors, update the function timeout to 5 seconds. For more information, see Configure Lambda function timeout in the Amazon Lambda Developer Guide.

Step 8: Register the Lambda read function as an Amazon Cloud Map service instance

In this step, you register the Lambda read function as a service instance in the app-service service you previously created.

  1. Open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/

  2. In the left navigation, choose Namespaces.

  3. From the list of namespaces, select the cloudmap-tutorial namespace and choose View details.

  4. In the Services section, select the app-service service and choose View details.

  5. In the Service instances section, choose Register service instance.

  6. On the Register service instance page, do the following.

    1. For Instance type, select Identifying information for another resource.

    2. For Service instance id, specify read-instance.

    3. In the Custom attributes section, specify the following key-value pairs.

      • key = action, value = read

      • key = functionname, value = readfunction

Step 9: Create and run read and write clients on Amazon CloudShell

You can create and run client applications in Amazon CloudShell that use code to discover the services you configured in Amazon Cloud Map and make calls to these services.

  1. Open the Amazon CloudShell console at https://console.amazonaws.cn/cloudshell/

  2. Use the following command to create a file called writefunction.py.

    vim writeclient.py

  3. In the writeclient.py file, enter insert mode by pressing the i button. Then, copy and paste the following code. This code discovers the Lambda function to write data by searching for the custom attribute name=writeservice in the app-service service. The name of the Lambda function responsible for writing data to the DynamoDB table is returned. Then the Lambda function is invoked, passing a sample payload that is written to the table as a value.

    import boto3

serviceclient = boto3.client('servicediscovery')

response = serviceclient.discover_instances(NamespaceName='cloudmap-tutorial', ServiceName='app-service', QueryParameters={ 'action': 'write' })

functionname = response["Instances"][0]["Attributes"]["functionname"]

lambdaclient = boto3.client('lambda')

resp = lambdaclient.invoke(FunctionName=functionname, Payload='"This is a test data"')

print(resp["Payload"].read())

  4. Press the escape key, type :wq, and press the enter key to save the file and exit.

  5. Use the following command to run the Python code.

    python3 writeclient.py

    The output should be a 200 response, similar to the following.

    b'{"statusCode": 200, "body": "{\\"ResponseMetadata\\": {\\"RequestId\\": \\"Q0M038IT0BPBVBJK8OCKK6I6M7VV4KQNSO5AEMVJF66Q9ASUAAJG\\", \\"HTTPStatusCode\\": 200, \\"HTTPHeaders\\": {\\"server\\": \\"Server\\", \\"date\\": \\"Wed, 06 Mar 2024 22:46:09 GMT\\", \\"content-type\\": \\"application/x-amz-json-1.0\\", \\"content-length\\": \\"2\\", \\"connection\\": \\"keep-alive\\", \\"x-amzn-requestid\\": \\"Q0M038IT0BPBVBJK8OCKK6I6M7VV4KQNSO5AEMVJF66Q9ASUAAJG\\", \\"x-amz-crc32\\": \\"2745614147\\"}, \\"RetryAttempts\\": 0}}"}'

  6. To verify the write was successful in the previous step, create a read client.

    1. Use the following command to create a file called readfunction.py.

      vim readclient.py

    2. In the readclient.py file, press the i button to enter insert mode. Then, copy and paste the following code. This code scans the table and will return the value that you wrote to the table in the previous step.

      import boto3

serviceclient = boto3.client('servicediscovery')

response = serviceclient.discover_instances(NamespaceName='cloudmap-tutorial', ServiceName='app-service', QueryParameters={ 'action': 'read' })

functionname = response["Instances"][0]["Attributes"]["functionname"]

lambdaclient = boto3.client('lambda')

resp = lambdaclient.invoke(FunctionName=functionname, InvocationType='RequestResponse')

print(resp["Payload"].read())

    3. Press the escape key, type :wq, and press the enter key to save the file and exit.

    4. Use the following command to run the Python code.

      python3 readclient.py

      The output should look similar to the following, listing the value written to the table by running writefunction.py and the random key generated in the Lambda write function.

        b'{"statusCode": 200, "body": "{\\"Items\\": [{\\"id\\": \\"45\\", \\"todo\\": \\"This is a test data\\"}], \\"Count\\": 1, \\"ScannedCount\\": 1, \\"ResponseMetadata\\": {\\"RequestId\\": \\"9JF8J6SFQCKR6IDT5JG5NOM3CNVV4KQNSO5AEMVJF66Q9ASUAAJG\\", \\"HTTPStatusCode\\": 200, \\"HTTPHeaders\\": {\\"server\\": \\"Server\\", \\"date\\": \\"Thu, 25 Jul 2024 20:43:33 GMT\\", \\"content-type\\": \\"application/x-amz-json-1.0\\", \\"content-length\\": \\"91\\", \\"connection\\": \\"keep-alive\\", \\"x-amzn-requestid\\": \\"9JF8J6SFQCKR6IDT5JG5NOM3CNVV4KQNSO5AEMVJF66Q9ASUAAJG\\", \\"x-amz-crc32\\": \\"1163081893\\"}, \\"RetryAttempts\\": 0}}"}'

Step 10: Clean up the resources

After you have completed the tutorial, delete the resources to avoid incurring additional charges. Amazon Cloud Map requires that you clean them up in reverse order, the service instances first, then the services, and finally the namespace. The following steps walk you through cleaning up the Amazon Cloud Map resources used in this tutorial.

To delete the Amazon Cloud Map resources

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/.

  2. From the list of namespaces, select the cloudmap-tutorial namespace and choose View details.

  3. On the namespace details page, from the list of services, select the data-service service and choose View details.

  4. In the Service instances section, select the data-instance instance and choose Deregister.

  5. Using the breadcrumb at the top of the page, select cloudmap-tutorial.com to navigate back to the namespace detail page.

  6. On the namespace details page, from the list of services, select the data-service service and choose Delete.

  7. Repeat steps 3-6 for the app-service service and the write-instance and read-instance service instances.

  8. In the left navigation, choose Namespaces.

  9. Select the cloudmap-tutorial namespace and choose Delete.

The following table lists procedures that you can use to delete the other resources used in the tutorial.

Resource Steps

DynamoDB table

 Step 6: (Optional) Delete your DynamoDB table to clean up resources in the Amazon DynamoDB Developer Guide
Lambda functions and associated IAM execution role

Clean up in the Amazon Lambda Developer Guide