Set up docs MCP커넥터는 clicklink라는 단일 바이너리로 제공되며, 실행할 명령어는 clicklink clctl 아래에 있습니다. 이 페이지에서는 설치 및 일상적인 운영에 사용하는 명령어를 다룹니다. 각 명령어에 --help를 지정하면 전체 도움말을 확인할 수 있습니다. troubleshoot 및 preflight 하위 트리의 플래그는 CLCTL_* 환경 변수(각 플래그의 도움말 출력에 이름이 표시됨) 또는 ~/.clicklink/clctl.yaml로도 지정할 수 있습니다.
clicklink clctl init
등록 토큰, 저장된 등록 번들 또는 대역 외에서 서명된 인증서를 사용하여 커넥터를 초기 설정합니다. 한 번의 호출로 구성을 준비하고, ClickHouse 액세스를 프로비저닝하며, mTLS 클라이언트 인증서를 가져오고, 배포(Helm 차트 또는 systemd unit)한 후 상태를 확인합니다. 다시 실행해도 안전합니다. 구성과 클러스터 UUID는 유지되며, 자격 증명은 원자적으로 덮어쓰고, --force를 전달하지 않는 한 기존 클라이언트 키를 재사용합니다. 전체 흐름은 onboarding을 참조하십시오.
진입점
3개의 진입점 중 정확히 하나를 지정해야 하며, 동시에 사용할 수 없습니다.
| 플래그 | 설명 |
|---|---|
--enroll <url> |
표준 흐름입니다. 조직의 커넥터 endpoint(https://<subdomain>.<커넥터 domain>)를 받아 일회용 등록 토큰을 사용합니다. 토큰은 터미널에서는 에코 없이 프롬프트로 입력받고, 그 외 환경에서는 stdin의 첫 번째 줄에서 읽습니다. 생성된 번들을 handoff.yaml(mode 0600)에 기록한 뒤 --handoff handoff.yaml으로 계속 진행합니다. 토큰은 명령줄, 디스크 또는 logs에 기록되지 않습니다. |
--handoff <path> |
저장된 등록 번들을 사용하여 Bootstrap합니다. handoff.yaml이 있으면 재실행 및 recovery 시 이 옵션을 사용합니다. |
--signed-cert <path> |
air-gapped 흐름의 단계 2입니다. 별도 경로로 서명된 클라이언트 인증서를 설치하고 단계별 설치를 완료합니다. 필요에 따라 --chain <path>를 사용하여 CA 체인도 함께 대체할 수 있습니다. |
공통 플래그
| 플래그 | 설명 |
|---|---|
--target <shape> |
배포 형태: systemd(기본값, 현재 사용 중인 VM 부트스트랩) 또는 helm(kubeconfig가 있는 워크스테이션에서 clicklink-connector 차트 스테이징)입니다. |
--instance <spec> |
쉼표로 구분된 key=value 쌍으로 지정하는 ClickHouse 인스턴스(name, host, port, secure, database, namespace, cluster)입니다. 반복 지정할 수 있으며, 대화형 인스턴스 입력을 건너뜁니다. |
--operators <emails> |
지원 세션을 열 수 있는 운영자 이메일을 쉼표로 구분하여 지정합니다. 세션 게이트웨이를 활성화하고 입력을 건너뜁니다. |
--no-gateway |
세션 게이트웨이를 비활성화합니다(OIDC로 관리되는 세션 없음). 입력을 건너뜁니다. VM에서는 호스트의 root 사용자가 로컬 세션 파일을 통해 계속 세션을 관리할 수 있습니다. |
--force |
기존 구성 또는 오버레이를 덮어쓰고 클라이언트 키를 다시 생성합니다. 또한 아직 만료되지 않은 자체 서명 인증서를 대체하는 데 동의합니다. --force를 사용해도 클러스터 UUID는 유지됩니다. |
--skip-provision |
스테이징만 수행합니다. 역할별 ClickHouse 액세스 프로비저닝을 건너뛰며(systemd 대상에서는 유닛 활성화 및 검증도 건너뜀), clicklink clctl {scraper,troubleshoot} access provision을 별도로 실행하십시오. |
--ch-user-suffix <suffix> |
프로비저닝된 ClickHouse 사용자 이름에 추가할 선택적 접미사입니다(pcm_scraper는 pcm_scraper_<suffix>가 됨). 이를 통해 두 번째 커넥터 배포가 첫 번째 배포의 사용자와 충돌하지 않고 인스턴스를 공유할 수 있습니다. |
--ch-admin-password-stdin |
SQL 프로비저닝에 필요한 경우 stdin에서 ClickHouse 관리자 비밀번호를 읽습니다. 터미널에서 실행하는 경우에는 대신 입력을 요청합니다. |
서명 플래그(1단계에만 해당)
| 플래그 | 설명 |
|---|---|
--no-auto-sign |
1단계에서만 사용: air-gapped 또는 대역 외 서명 흐름을 위해 등록 endpoint를 통한 자동 CSR 서명을 건너뜁니다. |
--sign-endpoint <url> |
등록 서명 endpoint를 재정의합니다(기본값: 번들 endpoint에 enroll DNS 레이블을 삽입해 파생됨). HTTPS URL이어야 합니다. |
Kubernetes 전용 플래그
--target helm에서만 유효합니다.
| 플래그 | 설명 |
|---|---|
--target-namespace <ns> |
차트가 설치되고 해당 시크릿이 생성되는 네임스페이스입니다(기본값: clicklink, 터미널에서 입력 요청). |
--instance-namespace <ns> |
대상 ClickHouse 인스턴스의 네임스페이스입니다. 네이티브 Service 감지 및 인스턴스 관련 입력 요청의 초기값을 설정합니다. |
--storage-class <name> |
문제 해결 도구 상태 볼륨에 사용할 StorageClass입니다(기본값: 클러스터의 기본 StorageClass, 클러스터에 기본 StorageClass가 없으면 입력 요청 또는 필수). |
--values <path> |
준비된 values 오버레이의 경로입니다(기본값: clicklink-values.yaml). |
--chart <ref> |
배포할 차트입니다. --chart-repo에서 해석되는 이름이나, 미러링 설치용 직접 oci:// 참조, URL 또는 로컬 참조를 지정합니다(기본값: clicklink-connector). |
--chart-repo <url> |
차트 이름을 해석할 Helm 리포지토리입니다(기본값: https://releases.clicklink.clickhouse.com/charts). 직접 지정한 --chart 참조에서는 무시됩니다. |
--chart-version <ver> |
배포할 차트 버전입니다(기본값: 이 바이너리의 릴리스 버전). |
--ch-pod <ref> |
파드 내 프로비저닝 단계에 사용할 ClickHouse 파드입니다. 이름 또는 k=v 레이블 셀렉터로 지정합니다(기본값: 각 인스턴스의 Service를 지원하는 Running 파드). |
--api-private-ca |
API endpoint가 등록 번들의 CA에서 발급한 인증서를 제공하는 경우 사용합니다. 시스템 루트 대신 마운트된 CA 체인을 가리키도록 api.tls.caFile을 준비합니다. |
VM 전용 플래그
--target systemd와 함께 사용할 때만 유효합니다.
| 플래그 | 설명 |
|---|---|
--server <url> |
액세스 번들이 가리키는 Kubernetes API server URL입니다(기본값: 이 host의 kubeconfig, 없으면 입력하라는 메시지가 표시됨). |
--ca-data <base64> |
--server용 Base64 인코딩 certificate-authority-data입니다(기본값: 이 host의 kubeconfig, 없으면 입력하라는 메시지가 표시됨). |
플래그 충돌
--handoff,--enroll,--signed-cert는 상호 배타적이며, 정확히 하나를 지정해야 합니다.- Kubernetes 전용 플래그는
--target helm을 지정한 경우에만 사용할 수 있습니다.--target helm에서는--server와--ca-data가 거부됩니다(Helm 흐름은 워크스테이션의 kubeconfig를 읽습니다). --no-auto-sign과--sign-endpoint는 서로 함께 사용할 수 없으며, 둘 다(--api-private-ca포함)--signed-cert와 함께 사용하면 거부됩니다.--operators와--no-gateway는 서로 함께 사용할 수 없습니다.--skip-provision을 지정하면--ch-pod,--ch-user-suffix,--server,--ca-data,--ch-admin-password-stdin이 거부됩니다(프로비저닝이 수행되지 않음).
clicklink clctl preflight
구성, 파일, 네트워크, clickhouse, systemd, 액세스, 디스크, 민감 정보 마스킹 범주별로 그룹화된 커넥터 검사 모음을 실행합니다. 각 검사는 통과, 경고, 실패 또는 건너뜀 상태를 보고합니다. 종료 코드 0은 모든 검사가 통과했음을 의미하며(경고는 non-blocking), 종료 코드 2는 하나 이상의 검사가 실패했음을 의미합니다.
이 명령은 기본적으로 로컬에서 실행됩니다. --k8s-namespace를 지정하면 kubectl exec를 통해 커넥터 파드의 바이너리를 실행하고, 보고서는 로컬에서 렌더링합니다(systemd 검사는 파드에서 항상 건너뜁니다). 원격 채널 플래그를 사용하면 원격 VM에 설치된 바이너리를 대신 실행합니다.
| 플래그 | 설명 |
|---|---|
--config <path> |
커넥터 구성 파일의 경로입니다. 원격 대상을 사용하는 경우 해당 호스트의 경로입니다. |
--output <fmt>, -o |
출력 형식: text(기본값) 또는 json. |
--timeout <dur> |
모든 검사에 적용되는 전체 timeout입니다(기본값 30s). |
--skip-systemd |
systemd 유닛 상태 검사를 건너뜁니다(non-systemd 호스트). |
--k8s-namespace <ns> |
커넥터 차트의 네임스페이스입니다. kubectl exec를 통해 커넥터 파드 내부에서 preflight를 실행합니다. |
--k8s-component <name> |
실행할 커넥터 파드입니다: scraper(기본값) 또는 troubleshooter. |
--k8s-pod <ref> |
파드 이름 또는 k=v 레이블 셀렉터 재정의입니다(기본값: 차트의 컴포넌트 레이블). |
--k8s-container <name> |
exec할 컨테이너입니다(기본값: 컴포넌트 이름). |
--k8s-* 플래그와 원격 채널 플래그는 함께 사용할 수 없습니다. 대상 하나만 선택하십시오.
clicklink clctl troubleshoot session
지원 세션을 활성화, 비활성화하고 상태를 확인합니다. 지원 세션은 문제 해결 도구가 명령어를 수락하는 시간 제한 창입니다. 활성화된 세션이 없으면 WebSocket이 연결되어 있더라도 데몬은 모든 명령어를 거부합니다. 지원 세션을 참조하십시오.
명령어는 다음 두 가지 모드 중 하나로 작동합니다.
- 로컬 파일(기본값): 문제 해결 도구가 실행되는 호스트에서 세션 상태 파일을 읽고 씁니다(기본값:
/var/lib/clicklink/session.json). - 게이트웨이:
--gateway-url을 사용하면 워크스테이션에서 OIDC ID 토큰을 획득한 후 문제 해결 도구의 세션 게이트웨이를 호출합니다.
공통 플래그
| 플래그 | 설명 |
|---|---|
--session-file <path> |
세션 상태 파일의 경로입니다(기본값: /var/lib/clicklink/session.json). |
--config <path> |
커넥터 구성 파일입니다. troubleshooter 섹션에서 세션 파일 경로를 가져옵니다. |
--gateway-url <url> |
세션 게이트웨이의 기준 URL입니다. 설정하면 명령이 OIDC bearer 토큰을 가져와 로컬 상태 파일 대신 게이트웨이를 호출합니다. --session-file 및 --config와 함께 사용할 수 없습니다. |
--gateway-audience <aud> |
OIDC 토큰이 바인딩되는 audience 클레임입니다(기본값: 게이트웨이의 기본값과 일치하는 clicklink-clctl). 게이트웨이 audience를 재구성한 경우에만 설정하십시오. |
--gateway-issuer <url> |
게이트웨이가 검증하는 OIDC issuer입니다. 비어 있으면 Google 경로를 선택합니다. Google 이외의 IdP(Identity Provider)를 대상으로 device-code 흐름을 실행하려면 --oidc-client-id와 함께 설정하십시오. |
--oidc-client-id <id> |
device grant가 활성화된 --gateway-issuer에 등록된 device-code 흐름용 공개 OIDC 클라이언트 ID입니다. |
--token-file <path> |
미리 발급된 OIDC ID 토큰이 포함된 파일입니다. 이 토큰을 bearer로 사용하며 다른 토큰 provider를 우회합니다. |
--gateway-ca <path> |
게이트웨이 인증서를 검증하는 CA 번들입니다(BYO 인증서). 설정하지 않으면 gateway trust로 고정한 인증서를 사용합니다. 고정 정보가 없는 self-signed 게이트웨이는 연결을 거부하도록 실패합니다. |
세션 활성화
| 플래그 | 설명 |
|---|---|
--duration <dur> |
세션이 활성 상태로 유지되는 시간(기본값 4h, 최대 24h)입니다. |
--reason <text> |
세션과 함께 기록할 선택적 자유 형식 사유(최대 256자)입니다. |
--user <name> |
로컬 파일 모드에서 기록할 운영자 아이덴티티입니다. 기본값은 $SUDO_USER 또는 $USER입니다. gateway 모드에서는 토큰으로 확인된 이메일이 기준이 됩니다. |
이미 활성 상태인 세션이 있으면 활성화할 수 없습니다. 먼저 비활성화하거나 만료될 때까지 기다리십시오.
session 비활성화
session을 즉시 비활성화합니다. 활성 session이 없으면 아무 작업도 수행하지 않습니다.
세션 상태
세션의 활성 여부, 활성화한 사용자 및 만료 시점을 표시합니다. --output(-o)으로 table(기본값) 또는 json을 선택합니다.
Kubernetes에서는 포트 포워딩을 통해 게이트웨이에 연결합니다.
kubectl -n <connector-namespace> port-forward \
statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
--gateway-url http://localhost:8443 \
--duration 1h --reason "support ticket 1234"clicklink clctl troubleshoot gateway trust
VM에서 세션 게이트웨이는 self-signed TLS 인증서를 제공합니다. 이 명령어는 인증서의 SHA-256 fingerprint를 ~/.clicklink/clctl.yaml에 기록하여 session 명령어가 이를 검증할 수 있도록 합니다. 고정된 fingerprint가 더 이상 일치하지 않으면 연결이 안전하게 실패합니다. 신뢰는 다음 두 가지 방법 중 하나로 대역 외에서 설정됩니다.
- remote channel flags를 사용하면 이미 인증된 channel을 통해 VM에서 인증서를 직접 읽어 고정합니다.
- channel을 사용하지 않는 경우, 커넥터가 인증서를 생성할 때 log에 기록한 SHA-256 값을
--gateway-fingerprint로 전달합니다. 가져온 인증서는 일치하는 경우에만 고정됩니다. flag를 생략하면 아무것도 고정하지 않고 제시된 fingerprint를 출력합니다.
| Flag | 설명 |
|---|---|
--gateway-url <url> |
신뢰할 게이트웨이 기준 URL(필수)입니다. 예: https://<vm-host>:8443. |
--gateway-fingerprint <sha256> |
커넥터 log에 기록된 예상 SHA-256 fingerprint이며, 고정 전에 검증합니다. 콜론과 영문 대소문자는 무시됩니다. |
--remote-cert-file <path> |
channel을 통해 읽는 VM의 게이트웨이 인증서 경로입니다(기본값: /var/lib/clicklink/gateway/tls/server.crt). |
clicklink clctl troubleshoot gateway trust \
--gateway-url https://<vm-host>:8443 \
--gateway-fingerprint <sha256-from-connector-log>Kubernetes에서는 pinning을 사용하지 않습니다. CA에서 발급한 인증서를 사용하는 인그레스를 통해 게이트웨이를 노출하거나 포트 포워딩을 사용하십시오.
clicklink clctl troubleshoot audit tail
문제 해결사 감사 로그의 마지막 항목을 출력합니다. 각 줄에 하나의 JSON 객체가 포함되는 형식이며, 데몬이 허용하거나 차단한 명령마다 항목이 하나씩 기록됩니다. 이 명령은 로그를 읽기 전용으로 열며 수정하지 않습니다.
| 플래그 | 설명 |
|---|---|
--lines <n>, -n |
출력할 마지막 항목 수(기본값: 50). |
--path <path> |
감사 로그 파일의 경로(기본값: /var/log/clicklink/troubleshoot-audit.log). |
커넥터 런타임 image에는 셸이 없으므로 Kubernetes에서는 이 명령이 지원되는 reader입니다:
kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
/clicklink clctl troubleshoot audit tail액세스 프로비저닝
clicklink clctl scraper access provision 및 clicklink clctl troubleshoot access provision은 구성 요소별 인스턴스 액세스 번들, 즉 읽기 전용 ClickHouse 사용자와 해당 권한 부여, 그리고 구성 요소가 사용하는 Kubernetes ServiceAccount, RBAC, 토큰을 생성합니다. --force를 사용하면 이를 교체합니다. init는 설치 과정에서 이를 인라인으로 실행하며, 독립 실행형 명령어는 재실행 및 자격 증명 교체에 사용합니다.
| 플래그 | 설명 |
|---|---|
--instance <name> |
구성에 지정된 인스턴스 이름(필수)입니다. |
--server <url> |
Kubernetes API 서버 URL(필수)입니다. |
--ca-data <base64> |
생성되는 kubeconfig에 사용할 Base64 인코딩 클러스터 CA 인증서입니다. |
--config <path> |
인스턴스 정보를 읽을 커넥터 구성 파일입니다. |
--target <shape> |
systemd(기본값: 원격 채널을 통해 번들을 VM으로 전송하거나 --provider local을 사용해 로컬에서 생성) 또는 helm(차트용 Kubernetes 시크릿으로 번들 푸시)입니다. |
--target-namespace <ns> |
번들 시크릿이 생성될 네임스페이스입니다(--target helm 사용 시 필수). |
--instance-namespace <ns> |
(--target helm) 대상 ClickHouse 인스턴스의 네임스페이스입니다. |
--force |
기존 번들을 덮어씁니다. 재실행 및 자격 증명 교체에 사용합니다. |
--secret-name <name> |
번들 시크릿 이름을 재정의합니다(기본값 clicklink-connector-<component>-access-<instance>). |
--output-dir <path> |
(--target helm 또는 --provider local) 번들이 생성될 루트 디렉터리입니다. |
--ch-admin-user <name> |
권한 부여를 적용할 ClickHouse 관리자 사용자입니다(기본값 default). |
--ch-admin-password-stdin |
stdin에서 ClickHouse 관리자 비밀번호를 읽습니다. |
--ch-user-suffix <suffix> |
프로비저닝된 ClickHouse 사용자 이름에 추가할 선택적 접미사입니다. |
--ch-user-via <mode> |
ClickHouse 사용자 프로비저닝 방식입니다. sql(기본값, 생성된 권한 부여를 --ch-admin-user로 적용) 또는 cr(SQL을 사용할 수 있는 관리자가 없는 operator 관리형 인스턴스의 사용자 지정 리소스에 사용자를 기록)입니다. |
--apply-ch-grants |
(--target helm) 생성된 권한 부여를 사용자가 직접 적용하도록 남겨두는 대신 kubectl exec를 통해 파드 내에서 적용합니다. |
--ch-pod <ref>, --ch-pod-namespace <ns>, --ch-container <name> |
(--target helm에서 --apply-ch-grants 또는 --ch-user-via cr 사용 시) exec를 실행할 ClickHouse 파드와 컨테이너를 선택합니다. |
--token-duration <dur> |
ServiceAccount 토큰 수명입니다(기본값 2160h, 90일, EKS에서는 권한 부여 기간이 최대 24시간). |
--skip-restart |
프로비저닝 후 구성 요소를 재시작하지 않습니다. |
--dry-run |
실행 계획을 출력하고 종료합니다. Kubernetes, 원격 시스템 또는 ClickHouse에 쓰기 작업을 수행하지 않습니다. |
구성 요소 하나의 인스턴스 자격 증명을 교체합니다:
clicklink clctl scraper access provision --target helm \
--target-namespace <connector-namespace> \
--instance <instance-name> --instance-namespace <clickhouse-namespace> \
--server <kubernetes-api-server-url> \
--apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
--force원격 채널 플래그
preflight, gateway trust, access provision은 VM 대상에 연결하는 방식을 선택하는 공통 플래그 세트를 지원합니다.
| 플래그 | 설명 |
|---|---|
--provider <name> |
실행 채널입니다. 원격 VM에는 ssh, aws(SSM), gcp(IAP)를 사용하며, 대상 VM에서 직접 실행하는 경우에는 local을 사용합니다. 명시적으로 설정하지 않으면 공급자별 플래그를 기반으로 추론되지만, local은 자동으로 추론되지 않습니다. |
--ssh-host <host>, --ssh-user <user>, --ssh-port <port>, --ssh-identity-file <path> |
SSH 연결 정보(--provider ssh)입니다. 사용자, 포트, 키의 기본값은 SSH 구성에서 가져옵니다. |
--instance-id <id>, --region <region>, --profile <name> |
SSM용 EC2 인스턴스, 리전, 공유 구성 프로필입니다(--provider aws). |
--project <id>, --zone <zone>, --instance-name <name> |
IAP 터널링용 프로젝트, 영역, 인스턴스입니다(--provider gcp). |