Release of Vitess v23.0.0

Summary

Table of Contents

• Major Changes
  • New default versions
    • Upgrade to MySQL 8.4
• Minor Changes
  • Deprecations
    • Metrics
  • Deletions
    • Metrics
  • New Metrics
    • VTGate
    • VTOrc
  • Topology
    • --consul_auth_static_file requires 1 or more credentials
  • VTOrc
    • Aggregated Discovery Metrics HTTP API removed
    • Dynamic control of EmergencyReparentShard-based recoveries
    • Recovery stats to include keyspace/shard
    • /api/replication-analysis HTTP API deprecation
  • VTTablet
    • API Changes
    • CLI Flags
    • Managed MySQL configuration defaults to caching-sha2-password
    • MySQL timezone environment propagation
    • gRPC tabletmanager client error changes
  • Docker

Major Changes

New default versions

Upgrade to MySQL 8.4

The default major MySQL version used by our vitess/lite:latest image is going from 8.0.40 to 8.4.6.
This change was merged in #18569.

VTGate also advertises MySQL version 8.4.6 by default instead of 8.0.40. If that is not what you are running, you can set the mysql_server_version flag to advertise the desired version.

⚠️ Upgrading to this release with vitess-operator:

If you are using the vitess-operator, considering that we are bumping the MySQL version from 8.0.40 to 8.4.6, you will have to manually upgrade:

1. Add innodb_fast_shutdown=0 to your extra cnf in your YAML file.
2. Apply this file.
3. Wait for all the pods to be healthy.
4. Then change your YAML file to use the new Docker Images (vitess/lite:v23.0.0).
5. Remove innodb_fast_shutdown=0 from your extra cnf in your YAML file.
6. Apply this file.

This is only needed once when going from the latest 8.0.x to 8.4.x. Once you're on 8.4.x, it is possible to upgrade and downgrade between 8.4.x versions without needing to run innodb_fast_shutdown=0.

Minor Changes

Deprecations

Metrics

Deletions

Metrics

New Metrics

VTGate

VTOrc

Topology

--consul_auth_static_file requires 1 or more credentials

The --consul_auth_static_file flag used in several components now requires that 1 or more credentials can be loaded from the provided json file.

VTOrc

Aggregated Discovery Metrics HTTP API removed

VTOrc's undocumented /api/aggregated-discovery-metrics HTTP API endpoint was removed. The list of documented VTOrc APIs can be found here.

We recommend using the standard VTOrc metrics to gather the same metrics. If you find that a metric is missing in standard metrics, please open an issue or PR to address this.

Dynamic control of EmergencyReparentShard-based recoveries

Note: disabling EmergencyReparentShard-based recoveries introduces availability risks; please use with extreme caution! If you rely on this functionality often, for example in automation, this may be signs of an anti-pattern. If so, please open an issue to discuss supporting your use case natively in VTOrc.

The new vtctldclient RPC SetVtorcEmergencyReparent was introduced to allow VTOrc recoveries involving EmergencyReparentShard actions to be disabled on a per-keyspace and/or per-shard basis. Previous to this version, disabling EmergencyReparentShard-based recoveries was only possible globally/per-VTOrc-instance. VTOrc will now consider this keyspace/shard-level setting that is refreshed from the topo on each recovery. The disabled state is determined by first checking if the keyspace, and then the shard state. Removing a keyspace-level override does not remove per-shard overrides.

To provide observability of keyspace/shards with EmergencyReparentShard-based VTOrc recoveries disabled, the EmergencyReparentShardDisabled metric was added. This metric label can be used to create alerting to ensure EmergencyReparentShard-based recoveries are not disabled for an undesired period of time.

Recovery stats to include keyspace/shard

The following recovery-related stats now include labels for keyspaces and shards:

1. FailedRecoveries
2. PendingRecoveries
3. RecoveriesCount
4. SuccessfulRecoveries

Previous to this release, only the recovery "type" was included in labels.

/api/replication-analysis HTTP API deprecation

The /api/replication-analysis HTTP API endpoint is now deprecated and is replaced with /api/detection-analysis, which currently returns the same response format.

VTTablet

API Changes

• Added RestartReplication method to TabletManagerClient interface. This new RPC allows stopping and restarting MySQL replication with semi-sync configuration in a single call, providing a convenient alternative to separate StopReplication and StartReplication calls.

CLI Flags

• skip-user-metrics flag if enabled, replaces the username label with "UserLabelDisabled" to prevent metric explosion in environments with many unique users.

Managed MySQL configuration defaults to caching-sha2-password

The default authentication plugin for MySQL 8.0.26 and later is now caching_sha2_password instead of mysql_native_password. This change is made because mysql_native_password is deprecated and removed in future MySQL versions. mysql_native_password is still enabled for backwards compatibility.

This change specifically affects the replication user. If you have a user configured with an explicit password, it is recommended to make sure to upgrade this user after upgrading to v23 with a statement like the following:

ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password';

In future Vitess versions, the mysql_native_password authentication plugin will be disabled for managed MySQL instances.

MySQL timezone environment propagation

Fixed a bug where environment variables like TZ were not propagated from mysqlctl to the mysqld process.
As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables.
⚠️ Deployments that relied on the old behavior and explicitly set a non-UTC timezone may see changes in how DATETIME values are interpreted. To preserve compatibility, set TZ=UTC explicitly in MySQL pods.

gRPC tabletmanager client error changes

The vttablet gRPC tabletmanager client now returns errors wrapped by the internal go/vt/vterrors package. External automation relying on google-gRPC error codes should now use vterrors.Code(err) to inspect the code of an error, which returns vtrpcpb.Codes defined in the proto/vtrpc.proto protobuf.

Docker

Bullseye went EOL 1 year ago, so starting from v23, we will no longer build or publish images based on debian:bullseye.

Builds will continue for Debian Bookworm, and add the recently released Debian Trixie. v23 explicitly does not change the default Debian tag to Trixie.

The entire changelog for this release can be found here.

The release includes 225 merged Pull Requests.

Thanks to all our contributors: @Arshdeep54, @BenjaminLockhart, @GrahamCampbell, @GuptaManan100, @HenryCaiHaiying, @app/dependabot, @app/vitess-bot, @arthurschreiber, @bantyK, @beingnoble03, @canoriz, @chapsuk, @chrisplim, @corbantek, @davidpiegza, @dbussink, @deepthi, @demmer, @derekperkins, @frouioui, @harshit-gangal, @jdoupe, @jeefy, @leejones, @mattlord, @maxenglander, @mdlayher, @mhamza15, @morgo, @mounicasruthi, @nickvanw, @notfelineit, @rohit-nayak-ps, @rvrangel, @shlomi-noach, @siddharth16396, @stankevich, @stutibiyani, @systay, @timvaillancourt, @twthorn, @vitess-bot, @wukuai, @yoheimuta