Project: YugabyteDB (App Definition and Development / Database)
File: managed-guide-api.md

private: true <! title: Guide for ybm API automation headerTitle: "Tutorial: Create a cluster using the REST API" linkTitle: "Tutorial: REST API" description: Tutorial for using YugabyteDB Managed REST API to create clusters. headcontent: Example workflows for automation tools menu: preview_yugabyte-cloud: identifier: managed-guide-api parent: managed-cli-examples weight: 60 type: docs > The following tutorial shows how you can use the REST API to create clusters in YugabyteDB Managed. For documentation and Postman collection, refer to . This guide assumes you have already done the following: Created and saved an . Obtained your . Installed . For convenience, add the API key and IDs to environment variables, as follows: ```sh YBMAPIKEY="<api_key>" YBMACCOUNTID="<account_ID>" YBMPROJECTID="<project_ID>" ``` To create VPCs and dedicated clusters, you also need to add a and payment method, or you can . Note that you can only create one Sandbox cluster per account. To create your free cluster, you'll first set up environment variables for the version of YugabyteDB to use, and an IP allow list. YugabyteDB Managed has , Innovation or Preview for Sandbox clusters, and Innovation or Production for dedicated clusters. To get the ID for the Preview track and add it to an environment variable, enter the following commands: ```sh YBM_SOFTWARE="Preview" YBMSOFTWARETRACK_ID=$( curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/software-tracks \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' | \ tee /dev/stderr | jq -r '.data[] | select(.spec.name=="'$YBM_SOFTWARE'") | .info.id ' ) echo ; set | grep ^YBM_ | cut -c1-80 ``` To access the cluster from your computer, you need to add your public IP to an IP allow list. The following creates an allow list with the address obtained from <http://ifconfig.me>, and puts the ID of the allow list into an environment variable: ```sh YBMALLOWLIST="home" curl -s --request POST \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/allow-lists \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' \ --data '{ "name": "'${YBMALLOWLIST}'", "description": "Gathered from http://ifconfig.me", "allow_list": [ "'$(curl -s ifconfig.me)'/32" ] }' YBMALLOWLIST_ID=$( curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/allow-lists \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' | tee /dev/stderr | jq -r '.data[] | select(.spec.name=="'${YBMALLOWLIST}'") | .info.id' ) echo ; set | grep ^YBM_ | cut -c1-80 ``` Now you have all the information you need to deploy a cluster as environment variables: ```output.sh YBMACCOUNTID=a1fcd466-f30a-4074-b042-[...] YBMALLOWLIST=home YBMALLOWLIST_ID=0cf48f5f-4dfe-4d71-a506-d6415fed6f8a YBMAPIKEY=eyJhbGc[...] YBMCLUSTERID=ca209cb4-3714-4968-8800-[...] YBMPROJECTID=cd15fb18-3117-47d2-b705-[...] YBM_SOFTWARE=Preview YBMSOFTWARETRACK_ID=250ef2a0-0555-4e3a-9418-00e6bdfe1cb0 ``` The following defines a name for the cluster and a password for the database admin user. Then it calls the cluster creation API with one node in Ireland AWS region eu-west-1; the `numcores`, `memorymb`, and `disksizegb` settings are those of the free tier on AWS: ```sh YBM_CLUSTER="my-free-yugabytedb" YBMADMINPASSWORD="Password-5up3r53cr3t" curl -s --request POST \ --url

\ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' \ --data '{ "cluster_spec": { "name": "'$YBM_CLUSTER'", "cloud_info": { "code": "AWS", "region": "eu-west-1" }, "cluster_info": { "cluster_tier": "FREE", "cluster_type": "SYNCHRONOUS", "num_nodes": 1, "fault_tolerance": "NONE", "node_info": { "num_cores": 2, "memory_mb": 4096, "disksizegb": 10 }, "is_production": false, "version": null }, "network_info": { "singletenantvpc_id": null }, "software_info": { "trackid": "'$YBMSOFTWARETRACKID'" }, "clusterregioninfo": [ { "placement_info": { "cloud_info": { "code": "AWS", "region": "eu-west-1" }, "num_nodes": 1, "vpc_id": null, "num_replicas": 1, "multi_zone": false }, "is_default": true, "is_affinitized": true, "accessibility_types": [ "PUBLIC" ] } ] }, "allowlistinfo": [ "'"$YBMALLOWLIST_ID"'" ], "db_credentials": { "ycql": { "username": "admin", "password": "'"$YBMADMINPASSWORD"'" }, "ysql": { "username": "admin", "password": "'"$YBMADMINPASSWORD"'" } } }' ``` The cluster takes five to ten minutes to deploy. Enter the following to check the progress from the list of clusters: ```sh curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' \ | jq -r '.data[] | .info.id +" "+ .spec.name +": "+ .info.state' ``` ```output ca209cb4-3714-4968-8800-4db1b551744a my-free-yugabytedb: BOOTSTRAPPING ``` Set an environment variable for the ID of the cluster currently being deployed: ```sh YBMCLUSTERID=$( curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' | tee /dev/stderr | jq -r '.data[] | select(.spec.name=="'$YBM_CLUSTER'") | .info.id' ) echo ; set | grep ^YBM_ | cut -c1-80 ``` You can use the cluster ID to monitor the progress of your cluster deployment. Enter the following: ```sh until curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters/$YBMCLUSTERID --header "Authorization: Bearer $YBMAPIKEY" | \ grep '"state":"ACTIVE"' ; do sleep 1 ; done ``` This loop stops when the cluster is ready. To be able to connect to the default database `yugabyte` using the database admin user you created, you need to obtain the public host address of the cluster from the list of endpoints. The following commands save the connection parameters you need to connect to a YugabyteDB Managed database to environment variables: ```sh PGDATABASE=yugabyte PGUSER="admin" PGPASSWORD="$YBMADMINPASSWORD" PGPORT="5433" PGSSLMODE=require PGHOST=$( curl -s --request GET \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters \ --header "Authorization: Bearer $YBMAPIKEY" \ --header 'Content-Type: application/json' | tee /dev/stderr | jq -r '.data[] | select(.spec.name=="'$YBMCLUSTER'") | .info.clusterendpoints[0].host ' ) echo ; set | grep ^PG export PGDATABASE PGUSER PGHOST PGPORT PGPASSWORD PGSSLMODE ``` You can now use any PostgreSQL tool or application to . You can pause a cluster when you don't need it: ```sh curl -s --request POST \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters/$YBMCLUSTERID/pause \ --header "Authorization: Bearer $YBMAPIKEY" --data '' ``` (Note that the Sandbox is free, and can't be paused.) If you don't need a cluster anymore, you can terminate the service: ```sh curl -s --request DELETE \ --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBMACCOUNTID/projects/$YBMPROJECTID/clusters/$YBMCLUSTERID \ --header "Authorization: Bearer $YBMAPIKEY" ```