Instaclustr BYOC AWS Provider Account Setup V1 API

openapi: 3.2.0
info:
  title: Instaclustr BYOC AWS Provider Account Setup V1 API
  version: Current
  x-logo:
    altText: Instaclustr Logo
    backgroundColor: '#FFFFFF'
    url: https://console2.instaclustr.com/assets/logos/instaclustr_logo_for_redocly.svg
  description: 'Operations tagged BYOC AWS Provider Account Setup V1 across 2 of this provider''s published API definitions: instaclustr-current-openapi.json, instaclustr-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.instaclustr.com
  description: Instaclustr API
security:
- Basic Authentication: []
tags:
- name: BYOC AWS Provider Account Setup V1
  description: Operations related to BYOC provider account setup records.
  x-insta-tag-group: Cluster Management V2
paths:
  /cluster-management/v2/resources/byoc-setups/aws/v1/:
    x-terraform-resource-name: byoc_aws_provider_account_setup_v1
    x-terraform-resource-poll-completed-statuses: RUNNING, FAILED
    x-terraform-resource-poll-enabled: true
    x-terraform-resource-poll-pending-statuses: GENESIS, PROVISIONING
    get:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: List all BYOC provider account setup records
      description: Returns a list of all BYOC provider account setup records for the authenticated account.
      responses:
        '200':
          description: List of BYOC provider account setup records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: getClusterManagementV2ResourcesByocSetupsAwsV1
      x-operation-id-source: derived
    post:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Create BYOC provider account setup record
      description: Create a new BYOC provider account setup record to indicate that a user has started setting up a BYOC provider account.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        required: true
      responses:
        '202':
          description: BYOC provider account setup record created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        '400':
          description: Bad request. Invalid input parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      x-codegen-request-body-name: body
      operationId: postClusterManagementV2ResourcesByocSetupsAwsV1
      x-operation-id-source: derived
    servers:
    - url: https://api.instaclustr.com
      description: Instaclustr API
  /cluster-management/v2/resources/byoc-setups/aws/v1/{id}:
    parameters:
    - name: id
      in: path
      description: ID of the BYOC provider account.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    get:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Get BYOC provider account setup record
      description: Returns a BYOC provider account setup record matching the provided provider account ID.
      responses:
        '200':
          description: BYOC provider account setup record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: getClusterManagementV2ResourcesByocSetupsAwsV1ById
      x-operation-id-source: derived
    put:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Update BYOC provider account setup record
      description: 'Update a BYOC provider account setup record matching the provided provider account ID. For setups in PROVISIONING, GENESIS, or FAILED status, the following fields can be updated: dataCentreBackupBuckets, cloudProviderAccountId, and iamRoleName. For setups in RUNNING status, AWS regions may be added or removed through dataCentreBackupBuckets (backup bucket names for retained AWS regions cannot be changed). An AWS region in use by an active cluster cannot be removed. At least one validated AWS region mapping is required.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        required: true
      responses:
        '202':
          description: BYOC provider account setup record updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        '400':
          description: Bad request. Invalid input parameters or disallowed field changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden. Missing required permissions, or AWS permission validation failed for new data centres.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      x-codegen-request-body-name: body
      operationId: putClusterManagementV2ResourcesByocSetupsAwsV1ById
      x-operation-id-source: derived
    post:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Validate BYOC provider account setup record
      description: Triggers validation of a BYOC provider account setup record matching the provided provider account ID. Validates the setup configuration and, if successful, transitions the provider account status to RUNNING.
      responses:
        '202':
          description: BYOC provider account setup validation triggered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByocAwsProviderAccountSetupV1'
        '400':
          description: Bad request. Invalid input parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden. Missing required permissions, or AWS provisioning permission validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: postClusterManagementV2ResourcesByocSetupsAwsV1ById
      x-operation-id-source: derived
    delete:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Delete BYOC provider account setup record
      description: Delete a BYOC provider account setup record matching the provided provider account ID.
      responses:
        '204':
          description: BYOC provider account setup record deleted successfully.
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: deleteClusterManagementV2ResourcesByocSetupsAwsV1ById
      x-operation-id-source: derived
    servers:
    - url: https://api.instaclustr.com
      description: Instaclustr API
  /cluster-management/v2/resources/byoc-setups/aws/v1/{id}/pending-data-centre-backup-buckets:
    parameters:
    - name: id
      in: path
      description: ID of the BYOC provider account.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    get:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: List pending AWS data centre backup bucket mappings
      description: Returns pending data centre backup bucket mappings for a RUNNING BYOC AWS provider account setup.
      responses:
        '200':
          description: Pending data centre backup bucket mappings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ByocAwsPendingDataCentreBackupBucketV1'
        '400':
          description: The BYOC provider account setup is not RUNNING.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: getClusterManagementV2ResourcesByocSetupsAwsV1ByIdPendingDataCentreBackupBuckets
      x-operation-id-source: derived
    servers:
    - url: https://api.instaclustr.com
      description: Instaclustr API
  /cluster-management/v2/resources/byoc-setups/aws/v1/{id}/pending-data-centre-backup-buckets/{dataCentre}:
    parameters:
    - name: id
      in: path
      description: ID of the BYOC provider account.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    - name: dataCentre
      in: path
      description: Data centre region name.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    put:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Upsert a pending AWS data centre backup bucket mapping
      description: Creates or replaces one pending data centre backup bucket mapping on a RUNNING BYOC AWS provider account setup.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ByocAwsPendingDataCentreBackupBucketUpdateV1'
        required: true
      responses:
        '202':
          description: Pending mapping saved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByocAwsPendingDataCentreBackupBucketV1'
        '400':
          description: Invalid mapping, non-RUNNING setup, validated data centre, or maximum mapping count exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup record not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      x-codegen-request-body-name: body
      operationId: putClusterManagementV2ResourcesByocSetupsAwsV1ByIdPendingDataCentreBackupBucketsByDataCentre
      x-operation-id-source: derived
    delete:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Delete a pending AWS data centre backup bucket mapping
      description: Deletes one pending data centre backup bucket mapping from a RUNNING BYOC AWS provider account setup.
      responses:
        '204':
          description: Pending mapping deleted successfully.
          content: {}
        '400':
          description: The BYOC provider account setup is not RUNNING.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup or pending mapping not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: deleteClusterManagementV2ResourcesByocSetupsAwsV1ByIdPendingDataCentreBackupBucketsByDataCentre
      x-operation-id-source: derived
    servers:
    - url: https://api.instaclustr.com
      description: Instaclustr API
  /cluster-management/v2/resources/byoc-setups/aws/v1/{id}/regions/{dataCentre}:
    parameters:
    - name: id
      in: path
      description: ID of the BYOC provider account.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    - name: dataCentre
      in: path
      description: Internal data centre code for the AWS region.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    delete:
      tags:
      - BYOC AWS Provider Account Setup V1
      summary: Delete a validated AWS region
      description: Delete a validated AWS region from a BYOC provider account in RUNNING status. The final validated AWS region cannot be deleted; delete the provider account instead. An AWS region still occupied by a cluster data centre (any status except DELETED, including suspended and failed) cannot be deleted.
      responses:
        '204':
          description: Validated AWS region deleted successfully.
          content: {}
        '400':
          description: The AWS region is in use by clusters, is the final validated AWS region, or the BYOC provider account setup is not RUNNING.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
        '404':
          description: BYOC provider account setup or validated AWS region not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorListResponseV2'
      operationId: deleteClusterManagementV2ResourcesByocSetupsAwsV1ByIdRegionsByDataCentre
      x-operation-id-source: derived
    servers:
    - url: https://api.instaclustr.com
      description: Instaclustr API
components:
  schemas:
    ErrorListResponseV2:
      title: Root Type for ErrorResponse
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseV2'
      description: ''
    ByocAwsPendingDataCentreBackupBucketUpdateV1:
      required:
      - backupBucketName
      type: object
      properties:
        backupBucketName:
          type: string
          description: S3 backup bucket name for the pending data centre region.
      description: Request to create or replace a pending AWS data centre backup bucket mapping.
    ByocAwsDataCentreBackupBucketV1:
      required:
      - backupBucketName
      - dataCentre
      type: object
      properties:
        backupBucketName:
          type: string
          description: S3 backup bucket name for the data centre region. An empty string indicates that an existing validated region from a manually configured provider account has no backup bucket. New and pending regions require a valid bucket name.
        dataCentre:
          type: string
          description: Data centre region name.
      description: Backup bucket mapping for a BYOC data centre region.
    ByocAwsPendingDataCentreBackupBucketV1:
      required:
      - backupBucketName
      - dataCentre
      type: object
      properties:
        backupBucketName:
          type: string
          description: S3 backup bucket name for the pending data centre region.
        dataCentre:
          type: string
          description: Data centre region name.
      description: Pending AWS data centre backup bucket mapping awaiting validation.
    ByocAwsProviderAccountSetupV1:
      required:
      - cloudProviderAccountId
      - dataCentreBackupBuckets
      - providerAccountName
      type: object
      properties:
        accountId:
          type: string
          description: UUID of the Instaclustr Account.
          format: uuid
          readOnly: true
        selfServiceByoc:
          type: boolean
          description: Whether this provider account was created via self-service BYOC setup.
          readOnly: true
        cloudProvider:
          type: string
          description: Cloud provider for this BYOC setup.
          readOnly: true
          example: AWS_VPC
        providerAccountId:
          type: string
          description: ID of the provider account.
          format: uuid
          readOnly: true
          x-terraform-id: true
        cloudProviderAccountId:
          type: string
          description: Cloud provider account ID for BYOC setup.
        dataCentreBackupBuckets:
          maxItems: 30
          type: array
          description: One or more data centre backup bucket mappings. Array order has no semantic meaning.
          items:
            $ref: '#/components/schemas/ByocAwsDataCentreBackupBucketV1'
          x-terraform-ignore-order: true
        existingKeyPairProviderAccountNames:
          type: array
          description: Names of other RUNNING BYOC provider accounts under this Instaclustr account that share the same AWS account ID and overlap at least one configured data centre region.
          readOnly: true
          items:
            type: string
        providerAccountName:
          type: string
          description: Name of the provider account.
          x-terraform-force-new: true
        iamRoleName:
          type: string
          description: Custom IAM role name for BYOC setup. If not provided, defaults to 'instaclustr-<account-id>'. Must be 1-64 characters, containing only alphanumeric characters and +=,.@-_ symbols.
        skipKeyPairCreation:
          type: boolean
          description: When true, an EC2 key pair already exists for this Instaclustr account in every configured data centre region in the target AWS account (created by another RUNNING BYOC setup, or by this setup if already validated). Terraform users should pass create_key_pair = false when applying the template. When false, individual regions may still overlap the RUNNING accounts named in existingKeyPairProviderAccountNames; compare their data centre mappings and set create_key_pair = false only for overlapping regions. CloudFormation downloads set CreateKeyPair automatically per region.
          readOnly: true
        status:
          type: string
          description: Status of the BYOC provider account setup.
          readOnly: true
          x-terraform-field-status: true
      description: A resource representing a BYOC provider account setup record.
      example:
        accountId: 068c447e-8475-49b2-974b-ca1c91702ed4
        cloudProvider: AWS_VPC
        cloudProviderAccountId: '123456789012'
        dataCentreBackupBuckets:
        - backupBucketName: my-byoc-backup-bucket-east
          dataCentre: US_EAST_1
        iamRoleName: instaclustr-my-account-role
        providerAccountId: 568c447e-8475-49b2-974b-ca1c91702ed4
        providerAccountName: my-byoc-provider-account
        selfServiceByoc: true
        status: RUNNING
    ErrorResponseV2:
      title: Root Type for ErrorResponse
      type: object
      properties:
        name:
          type: string
        message:
          type: string
      description: ''
  securitySchemes:
    Basic_Authentication:
      type: http
      description: Most requests to the API must use Basic Authentication and contain a valid username and appropriate API key for the endpoint.<br><br>API keys can be retrieved any time from the <a href='https://console2.instaclustr.com/' target='_blank'>console</a>. To find the API key relevant to the endpoint, refer to the Authentication & Rate Limit section for the endpoint or the group of the endpoint.
      scheme: basic
    No_Authentication:
      type: http
      description: Certain endpoints are publicly available and does not need any authentication to access.
      scheme: none
x-refined-from:
- instaclustr-current-openapi.json
- instaclustr-openapi.yml
x-tagGroups:
- name: Cluster Management V2
  tags:
  - Cluster Management V2 - Trait
  - Account Cluster List V2
  - AWS Encryption Key V2
  - AWS Endpoint DNS Names V2
  - AWS Endpoint Service Names V2
  - AWS Endpoint Service Principals V2
  - AWS FSx ONTAP File Systems
  - AWS FSx ONTAP Filesystem Credentials V2
  - AWS Prefix List Firewall Rule V1
  - AWS Prefix List Firewall Rules V1
  - AWS Security Group Firewall Rule V2
  - AWS Security Group Firewall Rules V2
  - AWS VPC Peer V2
  - Apache Cassandra Provisioning V2
  - Apache Kafka ACL V2
  - Apache Kafka ACL V3
  - Apache Kafka Connect Mirror V2
  - Apache Kafka Connect Provisioning V2
  - Apache Kafka Provisioning V2
  - Apache Kafka Provisioning V3
  - Apache Kafka Rest Proxy User
  - Apache Kafka Schema Registry User
  - Apache Kafka Tiered Storage
  - Apache Kafka Topic V2
  - Apache Kafka Topic V3
  - Apache Kafka User
  - Apache Zookeeper Provisioning V2
  - Azure Private Link Service Subscriptions
  - Azure Vnet Peer V2
  - BYOC AWS CloudFormation
  - BYOC AWS Provider Account Setup V1
  - Cadence Domain Rate Limits V2
  - Cadence Global Domain Rate Limits V2
  - Cadence Provisioning V2
  - ClickHouse Configurations
  - ClickHouse Integrations
  - ClickHouse Provisioning
  - Cloud Provider Details V2
  - Cluster Exclusion Window V2
  - Cluster Maintenance Events V2
  - Cluster Network Firewall Rule V2
  - Cluster Network Firewall Rules V2
  - Cluster Non Recurring Exclusion Window V2
  - Cluster Settings V2
  - Cluster Suspend Resume V2
  - Custom Tags V2
  - GCP PSC Service Attachments Accept List V2
  - GCP VPC Peer V2
  - Horizontal Scaling Operations
  - Karapace Rest Proxy User
  - Karapace Schema Registry User
  - MCP Gateway Backend V1
  - MCP Gateway Persona Access Control V1
  - MCP Gateway Provisioning V1
  - MCP Gateway Tool V1
  - MCP Gateway Virtual Server V1
  - Management Units Usage
  - OpenSearch Egress Rules V2
  - OpenSearch External S3 Bucket V2
  - OpenSearch Provisioning V2
  - PostgreSQL Configuration V2
  - PostgreSQL Operations
  - PostgreSQL Provisioning V2
  - Private Link Private Service Connect Endpoint Addresses V2
  - Redis Provisioning V2
  - Redis User V2
  - Resize Operations V2
  - Terraform Import V2
  - User Actions V3
  - Valkey Provisioning V2
  - Valkey User V2
- name: Monitoring
  tags:
  - Monitoring - Trait
  - Monitoring API
  - Monitoring API - Cluster
  - Monitoring API - Data Centre
  - Monitoring API - Node
- name: User Management
  tags:
  - User Management and SCIM 2.0 API - Trait
  - Service User Management API
  - User Management and SCIM 2.0 API
- name: Other
  tags:
  - Organization Management API
  - Pricing information - Node sizes