Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Validate BYOC infrastructure prerequisites

POST/v1/organizations/{organizationId}/byocInfrastructure/validate
API playground

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

Path parameters

  • organizationIdstringrequired

    ID of the requested organization.

    format: uuid

Request bodyJSON

  • regionIdap-northeast-1orap-northeast-2orap-south-1orap-southeast-1orap-southeast-2orca-central-1+18 morerequired

    Region in which the BYOC infrastructure will be located

  • accountIdstringrequired

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

    Example: "123456789012"
  • availabilityZoneSuffixesoptionalarray ofaorborcordoreorf

    List of availability zone suffixes

  • vpcCidrRangeoptionalstring

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

    Example: "10.0.0.0/16"
  • externalIdoptionalstring

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

    Example: "ch-0a1b2c3d4e5f6789"
  • tenantIdoptionalstring

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

  • servicePrincipalClientIdoptionalstring

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

  • vpcIdoptionalstring

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

    Example: "vpc-0abc1234def567890"
  • privateSubnetIdsoptionalarray ofstring

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

  • publicSubnetIdsoptionalarray ofstring

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

  • gcpPodCidrRangeNamesoptionalarray ofstring

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

  • gcpSharedVpcHostProjectIdoptionalstring

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

  • tagsoptionalmap ofstring

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    5 properties
    • cloudProvideroptionalgcporawsorazure

      Cloud provider of the requested region

    • allPassedoptionalboolean

      True when every check passed

    • anyPassedoptionalboolean

      True when at least one check passed

    • supportedoptionalboolean

      Whether preflight validation is implemented for the requested cloud and configuration. When false, an empty check list means nothing was verified rather than everything passed

    • checksoptionalarray ofobject

      Individual permission checks with their outcomes

      5 properties
      • nameoptionalstring

        Human readable name of the check

        Example: "Create EKS cluster"
      • actionoptionalstring

        Cloud permission or action the check simulated

        Example: "eks:CreateCluster"
      • allowedoptionalboolean

        Whether the account allowed the simulated action

      • reasonoptionalstring

        Cloud-provider detail for a denied check, e.g. an IAM decision reason

        Example: "implicitDeny"
      • groupoptionalstring

        Free-form grouping of related checks, e.g. base or vpc-write. Groupings may change as validations evolve