Skip to content

Commit

Permalink
Add basic docs on multi-region zone configs
Browse files Browse the repository at this point in the history
Fixes #9741, #9746.

Addresses #9287.
  • Loading branch information
rmloveland committed Mar 9, 2021
1 parent 64d938b commit 6f29d5b
Showing 1 changed file with 3 additions and 0 deletions.
3 changes: 3 additions & 0 deletions _includes/v21.1/zone-configs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ Variable | Description
`num_replicas` | <a name="num_replicas"></a> The number of replicas in the zone.<br><br>**Default:** `3`<br><br>For the `system` database and `.meta`, `.liveness`, and `.system` ranges, the default value is `5`.
`constraints` | An array of required (`+`) and/or prohibited (`-`) constraints influencing the location of replicas. See [Types of Constraints](configure-replication-zones.html#types-of-constraints) and [Scope of Constraints](configure-replication-zones.html#scope-of-constraints) for more details.<br/><br/>To prevent hard-to-detect typos, constraints placed on [store attributes and node localities](configure-replication-zones.html#descriptive-attributes-assigned-to-nodes) must match the values passed to at least one node in the cluster. If not, an error is signalled. To prevent this error, make sure at least one active node is configured to match the constraint. For example, apply `constraints = '[+region=west]'` only if you had set `--locality=region=west` for at least one node while starting the cluster.<br/><br/>**Default:** No constraints, with CockroachDB locating each replica on a unique node and attempting to spread replicas evenly across localities.
`lease_preferences` <a name="lease_preferences"></a> | An ordered list of required and/or prohibited constraints influencing the location of [leaseholders](architecture/overview.html#glossary). Whether each constraint is required or prohibited is expressed with a leading `+` or `-`, respectively. Note that lease preference constraints do not have to be shared with the `constraints` field. For example, it's valid for your configuration to define a `lease_preferences` field that does not reference any values from the `constraints` field. It's also valid to define a `lease_preferences` field with no `constraints` field at all. <br /><br /> If the first preference cannot be satisfied, CockroachDB will attempt to satisfy the second preference, and so on. If none of the preferences can be met, the lease will be placed using the default lease placement algorithm, which is to base lease placement decisions on how many leases each node already has, trying to make all the nodes have around the same amount.<br /><br />Each value in the list can include multiple constraints. For example, the list `[[+zone=us-east-1b, +ssd], [+zone=us-east-1a], [+zone=us-east-1c, +ssd]]` means "prefer nodes with an SSD in `us-east-1b`, then any nodes in `us-east-1a`, then nodes in `us-east-1c` with an SSD."<br /><br /> For a usage example, see [Constrain leaseholders to specific availability zones](configure-replication-zones.html#constrain-leaseholders-to-specific-availability-zones).<br /><br />**Default**: No lease location preferences are applied if this field is not specified.
`global_reads` | If `true`, transactions operating on the range(s) affected by this zone config should be non-blocking. Most users will not need to modify this setting; it is applied automatically when you [use the `GLOBAL` table locality in a multi-region cluster](multiregion-overview.html#table-locality).
`num_voters` | Specifies the number of [voting replicas](architecture/life-of-a-distributed-transaction.html#consensus). When set, `num_replicas` will be the sum of voting and non-voting replicas. Most users will not need to modify this setting; it is part of the underlying machinery that enables [improved multi-region capabilities in v21.1 and above](multiregion-overview.html).
`voter_constraints` | Specifies the constraints that govern the placement of voting replicas. This differs from the `constraints` field, which will govern the placement of all voting and non-voting replicas. Most users will not need to modify this setting; it is part of the underlying machinery that enables [improved multi-region capabilities in v21.1 and above](multiregion-overview.html).

{{site.data.alerts.callout_info}}
If a value is not set, new zone configurations will inherit their values from their parent zone (e.g., a partition zone inherits from the table zone), which is not necessarily `default`.
Expand Down

0 comments on commit 6f29d5b

Please sign in to comment.