AWS.CloudMap reference

DeregisterInstance

Source: src/AWS/CloudMap/DeregisterInstance.ts

Runtime binding for servicediscovery:DeregisterInstance — lets a self-registering workload remove its own Cloud Map instance (and the Route 53 records/health check Cloud Map created for it).

The response carries an OperationId; deregistration completes asynchronously on the Cloud Map side.

DeregisterInstance: Deregistering Instances

const deregisterInstance = yield* AWS.CloudMap.DeregisterInstance(service);

yield* deregisterInstance({ InstanceId: "worker-1" });

DiscoverInstances

Source: src/AWS/CloudMap/DiscoverInstances.ts

Runtime binding for servicediscovery:DiscoverInstances — the Cloud Map data-plane query that returns a randomized list of registered (by default healthy) instances of a service.

Bind this operation to a Service inside a function runtime to get a callable that automatically injects the namespace and service names.

DiscoverInstances: Discovering Instances

Discover Healthy Instances

const discover = yield* AWS.CloudMap.DiscoverInstances(service);

const { Instances } = yield* discover({});
for (const instance of Instances ?? []) {
  console.log(instance.InstanceId, instance.Attributes?.AWS_INSTANCE_IPV4);
}

Include Unhealthy Instances

const { Instances } = yield* discover({ HealthStatus: "ALL" });

DiscoverInstancesRevision

Source: src/AWS/CloudMap/DiscoverInstancesRevision.ts

Runtime binding for servicediscovery:DiscoverInstancesRevision — the Cloud Map data-plane query that returns the monotonically-increasing revision of the bound Service’s instance set. Poll it as a cheap change detector and re-call DiscoverInstances only when the revision moves. Provide the implementation with Effect.provide(AWS.CloudMap.DiscoverInstancesRevisionHttp).

DiscoverInstancesRevision: Discovering Instances

const discoverInstancesRevision =
  yield* AWS.CloudMap.DiscoverInstancesRevision(service);

const { InstancesRevision } = yield* discoverInstancesRevision();
if (InstancesRevision !== lastSeenRevision) {
  // instance set changed — re-run DiscoverInstances
}

GetInstance

Source: src/AWS/CloudMap/GetInstance.ts

Runtime binding for servicediscovery:GetInstance — reads a single registered instance of the bound Service by its instance ID, returning its full attribute map. Provide the implementation with Effect.provide(AWS.CloudMap.GetInstanceHttp).

GetInstance: Reading Instances

const getInstance = yield* AWS.CloudMap.GetInstance(service);

const { Instance } = yield* getInstance({ InstanceId: "worker-1" });
console.log(Instance?.Attributes?.AWS_INSTANCE_IPV4);

GetInstancesHealthStatus

Source: src/AWS/CloudMap/GetInstancesHealthStatus.ts

Runtime binding for servicediscovery:GetInstancesHealthStatus — reads the current health status (HEALTHY, UNHEALTHY, or UNKNOWN) of the bound Service’s instances. There is a brief delay between registering an instance and its health status becoming available. Provide the implementation with Effect.provide(AWS.CloudMap.GetInstancesHealthStatusHttp).

GetInstancesHealthStatus: Instance Health

Read Health of All Instances

const getInstancesHealthStatus =
  yield* AWS.CloudMap.GetInstancesHealthStatus(service);

const { Status } = yield* getInstancesHealthStatus();
console.log(Status?.["worker-1"]); // "HEALTHY" | "UNHEALTHY" | "UNKNOWN"

Read Health of Specific Instances

const { Status } = yield* getInstancesHealthStatus({
  Instances: ["worker-1", "worker-2"],
});

GetOperation

Source: src/AWS/CloudMap/GetOperation.ts

Runtime binding for servicediscovery:GetOperation — reads the status of an asynchronous Cloud Map operation. RegisterInstance and DeregisterInstance return an OperationId; poll it with this binding to await completion (SUCCESS / FAIL) before relying on the registration. Provide the implementation with Effect.provide(AWS.CloudMap.GetOperationHttp).

GetOperation: Registering Instances

const registerInstance = yield* AWS.CloudMap.RegisterInstance(service);
const getOperation = yield* AWS.CloudMap.GetOperation();

const { OperationId } = yield* registerInstance({
  InstanceId: "worker-1",
  Attributes: { AWS_INSTANCE_IPV4: "10.0.1.10" },
});
const { Operation } = yield* getOperation({ OperationId: OperationId! });
console.log(Operation?.Status); // "SUBMITTED" | "PENDING" | "SUCCESS" | "FAIL"

GetServiceAttributes

Source: src/AWS/CloudMap/GetServiceAttributes.ts

Runtime binding for servicediscovery:GetServiceAttributes — reads the custom key/value attributes stored on the bound Service (declared via the Service resource’s attributes prop or written out-of-band). Use it to distribute small pieces of service-level configuration to consumers without an extra config store. Provide the implementation with Effect.provide(AWS.CloudMap.GetServiceAttributesHttp).

GetServiceAttributes: Service Attributes

const getServiceAttributes =
  yield* AWS.CloudMap.GetServiceAttributes(service);

const { ServiceAttributes } = yield* getServiceAttributes();
console.log(ServiceAttributes?.Attributes?.tier);

HttpNamespace

Source: src/AWS/CloudMap/HttpNamespace.ts

An AWS Cloud Map HTTP namespace — an API-only service registry. Instances registered in an HTTP namespace are discoverable via the DiscoverInstances API but not via DNS, so no VPC or hosted zone is required.

Namespace creation and deletion are asynchronous — the provider polls the Cloud Map operations API (bounded) until they complete.

HttpNamespace: Creating Namespaces

import * as AWS from "alchemy/AWS";

const namespace = yield* AWS.CloudMap.HttpNamespace("AppNamespace", {
  description: "API-only service discovery",
});

HttpNamespace: Registering Services

const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
});

InstanceRegistration

Source: src/AWS/CloudMap/InstanceRegistration.ts

A manual AWS Cloud Map instance registration — registers a static endpoint (an IP, port, CNAME, or an arbitrary attribute bag) with a Cloud Map service so it is returned by DiscoverInstances and, for DNS services, resolvable via Route 53.

Use this for non-ECS targets: static IPs, on-prem hosts, external dependencies. ECS registers its own tasks automatically via serviceRegistries.

RegisterInstance is an upsert — reconcile re-registers with the desired attributes and Cloud Map converges the records. Registration and deregistration are asynchronous; the provider polls the operations API (bounded) until they complete.

InstanceRegistration: Registering Instances

Register a Static IP

import * as AWS from "alchemy/AWS";

const instance = yield* AWS.CloudMap.InstanceRegistration("Primary", {
  serviceId: service.serviceId,
  instanceId: "primary",
  attributes: { AWS_INSTANCE_IPV4: "10.0.1.10" },
});

Register an API-only Instance with Custom Attributes

const instance = yield* AWS.CloudMap.InstanceRegistration("Worker", {
  serviceId: service.serviceId,
  instanceId: "worker-1",
  attributes: { endpoint: "https://worker-1.internal:8443", zone: "us-west-2a" },
});

ListInstances

Source: src/AWS/CloudMap/ListInstances.ts

Runtime binding for servicediscovery:ListInstances — lists summary information (id + attributes) for every instance registered with the bound Service. Unlike DiscoverInstances this is the control-plane view: strongly consistent with registration, one page at a time via NextToken. Provide the implementation with Effect.provide(AWS.CloudMap.ListInstancesHttp).

ListInstances: Reading Instances

const listInstances = yield* AWS.CloudMap.ListInstances(service);

const { Instances } = yield* listInstances();
for (const instance of Instances ?? []) {
  console.log(instance.Id, instance.Attributes);
}

PrivateDnsNamespace

Source: src/AWS/CloudMap/PrivateDnsNamespace.ts

An AWS Cloud Map private DNS namespace — the DNS-based service registry that ECS Service Connect and serviceRegistries point at. Services registered in the namespace are discoverable inside the associated VPC via DNS ({service}.{namespace}) and from anywhere via the DiscoverInstances API.

Namespace creation and deletion are asynchronous — the provider polls the Cloud Map operations API (bounded) until they complete, which typically takes 30-60 seconds.

PrivateDnsNamespace: Creating Namespaces

Private DNS Namespace in a VPC

import * as AWS from "alchemy/AWS";

const vpc = yield* AWS.EC2.Vpc("AppVpc", { cidrBlock: "10.0.0.0/16" });
const namespace = yield* AWS.CloudMap.PrivateDnsNamespace("AppNamespace", {
  name: "internal.example.com",
  vpc: vpc.vpcId,
});

Namespace with SOA TTL and Description

const namespace = yield* AWS.CloudMap.PrivateDnsNamespace("AppNamespace", {
  name: "internal.example.com",
  vpc: vpc.vpcId,
  description: "service discovery for the app tier",
  ttl: "60 seconds",
});

PrivateDnsNamespace: Registering Services

const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
  dnsRecords: [{ type: "A", ttl: "10 seconds" }],
  routingPolicy: "MULTIVALUE",
});

PublicDnsNamespace

Source: src/AWS/CloudMap/PublicDnsNamespace.ts

An AWS Cloud Map public DNS namespace — a service registry backed by a Route 53 public hosted zone, so registered instances are discoverable on the public internet via DNS as well as via the DiscoverInstances API.

The hosted zone incurs standard Route 53 charges while the namespace exists, and the namespace name is only useful if you control the domain.

Namespace creation and deletion are asynchronous — the provider polls the Cloud Map operations API (bounded) until they complete.

PublicDnsNamespace: Creating Namespaces

import * as AWS from "alchemy/AWS";

const namespace = yield* AWS.CloudMap.PublicDnsNamespace("PublicNamespace", {
  name: "discovery.example.com",
});

RegisterInstance

Source: src/AWS/CloudMap/RegisterInstance.ts

Runtime binding for servicediscovery:RegisterInstance — lets a self-registering workload create or update its own Cloud Map instance (an upsert on the instance ID).

The response carries an OperationId; registration completes asynchronously on the Cloud Map side.

RegisterInstance: Registering Instances

const registerInstance = yield* AWS.CloudMap.RegisterInstance(service);

yield* registerInstance({
  InstanceId: "worker-1",
  Attributes: { AWS_INSTANCE_IPV4: "10.0.1.10" },
});

Service

Source: src/AWS/CloudMap/Service.ts

An AWS Cloud Map service — a named entry in a namespace that instances register against. For DNS namespaces, Cloud Map creates the configured DNS records per registered instance; every service is also queryable via the DiscoverInstances API. This is what ECS serviceRegistries[].registryArn consumes.

Service: Creating Services

DNS Service with A Records

import * as AWS from "alchemy/AWS";

const namespace = yield* AWS.CloudMap.PrivateDnsNamespace("AppNamespace", {
  name: "internal.example.com",
  vpc: vpc.vpcId,
});

const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
  dnsRecords: [{ type: "A", ttl: "10 seconds" }],
  routingPolicy: "MULTIVALUE",
});

API-only Service in an HTTP Namespace

const namespace = yield* AWS.CloudMap.HttpNamespace("AppNamespace");
const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
});

Service with Custom Health Checks

const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
  dnsRecords: [{ type: "SRV", ttl: "10 seconds" }],
  healthCheckCustomConfig: {},
});

Service with Custom Attributes

const service = yield* AWS.CloudMap.Service("Backend", {
  namespaceId: namespace.namespaceId,
  attributes: { tier: "backend", version: "2" },
});

Service: Discovering Instances

// init
const discover = yield* AWS.CloudMap.DiscoverInstances(service);

// runtime
const { Instances } = yield* discover({ HealthStatus: "HEALTHY" });

UpdateInstanceCustomHealthStatus

Source: src/AWS/CloudMap/UpdateInstanceCustomHealthStatus.ts

Runtime binding for servicediscovery:UpdateInstanceCustomHealthStatus — pushes an instance’s health status (HEALTHY / UNHEALTHY) for a service configured with healthCheckCustomConfig. This is the push-based health mechanism: the workload reports its own health instead of being probed by Route 53. Provide the implementation with Effect.provide(AWS.CloudMap.UpdateInstanceCustomHealthStatusHttp).

UpdateInstanceCustomHealthStatus: Instance Health

const updateInstanceCustomHealthStatus =
  yield* AWS.CloudMap.UpdateInstanceCustomHealthStatus(service);

yield* updateInstanceCustomHealthStatus({
  InstanceId: "worker-1",
  Status: "HEALTHY",
});