Aiven Client for Managed Service for TimescaleDB

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

You can use the Aiven Client tool to:

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

Instructions:

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.

Creating an authentication token in Managed Service for TimescaleDB

In MST Portal, click User Information in the top right corner.
In the User Profile page, navigate to the Authenticationtab.
Click Generate 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 services on Managed Service for TimescaleDB.

Configuring Aiven Client to connect to Managed Service for TimescaleDB

Change to the install directory that contains the configuration files:
```
cd ~/.config/aiven/
```
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.

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 a fork a service, you create an exact copy of the service, including the underlying database. You can use a fork of your 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 Services.

Creating a fork of your service

In the Aiven client, connect to your Managed Service for TimescaleDB service.
Switch to the project that contains the service you want to fork:
```
avn project switch <PROJECT>
```
List the services in the project, and make a note of the service that you want to fork, listed under SERVICE_NAME column in the output.
```
avn service list
```
Get the details of the service that you want to fork:
```
avn service get <SERVICE_NAME>
```

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 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.

How to integrate the Google authentication plugin

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>
```
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>
```

Integrate the plugin with your service 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>

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.

How to integrate the GitHub authentication plugin

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>
```
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>
```
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>
```
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 viewerpermission 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

How to integrate the GitLab authentication plugin

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>
```
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>
```

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>

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 viewerpermission 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.

Prerequisites

Before you begin, make sure you have:

(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.

Configuring the SMTP server for Grafana service

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>
```
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>
```

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"

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.

Creating a read-only replica of your service

In the Aiven client, connect to your Managed Service for TimescaleDB service.
Switch to the project that contains the TimescaleDB service you want to create a read-only replica for:
```
avn project switch <PROJECT>
```
List the 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 service that you want to fork:
```
avn service get <SERVICE_NAME>
```

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 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

Note

Note

Note

Related Content