Create cluster example
The following tutorial shows how you can use ybm CLI to create clusters in YugabyteDB Aeon. The example shows how to use the cluster resource.
Prerequisites
This guide assumes you have already done the following:
- Created and saved an API key.
- Installed ybm CLI.
- Configured ybm CLI with your API key.
To create VPCs and dedicated clusters, you need to choose a plan, or you can start a free trial.
Create dedicated clusters
Create a single-region cluster
The following command creates a single-region dedicated cluster in Tokyo:
ybm cluster create \
--credentials username=admin,password=password \
--cloud-provider AWS \
--cluster-type SYNCHRONOUS \
--region-info region=ap-northeast-1,num-nodes=3,num-cores=4,disk-size-gb=200 \
--cluster-tier Dedicated \
--fault-tolerance ZONE \
--database-version Rapid \
--cluster-name my-single-region \
--wait
The cluster my-single-region has been created
Name Tier Version State Health Regions Nodes Total Res.(Vcpu/Mem/Disk)
my-single-region Dedicated 2.17.2.0-b216 ACTIVE 💚 ap-northeast-1 3 12 / 48GB / 600GB
Create a VPC and multi-region cluster
Multi-region clusters must be deployed in a VPC. The following example creates a VPC on GCP:
ybm vpc create \
--name gcp-vpc \
--cloud-provider GCP \
--global-cidr 10.0.0.0/18 \
--wait
The VPC gcp-vpc has been created
Name State Provider Region[CIDR] Peerings Clusters
gcp-vpc ACTIVE GCP asia-southeast2[10.0.19.0/24],+27 0 0
To list the available regions in GCP:
ybm region list --cloud-provider GCP
The following command creates a replicate-across-regions cluster in the VPC you created:
ybm cluster create \
--cluster-name my-multi-region \
--credentials username=admin,password=password \
--cloud-provider GCP \
--cluster-type SYNCHRONOUS \
--region-info region=us-east1,num-nodes=1,num-cores=2,disk-size-gb=200,vpc=gcp-vpc \
--region-info region=us-west1,num-nodes=1,num-cores=2,disk-size-gb=200,vpc=gcp-vpc \
--region-info region=us-central1,num-nodes=1,num-cores=2,disk-size-gb=200,vpc=gcp-vpc \
--cluster-tier Dedicated \
--fault-tolerance REGION \
--database-version Extended \
--wait
The cluster my-multi-region has been created
Name Tier Version State Health Regions Nodes Total Res.(Vcpu/Mem/Disk)
my-multi-region Dedicated 2.14.7.0-b51 ACTIVE 💚 us-central1,+2 3 6 / 24GB / 600GB
Scale your cluster
Use the ybm cluster update command with --region-info flag to scale your cluster by adding or removing nodes, cores, and disk size. You can also change the region name. For example, to change the number of nodes in the us-east1 region from 1 to 3, and the number of cores from 2 to 4, enter the following command:
ybm cluster update \
--cluster-name my-multi-region \
--region-info region=us-east1,num-nodes=3,num-cores=4,disk-size-gb=250 \
--wait
For more information, see Scale and configure clusters.
Connect to your cluster
To connect to your database from your desktop or an application, you need the following:
- your device added to the cluster IP allow list
- the cluster TLS certificate
- the host address of the cluster
The following example connects to the single-region cluster my-single-region.
Create and assign an IP allow list
To connect to your cluster from your computer, you need an IP allow list with your computer's IP address. Create one as follows:
ybm network-allow-list create \
--ip-addr $(curl ifconfig.me) \
--name my-computer
Name Description Allow List Clusters
my-computer 170.200.10.100/32
NetworkAllowList my-computer successfully created
Assign the IP allow list to the cluster:
ybm cluster network allow-list assign \
--network-allow-list my-computer \
--cluster-name my-single-region
The network allow list my-computer is being assigned to the cluster my-single-region
To list your current network allow lists, enter the following command:
ybm network-allow-list list
Name Description Allow List Clusters
my-computer 173.206.17.104/32 my-single-region
Download the cluster certificate
To connect to a cluster in YugabyteDB Aeon using a shell, you need the cluster certificate. Download the certificate using the following command:
ybm cluster cert download --out $HOME/root.crt
Show cluster settings
To show details about your cluster, use the describe command as follows:
ybm cluster describe --cluster-name my-single-region
General
Name ID Version State Health
my-single-region 035f24da-3000-41c0-b12f-ef20004a3000 2.17.2.0-b216 ACTIVE 💚
Provider Tier Fault Tolerance Nodes Total Res.(Vcpu/Mem/Disk)
AWS Dedicated ZONE 3 12 / 48GB / 600GB
Regions
Region Nodes vCPU/Node Mem/Node Disk/Node VPC
ap-northeast-1 3 4 16GB 200GB
Endpoints
Region Accessibility State Host
ap-northeast-1 PUBLIC ACTIVE ap-northeast-1.000f20da-3000-40c0-b10f-ef20004a3000.aws.yugabyte.cloud
Network AllowList
Name Description Allow List
my-computer 173.200.10.100/32
Nodes
Name Region[zone] Health Master Tserver ReadReplica Used Memory(MB)
my-single-region-n1 ap-northeast-1[ap-northeast-1a] 💚 ✅ ✅ ❌ 40MB
my-single-region-n2 ap-northeast-1[ap-northeast-1c] 💚 ✅ ✅ ❌ 38MB
my-single-region-n3 ap-northeast-1[ap-northeast-1d] 💚 ✅ ✅ ❌ 41MB
The public host address to use to connect to your cluster is displayed under Endpoints.
To connect to your cluster using the ysqlsh or ycqlsh shells, follow the instructions in Connect via client shells. Use the public endpoint host address, the database credentials you specified when you created the cluster, and the certificate you downloaded.
Encryption at rest
YugabyteDB Aeon supports encryption at rest (EAR). Before you can create a cluster with EAR, you need to create a customer managed key (CMK) in a cloud provider Key Management Service (KMS). See Prerequisites.
Create a cluster with EAR
Use the following commands to create a new cluster with EAR in AWS, GCP, or Azure.
ybm cluster create \
--cluster-name my-sandbox \
--cloud-provider AWS \
--cluster-tier Dedicated \
--cluster-type SYNCHRONOUS \
--encryption-spec cloud-provider=AWS,aws-secret-key=<your-secret-key>,aws-access-key=<your-access-key>,aws-arn=<your-aws-arn-key> \
--credentials username=admin,password=password \
--fault-tolerance ZONE \
--region-info region=us-east-2,num-nodes=3,num-cores=4
The cluster my-sandbox has been created
Name Tier Version State Health Provider Regions Nodes Node Res.(Vcpu/Mem/DiskGB/IOPS)
my-sandbox Dedicated 2026.1.3.0-b100 ACTIVE 💚 AWS us-east-2 3 4 / 16GB / 200GB / 3000
You can list the EAR details using the encryption list command.
ybm cluster encryption list --cluster-name my-sandbox
Provider Key Alias Last Rotated Security Principals CMK Status
AWS XXXXXXXX-e690-42fc-b209-baf969930b2c - arn:aws:kms:us-east-1:712345678912:key/db272c8d-1592-4c73-bfa3-420d05822933 ACTIVE
EAR details are also shown when you use the cluster describe command.
ybm cluster create \
--cluster-name my-sandbox \
--cloud-provider GCP \
--cluster-tier Dedicated \
--cluster-type SYNCHRONOUS \
--encryption-spec cloud-provider=GCP,gcp-resource-id=projects/<your-project>/locations/<your-location>/keyRings/<your-key-ring-name>/cryptoKeys/<your-key-name>,gcp-service-account-path=creds.json \
--credentials username=admin,password=password \
--fault-tolerance ZONE \
--region-info region=us-central1,num-nodes=3,num-cores=4
The cluster my-sandbox has been created
Name Tier Version State Health Provider Regions Nodes Node Res.(Vcpu/Mem/DiskGB/IOPS)
my-sandbox Dedicated 2026.1.3.0-b100 ACTIVE 💚 GCP us-central1 3 4 / 16GB / 200GB / 3000
You can list the EAR details using the encryption list command.
ybm cluster encryption list --cluster-name my-sandbox
Provider Key Alias Last Rotated Security Principals CMK Status
GCP <your-key-name> 2023-11-03T07:37:26.351Z projects/<your-project-id>/<your-location>/global/keyRings/<your-key-ring-name>/cryptoKeys/<your-key-name> ACTIVE
EAR details are also shown when you use the cluster describe command.
ybm cluster create \
--cluster-name my-sandbox \
--cloud-provider AZURE \
--cluster-tier Dedicated \
--cluster-type SYNCHRONOUS \
--encryption-spec cloud-provider=AZURE,azu-client-id=<your-client-id>,azu-client-secret=<your-client-secret>,azu-tenant-id=<your-tenant-id>,azu-key-name=test-key,azu-key-vault-uri=<your-key-vault-uri> \
--credentials username=admin,password=password \
--fault-tolerance ZONE \
--region-info region=eastus,num-nodes=3,num-cores=4 \
The cluster my-sandbox has been created
Name Tier Version State Health Provider Regions Nodes Node Res.(Vcpu/Mem/DiskGB/IOPS)
my-sandbox Dedicated 2026.1.3.0-b100 ACTIVE 💚 AZURE eastus 3 4 / 16GB / 200GB / 3000
You can list the EAR details using the encryption list command.
ybm cluster encryption list --cluster-name my-sandbox
Provider Key Alias Last Rotated Security Principals CMK Status
AZURE 8aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX5b 2023-11-03T07:37:26.351Z <your-key-vault-uri> ACTIVE
EAR details are also shown when you use the cluster describe command.
Rotate your CMK
Use the encryption update command to rotate your CMK. You can also use this command to encrypt a cluster that does not already have EAR.
When encrypting an existing cluster, YugabyteDB Aeon uses lazy encryption.
ybm cluster encryption update \
--cluster-name my-sandbox \
--encryption-spec cloud-provider=AWS,aws-secret-key=<new-secret-key>,aws-access-key=<new-access-key>
ybm cluster encryption update \
--cluster-name my-sandbox \
--encryption-spec cloud-provider=GCP,gcp-resource-id=projects/yugabyte/locations/global/keyRings/test-byok/cryptoKeys/key1,gcp-service-account-path=<path-to-service-account-file>
ybm cluster encryption update \
--cluster-name my-sandbox \
--encryption-spec cloud-provider=AZURE,azu-client-id=<new-client-id>,azu-client-secret=<new-client-secret>,azu-tenant-id=<new-tenant-id>,azu-key-name=test-key,azu-key-vault-uri=<new-key-vault-uri>
Enable and disable EAR
To disable EAR on a cluster, use the following command:
ybm cluster encryption update-state \
--cluster-name my-sandbox \
--disable
Successfully DISABLED encryption at rest for cluster my-sandbox
After you disable EAR, YugabyteDB Aeon uses lazy decryption to decrypt the cluster.
You can check the status of the EAR using the encryption list command.
ybm cluster encryption list --cluster-name my-sandbox
Provider Key Alias Last Rotated Security Principals CMK Status
AZURE 8aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX5b 2023-11-03T07:37:26.351Z <your-key-vault-uri> DISABLED
To re-enable EAR on a cluster, use the following command:
```sh
ybm cluster encryption update-state \
--cluster-name my-sandbox \
--enable
Successfully ENABLED encryption at rest for cluster my-sandbox
Pause, resume, and terminate
To list your clusters, enter the following command:
ybm cluster list
Name Tier Version State Health Regions Nodes Total Res.(Vcpu/Mem/Disk)
my-multi-region Dedicated 2.14.7.0-b51 ACTIVE 💚 us-central1,+2 3 6 / 24GB / 600GB
my-single-region Dedicated 2.14.7.0-b51 ACTIVE 💚 ap-northeast-1 3 12 / 48GB / 600GB
You can pause a cluster when you don't need it:
ybm cluster pause \
--cluster-name my-single-region \
--wait
The cluster my-single-region has been paused
Name Tier Version State Health Regions Nodes Total Res.(Vcpu/Mem/Disk)
my-single-region Dedicated 2.17.2.0-b216 PAUSED ❓ ap-northeast-1 3 12 / 48GB / 600GB
To resume a cluster:
ybm cluster resume \
--cluster-name my-single-region \
--wait
The cluster my-single-region has been resumed
Name Tier Version State Health Regions Nodes Total Res.(Vcpu/Mem/Disk)
my-single-region Dedicated 2.14.7.0-b51 ACTIVE 💚 ap-northeast-1 3 12 / 48GB / 600GB
If you don't need a cluster anymore, you can terminate it:
ybm cluster delete \
--cluster-name my-multi-region \
--wait
The cluster my-multi-region has been deleted