Deploy a data plane on AWS¶

This topic introduces how to deploy a data plane in your AWS account through NebulaGraph Cloud. You use the provided Terraform template to create the IAM roles that authorize AWS access, then submit their ARNs in NebulaGraph Cloud to start infrastructure deployment.

Opened from View Guide?

If you are already on Credential Settings, start at Step 2. Copy the deployment parameters. Keep that platform tab open and return to it after obtaining the two role ARNs.

Prerequisites¶

A BYOC organization with its license configured, and its sole project.
Organization Owner or Project Admin for platform deployment operations. Only the Organization Owner creates a project.
A standard commercial AWS account, excluding AWS China and AWS GovCloud accounts. The AWS identity running Terraform must be allowed to create, read, and tag IAM roles and policies, and attach policies. AWS Organizations service control policies (SCPs) and permissions boundaries must also permit these operations.
A macOS or Linux terminal using Bash or zsh, Terraform 1.14.0 or later, and AWS CLI v2.
Network access to the template download URL and Terraform Registry/provider download services. The published template pins the AWS provider to 6.55.0.

Step 1. Create the data plane record¶

Sign in to NebulaGraph Cloud and select your BYOC organization from the top organization menu.
On Projects, open the existing project. If there is no project, the Organization Owner clicks Create Project, enters a project name, and clicks Create and Next.
In the project's left navigation, click Data Plane, then Deploy Data Plane.
Enter Data Plane Name, keep AWS as the Cloud Provider, and select an available Region. Record the AWS region code, such as us-east-2.
Click Next. The platform creates a Pending record and opens Credential Settings. This has not started infrastructure deployment.

Closing the dialog after Next leaves the Pending record. To continue, open Data Plane and click Deploy on its card; do not try to create a second data plane.

Step 2. Copy the deployment parameters¶

On Deploy Data Plane → Credential Settings, copy External ID and Principal. Use the region selected in Step 1.

Platform value	Terraform input	How to fill it
Region	`region`	Selected AWS region code
External ID (data plane ID)	`prefix_name` and `external_id`	Use the same platform-provided ID for both
Principal	`nebula_principal_arn`	Copy the complete platform-provided IAM ARN

Do not generate your own ID or replace it with the display name. Both role trust policies require this External ID and the provided Principal.

Step 3. Create the IAM roles with Terraform¶

In your local terminal, download the IAM template, authenticate to AWS, and create the two roles. Keep Credential Settings open in NebulaGraph Cloud so you can return the role ARNs in Step 4.

The interactive guide shows command and configuration examples, followed by a screenshot from a previous successful Terraform apply. Replace the placeholders with your own values when following the procedure below.

3.1. Download and extract the IAM template¶

Download the official AWS BYOC IAM template. In your local terminal, create a dedicated directory for this data plane and extract the archive. Use an empty directory for a first deployment; change the example path if it is already used for another data plane:

mkdir -p ~/nebula-byoc/aws-byoc-iam
cd ~/nebula-byoc/aws-byoc-iam
curl --fail --location \
  'https://nebula-cloud-prod-public-us-east-2.s3.us-east-2.amazonaws.com/byoc/aws-byoc-iam.tar.gz' \
  --output aws-byoc-iam.tar.gz
tar -xzf aws-byoc-iam.tar.gz

Run all subsequent Terraform commands from this directory. The .tf files are extracted directly into it. Create terraform.tfvars in section 3.3 with the values from your data plane. If resuming setup, use the original directory and state.

3.2. Authenticate and verify the AWS account¶

The examples use byoc-customer as the local AWS CLI profile name. Use the profile configured for your AWS account, or create one with this name. This name is independent of your NebulaGraph Cloud organization name.

If your company uses AWS IAM Identity Center for single sign-on (SSO), configure an AWS CLI profile once, then sign in:

aws configure sso --profile byoc-customer
aws sso login --profile byoc-customer

For an existing SSO profile, run only the login command. If your organization uses access keys, configure them locally with aws configure --profile byoc-customer.

Select the profile and verify your identity:

export AWS_PROFILE=byoc-customer
aws sts get-caller-identity

Check that the output's Account is the customer AWS account where you intend to deploy BYOC. If it is incorrect, stop and resolve the profile issue before proceeding. AWS credentials stay local; do not put them in terraform.tfvars or provide them to NebulaGraph Cloud.

3.3. Create terraform.tfvars¶

Create terraform.tfvars in the working directory with the following complete content. Replace all placeholders with Step 2 values:

region               = "<DATAPLANE_REGION>"
prefix_name          = "<DATAPLANE_ID>"
external_id          = "<DATAPLANE_ID>"
nebula_principal_arn = "<NEBULA_AWS_PRINCIPAL_ARN>"

Keep the template's .tf files unchanged. prefix_name and external_id must contain the same External ID.

3.4. Review and apply the IAM plan¶

Initialize Terraform, then save an execution plan:

terraform init
terraform plan -out=tfplan

On the first run, Terraform plans to create 24 IAM resources: 2 roles, 11 policies, and 11 policy attachments. The plan summary is:

Plan: 24 to add, 0 to change, 0 to destroy.

On subsequent runs, Terraform compares the configuration with the existing resources and plans the changes needed to match it.

Before applying, review the permissions and changes. Verify the target AWS account, role names <DATAPLANE_ID>-deployment-role and <DATAPLANE_ID>-runtime-role, the trust policy's Principal, and its sts:ExternalId condition. To inspect the saved plan again, run terraform show tfplan.

Warning

Applying a saved plan changes IAM authorization immediately and does not ask you to type yes. Apply only after reviewing it. If you change inputs after saving the plan, generate a new plan first.

terraform apply tfplan

Wait for Apply complete! and the two role ARN outputs. If the command fails partway through, retain the directory and state, fix the cause, and generate a new plan in the same directory.

Step 4. Return the role ARNs to the platform¶

Obtain Deployment Role ARN without quotation marks:

terraform output -raw deployment_role_arn

Then obtain Runtime Role ARN separately:

terraform output -raw runtime_role_arn

In the original Credential Settings tab, fill the corresponding fields:

Terraform output	Platform field
`deployment_role_arn`	Deployment Role ARN
`runtime_role_arn`	Runtime Role ARN

Each value is a complete arn:aws:iam::<CUSTOMER_ACCOUNT_ID>:role/<ROLE_NAME> string. Verify that both role ARNs contain the AWS account ID confirmed in section 3.2. Enter deployment_role_arn in Deployment Role ARN and runtime_role_arn in Runtime Role ARN.

Step 5. Start deployment and verify Running¶

Click Review to open Deployment Summary.
Check the data plane name, AWS provider, region, and both role ARNs.
Click Deploy. The platform uses the authorization to deploy infrastructure in your AWS account; AWS resources can incur charges.
Open the data plane's details and follow Deployment Timeline and SYSTEM LOGS to monitor progress.
When the data plane status is Running, create a database. If it becomes Failed, use Troubleshooting.

Note

Data plane deployment typically takes 15–20 minutes. The status shows Deploying while infrastructure is being created in your AWS account. Wait until the status changes to Running before creating a database.

Retain the authorization files¶

Keep the working directory, terraform.tfvars, terraform.tfstate, and .terraform.lock.hcl securely for future output inspection and authorization updates. Do not commit state, credentials, or saved plans to a public repository. To view the ARNs later, run terraform output in the original directory.

The roles are needed for operation and cleanup. Delete the data plane and verify infrastructure cleanup before revoking or removing IAM authorization. Running terraform destroy in this IAM directory removes authorization; it does not delete the platform-created data plane infrastructure.