AWS PrivateLink - ClickHouse Documentation

AWS PrivateLink を使用すると、トラフィックをパブリックインターネットに公開することなく、VPC、AWS のサービス、自社運用のシステム、ClickHouse Cloud の間で安全な接続を確立できます。このドキュメントでは、AWS PrivateLink を使用して ClickHouse Cloud に接続する手順の概要を説明します。 ClickHouse Cloud サービスへのアクセスを AWS PrivateLink のアドレス経由のみに制限するには、ClickHouse Cloud の IP Access Lists の手順に従ってください。

ClickHouse Cloud は、以下のリージョンからの cross-region PrivateLink をサポートしています。

sa-east-1
il-central-1
me-south-1
mx-central-1
eu-central-2
eu-north-1
eu-south-2
eu-west-3
eu-south-1
eu-west-2
eu-west-1
eu-central-1
ca-west-1
ca-central-1
ap-northeast-1
ap-southeast-2
ap-southeast-1
ap-northeast-2
ap-northeast-3
ap-south-1
ap-southeast-4
ap-southeast-3
ap-south-2
ap-east-1
af-south-1
us-west-2
us-west-1
us-east-2
us-east-1 料金に関する注意: クロスリージョンのデータ転送については AWS から課金されます。料金はこちらを参照してください。

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 をクリックします。 PrivateLink 経由でクロスリージョン接続を確立する場合は、“Cross region endpoint” チェックボックスをオンにして、サービスのリージョンを指定します。サービスのリージョンは、ClickHouse インスタンスが稼働しているリージョンです。 “Service name couldn’t be verified.” という error が表示された場合は、サポート対象リージョンの一覧に新しいリージョンを追加するよう Customer Support へお問い合わせください。次に、使用する VPC とサブネットを選択します。必要に応じて、セキュリティグループ/タグを割り当てます。

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

VPC Endpoint を作成したら、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 エンドポイントに関連付けてください。
エンドポイントに関連付けられたセキュリティグループの inbound ルールを確認し、ClickHouse のポートへのアクセスを許可してください。
接続テストに使用している VM に関連付けられたセキュリティグループの outbound ルールを確認し、ClickHouse のポートへの接続を許可してください。

プライベートホスト名: ホストのアドレスが見つかりません

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

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

おそらく、Endpoint ID が service の許可リストに追加されていません。手順を参照してください

エンドポイントフィルターを確認する

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

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

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

ClickHouse Cloud で MySQL または PostgreSQL のテーブル関数を使用して、Amazon Web Services (AWS) の VPC でホストされているデータベースに接続しようとしているとします。この接続を安全に確立するために AWS PrivateLink を使用することはできません。PrivateLink は一方向の接続だからです。内部ネットワークまたは Amazon VPC から ClickHouse Cloud へ安全に接続することはできますが、ClickHouse Cloud から内部ネットワークへ接続することはできません。 AWS PrivateLink documentation には、次のように記載されています。

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

これを行うには、AWS のセキュリティグループを設定して、ClickHouse Cloud から内部またはプライベートなデータベースサービスへの接続を許可してください。ClickHouse Cloud の各 Region のデフォルトの egress IP アドレスと、利用可能な静的 IP アドレスを確認してください。

​重要な注意事項

​この手順の前提条件

​手順

​エンドポイントの「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

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

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

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

​プライベートホスト名: ホストのアドレスが見つかりません

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

​エンドポイントフィルターを確認する

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

重要な注意事項

この手順の前提条件

手順

エンドポイントの「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 つのリージョン内の複数の PrivateLink

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

プライベートホスト名: ホストのアドレスが見つかりません

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

エンドポイントフィルターを確認する

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