OpenMCF logoOpenMCF

Loading...

AWS Neptune Cluster

Deploys an Amazon Neptune graph database cluster with automatic subnet group creation, managed security group configuration, configurable cluster instances, optional Serverless v2 scaling, and optional parameter group customization. The component provisions both the cluster and its instances in a single resource definition. Neptune supports property-graph queries via Apache TinkerPop Gremlin and RDF queries via SPARQL.

What Gets Created

When you deploy an AwsNeptuneCluster resource, OpenMCF provisions:

  • Neptune Cluster — a neptune.Cluster with the neptune engine at the specified version, encryption settings, backup configuration, IAM database authentication, optional Serverless v2 scaling, and CloudWatch log exports
  • Cluster Instances — one neptune.ClusterInstance per instanceCount (default 1), each using the specified instanceClass (default db.r6g.large) with promotion tier assignment (primary at tier 0, replicas at tier 1)
  • Neptune Subnet Group — a neptune.SubnetGroup created automatically when subnetIds are provided and neptuneSubnetGroupName is not set, placing the cluster across the specified subnets
  • Security Group — an ec2.SecurityGroup created when securityGroupIds or allowedCidrBlocks are provided, with ingress rules on the cluster port from the specified sources and unrestricted egress
  • Security Group Ingress Rules — one ec2.SecurityGroupRule per source security group and one for CIDR blocks, scoped to the configured port (default 8182)
  • Security Group Egress Rule — an ec2.SecurityGroupRule allowing all outbound traffic
  • Cluster Parameter Group — a neptune.ClusterParameterGroup created when clusterParameters are provided, with the family auto-derived from the engine version (e.g., neptune1.3 for engine version 1.3.0.0)

Prerequisites

  • AWS credentials configured via environment variables or OpenMCF provider config
  • At least two subnets in different Availability Zones, or an existing Neptune subnet group name
  • A VPC ID if creating a managed security group with securityGroupIds or allowedCidrBlocks
  • A KMS key ARN if using a customer-managed key for storage encryption
  • IAM roles if Neptune needs to access S3 for bulk data loading

Quick Start

Create a file neptune.yaml:

apiVersion: aws.openmcf.org/v1
kind: AwsNeptuneCluster
metadata:
  name: my-neptune
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsNeptuneCluster.my-neptune
spec:
  region: us-west-2
  subnetIds:
    - subnet-0a1b2c3d4e5f00001
    - subnet-0a1b2c3d4e5f00002
  storageEncrypted: true
  skipFinalSnapshot: true

Deploy:

openmcf apply -f neptune.yaml

This creates a single-instance Neptune 1.3.0.0 cluster with encrypted storage, IAM-ready authentication, and a db.r6g.large instance in the specified subnets. Unlike relational databases, Neptune does not require a master username or password — access is controlled via IAM database authentication and VPC security groups.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
regionstringAWS region where the Neptune cluster will be created (e.g., us-west-2, eu-west-1).Required; non-empty
subnetIdsStringValueOrRef[]Subnet IDs for the Neptune subnet group. Provide at least two in distinct AZs.Minimum 2 items unless neptuneSubnetGroupName is set. Can reference AwsVpc resource via valueFrom.
finalSnapshotIdentifierstringIdentifier for the final snapshot on deletion.Required when skipFinalSnapshot is false (the default).

Optional Fields

FieldTypeDefaultDescription
neptuneSubnetGroupNameStringValueOrRef—Name of an existing Neptune subnet group. When set, subnetIds is not required.
securityGroupIdsStringValueOrRef[][]Security group IDs used to create ingress rules on the managed security group. Can reference AwsSecurityGroup resources via valueFrom.
allowedCidrBlocksstring[][]IPv4 CIDRs to allow ingress to the managed security group. Must be unique, valid CIDR notation.
vpcIdStringValueOrRef—VPC ID for the managed security group. Can reference AwsVpc resource via valueFrom.
engineVersionstring"1.3.0.0"Neptune engine version. Examples: 1.2.1.0, 1.3.0.0, 1.3.1.0.
portint328182TCP port on which the cluster accepts connections. Valid range: 1-65535.
storageTypestring"standard"Storage I/O model. standard for general use; iopt1 for I/O-Optimized storage with higher throughput and predictable pricing on read-heavy workloads.
instanceCountint321Number of instances to create. First instance is the primary writer; additional instances are read replicas. Minimum: 1.
instanceClassstring"db.r6g.large"Compute and memory capacity of each instance. Use db.serverless for Neptune Serverless (requires serverlessV2Scaling). Examples: db.r6g.large, db.r6g.xlarge, db.r5.large.
serverlessV2Scaling.minCapacitydouble—Minimum Neptune Capacity Units (NCUs) for Serverless v2. Range: 1.0-128.0.
serverlessV2Scaling.maxCapacitydouble—Maximum NCUs for Serverless v2. Must be >= minCapacity. Range: 1.0-128.0.
storageEncryptedbooltrueEncrypts cluster storage at rest.
kmsKeyIdStringValueOrRef—KMS key ARN for storage encryption. Can reference AwsKmsKey resource via valueFrom.
iamDatabaseAuthenticationEnabledboolfalseEnables IAM database authentication, allowing IAM users and roles to authenticate using temporary credentials.
iamRolesStringValueOrRef[][]IAM role ARNs to associate with Neptune for accessing other AWS services (e.g., S3 for bulk data loading). Can reference AwsIamRole resources via valueFrom.
backupRetentionPeriodint327Number of days to retain automated backups. Valid range: 1-35.
preferredBackupWindowstring—Daily backup window in UTC. Format: hh24:mi-hh24:mi (e.g., 03:00-04:00).
preferredMaintenanceWindowstring—Weekly maintenance window in UTC. Format: ddd:hh24:mi-ddd:hh24:mi (e.g., sun:05:00-sun:06:00).
deletionProtectionboolfalsePrevents accidental cluster deletion when enabled.
skipFinalSnapshotboolfalseWhen true, no final snapshot is created on deletion. When false, finalSnapshotIdentifier is required.
enabledCloudwatchLogsExportsstring[][]Log types to export to CloudWatch Logs. Valid values: audit, slowquery.
applyImmediatelyboolfalseApplies modifications immediately instead of during the next maintenance window.
copyTagsToSnapshotboolfalseCopies cluster tags to snapshots.
allowMajorVersionUpgradeboolfalseAllows major engine version upgrades. Required when updating engineVersion to a new major version.
clusterParameterGroupNamestring—Name of an existing Neptune cluster parameter group.
clusterParametersAwsNeptuneClusterParameter[][]Inline cluster parameters. Each entry has name, value, and optional applyMethod (immediate or pending-reboot).

Examples

Production Graph Database with IAM Auth

A Neptune cluster with two instances for high availability, IAM authentication, encrypted storage, and audit logging:

apiVersion: aws.openmcf.org/v1
kind: AwsNeptuneCluster
metadata:
  name: knowledge-graph
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsNeptuneCluster.knowledge-graph
spec:
  region: us-west-2
  subnetIds:
    - subnet-private-az1
    - subnet-private-az2
    - subnet-private-az3
  vpcId: vpc-0a1b2c3d4e5f00001
  securityGroupIds:
    - sg-app-servers
  storageEncrypted: true
  kmsKeyId: arn:aws:kms:us-east-1:123456789012:key/abc-12345
  iamDatabaseAuthenticationEnabled: true
  instanceCount: 2
  instanceClass: db.r6g.xlarge
  storageType: iopt1
  deletionProtection: true
  backupRetentionPeriod: 14
  preferredBackupWindow: "03:00-04:00"
  preferredMaintenanceWindow: "sun:05:00-sun:06:00"
  copyTagsToSnapshot: true
  skipFinalSnapshot: false
  finalSnapshotIdentifier: knowledge-graph-final
  enabledCloudwatchLogsExports:
    - audit
    - slowquery

Neptune Serverless v2

A Neptune Serverless cluster that auto-scales between 2.5 and 64 NCUs based on demand:

apiVersion: aws.openmcf.org/v1
kind: AwsNeptuneCluster
metadata:
  name: serverless-graph
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsNeptuneCluster.serverless-graph
spec:
  region: us-west-2
  subnetIds:
    - subnet-private-az1
    - subnet-private-az2
  storageEncrypted: true
  instanceClass: db.serverless
  serverlessV2Scaling:
    minCapacity: 2.5
    maxCapacity: 64.0
  iamDatabaseAuthenticationEnabled: true
  skipFinalSnapshot: true

Neptune with S3 Bulk Loading

A cluster with IAM roles for loading graph data from S3:

apiVersion: aws.openmcf.org/v1
kind: AwsNeptuneCluster
metadata:
  name: data-loader
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsNeptuneCluster.data-loader
spec:
  region: us-west-2
  subnetIds:
    - subnet-private-az1
    - subnet-private-az2
  storageEncrypted: true
  iamDatabaseAuthenticationEnabled: true
  iamRoles:
    - arn:aws:iam::123456789012:role/NeptuneS3ReadRole
  instanceCount: 2
  enabledCloudwatchLogsExports:
    - audit
  skipFinalSnapshot: false
  finalSnapshotIdentifier: data-loader-final

Using Foreign Key References

Reference other OpenMCF-managed resources instead of hardcoding IDs:

apiVersion: aws.openmcf.org/v1
kind: AwsNeptuneCluster
metadata:
  name: ref-graph
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsNeptuneCluster.ref-graph
spec:
  region: us-west-2
  subnetIds:
    - valueFrom:
        kind: AwsVpc
        name: my-vpc
        field: status.outputs.private_subnets.[0].id
    - valueFrom:
        kind: AwsVpc
        name: my-vpc
        field: status.outputs.private_subnets.[1].id
  vpcId:
    valueFrom:
      kind: AwsVpc
      name: my-vpc
      field: status.outputs.vpc_id
  securityGroupIds:
    - valueFrom:
        kind: AwsSecurityGroup
        name: neptune-sg
        field: status.outputs.security_group_id
  kmsKeyId:
    valueFrom:
      kind: AwsKmsKey
      name: neptune-encryption-key
      field: status.outputs.key_arn
  iamRoles:
    - valueFrom:
        kind: AwsIamRole
        name: neptune-s3-role
        field: status.outputs.role_arn
  storageEncrypted: true
  iamDatabaseAuthenticationEnabled: true
  skipFinalSnapshot: false
  finalSnapshotIdentifier: ref-graph-final

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
cluster_endpointstringThe primary writer endpoint for the Neptune cluster (Gremlin/SPARQL queries)
cluster_reader_endpointstringThe reader endpoint for load-balanced read traffic across replicas
cluster_idstringThe AWS identifier of the Neptune cluster
cluster_arnstringThe Amazon Resource Name of the Neptune cluster
cluster_resource_idstringThe internal AWS resource identifier
cluster_portint32The port on which the cluster accepts connections (default 8182)
db_subnet_group_namestringThe subnet group name (only when created by the module)
security_group_idstringThe security group ID (only when created by the module)
cluster_parameter_group_namestringThe parameter group name (only when created by the module)
hosted_zone_idstringThe Route 53 hosted zone ID for the cluster endpoint

Related Components

  • AwsVpc — provides subnets and VPC ID for cluster placement
  • AwsSecurityGroup — controls network access to the cluster
  • AwsKmsKey — provides KMS keys for storage encryption
  • AwsIamRole — provides IAM roles for S3 bulk data loading
  • AwsRoute53Zone — hosts DNS zones for CNAME records pointing to the cluster endpoint

Next article

AWS Network Load Balancer

AWS Network Load Balancer Deploys an AWS Network Load Balancer with bundled listeners and target groups, optional static IP addresses via Elastic IP allocation, TLS termination, and Route53 DNS record management. The component operates at Layer 4 (TCP/UDP/TLS) and requires at least one subnet mapping and one listener. What Gets Created When you deploy an AwsNetworkLoadBalancer resource, OpenMCF provisions: Network Load Balancer — an awslb resource of type network, placed in the specified...
Read next article
Presets
3 ready-to-deploy configurationsView presets →