Skip to main content

instances

Creates, updates, deletes, gets or lists an instances resource.

Overview​

Nameinstances
TypeResource
Idaws.servicediscovery.instances

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
instanceobjectA complex type that contains information about a specified instance.
resource_ownerstringThe ID of the Amazon Web Services account that created the namespace that contains the service that the instance is associated with. If this isn't your account ID, it's the ID of the account that shared the namespace with your account.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_instanceselectregionGets information about a specified instance.
list_instancesselectregionLists summary information about the instances that you registered by using a specified service.
register_instanceinsertregion, ServiceId, InstanceIdCreates or updates one or more records and, optionally, creates a health check based on the settings in a specified service. When you submit a RegisterInstance request, the following occurs: 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. The health check, if any, is associated with each of the new or updated records. One RegisterInstance request must complete before you can submit another request and specify the same service ID and instance ID. For more information, see CreateService. When Cloud Map receives a DNS query for the specified DNS name, it returns the applicable value: If the health check is healthy: returns all the records If the health check is unhealthy: returns the applicable value for the last healthy instance If you didn't specify a health check configuration: returns all the records For the current quota on the number of instances that you can register using the same namespace and using the same service, see Cloud Map quotas in the Cloud Map Developer Guide.
update_instance_custom_health_statusupdateregion, ServiceId, InstanceId, StatusSubmits a request to change the health status of a custom health check to healthy or unhealthy. You can use UpdateInstanceCustomHealthStatus to change the status only for custom health checks, which you define using HealthCheckCustomConfig when you create a service. You can't use it to change the status for Route 53 health checks, which you define using HealthCheckConfig. For more information, see HealthCheckCustomConfig.
deregister_instancedeleteregionDeletes the Amazon Route 53 DNS records and health check, if any, that Cloud Map created for the specified instance.
discover_instancesexecregion, NamespaceName, ServiceNameDiscovers registered instances for a specified namespace and service. You can use DiscoverInstances to discover instances for any type of namespace. DiscoverInstances returns a randomized list of instances allowing customers to distribute traffic evenly across instances. For public and private DNS namespaces, you can also use DNS queries to discover instances.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Gets information about a specified instance.

SELECT
instance,
resource_owner
FROM aws.servicediscovery.instances
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates or updates one or more records and, optionally, creates a health check based on the settings in a specified service. When you submit a RegisterInstance request, the following occurs: 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. The health check, if any, is associated with each of the new or updated records. One RegisterInstance request must complete before you can submit another request and specify the same service ID and instance ID. For more information, see CreateService. When Cloud Map receives a DNS query for the specified DNS name, it returns the applicable value: If the health check is healthy: returns all the records If the health check is unhealthy: returns the applicable value for the last healthy instance If you didn't specify a health check configuration: returns all the records For the current quota on the number of instances that you can register using the same namespace and using the same service, see Cloud Map quotas in the Cloud Map Developer Guide.

INSERT INTO aws.servicediscovery.instances (
ServiceId,
InstanceId,
CreatorRequestId,
Attributes,
region
)
SELECT 
'{{ ServiceId }}' /* required */,
'{{ InstanceId }}' /* required */,
'{{ CreatorRequestId }}',
'{{ Attributes }}',
'{{ region }}'
RETURNING
operation_id
;

UPDATE examples​

Submits a request to change the health status of a custom health check to healthy or unhealthy. You can use UpdateInstanceCustomHealthStatus to change the status only for custom health checks, which you define using HealthCheckCustomConfig when you create a service. You can't use it to change the status for Route 53 health checks, which you define using HealthCheckConfig. For more information, see HealthCheckCustomConfig.

UPDATE aws.servicediscovery.instances
SET 
ServiceId = '{{ ServiceId }}',
InstanceId = '{{ InstanceId }}',
Status = '{{ Status }}'
WHERE 
region = '{{ region }}' --required
AND ServiceId = '{{ ServiceId }}' --required
AND InstanceId = '{{ InstanceId }}' --required
AND Status = '{{ Status }}' --required;

DELETE examples​

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

DELETE FROM aws.servicediscovery.instances
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Discovers registered instances for a specified namespace and service. You can use DiscoverInstances to discover instances for any type of namespace. DiscoverInstances returns a randomized list of instances allowing customers to distribute traffic evenly across instances. For public and private DNS namespaces, you can also use DNS queries to discover instances.

EXEC aws.servicediscovery.instances.discover_instances 
@region='{{ region }}' --required 
@@json=
'{
"NamespaceName": "{{ NamespaceName }}", 
"ServiceName": "{{ ServiceName }}", 
"MaxResults": {{ MaxResults }}, 
"QueryParameters": "{{ QueryParameters }}", 
"OptionalParameters": "{{ OptionalParameters }}", 
"HealthStatus": "{{ HealthStatus }}", 
"OwnerAccount": "{{ OwnerAccount }}"
}'
;
Last updated on