Aiven Client

You can use Aiven Client to manage your MST services in Managed Service for TimescaleDB.

You can use the Aiven Client tool to:

• Connect to Managed Service for TimescaleDB
• Create a MST service
• Create a fork
• Add authentication plugins to your attached Grafana service

Instructions:

• Install and configure the Aiven client
• Fork services with Aiven client
• Configure Grafana authentication plugins
• Send Grafana emails
• Create a read-only replica with the Aiven client

Install and configure the Aiven client

Aiven Client is a command line tool for fully managed services. To use Aiven Client, you first need to create an authentication token. Then, you configure the client to connect to your Managed Service for TimescaleDB using the command line.

Create an authentication token in Managed Service for TimescaleDB

To connect to Managed Service for TimescaleDB using Aiven Client, create an authentication token.

1. Open user information

   In Managed Service for TimescaleDB, click User Information in the top right corner.

2. Generate a token

   In the User Profile page, navigate to the Authentication tab. Click Generate Token.

3. Save the token

   In the Generate access token dialog, type a descriptive name for the token. Leave the rest of the fields blank. Copy the generated authentication token and save it.

Install the Aiven Client

The Aiven Client is provided as a Python package. If you’ve already installed Python, you can install the client on Linux, MacOS, or Windows systems using pip:

pip install aiven-client

For more information about installing the Aiven Client, see the Aiven documentation.

Configure Aiven Client to connect to Managed Service for TimescaleDB

To access Managed Service for TimescaleDB with the Aiven Client, you need an authentication token. Aiven Client uses this to access your MST services on Managed Service for TimescaleDB.

1. Open the configuration directory

   Change to the install directory that contains the configuration files:

   cd ~/.config/aiven/

2. Update the credentials file

   Open the aiven-credentials.json using any editor and update these lines with your Managed Service for TimescaleDB User email, and the authentication token that you generated:

   {
     "auth_token": "ABC1+123...TOKEN==",
     "user_email": "your.email@timescale.com"
   }

   Save the aiven-credentials.json file.

3. Verify access

   To verify that you can access your services on Managed Service for TimescaleDB, type:

   avn project list

   This command shows a list of all your projects:

    PROJECT_NAME       DEFAULT_CLOUD            CREDIT_CARD
    =============     =======================   ===================
    project-xxxx      timescale-aws-us-east-1   xxxx-xxxx-xxxx-xxxx
    project-yyyy      timescale-aws-us-east-1   xxxx-xxxx-xxxx-xxxx
    project-zzzz      timescale-aws-us-east-1   xxxx-xxxx-xxxx-xxxx

Fork services with Aiven client

When you fork a MST service, you create an exact copy of the MST service, including the underlying database. You can use a fork of your MST service to:

• Create a development copy of your production environment.
• Set up a snapshot to analyze an issue or test an upgrade.
• Create an instance in a different cloud, geographical location, or under a different plan.

For more information about projects, plans, and other details about services, see About Managed Service for TimescaleDB.

1. Connect to your service

   In the Aiven client, connect to your Managed Service for TimescaleDB service.

2. Switch to the project

   Switch to the project that contains the MST service you want to fork:

   avn project switch <PROJECT>

3. List the services

   List the MST services in the project, and make a note of the MST service that you want to fork, listed under SERVICE_NAME column in the output.

   avn service list

4. Get the service details

   Get the details of the MST service that you want to fork:

   avn service get <SERVICE_NAME>

5. Create the fork

   Create the fork:

   avn service create <NAME_OF_FORK> --project <PROJECT_ID>\
   -t <SERVICE_TYPE> --plan <PLAN> --cloud <CLOUD_NAME>\
   -c service_to_fork_from=<NAME_OF_SERVICE_TO_FORK>

Example

To create a fork named grafana-fork for a MST service named grafana with these parameters:

• PROJECT_ID: project-fork
• CLOUD_NAME: timescale-aws-us-east-1
• PLAN_TYPE: dashboard-1

avn service create grafana-fork --project project-fork -t grafana --plan dashboard-1 --cloud timescale-aws-us-east-1  -c service_to_fork_from=grafana

You can switch to project-fork and view the newly created grafana-fork using:

avn service list

Configure Grafana authentication plugins

Grafana supports multiple authentication plugins, in addition to built-in username and password authentication.

On Managed Service for TimescaleDB, Grafana supports Google, GitHub, and GitLab authentication. You can configure authentication integration using the Aiven command-line client.

Integrating the Google authentication plugin

To integrate Google authentication with Grafana service on Managed Service for TimescaleDB, you need to create your Google OAuth keys. Copy your client ID and client secret to a secure location.

1. Connect and switch to the project

   In the Aiven Client, connect to your Managed Service for TimescaleDB service. Switch to the project that contains the Grafana service you want to integrate:

   avn switch <PROJECT>

2. Find the Grafana service

   List the services in the project. Make a note of the Grafana service that you want to integrate, listed under SERVICE_NAME column in the output.

   avn service list

   Get the details of the service that you want to integrate:

   avn service get <SERVICE_NAME>

3. Integrate the plugin

   Integrate the plugin with your services using the <CLIENT_ID> and <CLIENT_SECRET> from your Google developer console:

   avn service update -c auth_google.allowed_domains=<G-SUITE_DOMAIN>\
   -c auth_google.client_id=<CLIENT_ID>\
   -c auth_google.client_secret=<CLIENT_SECRET> <SERVICE_NAME>

4. Verify the plugin

   Log in to Grafana with your service credentials. Navigate to Configuration → Plugins and verify that the Google OAuth application is listed as a plugin.

   Note

   When you allow sign-ups using the -c auth_google.allow_sign_up=true option, by default each new user is created with viewer permissions and added to their own newly created organizations. To specify different permissions, use -c user_auto_assign_org_role=ROLE_NAME. To add all new users to the main organization, use the -c user_auto_assign_org=true option.

Integrating the GitHub authentication plugin

To integrate GitHub authentication with Grafana service on Managed Service for TimescaleDB, you need to create your GitHub OAuth application. Store your client ID and client secret in a secure location.

1. Connect and switch to the project

   In the Aiven Client, connect to your Managed Service for TimescaleDB service. Switch to the project that contains the Grafana service you want to integrate:

   avn switch <PROJECT>

2. Find the Grafana service

   List the services in the project, and make a note of the Grafana service that you want to integrate, listed under SERVICE_NAME column in the output.

   avn service list

   Get the details of the service that you want to integrate:

   avn service get <SERVICE_NAME>

3. Integrate the plugin

   Integrate the plugin with your service using the <CLIENT_ID>, and <CLIENT_SECRET> from your GitHub OAuth application:

   avn service update -c auth_github.client_id=<CLIENT_ID>\
   -c auth_github.client_secret=<CLIENT_SECRET> <SERVICE_NAME>

4. Verify the plugin

   Log in to Grafana with your service credentials. Navigate to Configuration → Plugins. The Plugins page lists GitHub OAuth application for the Grafana instance.

   Note

   When you allow sign-ups using the -c auth_github.allow_sign_up=true option, by default each new user is created with viewer permission and added to their own newly created organizations. To specify different permissions, use -c user_auto_assign_org_role=ROLE_NAME. To add all new users to the main organization, use the -c user_auto_assign_org=true option.

Integrating the GitLab authentication plugin

To integrate the GitLab authentication with Grafana service on Managed Service for TimescaleDB, you need to create your GitLab OAuth application. Copy your client ID, client secret, and GitLab groups name to a secure location.

If you use your own instance of GitLab instead of gitlab.com, then you need to set the following:

• auth_gitlab.api_url
• auth_github.auth_url
• auth_github.token_url

1. Connect and switch to the project

   In the Aiven Client, connect to your Managed Service for TimescaleDB service. Switch to the project that contains the Grafana service you want to integrate:

   avn project switch <PROJECT>

2. Find the Grafana service

   List the services in the project. Note the Grafana service that you want to integrate, listed under SERVICE_NAME column in the output.

   avn service list

   Get the details of the service that you want to integrate:

   avn service get <SERVICE_NAME>

3. Integrate the plugin

   Integrate the plugin with your service using the <CLIENT_ID>, <CLIENT_SECRET>, and <GITLAB_GROUPS> from your GitLab OAuth application:

   avn service update -c auth_gitlab.client_id=<CLIENT_ID>\
   -c auth_gitlab.client_secret=<CLIENT_SECRET>\
   -c auth_gitlab.allowed_groups=<GITLAB_GROUPS> <SERVICE_NAME>

4. Verify the plugin

   Log in to Grafana with your service credentials. Navigate to Configuration → Plugins. The Plugins page lists GitLab OAuth application for the Grafana instance.

   Note

   When you allow sign-ups using the -c auth_gitlab.allow_sign_up=true option, by default each new user is created with viewer permission and added to their own newly created organizations. To specify different permissions, use -c user_auto_assign_org_role=ROLE_NAME. To add all new users to the main organization, use the -c user_auto_assign_org=true option.

Send Grafana emails

Use the Aiven client to configure the Simple Mail Transfer Protocol (SMTP) server settings and send emails from Managed Service for TimescaleDB for Grafana. This includes invite emails, reset password emails, and alert messages.

Before you begin

• (Optional): Made a note of these values in the SMTP server: IP or hostname, SMTP server port, Username, Password, Sender email address, and Sender name.

1. Connect and switch to the project

   In the Aiven client, connect to your Managed Service for TimescaleDB service. Switch to the project that contains the Grafana service you want to integrate:

   avn project switch <PROJECT>

2. Find the Grafana service

   List the services in the project. Note the Grafana service that you want to configure, listed under SERVICE_NAME column in the output.

   avn service list

   Get the details of the service that you want to integrate:

   avn service get <SERVICE_NAME>

3. Configure the SMTP settings

   Configure the Grafana service using the SMTP values:

   avn service update --project <PROJECT> <SERVICE_NAME>\
   -c smtp_server.host=smtp.example.com \
   -c smtp_server.port=465 \
   -c smtp_server.username=emailsenderuser \
   -c smtp_server.password=emailsenderpass \
   -c smtp_server.from_address="grafana@yourcompany.com"

4. Review custom options (optional)

   Review all available custom options, and configure:

   avn service types -v

   You can now send emails for your Grafana service on MST.

Create a read-only replica with Aiven client

Read-only replicas enable you to perform read-only queries against the replica and reduce the load on the primary server. They are also a good way to optimize query response times across different geographical locations. You can achieve this by placing the replicas in different regions or even different cloud providers.

1. Connect and switch to the project

   In the Aiven client, connect to your Managed Service for TimescaleDB service. Switch to the project that contains the Managed Service for TimescaleDB service you want to create a read-only replica for:

   avn project switch <PROJECT>

2. Find the service

   List the MST services in the project. Note the service for which you will create a read-only replica. You can find it listed under the SERVICE_NAME column in the output:

   avn service list

   Get the details of the MST service that you want to fork:

   avn service get <SERVICE_NAME>

3. Create a read-only replica

   Create a read-only replica:

   avn service create <NAME_OF_REPLICA> --project <PROJECT_ID>\
   -t pg --plan <PLAN_TYPE> --cloud timescale-aws-us-east-1\
   -c pg_read_replica=true\
   -c service_to_fork_from=<NAME_OF_SERVICE_TO_FORK>\
   -c pg_version=11 -c variant=timescale

Example

To create a fork named replica-fork for a MST service named timescaledb with these parameters:

• PROJECT_ID: fork-project
• CLOUD_NAME: timescale-aws-us-east-1
• PLAN_TYPE: timescale-basic-100-compute-optimized

avn service create replica-fork --project fork-project\
-t pg --plan timescale-basic-100-compute-optimized\
--cloud timescale-aws-us-east-1 -c pg_read_replica=true\
-c service_to_fork_from=timescaledb -c\
pg_version=11 -c variant=timescale

You can switch to project-fork and view the newly created replica-fork using:

avn service list