Ansible and Astra DB APIs – A Match Made in Heaven
Madhavan Sridharan
Every business is a digital business today. Technology is your innovation engine, and delivering your applications faster helps you win. Historically, that required a lot of manual effort and complicated coordination. But today, there is Ansible, the simple, yet powerful IT automation engine that thousands of companies are using to drive complexity out of their environments and accelerate DevOps initiatives.
DataStax Astra DB offers a rich set of APIs. The DevOps API makes it easy to script the creation and management of an Astra DB database, roles, security tokens, access lists and private links for your database. And, with Stargate, Astra users have easy access to built-in APIs (REST, gRPC, GraphQL, and Document) to work with the data.
You may have queried APIs with a Postman, a web browser or cURL, but one of the overlooked capabilities of Ansible is how well it can leverage APIs as part of the playbook. This is extremely useful because the number of APIs being built and offered both by Astra and across the global internet-scale companies is growing exponentially. There's even a public-apis GitHub repo listing hundreds of free APIs in over a dozen categories.
In this post, we are going to walk you through how to use Ansible to leverage Astra DB’s DevOps APIs and Stargate Data APIs. In the repo, we give you the Ansible playbook for interacting with Astra APIs to get your database up and running with the required table(s) for your application(s) so you can begin kicking the tires.
Let’s get started!
With just one single playbook, we will demonstrate the operations needed to begin leveraging your database. These steps will help you get your Astra DB up and running and the tables ready to go for your applications:
- Create a token to use the Astra DevOps API endpoints (this is only supported for classic tier Astra DBs)
- Return supported regions and availability for a given user and org combination
- Create a new Astra database and create a keyspace on the created DB
- Find the created Astra database using its ID
- Obtain the secure connect bundle for the created Astra database using its ID
- Create a token to use the Data API for the Astra database using its ID
- Return all keyspaces in the Astra database using its ID
- Add a table in the created Astra database
- Return all tables in the Astra database using its ID
- Resize the already-created Astra database (this is only supported for non-free tier classic tier Astra DBs)
- Park the already-created Astra database (this is only supported for classic tier Astra DBs)
- Unpark the already-parked Astra database (this is only supported for classic tier Astra DBs)
Getting set up with the necessary prerequisites
- Download and set Ansible up on the control machine from where you’ll be executing the Ansible playbook. In this example, we used version 2.9.13.
- Sign into DataStax Astra DB portal and create an Application Token. We are going to use the
API Admin Svc Accountrole here to generate the token. Save the generated token details by downloading the CSV.
Tip: This step can also be created using the DevOps API, but we wanted to show you the Astra DB portal mechanism as well here!
- Download the
astra_api.ymlfile to your Ansible control machine. If you’re curious, you could dive into this playbook to understand the operations at a deeper level. All we need right now is Ansible's coreurimodule to achieve what we want.
Executing the Ansible playbook
Run the astra_api.yml Ansible playbook using the below command on the Ansible control machine. You’ll experience all the actions/tasks being executed sequentially as defined in the playbook.
ansible-playbook astra_api.yml |
You’ll be asked to provide answers/values for the questions one after the other which are required to execute the playbook. Just hit enter for the optional ones. See below table for additional details.
Alternatively, one could pass in the answers/values via command-line arguments by running the following:
ansible-playbook astra_api.yml --extra-vars 'astra_devops_api_auth_token=<your_iam_token_from_prerequisite_step2> astra_db_name=<name_for_your_db> astra_db_keyspace=<name_for_your_keyspace> astra_db_cloudProvider=<public_cloud_provider_name_AZURE_GCP_AWS> astra_db_tier=<astra_db_tier> astra_db_capacityUnits=<capacity_unit_in_numeric> astra_db_region=<your_astra_db_region> astra_db_username=<your_astra_username> astra_db_tableName=<name_for_the_table>' |
Let’s see what’s all these Ansible playbook input variables mean:
|
Property Name |
Required? |
Notes & References |
astra_devops_api_auth_token |
Yes |
An application token to connect to the DB |
astra_db_name |
Optional |
Default: |
astra_db_keyspace |
Optional |
A container to hold to your tables within the DB. |
astra_db_cloudProvider |
Optional |
Default: |
astra_db_tier |
Optional |
Default: |
astra_db_region |
Optional |
Default: |
astra_db_tableName |
Yes |
Your AstraDB’s table name |
astra_db_username |
Optional |
Only applicable for clusters created prior to the introduction of IAM capabilities. Default: |
astra_db_password |
Optional |
Only applicable for clusters created prior to the introduction of IAM capabilities. Use this along with |
astra_db_capacityUnits |
Optional |
A Group of replicas. N/A for Serverless tier DB. Default: |
And, voila!! ✨ We've successfully performed a series of operations leveraging Astra DevOps API and the built-in Stargate APIs to spin up a free-tier database.
The following are some examples of the output you’ll see when your playbook has completed successfully. You’ll notice that these examples are similar to the larger example at the end of this post. We just shortened it here for the sake of brevity. Note that the playbook would have skipped agenda items 1, 10, 11, and 12 here during this run, as this operation is not required with serverless tier Astra DBs but we wanted to showcase what’s possible for classic tier Astra DBs.
We’re only showing the last line of the playbook’s run output here for brevity:
PLAY RECAP ************************************************************************************************************************ localhost : ok=19 changed=0 unreachable=0 failed=0 skipped=4 rescued=0 ignored=0 |
Upon the run completion, you’ll see the following in the AstraDB portal:
Figure 1. DataStax Astra portal showing the created free-tier database.
And, when you click on the “CQL Console” menu/section to explore the created data model schema by describing it, you’ll notice output similar to below:
Figure 2. DataStax Astra portal showing the created free-tier database’s data model/schema.
And, here’s a simplified example of the run output:
$ ansible-playbook astra_api.yml --extra-vars 'astra_devops_api_auth_token=AstraCS:CHANGE:ME astra_db_name=astra astra_db_keyspace=astra astra_db_cloudProvider=GCP astra_db_tier=serverless astra_db_capacityUnits=1 astra_db_region=us-east1 astra_db_username=astra astra_db_tableName=astra'
PLAY [localhost] *****************************************************************************************************************************************************
TASK [Returns supported regions and availability for a given user and org combination] ****************************************************************************************************************************
ok: [localhost] => {...},
"json": [{"cloudProvider": "GCP","cost": {...}, …,"description": "Free tier: Try Astra with no obligation. Get 5 GB of storage, free forever.",
"region": "us-east1", "regionContinent": "North America","regionDisplay": "Moncks Corner, South Carolina", "tier": "serverless"},{...}],
"msg": "OK (unknown bytes)", "status": 200,"url": "https://api.astra.datastax.com/v2/availableRegions"}
|
We’ve only scratched the surface in this post in terms of what’s possible. With the ever-increasing capabilities of the Astra DevOps API and Stargate data APIs built into Astra, there’s even more you can do, including creating the users, their tokens, access list, private link and more! If you’re not already using Astra DB, maybe it’s time to take it for a spin. You can sign up for free here!
Follow the DataStax Tech Blog for more developer stories. Check out our YouTube channel for tutorials and here for DataStax Developers on Twitter for the latest news about our developer community.
Resources
- Ansible
- Astra DB (Classic Tier) (Astra Documentation)
- Serverless Astra DB (Astra Documentation)
- DataStax Astra DB Registration
- DevOps API for managing your databases (Documentation)
- Stargate
- Get a Head Start on Your App Development with Flexible DataStax Stargate APIs
- Qualify Your Database Needs with DataStax Astra Stargate REST API
- Say Goodbye to Native Drivers with Stargate gRPC API in Java
- How to get just the data you need with the Stargate GraphQL API in a simple coding scenario
- Create and Use a Document Database with Stargate Document API and Astra DB in 15 Minutes
- GitHub public repo with a collective list of free APIs
- Installation Guide for Installing Ansible
- Manage application tokens (Astra Documentation)
- User Permissions (Astra Documentation)
- Astra API .yml file on GitHub
- Ansible core uri module
- Ansible control machine
- Astra DB Glossary (Astra Documentation)
- Security Highlights (Astra Documentation)
- Using the Astra DB DevOps & Data APIs Reference
- Using the Astra DB DevOps APIs examples (Astra Documentation)
- Automate Database Infrastructure with Astra DB Terraform Provider
More Technology
View All
How to Build a Crystal Image Search App with Vector Search
Knowledge Graphs for RAG without a GraphDB
