--- title: Aiven Client | Tiger Data Docs description: Manage your services in the Managed Service for TimescaleDB with a command-line tool --- 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](#install-and-configure-the-aiven-client) - [Fork services with Aiven client](#fork-services-with-aiven-client) - [Configure Grafana authentication plugins](#configure-grafana-authentication-plugins) - [Send Grafana emails](#send-grafana-emails) - [Create a read-only replica with the Aiven client](#create-a-read-only-replica-with-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](https://portal.managed.timescale.com/login), 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](https://github.com/aiven/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`: Terminal window ``` pip install aiven-client ``` For more information about installing the Aiven Client, see the [Aiven](https://github.com/aiven/aiven-client) 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: Terminal window ``` 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: Terminal window ``` { "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: Terminal window ``` avn project list ``` This command shows a list of all your projects: Terminal window ``` 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](/docs/deploy/mst/about-mst/index.md). 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: Terminal window ``` avn project switch ``` 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. Terminal window ``` avn service list ``` 4. **Get the service details** Get the details of the MST service that you want to fork: Terminal window ``` avn service get ``` 5. **Create the fork** Create the fork: Terminal window ``` avn service create --project \ -t --plan --cloud \ -c service_to_fork_from= ``` ### 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` Terminal window ``` 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: Terminal window ``` 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](https://grafana.com/docs/grafana/v9.0/setup-grafana/configure-security/configure-authentication/google/). 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: Terminal window ``` avn switch ``` 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. Terminal window ``` avn service list ``` Get the details of the service that you want to integrate: Terminal window ``` avn service get ``` 3. **Integrate the plugin** Integrate the plugin with your services using the `` and `` from your Google developer console: Terminal window ``` avn service update -c auth_google.allowed_domains=\ -c auth_google.client_id=\ -c auth_google.client_secret= ``` 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](https://grafana.com/docs/grafana/v9.0/setup-grafana/configure-security/configure-authentication/github/). 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: Terminal window ``` avn switch ``` 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. Terminal window ``` avn service list ``` Get the details of the service that you want to integrate: Terminal window ``` avn service get ``` 3. **Integrate the plugin** Integrate the plugin with your service using the ``, and `` from your GitHub OAuth application: Terminal window ``` avn service update -c auth_github.client_id=\ -c auth_github.client_secret= ``` 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](https://grafana.com/docs/grafana/v9.0/setup-grafana/configure-security/configure-authentication/gitlab/). 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: Terminal window ``` avn project switch ``` 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. Terminal window ``` avn service list ``` Get the details of the service that you want to integrate: Terminal window ``` avn service get ``` 3. **Integrate the plugin** Integrate the plugin with your service using the ``, ``, and `` from your GitLab OAuth application: Terminal window ``` avn service update -c auth_gitlab.client_id=\ -c auth_gitlab.client_secret=\ -c auth_gitlab.allowed_groups= ``` 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: Terminal window ``` avn project switch ``` 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. Terminal window ``` avn service list ``` Get the details of the service that you want to integrate: Terminal window ``` avn service get ``` 3. **Configure the SMTP settings** Configure the Grafana service using the SMTP values: Terminal window ``` avn service update --project \ -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: Terminal window ``` 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: Terminal window ``` avn project switch ``` 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: Terminal window ``` avn service list ``` Get the details of the MST service that you want to fork: Terminal window ``` avn service get ``` 3. **Create a read-only replica** Create a read-only replica: Terminal window ``` avn service create --project \ -t pg --plan --cloud timescale-aws-us-east-1\ -c pg_read_replica=true\ -c service_to_fork_from=\ -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` Terminal window ``` 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: Terminal window ``` avn service list ```