AWS PrivateLink

AWS PrivateLink を使用すると、トラフィックをパブリックインターネットに公開することなく、VPC、AWS のサービス、自社運用のシステム、ClickHouse Cloud の間で安全な接続を確立できます。このドキュメントでは、AWS PrivateLink を使用して ClickHouse Cloud に接続する手順の概要を説明します。

AWS PrivateLink がサポートするのは、お使いの AWS VPC から ClickHouse Cloud への接続のみです。プライベートデータベースなど、ClickHouse Cloud からお使いの VPC 内のサービスへの接続には使用できません。

ClickHouse Cloud サービスへのアクセスを AWS PrivateLink のアドレス経由のみに制限するには、ClickHouse Cloud の IP Access Lists の手順に従ってください。 ClickHouse Cloud は、以下の AWS リージョンでホストされているサービス向けにクロスリージョン PrivateLink をサポートしています。この表は、サービスをホストするリージョンのみを対象としています。コンシューマーインターフェイス VPC エンドポイントのリージョンには別の許可リストが適用されます。たとえば、mx-central-1 は、そこでホストされるサービスではクロスリージョンアクセスを有効にできませんが、許可されるコンシューマーリージョンです。

リージョンコード	リージョン名
`af-south-1`	アフリカ (ケープタウン)
`ap-east-1`	アジアパシフィック (香港)
`ap-northeast-1`	アジアパシフィック (東京)
`ap-northeast-2`	アジアパシフィック (ソウル)
`ap-south-1`	アジアパシフィック (ムンバイ)
`ap-southeast-1`	アジアパシフィック (シンガポール)
`ap-southeast-2`	アジアパシフィック (シドニー)
`ap-southeast-3`	アジアパシフィック (ジャカルタ)
`ap-southeast-5`	アジアパシフィック (マレーシア)
`ca-central-1`	カナダ (中部)
`eu-central-1`	欧州 (フランクフルト)
`eu-north-1`	欧州 (ストックホルム)
`eu-west-1`	欧州 (アイルランド)
`eu-west-2`	欧州 (ロンドン)
`il-central-1`	イスラエル (テルアビブ)
`me-central-1`	中東 (UAE)
`sa-east-1`	南アメリカ (サンパウロ)
`us-east-1`	米国東部 (N. Virginia)
`us-east-2`	米国東部 (オハイオ)
`us-west-2`	米国西部 (オレゴン)

ap-east-2 または mx-central-1 でホストされている ClickHouse Cloud サービスでは、クロスリージョン PrivateLink はサポートされていません。いずれかのリージョンのサービスに PrivateLink を使用して接続するには、サービスと同じ AWS リージョンにインターフェイス VPC エンドポイントを作成してください。

クロスリージョンのデータ転送については AWS から課金されます。詳細は AWS PrivateLink pricing を参照してください。

AWS PrivateLink を有効にするには、以下を完了してください:

Endpoint “Service name” を取得します。
AWS エンドポイントを作成します。
“Endpoint ID” を ClickHouse Cloud 組織に追加します。
“Endpoint ID” を ClickHouseサービスの許可リストに追加します。

Terraform の例はこちらをご覧ください。

重要な注意事項

ClickHouse は、AWS リージョン内で同じ公開済みのサービスエンドポイントを再利用できるよう、サービスをグループ化しようとします。ただし、このグループ化が保証されるわけではなく、特に複数の ClickHouse 組織にまたがってサービスを分散している場合はそうとは限りません。 ClickHouse 組織内の他のサービス向けにすでに PrivateLink を構成している場合は、このグループ化により多くの手順を省略できることがあり、最後の手順である「ClickHouse の “Endpoint ID” を ClickHouse service の許可リストに追加する」に直接進めることがよくあります。

この手順の前提条件

始める前に、以下が必要です。

AWS アカウント。
ClickHouse 側でプライベートエンドポイントを作成および管理するために必要な権限を持つ ClickHouse API key。

手順

AWS PrivateLink 経由で ClickHouse Cloud サービスに接続するには、以下の手順に従ってください。

エンドポイントの「Service name」を確認する

オプション 1: ClickHouse Cloud コンソール

ClickHouse Cloud コンソールで、PrivateLink 経由で接続するサービスを開き、Settings メニューに移動します。 Service name と DNS name をメモしたら、次のステップに進みます。

オプション 2: API

まず、コマンドを実行する前に、次の環境変数を設定します。

REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>

リージョン、プロバイダー、サービス名で絞り込んで、ClickHouse の INSTANCE_ID を取得します:

INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)

PrivateLink 設定用の endpointServiceId と privateDnsHostname を取得します。

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

このコマンドを実行すると、次のような結果が返されるはずです:

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

endpointServiceId と privateDnsHostname をメモし、次のステップに進みます。

AWSエンドポイントを作成

このセクションでは、AWS PrivateLink 経由で ClickHouse を設定する際の ClickHouse 固有の注意点を説明します。AWS 固有の手順は、確認すべき箇所の参考情報として記載していますが、AWS クラウドプロバイダーからの事前通知なく変更される場合があります。AWS の設定については、ご利用のユースケースに応じてご判断ください。必要な AWS VPC エンドポイント、セキュリティグループルール、DNS レコードの設定は ClickHouse の責任範囲ではありませんので、ご注意ください。以前に PrivateLink の設定時に「private DNS names」を有効にしており、PrivateLink 経由で新しいサービスの設定に問題が発生している場合は、ClickHouse Support にお問い合わせください。AWS の設定作業に関するその他の問題については、AWS Support に直接お問い合わせください。

オプション 1: AWS コンソール

AWS コンソールを開き、VPC → Endpoints → Create endpoints の順に進みます。 Endpoint services that use NLBs and GWLBs を選択し、Obtain Endpoint “Service name” の手順で取得した Service name^console または endpointServiceId^API を Service Name フィールドに入力します。続いて、Verify service をクリックします。

クロスリージョン接続の場合は、Cross region endpoint チェックボックスをオンにして、ClickHouse service が稼働しているリージョンを指定します。

“Service name couldn’t be verified.” という error が表示された場合は、サポート対象リージョンの一覧に新しいリージョンを追加するよう Customer Support へお問い合わせください。次に、使用する VPC とサブネットを選択します。必要に応じて、セキュリティグループ/タグを割り当てます。

セキュリティグループでポート 443、8443、9440、3306 が許可されていることを確認してください。

VPC エンドポイントを作成したら、Endpoint ID の値を控えておいてください。後続の手順で必要になります。

オプション 2: AWS CloudFormation

次に、エンドポイントの”Service name”を取得する手順で取得したService name^consoleまたはendpointServiceId^APIを使用して、VPC エンドポイントを作成します。サブネット ID、セキュリティグループ、VPC ID には正しい値を使用していることを確認してください。

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3

VPC Endpoint を作成したら、Endpoint ID の値を控えておいてください。後続の手順で必要になります。

オプション 3: Terraform

以下の service_name は、エンドポイントの”Service name” を取得する手順で取得した Service name^{コンソール} または endpointServiceId^API です

resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}

VPC Endpoint を作成したら、Endpoint ID の値を控えておいてください。後続の手順で必要になります。

エンドポイントのプライベート DNS 名を設定する

DNS の設定方法はいくつかあります。ご利用のユースケースに応じて設定してください。

Endpoint の「Service name」を取得するステップで取得した “DNS name” が、AWS エンドポイントのネットワークインターフェイスを指すように設定する必要があります。これにより、VPC/ネットワーク内のサービスやコンポーネントがその名前を適切に解決できるようになります。

“Endpoint ID” を ClickHouseサービスの許可リストに追加する

オプション 1: ClickHouse Cloud コンソール

追加するには、ClickHouse Cloud コンソールに移動し、PrivateLink 経由で接続するサービスを開いて Settings に進みます。Set up private endpoint をクリックして、プライベートエンドポイントの設定を開きます。Create AWS Endpoint の手順で取得した Endpoint ID を入力し、“Create endpoint” をクリックします。

既存の PrivateLink 接続からのアクセスを許可する場合は、既存のエンドポイントのドロップダウンメニューを使用します。

削除するには、ClickHouse Cloud コンソールに移動してサービスを見つけ、そのサービスの Settings に進み、削除したいエンドポイントを見つけます。エンドポイントの一覧から削除します。

オプション 2: API

PrivateLink 経由で利用可能にする各インスタンスについて、許可リストに Endpoint ID を追加する必要があります。 Create AWS エンドポイントの手順で取得した情報を使って、ENDPOINT_ID 環境変数を設定します。コマンドを実行する前に、次の環境変数を設定します。

REGION=<AWSフォーマットのリージョンコード（例: us-west-2）>
PROVIDER=aws
KEY_ID=<ClickHouseのキーID>
KEY_SECRET=<ClickHouseのキーシークレット>
ORG_ID=<ClickHouseの組織ID>
SERVICE_NAME=<ClickHouseのサービス名>

Endpoint IDを許可リストに追加するには:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

許可リストから Endpoint ID を削除するには、

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

PrivateLink を使用したインスタンスへのアクセス

プライベートリンクが有効な各サービスには、パブリックエンドポイントとプライベートエンドポイントがあります。PrivateLink を使用して接続するには、エンドポイントの「Service name」を取得するで取得した privateDnsHostname^API または DNS Name^console のプライベートエンドポイントを使用する必要があります。

プライベート DNS ホスト名の取得

オプション 1: ClickHouse Cloud コンソール

ClickHouse Cloud コンソールで Settings に移動します。Set up private endpoint ボタンをクリックします。表示された flyout で、DNS Name をコピーします。

オプション 2: API

コマンドを実行する前に、以下の環境変数を設定してください。

KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>

INSTANCE_ID は手順で取得できます。

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

次のような出力になるはずです:

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

この例では、privateDnsHostname の値であるホスト名を使用した接続は PrivateLink にルーティングされますが、endpointServiceId のホスト名を使用した接続はインターネット経由でルーティングされます。

トラブルシューティング

1 つのリージョン内の複数の PrivateLink

ほとんどの場合、VPC ごとに作成するエンドポイントサービスは 1 つだけで十分です。このエンドポイントを介して、VPC から複数の ClickHouse Cloud サービスにリクエストをルーティングできます。こちらを参照してください。

プライベートエンドポイントへの接続がタイムアウトする

VPC Endpoint にセキュリティグループを関連付けてください。
Endpoint に関連付けられたセキュリティグループの inbound ルールを確認し、ClickHouse のポートを許可してください。
接続テストに使用する VM に関連付けられたセキュリティグループの outbound ルールを確認し、ClickHouse のポートへの接続を許可してください。

プライベートホスト名: ホストのアドレスが見つからない

DNS 設定を確認してください。

ピアによって接続がリセットされた

Endpoint ID がサービスの許可リストに追加されていない可能性が高いため、手順を参照してください。

エンドポイントフィルターの確認

コマンドを実行する前に、次の環境変数を設定してください。

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>

INSTANCE_ID は手順から取得できます。

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X GET -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | \
jq .result.privateEndpointIds

リモートデータベースへの接続

AWS PrivateLink のドキュメントによると、次のとおりです。

AWS PrivateLink は、クライアント/サーバー構成において、1 つ以上の consumer VPC から、service provider VPC 内の特定のサービスまたはインスタンス群への単方向アクセスを許可したい場合に使用します。service provider VPC 内のサービスへの接続を開始できるのは、consumer VPC 内のクライアントのみです。

ClickHouse Cloud で MySQL または PostgreSQL のテーブル関数を、AWS VPC でホストされているデータベースに接続するには、AWS のセキュリティグループを設定し、ClickHouse Cloud からの接続を許可してください。ClickHouse Cloud の各リージョンにおけるデフォルトの egress IP アドレスと、利用可能な静的 IP アドレスを確認してください。

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

重要な注意事項

この手順の前提条件

手順

エンドポイントの「Service name」を確認する

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

AWSエンドポイントを作成

オプション 1: AWS コンソール

オプション 2: AWS CloudFormation

オプション 3: Terraform

エンドポイントのプライベート DNS 名を設定する

“Endpoint ID” を ClickHouseサービスの許可リストに追加する

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

PrivateLink を使用したインスタンスへのアクセス

プライベート DNS ホスト名の取得

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

トラブルシューティング

​重要な注意事項

​この手順の前提条件

​手順

​エンドポイントの「Service name」を確認する

​オプション 1: ClickHouse Cloud コンソール

​オプション 2: API

​AWSエンドポイントを作成

​オプション 1: AWS コンソール

​オプション 2: AWS CloudFormation

​オプション 3: Terraform

​エンドポイントのプライベート DNS 名を設定する

​“Endpoint ID” を ClickHouseサービスの許可リストに追加する

​オプション 1: ClickHouse Cloud コンソール

​オプション 2: API

​PrivateLink を使用したインスタンスへのアクセス

​プライベート DNS ホスト名の取得

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

​トラブルシューティング

重要な注意事項

この手順の前提条件

手順

エンドポイントの「Service name」を確認する

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

AWSエンドポイントを作成

オプション 1: AWS コンソール

オプション 2: AWS CloudFormation

オプション 3: Terraform

エンドポイントのプライベート DNS 名を設定する

“Endpoint ID” を ClickHouseサービスの許可リストに追加する

オプション 1: ClickHouse Cloud コンソール

オプション 2: API

PrivateLink を使用したインスタンスへのアクセス

プライベート DNS ホスト名の取得

トラブルシューティング