Skip to content

Update zone configuration constraints to provide cloud vendor region … #23146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeevanshu wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update zone configuration constraints to provide cloud vendor region … #23146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions src/current/v23.1/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
Copy link
Copy Markdown
Contributor

@rmloveland rmloveland Apr 1, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @jeevanshu can you say more about the motivation for this docs PR? it wasn't clear from reading the postmortem in Confluence why this is necessary

this says "you must include the cloud provider prefix in the region name" but AIUI that isn't actually true, the --locality flag just does arbitrary string matching:

https://www.cockroachlabs.com/docs/v26.1/cockroach-start#locality

so it's only necessary to pass that exact string using the cloud provider if that's what you passed to the cockroach binary in the cockroach start --locality flag

this seems like it might be something internal to how we run CockroachCloud and not something that is generally true for self-hosted clusters where people run cockroach start --locality={foo} with arbitrary values of {foo}

but maybe i'm misunderstanding this, please say more about what is motivating this change

Copy link
Copy Markdown
Author

@jeevanshu jeevanshu Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the comment @rmloveland.
I was not aware of locality flags can be arbitrary value.

You are also correct about CC clusters, where we pass locality flags to include cloud provider prefix like --locality=region=gcp-asia-southeast1,zone=gcp-asia-southeast1-c.

Context behind this change is during the incident, engineers tried to run the query to restrict zonal config for liveness ranges of CC host cluster away from certain zones but due to regional config missing the cloud provider prefix it was failing and there was no check present to validate the config.

Since it looks to be limited to just CockroachCloud clusters, do you recommend closing this PR and documenting this behaviour elsewhere?

<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v23.2/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v24.1/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v24.2/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v24.3/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v25.1/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v25.2/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v25.3/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v25.4/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v26.1/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
24 changes: 24 additions & 0 deletions src/current/v26.2/show-zone-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,30 @@ CONFIGURE ZONE 1

{% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md %}

{{site.data.alerts.callout_info}}
When specifying region constraints or lease preferences for nodes running on cloud providers, you must include the cloud provider prefix in the region name. The format is `{provider}-{region}`.
<br><br>
For example:

Cloud Provider | Region Format | Example
---------------|---------------|--------
**AWS** | `aws-{region}` | `aws-us-east-1`, `aws-eu-central-1`
**GCP** | `gcp-{region}` | `gcp-us-east1`, `gcp-asia-south1`
**Azure** | `azure-{region}` | `azure-eastus`, `azure-westus2`

This applies when using `constraints` or `lease_preferences` in zone configurations. For instance:

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER TABLE my_table CONFIGURE ZONE USING constraints = '[+region=gcp-us-east1]';
~~~

{% include_cached copy-clipboard.html %}
~~~ sql
ALTER DATABASE my_db CONFIGURE ZONE USING constraints = '{"+region=aws-us-east-1": 2, "+region=aws-eu-central-1": 1}';
~~~
{{site.data.alerts.end}}

## See also

- [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %})
Expand Down
Loading