This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

General User Guide

Instructions on general use of Altinity.Cloud

Altinity.Cloud is made to be both convenient and powerful for ClickHouse users. Whether you’re a ClickHouse administrator or a developer, these are the concepts and procedures common to both.

1 - How to Create an Account

Creating your Altinity.Cloud account.

To create an Altinity.Cloud account, visit the Altinity.Cloud info page and select Free Trial. Fill in your contact information, and our staff will reach out to you to create a test account.

If you’re ready to upgrade to a full production account, talk to one of our consultants by filling out your contact information on our Consultation Request page.

2 - How to Login

Login to Altinity.Cloud

Altinity.Cloud provides the following methods to login to your account:

  • Username and Password
  • Auth0

Login with Username and Password

To login to Altinity.Cloud with your Username and Password:

  1. Open the Altinity.Cloud website.
  2. Enter your Email Address registered to your Altinity.Cloud account.
  3. Enter your Password.
  4. Click Sign In.

Once authenticated, you will be logged into Altinity.Cloud.

Login with Auth0

Auth0 allows you to use your existing Altinity account using trust authentication platforms such as Google to verify your identity.

  • IMPORTANT NOTE: This requires that your Altinity.Cloud account matches the authentication platform you are using. For example, if your email address in Altinity.Cloud is listed as Nancy.Doe@gmail.com, your Gmail address must also be Nancy.Doe@gmail.com.

To login using Auth0:

  1. Open the Altinity.Cloud website.
  2. Select Auth0.
  3. Select which authentication platform to use from the list (for example: Google).
    1. If this is your first time using Auth0, select which account to use. You must be already logged into the authentication platform
  4. You will be automatically logged into Altinity.Cloud.

3 - How to Logout

Logout of Altinity.Cloud

To logout:

  1. Select your profile icon in the upper right hand corner.
  2. Select Log out.

Your session will be ended, and you will have to authenticate again to log back into Altinity.Cloud.

4 - Account Settings

Account and profile settings.

Access My Account

To access your account profile:

  1. Select your user profile in the upper right hand corner.

  2. Select My Account.

    Access user account

My Account Settings

From the My Account page the following settings can be viewed:

  • Common Information. From here you can update or view the following:
    • Email Address View Only: Your email address or login
    • Password settings.
    • Dark Mode: Set the user interface to either the usual or darker interface.
  • API Access: The security access rights assigned to this account.
  • Access Rights: What security related actions this account can perform.

Update Password

To update your account password:

  1. Click your profile icon in the upper right hand corner.

  2. Select My Account.

  3. In the Common Information tab, enter the new password in the Password field.

  4. Select Save.

    Altinity Cloud user common settings

API Access Settings

Accounts can make calls to Altinity.Cloud through the API address at https://acm.altinity.cloud/api, and the Swagger API definition file is available at https://acm.altinity.cloud/api/reference.json.

Access is controlled through API access keys and API Allow Domains.

API Access Keys

Accounts can use this page to generate one or more API keys that can be used without exposing the accounts username and password. They allow API calls made to Altinity.Cloud to be made by the same Account as the keys were generated for.

When an Altinity.Cloud API key is generated, an expiration date is set for the key. By default, the expiration date is set 24 hours after the key is generated, with the date and time set to GMT. This date can be manually adjusted to allow the expiration date to make the API key invalid at the date of your choosing.

Create Altinity.Cloud API Key

To generate a new API key:

  1. Click your profile icon in the upper right hand corner.
  2. Select My Account.
  3. In the API Access tab, select + Add Key. The key will be available for use with the Altinity.Cloud API.

To change the expiration date of an API key:

  1. Click your profile icon in the upper right hand corner.
  2. Select My Account.
  3. In the API Access tab, update the date and time for the API key being modified. Note that the date and time are in GMT (Greenwich Mean Time).

To remove an API key:

  1. Click your profile icon in the upper right hand corner.
  2. Select My Account.
  3. In the API Access tab, select the trashcan icon next to the API key to delete. The key will no longer be allowed to connect to the Altinity.Cloud API for this account.

API Allow Domains

API submissions can be restricted by the source domain address. This provides enhanced security by keeping API communications only between authorized sources.

To update the list of domains this account can submit API commands from:

  1. Click your profile icon in the upper right hand corner.
  2. Select My Account.
  3. In the API Access tab, list each URL this account can submit API commands from. Each URl is a separate line.
  4. Click Save to update the account settings.
Altinity Cloud user common settings

Access Rights

The Access Rights page displays which permissions your account has. These are listed in three columns:

  • Section: The area of access within Altinity.Cloud, such as Accounts, Environments, and Console.
  • Action: What actions the access right rule allows within the section. Actions marked as * include all actions within the section.
  • Rule: Whether the Action in the Section is Allow (marked with a check mark), or Deny (marked with an X).

5 - Notifications

Notifications critical to your Altinity.Cloud account.

Notifications allow you to see any messages related to your Altinity.Cloud account. For example: billing, service issues, etc.

To access your notifications:

  1. From the upper right corner of the top navigation bar, select your user ID, then Notifications.

    Access notifications

Notifications History

The Notifications History page shows the notifications for your account, including the following:

  • Message: The notifications message.
  • Level: The priority level which can be:
    • Danger: Critical notifications that can effect your clusters or account.
    • Warning: Notifications of possible issues that are less than critical.
    • News: Notifications of general news and updates in Altinity.Cloud.
    • Info: Updates for general information.

6 - Billing

Managing billing for Altinity.Cloud.

Accounts with the role orgadmin are able to access the Billing page for their organizations.

To access the Billing page:

  1. Login to your Altinity.Cloud with an account with the orgadmin role.
  2. From the upper right hand corner, select the Account icon, and select Billing.
Access Billing

From the billing page, the following Usage Summary and the Billing Summary are available for the environments connected to the account.

Billing page

Usage Summary

The Usage Summary displays the following:

  • Current Period: The current billing month displaying the following:
    • Current Spend: The current total value of charges for Altinity.Cloud services.
    • Avg. Daily Spend: The average cost of Altinity.Cloud services per day.
    • Est. Monthly BIll: The total estimated value for the current period based on Current Spend and if usage continues at the current rate.
  • Usage for Period: Select the billing period to display.
  • Environment: Select the environment or All environments to display billing costs for. Each environment, its usage, and cost will be displayed with the total cost.

Billing Summary

The Billing Summary section displays the payment method, service address, and email address used for billing purposes. Each of these settings can be changed as required.

7 - System Status

View the status of Altinity.Cloud services.

The System Status page provides a quick view of whether the Altinity.Cloud services are currently up or down. This provides a quick glance to help devops staff determine where any issues may be when communicating with their Altinity.Cloud clusters.

To access tne System Status page:

  1. Login to your Altinity.Cloud account.

  2. From the upper right hand corner, select the Account icon, and select System Status.

    Access user account

System Status Page

The System Status page displays the status of the Altinity.Cloud services. To send a message to Altinity.Cloud support representatives, select Get in touch.

From the page the following information is displayed:

Altinity.Cloud system statut page

This sample is from a staging environment and cluster that was stopped and started to demonstrate how the uptime tracking system works.

  • Whether all Altinity.Cloud services are online or if there are any issues.
  • The status of services by product, with the uptime of the last 60 days shown as either green (the service was fully available that day), or red (the service suffered an issue). Hovering over a red bar will display how long the service was unavailable for the following services:
    • ClickHouse clusters
    • Ingress
    • Management Console

Enter your email at the bottom of the page in the section marked Subscribe to status updates to receive notifications via email regarding any issues with Altinity.Cloud services.

8 - Clusters View

Overview of the Clusters View

The Clusters View page allows you to view available clusters and access your profile settings.

To access the Clusters View page while logged in to Altinity.Cloud, click Altinity Cloud Manager.

The Clusters View page is separated into the following sections:

  • A: Cluster Creation: For more information on how to create new clusters, see the Administrator Guide.
  • B: Clusters: Each cluster associated with your Altinity.Cloud account is listed in either tile format, or as a short list.
  • C: User Management:
    • Change which environment clusters are on display.
    • Access your Account Settings.
Clusters View

Organizational Admins have additional options in the left navigation panel that allows them to select the Accounts, Environments, and Clusters connected to the organization’s Altinity.Cloud account.

Change Environment

Accounts who are assigned to multiple Altinity.Cloud environments can select which environment’s clusters they are viewing. To change your current environment:

  1. Click the environment dropdown in the upper right hand corner, next to your user profile icon.
  2. Select the environment to use. You will automatically view that environment’s clusters.
Change Environment

Manage Environments

Accounts that have permission to manage environments access them through the following process:

  1. Select the Settings icon in the upper right hand corner.
  2. Select Environments.
Manage Environments

For more information on managing environments, see the Administrator Guide.

Access Settings

For information about access your account profile and settings, see Account Settings.

Cluster Access

For details on how to launch and manage clusters, see the Administrator Guide for Clusters.

9 - Uptime Schedules

Uptime Schedule Overview

Uptime schedules allow users to shut off ClickHouse servers automatically on a schedule or after a period of inactivity. It’s an easy way to reduce the bill for servers that are used intermittently. When the server is shut down, Altinity.Cloud does not bill you for server compute resources or support. Storage (including backups) is still billed.

All users who have access to the cluster dashboard may access uptime schedules.

Important note! Uptime schedules are intended for ClickHouse clusters that only operate intermittently. Do not enable them for production clusters that operate continuously. Doing so may cause the ClickHouse server to stop unexpectedly, creating a potential service outage.

Accessing Uptime Schedules

To set up an uptime schedule open the cluster dashboard and select Uptime Schedule from the CONFIGURE menu. The Clusters View page allows you to view available clusters and access your profile settings.

Uptime Menu

Clusters with an active uptime schedule will also have a stopwatch icon beside the cluster name on the dashboard panel. You can access the uptime schedule by clicking on the icon.

Uptime Schedule Icon

If there is no icon, it means that no uptime schedule is currently active.

Regardless of how you access the uptime schedule, you will see a popup window that shows the current status. The default setting is ALWAYS ON, which means the cluster operates continuously.

Default Uptime Schedule

Stopping Servers after a Period of Inactivity

Select STOP WHEN INACTIVE to configure the cluster to stop after a period of inactivity. For example, you may stop clusters after two hours of inactivity. This is a useful setting for development servers. Choose your desired inactivity period. Press CONFIRM to save the setting.

Inactive Uptime Schedule

Once the server becomes inactive, you must restart it manually using the ACTIONS->RESUME on the cluster dashboard.

Stopping Clusters on a Schedule

You may also configure clusters to run on a schedule using the ON SCHEDULE tab. The following example shows how to configure a server to run 24 hours on Monday, Wednesday, Friday and 8am to 5pm on Tuesday, Thursday. Note that the time zone is GMT, so you’ll need to convert your local time zone to GMT values. Press CONFIRM to save the schedule.

Calendar Uptime Schedule

10 - Cluster Explore Guide

How to explore a Cluster through queries, schema and processes

Altinity.Cloud users a range of options they can take on existing clusters.

For a quick view on how to create a cluster, see the Altinity.Cloud Quick Start Guide. For more details on interacting with clusters, see the Administrative Clusters Guide.

10.1 - Query Tool

How to submit ClickHouse queries to a cluster or nodes of the cluster

The Query Tool page allows users to submit ClickHouse SQL queries directly to the cluster or a specific cluster node.

To use the Query Tool:

  1. Select Explore from either the Clusters View or the Clusters Detail Page.

  2. Select Query from the top tab. This is the default view for the Explore page.

  3. Select from the following:

    Query Page
    1. Select which cluster to run a query against.

    2. Select Run DDLs ON CLUSTER to run Distributed DDL Queries.

    3. Select the following node options:

      Select node for query.
      1. Any: Any node selected from the Zookeeper parameters.
      2. All: Run the query against all nodes in the cluster.
      3. Node: Select a specific node to run the query against.
    4. The Query History allows you to scroll through queries that have been executed.

    5. Enter the query in the Query Textbox. For more information on ClickHouse SQL queries, see the SQL Reference page on ClickHouse.tech.

    6. Select Execute to submit the query from the Query Textbox.

    7. The results of the query will be displayed below the Execute button.

Additional tips and examples are listed on the Query page.

10.2 - Schema View

Viewing the database schema for clusters and nodes.

The Schema page allows you to view the databases, tables, and other details.

To access the Schema page:

  1. Select Explore from either the Clusters View or the Clusters Detail Page.

  2. Select Schema from the top tab.

  3. Select the following node options:

    Select node for query.
    1. Any: Any node selected from the Zookeeper parameters.
    2. All: Run the query against all nodes in the cluster.
    3. Node: Select a specific node to run the query against.

To view details on a table, select the table name. The following details are displayed:

  • Table Description: Details on the table’s database, engine, and other details.
  • Table Schema: The CREATE TABLE command used to generate the table.
  • Sample Rows: A display of 5 selected rows from the table to give an example of the data contents.

10.3 - Processes

How to view the processes for a cluster or node.

The Processes page displays the currently running processes on a cluster or node.

To view the processes page:

  1. Select Explore from either the Clusters View or the Clusters Detail Page.

  2. Select Processes from the top tab.

  3. Select the following node options:

    Select node for query.
    1. Any: Any node selected from the Zookeeper parameters.
    2. All: Run the query against all nodes in the cluster.
    3. Node: Select a specific node to run the query against.

The following information is displayed:

  • Query ID: The ClickHouse ID of the query.
  • Query: The ClickHouse query that the process is running.
  • Time: The elapsed time of the process.
  • User: The ClickHouse user running the process.
  • Client Address: The address of the client submitting the process.
  • Action: Stop or restart a process.