온보딩

​

사전 요구 사항

​

환경 등록

• AWS 계정 ID, 리전, EKS 클러스터 이름
• 커넥터가 Linux VM에서 실행되는지, 아니면 클러스터 내에서 실행되는지 여부
• 플랫폼 구성 요소용 노드 그룹
• 서비스의 네임스페이스 접두사(기본값 ns-)
• 클러스터가 ClickHouse image를 가져오는 방식: ClickHouse Cloud가 사용자 계정을 위해 설정한 레지스트리 액세스를 통하는지, 아니면 자체 미러를 사용하는지

​

모든 설치에 공통

• 커넥터 v0.17.0 이상. 이전 릴리스에는 관리형 모드, platform 명령어, instances create가 없습니다. 설치 프로그램은 --version을 전달하지 않는 한 최신 릴리스를 제공합니다.
• 등록 과정에서 제공된 엔드포인트와 등록 토큰.
• 443 포트 egress: https://<subdomain>.<connector-domain> 및 https://<subdomain>.enroll.<connector-domain>, 그리고 설치 시점에는 releases.clicklink.clickhouse.com과 Amazon ECR Public으로의 연결이 필요합니다. 관리형 모드에서는 플랫폼 동기화 또는 생성 작업이 ECR에서 차트를 가져올 때 실행기가 Amazon ECR 및 STS에도 접근합니다. 이 중 하나라도 연결할 수 없다면 에어갭 및 미러 설치를 참조하십시오.
• 관리형 모드에는 Amazon EKS 클러스터가 필요합니다. init은 그 외의 클러스터에서는 관리형 모드를 거부하며, 실행기 없이 설치하려면 --no-managed를 사용하도록 안내합니다. AWS에서 Terraform 사용에서는 새 클러스터용과 이미 운영 중인 클러스터용 루트 모듈을 제공하며, 그 위에 플랫폼 계층을 설치하는 init 명령어도 함께 안내합니다.
• 실행기 권한 부여를 위한 클러스터 관리자 권한. 이 권한 부여는 실행기를 사용자 접두사 하위의 네임스페이스로 제한하는 클러스터 역할, ClusterRoleBinding, ValidatingAdmissionPolicy를 생성합니다. Kubernetes에서는 init을 실행하는 데 사용하는 kubeconfig에 이 권한이 있어야 합니다. VM에서는 호스트의 kubeconfig에 이 권한이 있어야 하며, 호스트에 관리자 권한이 없으면 init이 권한을 가진 호스트에서 실행할 명령을 출력합니다.
• 아직 ClickHouse가 없어야 합니다. 관리형 설치는 서비스 없이 시작하며, 실행기가 생성한 서비스들이 스스로 등록됩니다. 관리형 모드에서 init은 사용자가 직접 운영하는 ClickHouse를 등록하지 않습니다(Kubernetes에서는 --instance와 --instance-namespace를 거부합니다). 이러한 클러스터를 관찰하려면 --no-managed로 별도의 커넥터 배포를 설치하십시오. --ch-user-suffix를 사용하면 두 배포가 커넥터의 USER 충돌 없이 하나의 instance를 공유할 수 있습니다. 해당 배포에는 연결할 수 있는 네이티브 listener가 필요합니다. 보안 포트 9440 또는 plaintext 포트 9000이며, Kubernetes에서는 자동으로 감지됩니다. 또한 provisioning을 위한 ClickHouse admin 액세스가 필요합니다. 비밀번호가 없는 default USER, --ch-admin-password-stdin 또는 프롬프트로 전달하는 password, 혹은 연산자 관리형 instance의 CR injection 중 하나를 사용합니다.
• 릴리스 아티팩트를 내려받는 모든 환경에는 cosign이 필요합니다. 설치 프로그램은 항상 SHA-256 체크섬을 검증합니다. cosign이 설치되어 있으면 릴리스 서명도 함께 검증하며, CLICKLINK_REQUIRE_COSIGN=1이 설정된 경우 cosign 없이는 진행을 거부합니다.

​

Kubernetes(Helm) 설치 시

• kubeconfig: 현재 컨텍스트가 EKS 클러스터를 가리켜야 합니다. 커넥터 네임스페이스를 생성하고 읽을 수 있어야 하며, Secret 적용, ServiceAccount·Role·RoleBinding 생성, 차트 설치, 실행기에 대한 클러스터 전역 액세스 부여가 가능해야 합니다.
• AWS 자격 증명: 워크스테이션(환경 변수 또는 프로필)에 eks:DescribeCluster 및 ec2:DescribeVpcs 권한이 있어야 합니다. init은 이 권한으로 NetworkPolicy에 필요한 클러스터 VPC의 CIDR 블록을 읽습니다. 조회에 실패하면 경고를 출력하고, 해당 목록은 직접 입력하도록 비워 둡니다.
• 엔드포인트 뒤의 CIDR: 설치 시점에 차트의 기본 거부(default-deny) NetworkPolicy를 활성화하는 데 필요합니다. 이 값이 없으면 init은 정책을 비활성화된 상태로 준비하고, 나중에 활성화하는 방법을 출력합니다.
• 기본 StorageClass 또는 --storage-class로 전달할 클래스: Troubleshooter와 실행기는 PersistentVolumeClaim에 상태를 유지합니다.
• image 풀 액세스: 클러스터 노드가 퍼블릭 ECR image 또는 직접 호스팅하는 미러에서 image를 가져올 수 있어야 합니다.

​

Linux VM(systemd) 설치

• systemd를 사용하는 모든 Linux 호스트, amd64 또는 arm64. Linux 빌드는 FIPS 모드로 실행됩니다.
• 설치 관리자와 init 실행에 필요한 루트 액세스.
• 사용 가능한 포트: health 및 메트릭용 8082, 8084, 8086, 실행기의 로컬 API용 루프백 인터페이스의 9999, 지원 세션 게이트웨이를 활성화한 경우 8443.
• provisioning과 실행기의 grant에 필요한 Kubernetes API 서버 관리자 액세스: 호스트의 kubeconfig, --server 및 --ca-data, 또는 프롬프트 입력 중 하나를 사용합니다. 액세스 번들은 양쪽 대상 모두에서 Kubernetes ServiceAccount에 연결됩니다. 관리형 모드에서는 kubeconfig의 현재 context가 관리 중인 EKS 클러스터를 가리켜야 하며, 다른 context를 통한 grant는 init이 거부합니다.

​

설치 및 등록

https://<subdomain>.<connector-domain>

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | bash

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host

clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --managed

clicklink clctl init --handoff handoff.yaml --target helm --managed \
  --egress-cidrs 203.0.113.0/24 \
  --operators '<operator-email-1>,<operator-email-2>' \
  --storage-class <storage-class>

sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --managed

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get pods -n "${CONNECTOR_NAMESPACE}"

sudo clicklink clctl preflight

rm handoff.yaml        # workstation (Kubernetes installs)
sudo rm handoff.yaml   # VM host (init ran as root, so the file is root-owned)

​

에어갭 및 미러 설치

​

수동 다운로드 및 검증

CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
# Or pin a specific release: CLICKLINK_VERSION='v0.17.0'
CLICKLINK_TARBALL="clicklink-${CLICKLINK_VERSION}-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/').tar.gz"
for suffix in '' .sha256 .sig .crt; do
  curl -fsSLO "https://releases.clicklink.clickhouse.com/${CLICKLINK_TARBALL}${suffix}"
done
if command -v sha256sum >/dev/null; then
  sha256sum -c "${CLICKLINK_TARBALL}.sha256"
else
  shasum -a 256 -c "${CLICKLINK_TARBALL}.sha256"
fi

cosign verify-blob \
  --certificate "${CLICKLINK_TARBALL}.crt" \
  --signature "${CLICKLINK_TARBALL}.sig" \
  --certificate-identity-regexp "^https://github\.com/ClickHouse/data-plane-clicklink/\.github/workflows/release\.yaml@refs/tags/v" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "${CLICKLINK_TARBALL}"

tar -xzf "${CLICKLINK_TARBALL}"
sudo install -m 0755 clicklink /usr/local/bin/clicklink

​

문제가 발생한 경우

• VM에서는 init이 실패하지 않습니다. 번들을 스테이징한 뒤, 클러스터 관리자 권한이 있는 kubeconfig에서 실행해야 할 명령어를 정확히 담은 경고를 출력합니다. 검증 프리플라이트는 실행기의 상태를 있는 그대로 보고합니다. 출력된 명령어를 실행한 다음, 동일한 init 명령을 다시 실행하여 검증하십시오:

sudo env KUBECONFIG=<path> clicklink clctl executor access apply --cluster --config /etc/clicklink/config.yaml

• Kubernetes에서는 권한 부여가 거부되면 차트가 배포되기 전에 init이 중단됩니다. 실행기가 부여된 ServiceAccount에 바인딩되므로 해당 권한 없이는 시작할 수 없기 때문입니다. 스테이징된 오버레이, 시크릿, CSR은 그대로 유지되며, init은 클러스터 관리자 권한이 있는 호스트에서 실행해야 할 두 개의 명령어를 출력합니다. 해당 명령어를 실행한 뒤 동일한 init 명령어를 다시 실행하여 계속 진행하십시오:

clicklink clctl executor access grant --cluster --sa-namespace <connector-namespace> --server <kubernetes-api-server-url> --output-dir <dir>
clicklink clctl executor access apply --cluster --output-dir <dir>