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

# ACME による TLS の自動プロビジョニングの設定

> このガイドでは、接続の検証に OpenSSL 証明書を使用するよう ClickHouse を設定するための、シンプルで最小限の設定を紹介します。

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            実験的な機能です。 <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">詳細を見る。</a></u>
        </div>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud では利用できません
        </div>;
};

<ExperimentalBadge />

<CloudNotSupportedBadge />

<Note>
  このページは[ClickHouse Cloud](https://clickhouse.com/cloud)には該当しません。ここで説明している手順は、ClickHouse Cloud サービスでは自動化されています。
</Note>

このガイドでは、ClickHouse で [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) ([RFC8555](https://www.rfc-editor.org/rfc/rfc8555) で定義) プロトコルを使用するよう設定する方法を説明します。
ACME をサポートすることで、ClickHouse は [Let's Encrypt](https://letsencrypt.org/) や [ZeroSSL](https://zerossl.com/) などのプロバイダーから証明書を自動的に取得し、更新できます。
TLS 暗号化は、クライアントと ClickHouse サーバー間で送受信されるデータを保護し、機密性の高いクエリや結果の盗聴を防ぎます。

<div id="overview">
  ## 概要
</div>

ACME プロトコルは、[Let's Encrypt](https://letsencrypt.org/) や [ZeroSSL](https://zerossl.com/) などのサービスによる証明書の自動更新プロセスを定義しています。簡単に言うと、証明書をリクエストする ClickHouse は、証明書を取得するために、あらかじめ定義されたチャレンジタイプを使ってドメインの所有権を確認する必要があります。

ACME を有効にするには、HTTP ポートと HTTPS ポートを `acme` ブロックとあわせて設定します:

```xml theme={null}
<http_port>80</http_port>
<https_port>443</https_port>

<acme>
    <email>valid_email@example.com</email>
    <terms_of_service_agreed>true</terms_of_service_agreed>
    <domains>
        <domain>example.com</domain>
    </domains>
</acme>
```

HTTPポートは、ドメイン検証中に ACME の `HTTP-01` チャレンジ (チャレンジタイプの詳細は[こちら](https://letsencrypt.org/docs/challenge-types/)) のリクエストを処理します。検証が完了して証明書が発行されると、HTTPS ポートは取得した証明書を使って暗号化されたトラフィックを処理します。

HTTP ポートは、サーバー自体で 80 である必要はありません。`nftables` などのツールを使って別のポートに再マップできます。`HTTP-01` チャレンジで使用できるポートについては、ACME プロバイダーのドキュメントを確認してください。

`acme` ブロックでは、アカウント作成用の `email` を設定し、ACME サービスの利用規約に同意します。
その後に必要なのは、ドメインのリストだけです。

<div id="current-limitations">
  ### 現在の制限事項
</div>

* サポートされているチャレンジタイプは `HTTP-01` のみです。
* サポートされている秘密鍵は `RSA 2048` のみです。
* レート制限には対応していません。

<div id="configuration-parameters">
  ## 設定パラメータ
</div>

`acme` セクションで使用できる設定オプション:

| パラメータ                                | デフォルト値                                           | 説明                                                                     |
| ------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------- |
| `zookeeper_path`                     | `/clickhouse/acme`                               | ACME アカウントデータ、証明書、ClickHouse ノード間の協調状態を保存するための ZooKeeper パス。           |
| `directory_url`                      | `https://acme-v02.api.letsencrypt.org/directory` | 証明書の発行に使用する ACME ディレクトリエンドポイント。デフォルトでは Let’s Encrypt の本番サーバーが使われます。    |
| `email`                              |                                                  | ACME アカウントの作成と管理に使用するメールアドレス。ACME プロバイダーが有効期限の通知や重要な更新の連絡に使用する場合があります。 |
| `terms_of_service_agreed`            | `false`                                          | ACME プロバイダーの利用規約に同意しているかどうかを示します。ACME を有効にするには `true` に設定する必要があります。    |
| `domains`                            |                                                  | TLS 証明書を発行する対象のドメイン名の一覧。各ドメインは `<domain>` エントリとして指定します。                |
| `refresh_certificates_before`        | `2592000` (1 か月、秒単位)                             | 証明書の有効期限が切れるどれくらい前に ClickHouse が証明書の更新を試みるかを示す時間。                      |
| `refresh_certificates_task_interval` | `3600` (1 時間、秒単位)                                | ClickHouse が証明書の更新が必要かどうかを確認する間隔。                                      |

設定では、デフォルトで Let's Encrypt の本番ディレクトリが使用されます。設定ミスによってリクエストのクォータに達するのを避けるため、まずは [staging directory](https://letsencrypt.org/docs/staging-environment/) で証明書の発行プロセスをテストすることを推奨します。

<div id="administration">
  # 管理
</div>

<div id="initial-deployment">
  ## 初期デプロイ
</div>

複数のレプリカを持つクラスターで ACME クライアントを有効にする場合、証明書の初回発行時には特に注意が必要です。

ACME を有効にして起動した最初のレプリカは、ただちに ACME オーダーの作成を試み、HTTP-01 チャレンジの検証を行います。その時点でトラフィックを受けているレプリカが一部に限られていると、ほかのレプリカは検証リクエストに応答できないため、チャレンジは失敗する可能性が高くなります。

可能であれば、トラフィックを一時的に 1 つのレプリカのみにルーティングし (たとえば DNS レコードを調整して) 、そのレプリカで初回の証明書発行を完了させることをおすすめします。証明書が正常に発行されて Keeper に保存されたら、残りのレプリカでも ACME を有効にできます。これらのレプリカは既存の証明書を自動的に再利用し、以後の更新にも参加します。

トラフィックを 1 つのレプリカにルーティングできない場合は、代替手段として、ACME クライアントを有効にする前に既存の証明書と秘密鍵を Keeper に手動でアップロードできます。これにより初回の検証ステップを回避でき、すべてのレプリカを、有効な証明書がすでに存在する状態で起動できます。

初回の証明書が発行またはインポートされたあとは、すべてのレプリカですでに ACME クライアントが動作しており、Keeper を介して状態を共有するため、証明書の更新に特別な対応は必要ありません。

<div id="keeper-data-structure">
  ## Keeper のデータ構造
</div>

```text theme={null}
/clickhouse/acme
└── <acme-directory-host>
    ├── account_private_key          # ACME アカウント秘密鍵 (PEM)
    ├── challenges                   # アクティブな HTTP-01 チャレンジの状態
    └── domains
        └── <domain-name>
            ├── certificate          # 発行済み TLS 証明書 (PEM)
            └── private_key          # ドメイン秘密鍵 (PEM)
```

<div id="migrating-from-other-acme-clients">
  ## 他の ACME クライアントからの移行
</div>

移行を容易にするため、現在使用中の TLS 証明書と秘密鍵を Keeper に移行できます。
現時点でサーバーがサポートしているのは、`RSA 2048` の鍵のみです。

`certbot` から移行し、`/etc/letsencrypt/live` ディレクトリを使用している場合は、次の一連のコマンドを使用できます。

```bash theme={null}
DOMAIN=example.com
CERT_DIR=/etc/letsencrypt/live/$DOMAIN
ZK_BASE=/clickhouse/acme/acme-v02.api.letsencrypt.org/domains/$DOMAIN

clickhouse keeper-client -q "create '/clickhouse' ''"
clickhouse keeper-client -q "create '/clickhouse/acme' ''"
clickhouse keeper-client -q "create '/clickhouse/acme/acme-v02.api.letsencrypt.org' ''"
clickhouse keeper-client -q "create '/clickhouse/acme/acme-v02.api.letsencrypt.org/domains' ''"
clickhouse keeper-client -q "create '$ZK_BASE' ''"

clickhouse keeper-client -q "create '$ZK_BASE/certificate' \"$(cat $CERT_DIR/fullchain.pem)\""
clickhouse keeper-client -q "set '$ZK_BASE/certificate' \"$(cat $CERT_DIR/fullchain.pem)\""

clickhouse keeper-client -q "create '$ZK_BASE/private_key' \"$(cat $CERT_DIR/privkey.pem)\""
clickhouse keeper-client -q "set '$ZK_BASE/private_key' \"$(cat $CERT_DIR/privkey.pem)\""
```