{"id":9528,"library":"aws-cdk-aws-servicediscovery","title":"AWS CDK Service Discovery (Cloud Map)","description":"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.","status":"maintenance","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","cloudformation","infrastructure-as-code","servicediscovery","cloudmap","dns"],"install":[{"cmd":"pip install aws-cdk-aws-servicediscovery aws-cdk.core","lang":"bash","label":"Install for CDK v1"}],"dependencies":[{"reason":"Core CDK functionalities like Stack and Construct are required.","package":"aws-cdk.core","optional":false},{"reason":"Required for creating Private DNS Namespaces which must be associated with a VPC.","package":"aws-cdk.aws-ec2","optional":true},{"reason":"Indirectly used by Public DNS Namespaces.","package":"aws-cdk.aws-route53","optional":true}],"imports":[{"note":"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.","wrong":"from aws_cdk_lib import aws_servicediscovery","symbol":"aws_servicediscovery","correct":"from aws_cdk import aws_servicediscovery"},{"symbol":"PublicDnsNamespace","correct":"from aws_cdk.aws_servicediscovery import PublicDnsNamespace"},{"symbol":"PrivateDnsNamespace","correct":"from aws_cdk.aws_servicediscovery import PrivateDnsNamespace"},{"symbol":"Service","correct":"from aws_cdk.aws_servicediscovery import Service"}],"quickstart":{"code":"import os\nfrom aws_cdk import ( \n    core, \n    aws_servicediscovery as servicediscovery\n)\n\nclass MyServiceDiscoveryStack(core.Stack):\n    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Create a Public DNS Namespace\n        # This will create a Route 53 Hosted Zone for your services.\n        public_dns_namespace = servicediscovery.PublicDnsNamespace(\n            self, \"MyPublicNamespace\",\n            name=\"example.com\"\n        )\n\n        # Create a service within the namespace\n        # This service will have an A record by default for IP instances.\n        service = public_dns_namespace.create_service(\n            \"MyPublicWebService\",\n            name=\"web-api\"\n        )\n\n        # Register an IP instance with the service\n        # Applications can now discover 'web-api.example.com'\n        service.register_ip_instance(\n            \"WebInstance1\",\n            ip=\"192.0.2.100\", # Example IP address, replace with actual target\n            port=80\n        )\n\n# Instantiate and synthesize the CDK app\napp = core.App()\nMyServiceDiscoveryStack(app, os.environ.get('CDK_STACK_NAME', 'ServiceDiscoveryQuickstartStack'))\napp.synth()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All v1.x.x versions when used with v2 core."},{"fix":"Ensure you provide a `vpc` property, typically an `aws_ec2.Vpc` object, when instantiating `servicediscovery.PrivateDnsNamespace`.","message":"When creating a `PrivateDnsNamespace`, you *must* associate it with an existing VPC. Forgetting this will cause CloudFormation deployment failures.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install aws-cdk-aws-servicediscovery aws-cdk.core` to install the necessary packages for CDK v1.","cause":"The `aws-cdk-aws-servicediscovery` Python package has not been installed in your environment, or `aws-cdk.core` is missing.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_servicediscovery'"},{"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.","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.","error":"TypeError: Object of type <class 'aws_cdk.aws_servicediscovery.PublicDnsNamespace'> is not JSON serializable"},{"fix":"Ensure you pass an `aws_ec2.Vpc` object to the `vpc` argument when instantiating `servicediscovery.PrivateDnsNamespace`.","cause":"You are attempting to create a `PrivateDnsNamespace` without providing a `vpc` property, which is required for private namespaces.","error":"Validation failed with message: 'vpc' must be specified for private DNS namespaces (ServiceDiscoveryPrivateDnsNamespacexxxx)"}]}