# AWS Cloud Map service instances A service instance contains information about how to locate a resource, such as a web server, for an application. After you register instances, you locate them by using DNS queries or the AWS Cloud Map [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) API action. The resources you can register include, but aren't limited to, the following: + Amazon EC2 instances + Amazon DynamoDB tables + Amazon S3 buckets + Amazon Simple Queue Service (Amazon SQS) queues + APIs deployed on top of Amazon API Gateway You can specify attribute values for services instances, and clients can use these attributes to filter the resources that AWS Cloud Map returns. For example, an application can request resources in a particular deployment stage, like BETA or PROD. You can also use attributes for versioning. The following procedures describe how you can register resources in your application as service instances, view a list of registered instances in a service, edit certain instance parameters, and deregister an instance. **Topics** + [Registering a resource as an AWS Cloud Map service instance](registering-instances.md) + [Listing AWS Cloud Map service instances](listing-instances.md) + [Updating an AWS Cloud Map service instance](updating-instances.md) + [Deregistering an AWS Cloud Map service instance](deregistering-instances.md) # Registering a resource as an AWS Cloud Map service instance You can register your application's resources as instances in a AWS Cloud Map service. For example, assume you've created a service called `users` for all application resources that manage user data. You can then register a DynamoDB table that's used to store user data as an instance in this service. **Note** The following features are not available on the AWS Cloud Map console: When you register a service instance using the console, you can't create an alias record that routes traffic to an Elastic Load Balancing (ELB) load balancer. When you register an instance, you must include the `AWS_ALIAS_DNS_NAME` attribute. For more information, see [RegisterInstance](https://docs.aws.amazon.com/cloud-map/latest/api/API_RegisterInstance.html) in the *AWS Cloud Map API Reference*. If you register an instance using a service that includes a custom health check, you can't specify the initial status for the custom health check. By default, the initial status of a custom health checks is **Healthy**. If you want the initial health status to be **Unhealthy**, register the instance programmatically and include the `AWS_INIT_HEALTH_STATUS` attribute. For more information, see [RegisterInstance](https://docs.aws.amazon.com/cloud-map/latest/api/API_RegisterInstance.html) in the *AWS Cloud Map API Reference*. To register an instance in a service, follow these steps. ------ #### [ AWS Management 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/). 1. In the navigation pane, choose **Namespaces**. 1. On the **Namespaces** page, choose the namespace that contains the service that you want to use as a template for registering a service instance. 1. On the **Namespace: *namespace-name*** page, choose the service that you want to use. 1. On the **Service: *service-name*** page, choose **Register service instance**. 1. On the **Register service instance** page, choose an **Instance type**. Depending on the namespace instance discovery configuration, you can choose to specify an IP address, an Amazon EC2 instance ID, or other identifying information for a resource that doesn't have an IP address. **Note** You can choose **EC2 instance** only in HTTP namespaces. 1. For **Service instance ID**, provide an identifier associated with the service instance. **Note** If you want to update an existing instance, provide the identifier associated with the instance you want to update. Then, use the next steps to update values and reregister the instance. 1. Based on your choice of **Instance type**, perform the following steps. **Important** You can't use the `AWS_` prefix (not case sensitive) in a key when you specify a custom attribute. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloud-map/latest/dg/registering-instances.html) 1. Choose **Register service instance**. ------ #### [ AWS CLI ] + When you submit a `RegisterInstance` request: + For each DNS record that you define in the service that's specified by `ServiceId`, a record is created or updated in the hosted zone that's associated with the corresponding namespace. + If the service includes `HealthCheckConfig`, a health check is created based on the settings in the health check configuration. + Any health checks are associated with each of the new or updated records. Register a service instance with the `[register-instance](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/register-instance.html)` command (replace the *red* values with your own). ``` aws servicediscovery register-instance \ --service-id srv-xxxxxxxxx \ --instance-id myservice-xx \ --attributes=AWS_INSTANCE_IPV4=172.2.1.3,AWS_INSTANCE_PORT=808 ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. When you submit a `RegisterInstance` request: + For each DNS record that you define in the service that's specified by `ServiceId`, a record is created or updated in the hosted zone that's associated with the corresponding namespace. + If the service includes `HealthCheckConfig`, a health check is created based on the settings in the health check configuration. + Any health checks are associated with each of the new or updated records. Register a service instance with `register_instance()` (replace the *red* values with your own). ``` response = client.register_instance( Attributes={ 'AWS_INSTANCE_IPV4': '172.2.1.3', 'AWS_INSTANCE_PORT': '808', }, InstanceId='myservice-xx', ServiceId='srv-xxxxxxxxx', ) # If you want to see the response print(response) ``` Example response output ``` { 'OperationId': '4yejorelbukcjzpnr6tlmrghsjwpngf4-k95yg2u7', 'ResponseMetadata': { '...': '...', }, } ``` ------ # Listing AWS Cloud Map service instances To view a list of the service instances that you registered using a service, perform the following procedure. ------ #### [ AWS Management 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/). 1. In the navigation pane, choose **Namespaces**. 1. Choose the name of the namespace that contains the service for which you want to list service instances. 1. Choose the name of the service that you used to create the service instances. You'll see a list of instances under **Service instances**. You can enter the instance ID in the search field to list a specific instance. The **Created by** field shows the ID of the AWS account that registered the instance. **Note** If the namespace in which the instance is registered is a shared namespace, the AWS account ID under **Created by** may not be the same as your account ID. For more information about shared namespaces, see [Shared AWS Cloud Map namespaces](sharing-namespaces.md). ------ #### [ AWS CLI ] + List service instances with the `[list-instances](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/list-instances.html)` command (replace the *red* value with your own). ``` aws servicediscovery list-instances --service-id srv-xxxxxxxxx ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. List service instances with `list_instances()` (replace the *red* value with your own). ``` response = client.list_instances( ServiceId='srv-xxxxxxxxx', ) # If you want to see the response print(response) ``` Example response output ``` { 'Instances': [ { 'Attributes': { 'AWS_INSTANCE_IPV4': '172.2.1.3', 'AWS_INSTANCE_PORT': '808', }, 'Id': 'i-xxxxxxxxxxxxxxxxx', }, ], 'ResponseMetadata': { '...': '...', }, } ``` ------ # Updating an AWS Cloud Map service instance You can update service instances in two ways, depending on which values you want to update: + **Update any values**: If you want to update any of the values that you specified for a service instance when you registered it, including custom attributes, you need to reregister the service instance and respecify all values. Follow the steps in [Registering a resource as an AWS Cloud Map service instance](registering-instances.md), specifying the instance ID of the existing service instance for **Service instance ID**. Alternatively, you can use the [https://docs.aws.amazon.com/cloud-map/latest/api/API_RegisterInstance.html](https://docs.aws.amazon.com/cloud-map/latest/api/API_RegisterInstance.html) API. You can specify the ID of the existing instance and service using the `InstanceId` and `ServiceId` parameters and respecify other values. + **Update only custom attributes**: If you want to update only the custom attributes for a service instance, you don't need to reregister the instance. You can update only those values. See [Updating the custom attributes for a service instance](#updating-instance-attributes-procedure). ## Updating the custom attributes for a service instance **To update only custom attributes for a service instance** 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/). 1. In the navigation pane, choose **Namespaces**. 1. On the **Namespaces** page, choose the namespace that contains the service that you originally used to register the service instance. 1. On the **Namespace: *namespace-name*** page, choose the service that you used to register the service instance. 1. On the **Service: *service-name*** page, choose the name of the service instance that you want to update. 1. In the **Custom attributes** section, choose **Edit**. 1. On the **Edit service instance: *instance-name*** page, add, remove, or update custom attributes. You can update both keys and values for existing attributes. 1. Choose **Update service instance**. # Deregistering an AWS Cloud Map service instance Before you can delete a service, you must deregister all service instances that were registered using the service. To deregister a service instance, perform the following procedure. ------ #### [ AWS Management 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/). 1. In the navigation pane, choose **Namespaces**. 1. Choose the option for the namespace that contains the service instance that you want to deregister. 1. On the **Namespace: *namespace-name*** page, choose the service you used to register the service instance. 1. On the **Service: *service-name*** page, choose the service instance that you want to deregister. 1. Choose **Deregister**. 1. Confirm that you want to deregister the service instance. ------ #### [ AWS CLI ] + Deregister a service instance with the `[deregister-instance](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/deregister-instance.html)` command (replace the *red* values with your own). This command deletes the Amazon Route 53 DNS records and any health checks that AWS Cloud Map created for the specified instance. ``` aws servicediscovery deregister-instance \ --service-id srv-xxxxxxxxx \ --instance-id myservice-53 ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. Deregister a service instance with `deregister-instance()` (replace the *red* values with your own). This command deletes the Amazon Route 53 DNS records and any health checks that AWS Cloud Map created for the specified instance. ``` response = client.deregister_instance( InstanceId='myservice-53', ServiceId='srv-xxxxxxxxx', ) # If you want to see the response print(response) ``` Example response output ``` { 'OperationId': '4yejorelbukcjzpnr6tlmrghsjwpngf4-k98rnaiq', 'ResponseMetadata': { '...': '...', }, } ``` ------