ClustersApi.md

Clusters

All URIs are relative to https://cockroachlabs.cloud

Method	HTTP request	Description
CreateCluster	Post /api/v1/clusters	Create and initialize a new cluster
DeleteCluster	Delete /api/v1/clusters/{cluster_id}	Delete a cluster and all of its data
GetCluster	Get /api/v1/clusters/{cluster_id}	Get extended information about a cluster
GetConnectionString	Get /api/v1/clusters/{cluster_id}/connection-string	Get a formatted generic connection string for a cluster
ListAvailableRegions	Get /api/v1/clusters/available-regions	List the regions available for new clusters and nodes
ListClusterNodes	Get /api/v1/clusters/{cluster_id}/nodes	List nodes for a cluster
ListClusters	Get /api/v1/clusters	List clusters owned by an organization
ListMajorClusterVersions	Get /api/v1/cluster-versions	List available major cluster versions
UpdateCluster	Patch /api/v1/clusters/{cluster_id}	Scale, edit or upgrade a cluster

CreateCluster

Cluster CreateCluster(ctx).CreateClusterRequest(createClusterRequest).Execute()

Create and initialize a new cluster

Can be used by the following roles assigned at the organization scope:

• CLUSTER_ADMIN
• CLUSTER_CREATOR

Example

package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "./openapi"
)

func main() {
    createClusterRequest := *openapiclient.NewCreateClusterRequest("Name_example", openapiclient.CloudProvider.Type("GCP"), *openapiclient.NewCreateClusterSpecification()) // CreateClusterRequest | 

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.CreateCluster(context.Background()).CreateClusterRequest(createClusterRequest).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.CreateCluster``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `CreateCluster`: Cluster
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.CreateCluster`: %v\n", resp)
}

Path Parameters

Other Parameters

Other parameters are passed through a pointer to a apiCreateCluster struct via the builder pattern

Name	Type	Description	Notes
createClusterRequest	CreateClusterRequest

Return type

Cluster

Authorization

Bearer

HTTP request headers

• Content-Type: application/json
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

DeleteCluster

Cluster DeleteCluster(ctx, clusterId).Execute()

Delete a cluster and all of its data

Can be used by the following roles assigned at the organization or cluster scope:

• CLUSTER_ADMIN

Example

package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "./openapi"
)

func main() {
    clusterId := "clusterId_example" // string | 

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.DeleteCluster(context.Background(), clusterId).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.DeleteCluster``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `DeleteCluster`: Cluster
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.DeleteCluster`: %v\n", resp)
}

Path Parameters

Name	Type	Description	Notes
ctx	context.Context	context for authentication, logging, cancellation, deadlines, tracing, etc.
clusterId	string

Other Parameters

Other parameters are passed through a pointer to a apiDeleteCluster struct via the builder pattern

Name	Type	Description	Notes

Return type

Cluster

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

GetCluster

Cluster GetCluster(ctx, clusterId).Execute()

Get extended information about a cluster

Can be used by the following roles assigned at the organization or cluster scope:

• ORG_ADMIN
• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER
• CLUSTER_DEVELOPER

Example

package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "./openapi"
)

func main() {
    clusterId := "clusterId_example" // string | 

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.GetCluster(context.Background(), clusterId).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.GetCluster``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `GetCluster`: Cluster
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.GetCluster`: %v\n", resp)
}

Path Parameters

Name	Type	Description	Notes
ctx	context.Context	context for authentication, logging, cancellation, deadlines, tracing, etc.
clusterId	string

Other Parameters

Other parameters are passed through a pointer to a apiGetCluster struct via the builder pattern

Name	Type	Description	Notes

Return type

Cluster

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

GetConnectionString

GetConnectionStringResponse GetConnectionString(ctx, clusterId).Database(database).SqlUser(sqlUser).Os(os).Execute()

Get a formatted generic connection string for a cluster

Can be used by the following roles assigned at the organization or cluster scope:

• ORG_ADMIN
• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER
• CLUSTER_DEVELOPER

Example

package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "./openapi"
)

func main() {
    clusterId := "clusterId_example" // string | 
    database := "database_example" // string |  (optional) (default to "defaultdb")
    sqlUser := "sqlUser_example" // string |  (optional)
    os := "os_example" // string | os indicates the target operating system, used with formatting the default SSL certificate path. Required only for dedicated clusters. (optional)

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.GetConnectionString(context.Background(), clusterId).Database(database).SqlUser(sqlUser).Os(os).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.GetConnectionString``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `GetConnectionString`: GetConnectionStringResponse
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.GetConnectionString`: %v\n", resp)
}

Path Parameters

Name	Type	Description	Notes
ctx	context.Context	context for authentication, logging, cancellation, deadlines, tracing, etc.
clusterId	string

Other Parameters

Other parameters are passed through a pointer to a apiGetConnectionString struct via the builder pattern

Name	Type	Description	Notes

database | string | | [default to "defaultdb"] sqlUser | string | | os | string | os indicates the target operating system, used with formatting the default SSL certificate path. Required only for dedicated clusters. |

Return type

GetConnectionStringResponse

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

ListAvailableRegions

ListAvailableRegionsResponse ListAvailableRegions(ctx).Provider(provider).Serverless(serverless).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()

List the regions available for new clusters and nodes

Sort order: Distance (based on client IP address)

This endpoint may be used by any member of the organization.

Example

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    openapiclient "./openapi"
)

func main() {
    provider := "provider_example" // string | Optional CloudProvider for filtering.   - GCP: The Google Cloud Platform cloud provider.  - AWS: The Amazon Web Services cloud provider.  - AZURE: The Azure cloud provider. (optional)
    serverless := true // bool | Optional filter to only show regions available for serverless clusters. (optional) (default to false)
    paginationPage := "paginationPage_example" // string |  (optional)
    paginationLimit := int32(56) // int32 |  (optional)
    paginationAsOfTime := time.Now() // time.Time |  (optional)
    paginationSortOrder := "paginationSortOrder_example" // string |  - ASC: Sort in ascending order. This is the default unless otherwise specified.  - DESC: Sort in descending order. (optional)

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.ListAvailableRegions(context.Background()).Provider(provider).Serverless(serverless).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.ListAvailableRegions``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `ListAvailableRegions`: ListAvailableRegionsResponse
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.ListAvailableRegions`: %v\n", resp)
}

Path Parameters

Other Parameters

Other parameters are passed through a pointer to a apiListAvailableRegions struct via the builder pattern

Name	Type	Description	Notes
provider	string	Optional CloudProvider for filtering. - GCP: The Google Cloud Platform cloud provider. - AWS: The Amazon Web Services cloud provider. - AZURE: The Azure cloud provider.
serverless	bool	Optional filter to only show regions available for serverless clusters.	[default to false]
paginationPage	string
paginationLimit	int32
paginationAsOfTime	time.Time
paginationSortOrder	string	- ASC: Sort in ascending order. This is the default unless otherwise specified. - DESC: Sort in descending order.

Return type

ListAvailableRegionsResponse

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

ListClusterNodes

ListClusterNodesResponse ListClusterNodes(ctx, clusterId).RegionName(regionName).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()

List nodes for a cluster

Sort order: Region name, node name

Can be used by the following roles assigned at the organization or cluster scope:

• ORG_ADMIN
• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER
• CLUSTER_DEVELOPER

Example

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    openapiclient "./openapi"
)

func main() {
    clusterId := "clusterId_example" // string | 
    regionName := "regionName_example" // string | Optional filter to limit response to a single region. (optional)
    paginationPage := "paginationPage_example" // string |  (optional)
    paginationLimit := int32(56) // int32 |  (optional)
    paginationAsOfTime := time.Now() // time.Time |  (optional)
    paginationSortOrder := "paginationSortOrder_example" // string |  - ASC: Sort in ascending order. This is the default unless otherwise specified.  - DESC: Sort in descending order. (optional)

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.ListClusterNodes(context.Background(), clusterId).RegionName(regionName).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.ListClusterNodes``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `ListClusterNodes`: ListClusterNodesResponse
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.ListClusterNodes`: %v\n", resp)
}

Path Parameters

Name	Type	Description	Notes
ctx	context.Context	context for authentication, logging, cancellation, deadlines, tracing, etc.
clusterId	string

Other Parameters

Other parameters are passed through a pointer to a apiListClusterNodes struct via the builder pattern

Name	Type	Description	Notes

regionName | string | Optional filter to limit response to a single region. | paginationPage | string | | paginationLimit | int32 | | paginationAsOfTime | time.Time | | paginationSortOrder | string | - ASC: Sort in ascending order. This is the default unless otherwise specified. - DESC: Sort in descending order. |

Return type

ListClusterNodesResponse

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

ListClusters

ListClustersResponse ListClusters(ctx).ShowInactive(showInactive).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()

List clusters owned by an organization

Sort order: Cluster name

Returns all clusters that the user has read access over

Example

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    openapiclient "./openapi"
)

func main() {
    showInactive := true // bool | If `true`, show clusters that have been deleted or failed to initialize. Note that inactive clusters will only be included if the requesting user has organization-scoped cluster read permissions. (optional) (default to false)
    paginationPage := "paginationPage_example" // string |  (optional)
    paginationLimit := int32(56) // int32 |  (optional)
    paginationAsOfTime := time.Now() // time.Time |  (optional)
    paginationSortOrder := "paginationSortOrder_example" // string |  - ASC: Sort in ascending order. This is the default unless otherwise specified.  - DESC: Sort in descending order. (optional)

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.ListClusters(context.Background()).ShowInactive(showInactive).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.ListClusters``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `ListClusters`: ListClustersResponse
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.ListClusters`: %v\n", resp)
}

Path Parameters

Other Parameters

Other parameters are passed through a pointer to a apiListClusters struct via the builder pattern

Name	Type	Description	Notes
showInactive	bool	If `true`, show clusters that have been deleted or failed to initialize. Note that inactive clusters will only be included if the requesting user has organization-scoped cluster read permissions.	[default to false]
paginationPage	string
paginationLimit	int32
paginationAsOfTime	time.Time
paginationSortOrder	string	- ASC: Sort in ascending order. This is the default unless otherwise specified. - DESC: Sort in descending order.

Return type

ListClustersResponse

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

ListMajorClusterVersions

ListMajorClusterVersionsResponse ListMajorClusterVersions(ctx).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()

List available major cluster versions

Sort order: Version number descending

This endpoint may be used by any member of the organization.

Example

package main

import (
    "context"
    "fmt"
    "os"
    "time"
    openapiclient "./openapi"
)

func main() {
    paginationPage := "paginationPage_example" // string |  (optional)
    paginationLimit := int32(56) // int32 |  (optional)
    paginationAsOfTime := time.Now() // time.Time |  (optional)
    paginationSortOrder := "paginationSortOrder_example" // string |  - ASC: Sort in ascending order. This is the default unless otherwise specified.  - DESC: Sort in descending order. (optional)

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.ListMajorClusterVersions(context.Background()).PaginationPage(paginationPage).PaginationLimit(paginationLimit).PaginationAsOfTime(paginationAsOfTime).PaginationSortOrder(paginationSortOrder).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.ListMajorClusterVersions``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `ListMajorClusterVersions`: ListMajorClusterVersionsResponse
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.ListMajorClusterVersions`: %v\n", resp)
}

Path Parameters

Other Parameters

Other parameters are passed through a pointer to a apiListMajorClusterVersions struct via the builder pattern

Name	Type	Description	Notes
paginationPage	string
paginationLimit	int32
paginationAsOfTime	time.Time
paginationSortOrder	string	- ASC: Sort in ascending order. This is the default unless otherwise specified. - DESC: Sort in descending order.

Return type

ListMajorClusterVersionsResponse

Authorization

Bearer

HTTP request headers

• Content-Type: Not defined
• Accept: application/json

[Back to top] [Back to API list] [Back to README]

UpdateCluster

Cluster UpdateCluster(ctx, clusterId).UpdateClusterSpecification(updateClusterSpecification).Execute()

Scale, edit or upgrade a cluster

In addition to adding nodes and changing cluster fields, the PATCH Cluster endpoint can be used to upgrade the cluster version. A cluster can be upgraded when its upgrade_status field is equal to UPGRADE_AVAILABLE. To begin the upgrade, PATCH {"upgrade_status": "MAJOR_UPGRADE_RUNNING"} to this endpoint. Multi-node clusters will undergo a rolling upgrade and will remain available, but single-node clusters will be briefly unavailable while the upgrade takes place. Upgrades will be finalized automatically after 72 hours but can be manually finalized by sending a PATCH containing {"upgrade_status": "FINALIZED"} to this endpoint. Before the cluster is finalized, it can be rolled back by sending a PATCH containing {"upgrade_status": "ROLLBACK_RUNNING"}. Version upgrade operations cannot be performed simultaneously with other update operations.

Can be used by the following roles assigned at the organization or cluster scope:

• CLUSTER_ADMIN
• CLUSTER_OPERATOR_WRITER

Example

package main

import (
    "context"
    "fmt"
    "os"
    openapiclient "./openapi"
)

func main() {
    clusterId := "clusterId_example" // string | 
    updateClusterSpecification := *openapiclient.NewUpdateClusterSpecification() // UpdateClusterSpecification | 

    configuration := openapiclient.NewConfiguration()
    api_client := openapiclient.NewClient(configuration)
    resp, r, err := api_client.ClustersApi.UpdateCluster(context.Background(), clusterId).UpdateClusterSpecification(updateClusterSpecification).Execute()
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `ClustersApi.UpdateCluster``: %v\n", err)
        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    }
    // response from `UpdateCluster`: Cluster
    fmt.Fprintf(os.Stdout, "Response from `ClustersApi.UpdateCluster`: %v\n", resp)
}

Path Parameters

Name	Type	Description	Notes
ctx	context.Context	context for authentication, logging, cancellation, deadlines, tracing, etc.
clusterId	string

Other Parameters

Other parameters are passed through a pointer to a apiUpdateCluster struct via the builder pattern

Name	Type	Description	Notes

updateClusterSpecification | UpdateClusterSpecification | |

Return type

Cluster

Authorization

Bearer

HTTP request headers

• Content-Type: application/json
• Accept: application/json

[Back to top] [Back to API list] [Back to README]