AWS CDK Service Discovery (Cloud Map)

1.204.0 · maintenance · verified Fri Apr 17

The `aws-cdk-aws-servicediscovery` package provides AWS Cloud Development Kit (CDK) constructs for AWS Cloud Map (Service Discovery). It allows you to define and manage DNS-based service discovery for your applications within AWS infrastructure as code. This package is part of the CDK v1 ecosystem, and its functionality is integrated into `aws-cdk-lib` for CDK v2. The current version is 1.204.0, following the release cadence of AWS CDK v1.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_servicediscovery'
```
cause The `aws-cdk-aws-servicediscovery` Python package has not been installed in your environment, or `aws-cdk.core` is missing.

fix Run `pip install aws-cdk-aws-servicediscovery aws-cdk.core` to install the necessary packages for CDK v1.
```
TypeError: Object of type <class 'aws_cdk.aws_servicediscovery.PublicDnsNamespace'> is not JSON serializable
```
cause This error or similar `TypeError` can occur when attempting to mix AWS CDK v1 constructs (like those from `aws-cdk-aws-servicediscovery`) with a CDK v2 core (`aws-cdk-lib`). The object models are incompatible.

fix Standardize your project on either CDK v1 (using `aws-cdk.core` and `aws-cdk.aws-*` packages) or CDK v2 (using `aws-cdk-lib`). This library is v1-specific.
```
Validation failed with message: 'vpc' must be specified for private DNS namespaces (ServiceDiscoveryPrivateDnsNamespacexxxx)
```
cause You are attempting to create a `PrivateDnsNamespace` without providing a `vpc` property, which is required for private namespaces.

fix Ensure you pass an `aws_ec2.Vpc` object to the `vpc` argument when instantiating `servicediscovery.PrivateDnsNamespace`.

Warnings

breaking This package (`aws-cdk-aws-servicediscovery`) is for AWS CDK v1. AWS CDK v2 has consolidated all `aws-cdk.aws-*` packages into `aws-cdk-lib`. Mixing v1 and v2 packages will lead to runtime errors.
Fix: For new projects or migration, use CDK v2 and import `aws_cdk.aws_servicediscovery` from `aws_cdk.aws_servicediscovery` after installing `aws-cdk-lib`. For existing v1 projects, ensure all CDK packages (`aws-cdk.core` and `aws-cdk.aws-*`) are consistently v1.
gotcha When creating a `PrivateDnsNamespace`, you *must* associate it with an existing VPC. Forgetting this will cause CloudFormation deployment failures.
Fix: Ensure you provide a `vpc` property, typically an `aws_ec2.Vpc` object, when instantiating `servicediscovery.PrivateDnsNamespace`.
gotcha Cloud Map service instances registered via IP (`register_ip_instance`) are not automatically deregistered if the underlying resource (e.g., an EC2 instance) is terminated outside of CDK's control. This can lead to stale DNS records.
Fix: Implement custom lifecycle hooks or monitoring to deregister instances when the associated resource is terminated. For EC2 instances, consider using Auto Scaling Groups with integrated Cloud Map support.

Install

pip install aws-cdk-aws-servicediscovery aws-cdk.core Install for CDK v1

Imports

aws_servicediscovery
wrong:
```
from aws_cdk_lib import aws_servicediscovery
```
correct:
```
from aws_cdk import aws_servicediscovery
```
This package is for CDK v1. For CDK v2, the `aws_servicediscovery` module is imported from `aws_cdk.aws_servicediscovery` within the `aws-cdk-lib` package.

PublicDnsNamespace

from aws_cdk.aws_servicediscovery import PublicDnsNamespace

PrivateDnsNamespace

from aws_cdk.aws_servicediscovery import PrivateDnsNamespace

Service

from aws_cdk.aws_servicediscovery import Service

Quickstart

This quickstart demonstrates how to create a Public DNS Namespace and register an IP-based service instance using AWS CDK v1. This sets up a discoverable DNS record (e.g., `web-api.example.com`) that can be resolved by clients.

import os
from aws_cdk import ( 
    core, 
    aws_servicediscovery as servicediscovery
)

class MyServiceDiscoveryStack(core.Stack):
    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create a Public DNS Namespace
        # This will create a Route 53 Hosted Zone for your services.
        public_dns_namespace = servicediscovery.PublicDnsNamespace(
            self, "MyPublicNamespace",
            name="example.com"
        )

        # Create a service within the namespace
        # This service will have an A record by default for IP instances.
        service = public_dns_namespace.create_service(
            "MyPublicWebService",
            name="web-api"
        )

        # Register an IP instance with the service
        # Applications can now discover 'web-api.example.com'
        service.register_ip_instance(
            "WebInstance1",
            ip="192.0.2.100", # Example IP address, replace with actual target
            port=80
        )

# Instantiate and synthesize the CDK app
app = core.App()
MyServiceDiscoveryStack(app, os.environ.get('CDK_STACK_NAME', 'ServiceDiscoveryQuickstartStack'))
app.synth()

view raw JSON →