Prerequisites
Python Runtime
Section titled “Python Runtime”- Python 3.11 or higher is required.
AWS IAM Permissions
Section titled “AWS IAM Permissions”The IAM role or user you run nx-neptune as needs the following permissions, depending on the features you use. Neptune Analytics also needs an import role to read and write S3. With SessionManager and the proxy UI, that is the same role you run as. An example policy at the end of this section combines the main permissions.
Graph query operations
Section titled “Graph query operations”Required to read, write, and manage graph data via queries:
neptune-graph:ReadDataViaQueryneptune-graph:WriteDataViaQueryneptune-graph:DeleteDataViaQuery
Graph management
Section titled “Graph management”Required access to Neptune Analytics graphs:
neptune-graph:CreateGraphneptune-graph:CreateGraphUsingImportTaskneptune-graph:GetGraphneptune-graph:ListGraphsneptune-graph:UpdateGraphneptune-graph:ResetGraphneptune-graph:StartGraphneptune-graph:StopGraphneptune-graph:DeleteGraphneptune-graph:TagResource
Note: ResetGraph and DeleteGraph delete graph data.
Note: nx-neptune tags every graph and snapshot it creates with agent=nx-neptune, which is why TagResource is needed wherever creation is.
Snapshots
Section titled “Snapshots”Required to save/restore a Neptune Analytics snapshot:
neptune-graph:CreateGraphSnapshotneptune-graph:GetGraphSnapshotneptune-graph:RestoreGraphFromSnapshotneptune-graph:DeleteGraphSnapshotneptune-graph:TagResource
S3 import/export
Section titled “S3 import/export”Required to import/export between S3 and Neptune Analytics:
neptune-graph:StartImportTaskneptune-graph:GetImportTaskneptune-graph:StartExportTaskneptune-graph:GetExportTask
nx-neptune stages CSV files in S3, deletes them after an import, and checks the bucket’s settings. On the staging and export buckets, this needs:
s3:GetObjects3:PutObjects3:DeleteObjects3:ListBuckets3:GetBucketVersionings3:GetEncryptionConfigurationkms:Decrypt,kms:GenerateDataKeyandkms:DescribeKeyon the bucket’s KMS key
Note: The S3 buckets nx-neptune writes to or deletes from (staging, Athena query results and export destinations) must have versioning enabled, and should be in the same region as your graphs. Otherwise imports, exports and Athena projections fail before any query runs. To enable versioning:
aws s3api put-bucket-versioning --bucket <bucket> --versioning-configuration Status=EnabledBecause nx-neptune deletes its staged files, a versioned bucket keeps their old versions. A lifecycle rule that expires noncurrent versions avoids paying to store them.
Import role
Section titled “Import role”Neptune Analytics reads S3 for imports, and writes S3 for exports, using an IAM role that nx-neptune passes to it in StartImportTask, CreateGraphUsingImportTask and StartExportTask. With SessionManager and the proxy UI, that role is the one you are running as. With the NetworkX backend, it is s3_iam_role in NeptuneConfig if you set it, otherwise again your own role.
The import role must:
-
Trust
neptune-graph.amazonaws.com, with noaws:SourceAccountoraws:SourceArncondition:{"Effect": "Allow","Principal": { "Service": "neptune-graph.amazonaws.com" },"Action": "sts:AssumeRole"}With those conditions,
StartImportTaskfails withThe S3 arn ... is inaccessible or your role does not have access to it, even though the cause is the trust policy. -
Have
s3:GetObjectands3:ListBucketon the staging location andkms:Decrypton its key for imports, ands3:PutObjecton the destination for exports.
The role you run as needs these actions on the import role:
iam:PassRole, with the conditioniam:PassedToService=neptune-graph.amazonaws.comiam:GetRoleandiam:SimulatePrincipalPolicy, which nx-neptune uses to check the import role before an import or export
With SessionManager and the proxy UI, the role you run as is the import role, so it needs both sets of permissions and the trust statement. IAM Identity Center (SSO) permission-set roles can’t have their trust policy edited, so with SSO, assume a separate role that meets these requirements (for example with aws sts assume-role) and run nx-neptune with its credentials.
Athena (for data lake integration)
Section titled “Athena (for data lake integration)”Required to read from/write to a Catalog through Athena:
athena:StartQueryExecutionathena:GetQueryExecutionathena:GetQueryResultsathena:GetTableMetadata(forCREATE PROPERTY GRAPH, which reads source table columns)glue:GetDatabaseglue:GetDatabasesglue:GetTableglue:GetTablesglue:GetPartitions
Queries run in the primary workgroup unless you set NETWORKX_ATHENA_WORKGROUP. Athena writes query results to S3, so the query results bucket also needs s3:GetBucketLocation, s3:GetObject and s3:PutObject. Reading source tables needs s3:GetObject and s3:ListBucket on the buckets behind them.
To export results to Iceberg tables:
glue:CreateTableglue:UpdateTableglue:DeleteTable
To query federated catalogs (for example Databricks, Snowflake or S3 Vectors), also allow lambda:InvokeFunction on each connector’s Lambda function. The permissions to read the source (for example the Databricks secret, or S3 Vectors) belong to the connector Lambda’s execution role, not to you.
S3 Tables
Section titled “S3 Tables”To query Amazon S3 Tables through Athena, also allow:
s3tables:GetTableBuckets3tables:GetNamespaces3tables:GetTables3tables:GetTableDatas3tables:GetTableMetadataLocationlakeformation:GetDataAccess
Embedding helpers
Section titled “Embedding helpers”The to_embedding_entries and push_to_s3_vector helpers in nx_neptune.utils, used by the vector embedding notebooks, call Amazon Bedrock and Amazon S3 Vectors directly:
bedrock:InvokeModel(forto_embedding_entries)s3vectors:PutVectors(forpush_to_s3_vector)
Proxy UI
Section titled “Proxy UI”The proxy UI also lists catalogs, databases, tables, buckets and graph summaries, which needs:
athena:ListDataCatalogsathena:ListDatabasesathena:GetDatabaseathena:ListTableMetadataneptune-graph:GetGraphSummarys3:ListAllMyBuckets
Example policy
Section titled “Example policy”This policy combines graph management, S3 import/export, Athena, the import role and the proxy UI, following the CloudFormation template. Add the actions from the other sections for the features you use. Replace the placeholders:
| Placeholder | Value |
|---|---|
<region>, <account-id> |
Region and account of your graphs |
<bucket> |
Staging bucket, also used for Athena query results |
<kms-key-id> |
KMS key that encrypts the bucket |
<database> |
Glue database with your source tables. Repeat the database/ and table/ lines for each database |
<import-role-name> |
Import role (with SessionManager and the proxy, the role you run as) |
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ListResources", "Effect": "Allow", "Action": [ "athena:ListDataCatalogs", "s3:ListAllMyBuckets" ], "Resource": "*" }, { "Sid": "NeptuneAnalytics", "Effect": "Allow", "Action": [ "neptune-graph:ListGraphs", "neptune-graph:CreateGraph", "neptune-graph:CreateGraphUsingImportTask", "neptune-graph:GetGraph", "neptune-graph:UpdateGraph", "neptune-graph:ResetGraph", "neptune-graph:StartGraph", "neptune-graph:StopGraph", "neptune-graph:DeleteGraph", "neptune-graph:TagResource", "neptune-graph:StartImportTask", "neptune-graph:GetImportTask", "neptune-graph:StartExportTask", "neptune-graph:GetExportTask" ], "Resource": "*" }, { "Sid": "NeptuneAnalyticsTaggedGraphs", "Effect": "Allow", "Action": [ "neptune-graph:GetGraphSummary", "neptune-graph:ReadDataViaQuery", "neptune-graph:WriteDataViaQuery", "neptune-graph:DeleteDataViaQuery" ], "Resource": "arn:aws:neptune-graph:<region>:<account-id>:graph/*", "Condition": { "StringEquals": { "aws:ResourceTag/agent": "nx-neptune" } } }, { "Sid": "AthenaCatalogMetadata", "Effect": "Allow", "Action": [ "athena:ListDatabases", "athena:GetDatabase", "athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource": "arn:aws:athena:<region>:<account-id>:datacatalog/*" }, { "Sid": "AthenaQueries", "Effect": "Allow", "Action": [ "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:GetQueryResults" ], "Resource": "*" }, { "Sid": "GlueReadCatalog", "Effect": "Allow", "Action": [ "glue:GetDatabase", "glue:GetDatabases", "glue:GetTable", "glue:GetTables", "glue:GetPartitions" ], "Resource": [ "arn:aws:glue:<region>:<account-id>:catalog", "arn:aws:glue:<region>:<account-id>:database/<database>", "arn:aws:glue:<region>:<account-id>:table/<database>/*" ] }, { "Sid": "S3Staging", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket", "s3:GetBucketLocation", "s3:GetBucketVersioning", "s3:GetEncryptionConfiguration" ], "Resource": [ "arn:aws:s3:::<bucket>", "arn:aws:s3:::<bucket>/*" ] }, { "Sid": "KMSForBucket", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey" ], "Resource": "arn:aws:kms:<region>:<account-id>:key/<kms-key-id>" }, { "Sid": "CheckImportRole", "Effect": "Allow", "Action": [ "iam:GetRole", "iam:SimulatePrincipalPolicy" ], "Resource": "arn:aws:iam::<account-id>:role/<import-role-name>" }, { "Sid": "PassImportRole", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::<account-id>:role/<import-role-name>", "Condition": { "StringEquals": { "iam:PassedToService": "neptune-graph.amazonaws.com" } } } ]}athena:ListDataCatalogs and s3:ListAllMyBuckets don’t support resource-level permissions, so they use "*". With the Glue statement limited to your databases, the proxy UI lists only those databases, and validation fails early for tables in others. The import role also needs the trust statement in Import role, and read access to your source tables’ buckets isn’t included.
Environment Variables
Section titled “Environment Variables”| Variable | Purpose |
|---|---|
NETWORKX_GRAPH_ID |
Neptune Analytics graph identifier |
NETWORKX_S3_IAM_ROLE_ARN |
Optional import role ARN for the NetworkX backend; defaults to the caller identity. Read at nx_neptune import time, so set it before starting Jupyter. Does not apply to SessionManager, which builds its role from the caller identity |
NETWORKX_S3_IMPORT_BUCKET_PATH |
S3 path for imports |
NETWORKX_S3_EXPORT_BUCKET_PATH |
S3 path for exports |
AWS_REGION |
AWS region |
NETWORKX_PUBLIC_CONNECTIVITY |
Give new graphs a public endpoint (default false) |
NETWORKX_DELETION_PROTECTION |
Enable deletion protection on new graphs (default true) |
NETWORKX_ATHENA_WORKGROUP |
Athena workgroup for queries (default primary) |