Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Install the ClickHouse Private API

View as MarkdownEdit this pageReport an issueSet up docs MCP

This tutorial walks you through installing the ClickHouse Private API, an optional standalone component that provides support for common management operations such as backups and vertical scaling.

Prerequisites

Before starting, ensure you have:

  • ClickHouse Operator installed (see tutorials/deploy-aws.md, Step 8)
  • At least one ClickHouse cluster deployed (see tutorials/deploy-aws.md, Step 9)
  • Access to the ClickHouse private ECR repository (access details provided by ClickHouse during onboarding)
  • Target ECR repositories created in your AWS account:
    • airgap-management
    • helm/airgap-management

Step 1: Copy Container Images

Use skopeo to copy the Private API image and Helm chart to your ECR.

SOURCE_ECR_ACCOUNT_ID=<account-id-from-onboarding>
SOURCE_REGION=us-east-1
SOURCE_ECR_REPO=$SOURCE_ECR_ACCOUNT_ID.dkr.ecr.$SOURCE_REGION.amazonaws.com

TARGET_REGION=us-west-2
TARGET_ECR_REPO=0000000000.dkr.ecr.$TARGET_REGION.amazonaws.com

# log into our ECR
aws ecr get-login-password --region $SOURCE_REGION | skopeo login --username AWS --password-stdin $SOURCE_ECR_REPO

# log into the target AWS repo
aws ecr get-login-password --region $TARGET_REGION | skopeo login --username AWS --password-stdin $TARGET_ECR_REPO

# copy each image to target ECR, be sure to include the --all flag
skopeo copy --all docker://$SOURCE_ECR_REPO/airgap-management:1.173.2 docker://$TARGET_ECR_REPO/airgap-management:1.173.2
skopeo copy --all docker://$SOURCE_ECR_REPO/helm/airgap-management:1.173.2 docker://$TARGET_ECR_REPO/helm/airgap-management:1.173.2

The version tags above are the current release. See Latest Release for the full list.

Step 2: Install via Helm

The Private API is installed in a dedicated namespace.

# update ECR_HOST as needed
ECR_HOST=0000000000.dkr.ecr.us-west-2.amazonaws.com

# should use the version of the API's helm chart
API_HELM_VERSION=1.173.2

# set the API image tag
API_IMAGE_TAG=1.173.2

helm install clickhouse-private-api \
   oci://$ECR_HOST/helm/airgap-management \
   --version=$API_HELM_VERSION \
   --create-namespace \
   -n clickhouse-private-api \
   --set-json="image.repository=\"$ECR_HOST/airgap-management\"" \
   --set-json="image.tag=\"$API_IMAGE_TAG\""

Step 3: Configure Authentication

By default, basic authentication is disabled. For production environments, enable it by setting Helm values:

  • api.basicAuth.enabled=true
  • api.basicAuth.username – your chosen username
  • api.basicAuth.password – a secure password

The username and password should be stored securely and rotated regularly according to your organization’s security policies.

Step 4: Verify Installation

Check the Pod

kubectl get pods -n clickhouse-private-api

Expected output:

NAME                                    READY   STATUS    RESTARTS   AGE
clickhouse-private-api-xxxxxxxxxx-xxxxx   1/1     Running   0          1m

Port-forward and Test

kubectl port-forward svc/clickhouse-private-api-airgap-management 8080:8080 -n clickhouse-private-api

Test the health endpoint:

curl http://localhost:8080/readiness

If authentication is enabled:

curl -u admin:YOUR_SECURE_PASSWORD_HERE http://localhost:8080/readiness

Configuration Options

The following key configuration options are available via Helm values:

Helm Value Description Default
image.repository ECR repository for the Private API image –
image.tag Image tag to deploy –
api.port Port on which the API listens 8080
api.basicAuth.enabled Enable HTTP basic authentication false
api.basicAuth.username Username for basic auth admin
api.basicAuth.password Password for basic auth changeme
serviceAccount.enabled Create a service account for the API true
serviceAccount.annotations Annotations for the service account (e.g., for IRSA) {}

For a complete list of configuration options, refer to the Helm chart’s values file.

Next Steps

Navigation