> ## 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.

# 운영

> ClickHouse Connector의 배포 후 운영: 업그레이드, 상태 점검, 인증서, 자격 증명 교체, 복구 및 제거

이 페이지에서는 두 설치 대상에서 ClickHouse Connector를 배포한 후 수행하는 운영 작업을 다룹니다. 설치 및 등록은 [온보딩](/docs/ko/products/bring-your-own-cloud/connector/onboarding)을 참조하십시오.

<div id="upgrades">
  ## 업그레이드
</div>

<div id="upgrades-kubernetes">
  ### Kubernetes
</div>

<Note>
  Day-2 Kubernetes 작업에는 워크스테이션의 `helm` CLI를 사용합니다. 내장 Helm 클라이언트는 `init`에만 포함되어 있으므로 첫 업그레이드 전에 `helm`을 설치하십시오.
</Note>

`init`에서 준비한 values 오버레이를 재사용하여 공개 차트 리포지토리의 릴리스를 업그레이드합니다:

```bash theme={null}
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm upgrade --install clicklink-connector clicklink-connector \
  --repo https://releases.clicklink.clickhouse.com/charts \
  --version <version> \
  -n "${CONNECTOR_NAMESPACE}" \
  -f clicklink-values.yaml
```

차트 버전은 앞의 `v`를 제외한 릴리스 태그입니다(차트 `0.9.0`은 태그 `v0.9.0`에 해당합니다). 게시된 차트는 이미 공개 컨테이너 이미지를 가리키므로 일반 설치 및 업그레이드에는 이미지 values를 지정할 필요가 없습니다. 차트 기본값을 확인하려면 `helm show values clicklink-connector --repo https://releases.clicklink.clickhouse.com/charts`를 실행하십시오.

직접 차트 참조(`oci://`, URL 또는 로컬 아카이브나 디렉터리)로 설치한 경우에는 확인할 리포지토리가 없습니다. 대신 새 버전에서 `helm upgrade clicklink-connector <same-chart-reference>`를 다시 실행하십시오. 최신 CLI로 `init`를 다시 실행해도 원하는 상태로 수렴하지만, `init`에는 항상 진입점 중 하나가 필요합니다. 번들을 보관한 경우에는 `--handoff`를 사용하고, 문서화된 정리 후에는 `--force`와 함께 새 등록 토큰을 사용하십시오. 위의 `helm upgrade`가 일반적인 방법입니다([재실행 및 복구](#re-runs-and-recovery) 참조).

<div id="upgrades-linux-vm">
  ### Linux VM
</div>

호스트에서 설치 관리자를 다시 실행하십시오. [온보딩](/docs/ko/products/bring-your-own-cloud/connector/onboarding) 시와 동일한 방식으로 최신 릴리스를 다운로드하고 검증하며, 기존 바이너리를 백업하고, 현재 사용 중인 민감 정보 마스킹 패턴과 환경 파일을 유지합니다. 그런 다음 데몬을 다시 시작하십시오:

```bash theme={null}
curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host
sudo systemctl restart clicklink-scraper clicklink-troubleshooter
```

최신 버전 대신 특정 릴리스로 업그레이드하려면 설치 명령에 `--version vX.Y.Z`를 추가하십시오.

<div id="health">
  ## 상태
</div>

각 데몬은 상태 확인 포트에서 `/livez` 엔드포인트를 제공합니다. 응답 본문의 JSON `status` 필드는 HTTP 상태 코드가 아닌 상태 신호이므로, `200`에 의존하지 말고 본문을 확인하십시오. Prometheus 메트릭은 각 구성 요소의 메트릭 포트에서 제공됩니다. 두 대상의 기본 포트는 다음과 같습니다.

| 구성 요소          | 상태 확인 포트 | 메트릭 포트 |
| -------------- | -------- | ------ |
| 전역 기본값         | 8080     | 9090   |
| Scraper        | 8082     | 9092   |
| Troubleshooter | 8084     | 9094   |

지원 세션이 활성화되면 gateway는 추가로 포트 8443에서 수신 대기합니다. VM에서는 자체 서명 TLS를 사용하며, Kubernetes에서는 `kubectl port-forward`를 통한 파드 로컬 HTTP 또는 TLS 종료 인그레스를 사용합니다.

VM에서는 언제든지 전체 검사 모음을 실행할 수 있습니다.

```bash theme={null}
sudo clicklink clctl preflight
```

구성, 파일, 포트 충돌, 네트워크 연결 가능 여부(API 엔드포인트 및 각 ClickHouse 인스턴스), ClickHouse 연결, systemd 유닛 상태, 구성 요소별 액세스, 디스크 및 민감 정보 마스킹 패턴을 확인하며, 하나라도 확인에 실패하면 `2`로 종료합니다.

<div id="certificates">
  ## 인증서
</div>

connector는 자체 클라이언트 인증서를 갱신합니다. 각 데몬은 12시간마다 리프를 확인하며, 만료까지 10일이 남으면 기존 mTLS 및 HMAC 인증 채널을 통해 30일 유효한 리프를 받아 갱신합니다. 연산자가 별도로 수행할 작업은 없습니다. Kubernetes에서는 갱신된 리프가 `clicklink-mtls` 시크릿에 다시 기록되고, VM에서는 `/etc/clicklink/tls/` 아래에 기록됩니다.

현재 만료일을 확인하려면:

```bash theme={null}
# Linux VM
sudo openssl x509 -in /etc/clicklink/tls/client.crt -noout -enddate

# Kubernetes
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get secret clicklink-mtls -n "${CONNECTOR_NAMESPACE}" -o jsonpath='{.data.tls\.crt}' \
  | base64 -d | openssl x509 -noout -enddate
```

<div id="credential-rotation">
  ## 자격 증명 교체
</div>

<div id="rotate-api-credentials">
  ### API (HMAC) 자격 증명
</div>

ClickHouse 계정 팀에 새 등록 토큰을 요청한 후, `--enroll` 및 `--force`를 지정하여 기존 `init` 명령을 다시 실행하십시오. `--force`는 기존 구성을 다시 준비하므로, 최초 설치 시 사용한 모든 대상별 플래그(`--target-namespace`, `--values` 및 모든 `--chart`, `--chart-repo`, `--chart-version` 미러 플래그)를 그대로 유지하십시오. 기본 설치에서는 다음과 같습니다:

```bash theme={null}
# Kubernetes, from your workstation
clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --force

# Linux VM, on the host
sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force
```

<Note>
  SQL 프로비저닝에 password가 필요한 무인 교체 시 stdin을 통해 두 시크릿이 순서대로 전달됩니다. 첫 번째 줄에는 token, 두 번째 줄에는 password를 입력합니다. token을 읽으면 정확히 한 줄이 소비됩니다.

  ```bash theme={null}
  printf '%s\n' "$ENROLLMENT_TOKEN" "$CH_ADMIN_PASSWORD" | \
    clicklink clctl init --enroll https://<subdomain>.<connector-domain> --force --ch-admin-password-stdin
  ```
</Note>

<div id="rotate-clickhouse-users">
  ### ClickHouse 사용자
</div>

인스턴스별로 connector의 읽기 전용 사용자를 다시 프로비저닝합니다. Kubernetes에서는 워크스테이션에서 다음을 실행하십시오. `--apply-ch-grants`는 재생성된 권한을 파드 내에서 다시 적용하여 새 자격 증명이 ClickHouse에 반영되도록 합니다(admin user에 password가 설정되어 있으면 `--ch-admin-password-stdin`을 추가하고 파이프로 전달하십시오):

```bash theme={null}
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
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
clicklink clctl troubleshoot 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
```

VM의 호스트에서:

```bash theme={null}
sudo clicklink clctl scraper access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force
sudo clicklink clctl troubleshoot access provision --provider local \
  --instance <instance-name> --server <kubernetes-api-server-url> --force
```

연산자가 관리하는 인스턴스에서는 두 형식 중 어느 쪽이든 `--ch-user-via cr` 및 파드 선택 플래그를 추가하십시오. 자세한 내용은 [CLI 참고](/docs/ko/products/bring-your-own-cloud/connector/reference/cli)를 참조하십시오.

<div id="rotate-client-certificate">
  ### 클라이언트 인증서
</div>

인증서는 자동으로 갱신됩니다([인증서](#certificates) 참조). 아직 만료되지 않은 인증서를 즉시 교체하려면 `--force` 옵션과 함께 `init`을 다시 실행하십시오.

<div id="re-runs-and-recovery">
  ## 재실행 및 복구
</div>

`init`은 재실행해도 동일한 상태로 수렴하므로, 먼저 같은 명령어를 다시 실행해 보십시오. `--force` 없이 실행하면 기존 `/etc/clicklink/config.yaml`(VM) 또는 `clicklink-values.yaml` 오버레이(Kubernetes)는 유지되고, 기존 클라이언트 키는 재사용됩니다. 자격 증명과 CA 체인은 원자적으로 덮어씌워집니다. 부분 실패 후 CLI가 출력하는 복구 명령어는 반복 실행해도 안전합니다.

`--force`는 유지된 구성 또는 오버레이를 덮어쓰고, 클라이언트 키를 다시 생성하며, 아직 만료되지 않은 클라이언트 인증서를 대체합니다. 새 클러스터 UUID를 발급하지는 않습니다. `--force`를 사용하더라도 connector의 아이덴티티는 유지됩니다.

스테이징 후 인증서 서명에 실패했거나, 아직 만료되지 않은 인증서가 이미 존재해 서명 엔드포인트가 `409`를 반환한 경우 새 token이나 두 번째 발급은 필요하지 않습니다. 디스크에 이미 있는 서명된 자료로 설치를 완료하십시오:

```bash theme={null}
sudo clicklink clctl init --signed-cert client.crt --chain ca-chain.crt
```

이는 VM용 형식입니다(root가 `/etc/clicklink`를 재작성하고 서비스를 관리합니다). Kubernetes에서는 CLI가 `--target helm`, `--target-namespace`, `--values`를 포함한 전체 형식을 출력하므로, 출력된 명령을 그대로 사용하세요.

<div id="uninstall">
  ## 제거
</div>

<div id="upgrades-linux-vm">
  ### Linux VM
</div>

`uninstall.sh`는 릴리스 tarball에 포함되어 있습니다. 호스트에 추출된 tarball이 남아 있지 않으면 [수동 다운로드 및 검증](/docs/ko/products/bring-your-own-cloud/connector/onboarding#manual-download-and-verification)에 설명된 대로 tarball을 가져와 추출한 다음, 추출된 디렉터리에서 실행하십시오:

```bash theme={null}
sudo ./uninstall.sh
```

이 명령은 서비스를 중지하고 비활성화하며 systemd 유닛과 바이너리를 제거합니다. 하지만 `/etc/clicklink`, `/var/lib/clicklink`, `/var/log/clicklink` 및 `clicklink` 사용자는 유지되므로, 나중에 다시 설치하면 기존 구성이 적용됩니다. 이 항목들까지 제거하려면:

```bash theme={null}
sudo ./uninstall.sh --purge
```

<div id="upgrades-kubernetes">
  ### Kubernetes
</div>

```bash theme={null}
CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
helm uninstall clicklink-connector -n "${CONNECTOR_NAMESPACE}"
```

`init`가 생성한 시크릿은 차트에서 관리하지 않으므로 제거해도 남아 있습니다. 구성한 모든 인스턴스의 인스턴스별 액세스 시크릿을 포함해 명시적으로 삭제하십시오:

```bash theme={null}
kubectl delete secret clicklink-hmac clicklink-mtls -n "${CONNECTOR_NAMESPACE}"
kubectl delete secret -n "${CONNECTOR_NAMESPACE}" \
  clicklink-connector-scraper-access-<instance> \
  clicklink-connector-troubleshooter-access-<instance>
kubectl delete serviceaccount -n "${CONNECTOR_NAMESPACE}" \
  pcm-scraper-<instance> pcm-troubleshooter-<instance>
# Repeat for every ClickHouse namespace that holds a provisioned instance.
for ns in <clickhouse-namespace-1> <clickhouse-namespace-2>; do
  kubectl delete serviceaccount,role,rolebinding -n "${ns}" \
    pcm-scraper pcm-troubleshooter
done
```

<div id="rotate-clickhouse-users">
  ### ClickHouse 사용자
</div>

어느 대상에서 제거하더라도 프로비저닝된 읽기 전용 사용자는 그대로 남습니다. 각 인스턴스에서 관리자로 해당 사용자를 삭제하십시오(설정한 경우 이름에 `--ch-user-suffix`를 추가하십시오):

```sql theme={null}
DROP USER IF EXISTS pcm_scraper, pcm_troubleshooter;
```