Get things done with the Aiven CLI

The Aiven command line

GUIs (Graphical User Interfaces) like the Aiven web
console are a very approachable way to interact with systems,
especially since they can guide you towards the actions you might want to do.
When it comes to repeatability and automation however, these interfaces have limitations.

Luckily, almost every action available in the web console is also possible
using the open source avn CLI tool,
aiven-client. This tool is also heavily used
within Aiven itself, which means that it is well supported and gains new
service management features regularly.

In this article I will lead you through some common operations, using a
PosgreSQL® service as an example.

Install avn

Following the instructions at Aiven CLI: Getting
started, install the Aiven
CLI tool with pip:

Loading code...

A fun way to check that the command is working is with this special feature:

Loading code...

This will give you a nice piece of ASCII art.

Get help with the avn command

You can get help from avn in a few different ways.

To get general help on how to use the command, including a summary of the switches
the command accepts, and a list of the top-level subcommands:

Loading code...

You can also get help on specific commands by adding --help to the end of
the command line. For example to get some help with how to use the avn user login command:

Loading code...

You can get a (long) list of all the avn commands and a brief note of what
they each do by using:

Loading code...

This can be useful if you're trying to "guess" what command to use.

For instance, here's a part of the output relating to PostgreSQL®,
showing us the commands to retrieve the service connection information
as a string, as a URI, or in the format that psql needs:

Loading code...

Get an account

If you've already got an Aiven account, then you're ready to go.

Otherwise, you can sign up at the Aiven console - either for a free plan or for a free trial.

Log in to Aiven with avn

Most avn commands require authentication.
At the command line, this is normally done by logging in with an
authentication token.

Using a token rather than username and password is considered good practice.
Tokens can be limited to a specific time period, and they can also
be revoked, removing access only for those using that token, without affecting
other use cases. Resetting a password would have a much wider impact.

Get an authentication token, as described at Create an authentication
token,
copy it, and log in using the following command. You'll need to replace
YOUR-EMAIL-ADDRESS with the email address you've registered with Aiven.

Loading code...

This will prompt you to paste in your token, and then report that it has
saved your credentials to a JSON file on your filesystem.

Choose a project

Aiven uses "projects" to organise which services you can access. You can get a
list of the projects that you have access to, their default clouds, and some
information on payments with a command like this:

Loading code...

For instance, as a Developer Educator at Aiven, I see output something like the following:

Loading code...

Once you know which project you're going to be using, you can select it, replacing
PROJECT-NAME with the name of the actual project:

Loading code...

This makes that the default project for future commands.

Find out about a project

To find out more about a project:

Loading code...

This will typically show the default cloud for the project, its billing
currency, and maybe details of the VAT ID being used, the billing address and
credit card data (if appropriate).

Loading code...

Get JSON data

Commands that return data also take a --json switch, which causes them to
return their data in JSON. This often includes more information than is
provided by the standard text output. For instance altering our earlier command to include the switch:

Loading code...

This version gives a lot more detail, including account name and id, available credits and
current estimated balance.

Sometimes the data produced with --json can be overwhelming, especially if
you're only looking for one particular field. In that case, it can be useful
to pipe the JSON output into the jq tool,
and use a query to select just the information you want.

For instance, to find the name of the default cloud for the current project, do:

Loading code...

The command returns just the name of the cloud.

Find out what services are available

You can find out what services (PostgreSQL®, Apache Kafka®, OpenSearch®, etc.)
are available for the current project with this command:

Loading code...

This will will list the services and the abbreviation used for each service
type.

For instance, the entry for PostgreSQL looks like this:

Loading code...

Since PostgreSQL is such an excellent database, we're going to create a pg service and show off some more avn commands.

Find a cloud

In order to create a new service, you need to decide what region you want it
to run in, and what capabilities you need. To find out what clouds and regions
are available:

Loading code...

This will show the available clouds and information about them - specifically,
a description of the cloud, its name, its location (as latitude and longitude)
and its region.

The output will be lines looking something like:

Loading code...

Using the --json switch and jq can help if you want to get more
details of just part of the information. For instance, to find the information
for all the services in europe, try this:

Loading code...

You should see a list of entries like the one below:

Loading code...

To get just that particular entry, you could use:

Loading code...

Find a service plan

Aiven uses "service plans" to define the number of servers and what kind of
memory, CPU, and disk resources are allocated to your service.

To get a list of the available service plans for PostgreSQL in the cloud
google-europe-north1, including the plan name, its cost and what resources
it provides, use this command:

Loading code...

Here's part of the output I get:

Loading code...

It's worth trying different clouds to see how pricing differs between them.

Create a PostgreSQL® service

For this first service creation, create a PostgreSQL service on the Finnish
Google cloud at the Hobbyist level.

It's important to give the service a unique name - I like to put my own
name into it, but you should use your own! Beware that the name can't be
changed after you've created the service.

Loading code...

The command will return immediately. Meanwhile, Aiven will start creating the service, which will take a little while to build.

If you want to wait for the service to start, you can use the wait command for the service:

Loading code...

This will report the progress of the newly-created service as it comes up.

Loading code...

The command will return when the service is RUNNING (the ... means there might be multiple "Waiting" messages).
The wait command is especially useful in a script, when you have another command to run when things are ready.

You can explicitly check the state of the service, as well as other
information:

Loading code...

This returns service information like this:

Loading code...

If you just want the current state of the service, use --json and jq as we did earlier to
get the field you want from the output:

Loading code...

Interact with the PostgreSQL service

Once the PostgreSQL service is running, we can use the command line to
interact with it.

To find out what databases are present:

Loading code...

This will just show the default database since we just created a new service:

Loading code...

We can create a new database using avn:

Loading code...

If you list the databases again, the new one will appear:

Loading code...

Since this is a PostgreSQL database, we could get the connection details from avn
and use them to connect to the
database:

Loading code...

But it's probably easier to use the built-in helper:

Loading code...

This will run the appropriate CLI for the service - for our PostgreSQL service, that means psql.

Finally for this section, I like to know the backup status of services I'm
using. I can get a list of when backups were made and what region they're
stored in with:

Loading code...

Change plan, cloud and region

We created our PostgreSQL service using the Hobbyist plan. That's fine for
trying out a service, but it's definitely not suitable for production
use.

The avn service update command allows us to change the details of our service.

To update to a Startup-8 plan running on AWS in Ireland (aws-eu-west-1):

Loading code...

This will take a little while, because it has to start a new service with a
copy of the original data. How long it takes will depend on the amount of
data, and how busy the systems are. As before, you can use avn service get
or avn service wait to tell when it has finished. See the documentation for
Migrate
services and
Scale your
service. (Aiven takes care that there is no service interruption during a change like
this).

Once the service is RUNNING again, check the new plan and location:

Loading code...

Keep things tidy

If you're not going to be using a service for a while, then powering it off
will stop you being charged for it:

Loading code...

The command won't return until the service is powered off.

You can power the service back on again by using the update command once more:

Loading code...

Remember it will take a while before the service returns to the RUNNING state.

If you no longer need the service, then delete it:

Loading code...

Since this will delete the service and all associated data, it prompts you to
type in the service name to confirm the operation.

Further reading

We barely scratched the surface of the available features in this tool. For more information, visit the Aiven documentation
where you will find a whole section on the Aiven CLI.

The README for
the Aiven Client GitHub repository
also contains useful information and examples.

There's also an Introduction to Aiven CLI video, which covers some of the same material.

And for an example of using the Aiven CLI in a Bash script, see
Controlling non-production Aiven Services with the CLI

Alternatively, try one of the other ways to work with the Aiven platform:

• the Aiven web console
• the Aiven API - this is what
  the command line tool and the web console use to communicate with the Aiven platform
• Terraform and the Aiven Terraform provider
• Kubernetes® and Aiven Operator for Kubernetes