PlanetScaleDB Operator API Reference

This page describes all the available fields of CRD APIs implemented by the operator.

Resource Types

EtcdLockserver

EtcdLockserver runs an etcd cluster for use as a Vitess lockserver. Unlike etcd-operator, it uses static bootstrapping and PVCs, treating members as stateful rather the ephemeral. Bringing back existing members instead of creating new ones means etcd can recover from loss of quorum without data loss, which is important for Vitess because restoring from an etcd backup (resetting the lockserver to a point in the past) would violate the consistency model that Vitess expects of a lockserver.

Field Description
apiVersion
string
planetscale.com/v2
kind
string
EtcdLockserver
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
EtcdLockserverSpec


EtcdLockserverTemplate
EtcdLockserverTemplate

(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
string

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.

status
EtcdLockserverStatus

PlanetScaleCluster

PlanetScaleCluster is the top-level interface for configuring a cluster.

Although the PlanetScaleCluster controller creates various secondary objects like VitessCells, all the user-accessible configuration ultimately lives here. The other objects should be considered read-only representations of subsets of the dynamic cluster status. For example, you can examine a specific VitessCell object to get more details on the status of that cell than are summarized in the PlanetScaleCluster status, but any configuration changes should only be made in the PlanetScaleCluster object.

Field Description
apiVersion
string
planetscale.com/v2
kind
string
PlanetScaleCluster
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
PlanetScaleClusterSpec


image
VitessImageParams

Image defines parameters that will be used to fill in the default image URL template for Vitess containers, including mysqld.

The template is: {registry}/{repository}:{mysqlFlavor}-{version}.

Default: Use the current operator version’s recommended parameters.

images
VitessImages

Images allows overriding individual container image URLs (including tag) that would otherwise be generated based on the parameters in the ‘image’ field. Use the ‘image’ field instead unless you need to override certain containers to different images than the rest for some reason. Default: Generate image URLs based on parameters in the ‘image’ field.

imagePullPolicies
VitessImagePullPolicies

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

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets specifies the image pull secrets to add to all Pods that use the images defined in the ‘images’ field. Default: ps-gcr-credentials

backup
ClusterBackupSpec

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
LockserverSpec

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.

vitessDashboard
VitessDashboardSpec

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

monitoring
MonitoringSpec

Monitoring deploys monitoring infrastructure for the cluster. Default: Don’t deploy monitoring infrastructure.

adminProxy
AdminProxySpec

AdminProxy deploys a proxy for Vitess cluster admins to access Vitess component status pages from outside the Kubernetes cluster.

networkPolicies
NetworkPoliciesSpec

NetworkPolicies specifies various NetworkPolicy for the PlanetScaleCluster

cells
[]VitessCellTemplate

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
[]VitessKeyspaceTemplate

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
map[string]string

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 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
TopoReconcileConfig

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

updateStrategy
VitessClusterUpdateStrategy

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

gatewayService
ServiceOverrides

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
ServiceOverrides

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

lockserverTLS
VitessLockserverTLSParams

LockserverTLS specifies secret sources for the client certs, keys and server ca for vitess components to communicate with a given lockserver over TLS. Note that this applies to both global and local lockserver communication. Optional.

replication
VitessReplicationSpec

Replication configures Vitess replication settings for the cluster. These defaults can be overridden at the per-shard level.

federation
FederationSpec

Federation configures the operator to cooperate with operators running in other Kubernetes clusters to manage a single Vitess cluster that spans multiple Kubernetes clusters.

To enable federation without customization, specify a non-null, empty object (e.g. federation: {}). Only a null or missing value (the default) will disable federation.

WARNING: Migration of an already-deployed PlanetScaleCluster between unfederated and federated is currently NOT supported. Federation must be enabled from the initial deployment of the PSC, even if no remote cells are defined yet. The reverse migration is also not supported.

Default: Assume the whole Vitess cluster lives in one Kubernetes cluster.

status
PlanetScaleClusterStatus

VitessBackup

VitessBackup is a one-way mirror of metadata for a Vitess backup. These objects are created automatically by the VitessBackupStorage controller to provide access to backup metadata from Kubernetes. Each backup found in the storage location will be represented by its own VitessBackup object.

Field Description
apiVersion
string
planetscale.com/v2
kind
string
VitessBackup
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
VitessBackupSpec


status
VitessBackupStatus

ALBIngressSpec

(Appears on: IngressClassSpec)

ALBIngressSpec configures AWS ALB Ingress.

Field Description
backendProtocol
ALBProtocol

BackendProtocol is the protocol used when talking to backend Pods. Default: “HTTP”

scheme
ALBScheme

Scheme is whether the load balancer is internal or internet-facing. Default: “internal”

certificateARNs
[]string

CertificateARNs is a list of ARNs for certificates mananged by AWS Certificate Manager.

loadBalancerAttributes
map[string]string

LoadBalancerAttributes is a set of key-value pairs for ALB attributes.

listenPorts
[]ALBPort

ListenPorts specifies the ports that the ALB will listen on. Default: {HTTP: 80} if CertificateARNs is empty; {HTTPS: 443} otherwise.

targetType
ALBTargetType

TargetType specifies how to route traffic to backends. Default: “instance”

securityGroups
[]string

SecurityGroups specifies security groups to attach to the ALB.

ALBPort

(Appears on: ALBIngressSpec)

ALBPort is an ALB protocol and port number.

Field Description
protocol
ALBProtocol

Protocol is the protocol of the port.

port
int32

Port is the number of the port.

ALBProtocol (string alias)

(Appears on: ALBIngressSpec, ALBPort)

ALBProtocol are the protocols supported by ALB.

ALBScheme (string alias)

(Appears on: ALBIngressSpec)

ALBScheme are the types of load balanacers supported by ALB.

ALBTargetType (string alias)

(Appears on: ALBIngressSpec)

ALBTargetType are the traffic routing methods supported by ALB.

AdminProxyAuth (string alias)

(Appears on: AdminProxySpec)

AdminProxyAuth are the supported options for admin proxy authn/z.

AdminProxySpec

(Appears on: PlanetScaleClusterSpec)

AdminProxySpec configures a proxy for exposing Vitess status pages to admins.

Field Description
image
string

Image is the container image for the admin proxy. Default: Let the operator choose.

imagePullPolicy
Kubernetes core/v1.PullPolicy

ImagePullPolicy specifies if/when to pull a container image.

replicas
int32

Replicas is the number of proxy instances to deploy. Default: Let the operator choose.

resources
Kubernetes core/v1.ResourceRequirements

Resources determines the compute resources reserved for each proxy replica.

auth
AdminProxyAuth

Auth specifies how to authenticate and authorize requests. WARNING: Setting this to “None” is insecure and should only be done when running in a trusted environment. Default: Firebase

authSecret
SecretSource

AuthSecret is a reference to the config Secret for proxy authentication and authorization. This must point to an auth config file if the “auth” field is not “None”.

affinity
Kubernetes core/v1.Affinity

Affinity allows you to set rules that constrain the scheduling of your admin proxy 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
map[string]string

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

initContainers
[]Kubernetes core/v1.Container

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
[]Kubernetes core/v1.Container

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

service
ServiceOverrides

Service can optionally be used to customize the admin-proxy Service.

AdminProxyStatus

(Appears on: PlanetScaleClusterStatus)

AdminProxyStatus is the status of the admin proxy for this cluster.

Field Description
available
Kubernetes core/v1.ConditionStatus

Available indicates whether the admin proxy is deployed and healthy.

serviceName
string

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

AzblobBackupLocation

(Appears on: VitessBackupLocation)

AzblobBackupLocation specifies a backup location in Azure Blob Storage.

Field Description
account
string

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

container
string

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

keyPrefix
string

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
SecretSource

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

ClusterBackupSpec

(Appears on: PlanetScaleClusterSpec)

ClusterBackupSpec configures backups for a cluster.

Field Description
locations
[]VitessBackupLocation

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
VitessBackupEngine

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
VitessBackupSubcontrollerSpec

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

policy
VitessBackupPolicy

Policy specifies rules for automatic creation and deletion of backups. Default: Don’t create or delete backups automatically.

EtcdLockserverSpec

(Appears on: EtcdLockserver)

EtcdLockserverSpec defines the desired state of an EtcdLockserver.

Field Description
EtcdLockserverTemplate
EtcdLockserverTemplate

(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
string

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.

EtcdLockserverStatus

(Appears on: EtcdLockserver, LockserverStatus)

EtcdLockserverStatus defines the observed state of an EtcdLockserver.

Field Description
observedGeneration
int64

The generation observed by the controller.

available
Kubernetes core/v1.ConditionStatus

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

clientServiceName
string

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

EtcdLockserverTemplate

(Appears on: EtcdLockserverSpec, LockserverSpec)

EtcdLockserverTemplate defines the user-configurable settings for an etcd cluster that we deploy (not external), to serve as either a local or global lockserver.

Field Description
image
string

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

imagePullPolicy
Kubernetes core/v1.PullPolicy

ImagePullPolicy specifies if/when to pull a container image.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

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

resources
Kubernetes core/v1.ResourceRequirements

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

dataVolumeClaimTemplate
Kubernetes core/v1.PersistentVolumeClaimSpec

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, you must set a storageClassName here for a StorageClass that’s configured to only provision volumes in the Availability Zone that corresponds to the Vitess cell. Default: Let the operator choose.

extraFlags
map[string]string

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
[]Kubernetes core/v1.EnvVar

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

extraVolumes
[]Kubernetes core/v1.Volume

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
[]Kubernetes core/v1.VolumeMount

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
[]Kubernetes core/v1.Container

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
[]Kubernetes core/v1.Container

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

affinity
Kubernetes core/v1.Affinity

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
map[string]string

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

extraLabels
map[string]string

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

createPDB
bool

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
bool

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
bool

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
[]string

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
int32

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
ServiceOverrides

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

peerService
ServiceOverrides

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

tolerations
[]Kubernetes core/v1.Toleration

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

ExternalDatastore

(Appears on: VitessShardTabletPool)

ExternalDatastore defines information that vttablet needs to connect to an externally managed MySQL.

Field Description
user
string

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
string

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

port
int32

Port specifies the port for the externally managed MySQL endpoint.

database
string

Database is the name of the database.

credentialsSecret
SecretSource

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
SecretSource

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

ExternalVitessClusterUpdateStrategyOptions

(Appears on: VitessClusterUpdateStrategy)

Field Description
allowResourceChanges
[]Kubernetes core/v1.ResourceName

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.

FederationSpec

(Appears on: PlanetScaleClusterSpec)

FederationSpec configures PSC federation.

Field Description
globalServiceDiscovery
GlobalServiceDiscoverySpec

GlobalServiceDiscovery tells the operator how to connect services to each other across Kubernetes clusters.

Note that the operator itself doesn’t implement global service discovery. For certain features to work across Kubernetes clusters, such as deploying etcd, the operator requires that a solution for global service discovery is already present. These settings let you tell the operator what it needs to do to tap into the particular service discovery solution you have.

If your solution doesn’t require the operator to do anything at all, you can turn off the default service discovery assumptions without specifying any of the fields within by specifying a non-null, empty object (e.g. globalServiceDiscovery: {}).

Default: Assume Cilium Cluster Mesh is in use.

globalLockserverInstances
[]GlobalLockserverInstance

GlobalLockserverInstances configures the distribution of instances of the global lockserver cluster. This is required unless the PlanetScaleCluster is configured to connect to an external global lockserver.

If specified, there must be exactly 3 entries. The global lockservice will be available as long as at least 2 of the 3 instances are healthy. This allows the global lockservice to tolerate one whole region in this set becoming unavailable. The availability of regions that do not have global lockserver instances will not impact the availability of the global lockservice, even if those regions do contain other parts of the Vitess cluster (e.g. tablets).

WARNING: Migration of an already-deployed instance to a different region is currently NOT supported. These instances must not be moved after initial deployment of a given PlanetScaleCluster.

Default: Assume an external global lockserver is configured.

regionalLockserver
LockserverSpec

RegionalLockserver specifies either a deployed or external lockserver to be used as the Vitess cell-local topology store for all cells in a given region.

To specify that no per-region lockserver should be used, and that all cells should share the global lockserver (if they don’t have their own per-cell lockserver), specify a non-nil, empty object (e.g. regionalLockserver: {}).

Default: Deploy an etcd cluster as the regional lockserver.

GCEIngressSpec

(Appears on: IngressClassSpec)

GCEIngressSpec configures GCE GCLB Ingress.

Field Description
preSharedCerts
[]string

PreSharedCerts is a list of SSL certificate names stored in GCE.

allowHTTP
bool

AllowHTTP specified whether HTTP is allowed. Default: false

GCSBackupLocation

(Appears on: VitessBackupLocation)

GCSBackupLocation specifies a backup location in Google Cloud Storage.

Field Description
bucket
string

Bucket is the name of the GCS bucket to use.

keyPrefix
string

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
SecretSource

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.

GlobalLockserverInstance

(Appears on: FederationSpec)

GlobalLockserverInstance configures one of a set of federated lockserver instances.

Field Description
ProviderRegion
ProviderRegion

(Members of ProviderRegion are embedded into this type.)

ProviderRegion identifies the region in a given provider to which the operator should deploy this lockserver instance. Required.

clusterDomain
string

ClusterDomain is a DNS zone that can be used instead of the standard “cluster.local” zone to resolve the Pod IP of this lockserver instance from any Kubernetes cluster by requesting a name of the form “{podName}.{headlessServiceName}.{namespace}.svc.{clusterDomain}”.

Note that this requires some form of cross-Kubernetes DNS solution, such as PlanetScale xk-dns.

Example: “aws-uswest1.xk.local”. Required.

GlobalServiceDiscoverySpec

(Appears on: FederationSpec)

GlobalServiceDiscoverySpec configures how the operator creates global services.

Field Description
serviceAnnotations
map[string]string

ServiceAnnotations specifies annotations that should be added to a Kubernetes Service object that is expected to route globally to Pods in any Kubernetes cluster.

GrafanaMonitoringSpec

(Appears on: MonitoringSpec)

GrafanaMonitoringSpec configures a Grafana dashboard for the cluster.

Field Description
image
string

Image is the container image for Grafana. Default: Let the operator choose.

imagePullPolicy
Kubernetes core/v1.PullPolicy

ImagePullPolicy specifies if/when to pull a container image.

replicas
int32

Replicas is the number of Grafana instances to deploy. Default: Let the operator choose.

resources
Kubernetes core/v1.ResourceRequirements

Resources determines the compute resources reserved for each Grafana replica.

affinity
Kubernetes core/v1.Affinity

Affinity allows you to set rules that constrain the scheduling of your Grafana 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
map[string]string

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

service
ServiceOverrides

Service can optionally be used to customize the Grafana Service.

GrafanaMonitoringStatus

(Appears on: MonitoringStatus)

GrafanaMonitoringStatus is a summary of the status of Grafana.

Field Description
available
Kubernetes core/v1.ConditionStatus

Available indicates whether the Grafana dashboard is deployed and healthy.

serviceName
string

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

IngressClassSpec

(Appears on: IngressTemplateSpec)

IngressClassSpec configures implementation-specific Ingress settings.

Field Description
alb
ALBIngressSpec

ALB configures settings for AWS ALB Ingress.

gce
GCEIngressSpec

GCE configures settings for GCE GCLB Ingress.

IngressRuleTemplate

(Appears on: IngressTemplateSpec)

IngressRuleTemplate is a template for creating an IngressRule.

Field Description
host
string

Host is the host for the Ingress rule.

serviceSelector
Kubernetes meta/v1.LabelSelector

ServiceSelector specifies which Services to expose through this rule. The controller will keep the list of backends in the rule updated as this set of Services changes.

servicePort
k8s.io/apimachinery/pkg/util/intstr.IntOrString

ServicePort is the port on each Service to route to.

pathTemplate
string

PathTemplate is a Go text template used to set the path for each Service. Use {{label .Service “key”}} to expand a label from the Service. For example, ‘/{{label .Service “component”}}/’ would expand to ‘/foo/’ if the Service has the label ‘component’ set to the value ‘foo’.

IngressTemplate

IngressTemplate is a template for automatically generating Ingress objects.

Field Description
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
IngressTemplateSpec


backend
Kubernetes extensions/v1beta1.IngressBackend

Backend is an optional default backend if no rules are matched.

tls
[]Kubernetes extensions/v1beta1.IngressTLS

TLS is an optional TLS configuration.

rules
[]IngressRuleTemplate

Rules is a list of templates for generating Ingress rules.

ingressClass
IngressClassSpec

IngressClass configures settings that are specific to a particular Ingress implementation. Only one subfield should be set at a time. Default: Generate a purely implementation-agnostic Ingress.

status
IngressTemplateStatus

IngressTemplateSpec

(Appears on: IngressTemplate)

IngressTemplateSpec defines the desired state of an IngressTemplate.

Field Description
backend
Kubernetes extensions/v1beta1.IngressBackend

Backend is an optional default backend if no rules are matched.

tls
[]Kubernetes extensions/v1beta1.IngressTLS

TLS is an optional TLS configuration.

rules
[]IngressRuleTemplate

Rules is a list of templates for generating Ingress rules.

ingressClass
IngressClassSpec

IngressClass configures settings that are specific to a particular Ingress implementation. Only one subfield should be set at a time. Default: Generate a purely implementation-agnostic Ingress.

IngressTemplateStatus

(Appears on: IngressTemplate)

IngressTemplateStatus defines the observed state of an IngressTemplate.

Field Description
observedGeneration
int64

The generation observed by the controller.

loadBalancer
Kubernetes core/v1.LoadBalancerStatus

LoadBalancer contains the current status of the load-balancer.

paths
int32

Paths is the total number of paths generated from the path template.

LockserverSpec

(Appears on: FederationSpec, PlanetScaleClusterSpec, VitessCellTemplate, VitessClusterSpec)

LockserverSpec specifies either a deployed or external lockserver, which can be either global or local.

Field Description
external
VitessLockserverParams

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
EtcdLockserverTemplate

Etcd deploys our own etcd cluster as a lockserver.

LockserverStatus

(Appears on: PlanetScaleClusterStatus, VitessCellStatus, VitessClusterStatus)

LockserverStatus is the lockserver component of status.

Field Description
etcd
EtcdLockserverStatus

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

MonitoringSpec

(Appears on: PlanetScaleClusterSpec)

MonitoringSpec specifies the type of monitoring infrastructure to deploy.

Field Description
prometheus
PrometheusMonitoringSpec

Prometheus deploys Prometheus monitoring.

grafana
GrafanaMonitoringSpec

Grafana deploys a Grafana dashboard.

MonitoringStatus

(Appears on: PlanetScaleClusterStatus)

MonitoringStatus is a summary of the status of the monitoring infrastructure.

Field Description
prometheus
PrometheusMonitoringStatus

Prometheus is the status of the Prometheus deployment.

grafana
GrafanaMonitoringStatus

Grafana is the status of the Grafana dashboard.

MysqldImage

(Appears on: VitessImages, VitessKeyspaceImages)

MysqldImage specifies the container image to use for mysqld, as well as declaring which MySQL flavor setting in Vitess the image is compatible with.

Field Description
mysql56Compatible
string

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

mysql80Compatible
string

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

mariadbCompatible
string

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

mariadb103Compatible
string

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

MysqldSpec

(Appears on: VitessShardTabletPool)

MysqldSpec configures the local MySQL server within a tablet.

Field Description
resources
Kubernetes core/v1.ResourceRequirements

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

configOverrides
string

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.

NetworkPoliciesSpec

(Appears on: PlanetScaleClusterSpec)

NetworkPoliciesSpec contains various NetworkPolicy definitions

OrphanStatus

(Appears on: PlanetScaleClusterStatus, VitessClusterStatus, VitessKeyspaceStatus, VitessShardStatus)

OrphanStatus indiciates why a secondary object is orphaned.

Field Description
reason
string

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

message
string

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

PlanetScaleClusterSpec

(Appears on: PlanetScaleCluster)

PlanetScaleClusterSpec defines the desired state of PlanetScaleCluster.

Field Description
image
VitessImageParams

Image defines parameters that will be used to fill in the default image URL template for Vitess containers, including mysqld.

The template is: {registry}/{repository}:{mysqlFlavor}-{version}.

Default: Use the current operator version’s recommended parameters.

images
VitessImages

Images allows overriding individual container image URLs (including tag) that would otherwise be generated based on the parameters in the ‘image’ field. Use the ‘image’ field instead unless you need to override certain containers to different images than the rest for some reason. Default: Generate image URLs based on parameters in the ‘image’ field.

imagePullPolicies
VitessImagePullPolicies

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

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets specifies the image pull secrets to add to all Pods that use the images defined in the ‘images’ field. Default: ps-gcr-credentials

backup
ClusterBackupSpec

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
LockserverSpec

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.

vitessDashboard
VitessDashboardSpec

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

monitoring
MonitoringSpec

Monitoring deploys monitoring infrastructure for the cluster. Default: Don’t deploy monitoring infrastructure.

adminProxy
AdminProxySpec

AdminProxy deploys a proxy for Vitess cluster admins to access Vitess component status pages from outside the Kubernetes cluster.

networkPolicies
NetworkPoliciesSpec

NetworkPolicies specifies various NetworkPolicy for the PlanetScaleCluster

cells
[]VitessCellTemplate

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
[]VitessKeyspaceTemplate

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
map[string]string

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 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
TopoReconcileConfig

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

updateStrategy
VitessClusterUpdateStrategy

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

gatewayService
ServiceOverrides

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
ServiceOverrides

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

lockserverTLS
VitessLockserverTLSParams

LockserverTLS specifies secret sources for the client certs, keys and server ca for vitess components to communicate with a given lockserver over TLS. Note that this applies to both global and local lockserver communication. Optional.

replication
VitessReplicationSpec

Replication configures Vitess replication settings for the cluster. These defaults can be overridden at the per-shard level.

federation
FederationSpec

Federation configures the operator to cooperate with operators running in other Kubernetes clusters to manage a single Vitess cluster that spans multiple Kubernetes clusters.

To enable federation without customization, specify a non-null, empty object (e.g. federation: {}). Only a null or missing value (the default) will disable federation.

WARNING: Migration of an already-deployed PlanetScaleCluster between unfederated and federated is currently NOT supported. Federation must be enabled from the initial deployment of the PSC, even if no remote cells are defined yet. The reverse migration is also not supported.

Default: Assume the whole Vitess cluster lives in one Kubernetes cluster.

PlanetScaleClusterStatus

(Appears on: PlanetScaleCluster)

Field Description
observedGeneration
int64

The generation observed by the controller.

globalLockserver
LockserverStatus

GlobalLockserver is the status of the global lockserver.

regionalLockserver
LockserverStatus

RegionalLockserver is the status of the regional lockserver, if any.

gatewayServiceName
string

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

vitessDashboard
VitessDashboardStatus

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

cells
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessClusterCellStatus

Cells is a summary of the status of desired cells.

keyspaces
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessClusterKeyspaceStatus

Keyspaces is a summary of the status of desired keyspaces.

orphanedCells
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

orphanedKeyspaces
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

monitoring
MonitoringStatus

Monitoring is the status of the monitoring infrastructure.

adminProxy
AdminProxyStatus

AdminProxy is the status of the admin proxy.

PrometheusMonitoringSpec

(Appears on: MonitoringSpec)

PrometheusMonitoringSpec configures a Prometheus deployment for the cluster.

Field Description
version
string

Version of Prometheus to be deployed. Default: Let the operator choose.

image
string

Image can optionally be used to override the image URL for Prometheus. Specifying the version is still necessary to ensure the Prometheus Operator knows what version of Prometheus is being configured. Default: Use the prometheus-operator default.

replicas
int32

Replicas is the number of Prometheus instances to deploy. Default: Let the operator choose.

retention
string

Time duration Prometheus shall retain data for. Default is ‘24h’, and must match the regular expression [0-9]+(ms|s|m|h|d|w|y) (milliseconds seconds minutes hours days weeks years).

dataVolumeClaimTemplate
Kubernetes core/v1.PersistentVolumeClaimSpec

PersistentVolumeClaimSpec for Prometheus to store metrics Default: Use an emptyDir volume.

resources
Kubernetes core/v1.ResourceRequirements

Resources determines the compute resources reserved for each Prometheus replica.

affinity
Kubernetes core/v1.Affinity

Affinity allows you to set rules that constrain the scheduling of your Prometheus 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
map[string]string

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

externalLabels
map[string]string

ExternalLabels are Prometheus labels (not Kubernetes labels) to add to any time series or alerts when communicating with external systems (federation, remote storage, Alertmanager).

service
ServiceOverrides

Service can optionally be used to customize the Prometheus Service.

PrometheusMonitoringStatus

(Appears on: MonitoringStatus)

PrometheusMonitoringStatus is a summary of the status of Prometheus.

Field Description
serviceName
string

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

ProviderRegion

(Appears on: GlobalLockserverInstance, VitessShardTemplate)

ProviderRegion identifies a region within a given provider.

Field Description
provider
string

Provider is the name of the cloud provider in which the region lives. This can be any arbitrary value as long as it matches the provider value supplied to the operator instance that should deploy into this region. Example: “aws”. Required.

region
string

Region is the name of a region within the specified provider. This can be any arbitrary value as long as it matches the region value supplied to the operator instance that should deploy into this region. Example: “us-west-1”. Required.

ReshardingStatus

(Appears on: VitessKeyspaceStatus)

ReshardingStatus defines some of the workflow related status information.

Field Description
workflow
string

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

state
WorkflowState

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

sourceShards
[]string

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

targetShards
[]string

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

copyProgress
int

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.

S3BackupLocation

(Appears on: VitessBackupLocation)

S3BackupLocation specifies a backup location in Amazon S3.

Field Description
region
string

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

bucket
string

Bucket is the name of the S3 bucket to use.

endpoint
string

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

keyPrefix
string

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
SecretSource

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.

SecretSource

(Appears on: AdminProxySpec, AzblobBackupLocation, ExternalDatastore, GCSBackupLocation, S3BackupLocation, VitessGatewayStaticAuthentication, VitessGatewayTLSSecureTransport, VitessLockserverTLSParams, VitessShardTemplate)

SecretSource specifies where to find the data for a particular secret value.

Field Description
name
string

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 either the ‘volumeName’ or ‘initContainer’ fields instead.

volumeName
string

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.

initContainer
Kubernetes core/v1.Container

InitContainer specifies an init container to run to fetch secret data from any arbitrary source. This can be used as an alternative to storing secret data in Kubernetes Secret objects.

You should design the command and/or image to place secret data into the ‘/output’ directory of the init container’s filesystem. Make sure the command still works if the destination file already exists (e.g. allow overwriting) since the init container might run more than once on a given Pod. Also make sure to leave the output files with permissions that allow Vitess processes to read them.

The ‘key’ field defines the name of the file within the output directory to load for this particular piece of secret data.

You can use one container image to provide more than one piece of secret data by having the command place multiple files in the output directory. You can then specify that same init container for multiple secret sources but with a different ‘key’ value (file name).

key
string

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.

When ‘initContainer’ is used, this specifies the name of the file to load within the output directory filled by the init container.

ServiceOverrides

(Appears on: AdminProxySpec, EtcdLockserverTemplate, GrafanaMonitoringSpec, PlanetScaleClusterSpec, PrometheusMonitoringSpec, VitessCellGatewaySpec, VitessClusterSpec, VitessDashboardSpec)

ServiceOverrides allows customization of an arbitrary Service object.

Field Description
annotations
map[string]string

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
string

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.

ShardBackupLocationStatus

ShardBackupLocationStatus reports status for the backups of a given shard in a given backup location.

Field Description
name
string

Name is the backup location name.

completeBackups
int32

CompleteBackups is the number of complete backups observed.

incompleteBackups
int32

IncompleteBackups is the number of incomplete backups observed.

latestCompleteBackupTime
Kubernetes meta/v1.Time

LatestCompleteBackupTime is the timestamp of the most recent complete backup.

TopoReconcileConfig

(Appears on: PlanetScaleClusterSpec, VitessCellSpec, VitessClusterSpec, VitessKeyspaceSpec, VitessShardSpec)

TopoReconcileConfig can be used to turn on or off registration or pruning of specific vitess components from topo records. This should only be necessary if you need to override defaults, and shouldn’t be required for the vast majority of use cases.

Field Description
registerCellsAliases
bool

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

registerCells
bool

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

pruneCells
bool

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

pruneKeyspaces
bool

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

pruneSrvKeyspaces
bool

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

pruneShards
bool

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

pruneShardCells
bool

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

pruneTablets
bool

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

VitessBackupEngine (string alias)

(Appears on: ClusterBackupSpec, VitessKeyspaceSpec, VitessShardSpec)

VitessBackupEngine is the backup implementation to use.

VitessBackupLocation

(Appears on: ClusterBackupSpec)

VitessBackupLocation defines a location where Vitess backups can be stored.

Field Description
name
string

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
GCSBackupLocation

GCS specifies a backup location in Google Cloud Storage.

s3
S3BackupLocation

S3 specifies a backup location in Amazon S3.

azblob
AzblobBackupLocation

Azblob specifies a backup location in Azure Blob Storage.

volume
Kubernetes core/v1.VolumeSource

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.

annotations
map[string]string

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

VitessBackupPolicy

(Appears on: ClusterBackupSpec)

VitessBackupPolicy specifies rules for automatic backup management.

Field Description
backupIntervalHours
int32

BackupIntervalHours is the time (in hours) to wait between taking new backups automatically for a given shard in a given storage location. You should make sure to set this interval well below the expiry interval for MySQL binary logs, so your most recent backup is always at a replication position that is still present in the master’s binary logs. Default: 24 hours

minRetentionHours
int32

MinRetentionHours is the minimum time (in hours) to retain each backup. Each backup will be kept until it is at least this old. Default: 72 hours

minRetentionCount
int32

MinRetentionCount is the minimum number of backups to retain for a given shard in a given storage location. Even if a backup is past the MinRetentionHours, it will not be deleted if doing so would take the total number of backups for that shard in that storage location below MinRetentionCount. This must be at least 1 since otherwise the shard might be left without any backup from which to restore. Default: 1

VitessBackupSpec

(Appears on: VitessBackup)

VitessBackupSpec defines the desired state of the backup.

VitessBackupStatus

(Appears on: VitessBackup)

VitessBackupStatus describes the observed state of the backup.

Field Description
startTime
Kubernetes meta/v1.Time

StartTime is the time when the backup started.

finishedTime
Kubernetes meta/v1.Time

FinishedTime is the time when the backup finished.

complete
bool

Complete indicates whether the backup ever completed.

position
string

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
string

Engine is the Vitess backup engine implementation that was used.

storageDirectory
string

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

storageName
string

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.

VitessBackupStorage

VitessBackupStorage represents a storage location for Vitess backups. It provides access to metadata about Vitess backups inside Kubernetes by maintaining a set of VitessBackup objects that represent backups in the given storage location. One VitessBackupStorage represents a storage location defined at the VitessCluster level, so it provides access to metadata about backups stored in that location for any keyspace and any shard in that cluster.

Field Description
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
VitessBackupStorageSpec


location
VitessBackupLocation

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

subcontroller
VitessBackupSubcontrollerSpec

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

status
VitessBackupStorageStatus

VitessBackupStorageSpec

(Appears on: VitessBackupStorage)

VitessBackupStorageSpec defines the desired state of VitessBackupStorage.

Field Description
location
VitessBackupLocation

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

subcontroller
VitessBackupSubcontrollerSpec

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

VitessBackupStorageStatus

(Appears on: VitessBackupStorage)

VitessBackupStorageStatus defines the observed state of VitessBackupStorage.

Field Description
observedGeneration
int64

The generation observed by the controller.

totalBackupCount
int32

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

VitessBackupSubcontrollerSpec

(Appears on: ClusterBackupSpec, VitessBackupStorageSpec)

Field Description
serviceAccountName
string

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.

VitessCell

VitessCell represents a group of Nodes in a given failure domain (Zone), plus Vitess components like the lockserver and gateway that are local to each cell. Together, these cell-local components make it possible for Vitess instances (tablets) to run on those Nodes, and for clients to reach Vitess instances in the cell.

Note that VitessCell does not “own” the VitessKeyspaces deployed in it, just like a Node does not own the Pods deployed on it. In addition, each VitessKeyspace can deploy Vitess instances in multiple VitessCells, just like a Deployment can manage Pods that run on multiple Nodes.

Field Description
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
VitessCellSpec


VitessCellTemplate
VitessCellTemplate

(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
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

allCells
[]string

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

images
VitessCellImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

status
VitessCellStatus

VitessCellGatewaySpec

(Appears on: VitessCellTemplate)

VitessCellGatewaySpec specifies the per-cell deployment parameters for vtgate.

Field Description
replicas
int32

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

resources
Kubernetes core/v1.ResourceRequirements

Resources determines the compute resources reserved for each vtgate replica.

authentication
VitessGatewayAuthentication

Authentication configures how Vitess Gateway authenticates MySQL client connections.

secureTransport
VitessGatewaySecureTransport

SecureTransport configures secure transport connections for vtgate.

extraFlags
map[string]string

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
[]Kubernetes core/v1.EnvVar

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

extraVolumes
[]Kubernetes core/v1.Volume

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
[]Kubernetes core/v1.VolumeMount

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
[]Kubernetes core/v1.Container

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
[]Kubernetes core/v1.Container

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

affinity
Kubernetes core/v1.Affinity

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
map[string]string

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
map[string]string

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
ServiceOverrides

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

tolerations
[]Kubernetes core/v1.Toleration

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

VitessCellGatewayStatus

(Appears on: VitessCellStatus)

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

Field Description
available
Kubernetes core/v1.ConditionStatus

Available indicates whether the vtgate service is fully available.

serviceName
string

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

VitessCellImages

(Appears on: VitessCellSpec)

VitessCellImages specifies container images to use for this cell.

Field Description
vtgate
string

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

VitessCellKeyspaceStatus

(Appears on: VitessCellStatus)

VitessCellKeyspaceStatus summarizes the status of a keyspace deployed in this cell.

VitessCellSpec

(Appears on: VitessCell)

VitessCellSpec defines the desired state of a VitessCell.

Field Description
VitessCellTemplate
VitessCellTemplate

(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
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

allCells
[]string

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

images
VitessCellImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

VitessCellStatus

(Appears on: VitessCell)

VitessCellStatus defines the observed state of VitessCell

Field Description
observedGeneration
int64

The generation observed by the controller.

lockserver
LockserverStatus

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

gateway
VitessCellGatewayStatus

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

keyspaces
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessCellKeyspaceStatus

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
Kubernetes core/v1.ConditionStatus

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.

VitessCellTemplate

(Appears on: PlanetScaleClusterSpec)

VitessCellTemplate contains only the user-specified parts of a VitessCell object.

Field Description
name
string

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
string

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.

region
string

Region is the name of the region that this Vitess Cell should run in. This is optional if all cells are in the same region, but if any cells set a region then every cell must set a region. Example: us-west-1. Optional.

provider
string

Provider is the name of the cloud provider this Vitess Cell should run in. It’s fine to use whatever value you like here, as long as it matches the provider value you supply to the operator instance in charge of this cell. Effectively a provider is just a namespace within which region names live. This is optional if all cells are in the same provider, but if any cells set a provider then every cell must set a provider. Example: aws. Optional.

lockserver
LockserverSpec

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 (if federation is off) or in a shared, per-region lockserver (if federation is on) instead of in its own per-cell lockserver.

gateway
VitessCellGatewaySpec

Gateway configures the Vitess Gateway deployment in this cell.

VitessClusterCellStatus

(Appears on: PlanetScaleClusterStatus, VitessClusterStatus)

VitessClusterCellStatus is the status of a cell within a VitessCluster.

Field Description
pendingChanges
string

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

gatewayAvailable
Kubernetes core/v1.ConditionStatus

GatewayAvailable indicates whether the vtgate service is fully available.

VitessClusterKeyspaceStatus

(Appears on: PlanetScaleClusterStatus, VitessClusterStatus)

VitessClusterKeyspaceStatus is the status of a keyspace within a VitessCluster.

Field Description
pendingChanges
string

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

desiredShards
int32

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
int32

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

readyShards
int32

ReadyShards is the number of desired shards that are Ready.

updatedShards
int32

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

desiredTablets
int32

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
int32

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
int32

ReadyTablets is the number of desired tablets that are Ready.

updatedTablets
int32

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

cells
[]string

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

VitessClusterSpec

VitessClusterSpec defines the desired state of VitessCluster.

Field Description
images
VitessImages

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

imagePullPolicies
VitessImagePullPolicies

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

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

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

backup
ClusterBackupSpec

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
LockserverSpec

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.

vitessDashboard
VitessDashboardSpec

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

cells
[]VitessCellTemplate

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
[]VitessKeyspaceTemplate

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
map[string]string

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 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
TopoReconcileConfig

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

updateStrategy
VitessClusterUpdateStrategy

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

gatewayService
ServiceOverrides

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
ServiceOverrides

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

VitessClusterStatus

VitessClusterStatus defines the observed state of VitessCluster

Field Description
observedGeneration
int64

The generation observed by the controller.

globalLockserver
LockserverStatus

GlobalLockserver is the status of the global lockserver.

gatewayServiceName
string

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

vitessDashboard
VitessDashboardStatus

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

cells
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessClusterCellStatus

Cells is a summary of the status of desired cells.

keyspaces
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessClusterKeyspaceStatus

Keyspaces is a summary of the status of desired keyspaces.

orphanedCells
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

orphanedKeyspaces
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

VitessClusterUpdateStrategy

(Appears on: PlanetScaleClusterSpec, VitessClusterSpec, VitessKeyspaceSpec, VitessShardSpec)

VitessClusterUpdateStrategy indicates the strategy that the operator will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy.

Field Description
type
VitessClusterUpdateStrategyType

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
ExternalVitessClusterUpdateStrategyOptions

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.

VitessClusterUpdateStrategyType (string alias)

(Appears on: VitessClusterUpdateStrategy)

VitessClusterUpdateStrategyType is a string enumeration type that enumerates all possible update strategies for the VitessCluster.

VitessDashboardSpec

(Appears on: PlanetScaleClusterSpec, VitessClusterSpec)

VitessDashboardSpec specifies deployment parameters for vtctld.

Field Description
cells
[]string

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
int32

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

resources
Kubernetes core/v1.ResourceRequirements

Resources determines the compute resources reserved for each vtctld replica.

extraFlags
map[string]string

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
[]Kubernetes core/v1.EnvVar

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

extraVolumes
[]Kubernetes core/v1.Volume

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
[]Kubernetes core/v1.VolumeMount

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
[]Kubernetes core/v1.Container

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
[]Kubernetes core/v1.Container

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

affinity
Kubernetes core/v1.Affinity

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
map[string]string

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
map[string]string

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
ServiceOverrides

Service can optionally be used to customize the vtctld Service.

tolerations
[]Kubernetes core/v1.Toleration

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

VitessDashboardStatus

(Appears on: PlanetScaleClusterStatus, VitessClusterStatus)

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

Field Description
available
Kubernetes core/v1.ConditionStatus

Available indicates whether the vtctld service has available endpoints.

serviceName
string

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

VitessGatewayAuthentication

(Appears on: VitessCellGatewaySpec)

VitessGatewayAuthentication configures authentication for vtgate in this cell.

Field Description
static
VitessGatewayStaticAuthentication

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

VitessGatewaySecureTransport

(Appears on: VitessCellGatewaySpec)

VitessGatewaySecureTransport configures secure transport connections for vtgate.

Field Description
required
bool

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
VitessGatewayTLSSecureTransport

TLS configures vtgate to use TLS encrypted transport.

VitessGatewayStaticAuthentication

(Appears on: VitessGatewayAuthentication)

VitessGatewayStaticAuthentication configures static file authentication for vtgate.

Field Description
secret
SecretSource

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

VitessGatewayTLSSecureTransport

(Appears on: VitessGatewaySecureTransport)

VitessGatewayAuthentication configures authentication for vtgate in this cell.

Field Description
clientCACertSecret
SecretSource

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
SecretSource

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

keySecret
SecretSource

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

VitessImageMysqlFlavor (string alias)

(Appears on: VitessImageParams)

VitessImageParams

(Appears on: PlanetScaleClusterSpec)

VitessImageParams are values used to build the Vitess container image URL.

Field Description
registry
string

Registry is the base registry address. Default: us.gcr.io

repository
string

Repository is the path within the registry to the desired image repository. Default: planetscale-vitess/lite

mysqlFlavor
VitessImageMysqlFlavor

MysqlFlavor is the component of the generated image tag that determines which MySQL flavor/variant is installed in the image alongside Vitess. Default: Use the upstream Vitess project’s default MySQL flavor.

version
string

Version is the component of the generated image tag that determines the version of Vitess installed in the image.

VitessImagePullPolicies

(Appears on: PlanetScaleClusterSpec, VitessCellSpec, VitessClusterSpec, VitessKeyspaceSpec, VitessShardSpec)

VitessImagePullPolicies specifies container image pull policies to use for Vitess components.

Field Description
vtctld
Kubernetes core/v1.PullPolicy

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

vtgate
Kubernetes core/v1.PullPolicy

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

vttablet
Kubernetes core/v1.PullPolicy

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

vtbackup
Kubernetes core/v1.PullPolicy

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

mysqld
Kubernetes core/v1.PullPolicy

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

mysqldExporter
Kubernetes core/v1.PullPolicy

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

VitessImages

(Appears on: PlanetScaleClusterSpec, VitessClusterSpec)

VitessImages specifies container images to use for Vitess components.

Field Description
vtctld
string

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

vtgate
string

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

vttablet
string

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

vtbackup
string

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

mysqld
MysqldImage

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
string

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

VitessKeyRange

(Appears on: VitessKeyspaceKeyRangeShard, VitessShardSpec)

VitessKeyRange specifies a range of keyspace IDs.

Field Description
start
string

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
string

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.

VitessKeyspace

VitessKeyspace represents the deployment of a logical database in Vitess. Each keyspace consists of a number of shards, which then consist of tablets. The tablets belonging to one VitessKeyspace can ultimately be deployed across various VitessCells.

Field Description
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
VitessKeyspaceSpec


VitessKeyspaceTemplate
VitessKeyspaceTemplate

(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
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

images
VitessKeyspaceImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

zoneMap
map[string]string

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

backupLocations
[]VitessBackupLocation

BackupLocations are the backup locations defined in the VitessCluster.

backupEngine
VitessBackupEngine

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

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

updateStrategy
VitessClusterUpdateStrategy

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

status
VitessKeyspaceStatus

VitessKeyspaceCondition

(Appears on: VitessKeyspaceStatus)

VitessKeyspaceCondition contains details for the current condition of this VitessKeyspace.

Field Description
type
VitessKeyspaceConditionType

Type is the type of the condition.

status
Kubernetes core/v1.ConditionStatus

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

lastTransitionTime
Kubernetes meta/v1.Time

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

reason
string

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

message
string

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

VitessKeyspaceConditionType (string alias)

(Appears on: VitessKeyspaceCondition)

VitessKeyspaceConditionType is a valid value for the key of a VitessKeyspaceCondition map where the key is a VitessKeyspaceConditionType and the value is a VitessKeyspaceCondition.

VitessKeyspaceCustomPartitioning

(Appears on: VitessKeyspacePartitioning)

VitessKeyspaceCustomPartitioning lets you explicitly specify the key range of every shard.

Field Description
shards
[]VitessKeyspaceKeyRangeShard

Shards is a list of explicit shard specifications.

VitessKeyspaceEqualPartitioning

(Appears on: VitessKeyspacePartitioning)

VitessKeyspaceEqualPartitioning splits the keyspace into some number of equal parts.

Field Description
parts
int32

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
VitessShardTemplate

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.

VitessKeyspaceImages

(Appears on: VitessKeyspaceSpec, VitessShardSpec)

VitessKeyspaceImages specifies container images to use for this keyspace.

Field Description
vttablet
string

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

vtbackup
string

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

mysqld
MysqldImage

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
string

MysqldExporter specifies the container image for mysqld-exporter.

VitessKeyspaceKeyRangeShard

(Appears on: VitessKeyspaceCustomPartitioning)

VitessKeyspaceKeyRangeShard defines a shard based on a key range.

Field Description
keyRange
VitessKeyRange

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.

VitessShardTemplate
VitessShardTemplate

(Members of VitessShardTemplate are embedded into this type.)

VitessShardTemplate is the configuration for the shard.

VitessKeyspacePartitioning

(Appears on: VitessKeyspaceTemplate)

VitessKeyspacePartitioning defines a set of shards by dividing the keyspace into key ranges. Each field is a different method of dividing the keyspace. Only one field should be set on a given partitioning.

Field Description
equal
VitessKeyspaceEqualPartitioning

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
VitessKeyspaceCustomPartitioning

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

migrateTraffic
VitessKeyspaceTraffic

MigrateTraffic indicates what kind of traffic we should migrate from another partitioning to this partitioning. Only one target partitioning should have MigrateTraffic set at a time. If multiple partitionings have “All” set for MigrateTraffic, the operator will not proceed to switch traffic, and a user will be alerted via the status section of the VitessKeyspace. Default: None

VitessKeyspacePartitioningSpecAnnotations

(Appears on: VitessKeyspaceSpecAnnotations)

VitessKeyspacePartitioningSpecAnnotations defines spec-like fields that we pass down to VitessKeyspace objects through annotations with the specannotations package.

Field Description
MigrateTraffic
VitessKeyspaceTraffic

MigrateTraffic should match the MigrateTraffic flag of the Partitioning.

VitessKeyspacePartitioningStatus

(Appears on: VitessKeyspaceStatus)

VitessKeyspacePartitioningStatus aggregates status for all shards in a given partitioning.

Field Description
shardNames
[]string

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

servingWrites
Kubernetes core/v1.ConditionStatus

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
int32

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
int32

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

readyTablets
int32

ReadyTablets is the number of desired tablets that are Ready.

updatedTablets
int32

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

desiredShards
int32

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
int32

ReadyShards is the number of desired shards that are Ready.

VitessKeyspaceShardStatus

(Appears on: VitessKeyspaceStatus)

VitessKeyspaceShardStatus is the status of a shard within a keyspace.

Field Description
hasMaster
Kubernetes core/v1.ConditionStatus

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

servingWrites
Kubernetes core/v1.ConditionStatus

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
int32

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
int32

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

readyTablets
int32

ReadyTablets is the number of desired tablets that are Ready.

updatedTablets
int32

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

pendingChanges
string

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

cells
[]string

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

VitessKeyspaceSpec

(Appears on: VitessKeyspace)

VitessKeyspaceSpec defines the desired state of a VitessKeyspace.

Field Description
VitessKeyspaceTemplate
VitessKeyspaceTemplate

(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
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

images
VitessKeyspaceImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

zoneMap
map[string]string

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

backupLocations
[]VitessBackupLocation

BackupLocations are the backup locations defined in the VitessCluster.

backupEngine
VitessBackupEngine

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

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

updateStrategy
VitessClusterUpdateStrategy

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

VitessKeyspaceSpecAnnotations

VitessKeyspaceSpecAnnotations defines spec-like fields that we pass down to VitessKeyspace objects through annotations with the specannotations package.

Field Description
Federated
bool

Federated indicates whether we are currently federated and matches the output of the federated() helper method on the PlanetscaleClusterSpec.

Partitionings
[]VitessKeyspacePartitioningSpecAnnotations

Partitionings represents an ordered list of options related to each partitioning, in the same order as the partionings list in the VitessKeyspace template.

VitessKeyspaceStatus

(Appears on: VitessKeyspace)

VitessKeyspaceStatus defines the observed state of a VitessKeyspace.

Field Description
observedGeneration
int64

The generation observed by the controller.

shards
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessKeyspaceShardStatus

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

partitionings
[]VitessKeyspacePartitioningStatus

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

orphanedShards
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

idle
Kubernetes core/v1.ConditionStatus

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.

resharding
ReshardingStatus

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
[]VitessKeyspaceCondition

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.

VitessKeyspaceTemplate

(Appears on: PlanetScaleClusterSpec)

VitessKeyspaceTemplate contains only the user-specified parts of a VitessKeyspace object.

Field Description
name
string

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
string

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.

partitionings
[]VitessKeyspacePartitioning

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
VitessKeyspaceTurndownPolicy

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
map[string]string

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

VitessKeyspaceTraffic (string alias)

(Appears on: VitessKeyspacePartitioning, VitessKeyspacePartitioningSpecAnnotations)

VitessKeyspaceTraffic represents a valid combination of read and write traffic.

VitessKeyspaceTurndownPolicy (string alias)

(Appears on: VitessKeyspaceTemplate)

VitessKeyspaceTurndownPolicy is the policy for turning down a keyspace.

VitessLockserverParams

(Appears on: LockserverSpec, VitessCellSpec, VitessKeyspaceSpec, VitessShardSpec)

VitessLockserverParams contains only the values that Vitess needs to connect to a given lockserver.

Field Description
implementation
string

Implementation specifies which Vitess “topo” plugin to use.

address
string

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

rootPath
string

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.

VitessLockserverTLSParams

(Appears on: PlanetScaleClusterSpec)

VitessLockserverTLSParams contains optional data used to connect to a lockserver that is TLS enabled.

Field Description
clientCertSecret
SecretSource

ClientCertSecret is a secret source for the client cert to use to connect to a TLS enabled lockserver.

clientKeySecret
SecretSource

ClientKeySecret is a secret source for the client key to use to connect to a TLS enabled lockserver.

serverCACertSecret
SecretSource

ServerCACertSecret is a secret source for the CA cert to use to validate the server cert when connecting to a TLS enabled lockserver.

VitessReplicationSpec

(Appears on: PlanetScaleClusterSpec, VitessShardTemplate)

VitessReplicationSpec specifies how Vitess will set up MySQL replication.

Field Description
enforceSemiSync
bool

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.

recoverDeadMaster
bool

RecoverDeadMaster specifies whether you want the operator to automatically handle a failure scenario where the master has completely failed. Complete master failure is detected when the master cannot be reached directly, and none of the replicas in the shard are currently replicating, or able to communicate with the master in any way. It essentially is a quorum where all tablets in a shard agree that the master is dead. In the case of DeadMasterProtection being enabled, we will automatically elect a new master from a healthy replica in the given shard to handle the failure case for you.

WARNING: It is highly recommended that you only run dead master recovery with enforceSemiSync turned on, to prevent the potential loss of committed transactions. If enforceSemiSync is not enabled, a dead master recovery may appear to be no different from the perspective of a client than the experience of true data loss, even in circumstances where data can be manually recovered from the old dead master.

Default: false.

deadMasterThresholdSeconds
int32

DeadMasterThresholdSeconds is the number of seconds for which a master must be consistently detected as dead before a recovery (if enabled) will be attempted. This threshold is important to prevent spurious detection. Decreasing it will improve response time at the risk of causing flapping. Default: 10.

ignoreDeadMasterCell
bool

IgnoreDeadMasterCell specifies whether you want to ignore the master cell entirely when getting a quorum from tablets around whether master is dead.

WARNING: It is highly recommended that you do not set this to true unless you have manually configured semi-sync to operate with cross-cell guarantees.

Default: false

initializeMaster
bool

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

Default: true.

initializeBackup
bool

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
bool

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.

VitessShard

VitessShard represents a group of Vitess instances (tablets) that store a subset of the data in a logical database (keyspace).

The tablets belonging to one VitessShard can ultimately be deployed across various VitessCells. All the tablets in a given shard, across all cells, use MySQL replication to stay eventually consistent with the MySQL master for that shard.

Field Description
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
VitessShardSpec


VitessShardTemplate
VitessShardTemplate

(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
string

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

databaseName
string

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
map[string]string

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

images
VitessKeyspaceImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

keyRange
VitessKeyRange

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

globalLockserver
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

backupLocations
[]VitessBackupLocation

BackupLocations are the backup locations defined in the VitessCluster.

backupEngine
VitessBackupEngine

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

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

updateStrategy
VitessClusterUpdateStrategy

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

status
VitessShardStatus

VitessShardCondition

(Appears on: VitessShardStatus)

VitessShardCondition contains details for the current condition of this VitessShard.

Field Description
status
Kubernetes core/v1.ConditionStatus

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

lastTransitionTime
Kubernetes meta/v1.Time

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

reason
string

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

message
string

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

VitessShardConditionType (string alias)

VitessShardConditionType is a valid value for the key of a VitessShardCondition map where the key is a VitessShardConditionType and the value is a VitessShardCondition.

VitessShardSpec

(Appears on: VitessShard)

VitessShardSpec defines the desired state of a VitessShard.

Field Description
VitessShardTemplate
VitessShardTemplate

(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
string

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

databaseName
string

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
map[string]string

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

images
VitessKeyspaceImages

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
VitessImagePullPolicies

ImagePullPolicies are inherited from the VitessCluster spec.

imagePullSecrets
[]Kubernetes core/v1.LocalObjectReference

ImagePullSecrets are inherited from the VitessCluster spec.

keyRange
VitessKeyRange

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

globalLockserver
VitessLockserverParams

GlobalLockserver are the params to connect to the global lockserver.

backupLocations
[]VitessBackupLocation

BackupLocations are the backup locations defined in the VitessCluster.

backupEngine
VitessBackupEngine

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

extraVitessFlags
map[string]string

ExtraVitessFlags is inherited from the parent’s VitessClusterSpec.

topologyReconciliation
TopoReconcileConfig

TopologyReconciliation is inherited from the parent’s VitessClusterSpec.

updateStrategy
VitessClusterUpdateStrategy

UpdateStrategy is inherited from the parent’s VitessClusterSpec.

VitessShardSpecAnnotations

VitessShardSpecAnnotations is where the definition of all spec annotations we intend to put on the VitessShard object lives. Turning these into a map[string]string for placement into annotation, and translation back out of annotations should happen via the specannotations package.

Field Description
RecoverDeadMaster
bool

RecoverDeadMaster indicates whether we recover from dead master. This matches the RecoverDeadMaster field in the ReplicationSpec.

Federated
bool

Federated indicates whether we are currently federated and matches the output of the federated() helper method on the PlanetscaleClusterSpec.

DeadMasterThresholdSeconds
int32

DeadMasterThresholdSeconds indicates the maximum acceptable time that a dead master state may persist for before we attempt recovery. This matches the field in the ReplicationSpec.

IgnoreDeadMasterCell
bool

IgnoreDeadMasterCell indicates that we should ignore the master’s cell when getting a quorum to determine if master is dead. This matches the IgnoreDeadMasterCell field in the ReplicationSpec.

VitessShardStatus

(Appears on: VitessShard)

VitessShardStatus defines the observed state of a VitessShard.

Field Description
observedGeneration
int64

The generation observed by the controller.

tablets
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessTabletStatus

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

orphanedTablets
map[string]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.OrphanStatus

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

cells
[]string

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

hasMaster
Kubernetes core/v1.ConditionStatus

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

hasInitialBackup
Kubernetes core/v1.ConditionStatus

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

servingWrites
Kubernetes core/v1.ConditionStatus

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
Kubernetes core/v1.ConditionStatus

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
map[planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessShardConditionType]planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.VitessShardCondition

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
string

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
[]*planetscale.dev/vitess-operator/pkg/apis/planetscale/v2.ShardBackupLocationStatus

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

lowestPodGeneration
int64

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.

VitessShardTabletPool

(Appears on: VitessShardTemplate)

VitessShardTabletPool defines a pool of tablets with a similar purpose.

Field Description
cell
string

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

type
VitessTabletPoolType

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
int32

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
Kubernetes core/v1.PersistentVolumeClaimSpec

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: If your Kubernetes cluster is multi-zone, you must set a storageClassName here for a StorageClass that’s configured to only provision volumes in the same zone as this tablet pool.

backupLocationName
string

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
VttabletSpec

Vttablet configures the vttablet server within each tablet.

mysqld
MysqldSpec

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

externalDatastore
ExternalDatastore

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

affinity
Kubernetes core/v1.Affinity

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
map[string]string

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

extraLabels
map[string]string

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

extraEnv
[]Kubernetes core/v1.EnvVar

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
[]Kubernetes core/v1.Volume

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
[]Kubernetes core/v1.VolumeMount

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
[]Kubernetes core/v1.Container

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
[]Kubernetes core/v1.Container

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

tolerations
[]Kubernetes core/v1.Toleration

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

VitessShardTemplate

(Appears on: VitessKeyspaceEqualPartitioning, VitessKeyspaceKeyRangeShard)

VitessShardTemplate contains only the user-specified parts of a VitessShard object.

Field Description
tabletPools
[]VitessShardTabletPool

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
SecretSource

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
VitessReplicationSpec

Replication configures Vitess replication settings for the shard.

annotations
map[string]string

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

preferredMasterRegions
[]ProviderRegion

PreferredMasterRegions are the regions in which the operator will prefer to elect a master when possible. The first item in the list will be most preferred, the second will be the next most preferred, and so on. Be sure to define a replica pool in at least one cell within each region listed here.

Default: Use the order of the tablet pools list as the preference order.

VitessTabletPoolType (string alias)

(Appears on: VitessShardTabletPool)

VitessTabletPoolType represents the tablet types for which it makes sense to deploy a dedicated pool. Tablet types that indicate temporary or transient states are not valid pool types.

VitessTabletStatus

(Appears on: VitessShardStatus)

VitessTabletStatus is the status of one tablet in a shard.

Field Description
poolType
string

PoolType is the target tablet type for the tablet pool.

index
int32

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

running
Kubernetes core/v1.ConditionStatus

Running indicates whether the vttablet Pod is running.

ready
Kubernetes core/v1.ConditionStatus

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

available
Kubernetes core/v1.ConditionStatus

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

dataVolumeBound
Kubernetes core/v1.ConditionStatus

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

type
string

Type is the observed tablet type as reflected in topology.

pendingChanges
string

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

VttabletSpec

(Appears on: VitessShardTabletPool)

VttabletSpec configures the vttablet server within a tablet.

Field Description
resources
Kubernetes core/v1.ResourceRequirements

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
map[string]string

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”.

WorkflowState (string alias)

(Appears on: ReshardingStatus)

WorkflowState represents the current state for the given Workflow.


Generated with gen-crd-api-reference-docs.