DEV Community

Franck Pachot for YugabyteDB Distributed PostgreSQL Database

Posted on • Updated on

YugabyteDB Managed API: provisioning a free DB from command line

YugabyteDB Managed is the cloud service for YugabyteDB, PostgreSQL-compatible distributed SQL database. All actions can be done from http://cloud.yugabyte.com and can be automated. Here is an example of provisioning a DB on the free tier though the REST API.

API Key, Account ID, Project ID

To interact in a secure way with the API endpoint you need a key, that you create in the web portal:

Create API Key

You can retreive the key as well as the identifiers of your account and project:

Generate Key

If you need to revoke the key, this where were you can do it here:

Image description

For further actions, you have all the necessary information to call the API. I set those in environment variables:

YBM_API_KEY="eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJBcGlKd3QiLCJzdWIiOiIyN2NmZTg4OS03YjdiLTQyYmMtYWU1Mi1hYWFkZTNkMzFiZjQiLCJpc3MiOiJmcGFjaG90QHl1Z2FieXRlLmNvbSIsImV4cCI6MTcwNjk0ODY1NiwiaWF0IjoxNjc1NDEyNjU2LCJqdGkiOiI5ZjI4YzE1MC05NTg4LTQxM2QtODc0MS1hZjAzMmI4NTM1ODkifQ.ftcVHaGBLwVgFVDoxQ03-dr9OTL0QKhgZ5AcIEEL-FY"

YBM_ACCOUNT_ID="8c17af53-3c7c-4e76-a530-768ccdfd75b1"

YBM_PROJECT_ID="684d1eeb-4c50-4678-a925-1e7d777d6bd8"

Enter fullscreen mode Exit fullscreen mode

Software Track

There are two software tracks, the "Preview" to test all new features, with odd release numbers, and the "Stable" one, for production, with even release numbers:

Database Version

Here, I'm creating a free database to test the latest features.
I get the ID for the Preview track:

YBM_SOFTWARE="Preview"

YBM_SOFTWARE_TRACK_ID=$(
curl -s --request GET \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/software-tracks \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --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
Enter fullscreen mode Exit fullscreen mode

Allowed List

To access from the public internet I need to add my public IP to the "Allow List". I create an allow list with my public IP gathered from http://ifconfig.me and get its ID into an environment variable:

YBM_ALLOW_LIST="home"

curl -s --request POST \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/allow-lists  \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "'${YBM_ALLOW_LIST}'",
  "description": "Gathered from http://ifconfig.me",
  "allow_list": [
    "'$(curl -s ifconfig.me)'/32"
  ]
}'

YBM_ALLOW_LIST_ID=$(
curl -s --request GET \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/allow-lists \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --header 'Content-Type: application/json' |
  tee /dev/stderr |
  jq -r '.data[] | select(.spec.name=="'${YBM_ALLOW_LIST}'") | .info.id'
)
echo ; set | grep ^YBM_ | cut -c1-80
Enter fullscreen mode Exit fullscreen mode

Deploy

Now, I have all the necessary as environment variables:

Image description

I define a name for my cluster and a password for the admin user.
Then I call the cluster creation API with one node in Ireland AWS region eu-west-1. The num_cores, memory_mb and disk_size_gb settings are those of the free tier on AWS:

YBM_CLUSTER="my-free-yugabytedb"
YBM_ADMIN_PASSWORD="Password-5up3r53cr3t"

curl -s --request POST \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --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,
        "disk_size_gb": 10
      },
      "is_production": false,
      "version": null
    },
    "network_info": {
      "single_tenant_vpc_id": null
    },
    "software_info": {
      "track_id": "'$YBM_SOFTWARE_TRACK_ID'"
    },
    "cluster_region_info": [
      {
        "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"
        ]
      }
    ]
  },
  "allow_list_info": [ "'"$YBM_ALLOW_LIST_ID"'" ],
  "db_credentials": {
    "ycql": {
      "username": "admin",
      "password": "'"$YBM_ADMIN_PASSWORD"'"
    },
    "ysql": {
      "username": "admin",
      "password": "'"$YBM_ADMIN_PASSWORD"'"
    }
  }
}'

Enter fullscreen mode Exit fullscreen mode

I can check that the cluster is in Deploying state:

Image description

List the clusters

I check the state from the list of clusters:

curl -s --request GET \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --header 'Content-Type: application/json' \
  | jq -r '.data[] | .info.id +" "+ .spec.name +": "+ .info.state'

Enter fullscreen mode Exit fullscreen mode

Image description

For further interaction, I get the ID of the one I'm currently creating:

YBM_CLUSTER_ID=$(
curl -s --request GET \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --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
Enter fullscreen mode Exit fullscreen mode

I can wait in an automated way:

until curl -s --request GET   --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters/$YBM_CLUSTER_ID   --header "Authorization: Bearer $YBM_API_KEY" |
 grep '"state":"ACTIVE"' ; do sleep 1 ; done
Enter fullscreen mode Exit fullscreen mode

This loop stops when the cluster is active

Connect with PostgreSQL drivers

To connect to the default database yugabyte with the admin user I set the PostgreSQL environment variables, getting the host from the list of endpoints:

PGDATABASE=yugabyte
PGUSER="admin"
PGPASSWORD="$YBM_ADMIN_PASSWORD"
PGPORT="5433"
PGSSLMODE=require

PGHOST=$(
curl -s --request GET \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters \
  --header "Authorization: Bearer $YBM_API_KEY" \
  --header 'Content-Type: application/json' | 
  tee /dev/stderr |
  jq -r '.data[] | select(.spec.name=="'$YBM_CLUSTER'") | .info.cluster_endpoints[0].host '
)
echo ; set | grep ^PG
export PGDATABASE PGUSER PGHOST PGPORT PGPASSWORD PGSSLMODE

Enter fullscreen mode Exit fullscreen mode

I can now simply use any PostgreSQL tool or application:

psqln

Terminate

The API is documented, you have the link on the API key list as "Learn more about REST API".

I can pause a cluster when I don't need it:

curl -s --request POST \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters/$YBM_CLUSTER_ID/pause \
  --header "Authorization: Bearer $YBM_API_KEY" --data ''

Enter fullscreen mode Exit fullscreen mode

Image description

This one is free database, you don't pause it.
You can consider it as serverless 😃

If you don't need it anymore, you can terminate the service:

curl -s --request DELETE \
  --url https://cloud.yugabyte.com/api/public/v1/accounts/$YBM_ACCOUNT_ID/projects/$YBM_PROJECT_ID/clusters/$YBM_CLUSTER_ID \
  --header "Authorization: Bearer $YBM_API_KEY"

Enter fullscreen mode Exit fullscreen mode

Image description

I've revoked my API key, so don't use those above IDs. You can sign up for your own free YugabyteDB: https://cloud.yugabyte.com/signup

Top comments (2)

Collapse
 
aboutcb1 profile image
aboutcb1

thanks

Collapse
 
franklin1621 profile image
franklin1621 • Edited

Thanks for your article! I used to learn how YugabyteDB Managed cloud service work as it is the perfect subject for my college project. I love to use online resources for preparation and studyclerk.com/essay-writing-help is the latest site which helped with the essay part. Now, I am going to go ahread with practical part of the project and make a presentation about API Key, Account ID, Project ID.