AWS CDK AWS Neptune (Alpha)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_neptune_alpha'

  cause The `aws-cdk-aws-neptune-alpha` package has not been installed or is not accessible in the current Python environment.
  fix Run `pip install aws-cdk-aws-neptune-alpha` in your virtual environment. Ensure your `requirements.txt` includes this package and you've run `pip install -r requirements.txt`.

• AttributeError: 'DatabaseCluster' object has no attribute 'old_api_method'

  cause You are using an older (or newer) version of the `aws-cdk-aws-neptune-alpha` library, and an API method, property, or construct has been renamed, removed, or changed due to its alpha status.
  fix Consult the release notes or the latest API documentation for the `aws-cdk-aws-neptune-alpha` version you are using. Update your code to reflect the current API. Consider pinning your `aws-cdk-aws-neptune-alpha` version if stability is critical.

• CloudFormation deployment failed: The requested DBInstanceClass is not available for the specified EngineVersion and Availability Zone.

  cause The combination of the chosen `InstanceType`, `EngineVersion`, and potentially `vpc.availability_zones` is not supported by AWS Neptune in the region you are deploying to, or the specified engine version is outdated/invalid.
  fix Verify the selected `neptune.InstanceType` and `neptune.EngineVersion` against the official AWS Neptune documentation for your chosen AWS region. Ensure your VPC has sufficient available AZs that support the instance type.

• User: arn:aws:iam::ACCOUNT_ID:user/IAM_USER is not authorized to perform: neptune:CreateDBCluster on resource: arn:aws:neptune:REGION:ACCOUNT_ID:db-cluster/DB_CLUSTER_ID

  cause The IAM user or role attempting to deploy the CDK stack lacks the necessary permissions to create or manage Neptune resources.
  fix Attach an IAM policy to the deploying user/role that grants permissions like `neptune:CreateDBCluster`, `neptune:DeleteDBCluster`, `neptune:ModifyDBCluster`, `neptune:CreateDBInstance`, `ec2:CreateSecurityGroup`, etc., or use the `AdministratorAccess` managed policy for development environments.

Warnings

• breaking This module is in 'alpha' status. Its APIs are experimental and subject to non-backward compatible changes or removal in any future version. It does not adhere to semantic versioning, and breaking changes will be announced in release notes, requiring source code updates when upgrading.
  Fix: Refer to the release notes on the AWS CDK GitHub repository or official documentation before upgrading. Be prepared to update your code to match new API signatures or construct names.
• gotcha Neptune clusters *must* be launched within a VPC. Attempting to deploy a DatabaseCluster without specifying a valid VPC will result in CloudFormation deployment failures.
  Fix: Always pass a `vpc` property to the `DatabaseCluster` construct. Ensure the VPC has available private subnets and NAT Gateways for outbound internet access if required for engine updates or external services.
• gotcha The `EngineVersion` enum and available `InstanceType` options within the CDK construct might not automatically reflect the very latest versions or instance types supported by AWS Neptune. Using an unsupported version will lead to deployment errors.
  Fix: If a new engine version or instance type is released and not yet available in the enum, you can use `neptune.EngineVersion.of('your-new-version')` or `neptune.InstanceType.of('db.r6g.large')` to specify it as a string. Always check the official AWS Neptune documentation for the latest supported versions and instance types.
• gotcha Configuring IAM database authentication for Neptune requires careful setup of IAM policies and granting connect permissions to specific roles or users. Misconfigured IAM can lead to connection errors.
  Fix: Enable `iam_authentication=True` on your `DatabaseCluster` and use `cluster.grant_connect(iam_role)` to grant connection permissions to specific IAM roles or users. Ensure your application's IAM role has the necessary `neptune-db:connect` permissions.

Install

• pip install aws-cdk-aws-neptune-alpha Install library

Imports

• aws_neptune_alpha

  import aws_cdk.aws_neptune_alpha as neptune

  Standard import alias for Neptune alpha constructs.
• aws_ec2

  import aws_cdk.aws_ec2 as ec2

  Required for defining VPCs, which Neptune clusters depend on.
• cdk

  import aws_cdk as cdk

  Standard import for the core AWS CDK library.

Quickstart

This quickstart deploys a basic AWS Neptune Database Cluster within a new VPC. It defines a `Vpc`, then instantiates `neptune.DatabaseCluster` with a specified instance type and engine version, and finally adds a security group rule to allow connections. The cluster's endpoint is exported as a CloudFormation output.

import aws_cdk as cdk
from aws_cdk import (Stack,
                     aws_ec2 as ec2,
                     aws_neptune_alpha as neptune)

class NeptuneStack(Stack):
    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create a VPC for the Neptune cluster
        vpc = ec2.Vpc(self, "Vpc",
                      max_azs=2,  # Use 2 Availability Zones
                      nat_gateways=1)

        # Create a Neptune Database Cluster
        # Note: instanceType requires an 'alpha' prefix for some versions/runtimes
        cluster = neptune.DatabaseCluster(self, "NeptuneDatabase",
                                          vpc=vpc,
                                          instance_type=neptune.InstanceType.R5_LARGE,
                                          engine_version=neptune.EngineVersion.V1_2_0_0)

        # Add a default security group rule to allow connections
        cluster.connections.allow_default_port_from_any_ipv4("Allow connections from anywhere")

        # Output the cluster endpoint
        cdk.CfnOutput(self, "NeptuneClusterEndpoint",
                      value=cluster.cluster_endpoint.socket_address,
                      description="The endpoint address of the Neptune Cluster")

app = cdk.App()
NeptuneStack(app, "NeptuneAlphaQuickstartStack")
app.synth()