AWS PrivateLink - ClickHouse Documentation

Vous pouvez utiliser AWS PrivateLink pour établir une connectivité sécurisée entre des VPC, des services AWS, vos systèmes sur site et ClickHouse Cloud, sans exposer le trafic à l’Internet public. Ce document présente les étapes à suivre pour vous connecter à ClickHouse Cloud à l’aide d’AWS PrivateLink.

AWS PrivateLink prend uniquement en charge les connexions initiées depuis votre VPC AWS vers ClickHouse Cloud. Il ne peut pas être utilisé pour les connexions initiées depuis ClickHouse Cloud vers des services dans votre VPC, comme une base de données privée.

Pour restreindre l’accès à vos services ClickHouse Cloud exclusivement aux adresses AWS PrivateLink, suivez les instructions de ClickHouse Cloud relatives aux listes d’accès IP.

ClickHouse Cloud prend en charge le PrivateLink inter-région depuis les régions suivantes :

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 Considérations tarifaires : AWS facturera aux utilisateurs le transfert de données inter-région. Consultez les tarifs ici.

Veuillez effectuer les opérations suivantes pour activer AWS PrivateLink :

Récupérez le “Service name” de l’endpoint.
Créez l’endpoint AWS.
Ajoutez l’“Endpoint ID” à l’organisation ClickHouse Cloud.
Ajoutez l’“Endpoint ID” à la liste d’autorisation du service ClickHouse.

Vous trouverez des exemples Terraform ici.

Considérations importantes

ClickHouse essaie de regrouper vos services pour réutiliser le même endpoint de service publié au sein de la région AWS. Cependant, ce regroupement n’est pas garanti, surtout si vos services sont répartis entre plusieurs organisations ClickHouse. Si PrivateLink est déjà configuré pour d’autres services de votre organisation ClickHouse, vous pouvez souvent ignorer la plupart des étapes grâce à ce regroupement et passer directement à l’étape finale : ajouter l’« Endpoint ID » ClickHouse à la liste d’autorisation du service ClickHouse.

Prérequis pour cette procédure

Avant de commencer, vous aurez besoin de :

Votre compte AWS.
clé API ClickHouse avec les permissions nécessaires pour créer et gérer des endpoints privés côté ClickHouse.

Étapes

Suivez ces étapes pour connecter vos services ClickHouse Cloud à l’aide d’AWS PrivateLink.

Obtenir le « Service name » de l’endpoint

Option 1 : console ClickHouse Cloud

Dans la console ClickHouse Cloud, ouvrez le service auquel vous souhaitez vous connecter via PrivateLink, puis accédez au menu Settings. Relevez le Service name et le nom DNS, puis passez à l’étape suivante.

Option 2 : API

Commencez par définir les variables d’environnement suivantes avant d’exécuter des commandes :

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>

Obtenez votre INSTANCE_ID ClickHouse en filtrant par région, fournisseur et nom du service :

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)

Récupérez endpointServiceId et privateDnsHostname pour votre configuration PrivateLink :

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

Cette commande devrait renvoyer quelque chose comme :

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

Prenez note des valeurs de endpointServiceId et privateDnsHostname passez à l’étape suivante.

Créer un endpoint AWS

Cette section couvre les aspects spécifiques à ClickHouse pour configurer ClickHouse via AWS PrivateLink. Les étapes propres à AWS sont fournies à titre de référence pour vous indiquer où chercher, mais elles peuvent évoluer au fil du temps sans préavis de la part d’AWS. Adaptez la configuration AWS à votre cas d’usage.Veuillez noter que ClickHouse n’est pas responsable de la configuration des VPC endpoints AWS requis, des règles de groupe de sécurité ou des enregistrements DNS.Si vous avez précédemment activé les « noms DNS privés » lors de la configuration de PrivateLink et que vous rencontrez des difficultés pour configurer de nouveaux services via PrivateLink, veuillez contacter ClickHouse Support. Pour tout autre problème lié aux tâches de configuration AWS, contactez directement AWS Support.

Option 1 : console AWS

Ouvrez la console AWS et accédez à VPC → Endpoints → Create endpoints. Sélectionnez Endpoint services that use NLBs and GWLBs et utilisez Service name^console ou endpointServiceId^API obtenu à l’étape Obtenir le “Service name” de l’endpoint dans le champ Service Name. Cliquez sur Verify service : Si vous souhaitez établir une connexion interrégionale via PrivateLink, cochez la case “Cross region endpoint” et indiquez la région du service. Il s’agit de la région dans laquelle l’instance ClickHouse s’exécute. Si vous obtenez l’erreur “Service name couldn’t be verified.”, veuillez contacter le support client pour demander l’ajout de nouvelles régions à la liste des régions prises en charge. Ensuite, sélectionnez votre VPC et vos sous-réseaux : À titre facultatif, attribuez des groupes de sécurité/Tags :

Assurez-vous que les ports 443, 8443, 9440, 3306 sont autorisés dans le groupe de sécurité.

Après avoir créé le VPC Endpoint, notez la valeur de Endpoint ID ; vous en aurez besoin à l’étape suivante.

Option 2 : AWS CloudFormation

Ensuite, vous devez créer un VPC Endpoint à l’aide du Service name^console ou de l’endpointServiceId^API obtenu à l’étape Obtenir le “Service name” de l’endpoint . Assurez-vous d’utiliser les bons ID de sous-réseau, groupes de sécurité et ID de VPC.

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

Après avoir créé le VPC Endpoint, notez la valeur de l’Endpoint ID ; vous en aurez besoin à l’étape suivante.

Option 3 : Terraform

service_name ci-dessous correspond à Service name^console ou à endpointServiceId^API que vous avez obtenu à l’étape Obtenir le “Service name” de l’endpoint

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."
}

Après avoir créé le VPC Endpoint, notez la valeur de Endpoint ID ; vous en aurez besoin à l’étape suivante.

Définir le nom DNS privé de l’endpoint

Il existe plusieurs façons de configurer le DNS. Veuillez le configurer en fonction de votre cas d’usage.

Vous devez faire pointer le « nom DNS », obtenu à l’étape Obtain Endpoint “Service name” , vers les interfaces réseau de l’AWS Endpoint. Cela garantit que les services et composants de votre VPC/réseau pourront le résoudre correctement.

Ajouter l’« Endpoint ID » à la liste d’autorisation du service ClickHouse

Option 1 : console ClickHouse Cloud

Pour l’ajouter, accédez à la console ClickHouse Cloud, ouvrez le service que vous souhaitez connecter via PrivateLink, puis accédez à Settings. Cliquez sur Set up private endpoint pour ouvrir les paramètres des endpoints privés. Saisissez l’Endpoint ID obtenu à l’étape Create AWS Endpoint. Cliquez sur « Create endpoint ».

Si vous souhaitez autoriser l’accès depuis une connexion PrivateLink existante, utilisez le menu déroulant des endpoints existants.

Pour le supprimer, accédez à la console ClickHouse Cloud, recherchez le service, puis accédez à ses Settings. Trouvez l’endpoint que vous souhaitez supprimer. Supprimez-le de la liste des endpoints.

Option 2 : API

Vous devez ajouter un Endpoint ID à la liste d’autorisation de chaque instance devant être accessible via PrivateLink. Définissez la variable d’environnement ENDPOINT_ID à l’aide des données de l’étape Créer un AWS Endpoint. Définissez les variables d’environnement suivantes avant d’exécuter la moindre commande :

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>

Pour ajouter un ID d’endpoint à une liste d’autorisation :

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

Pour supprimer un Endpoint ID d’une liste d’autorisation :

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

Accéder à une instance à l’aide de PrivateLink

Chaque service pour lequel Private Link est activé dispose d’un endpoint public et d’un endpoint privé. Pour vous connecter via Private Link, vous devez utiliser un endpoint privé : privateDnsHostname^API ou Nom DNS^console, obtenu à partir de Obtenir le « Service name » de l’endpoint.

Récupération du nom d’hôte DNS privé

Option 1 : ClickHouse Cloud console

Dans la console ClickHouse Cloud, accédez à Settings. Cliquez sur le bouton Set up private endpoint. Dans le flyout qui s’ouvre, copiez le nom DNS.

Option 2 : API

Définissez les variables d’environnement suivantes avant d’exécuter toute commande :

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

Vous pouvez récupérer INSTANCE_ID à l’étape.

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

Cela devrait afficher quelque chose comme :

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

Dans cet exemple, la connexion via le nom d’hôte correspondant à la valeur de privateDnsHostname sera acheminée vers PrivateLink, tandis que la connexion via le nom d’hôte endpointServiceId passera par Internet.

Dépannage

Plusieurs PrivateLinks dans une même région

Dans la plupart des cas, vous n’avez besoin de créer qu’un seul service de point de terminaison par VPC. Cet endpoint peut acheminer les requêtes du VPC vers plusieurs services ClickHouse Cloud. Veuillez vous référer à cette section

Délai d’attente dépassé lors de la connexion au endpoint privé

Veuillez associer le groupe de sécurité au VPC Endpoint.
Veuillez vérifier les règles inbound du groupe de sécurité associé à l’Endpoint et autoriser les ports ClickHouse.
Veuillez vérifier les règles outbound du groupe de sécurité associé à la VM utilisée pour le test de connectivité et autoriser les connexions vers les ports ClickHouse.

Nom d’hôte privé : adresse de l’hôte introuvable

Veuillez vérifier votre configuration DNS

Connexion réinitialisée par le pair

Il est très probable que l’Endpoint ID n’ait pas été ajouté à la liste d’autorisation du service ; veuillez consulter cette étape

Vérifier les filtres de l’endpoint

Définissez les variables d’environnement suivantes avant d’exécuter une commande :

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

Vous pouvez récupérer INSTANCE_ID dans l’étape.

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

Connexion à une base de données distante

Selon la documentation AWS PrivateLink :

Utilisez AWS PrivateLink dans une configuration client/serveur lorsque vous souhaitez autoriser un ou plusieurs VPC consommateurs à accéder, de manière unidirectionnelle, à un service spécifique ou à un ensemble d’instances dans le VPC du fournisseur de services. Seuls les clients du VPC consommateur peuvent initier une connexion au service dans le VPC du fournisseur de services.

Pour connecter les fonctions de table MySQL ou PostgreSQL de ClickHouse Cloud à une base de données hébergée dans votre VPC AWS, configurez vos groupes de sécurité AWS afin d’autoriser les connexions depuis ClickHouse Cloud. Consultez les adresses IP de sortie par défaut des régions ClickHouse Cloud, ainsi que les adresses IP statiques disponibles.

​Considérations importantes

​Prérequis pour cette procédure

​Étapes

​Obtenir le « Service name » de l’endpoint

​Option 1 : console ClickHouse Cloud

​Option 2 : API

​Créer un endpoint AWS

​Option 1 : console AWS

​Option 2 : AWS CloudFormation

​Option 3 : Terraform

​Définir le nom DNS privé de l’endpoint

​Ajouter l’« Endpoint ID » à la liste d’autorisation du service ClickHouse

​Option 1 : console ClickHouse Cloud

​Option 2 : API

​Accéder à une instance à l’aide de PrivateLink

​Récupération du nom d’hôte DNS privé

Option 1 : ClickHouse Cloud console

Option 2 : API

​Dépannage

​Plusieurs PrivateLinks dans une même région

​Délai d’attente dépassé lors de la connexion au endpoint privé

​Nom d’hôte privé : adresse de l’hôte introuvable

​Connexion réinitialisée par le pair

​Vérifier les filtres de l’endpoint

​Connexion à une base de données distante

Considérations importantes

Prérequis pour cette procédure

Étapes

Obtenir le « Service name » de l’endpoint

Option 1 : console ClickHouse Cloud

Option 2 : API

Créer un endpoint AWS

Option 1 : console AWS

Option 2 : AWS CloudFormation

Option 3 : Terraform

Définir le nom DNS privé de l’endpoint

Ajouter l’« Endpoint ID » à la liste d’autorisation du service ClickHouse

Option 1 : console ClickHouse Cloud

Option 2 : API

Accéder à une instance à l’aide de PrivateLink

Récupération du nom d’hôte DNS privé

Dépannage

Plusieurs PrivateLinks dans une même région

Délai d’attente dépassé lors de la connexion au endpoint privé

Nom d’hôte privé : adresse de l’hôte introuvable

Connexion réinitialisée par le pair

Vérifier les filtres de l’endpoint

Connexion à une base de données distante