ClickHouse

ClickHouse Cloud는 조직 설정에서 만든 API 키로 연결합니다. API 키는 정확히 하나의 조직에 속하므로, 키 하나가 조직 하나를 연결하고, 각 조직은 워크스페이스에 한 번 연결됩니다. 키는 저장 전에 암호화되며 에이전트는 이를 절대 보지 못합니다.

1. ClickHouse Cloud를 열고 조직의 API Keys로 이동합니다.
2. New API key를 클릭하고 Developer(읽기 전용) 역할을 선택합니다: Polylane은 동기화 중 읽기만 합니다.
3. key ID와 key secret을 모두 복사합니다. 시크릿은 한 번만 표시됩니다.
4. 두 값을 Polylane에 붙여 넣습니다.
5. Polylane이 키를 검증하고 동기화를 시작합니다.

Polylane은 상태, 티어, 리전, 클라우드 제공자, ClickHouse 버전, 레플리카 크기, 연결 엔드포인트를 포함해 서비스를 발견합니다. 연결 호스트명은 클라우드 간 연결에 사용되므로, 환경 변수를 통해 서비스에 접근하는 애플리케이션은 맵에서 그 서비스와 연결됩니다.

모니터링은 서비스가 저하, 실패, 중지, 부분 실행 상태에 머물면 이슈를 제기합니다. 유휴 및 기동 중 상태는 유휴 스케일링되는 서비스의 일반적인 생명주기이므로 정상으로 유지됩니다. ClickHouse Cloud 컨트롤 플레인은 메트릭을 이력 없는 라이브 스냅샷으로 보고하므로, 에이전트는 필요할 때 현재 값을 읽고 서비스에는 메트릭 차트가 없습니다.

문제 해결

"Invalid API key" 오류

• 키 ID와 키 시크릿이 모두 필요합니다. 어느 하나만으로는 인증할 수 없습니다.
• ClickHouse Cloud의 API 키 설정에서 키가 삭제되거나 비활성화되지 않았는지 확인하세요.
• 만료일이 있는 키는 만료되면 동작을 멈춥니다. 새 키를 만들어 Polylane에서 교체하세요.

리소스 누락

• ClickHouse Cloud가 모든 것을 동기화하는 데 몇 분이 걸릴 수 있습니다.
• 계정 헤더에서 수동 Sync를 실행해 새로 고치세요.

요청 한도

• ClickHouse Cloud는 키당 10초에 10회의 API 요청을 허용합니다. Polylane 전용 키를 사용하면 다른 도구와 그 예산을 공유하지 않습니다.

연결 해제

Polylane에서 계정의 연결을 해제한 뒤, ClickHouse Cloud 조직 설정에서 API 키를 삭제하세요.

ClickHouse Cloud 연결에는 브라우저가 필요하지 않습니다: 콘솔이 호출하는 것과 같은 엔드포인트를 CI 작업에 담을 수 있습니다. 인증된 POST 하나가 연결을 만들고 첫 동기화를 시작합니다.

사전 요구 사항

• cloud_accounts:write와 cloud_accounts:read 스코프를 가진 Polylane API 키. API 키와 OAuth를 참고하세요.
• ws_로 시작하는 워크스페이스 ID. 같은 키로 GET /v1/workspaces에서 읽을 수 있습니다.
• Developer(읽기 전용) 역할로 만든, 조직의 API Keys에 있는 ClickHouse Cloud API 키 ID와 시크릿.

연결 만들기

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clickhouse",
    "workspaceId": "ws_0abc123",
    "keyId": "<key-id>",
    "keySecret": "<key-secret>"
  }'

API 키는 정확히 하나의 조직에 속하므로, 한 번의 호출로 조직 하나가 연결됩니다.

응답은 연결된 것을 나열하며, 첫 동기화는 이미 실행 중입니다. 나머지 흐름이 읽는 두 필드만 남기면:

{
  "success": true,
  "result": {
    "provider": "clickhouse",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

이미 연결된 계정은 accounts 대신 failures에 들어가므로, 호출을 반복해도 연결이 중복되지 않습니다.

첫 동기화 기다리기

반환된 각 계정을 id로 status가 ready에 도달할 때까지 폴링하세요(등록 시 new, 리소스가 들어오는 동안 syncing):

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

실패한 연결이 작업을 멈추게 하는 대신 실패시키도록 루프에 기한을 두세요. 계정이 ready가 되면 리소스는 토폴로지에 있고 Polylane은 첫 검사를 시작한 상태입니다.

API에서 연결 해제

연결을 삭제하면 모든 동기화와 검사가 중단되고 Polylane이 보관하던 자격 증명이 삭제됩니다. 호출에는 cloud_accounts:delete 스코프가 필요합니다:

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

그 다음 아래 연결 해제에 설명된 대로 제공자 쪽에서 ClickHouse Cloud 자격 증명을 취소하세요.