AWS Cloud Map

(1)

AWS Cloud Map

API Reference

API Version 2017-03-14

(2)

AWS Cloud Map: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS Cloud Map is a fully managed service that you can use to create and maintain a map of the backend services and resources that your applications depend on. Here's how AWS Cloud Map works:

1. You create a namespace that identiﬁes the name that you want to use to locate your resources and also speciﬁes how you want to locate resources: using AWS Cloud Map DiscoverInstances API calls, DNS queries in a VPC, or public DNS queries. Typically, a namespace contains all the services for an application, such as a billing application.

2. You create an AWS Cloud Map service for each type of resource for which you want to use AWS Cloud Map to locate endpoints. For example, you might create services for web servers and database servers.

A service is a template that AWS Cloud Map uses when your application adds another resource, such as another web server. If you chose to locate resources using DNS when you created the namespace, a service contains information about the types of records that you want to use to locate the web server.

A service also indicates whether you want to check the health of the resource and, if so, whether you want to use Route 53 health checks or a third-party health checker.

3. When your application adds a resource, it can call the AWS Cloud Map RegisterInstance API action, which creates a service instance. The service instance contains information about how your application can locate the resource, whether using DNS or using the AWS Cloud Map DiscoverInstances API action.

4. When your application needs to connect to a resource, it calls DiscoverInstances and speciﬁes the namespace and service that are associated with the resource. AWS Cloud Map returns information about how to locate one or more resources. If you speciﬁed health checking when you created the service, AWS Cloud Map returns only healthy instances.

AWS Cloud Map is tightly integrated with Amazon Elastic Container Service (Amazon ECS). As new container tasks spin up or down, they automatically register with AWS Cloud Map. You can use the Kubernetes ExternalDNS connector to integrate Amazon Elastic Kubernetes Service with AWS Cloud Map. You can also use AWS Cloud Map to register and locate any cloud resources, such as Amazon EC2 instances, Amazon DynamoDB, Amazon S3 buckets, Amazon Simple Queue Service (Amazon SQS) queues, or APIs deployed on top of Amazon API Gateway, among others. You can specify attribute values for services instances, and clients can use these attributes to ﬁlter the resources that AWS Cloud Map returns. For example, an application can request resources in a particular deployment stage, like BETA or PROD.

(10)

Actions

The following actions are supported:

• CreateHttpNamespace (p. 3)

• CreatePrivateDnsNamespace (p. 7)

• CreatePublicDnsNamespace (p. 11)

• CreateService (p. 15)

• DeleteNamespace (p. 21)

• DeleteService (p. 24)

• DeregisterInstance (p. 26)

• DiscoverInstances (p. 29)

• GetInstance (p. 34)

• GetInstancesHealthStatus (p. 37)

• GetNamespace (p. 41)

• GetOperation (p. 44)

• GetService (p. 47)

• ListInstances (p. 50)

• ListNamespaces (p. 54)

• ListOperations (p. 58)

• ListServices (p. 62)

• ListTagsForResource (p. 66)

• RegisterInstance (p. 69)

• TagResource (p. 75)

• UntagResource (p. 78)

• UpdateHttpNamespace (p. 81)

• UpdateInstanceCustomHealthStatus (p. 84)

• UpdatePrivateDnsNamespace (p. 87)

• UpdatePublicDnsNamespace (p. 90)

• UpdateService (p. 93)

(11)

CreateHttpNamespace

Creates an HTTP namespace. Service instances registered using an HTTP namespace can be discovered using a DiscoverInstances request but can't be discovered using DNS.

For the current quota on the number of namespaces that you can create using the same AWS account, see AWS Cloud Map quotas in the AWS Cloud Map Developer Guide.

Request Syntax

{ "CreatorRequestId": "string", "Description": "string", "Name": "string",

"Tags": [ {

"Key": "string", "Value": "string"

} ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 151).

The request accepts the following data in JSON format.

CreatorRequestId (p. 3)

A unique string that identiﬁes the request and that allows failed CreateHttpNamespace requests to be retried without the risk of running the operation twice. CreatorRequestId can be any unique string (for example, a date/time stamp).

Type: String

Length Constraints: Maximum length of 64.

Required: No Description (p. 3)

A description for the namespace.

Type: String

Required: No Name (p. 3)

The name that you want to assign to this namespace.

Type: String

Pattern: ^[!-~]{1,1024}$

(12)

Response Syntax

Required: Yes Tags (p. 3)

The tags to add to the namespace. Each tag consists of a key and an optional value that you deﬁne.

Tags keys can be up to 128 characters in length, and tag values can be up to 256 characters in length.

Type: Array of Tag (p. 150) objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

Required: No

Response Syntax

{ "OperationId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

OperationId (p. 4)

A value that you can use to determine whether the request completed successfully. To get the status of the operation, see GetOperation.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors (p. 153).

DuplicateRequest

The operation is already in progress.

HTTP Status Code: 400 InvalidInput

One or more speciﬁed values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

HTTP Status Code: 400 NamespaceAlreadyExists

The namespace that you're trying to create already exists.

HTTP Status Code: 400

(13)

Examples

ResourceLimitExceeded

The resource can't be created because you've reached the quota on the number of resources.

HTTP Status Code: 400 TooManyTagsException

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

Examples

CreateHttpNamespace Example

This example illustrates one usage of CreateHttpNamespace.

Sample Request

POST / HTTP/1.1

host:servicediscovery.us-west-2.amazonaws.com x-amz-date:20181118T211703Z

authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20181118/us-west-2/

servicediscovery/aws4_request,

SignedHeaders=content-length;content-type;host;user-agent;x-amz-date;x-amz- target,

Signature=[calculated-signature]

x-amz-target:Route53AutoNaming_v20170314.CreateHttpNamespace content-type:application/x-amz-json-1.1

content-length:[number of characters in the JSON string]

{

"CreatorRequestId": "example-creator-request-id-0001", "Name": "example-http.com",

"Description": "Example.com AWS Cloud Map HTTP Namespace"

}

Sample Response

HTTP/1.1 200

Content-Length: [number of characters in the JSON string]

Content-Type: application/x-amz-json-1.1 {

"OperationId":"httpvoqozuhfet5kzxoxg-a-response-example"

}

CreatePrivateDnsNamespace

Creates a private namespace based on DNS, which is visible only inside a speciﬁed Amazon VPC.

The namespace deﬁnes your service naming scheme. For example, if you name your namespace example.com and name your service backend, the resulting DNS name for the service is

backend.example.com. Service instances that are registered using a private DNS namespace can be discovered using either a DiscoverInstances request or using DNS. For the current quota on the number of namespaces that you can create using the same AWS account, see AWS Cloud Map quotas in the AWS Cloud Map Developer Guide.

Request Syntax

"Properties": { "DnsProperties": { "SOA": {

"TTL": number }

} },

"Tags": [ {

} ],

"Vpc": "string"

}

Request Parameters

A unique string that identiﬁes the request and that allows failed CreatePrivateDnsNamespace requests to be retried without the risk of running the operation twice. CreatorRequestId can be any unique string (for example, a date/timestamp).

Type: String

(16)

Response Syntax

The name that you want to assign to this namespace. When you create a private DNS namespace, AWS Cloud Map automatically creates an Amazon Route 53 private hosted zone that has the same name as the namespace.

Type: String

Pattern: ^[!-~]{1,1024}$

Required: Yes Properties (p. 7)

Properties for the private DNS namespace.

Type: PrivateDnsNamespaceProperties (p. 131) object Required: No

Tags (p. 7)

Required: No Vpc (p. 7)

The ID of the Amazon VPC that you want to associate the namespace with.

Type: String

Required: Yes

Response Syntax

{

"OperationId": "string"

}

Response Elements

(17)

Errors

Type: String

Errors

HTTP Status Code: 400 ResourceLimitExceeded

Examples

CreatePrivateDnsNamespace Example

This example illustrates one usage of CreatePrivateDnsNamespace.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.CreatePrivateDnsNamespace content-type:application/x-amz-json-1.1

(18)

See Also

{

"CreatorRequestId": "example-creator-request-id-0002", "Name": "example-private-dns.com",

"Description": "Example.com AWS Cloud Map Private DNS Namespace", "Vpc": "vpc-12345678"

}

Sample Response

HTTP/1.1 200

Content-Type: application/x-amz-json-1.1

{ "OperationId":"dns1voqozuhfet5kzxoxg-a-response-example"

}

CreatePublicDnsNamespace

Creates a public namespace based on DNS, which is visible on the internet. The namespace deﬁnes your service naming scheme. For example, if you name your namespace example.com and name your service backend, the resulting DNS name for the service is backend.example.com. You can discover instances that were registered with a public DNS namespace by using either a DiscoverInstances request or using DNS. For the current quota on the number of namespaces that you can create using the same AWS account, see AWS Cloud Map quotas in the AWS Cloud Map Developer Guide.

Important

The CreatePublicDnsNamespace API operation is not supported in the AWS GovCloud (US) Regions.

Request Syntax

"Properties": { "DnsProperties": { "SOA": {

"TTL": number }

} },

"Tags": [ {

} ] }

Request Parameters

A unique string that identiﬁes the request and that allows failed CreatePublicDnsNamespace requests to be retried without the risk of running the operation twice. CreatorRequestId can be any unique string (for example, a date/timestamp).

Type: String

(20)

Response Syntax

The name that you want to assign to this namespace.

Type: String

Pattern: ^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z0-9]([a-zA- Z0-9\-]{0,61}[a-zA-Z0-9])?$

Required: Yes Properties (p. 11)

Properties for the public DNS namespace.

Type: PublicDnsNamespaceProperties (p. 136) object Required: No

Tags (p. 11)

Required: No

Response Syntax

}

Response Elements

Type: String

Errors

(21)

Examples

CreatePublicDnsNamespace Example

This example illustrates one usage of CreatePublicDnsNamespace.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.CreatePublicDnsNamespace content-type:application/x-amz-json-1.1

{

"CreatorRequestId": "example-creator-request-id-0003", "Name": "example-public-dns.com",

"Description": "Example.com AWS Cloud Map Public DNS Namespace"

}

Sample Response

HTTP/1.1 200

(22)

See Also

{ "OperationId":"dns2voqozuhfet5kzxoxg-a-response-example"

}

CreateService

Creates a service. This action deﬁnes the conﬁguration for the following entities:

• For public and private DNS namespaces, one of the following combinations of DNS records in Amazon Route 53:

• A

• AAAA

• A and AAAA

• SRV

• CNAME

• Optionally, a health check

After you create the service, you can submit a RegisterInstance request, and AWS Cloud Map uses the values in the conﬁguration to create the speciﬁed entities.

For the current quota on the number of instances that you can register using the same namespace and using the same service, see AWS Cloud Map quotas in the AWS Cloud Map Developer Guide.

Request Syntax

{ "CreatorRequestId": "string", "Description": "string", "DnsConfig": {

"DnsRecords": [ {

"TTL": number, "Type": "string"

} ],

"NamespaceId": "string", "RoutingPolicy": "string"

},

"HealthCheckConfig": { "FailureThreshold": number, "ResourcePath": "string", "Type": "string"

},

"HealthCheckCustomConfig": { "FailureThreshold": number },

"Name": "string",

"NamespaceId": "string", "Tags": [

{

} ],

"Type": "string"

}

Request Parameters

(24)

Request Parameters

A unique string that identiﬁes the request and that allows failed CreateService requests to be retried without the risk of running the operation twice. CreatorRequestId can be any unique string (for example, a date/timestamp).

Type: String

A description for the service.

Type: String

Required: No DnsConﬁg (p. 15)

A complex type that contains information about the Amazon Route 53 records that you want AWS Cloud Map to create when you register an instance.

Type: DnsConﬁg (p. 98) object Required: No

HealthCheckConﬁg (p. 15)

Public DNS and HTTP namespaces only. A complex type that contains settings for an optional Route 53 health check. If you specify settings for a health check, AWS Cloud Map associates the health check with all the Route 53 DNS records that you specify in DnsConfig.

Important

If you specify a health check conﬁguration, you can specify either HealthCheckCustomConfig or HealthCheckConfig but not both.

For information about the charges for health checks, see AWS Cloud Map Pricing.

Type: HealthCheckConﬁg (p. 104) object Required: No

HealthCheckCustomConﬁg (p. 15)

A complex type that contains information about an optional custom health check.

Important

If you specify a health check conﬁguration, you can specify either HealthCheckCustomConfig or HealthCheckConfig but not both.

You can't add, update, or delete a HealthCheckCustomConfig conﬁguration from an existing service.

Type: HealthCheckCustomConﬁg (p. 107) object Required: No

Name (p. 15)

The name that you want to assign to the service.

(25)

Response Syntax

If you want AWS Cloud Map to create an SRV record when you register an instance and you're using a system that requires a speciﬁc SRV format, such as HAProxy, specify the following for Name:

• Start the name with an underscore (_), such as _exampleservice.

• End the name with ._protocol, such as ._tcp.

When you register an instance, AWS Cloud Map creates an SRV record and assigns a name to the record by concatenating the service name and the namespace name (for example,

_exampleservice._tcp.example.com).

Note

For services that are accessible by DNS queries, you can't create multiple services with names that diﬀer only by case (such as EXAMPLE and example). Otherwise, these services have the same DNS name and can't be distinguished. However, if you use a namespace that's only accessible by API calls, then you can create services that with names that diﬀer only by case.

Type: String

Pattern: ((?=^.{1,127}$)^([a-zA-Z0-9_][a-zA-Z0-9-_]{0,61}[a-zA-Z0-9_]|[a-zA- Z0-9])(\.([a-zA-Z0-9_][a-zA-Z0-9-_]{0,61}[a-zA-Z0-9_]|[a-zA-Z0-9]))*$)|(^\.

$)

Required: Yes NamespaceId (p. 15)

The ID of the namespace that you want to use to create the service. The namespace ID must be speciﬁed, but it can be speciﬁed either here or in the DnsConfig object.

Type: String

Required: No Tags (p. 15)

The tags to add to the service. Each tag consists of a key and an optional value that you deﬁne. Tags keys can be up to 128 characters in length, and tag values can be up to 256 characters in length.

Required: No Type (p. 15)

If present, speciﬁes that the service instances are only discoverable using the DiscoverInstances API operation. No DNS records is registered for the service instances. The only valid value is HTTP.

Type: String Valid Values: HTTP Required: No

Response Syntax

{ "Service": {

(26)

Response Elements

"Arn": "string", "CreateDate": number,

"CreatorRequestId": "string", "Description": "string", "DnsConfig": {

"DnsRecords": [ {

"TTL": number, "Type": "string"

} ],

"NamespaceId": "string", "RoutingPolicy": "string"

},

"HealthCheckConfig": { "FailureThreshold": number, "ResourcePath": "string", "Type": "string"

},

"HealthCheckCustomConfig": { "FailureThreshold": number },

"Id": "string",

"InstanceCount": number, "Name": "string",

"NamespaceId": "string", "Type": "string"

}}

Response Elements

Service (p. 17)

A complex type that contains information about the new service.

Type: Service (p. 140) object

Errors

InvalidInput

HTTP Status Code: 400 NamespaceNotFound

No namespace exists with the speciﬁed ID.

(27)

Examples

HTTP Status Code: 400 ServiceAlreadyExists

The service can't be created because a service with the same name already exists.

Examples

CreateService Example

This example illustrates one usage of CreateService.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.CreateService content-type:application/x-amz-json-1.1

{

"CreatorRequestId": "example-creator-request-id-0004", "NamespaceId": "ns-e4anhexample0004",

"Name": "example-http-service", "HealthCheckConfig": {

"Type": "HTTPS", "ResourcePath": "/", "FailureThreshold": 1 },

"Description": "Example.com AWS Cloud Map HTTP Service"

}

Sample Response

HTTP/1.1 200

"Service": {

"Arn": "arn:aws:servicediscovery:us-west-2:123456789120:service/srv- e4anhexample0004",

"CreateDate": "20181118T211707Z",

"CreatorRequestId": "example-creator-request-id-0004", "Description": "Example.com AWS Cloud Map HTTP Service", "HealthCheckConfig": {

(28)

See Also

"FailureThreshold": 1, "ResourcePath": "/", "Type": "HTTPS"

},

"Id": "srv-e4anhexample0004", "Name": "example-http-service", "NamespaceId": "ns-e4anhexample0004"

} }

DeleteNamespace

Deletes a namespace from the current account. If the namespace still contains one or more services, the request fails.

Request Syntax

{ "Id": "string"

}

Request Parameters

Id (p. 21)

The ID of the namespace that you want to delete.

Type: String

Required: Yes

Response Syntax

}

Response Elements

Type: String

Errors

(30)

Examples

HTTP Status Code: 400 ResourceInUse

The speciﬁed resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

Examples

DeleteNamespace Example

This example illustrates one usage of DeleteNamespace.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.DeleteNamespace content-type:application/x-amz-json-1.1

{

"Id": "ns-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

{ "OperationId":"deleteelozuhfet5kzxoxg-a-response-example"

}

(31)

See Also

DeleteService

Deletes a speciﬁed service. If the service still contains one or more registered instances, the request fails.

Request Syntax

{ "Id": "string"

}

Request Parameters

Id (p. 24)

The ID of the service that you want to delete.

Type: String

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InvalidInput

HTTP Status Code: 400 ServiceNotFound

No service exists with the speciﬁed ID.

(33)

Examples

DeleteService Example

This example illustrates one usage of DeleteService.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.DeleteService content-type:application/x-amz-json-1.1

{ "Id": "srv-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

Content-Type: application/x-amz-json-1.1 {}

DeregisterInstance

Deletes the Amazon Route 53 DNS records and health check, if any, that AWS Cloud Map created for the speciﬁed instance.

Request Syntax

{ "InstanceId": "string", "ServiceId": "string"

}

Request Parameters

InstanceId (p. 26)

The value that you speciﬁed for Id in the RegisterInstance request.

Type: String

Required: Yes ServiceId (p. 26)

The ID of the service that the instance is associated with.

Type: String

Required: Yes

Response Syntax

}

Response Elements

(35)

Errors

Type: String

Errors

HTTP Status Code: 400 InstanceNotFound

No instance exists with the speciﬁed ID, or the instance was recently registered, and information about the instance hasn't propagated yet.

Examples

DeregisterInstance Example

This example illustrates one usage of DeregisterInstance.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.DeregisterInstance content-type:application/x-amz-json-1.1

(36)

See Also

{ "InstanceId": "i-abcd1234", "ServiceId": "srv-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

"OperationId":"httpvoqozuhfet5kzxoxg-a-response-example"

}

DiscoverInstances

Discovers registered instances for a speciﬁed namespace and service. You can use DiscoverInstances to discover instances for any type of namespace. For public and private DNS namespaces, you can also use DNS queries to discover instances.

Request Syntax

{ "HealthStatus": "string", "MaxResults": number, "NamespaceName": "string", "OptionalParameters": { "string" : "string"

},

"QueryParameters": { "string" : "string"

},

"ServiceName": "string"

}

Request Parameters

HealthStatus (p. 29)

The health status of the instances that you want to discover. This parameter is ignored for services that don't have a health check conﬁgured, and all instances are returned.

HEALTHY

Returns healthy instances.

UNHEALTHY

Returns unhealthy instances.

ALL

Returns all instances.

HEALTHY_OR_ELSE_ALL

Returns healthy instances, unless none are reporting a healthy state. In that case, return all instances. This is also called failing open.

Type: String

Valid Values: HEALTHY | UNHEALTHY | ALL | HEALTHY_OR_ELSE_ALL Required: No

MaxResults (p. 29)

The maximum number of instances that you want AWS Cloud Map to return in the response to a DiscoverInstances request. If you don't specify a value for MaxResults, AWS Cloud Map returns up to 100 instances.

(38)

Request Parameters

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No NamespaceName (p. 29)

The HttpName name of the namespace. It's found in the HttpProperties member of the Properties member of the namespace.

Type: String

Required: Yes

OptionalParameters (p. 29)

Opportunistic filters to scope the results based on custom attributes. If there are instances that match both the filters specified in both the QueryParameters parameter and this parameter, all of these instances are returned. Otherwise, the filters are ignored, and only instances that match the filters that are specified in the QueryParameters parameter are returned.

Type: String to string map

Key Length Constraints: Maximum length of 255.

Key Pattern: ^[a-zA-Z0-9!-~]+$

Value Length Constraints: Maximum length of 1024.

Value Pattern: ^([a-zA-Z0-9!-~][ \ta-zA-Z0-9!-~]*){0,1}[a-zA-Z0-9!-~]{0,1}$

Required: No

QueryParameters (p. 29)

Filters to scope the results based on custom attributes for the instance (for example, {version=v1, az=1a}). Only instances that match all the speciﬁed key-value pairs are returned.

Key Pattern: ^[a-zA-Z0-9!-~]+$

Value Length Constraints: Maximum length of 1024.

Value Pattern: ^([a-zA-Z0-9!-~][ \ta-zA-Z0-9!-~]*){0,1}[a-zA-Z0-9!-~]{0,1}$

Required: No ServiceName (p. 29)

The name of the service that you speciﬁed when you registered the instance.

Type: String

Pattern: ((?=^.{1,127}$)^([a-zA-Z0-9_][a-zA-Z0-9-_]{0,61}[a-zA-Z0-9_]|[a-zA- Z0-9])(\.([a-zA-Z0-9_][a-zA-Z0-9-_]{0,61}[a-zA-Z0-9_]|[a-zA-Z0-9]))*$)|(^\.

$)

(39)

Response Syntax

Required: Yes

Response Syntax

{

"Instances": [ {

"Attributes": { "string" : "string"

},

"HealthStatus": "string", "InstanceId": "string", "NamespaceName": "string", "ServiceName": "string"

} ]}

Response Elements

Instances (p. 31)

A complex type that contains one HttpInstanceSummary for each registered instance.

Type: Array of HttpInstanceSummary (p. 109) objects

Errors

InvalidInput

HTTP Status Code: 400 RequestLimitExceeded

The operation can't be completed because you've reached the quota for the number of requests. For more information, see AWS Cloud Map API request throttling quota in the AWS Cloud Map Developer Guide.

(40)

Examples

DiscoverInstances Example

This example illustrates one usage of DiscoverInstances.

Sample Request

POST / HTTP/1.1

host:data-servicediscovery.us-west-2.amazonaws.com x-amz-date:20181118T211819Z

x-amz-target:Route53AutoNaming_v20170314.DiscoverInstances content-type:application/x-amz-json-1.1

{ "NamespaceName": "example-public-dns.com", "ServiceName": "example-dns-pub-service"

}

Sample Response

HTTP/1.1 200

"Instances": [ {

"Attributes": {

"AWS_INSTANCE_IPV4": "192.0.2.44", "AWS_INSTANCE_PORT": "80",

"color": "green", "region": "us-west-2", "stage": "beta"

},

"HealthStatus": "HEALTHY", "InstanceId": "i-abcd1234",

"NamespaceName": "example-public-dns.com", "ServiceName": "example-dns-pub-service"

} ] }

GetInstance

Gets information about a speciﬁed instance.

Request Syntax

{ "InstanceId": "string", "ServiceId": "string"

}

Request Parameters

InstanceId (p. 34)

The ID of the instance that you want to get information about.

Type: String

Required: Yes ServiceId (p. 34)

Type: String

Required: Yes

Response Syntax

{ "Instance": { "Attributes": { "string" : "string"

},

"CreatorRequestId": "string", "Id": "string"

}}

Response Elements

(43)

Errors

Instance (p. 34)

A complex type that contains information about a speciﬁed instance.

Type: Instance (p. 113) object

Errors

InstanceNotFound

Examples

GetInstance Example

This example illustrates one usage of GetInstance.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.GetInstance content-type:application/x-amz-json-1.1

{

"InstanceId": "i-abcd1234", "ServiceId": "srv-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

(44)

See Also

"Instance": {

"Id": "i-abcd1234", "Attributes": {

"AWS_INSTANCE_IPV4": "192.0.2.44", "AWS_INSTANCE_PORT": "80",

"color": "green", "region": "us-west-2", "stage": "beta"

} } }

GetInstancesHealthStatus

Gets the current health status (Healthy, Unhealthy, or Unknown) of one or more instances that are associated with a speciﬁed service.

NoteThere's a brief delay between when you register an instance and when the health status for the instance is available.

Request Syntax

{ "Instances": [ "string" ], "MaxResults": number, "NextToken": "string", "ServiceId": "string"

}

Request Parameters

Instances (p. 37)

An array that contains the IDs of all the instances that you want to get the health status for.

If you omit Instances, AWS Cloud Map returns the health status for all the instances that are associated with the speciﬁed service.

NoteTo get the IDs for the instances that you've registered by using a speciﬁed service, submit a ListInstances request.

Type: Array of strings

Array Members: Minimum number of 1 item.

Required: No MaxResults (p. 37)

The maximum number of instances that you want AWS Cloud Map to return in the response to a GetInstancesHealthStatus request. If you don't specify a value for MaxResults, AWS Cloud Map returns up to 100 instances.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No NextToken (p. 37)

For the ﬁrst GetInstancesHealthStatus request, omit this value.

(46)

Response Syntax

If more than MaxResults instances match the speciﬁed criteria, you can submit another GetInstancesHealthStatus request to get the next group of results. Specify the value of NextToken from the previous response in the next request.

Type: String

Required: No ServiceId (p. 37)

Type: String

Required: Yes

Response Syntax

{ "NextToken": "string", "Status": {

"string" : "string"

}}

Response Elements

NextToken (p. 38)

If more than MaxResults instances match the speciﬁed criteria, you can submit another GetInstancesHealthStatus request to get the next group of results. Specify the value of NextToken from the previous response in the next request.

Type: String

Status (p. 38)

A complex type that contains the IDs and the health status of the instances that you speciﬁed in the GetInstancesHealthStatus request.

Valid Values: HEALTHY | UNHEALTHY | UNKNOWN

Errors

(47)

Examples

InstanceNotFound

Examples

GetInstancesHealthStatus Example

This example illustrates one usage of GetInstancesHealthStatus.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.GetInstancesHealthStatus content-type:application/x-amz-json-1.1

{ "ServiceId": "srv-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

"Status": {

"i-abcd1234": "HEALTHY", "i-abcd1235": "UNHEALTHY"

} }

GetNamespace

Gets information about a namespace.

Request Syntax

{

"Id": "string"

}

Request Parameters

Id (p. 41)

The ID of the namespace that you want to get information about.

Type: String

Required: Yes

Response Syntax

{

"Namespace": { "Arn": "string", "CreateDate": number,

"CreatorRequestId": "string", "Description": "string", "Id": "string",

"Name": "string", "Properties": { "DnsProperties": {

"HostedZoneId": "string", "SOA": {

"TTL": number }

},

"HttpProperties": { "HttpName": "string"

} },

"ServiceCount": number, "Type": "string"

}}

Response Elements

(50)

Errors

Namespace (p. 41)

A complex type that contains information about the speciﬁed namespace.

Type: Namespace (p. 118) object

Errors

InvalidInput

Examples

GetNamespace Example

This example illustrates one usage of GetNamespace.

Sample Request

POST / HTTP/1.1

x-amz-target:Route53AutoNaming_v20170314.GetNamespace content-type:application/x-amz-json-1.1

{

"Id": "ns-e4anhexample0004"

}

Sample Response

HTTP/1.1 200

Content-Type: application/x-amz-json-1.1 { "Namespace": {

(51)

See Also

"Arn": "arn:aws:servicediscovery:us-west-2: 123456789120:namespace/ns- e1tpmexample0001",

"CreateDate": "20181118T211712Z",

"CreatorRequestId": "example-creator-request-id-0001", "Description": "Example.com AWS Cloud Map HTTP Namespace", "Id": "ns-e1tpmexample0001",

"Name": "example-http.com", "Properties": {

"DnsProperties": {}, "HttpProperties": {

"HttpName": "example-http.com"

} },

"Type": "HTTP"

} }

AWS Cloud Map

AWS Cloud Map

API Reference

API Version 2017-03-14

AWS Cloud Map: API Reference

Table of Contents

Welcome

Actions

CreateHttpNamespace

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

CreateHttpNamespace Example

Sample Request

Sample Response

See Also

CreatePrivateDnsNamespace

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

CreatePrivateDnsNamespace Example

Sample Request

Sample Response

See Also

CreatePublicDnsNamespace

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

CreatePublicDnsNamespace Example

Sample Request

Sample Response

See Also

CreateService

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

CreateService Example

Sample Request

Sample Response

See Also

DeleteNamespace

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

DeleteNamespace Example

Sample Request

Sample Response

See Also

DeleteService

Request Syntax

Request Parameters

Response Elements

Errors

Examples

DeleteService Example

Sample Request

Sample Response

See Also

DeregisterInstance

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples