ClickHouse Private API Reference

The ClickHouse Private API is a standalone optional component for managing ClickHouse Private clusters. It provides REST endpoints for backups, vertical scaling, password resets, and cluster status monitoring.

Configuration Options

The API is installed via Helm chart (helm/airgap-management).

Authentication

By default, basic authentication is disabled. For production environments, enable it via Helm:

--set-json='api.basicAuth.enabled=true'
--set-json='api.basicAuth.username="admin"'
--set-json='api.basicAuth.password="YOUR_SECURE_PASSWORD"'

When enabled, include credentials in requests:

curl -u admin:YOUR_SECURE_PASSWORD http://localhost:8080/api/v1/...

Resource Quantity Format

The API accepts Kubernetes resource quantity formats for CPU and memory fields.

CPU Quantities

Memory Quantities

Binary units (Ki, Mi, Gi) are recommended for memory to align with Kubernetes conventions.

Endpoints

Health Check

GET /readiness

Returns the health/readiness status of the API.

Response: 200 OK

Backups

Create Backup

POST /api/v1/backups?instance_id={instance_id}

Creates a new backup for the specified ClickHouse cluster.

Query parameters:

Request body:

{
    "incremental": false,
    "baseBackupUuid": "uuid-of-previous-backup",
    "databases": ["mydb"],
    "tables": ["mydb2.table"]
}

Response: 201 Created – Returns the created backup object including a UUID.

Behavior: Creates a Backup custom resource in the ClickHouse cluster namespace. The operator watches for new Backup objects and executes the relevant backup SQL statement, monitoring status via system tables.

Get Backup

GET /api/v1/backups/{backup_id}?instance_id={instance_id}

Returns the status and details of a specific backup.

Path parameters:

Query parameters:

Response: 200 OK – Returns the backup object. The status.state field indicates completion status (e.g., Ready when complete).

List Backups

GET /api/v1/backups?instance_id={instance_id}

Lists all backups for the specified cluster.

Query parameters:

Response: 200 OK – Returns an array of backup objects.

Example: Find the last successful backup UUID:

GET /api/v1/backups?instance_id=default-xx-01&status__state__eq=Ready&sort=status__finishTime&limit=1

Restore Backup

POST /api/v1/backups/{backup_id}/restore?instance_id={instance_id}&target_instance_id={target_instance_id}

Restores a backup onto a target ClickHouse cluster. Performs a RESTORE ALL of the backup.

Path parameters:

Query parameters:

Constraints:

• Restoration on the same instance (instance_id == target_instance_id) is disallowed for safety.
• It is recommended to restore onto a new cluster to avoid overloading the original.

Response: 202 Accepted – Returns the restore operation IDs.

Vertical Scaling

Scale Cluster

POST /api/v1/instances/{instance_id}/scale

Vertically scales a ClickHouse cluster by adjusting CPU and memory resources.

Path parameters:

Request body:

{
  "vertical": {
    "resources": {
      "cpu": "4",
      "memory": "16Gi"
    }
  }
}

*At least one of cpu or memory must be provided.

CPU-to-memory ratio: The API enforces a 1:4 ratio (1 CPU core per 4 GiB of memory) with a 5% margin. If only one resource is provided, the other is automatically derived to maintain this ratio.

Behavior: Updates the ServerPodPolicy of the ClickhouseCluster custom resource. The operator triggers a rolling restart of the StatefulSets with the new resource allocation.

Important: Unlike ClickHouse Cloud, ClickHouse Private does not use Make Before Break (MBB) scaling. Vertical scaling causes a rolling restart that may temporarily disrupt the service.

Response: 201 Created

Password Reset

Reset User Password

POST /api/v1/instances/{instance_id}/reset-user-password

Resets the password for a ClickHouse cluster user.

Path parameters:

Request body:

{
  "user_hashed_password": "<base64-encoded-sha256-hash>",
  "hashing_function": "sha256",
  "username": "default"
}

Password hash generation:

PASSWORD='My super secret p@$$w0rd'
if command -v sha256sum &> /dev/null; then
  HASHED_PASSWORD=$(echo -n "$PASSWORD" | sha256sum | awk '{printf $1}' | base64 | tr -d '\n')
else
  HASHED_PASSWORD=$(echo -n "$PASSWORD" | shasum -a 256 | awk '{printf $1}' | base64 | tr -d '\n')
fi

Constraints:

• Password resets cannot be performed on child instances (see compute-compute separation). Reset on the parent instance instead.

Response:

{
  "message": "User password reset successfully"
}

Behavior: Updates the CustomerAccount field in the ClickhouseCluster custom resource. The operator applies the credential change to the cluster. The password takes effect after the operator processes the change.

Cluster Status

Get Cluster Status

GET /api/v1/instances/{instance_id}/status

Returns the current state of the specified ClickHouse cluster.

Path parameters:

Response:

{
  "state": "Running",
  "previousState": "Provisioning",
  "message": "Cluster is healthy",
  "stateProvidedBy": "operator"
}

Use cases:

• Verify completion of a vertical scaling operation.
• Confirm a password reset has been applied across the cluster.
• Monitor cluster provisioning progress.

Endpoint Summary