#How to Use S3 Storage with ClickHouse

This guide explains how to configure Alauda Container Platform Log Storage Management with a ClickHouse backend to keep cold log data on an S3-compatible object store.

The S3-related knobs live on the PlatformLogForward (PLF) CR, not on the plugin install form. Enable them by editing PLF fields on the storage cluster; the change takes effect after log-storage-operator reconciles.

#Before You Begin

Confirm the target storage cluster:

1. Has Alauda Container Platform Log Storage Management installed with PlatformLogForward.spec.externalStorage.type: clickhouse (see Installation).
2. Has PlatformLogForward/platform-default in Ready state.
3. Has an S3-compatible endpoint reachable from every pod in cpaas-system.

You also need the S3 credentials and, if the endpoint uses HTTPS with a private CA, the CA certificate.

#1. Create the S3 credential Secret

Store the S3 credentials in a Secret in cpaas-system on the storage cluster. The Secret name is used by PlatformLogForward.spec.clickhouse.s3ColdSecretRef in the next step, and can be any DNS-safe name.

apiVersion: v1
kind: Secret
metadata:
  name: clickhouse-s3-cold
  namespace: cpaas-system
  labels:
    cpaas.io/credentials: S3     # required so the console filters this Secret in S3 selectors
type: Opaque
stringData:
  ACCESS_KEY_ID: "<access-key-id>"
  SECRET_ACCESS_KEY: "<secret-access-key>"
  ENDPOINT: "https://<s3-endpoint>"
  REGION: "<region>"             # leave empty only if the backend does not require it
  BUCKET: "<bucket-name>"

Apply the Secret on the storage cluster:

kubectl apply -f clickhouse-s3-cold.yaml

#2. Optional — trust the S3 CA

Skip this section if the S3 endpoint uses plain http://, or if its HTTPS certificate is signed by a system-trusted CA.

Create the CA Secret with the fixed name clickhouse-ca-certificates in cpaas-system. Do not change the Secret name, its namespace, or the key name; only replace the certificate content.

apiVersion: v1
kind: Secret
metadata:
  name: clickhouse-ca-certificates
  namespace: cpaas-system
type: Opaque
stringData:
  ca-certificates.crt: |
    -----BEGIN CERTIFICATE-----
    <ca-certificate-content>
    -----END CERTIFICATE-----

Apply:

kubectl apply -f clickhouse-ca-certificates.yaml

#3. Enable tiered storage on PlatformLogForward

Edit the PLF and set the tiered-storage fields. Every field is on spec.clickhouse:

kubectl edit platformlogforward platform-default

Add or replace:

spec:
  clickhouse:
    tieredPolicy:
      enabled: true                              # enable hot / cold tiering
      coldStoragePolicy: "log_s3_cold"           # storage policy name; leave the default unless
                                                 # you configured a custom name in the CHI
    s3ColdSecretRef:
      name: clickhouse-s3-cold                   # Secret created in Step 1
      namespace: cpaas-system
    coldTTL:
      workload: 30                               # days each log type stays on cold storage
      platform: 30                               # after leaving hot storage
      system: 30
      kubernetes: 30
      event: 30
      audit: 90
    ttl:
      workload: 7                                # days each log type stays on hot (local) storage
      platform: 7                                # before it moves to cold
      system: 7
      kubernetes: 7
      event: 30
      audit: 90

Save and exit. log-storage-operator runs the schema-migrations Job to apply the new storage policy and TTL settings; watch the PLF status until it returns to Ready:

kubectl get platformlogforward platform-default -w

#4. Optional — S3 as the only ClickHouse data location

Enable S3 as the sole data location for ClickHouse (no local hot layer) by setting the ClickHouse storage policy to an S3-only policy in the ClickHouseInstallation, then pointing PlatformLogForward at the same Secret through spec.clickhouse.s3DataSecretRef.

This mode is intended for evaluation or for backups where local disk cost dominates. It sacrifices query latency because every query round-trips to S3.

spec:
  clickhouse:
    s3DataSecretRef:
      name: clickhouse-s3-cold
      namespace: cpaas-system

#Project-level cold retention

Project-level overrides let you keep certain projects' logs longer (or shorter) than the PLF defaults. See How to Set the Retention Time of Cold Data for a Project.

#Notes and limits

• Only one cold-data Secret and one data-plane Secret are supported per PLF. Point both at the same S3 bucket, or at two buckets in the same S3 endpoint.
• Do not expose the S3 access keys in plain text; keep them in Secret resources and load them from there.
• Tiered storage cannot be disabled without redeploying the ClickHouse table layout. Plan the choice before you have production data.
• Cold TTL can be adjusted after install; changes take effect on the next reconcile.
• Cold data retention behavior is different from log archival. See How to Archive Logs to Third-Party Storage for the archival path.
• In disaster recovery scenarios, do not point the primary and standby ClickHouse clusters at the same S3 bucket.

#Related topics

• Installation — the PLF creation flow.
• How to Set the Retention Time of Cold Data for a Project — per-project override.
• Log Component Selection Guide — when to pick ClickHouse over OpenSearch or Elasticsearch.