planetscale.com/v2

Account is the name of the Azure storage account to use.

Container is the name of the Azure storage account container to use.

KeyPrefix is an optional prefix added to all object keys created by Vitess. This is only needed if the same container is also used for something other than backups for VitessClusters. Backups from different clusters, keyspaces, or shards will automatically avoid colliding with each other within a container, regardless of this setting.

AuthSecret is a reference to the Secret to use for Azure authentication.

AuthSecret is a reference to the Secret to use for Ceph S3 authentication. If set, this must point to a file in the format expected for the https://github.com/vitessio/vitess/blob/master/examples/local/ceph_backup_config.json file.

Locations is a list of places where Vitess backup data for the cluster can be stored. At least one storage location must be specified. Within each storage location, there are multiple fields for various location types (gcs, s3, etc.); exactly one such field must be populated.

Multiple storage locations may be desired if, for example, the cluster spans multiple regions. Each storage location is independent of the others; backups can only be restored from the same storage location in which they were originally taken.

Engine specifies the Vitess backup engine to use, either “builtin” or “xtrabackup”. Note that if you change this after a Vitess cluster is already deployed, you must roll the change out to all tablets and then take a new backup from one tablet in each shard. Otherwise, new tablets trying to restore will find that the latest backup was created with the wrong engine. Default: builtin

Subcontroller specifies any parameters needed for launching the VitessBackupStorage subcontroller pod.

(Members of EtcdLockserverTemplate are embedded into this type.)

EtcdLockserverTemplate contains the user-specified parts of EtcdLockserverSpec. These are the parts that are configurable inside VitessCluster. The rest of the fields below are filled in by the parent controller.

Zone is the name of the Availability Zone that this lockserver should run in. This value should match the value of the “failure-domain.beta.kubernetes.io/zone” label on the Kubernetes Nodes in that AZ. If the Kubernetes Nodes don’t have such a label, leave this empty.

The generation observed by the controller.

Available is a condition that indicates whether the cluster is able to serve queries.

ClientServiceName is the name of the Service for etcd client connections.

Image is the etcd server image (including version tag) to deploy. Default: Let the operator choose.

ImagePullPolicy specifies if/when to pull a container image.

ImagePullSecrets specifies the container image pull secrets to add to all etcd Pods.

Resources specify the compute resources to allocate for each etcd member. Default: Let the operator choose.

DataVolumeClaimTemplate configures the PersistentVolumeClaims that will be created for each etcd instance to store its data files. This field is required.

IMPORTANT: For a cell-local lockserver in a Kubernetes cluster that spans multiple zones, you should ensure that volumeBindingMode: WaitForFirstConsumer is set on the StorageClass specified in the storageClassName field here. Default: Let the operator choose.

ExtraFlags can optionally be used to override default flags set by the operator, or pass additional flags to etcd. All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

ExtraEnv can optionally be used to override default environment variables set by the operator, or pass additional environment variables.

ExtraVolumes can optionally be used to override default Pod volumes defined by the operator, or provide additional volumes to the Pod. Note that when adding a new volume, you should usually also add a volumeMount to specify where in each container’s filesystem the volume should be mounted.

ExtraVolumeMounts can optionally be used to override default Pod volumeMounts defined by the operator, or specify additional mounts. Typically, these are used to mount volumes defined through extraVolumes.

InitContainers can optionally be used to supply extra init containers that will be run to completion one after another before any app containers are started.

SidecarContainers can optionally be used to supply extra containers that run alongside the main containers.

Affinity allows you to set rules that constrain the scheduling of your Etcd pods. WARNING: These affinity rules will override all default affinities that we set; in turn, we can’t guarantee optimal scheduling of your pods if you choose to set this field.

Annotations can optionally be used to attach custom annotations to Pods created for this component.

ExtraLabels can optionally be used to attach custom labels to Pods created for this component.

CreatePDB sets whether to create a PodDisruptionBudget (PDB) for etcd member Pods.

Note: Disabling this will NOT delete a PDB that was previously created.

Default: true

CreateClientService sets whether to create a Service for the client port of etcd member Pods.

Note: Disabling this will NOT delete a Service that was previously created.

Default: true

CreatePeerService sets whether to create a Service for the peer port of etcd member Pods.

Note: Disabling this will NOT delete a Service that was previously created.

Default: true

AdvertisePeerURLs can optionally be used to override the URLs that etcd members use to find each other for peer-to-peer connections.

If specified, the list must contain exactly 3 entries, one for each etcd member index (1,2,3) respectively.

Default: Build peer URLs automatically based on Kubernetes built-in DNS.

LocalMemberIndex can optionally be used to specify that only one etcd member should actually be deployed. This can be used to spread members across multiple Kubernetes clusters by configuring the EtcdLockserver CRD in each cluster to deploy a different member index. If specified, the index must be 1, 2, or 3.

Default: Deploy all etcd members locally.

ClientService can optionally be used to customize the etcd client Service.

PeerService can optionally be used to customize the etcd peer Service.

Tolerations allow you to schedule pods onto nodes with matching taints.

User is a provided database user from an externally managed MySQL that Vitess can use to carry out necessary actions. Password for this user must be supplied in the CredentialsSecret.

Host is the endpoint string to an externally managed MySQL, without any port.

Port specifies the port for the externally managed MySQL endpoint.

Database is the name of the database.

CredentialsSecret should link to a JSON credentials file used to connect to the externally managed MySQL endpoint. The credentials file is understood and parsed by Vitess and must be in the format: { “username”: [ “password” ] } Vitess always uses the first password in the password array.

ServerCACertSecret should link to a certificate authority file if one is required by your externally managed MySQL endpoint.

AllowResourceChanges can be used to allow changes to certain resource requests and limits to propagate immediately, bypassing the external rollout tool.

Supported options: - storage

Default: All resource changes wait to be released by the external rollout tool.

Bucket is the name of the GCS bucket to use.

KeyPrefix is an optional prefix added to all object keys created by Vitess. This is only needed if the same bucket is also used for something other than backups for VitessClusters. Backups from different clusters, keyspaces, or shards will automatically avoid colliding with each other within a bucket, regardless of this setting.

AuthSecret is a reference to the Secret to use for GCS authentication. If set, this must point to a file in the format expected for the GOOGLE_APPLICATION_CREDENTIALS environment variable. Default: Use the default credentials of the Node.

External specifies that we should connect to an existing lockserver, instead of deploying our own. If this is set, all other Lockserver fields are ignored.

Etcd deploys our own etcd cluster as a lockserver.

Etcd is the status of the EtcdCluster, if we were asked to deploy one.

Mysql56Compatible is a container image (including version tag) for mysqld that’s compatible with the Vitess “MySQL56” flavor setting.

Mysql80Compatible is a container image (including version tag) for mysqld that’s compatible with the Vitess “MySQL80” flavor setting.

MariadbCompatible is a container image (including version tag) for mysqld that’s compatible with the Vitess “MariaDB” flavor setting.

Mariadb103Compatible is a container image (including version tag) for mysqld that’s compatible with the Vitess “MariaDB103” flavor setting.

Resources specify the compute resources to allocate for just the MySQL process (the underlying local datastore). This field is required.

ConfigOverrides can optionally be used to provide a my.cnf snippet to override default my.cnf values (included with Vitess) for this particular MySQL instance.

Reason is a CamelCase token for programmatic reasoning about why the object is orphaned.

Message is a human-readable explanation for why the object is orphaned.

Workflow represents the name of the active vreplication workflow for resharding.

State is either ‘Running’, ‘Copying’, ‘Error’ or ‘Unknown’.

SourceShards is a list of source shards for the current resharding operation.

TargetShards is a list of target shards for the current resharding operation.

CopyProgress will indicate the percentage completion ranging from 0-100 as integer values. Once we are past the copy phase, this value will always be 100, and will never be 100 while we are still within the copy phase. If we can not compute the copy progress in a timely fashion, we will report -1 to indicate the progress is unknown.

Region is the AWS region in which the bucket is located.

Bucket is the name of the S3 bucket to use.

Endpoint is the host:port (port is required) for the S3 backend. Default: Use the endpoint associated with region by the driver.

KeyPrefix is an optional prefix added to all object keys created by Vitess. This is only needed if the same bucket is also used for something other than backups for VitessClusters. Backups from different clusters, keyspaces, or shards will automatically avoid colliding with each other within a bucket, regardless of this setting.

AuthSecret is a reference to the Secret to use for S3 authentication. If set, this must point to a file in the format expected for the ~/.aws/credentials file. Default: Use the default credentials of the Node.

Name is the name of a Kubernetes Secret object to use as the data source. The Secret must be in the same namespace as the VitessCluster.

The ‘key’ field defines the item to pick from the Secret object’s ‘data’ map.

If a Secret name is not specified, the data source must be defined with the ‘volumeName’ field instead.

VolumeName directly specifies the name of a Volume in each Pod that should be mounted. You must ensure a Volume by that name exists in all relevant Pods, such as by using the appropriate ExtraVolumes fields. If specified, this takes precedence over the ‘name’ field.

The ‘key’ field defines the name of the file to load within this Volume.

Key is the name of the item within the data source to use as the value.

For a Kubernetes Secret object (specified with the ‘name’ field), this is the key within the ‘data’ map.

When ‘volumeName’ is used, this specifies the name of the file to load within that Volume.

Annotations specifies extra annotations to add to the Service object. Annotations added in this way will NOT be automatically removed from the Service object if they are removed here.

ClusterIP can optionally be used to override the Service’s clusterIP. This field is immutable on Service objects, so changes made after the initial creation of the Service will only be applied if you manually delete the Service.

Name is the backup location name.

CompleteBackups is the number of complete backups observed.

IncompleteBackups is the number of incomplete backups observed.

LatestCompleteBackupTime is the timestamp of the most recent complete backup.

RegisterCellsAliases can be used to enable or disable registering cells aliases into topo records. Default: true

RegisterCells can be used to enable or disable registering cells into topo records. Default: true

PruneCells can be used to enable or disable pruning of extraneous cells from topo records. Default: true

PruneKeyspaces can be used to enable or disable pruning of extraneous keyspaces from topo records. Default: true

PruneSrvKeyspaces can be used to enable or disable pruning of extraneous serving keyspaces from topo records. Default: true

PruneShards can be used to enable or disable pruning of extraneous shards from topo records. Default: true

PruneShardCells can be used to enable or disable pruning of extraneous shard cells from topo records. Default: true

PruneTablets can be used to enable or disable pruning of extraneous tablets from topo records. Default: true

Name is used to refer to this backup location from other parts of a VitessCluster object.

In particular, the backupLocationName field in each tablet pool within each shard must match one of the names defined by this field.

This name must be unique among all backup locations defined in a given cluster. A backup location with an empty name defines the default location used when a tablet pool does not specify a backupLocationName.

GCS specifies a backup location in Google Cloud Storage.

S3 specifies a backup location in Amazon S3.

Azblob specifies a backup location in Azure Blob Storage.

Ceph specifies a backup location in Ceph S3.

Volume specifies a backup location as a Kubernetes Volume Source to mount. This can be used, for example, to store backups on an NFS mount, or on a shared host path for local testing.

VolumeSubPath gives the subpath in the volume to mount to the backups target. Only used for Volume-backed backup storage, ignored otherwise.

Annotations can optionally be used to attach custom annotations to Pods that need access to this backup storage location.

StartTime is the time when the backup started.

FinishedTime is the time when the backup finished.

Complete indicates whether the backup ever completed.

Position is the replication position of the snapshot that was backed up. The position is expressed in the native, GTID-based format of the MySQL flavor that took the backup. This is only available after the backup is complete.

Engine is the Vitess backup engine implementation that was used.

StorageDirectory is the name of the parent directory in storage that contains this backup.

StorageName is the name of the backup in storage. This is different from the name of the VitessBackup object created to represent metadata about the actual backup in storage.

Location specifies the Vitess parameters for connecting to the backup storage location.

Subcontroller specifies any parameters needed for launching the VitessBackupStorage subcontroller pod.

The generation observed by the controller.

TotalBackupCount is the total number of backups found in this storage location, across all keyspaces and shards.

ServiceAccountName specifies the ServiceAccount used to launch the VitessBackupStorage subcontroller pod in the namespace of the VitessCluster. If empty (the default), the same account as the operator will be reused. If your VitessCluster is in a different namespace than the operator, this account is unlikely to work.

Replicas is the number of vtgate instances to deploy in this cell.

Resources determines the compute resources reserved for each vtgate replica.

Authentication configures how Vitess Gateway authenticates MySQL client connections.

SecureTransport configures secure transport connections for vtgate.

ExtraFlags can optionally be used to override default flags set by the operator, or pass additional flags to vtgate. All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

ExtraEnv can optionally be used to override default environment variables set by the operator, or pass additional environment variables.

ExtraVolumes can optionally be used to override default Pod volumes defined by the operator, or provide additional volumes to the Pod. Note that when adding a new volume, you should usually also add a volumeMount to specify where in each container’s filesystem the volume should be mounted.

ExtraVolumeMounts can optionally be used to override default Pod volumeMounts defined by the operator, or specify additional mounts. Typically, these are used to mount volumes defined through extraVolumes.

InitContainers can optionally be used to supply extra init containers that will be run to completion one after another before any app containers are started.

SidecarContainers can optionally be used to supply extra containers that run alongside the main containers.

Affinity allows you to set rules that constrain the scheduling of your vtgate pods. WARNING: These affinity rules will override all default affinities that we set; in turn, we can’t guarantee optimal scheduling of your pods if you choose to set this field.

Annotations can optionally be used to attach custom annotations to Pods created for this component. These will be attached to the underlying Pods that the vtgate Deployment creates.

ExtraLabels can optionally be used to attach custom labels to Pods created for this component. These will be attached to the underlying Pods that the vtgate Deployment creates.

Service can optionally be used to customize the per-cell vtgate Service.

Tolerations allow you to schedule pods onto nodes with matching taints.

Available indicates whether the vtgate service is fully available.

ServiceName is the name of the Service for this cell’s vtgate.

Vtgate is the container image (including version tag) to use for Vitess Gateway instances.

(Members of VitessCellTemplate are embedded into this type.)

VitessCellTemplate contains the user-specified parts of VitessCellSpec. These are the parts that are configurable inside VitessCluster. The rest of the fields below are filled in by the parent controller.

GlobalLockserver are the params to connect to the global lockserver.

AllCells is a list of all cells in the Vitess cluster.

Images are not customizable by users at the cell level because version skew across the cluster is discouraged except during rolling updates, in which case this field is automatically managed by the VitessCluster controller that owns this VitessCell.

ImagePullPolicies are inherited from the VitessCluster spec.

ImagePullSecrets are inherited from the VitessCluster spec.

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

The generation observed by the controller.

Lockserver is a summary of the status of the cell-local lockserver.

Gateway is a summary of the status of vtgate in this cell.

Keyspaces is a summary of keyspaces deployed in this cell. This summary could be empty either if there are no keyspaces, or if the controller failed to read the current state. Use the Idle condition to distinguish these scenarios when the difference matters.

Idle is a condition indicating whether the cell can be turned down. If Idle is True, there are no keyspaces deployed in the cell, so it should be safe to turn down the cell.

Name is the cell name as it should be provided to Vitess. Note that this is different from the VitessCell object’s metadata.name, which is generated by the operator.

Zone is the name of the Availability Zone that this Vitess Cell should run in. This value should match the value of the “failure-domain.beta.kubernetes.io/zone” label on the Kubernetes Nodes in that AZ. If the Kubernetes Nodes don’t have such a label, leave this empty.

Lockserver specifies either a deployed or external lockserver to be used as the Vitess cell-local topology store. Default: Put this cell’s topology data in the global lockserver instead of its own lockserver.

Gateway configures the Vitess Gateway deployment in this cell.

PendingChanges describes changes to the cell that will be applied the next time a rolling update allows.

GatewayAvailable indicates whether the vtgate service is fully available.

PendingChanges describes changes to the keyspace that will be applied the next time a rolling update allows.

DesiredShards is the number of desired shards. This is computed from information that’s already available in the spec, but clients should use this value instead of trying to compute shard partitionings on their own.

Shards is the number of observed shards. This could be higher or lower than desiredShards if the state has not yet converged.

ReadyShards is the number of desired shards that are Ready.

UpdatedShards is the number of desired shards that are up-to-date (have no pending changes).

DesiredTablets is the total number of desired tablets across all shards. This is computed from information that’s already available in the spec, but clients should use this value instead of trying to compute shard partitionings on their own.

Tablets is the total number of observed tablets across all shards. This could be higher or lower than desiredTablets if the state has not yet converged.

ReadyTablets is the number of desired tablets that are Ready.

UpdatedTablets is the number of desired tablets that are up-to-date (have no pending changes).

Cells is a list of cells in which any observed tablets for this keyspace are deployed.

Images specifies the container images (including version tag) to use in the cluster. Default: Let the operator choose.

ImagePullPolicies specifies the container image pull policies to use for images defined in the ‘images’ field.

ImagePullSecrets specifies the image pull secrets to add to all Pods that use the images defined in the ‘images’ field.

Backup specifies how to take and store Vitess backups. This is optional but strongly recommended. In addition to disaster recovery, Vitess currently depends on backups to support provisioning of a new tablet in a shard with existing data, as an implementation detail.

GlobalLockserver specifies either a deployed or external lockserver to be used as the Vitess global topology store. Default: Deploy an etcd cluster as the global lockserver.

Dashboard deploys a set of Vitess Dashboard servers (vtctld) for the Vitess cluster.

Cells is a list of templates for VitessCells to create for this cluster.

Each VitessCell represents a set of Nodes in a given failure domain, to which VitessKeyspaces can be deployed. The VitessCell also deploys cell-local services that any keyspaces deployed there will need.

This field is required, but it may be set to an empty list: []. Before removing any cell from this list, you should first ensure that no keyspaces are set to deploy to this cell.

Keyspaces defines the logical databases to deploy.

A VitessKeyspace can deploy to multiple VitessCells.

This field is required, but it may be set to an empty list: []. Before removing any keyspace from this list, you should first ensure that it is undeployed from all cells by clearing the keyspace’s list of target cells.

ExtraVitessFlags can optionally be used to pass flags to all Vitess components. WARNING: Any flags passed here must be flags that can be accepted by vtgate, vtctld, vtorc, and vttablet. An example use-case would be topo flags.

All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

TopologyReconciliation can be used to enable or disable registration or pruning of various vitess components to and from topo records.

UpdateStrategy specifies how components in the Vitess cluster will be updated when a revision is made to the VitessCluster spec.

GatewayService can optionally be used to customize the global vtgate Service. Note that per-cell vtgate Services can be customized within each cell definition.

TabletService can optionally be used to customize the global, headless vttablet Service.

The generation observed by the controller.

GlobalLockserver is the status of the global lockserver.

GatewayServiceName is the name of the cluster-wide vtgate Service.

VitessDashboard is a summary of the status of the vtctld deployment.

Cells is a summary of the status of desired cells.

Keyspaces is a summary of the status of desired keyspaces.

OrphanedCells is a list of unwanted cells that could not be turned down.

OrphanedKeyspaces is a list of unwanted keyspaces that could not be turned down.

Type selects the overall update strategy.

Supported options are:

• External: Schedule updates on objects that should be updated, but wait for an external tool to release them by adding the ‘rollout.planetscale.com/released’ annotation.
• Immediate: Release updates to all cells, keyspaces, and shards as soon as the VitessCluster spec is changed. Perform rolling restart of one tablet Pod per shard at a time, with automatic planned reparents whenever possible to avoid master downtime.

Default: External

External can optionally be used to enable the user to customize their external update strategy to allow certain updates to pass through immediately without using an external tool.

Cells is a list of cell names (as defined in the Cells list) in which to deploy vtctld. Default: Deploy to all defined cells.

Replicas is the number of vtctld instances to deploy in each cell.

Resources determines the compute resources reserved for each vtctld replica.

ExtraFlags can optionally be used to override default flags set by the operator, or pass additional flags to vtctld. All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

ExtraEnv can optionally be used to override default environment variables set by the operator, or pass additional environment variables.

ExtraVolumes can optionally be used to override default Pod volumes defined by the operator, or provide additional volumes to the Pod. Note that when adding a new volume, you should usually also add a volumeMount to specify where in each container’s filesystem the volume should be mounted.

ExtraVolumeMounts can optionally be used to override default Pod volumeMounts defined by the operator, or specify additional mounts. Typically, these are used to mount volumes defined through extraVolumes.

InitContainers can optionally be used to supply extra init containers that will be run to completion one after another before any app containers are started.

SidecarContainers can optionally be used to supply extra containers that run alongside the main containers.

Affinity allows you to set rules that constrain the scheduling of your vtctld pods. WARNING: These affinity rules will override all default affinities that we set; in turn, we can’t guarantee optimal scheduling of your pods if you choose to set this field.

Annotations can optionally be used to attach custom annotations to Pods created for this component. These will be attached to the underlying Pods that the vtctld Deployment creates.

ExtraLabels can optionally be used to attach custom labels to Pods created for this component. These will be attached to the underlying Pods that the vtctld Deployment creates.

Service can optionally be used to customize the vtctld Service.

Tolerations allow you to schedule pods onto nodes with matching taints.

Available indicates whether the vtctld service has available endpoints.

ServiceName is the name of the Service for this cluster’s vtctld.

Static configures vtgate to use a static file containing usernames and passwords.

Required configures vtgate to reject non-secure transport connections. Applies only to MySQL protocol connections. All GRPC transport is required to be encrypted when certs are set.

TLS configures vtgate to use TLS encrypted transport.

Secret configures vtgate to load the static auth file from a given key in a given Secret.

ClientCACertSecret configures vtgate to load the TLS certificate authority PEM file from a given key in a given Secret. If specified, checks client certificates are signed by this CA certificate. Optional.

CertSecret configures vtgate to load the TLS cert PEM file from a given key in a given Secret.

KeySecret configures vtgate to load the TLS key PEM file from a given key in a given Secret.

Vtctld is the container image pull policy to use for Vitess Dashboard instances.

Vtorc is the container image pull policy to use for Vitess Orchestrator instances.

Vtgate is the container image pull policy to use for Vitess Gateway instances.

Vttablet is the container image pull policy to use for Vitess Tablet instances.

Vtbackup is the container image pull policy to use for Vitess Backup jobs.

Mysqld is the container image pull policy to use for mysqld.

MysqldExporter is the container image pull policy to use for mysqld-exporter.

Vtctld is the container image (including version tag) to use for Vitess Dashboard instances.

Vtorc is the container image (including version tag) to use for Vitess Orchestrator instances.

Vtgate is the container image (including version tag) to use for Vitess Gateway instances.

Vttablet is the container image (including version tag) to use for Vitess Tablet instances.

Vtbackup is the container image (including version tag) to use for Vitess Backup jobs.

Mysqld specifies the container image to use for mysqld, as well as declaring which MySQL flavor setting in Vitess the image is compatible with. Only one flavor image may be provided at a time. mysqld running alongside each tablet.

MysqldExporter specifies the container image to use for mysqld-exporter.

Start is a lowercase hexadecimal string representation of an arbitrary-length sequence of bytes. If Start is the empty string, the key range is unbounded at the bottom. If Start is not empty, the bytes of a keyspace ID must compare greater than or equal to Start in lexicographical order to be in the range.

End is a lowercase hexadecimal string representation of an arbitrary-length sequence of bytes. If End is the empty string, the key range is unbounded at the top. If End is not empty, the bytes of a keyspace ID must compare strictly less than End in lexicographical order to be in the range.

Type is the type of the condition.

Status is the status of the condition. Can be True, False, Unknown.

Last time the condition transitioned from one status to another. Optional.

Unique, one-word, PascalCase reason for the condition’s last transition. Optional.

Human-readable message indicating details about last transition. Optional.

Shards is a list of explicit shard specifications.

Parts is the number of equal parts to split the keyspace into. If you need shards that are not equal-sized, use custom partitioning instead.

Note that if the number of parts is not a power of 2, the key ranges will only be roughly equal in size.

WARNING: DO NOT change the number of parts in a partitioning after deploying. That’s effectively deleting the old partitioning and adding a new one, which can lead to downtime or data loss. Instead, add an additional partitioning with the desired number of parts, perform a resharding migration, and then remove the old partitioning.

ShardTemplate is the configuration used for each equal-sized shard. If you need shards that don’t all share the same configuration, use custom partitioning instead.

Vttablet is the container image (including version tag) to use for Vitess Tablet instances.

Vtorc is the container image (including version tag) to use for Vitess Orchestrator instances.

Vtbackup is the container image (including version tag) to use for Vitess Backup jobs.

Mysqld specifies the container image to use for mysqld, as well as declaring which MySQL flavor setting in Vitess the image is compatible with. Only one flavor image may be provided at a time. mysqld running alongside each tablet.

MysqldExporter specifies the container image for mysqld-exporter.

KeyRange is the range of keys that this shard serves.

WARNING: DO NOT change the key range of a shard after deploying. That’s effectively deleting the old shard and adding a new one, which can lead to downtime or data loss. Instead, add an additional partitioning with the desired set of shards, perform a resharding migration, and then remove the old partitioning.

(Members of VitessShardTemplate are embedded into this type.)

VitessShardTemplate is the configuration for the shard.

Equal partitioning splits the keyspace into some number of equal parts, assuming that the keyspace IDs are uniformly distributed, for example because they’re generated by a hash vindex.

Custom partitioning lets you explicitly specify the key range of every shard, in case you don’t want them to be divided equally.

ShardNames is a sorted list of shards in this partitioning, in the format Vitess uses for shard names.

ServingWrites is a condition indicating whether all shards in this partitioning are serving writes for their key ranges. Note that False only means not all shards are serving writes; it’s still possible that some shards in this partitioning are serving writes. Check the per-shard status for full details.

DesiredTablets is the number of desired tablets. This is computed from information that’s already available in the spec, but clients should use this value instead of trying to compute shard partitionings on their own.

Tablets is the number of observed tablets. This could be higher or lower than desiredTablets if the state has not yet converged.

ReadyTablets is the number of desired tablets that are Ready.

UpdatedTablets is the number of desired tablets that are up-to-date (have no pending changes).

DesiredShards is the number of desired shards. This is computed from information that’s already available in the spec, but clients should use this value instead of trying to compute shard partitionings on their own.

ReadyShards is the number of desired shards that are Ready.

HasMaster is a condition indicating whether the Vitess topology reflects a master for this shard.

ServingWrites is a condition indicating whether this shard is the one that serves writes for its key range, according to Vitess topology. A shard might be deployed without serving writes if, for example, it is the target of a resharding operation that is still in progress.

DesiredTablets is the number of desired tablets. This is computed from information that’s already available in the spec, but clients should use this value instead of trying to compute shard partitionings on their own.

Tablets is the number of observed tablets. This could be higher or lower than desiredTablets if the state has not yet converged.

ReadyTablets is the number of desired tablets that are Ready.

UpdatedTablets is the number of desired tablets that are up-to-date (have no pending changes).

PendingChanges describes changes to the shard that will be applied the next time a rolling update allows.

Cells is a list of cells in which any tablets for this shard are deployed.

(Members of VitessKeyspaceTemplate are embedded into this type.)

VitessKeyspaceTemplate contains the user-specified parts of VitessKeyspaceSpec. These are the parts that are configurable inside VitessCluster. The rest of the fields below are filled in by the parent controller.

GlobalLockserver are the params to connect to the global lockserver.

Images are not customizable by users at the keyspace level because version skew across the cluster is discouraged except during rolling updates, in which case this field is automatically managed by the VitessCluster controller that owns this VitessKeyspace.

ImagePullPolicies are inherited from the VitessCluster spec.

ImagePullSecrets are inherited from the VitessCluster spec.

ZoneMap is a map from Vitess cell name to zone (failure domain) name for all cells defined in the VitessCluster.

BackupLocations are the backup locations defined in the VitessCluster.

BackupEngine specifies the Vitess backup engine to use, either “builtin” or “xtrabackup”.

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

The generation observed by the controller.

Shards is a summary of the status of all desired shards.

Partitionings is an aggregation of status for all shards in each partitioning.

OrphanedShards is a list of unwanted shards that could not be turned down.

Idle is a condition indicating whether the keyspace can be turned down. If Idle is True, the keyspace is not deployed in any cells, so it should be safe to turn down the keyspace.

ReshardingStatus provides information about an active resharding operation, if any. This field is only present if the ReshardingActive condition is True. If that condition is Unknown, it means the operator was unable to query resharding status from Vitess.

Conditions is a list of all VitessKeyspace specific conditions we want to set and monitor. It’s ok for multiple controllers to add conditions here, and those conditions will be preserved.

Name is the keyspace name as it should be provided to Vitess. Note that this is different from the VitessKeyspace object’s metadata.name, which is generated by the operator.

WARNING: DO NOT change the name of a keyspace that was already deployed. Keyspaces cannot be renamed, so this will be interpreted as an instruction to delete the old keyspace and create a new one.

DatabaseName is the name to use for the underlying, physical MySQL database created to hold data for the keyspace.

This name is mostly hidden from Vitess clients, which should see and use only the keyspace name as a logical database. However, you may want to set this to control the name used by clients that bypass Vitess and connect directly to the underlying MySQL, such as certain DBA tools.

The default, when the field is either left unset or set to empty string, is to add a “vt_” prefix to the keyspace name since that has historically been the default in Vitess itself. However, it’s often preferable to set this to be the same as the keyspace name to reduce confusion.

Default: Add a “vt_” prefix to the keyspace name.

VitessOrchestrator deploys a set of Vitess Orchestrator (vtorc) servers for the Keyspace. It is highly recommended that you set disable_active_reparents=true and enable_semi_sync=false for the vtablets if enabling vtorc. THIS API IS EXPERIMENTAL: NOT TO BE USED IN PRODUCTION.

Partitionings specify how to divide the keyspace up into shards by defining the range of keyspace IDs that each shard contains. For example, you might divide the keyspace into N equal-sized key ranges.

Note that this is distinct from defining how each row maps to a keyspace ID, which is done in the VSchema. Partitioning is purely an operational concern (scaling the infrastructure), while VSchema is an application-level concern (modeling relationships between data). This separation of concerns allows resharding to occur generically at the infrastructure level without any knowledge of the data model.

Each partitioning must define a set of shards that fully covers the space of all possible keyspace IDs; there can be no gaps between ranges. There’s usually only one partitioning present at a time, but during resharding, it’s necessary to launch the destination shards alongside the source shards. When the resharding is complete, the old partitioning can be removed, which will turn down (undeploy) any unneeded shards.

If only some shards are being split or joined during resharding, the shards that aren’t changing must be specified in both partitionings, although the common shards will be shared (only deployed once). If the per-shard configuration differs, the configuration in the latter partitioning (in the order listed in this field) will be used. For this reason, it’s recommended to add new partitionings at the end, and only remove partitionings from the beginning.

This field is required. An unsharded keyspace may be specified as a partitioning into 1 part.

TurndownPolicy specifies what should happen if this keyspace is ever removed from the VitessCluster spec. By default, removing a keyspace entry from the VitessCluster spec will NOT actually turn down the deployed resources, unless it can be verified that the keyspace was previously set to have 0 total desired tablets across all shards.

With this default policy (RequireIdle), before removing the keyspace entry from the spec, you must first edit the keyspace entry to remove all tablet pools from all shards, and wait for that change to roll out. If a keyspace entry is removed too soon, the keyspace resources will remain deployed indefinitely, and the keyspace will be listed in the orphanedKeyspaces field of VitessCluster status.

This is a safety mechanism to prevent accidental edits to the cluster object from having immediate, destructive consequences. If the cluster spec is only ever edited by automation whose edits you trust to be safe, you can set the policy to Immediate to skip these checks.

Default: RequireIdle

Annotations can optionally be used to attach custom annotations to the VitessKeyspace object.

Implementation specifies which Vitess “topo” plugin to use.

Address is the host:port of the lockserver client endpoint.

RootPath is a path prefix for all lockserver data belonging to a given Vitess cluster. Multiple Vitess clusters can share a lockserver as long as they have unique root paths.

ConfigSecret contains the config file (with passwords) for vtorc.

Resources determines the compute resources reserved for each vtorc replica.

ExtraFlags can optionally be used to override default flags set by the operator, or pass additional flags to vtorc. All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

ExtraEnv can optionally be used to override default environment variables set by the operator, or pass additional environment variables.

ExtraVolumes can optionally be used to override default Pod volumes defined by the operator, or provide additional volumes to the Pod. Note that when adding a new volume, you should usually also add a volumeMount to specify where in each container’s filesystem the volume should be mounted.

ExtraVolumeMounts can optionally be used to override default Pod volumeMounts defined by the operator, or specify additional mounts. Typically, these are used to mount volumes defined through extraVolumes.

InitContainers can optionally be used to supply extra init containers that will be run to completion one after another before any app containers are started.

SidecarContainers can optionally be used to supply extra containers that run alongside the main containers.

Affinity allows you to set rules that constrain the scheduling of your vtorc pods. WARNING: These affinity rules will override all default affinities that we set; in turn, we can’t guarantee optimal scheduling of your pods if you choose to set this field.

Annotations can optionally be used to attach custom annotations to Pods created for this component. These will be attached to the underlying Pods that the vtorc Deployment creates.

ExtraLabels can optionally be used to attach custom labels to Pods created for this component. These will be attached to the underlying Pods that the vtorc Deployment creates.

Service can optionally be used to customize the vtorc Service.

Tolerations allow you to schedule pods onto nodes with matching taints.

Available indicates whether the vtctld service has available endpoints.

ServiceName is the name of the Service for this cluster’s vtorc.

EnforceSemiSync means Vitess will configure MySQL to require semi-sync acknowledgement of all transactions while forbidding fallback to asynchronous replication under any circumstance.

Note that this is different from merely enabling semi-sync, which in its default configuration allows fallback to asynchronous replication if no replicas are connected or if they don’t respond after a few seconds. Enforced semi-sync is a mode that prefers master unavailability when durability cannot be ensured, rather than risking the loss of data that was already reported to clients as committed.

WARNING: Do not enable this if the shard has fewer than 3 master-eligible replicas, as that may lead to master unavailability during routine maintenance.

Default: Semi-sync is not enforced.

InitializeMaster specifies whether to choose an initial master for a new or restored shard that has no master yet.

Default: true.

InitializeBackup specifies whether to take an initial placeholder backup as part of preparing tablets to begin replication. This only takes effect if a backup location is defined in the VitessCluster.

Default: true.

RecoverRestartedMaster specifies whether the operator attempts to repair replication when the master MySQL restarts in-place (due to a crash) or its Pod gets deleted and recreated, causing the Pod IP to change.

Default: true.

Status is the status of the condition. Can be True, False, Unknown.

Last time the condition transitioned from one status to another. Optional.

Unique, one-word, PascalCase reason for the condition’s last transition. Optional.

Human-readable message indicating details about last transition. Optional.

(Members of VitessShardTemplate are embedded into this type.)

VitessShardTemplate contains the user-specified parts of VitessShardSpec. These are the parts that are configurable inside VitessCluster. The rest of the fields below are filled in by the parent controller.

Name is the shard name as it’s known to Vitess.

DatabaseName is the name to use for the underlying MySQL database. It is inherited from the parent keyspace, so it can only be configured at the keyspace level.

ZoneMap is a map from Vitess cell name to zone (failure domain) name for all cells defined in the VitessCluster.

Images are not customizable by users at the shard level because version skew across the shard is discouraged except during rolling updates, in which case this field is automatically managed by the VitessKeyspace controller that owns this VitessShard.

ImagePullPolicies are inherited from the VitessCluster spec.

ImagePullSecrets are inherited from the VitessCluster spec.

KeyRange is the range of keyspace IDs served by this shard.

GlobalLockserver are the params to connect to the global lockserver.

VitessOrchestrator is inherited from the parent’s VitessKeyspace.

BackupLocations are the backup locations defined in the VitessCluster.

BackupEngine specifies the Vitess backup engine to use, either “builtin” or “xtrabackup”.

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

The generation observed by the controller.

Tablets is a summary of the status of all desired tablets in the shard.

OrphanedTablets is a list of unwanted tablets that could not be turned down.

Cells is a list of cells in which any tablets for this shard are deployed.

VitessOrchestrator is a summary of the status of the vtorc deployment.

HasMaster is a condition indicating whether the Vitess topology reflects a master for this shard.

HasInitialBackup is a condition indicating whether the initial backup has been seeded for the shard.

ServingWrites is a condition indicating whether this shard is the one that serves writes for its key range, according to Vitess topology. A shard might be deployed without serving writes if, for example, it is the target of a resharding operation that is still in progress.

Idle is a condition indicating whether the shard can be turned down. If Idle is True, the shard is not part of the active shard set (partitioning) for any tablet type in any cell, so it should be safe to turn down the shard.

Conditions is a map of all VitessShard specific conditions we want to set and monitor. It’s ok for multiple controllers to add conditions here, and those conditions will be preserved.

MasterAlias is the tablet alias of the master according to the global shard record. This could be empty either because there is no master, or because the shard record could not be read. Check the HasMaster condition whenever the distinction is important.

BackupLocations reports information about the backups for this shard in each backup location.

LowestPodGeneration is the oldest VitessShard object generation seen across all child Pods. The tablet information in VitessShard status is guaranteed to be at least as up-to-date as this VitessShard generation. Changes made in subsequent generations that affect tablets may not be reflected in status yet.

Cell is the name of the Vitess cell in which to deploy this pool.

Type is the type of tablet contained in this tablet pool.

The allowed types are:

• replica - master-eligible tablets that serve transactional (OLTP) workloads
• rdonly - master-ineligible tablets (can never be promoted to master) that serve batch/analytical (OLAP) workloads
• externalmaster - tablets pointed at an external, read-write MySQL endpoint
• externalreplica - tablets pointed at an external, read-only MySQL endpoint that serve transactional (OLTP) workloads
• externalrdonly - tablets pointed at an external, read-only MySQL endpoint that serve batch/analytical (OLAP) workloads

Replicas is the number of tablets to deploy in this pool. This field is required, although it may be set to 0, which will scale the pool down to 0 tablets.

DataVolumeClaimTemplate configures the PersistentVolumeClaims that will be created for each tablet to store its database files. This field is required for local MySQL, but should be omitted in the case of externally managed MySQL.

IMPORTANT: For a tablet pool in a Kubernetes cluster that spans multiple zones, you should ensure that volumeBindingMode: WaitForFirstConsumer is set on the StorageClass specified in the storageClassName field here.

BackupLocationName is the name of the backup location to use for this tablet pool. It must match the name of one of the backup locations defined in the VitessCluster. Default: Use the backup location whose name is empty.

Vttablet configures the vttablet server within each tablet.

Mysqld configures a local MySQL running inside each tablet Pod. You must specify either Mysqld or ExternalDatastore, but not both.

ExternalDatastore provides information for an externally managed MySQL. You must specify either Mysqld or ExternalDatastore, but not both.

Affinity allows you to set rules that constrain the scheduling of your vttablet pods. Affinity rules will affect all underlying tablets in the specified tablet pool the same way. WARNING: These affinity rules will override all default affinities that we set; in turn, we can’t guarantee optimal scheduling of your pods if you choose to set this field.

Annotations can optionally be used to attach custom annotations to Pods created for this component.

ExtraLabels can optionally be used to attach custom labels to Pods created for this component.

ExtraEnv can optionally be used to override default environment variables set by the operator, or pass additional environment variables. These values are applied to both the vttablet and mysqld containers.

ExtraVolumes can optionally be used to override default Pod volumes defined by the operator, or provide additional volumes to the Pod. Note that when adding a new volume, you should usually also add a volumeMount to specify where in each container’s filesystem the volume should be mounted. These volumes are available to be mounted by both vttablet and mysqld.

ExtraVolumeMounts can optionally be used to override default Pod volumeMounts defined by the operator, or specify additional mounts. Typically, these are used to mount volumes defined through extraVolumes. These values are applied to both the vttablet and mysqld containers.

InitContainers can optionally be used to supply extra init containers that will be run to completion one after another before any app containers are started.

SidecarContainers can optionally be used to supply extra containers that run alongside the main containers.

Tolerations allow you to schedule pods onto nodes with matching taints.

TabletPools specify groups of tablets in a given cell with a certain tablet type and a shared configuration template.

There must be at most one pool in this list for each (cell,type) pair. Each shard must have at least one “replica” pool (in at least one cell) in order to be able to serve.

DatabaseInitScriptSecret specifies the init_db.sql script file to use for this shard. This SQL script file is executed immediately after bootstrapping an empty database to set up initial tables and other MySQL-level entities needed by Vitess.

Replication configures Vitess replication settings for the shard.

Annotations can optionally be used to attach custom annotations to the VitessShard object.

PoolType is the target tablet type for the tablet pool.

Index is the tablet’s index within its tablet pool.

Running indicates whether the vttablet Pod is running.

Ready indicates whether the vttablet Pod is passing health checks, meaning it’s ready to serve queries.

Available indicates whether the vttablet Pod has been consistently Ready for long enough to be considered stable.

DataVolumeBound indicates whether the main PersistentVolumeClaim has been matched up with a PersistentVolume and bound to it.

Type is the observed tablet type as reflected in topology.

PendingChanges describes changes to the tablet Pod that will be applied the next time a rolling update allows.

Resources specify the compute resources to allocate for just the vttablet process (the Vitess query server that sits in front of MySQL). This field is required.

ExtraFlags can optionally be used to override default flags set by the operator, or pass additional flags to vttablet. All entries must be key-value string pairs of the form “flag”: “value”. The flag name should not have any prefix (just “flag”, not “-flag”). To set a boolean flag, set the string value to either “true” or “false”.

Lifecycle can optionally be used to add container lifecycle hooks to vttablet container *kubebuilder:validation:EmbeddedResource