aiven-client 2.3.5

Aiven.io client library / command-line client

Aiven Client

Aiven is a next-generation managed cloud services platform. Its focus is in ease of adoption, high fault resilience, customer’s peace of mind and advanced features at competitive price points. See https://aiven.io/ for more information about the backend service.

aiven-client (avn) is the official command-line client for Aiven.

                    `'+;`         `'+;`
The Aiven Crab    '@@@#@@@`     '@@@#@@@`
~~~~~~~~~~~~~~   #@.     #@.   @@.     #@.
                 @: ,@@   @@   @: ,@@   @@
                ,@  @@@@@ :@  :@  @@@@@ .@
                 @  #@@@. #@   @` #@@@` @@
                 @@      `@#   @@      `@#
                  @@#. :@@+     @@#. :@@#
                   `+@@@'        `#@@@'
           ,;:`                             ,;;.
         @@@@@@#     .+@@@@@@@@@@@@@'.    `@@@@@@@
        @@@@@#    @@@@@@@@@@@@@@@@@@@@@@+    @@@@@@
         @@@   ;@@@@@@@@@@@@@@@@@@@@@@@@@@@`  `@@;
          `  `@@@@@@@@@@@        ;@@@@@@@@@@@
      `@@@  '@@@@@@@@@@@@@       @@@@@@@@@@@@@`  @@@
     '@@@` .@@@@@@@@@@@@@@@    `@@@@@@@@@@@@@@@  @@@@`
     @@@@  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  @@@@
    '@@@@  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  @@@@
    ,:::;  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  ,:::
       :@  ,@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@  #@
       @@@  +@#+#@@@@@@@@@@@@@@@@@@@@@@@@@#+#@.  @@@
       @@@@        '@@@@@@@@@@@@@@@@@@@.        @@@@
       @@@  @@@@@@+  @@@@@@@@@@@@@@@@@  @@@@@@;  @@@
       @@  @@@@@@@@@  @@@@@@@@@@@@@@@ `@@@@@@@@@  @+
          @@@@@@@@@@@ :@@@@@@@@@@@@@  @@@@@@@@@@@ '
         `@@@@@@@@@@@       ```      ,@@@@@@@@@@@
         `@@@@@@   '@                :@:   @@@@@@
          @@@@@:                           @@@@@@
           @@@@@                           @@@@@
            @@@@#                         @@@@'

Platform requirements

Aiven Client has been tested and developed on Linux and Mac OS X systems. It is a Python program that works with Python 3.4 or newer versions. The only external dependency is Requests (and certifi on Windows/OSX).

Installation

From PyPI (Linux/OSX):

$ python3 -m pip install aiven-client

From PyPI (Windows):

c:\> python3 -m pip install aiven-client

Build an RPM package (Linux):

$ make rpm

Basic Usage

• NOTE: On Windows you may need to use python3 -m aiven.client instead of avn.

• All commands will output the raw REST API JSON response with --json

Help command

$ avn help

List all commands. You can use the help to also search for matching commands, for example

$ avn help kafka topic

would list all commands that have kafka and topic in their description.

Login and users

Login:

$ avn user login <your@email>

Logout (revokes current access token, other sessions remain valid):

$ avn user logout

Expire all authentication tokens for your user, logs out all web console sessions, etc. You will need to login again after this.:

$ avn user tokens-expire

Manage individual access tokens:

$ avn user access-token list
$ avn user access-token create --description <usage_description> [--max-age-seconds <secs>] [--extend-when-used]
$ avn user access-token update <token|token_prefix> --description <new_description>
$ avn user access-token revoke <token|token_prefix>

Note that the system has hard limits for the number of tokens you can create. If you’re permanently done using a token you should always use user access-token revoke operation to revoke the token so that it does not count towards the quota.

Alternatively, you can add 2 JSON files, first create a default config in ~/.config/aiven/aiven-credentials.json containing the JSON with an auth_token:

{
    "auth_token": "ABC1+123...TOKEN==",
    "user_email": "[e-mail]"
}

Second create a default config in ~/.config/aiven/aiven-client.json containing the json with the default_project:

{"default_project": "yourproject-abcd"}

Clouds

List available cloud regions:

$ avn cloud list

Projects

List projects you are a member of:

$ avn project list

Project commands operate on the currently active project or the project specified with the --project NAME switch. The active project cab be changed with the project switch command:

$ avn project switch <projectname>

Show active project’s details:

$ avn project details

Create a project and set the default cloud region for it:

$ avn project create myproject --cloud aws-us-east-1

Delete an empty project:

$ avn project delete myproject

List authorized users in a project:

$ avn project user-list

Invite an existing Aiven user to a project:

$ avn project user-invite [e-mail]

Remove a user from the project:

$ avn project user-remove [e-mail]

View project management event log:

$ avn events

Services

List services (of the active project):

$ avn service list

List services in a specific project:

$ avn service list --project proj2

List only a specific service:

$ avn service list db1

Verbose list (includes connection information, etc.):

$ avn service list db1 -v

Full service information in JSON, as it is returned by the Aiven REST API:

$ avn service list db1 --json

Only a specific field in the output, custom formatting:

$ avn service list db1 --format "The service is at {service_uri}"

View service log entries (most recent entries and keep on following logs, other options can be used to get history):

$ avn service logs db1 -f

Launching services

View available service plans:

$ avn service plans

Launch a PostgreSQL service:

$ avn service create mydb -t pg --plan hobbyist

View service type specific options, including examples on how to set them:

$ avn service types -v

Launch a PostgreSQL service of a specific version (see above command):

$ avn service create mydb96 -t pg --plan hobbyist -c pg_version=9.6

Update a service’s list of allowed client IP addresses. Note that a list of multiple values is provided as a comma separated list:

$ avn service update mydb96 -c ip_filter=10.0.1.0/24,10.0.2.0/24,1.2.3.4/32

Open psql client and connect to the PostgreSQL service (also available for InfluxDB):

$ avn service cli mydb96

Update a service to a different plan AND move it to another cloud region:

$ avn service update mydb --plan startup-4 --cloud aws-us-east-1

Power off a service:

$ avn service update mydb --power-off

Power on a service:

$ avn service update mydb --power-on

Terminate a service (all data will be gone!):

$ avn service terminate mydb

Updating service configuration

Shell completions

avn supports shell completions. It requires an optional dependency: argcomplete. Install it:

$ python3 -m pip install argcomplete

To use completions in bash, add following line to ~/.bashrc:

eval "$(register-python-argcomplete avn)"

For more information (including completions usage in other shells) see https://kislyuk.github.io/argcomplete/.

More help

$ avn help
$ avn -h
$ avn user -h
$ avn service -h
$ avn service create -h
$ avn project -h

License

Aiven Client is released under the Apache License, Version 2.0.

For the exact license terms, see LICENSE and http://opensource.org/licenses/Apache-2.0 .

Contact

Bug reports and patches are very welcome, please post them as GitHub issues and pull requests at https://github.com/aiven/aiven-client