Validate BYOC infrastructure prerequisites

Disclaimer: This beta endpoint is evolving; the API contract may change.

Preflight-validates that a cloud account is ready for BYOC infrastructure creation: simulates the cloud permissions ClickHouse needs (and, for BYO-VPC, checks the provided network resources) without creating anything. Takes the same parameters as infrastructure creation, so a payload that passes validation will not be rejected by create for the same inputs.

POST

organizations

{organizationId}

byocInfrastructure

validate

Validate BYOC infrastructure prerequisites

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "123456789012",
  "availabilityZoneSuffixes": [],
  "vpcCidrRange": "10.0.0.0/16",
  "externalId": "ch-0a1b2c3d4e5f6789",
  "tenantId": "<string>",
  "servicePrincipalClientId": "<string>",
  "vpcId": "vpc-0abc1234def567890",
  "privateSubnetIds": [
    "<string>"
  ],
  "publicSubnetIds": [
    "<string>"
  ],
  "gcpPodCidrRangeNames": [
    "<string>"
  ],
  "gcpSharedVpcHostProjectId": "<string>",
  "tags": {}
}
'

import requests

url = "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate"

payload = {
    "accountId": "123456789012",
    "availabilityZoneSuffixes": [],
    "vpcCidrRange": "10.0.0.0/16",
    "externalId": "ch-0a1b2c3d4e5f6789",
    "tenantId": "<string>",
    "servicePrincipalClientId": "<string>",
    "vpcId": "vpc-0abc1234def567890",
    "privateSubnetIds": ["<string>"],
    "publicSubnetIds": ["<string>"],
    "gcpPodCidrRangeNames": ["<string>"],
    "gcpSharedVpcHostProjectId": "<string>",
    "tags": {}
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: '123456789012',
    availabilityZoneSuffixes: [],
    vpcCidrRange: '10.0.0.0/16',
    externalId: 'ch-0a1b2c3d4e5f6789',
    tenantId: '<string>',
    servicePrincipalClientId: '<string>',
    vpcId: 'vpc-0abc1234def567890',
    privateSubnetIds: ['<string>'],
    publicSubnetIds: ['<string>'],
    gcpPodCidrRangeNames: ['<string>'],
    gcpSharedVpcHostProjectId: '<string>',
    tags: {}
  })
};

fetch('https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => '123456789012',
    'availabilityZoneSuffixes' => [
        
    ],
    'vpcCidrRange' => '10.0.0.0/16',
    'externalId' => 'ch-0a1b2c3d4e5f6789',
    'tenantId' => '<string>',
    'servicePrincipalClientId' => '<string>',
    'vpcId' => 'vpc-0abc1234def567890',
    'privateSubnetIds' => [
        '<string>'
    ],
    'publicSubnetIds' => [
        '<string>'
    ],
    'gcpPodCidrRangeNames' => [
        '<string>'
    ],
    'gcpSharedVpcHostProjectId' => '<string>',
    'tags' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate"

	payload := strings.NewReader("{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "cloudProvider": "gcp",
    "allPassed": true,
    "anyPassed": true,
    "supported": true,
    "checks": [
      {
        "name": "Create EKS cluster",
        "action": "eks:CreateCluster",
        "allowed": true,
        "reason": "implicitDeny",
        "group": "<string>"
      }
    ]
  }
}

{
  "status": 400,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "status": 500,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Beta Disclaimer: This beta endpoint is evolving; the API contract may change.

Preflight-validates that a cloud account is ready for BYOC infrastructure creation: simulates the cloud permissions ClickHouse needs (and, for BYO-VPC, checks the provided network resources) without creating anything. Takes the same parameters as infrastructure creation, so a payload that passes validation will not be rejected by create for the same inputs.

Permission

The API key must have the control-plane:organization:manage permission.

Authorizations

Authorization

string

header

required

Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path Parameters

organizationId

string<uuid>

required

ID of the requested organization.

Body

application/json

regionId

enum<string>

required

Region in which the BYOC infrastructure will be located

Available options:

ap-northeast-1,

ap-northeast-2,

ap-south-1,

ap-southeast-1,

ap-southeast-2,

ca-central-1,

eu-central-1,

eu-west-1,

eu-west-2,

il-central-1,

us-east-1,

us-east-2,

us-west-2,

us-east1,

us-central1,

europe-west2,

europe-west4,

asia-southeast1,

asia-northeast1,

eastus,

eastus2,

westus3,

germanywestcentral,

centralus

accountId

string

required

Cloud account ID the BYOC infrastructure is configured for: AWS account ID, GCP project ID, or Azure subscription ID

Example:

"123456789012"

availabilityZoneSuffixes

enum<string>[]

List of availability zone suffixes

Available options:

a,

b,

c,

d,

e,

f

vpcCidrRange

string

CIDR range for the ClickHouse-managed VPC. Mutually exclusive with the BYO-VPC fields (vpcId, privateSubnetIds, publicSubnetIds)

Example:

"10.0.0.0/16"

externalId

string

AWS only: ExternalID baked into the ClickHouse management role trust policy in your account

Example:

"ch-0a1b2c3d4e5f6789"

tenantId

string

Azure only (required for Azure regions): Entra tenant ID of the subscription

servicePrincipalClientId

string

Azure only (required for Azure regions): client ID of the service principal ClickHouse uses to manage the infrastructure

vpcId

string

BYO-VPC only (AWS and GCP): ID or network name of the customer-provided VPC to deploy into. Requires privateSubnetIds

Example:

"vpc-0abc1234def567890"

privateSubnetIds

string[]

BYO-VPC only: private subnet IDs or names (1-6 entries on AWS, exactly one on GCP)

publicSubnetIds

string[]

AWS BYO-VPC only: public subnet IDs (at most 6 entries)

gcpPodCidrRangeNames

string[]

GCP BYO-VPC only: secondary IP range names on the subnet to use for pod IPs. Omitted: all secondary ranges are used

gcpSharedVpcHostProjectId

string

GCP BYO-VPC only: Shared VPC host project owning the VPC and subnet, when different from accountId

Response

Successful response

status

number

HTTP status code.

Example:

200

requestId

string<uuid>

Unique id assigned to every request. UUIDv4

result

object

Show child attributes

Validate BYOC infrastructure prerequisites

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "123456789012",
  "availabilityZoneSuffixes": [],
  "vpcCidrRange": "10.0.0.0/16",
  "externalId": "ch-0a1b2c3d4e5f6789",
  "tenantId": "<string>",
  "servicePrincipalClientId": "<string>",
  "vpcId": "vpc-0abc1234def567890",
  "privateSubnetIds": [
    "<string>"
  ],
  "publicSubnetIds": [
    "<string>"
  ],
  "gcpPodCidrRangeNames": [
    "<string>"
  ],
  "gcpSharedVpcHostProjectId": "<string>",
  "tags": {}
}
'

import requests

url = "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate"

payload = {
    "accountId": "123456789012",
    "availabilityZoneSuffixes": [],
    "vpcCidrRange": "10.0.0.0/16",
    "externalId": "ch-0a1b2c3d4e5f6789",
    "tenantId": "<string>",
    "servicePrincipalClientId": "<string>",
    "vpcId": "vpc-0abc1234def567890",
    "privateSubnetIds": ["<string>"],
    "publicSubnetIds": ["<string>"],
    "gcpPodCidrRangeNames": ["<string>"],
    "gcpSharedVpcHostProjectId": "<string>",
    "tags": {}
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: '123456789012',
    availabilityZoneSuffixes: [],
    vpcCidrRange: '10.0.0.0/16',
    externalId: 'ch-0a1b2c3d4e5f6789',
    tenantId: '<string>',
    servicePrincipalClientId: '<string>',
    vpcId: 'vpc-0abc1234def567890',
    privateSubnetIds: ['<string>'],
    publicSubnetIds: ['<string>'],
    gcpPodCidrRangeNames: ['<string>'],
    gcpSharedVpcHostProjectId: '<string>',
    tags: {}
  })
};

fetch('https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountId' => '123456789012',
    'availabilityZoneSuffixes' => [
        
    ],
    'vpcCidrRange' => '10.0.0.0/16',
    'externalId' => 'ch-0a1b2c3d4e5f6789',
    'tenantId' => '<string>',
    'servicePrincipalClientId' => '<string>',
    'vpcId' => 'vpc-0abc1234def567890',
    'privateSubnetIds' => [
        '<string>'
    ],
    'publicSubnetIds' => [
        '<string>'
    ],
    'gcpPodCidrRangeNames' => [
        '<string>'
    ],
    'gcpSharedVpcHostProjectId' => '<string>',
    'tags' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate"

	payload := strings.NewReader("{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clickhouse.cloud/v1/organizations/{organizationId}/byocInfrastructure/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountId\": \"123456789012\",\n  \"availabilityZoneSuffixes\": [],\n  \"vpcCidrRange\": \"10.0.0.0/16\",\n  \"externalId\": \"ch-0a1b2c3d4e5f6789\",\n  \"tenantId\": \"<string>\",\n  \"servicePrincipalClientId\": \"<string>\",\n  \"vpcId\": \"vpc-0abc1234def567890\",\n  \"privateSubnetIds\": [\n    \"<string>\"\n  ],\n  \"publicSubnetIds\": [\n    \"<string>\"\n  ],\n  \"gcpPodCidrRangeNames\": [\n    \"<string>\"\n  ],\n  \"gcpSharedVpcHostProjectId\": \"<string>\",\n  \"tags\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "cloudProvider": "gcp",
    "allPassed": true,
    "anyPassed": true,
    "supported": true,
    "checks": [
      {
        "name": "Create EKS cluster",
        "action": "eks:CreateCluster",
        "allowed": true,
        "reason": "implicitDeny",
        "group": "<string>"
      }
    ]
  }
}

{
  "status": 400,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "status": 500,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

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

Validate BYOC infrastructure prerequisites

Permission

Authorizations

Path Parameters

Body

Response