AWS PrivateLink

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

ClickHouse Cloud サービスへのアクセスを AWS PrivateLink のアドレス経由のみに制限するには、ClickHouse Cloud の IP Access Lists の手順に従ってください。

ClickHouse Cloud は、以下の AWS リージョンでホストされているサービス向けに クロスリージョン PrivateLink をサポートしています。

この表は、サービスをホストするリージョンのみを対象としています。コンシューマーインターフェイス VPC エンドポイントのリージョンには別の許可リストが適用されます。たとえば、mx-central-1 は、そこでホストされるサービスではクロスリージョンアクセスを有効にできませんが、許可されるコンシューマーリージョンです。

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

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

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

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

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

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

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

ClickHouse Cloud コンソールで、PrivateLink 経由で接続するサービスを開き、Settings メニューに移動します。

Service name と DNS name をメモしたら、次のステップに進みます。

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

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 コンソールを開き、VPC → Endpoints → Create endpoints の順に進みます。

Endpoint services that use NLBs and GWLBs を選択し、Obtain Endpoint "Service name" の手順で取得した Service name^console または endpointServiceId^API を Service Name フィールドに入力します。続いて、Verify service をクリックします。

"Service name couldn't be verified." という error が表示された場合は、サポート対象リージョンの一覧に新しいリージョンを追加するよう Customer Support へお問い合わせください。

次に、使用する VPC とサブネットを選択します。

必要に応じて、セキュリティグループ/タグを割り当てます。

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

次に、エンドポイントの"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 の値を控えておいてください。後続の手順で必要になります。

以下の 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 の値を控えておいてください。後続の手順で必要になります。

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

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

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

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 を使用して接続するには、エンドポイントの「Service name」を取得するで取得した privateDnsHostname^API または DNS Name^console のプライベート エンドポイントを使用する必要があります。

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

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

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 のホスト名を使用した接続はインターネット経由でルーティングされます。

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization 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