ClickHouse 연산자 구성 가이드

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # 세그먼트당 레플리카 수
  shards: 2             # 세그먼트 수
  keeperClusterRef:
    name: my-keeper     # KeeperCluster 참조
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

spec:
  replicas: 3  # 기본값: 3
  shards: 2    # 기본값: 1

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # Optional, defaults to the ClickHouseCluster namespace

spec:
  externalKeeper:
    nodes:
      - host: keeper-1.example.internal
        port: 9181
      - host: keeper-2.example.internal
        port: 9181
      - host: keeper-3.example.internal
        port: 9181

spec:
  externalKeeper:
    tls: Enabled
    nodes:
      - host: keeper-1.example.internal
        port: 9281

spec:
  settings:
    extraConfig:
      zookeeper:
        root: /clickhouse/production

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # 홀수여야 합니다: 1, 3, 5, 7, 9, 11, 13, 15
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 5Gi

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    resources:
      requests:
        storage: 100Gi

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    topologyMinDomains: 3   # number of availability zones

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

spec:
  replicas: 3
  shards: 2
  podDisruptionBudget:
    minAvailable: 2   # 중단 발생 시 각 세그먼트에서 레플리카 3개 중 최소 2개를 정상 상태로 유지

spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%

spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow

spec:
  podDisruptionBudget:
    policy: Disabled

spec:
  podDisruptionBudget:
    policy: Ignored

# operator 배포 스펙 내에서
env:
- name: ENABLE_PDB
  value: "false"

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml

spec:
  containerTemplate:
    livenessProbe:
      httpGet:
        path: /ping
        port: 9009
      initialDelaySeconds: 120
      periodSeconds: 10
      timeoutSeconds: 10
      failureThreshold: 10

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  containerTemplate:
    startupProbe:
      tcpSocket:
        port: 2181
      periodSeconds: 10
      failureThreshold: 60

spec:
  settings:
    tls:
      enabled: true
      required: true # 설정 시 비보안 포트가 비활성화됩니다
      serverCertSecret:
        name: <certificate-secret-name>

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
  externalSecret:
    name: my-clickhouse-credentials
    policy: Observe

apiVersion: v1
kind: Secret
metadata:
  name: my-clickhouse-credentials
  namespace: sample
type: Opaque
stringData:
  interserver-password: "a-strong-random-password"
  management-password: "another-strong-password"
  keeper-identity: "clickhouse:keeper-auth-password"
  cluster-secret: "cluster-internal-secret"
  named-collections-key: "0123456789abcdef0123456789abcdef"   # 32 hex chars = 16 bytes
  disk-encryption-key: "00112233445566778899aabbccddeeff"     # only when settings.encryption is set

# Plain kubectl — works out of the box
kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p'

# Same data as YAML
kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

# Pretty-printed JSON (requires jq)
kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq

spec:
  additionalPorts:
    - name: mysql
      port: 9004
    - name: postgres
      port: 9005
    - name: grpc
      port: 9100

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 1
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 2Gi

  # 1) Open the port on the Pod and the public headless Service.
  additionalPorts:
    - name: mysql
      port: 9004

  # 2) Tell ClickHouse server to actually listen on it.
  settings:
    extraConfig:
      protocols:
        mysql:
          type: mysql
          port: 9004
          description: "MySQL wire protocol"

kubectl exec sample-clickhouse-0-0-0 -- \
  clickhouse-client --port 9004 --query "SELECT 1"

spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port
spec.additionalPorts[0].name: "http" is reserved by the operator

spec:
  upgradeChannel: lts   # or "stable", or "25.8", or omitted

kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

spec:
  versionProbeTemplate:
    spec:
      ttlSecondsAfterFinished: 600   # delete completed probe Jobs 10 minutes after completion
      template:
        spec:
          nodeSelector:
            kubernetes.io/arch: amd64
          tolerations:
            - key: dedicated
              operator: Equal
              value: clickhouse
              effect: NoSchedule
          containers:
            - name: version-probe
              resources:
                requests:
                  cpu: 50m
                  memory: 64Mi

spec:
  settings:
    defaultUserPassword:
      passwordType: password   # default; see "Password types" below
      secret:                  # exactly one of secret or configMap
        name: clickhouse-password   # name of the Secret/ConfigMap
        key: password               # the key inside it, not the password value

kubectl create secret generic clickhouse-password \
  --from-literal=password='your-secure-password'

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  settings:
    defaultUserPassword:
      passwordType: password
      secret:
        name: clickhouse-password
        key: password

echo -n 'your-secure-password' | sha256sum   # use the hex digest as the value
kubectl create secret generic clickhouse-password \
  --from-literal=password='<sha256-hex-digest>'

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      secret:
        name: clickhouse-password
        key: password

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          query:
            - "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

spec:
  settings:
    enableDatabaseSync: true  # Default: true

spec:
  settings:
    logger:
      logToFile: true   # Default: true. Set false to log only to the console
      jsonLogs: false   # Default: false. Set true for structured JSON log lines
      level: information # Default: information
      size: 100M        # Default: 100M. Rotate a log file once it reaches this size
      count: 10         # Default: 10. Number of rotated files to keep

logger:
  console: true
  level: information
  log: /var/log/clickhouse-server/clickhouse-server.log
  errorlog: /var/log/clickhouse-server/clickhouse-server.err.log
  size: 100M
  count: 10

spec:
  settings:
    systemLogsTTLDays: 14

spec:
  settings:
    extraConfig:
      text_log:
        ttl: event_date + INTERVAL 90 DAY DELETE
      metric_log:
        collect_interval_milliseconds: 60000
      part_log:
        "@remove": "1"

spec:
  settings:
    extraConfig:
      background_pool_size: 20

spec:
  settings:
    extraReloadableConfig:
      named_collections:
        customers:
          url: "http://my-service.my-ns.svc:5400/Customers"
          format: "JSONEachRow"

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # 시크릿 비밀번호
  password: "..." # 비밀번호의 sha256 hex 값
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password

# in the operator Deployment spec
env:
- name: RESYNC_PERIOD
  value: "1m"

kubectl annotate clickhousecluster my-cluster clickhouse.com/pause-reconciliation=true
# ... manual surgery ...
kubectl annotate clickhousecluster my-cluster clickhouse.com/pause-reconciliation-