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:

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.

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

  1. In MST Portal, click User Information in the top right corner.
  2. In the User Profile page, navigate to the Authenticationtab.
  3. Click Generate Token.
  4. In the Generate access token dialog, type a descriptive name for the token. Leave the rest of the fields blank.
  5. Copy the generated authentication token and save it.

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.

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.

  1. Change to the install directory that contains the configuration files:

    cd ~/.config/aiven/
  2. 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"
    }
  3. Save the aiven-credentials.json file.

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

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.

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

  2. Switch to the project that contains the service you want to fork:

    avn project switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to fork:

    avn service get <SERVICE_NAME>
  5. 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>

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

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.

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. In the Aiven Client, connect to your Managed Service for TimescaleDB service.

  2. Switch to the project that contains the Grafana service you want to integrate:

    avn switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to integrate:

    avn service get <SERVICE_NAME>
  5. 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>
  6. Log in to Grafana with your service credentials.

  7. Navigate to ConfigurationPlugins 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.

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. In the Aiven Client, connect to your Managed Service for TimescaleDB service.

  2. Switch to the project that contains the Grafana service you want to integrate:

    avn switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to integrate:

    avn service get <SERVICE_NAME>
  5. 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>
  6. Log in to Grafana with your service credentials.

  7. Navigate to ConfigurationPlugins. 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.

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. In the Aiven Client, connect to your Managed Service for TimescaleDB service.

  2. Switch to the project that contains the Grafana service you want to integrate:

    avn project switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to integrate:

    avn service get <SERVICE_NAME>
  5. 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>
  6. Log in to Grafana with your service credentials.

  7. Navigate to ConfigurationPlugins. 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.

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, 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.
  1. In the Aiven client, connect to your Managed Service for TimescaleDB service.

  2. Switch to the project that contains the Grafana service you want to integrate:

    avn project switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to integrate:

    avn service get <SERVICE_NAME>
  5. 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"
  6. Optional Review all available custom options, and configure:

    avn service types -v

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

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. In the Aiven client, connect to your Managed Service for TimescaleDB service.

  2. Switch to the project that contains the TimescaleDB service you want to create a read-only replica for:

    avn project switch <PROJECT>
  3. 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
  4. Get the details of the service that you want to fork:

    avn service get <SERVICE_NAME>
  5. 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

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

Found an issue on this page?Report an issue or Edit this page in GitHub.