Administrator Guide

• 1: Access Control
• 1.1: Role Based Access and Security Tiers
• 1.2: Account Management
• 1.3: Integrating Okta into the Altinity.Cloud login page
• 2: Altinity Backup Solutions
• 3: How to use Altinity Backup and the Restore Wizard
• 4: Cluster Explore Guide
• 4.1: Query Tool
• 4.2: Schema View
• 4.3: Processes

1 - Access Control

Altinity.Cloud provides role based access control. Depending the role granted to an Altinity.Cloud Account, they can assign other Altinity.Cloud accounts roles and grant permissions to access organizations, environments, or clusters.

1.1 - Role Based Access and Security Tiers

Access to ClickHouse data hosted in Altinity.Cloud is controlled through a combination of security tiers and account roles. This allows companies to tailor access to data in a way that maximizes security while still allowing ease of access.

Security Tiers

Altinity.Cloud groups sets of clusters together in ways that allows companies to provide Accounts access only to the clusters or groups of clusters that they need to.

Altinity.Cloud groups clusters into the following security related tiers:

• Nodes: The most basic level - an individual ClickHouse database and tables.
• Clusters: These contain one or more nodes provide ClickHouse database access.
• Environments: Environments contain one or more clusters.
• Organizations: Organizations contain one or more environments.

Account access is controlled by assigning an account a single role and a security tier depending on their role. A single account can be assigned to multiple organizations, environments, multiple clusters in an environment, or a single cluster depending on their account role.

Account Roles

The actions that can be taken by Altinity.Cloud accounts is based on the role they are assigned. The following roles and their actions based on the security tier is detailed in the table below:

Role	Environment	Cluster
orgadmin	Create, Edit, and Delete environments that they create, or are assigned to, within the assigned organizations. Administrate Accounts associated with environments they are assign to.	Create, Edit, and Delete clusters within environments they create or assigned to in the organization.
envadmin	Access assigned environments.	Create, Edit, and Delete clusters within environments they are assigned to in the organization.
envuser	Access assigned environments.	Access one or more clusters the account is specifically assigned to.

The account roles are tied into the security tiers, and allow an account to access multiple environment and clusters depending on what type of tier they are assigned to.

For example, we may have the following situation:

• Accounts peter, paul, and mary and jessica are all members of the organization HappyDragon.
• HappyDragon has the following environments: HappyDragon_Dev and HappyDragon_Prod, each with the clusters marketing, sales, and ops.

The accounts are assigned the following roles and security tiers:

Account	Role	Organization	Environments	Clusters
mary	orgadmin	HappyDragon	HappyDragon_Prod	*
peter	envadmin	HappyDragon	HappyDragon_Dev	*
jessica	envadmin	HappyDragon	HappyDragon_Prod, HappyDragon_Dev	*
paul	envuser	HappyDragon	HappyDragon_Prod	marketing

In this scenario, mary has the ability to access the environment HappyDragon_Prod, or can create new environments and manage them and any clusters within them. However, she is not able to edit or access HappyDragon_Dev or any of its clusters.

• Both peter and jessica have the ability to create and remove clusters within their assigned environments.
  • peter is able to modify the clusters in the environment HappyDragon_Dev.
  • jessica can modify clusters in both environments.
• paul can only access the cluster marketing in the environment HappyDragon_Prod.

1.2 - Account Management

Altinity.Cloud accounts with the role orgadmin are able to create new Altinity.Cloud accounts and associate them with organizations, environments, and one or more clusters depending on their role. For more information on roles, see Role Based Access and Security Tiers.

Account Page

The Account Page displays all accounts assigned to the same Organization and Environments as the logged in account.

For example: the accounts mario, luigi, and peach and todd are members of the organizations MushroomFactory and BeanFactory as follows:

Account	Role	Organization: MushroomFactory	Organization: BeanFactory
peach	orgadmin	*
mario	orgadmin		*
luigi	envuser		*
todd	envuser	*

• peach will be able to see their account and todd in the Account Page, while accounts mario and luigi will be hidden from them.
• mario will be able to see their account and luigi.

Access Accounts

To access the accounts that are assigned to the same Organizations and Environments as the logged in user with the account role orgadmin:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. All accounts that are in the same Organizations and Environments as the logged in account will be displayed.

Account Details

Accounts have the following details that can be set by an account with the orgadmin role:

1. Common Information:
   1. Name: The name of the account.
   2. Email (Required): The email address of the account. This will be used to login, reset passwords, notifications, and other uses. This must be a working email for these functions to work.
   3. Password: The password for the account. Once a user has authenticated to the account, they can change their password.
   4. Confirm Password: Confirm the password for the account.
   5. Role (Required): The role assigned to the account. For more information on roles, see Role Based Access and Security Tiers.
   6. Organization: The organization assigned to the account. Note that the orgadmin can only assign accounts the same organizations that the orgadmin account also belongs to.
   7. Suspended: When enabled, this prevents the account from logging into Altinity.Cloud.
2. Environment Access:
   1. Select the environments that the account will require access to. Note that the orgadmin can only assign accounts the same environments that the orgadmin account also belongs to.
3. Cluster Access:
   1. This is only visible if the Role is set to envuser. This allows one or more clusters in the environments the new account was assigned to in Environmental Access to be accessed by them.
4. API Access:
   1. Allows the new account to make API calls from the listed domain names.

Account Actions

Create Account

orgadmin accounts can create new accounts and assign them to the same organization and environments they are assigned to. For example, continuing the scenario from above, if account peach is assigned to the organization MushroomFactory and the environments MushroomProd and MushroomDev, they can assign new accounts to the organization MushroomFactory, and to the environments MushroomProd or MushroomDev or both.

To create a new account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.

2. From the left navigation panel, select Accounts.

3. Select Add Account.

4. Set the fields as listed in the Account Details section.

   

5. Once all settings are completed, select Save. The account will be able to login with the username and password, or if their email address is registered through Google, Auth0.

Edit Account

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
4. Update the fields as listed in the Account Details section.
5. When finished, select Save.

Suspend Account

Instead of deleting an account, setting an account to Suspended may be more efficient to preserve the accounts name and other settings. A suspended account is unable to login to Altinity.Cloud. This includes directly logging through a browser and API calls made under the account.

To suspend or activate an account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Edit.
   1. To suspend an account, toggle Suspended to on.
   2. To activate a suspended account, toggle Suspended to off.
4. When finished, select Save.

Delete Account

Accounts can be deleted which removes all information on the account. Clusters and environments created by account will remain.

To delete an existing account:

1. Login to Altinity.Cloud with an account granted the orgadmin role.
2. From the left navigation panel, select Accounts.
3. From the left hand side of the Accounts table, select the menu icon for the account to update and select Delete.
4. Verify the account is to be deleted by selecting OK.

1.3 - Integrating Okta into the Altinity.Cloud login page

10 March 2023 · Read time 3 min

Overview - Okta Integration

Altinity uses Auth0 so that customers who are already logged into other identity providers such as Google or Okta are automatically granted access to Altinity.Cloud.

The following diagram shows the Altinity login process using Auth0, plus adding Okta as discussed on this page.

1. Logging in to Altinity.Cloud using a Login Email and Password.
2. The Auth0 login link to use a 3rd party authenticator such as Google or Okta. (See Okta/Auth0 Altinity Integration)
3. Using Okta allows previously authorized logged-in employees to gain immediate access to Altinity.Cloud. (See Okta Customer Configuration)

Figure 1 – Altinity integration of an Okta customer to Auth0.

---

Setting up the Auth0 Connection

These steps are for Altinity customers to configure their login integration with Okta.

1. Go to Auth0 Dashboard 》Authentication 》Enterprise.
2. Click Create (➕ plus icon) located next to OpenID Connect.
3. Provide a name.
4. Copy the customer-provided Okta domain to Issuer URL.
5. Copy the customer-provided Client ID to Client ID.
6. Click Create.

If you closed the page, select Dashboard 》Applications 》<application name> to view those settings.

Contact Altinity Support

Contact Altinity to add the customer’s Okta domain and Client ID to the Altinity.Cloud access list.
Please provide the following:

• The domain you want to sign in on the Okta side
• The Issues URL
• Client ID

---

Okta/Auth0 Altinity Integration

These steps are for Altinity technical support to add an Okta connection to Auth0.

Setting up the Auth0 connection

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click Create (plus icon) next to OpenID Connect.
3. Provide a name.
4. Copy the Okta domain provided by a customer to Issuer URL.
5. Copy the Client ID provided by a customer to the Client ID.
6. Click Create.

Enabling the connection

1. Go to Auth0 Dashboard -> Applications.
2. Click the application you wish to use with the connection.
3. Go to the Connections tab, find your newly created connection, and switch it on.

Testing the connection

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click OpenID Connect (not the plus sign, the text).
3. Find the newly created connection.
4. Click the three dots on the right -> Try.
   • You should be greeted with an Okta password prompt, or if there is a problem, an error is shown.
     
     

Enabling the button

1. Go to Auth0 Dashboard -> Authentication -> Enterprise.
2. Click OpenID Connect (not the plus sign, the text).
3. Find the newly created connection and click its name.
4. Go to the Login Experience tab.
5. Check the Connection button -> Display connection as a button.
6. Configure the Button display name and logo URL.
7. Click Save.

Testing

1. Go to the https://acm.altinity.cloud login page.
2. Click Sign in with Auth0.
3. A button for the new connection should be shown.
4. Upon clicking the button, it should either ask for Okta credentials or log straight into the app.

---

Altinity blog post

The following Altinity blog post provides an in-depth discussion of adding Okta as an identity provider.

• How we set up Okta as an Altinity Cloud Identity Provider using Auth0

2 - Altinity Backup Solutions

14 March 2023 · Read time 1 min

Overview

This section covers backup and restore options provided by the Altinity Cloud Manager.

Backups

• On-demand backups are provided in the cluster ACTIONS menu.
• Altinity supports 3rd-party external cloud provider remote backups such as Amazon or Google.
• New clusters created by the Cluster Launch Wizard are automatically backed up daily for 7 days.
• Create customized Altinity backups schedules.

Restoring Data

• Restore a backup to an existing cluster

• Restore a backup to a new cluster using the Cluster Launch Wizard.

• Restore a cluster or table from a backups list.

• Choose a specific day or on-demand snapshot to restore from.

Contact Altinity Support

• https://altinity.com/24x7-support/

3 - How to use Altinity Backup and the Restore Wizard

14 March 2023 · Read time 5 min

Overview

This section covers the Altinity Cloud Manager Cluster Restore Wizard, which is available from your cluster’s ACTIONS > Restore a Backup menu. This guide walks you through the steps to restore a cluster from an Altinity backup.

Create Backup

In addition to scheduled backups, an ad hoc backup feature is provided to create an on-demand snapshot. By manually creating a backup from the ACTIONS 》 Create Backup Backup, each backup request adds a Tag with a timestamp.

• Note that for ad hoc backups, there are no configuration options. A dialog box (Cluster Backup) displays to let you know the backup is in progress.

Figure 1 – Making an on-demand backup: the ACTIONS 》Create Backup and the confirmation window.

UI Text

• Cluster Backup
  The Backup procedure for the Cluster your-backup has been scheduled.
  It will require some time to finish the procedure.
  Note: Backup files are handled by ACM and stored separately from the cluster instances.
  These backup files will remain available even if you accidentally delete the cluster.

Backup Scheduling

To change the backup schedule from the 7 day default, bring up your cluster Environments settings, select the 3-dot menu icon beside your cluster, choose Edit then the Backups tab.

Figure 2 – Backup Schedule settings from the Environment > Cluster > Edit > Backup tab.

Restore a Backup

Prerequisites

• Login to the Altinity.Cloud Manager https://acm.altinity.cloud/clusters
• The backup operator has backup roles and permissions set up in My Account > Common Information > Role and Access Rights
• Accounts > Manage Roles > Account Role Details > Cluster Settings and NodeTypes are set to (Allow)
• The backup provider is Altinity or an external cloud provider
• The Organization list of account Names has been granted the role of allowing backups and restores to the listed Environments

NOTE: New users do not have the rights to perform manual backups and restore functions, so the default view of the Actions menu will not display the backup or restore options.

The following wizard screens are covered on this page:

1. Backup Location
2. Source Cluster
3. Source Backup
4. Destination Cluster
5. Restore Summary
6. Cluster Launch Wizard

The following illustration shows a summary of the various screens available in the Restore Wizard option.

• The Backup Location may be the Altinity.Cloud Backup or a Remote Backup of your choice of cloud provider.
• Colored orange, the Cluster Launch Wizard opens after you CONTINUE from the last screen of the Cluster Restore Wizard.
  

  

Figure 3 – Each of the 5 Restore Wizard screens and the available settings.

---

Clusters > Actions - Where to find the Restore Wizard

The ACTIONS menu contains the Restore a Backup function that starts the Cluster Restore Wizard within the Altinity.Cloud Connection Manager. The following screenshot shows the Altinity.Cloud Connection Manager dashboard screen for cluster-a, highlighting points of interest.

1. The your-environment menu is the parent for your clusters.
2. The Clusters in the left navigation pane let you know where you are in the ACM.
3. The cluster-a is the name of the dashboard you are currently viewing.
4. The Actions menu is where the Backup and Restore functions are found.

NOTE: If your account and roles are not set up, you will not see all of the items in the left-hand pane or all the items in the Actions menu.

Figure 4 – The dashboard view of cluster-a showing the selected environment and the ACTIONS menu.

---

ACTIONS menu - Backup and Restore

From your cluster dashboard, the ACTIONS menu lists the Restore a Backup setting.

Figure 5 – The ACTIONS menu shows the Restore a Backup setting.

---

Running the Cluster Restore Wizard

From the Altinity Cloud Manager cluster screen select ACTIONS > Restore a Backup to open the Cluster Restore Wizard. The

Features of the interface shown in Figure 4:

• The left side of each Cluster Restore Wizard screen shows the progress of the restore operation.
• The green bar indicates the section of the wizard you are viewing.
• The dimmed choices indicate you have not yet set anything in those screens.
• After progressing through the wizard screens, you can return to a previous screen by clicking on any of the 5 names of the screens shown in the left pane.

Buttons located at the bottom right include:

• CANCEL - Closes the Wizard without saving any settings.
• NEXT - Indicates that there is another screen that you will go to.
• BACK - Returns to the previous screen while retaining any changes you have made.
• CONTINUE - Appears on the last screen of the wizard. Click to start the Cluster Launch Wizard.
• The left pane titles are also buttons that allow you to jump directly to without using the BACK button.

1. Backup Location

This screen lets you choose where your backups are located, either from Altinity or from your own cloud provider.

• Altinity.Cloud Backup
• Remote Backup (AWS or GCP)

Backup Location Information

• This Backup Location information screen is used to choose between an Altinity backup or an external cloud vendor.

Altinity.Cloud Backup

To use Altinity as the source of the cluster you want to restore:

1. Select Altinity.Cloud Backup from the Backup Location Information.
2. Select an Altinity environment from the Source Environment menu, for example, tenant-a.
3. Select NEXT to go to the next screen Source Cluster.

Figure 6 – The Backup Location Information screen, selecting the Altinity.Cloud Backup and the Source Environment (for example: tenant-a).

Remote Backup

Use this selection if you are using a third-party cloud provider such as Amazon (AWS) or Google (GCP).
Select Remote Backup, fill in the fields then NEXT.

1. Select Remote Backup, fill in the following fields from steps 2 to 7 then NEXT.

Figure 7 – The Altinity Cloud Manager (ACM) home page, selecting the LAUNCH CLUSTER button.

2. Select an Altinity-supported cloud provider:
   
   Cloud Storage Provider

   • AWS (Amazon Web Services console)
   • GCP (Google Cloud Platform console)
   
   

3. Copy the AWS or GCP Access Key and paste it here:
   
   Access Key

   • UI Text:
     Storage Access Key
   • Example:
     EXAMPLE_KEY_ID_ABCDEFGH

4. Copy the AWS or GCP Secret Key and paste it here:
   
   Secret Key
   • UI Text:
     Storage Secret Key
   • Example:
     EXAMPLE_SECRET_ACCESS_KEY_ID_ABCDEFGH

5. Enter the Region identifier string ID here:
   
   Region
   • UI Text:
     Storage Region string ID
     (For “US West (Oregon)” the ID is us-west-2 )
   • Example:
     us-west-2
     
     More information:
     • Google Region name guidelines
     • Amazon Region name guidelines

6. Enter the Bucket name:
   
   Bucket
   • UI Text:
     Storage Bucket
   • Example:
     valid.Storage-name_buck3t
     
     More information:
     • Google bucket name guidelines
     • Amazon bucket name guidelines

7. Select ACM (Altinity Cloud Manager) if you want to retain this folder structure:
   
   ACM Compatible Folder Structure
   • UI Text:
     Bucket contents was previously created by ACM or has a fully ACM-compatible structure
   • Example:
     (checked)

8. Select NEXT to go to the next screen Source Cluster.

---

2. Source Cluster

The Source Cluster Information screen lets you choose one cluster from a list of cluster names. The following column names appear in a scrolling table:

• Radio button - Marks the cluster you want to use as the source. (Example: selected)
• Cluster - This is the name of the backed-up cluster. (Example: abc)
• Namespace - This is the environment name. (Example: tenant-a)
• Configuration - Checked if the configuration information is included in the backup (Example: checked)

To select a cluster name:

1. In the Source Cluster Information scrolling table, select the radio button of the Cluster name.
   
   Source Cluster Information
   
   

   • UI Text:
     Note: It is possible to restore a complete Cluster’s configuration only if a given backup contains it.
   • Example:
     abc

2. Select NEXT to go to the next screen Source Backup.

Figure 8 – The restore wizard screen 2 of 5 Source Cluster Information showing the selected cluster abc.

---

3. Source Backup (Backup Tag)

The Backup Information: <environment name>/<cluster name> screen lists the available backups by date. Note that the environment name (example tenant-a) and cluster name (example: abc) were selected in the previous wizard screens.

The following column names appear in a scrolling table:

• Radio button - Marks the backup Tag name you want to use.
• Tag - This is the 14-digit name of the backed-up cluster that is the
  year yyyy
  month mm
  day dd
  time hhmmss
  (Example: 20230104201700)
• Size - This is the size of the backup. (Example: 450 B)
• Timestamp - The date and time of the backup (Example: 2023-01-04-20:17:00)
• Configuration - Checked if the configuration information is included in the backup (Example: checked)

To select a backup:

1. In the screen Backup Information: tenant-a/abc select the radio button by the Tag name.
   Example:
   Tag: 20230104201700

2. Select NEXT to go to the next screen Destination Cluster.

Figure 9 – The wizard restore wizard screen 3 of 5 Backup Information showing a Tag backup selected.

---

4. Destination Cluster

The Destination Cluster Information screen is where the restored data is saved to.

Available options are:

• Launch a new Cluster
• Launch a new Cluster using configuration and settings of a source cluster
• Restore into an existing cluster
  • A new cluster will be launched using a fresh setup (it may be different from the original Cluster configuration)

Launch a new Cluster

The Launch of a new cluster runs the Cluster Launch Wizard immediately after the Review & Confirm screen appears and you select CONTINUE.

Select Launch a new cluster then NEXT to advance to Restore Summary.

Launch a new Cluster using the configuration and settings of a source cluster

Use this setting if you want to override the backed-up cluster settings such as CPU, RAM, and Storage size to instead use the destination cluster values.

The Launch a New Cluster runs the Cluster Launch Wizard immediately after the Review & Confirm screen appears and you select CONTINUE.

Select Launch a new cluster then NEXT to advance to Restore Summary.

Launch a new Cluster

In the Name field, create a new name.

• Example:
  restored-cluster-backup

Source Cluster

Ignores the backed-up settings and instead uses the settings in the destination cluster.
This is useful when you want to ignore the settings of the existing cluster and instead use the backed-up configuration.

Existing Cluster

This is the opposite of the Source Cluster.
This is useful when you want to use the settings of the existing cluster and not the backed-up configuration.

Figure 10 – The restore wizard screen 4 of 5 Destination Cluster Information with Launch a new Cluster selected.

---

5. Restore Summary

This Review & Confirm screen covers communication details such as port settings and endpoint information.
To change a setting, select BACK or the title of the screen from the left-hand pane.
Select CONTINUE to save and begin the restore process.
IMPORTANT: Do not perform any changes to the restored cluster until the process is complete

UI Text:
Please review and confirm the selected options:

• Backup Location: (example) Altinity.Cloud backup from this environment
• Source Cluster: (example) tenant-a/abc
• Backup Tag: (example) 0230104201700 (size: 450 B )
• Destination Cluster: (example) new-cluster
  • Name〈cluster name〉: (example) restored-clustr (15-character limit)

Figure 11 – The last restore wizard screen 5 of 5 Review & Confirm.

---

Cluster Launch Wizard

The Cluster Launch Wizard starts automatically after selecting CONTINUE from the Cluster Restore Wizard.
From that point, follow the instructions to create a cluster to restore to.

Figure 12 – The Cluster Launch Wizard appears after you select CONTINUE from the Cluster Restore Wizard.

4 - Cluster Explore Guide

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.

4.1 - Query Tool

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:

   

   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:

      

      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.

4.2 - Schema View

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:

   

   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.

4.3 - Processes

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:

   

   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.