Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Create BYOC Infrastructure

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

Create a new BYOC Infrastructure in the organization. Returns the configuration of the newly created infrastructure

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
  • displayNameoptionalstring

    Human readable name for infrastructure

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    7 properties
    • idoptionalstring

      Unique identifier of the BYOC configuration

    • stateoptionalinfra-provisioningorinfra-terminatedorinfra-terminatingorinfra-readyorinfra-degradedorinfra-upgrading

      State of the infrastructure

      Example: "infra-ready"
    • accountIdoptionalstring

      Cloud account ID the BYOC infrastructure is bound to: AWS account ID, GCP project ID, or Azure subscription ID

      Example: "123456789012"
    • accountNamedeprecatedstring

      DEPRECATED. Use accountId instead. Cloud account ID the BYOC infrastructure is bound to

    • regionIdoptionalap-northeast-1orap-northeast-2orap-south-1orap-southeast-1orap-southeast-2orca-central-1+18 more

      Region for which the BYOC has been configured and where it is possible to create services

    • cloudProvideroptionalgcporawsorazure

      Cloud provider of the region

    • displayNameoptionalstring

      Human readable name for infrastructure

Report an issue
Navigation