> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the ClickHouse Private API

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](/docs/cloud/clickhouse-private/tutorials/deploy-aws), Step 8)
* At least one ClickHouse cluster deployed (see [tutorials/deploy-aws.md](/docs/cloud/clickhouse-private/tutorials/deploy-aws), 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.

```bash theme={null}
SOURCE_ECR_ACCOUNT_ID=<<SOURCE_ECR_ACCOUNT_ID>>
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:<<API_TAG>> docker://$TARGET_ECR_REPO/airgap-management:<<API_TAG>>
skopeo copy --all docker://$SOURCE_ECR_REPO/helm/airgap-management:<<API_HELM_TAG>> docker://$TARGET_ECR_REPO/helm/airgap-management:<<API_HELM_TAG>>
```

Replace `<<API_TAG>>` and `<<API_HELM_TAG>>` with the version tags provided by ClickHouse.

***

## Step 2: Install via Helm

The Private API is installed in a dedicated namespace.

```bash theme={null}
# 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=<<API_HELM_TAG>>

# set the API image tag
API_IMAGE_TAG=<<API_TAG>>

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

```bash theme={null}
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

```bash theme={null}
kubectl port-forward svc/clickhouse-private-api-airgap-management 8080:8080 -n clickhouse-private-api
```

Test the health endpoint:

```bash theme={null}
curl http://localhost:8080/readiness
```

If authentication is enabled:

```bash theme={null}
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

* **[Manage backups via API](/docs/cloud/clickhouse-private/how-to/manage-backups-via-api)** — Create, list, schedule, and restore backups
* **[Scale a cluster](/docs/cloud/clickhouse-private/how-to/scale-cluster)** — Vertically scale CPU and memory
* **[Reset passwords](/docs/cloud/clickhouse-private/how-to/reset-passwords)** — Reset the ClickHouse default user password