|
| 1 | +# Release of Vitess v23.0.0 |
| 2 | +## Summary |
| 3 | + |
| 4 | +### Table of Contents |
| 5 | + |
| 6 | +- **[Major Changes](#major-changes)** |
| 7 | + - **[New default versions](#new-default-versions)** |
| 8 | + - [Upgrade to MySQL 8.4](#upgrade-to-mysql-8.4) |
| 9 | +- **[Minor Changes](#minor-changes)** |
| 10 | + - **[Deprecations](#deprecations)** |
| 11 | + - [Metrics](#deprecated-metrics) |
| 12 | + - **[Deletions](#deletions)** |
| 13 | + - [Metrics](#deleted-metrics) |
| 14 | + - **[New Metrics](#new-metrics)** |
| 15 | + - [VTGate](#new-vtgate-metrics) |
| 16 | + - [VTOrc](#new-vtorc-metrics) |
| 17 | + - **[Topology](#minor-changes-topo)** |
| 18 | + - [`--consul_auth_static_file` requires 1 or more credentials](#consul_auth_static_file-check-creds) |
| 19 | + - **[VTOrc](#minor-changes-vtorc)** |
| 20 | + - [Aggregated Discovery Metrics HTTP API removed](#aggregated-discovery-metrics-api-removed) |
| 21 | + - [Dynamic control of `EmergencyReparentShard`-based recoveries](#vtorc-dynamic-ers-disabled) |
| 22 | + - [Recovery stats to include keyspace/shard](#recoveries-stats-keyspace-shard) |
| 23 | + - [`/api/replication-analysis` HTTP API deprecation](#replication-analysis-api-deprecation) |
| 24 | + - **[VTTablet](#minor-changes-vttablet)** |
| 25 | + - [API Changes](#api-changes) |
| 26 | + - [CLI Flags](#flags-vttablet) |
| 27 | + - [Managed MySQL configuration defaults to caching-sha2-password](#mysql-caching-sha2-password) |
| 28 | + - [MySQL timezone environment propagation](#mysql-timezone-env) |
| 29 | + - [gRPC `tabletmanager` client error changes](#grpctmclient-err-changes) |
| 30 | + - **[Docker](#docker)** |
| 31 | + |
| 32 | +## <a id="major-changes"/>Major Changes</a> |
| 33 | + |
| 34 | +### <a id="new-default-versions"/>New default versions</a> |
| 35 | + |
| 36 | +#### <a id="upgrade-to-mysql-8.4"/>Upgrade to MySQL 8.4</a> |
| 37 | + |
| 38 | +The default major MySQL version used by our `vitess/lite:latest` image is going from `8.0.40` to `8.4.6`. |
| 39 | +This change was merged in [#18569](https://github.com/vitessio/vitess/pull/18569). |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +> ⚠️ Upgrading to this release with vitess-operator: |
| 44 | +> |
| 45 | +> 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: |
| 46 | +> |
| 47 | +> 1. Add `innodb_fast_shutdown=0` to your extra cnf in your YAML file. |
| 48 | +> 2. Apply this file. |
| 49 | +> 3. Wait for all the pods to be healthy. |
| 50 | +> 4. Then change your YAML file to use the new Docker Images (`vitess/lite:v23.0.0`). |
| 51 | +> 5. Remove `innodb_fast_shutdown=0` from your extra cnf in your YAML file. |
| 52 | +> 6. Apply this file. |
| 53 | +> |
| 54 | +> 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`. |
| 55 | +
|
| 56 | +## <a id="minor-changes"/>Minor Changes</a> |
| 57 | + |
| 58 | +### <a id="deprecations"/>Deprecations</a> |
| 59 | + |
| 60 | +#### <a id="deprecated-metrics"/>Metrics</a> |
| 61 | + |
| 62 | +| Component | Metric Name | Notes | Deprecation PR | |
| 63 | +|:---------:|:-------------------------:|:--------------------------------------:|:-------------------------------------------------------:| |
| 64 | +| `vtorc` | `DiscoverInstanceTimings` | Replaced by `DiscoveryInstanceTimings` | [#18406](https://github.com/vitessio/vitess/pull/18406) | |
| 65 | + |
| 66 | +### <a id="deletions"/>Deletions</a> |
| 67 | + |
| 68 | +#### <a id="deleted-metrics"/>Metrics</a> |
| 69 | + |
| 70 | +| Component | Metric Name | Was Deprecated In | Deprecation PR | |
| 71 | +|:---------:|:-------------------------:|:-----------------:|:-------------------------------------------------------:| |
| 72 | +| `vtgate` | `QueriesProcessed` | `v22.0.0` | [#17727](https://github.com/vitessio/vitess/pull/17727) | |
| 73 | +| `vtgate` | `QueriesRouted` | `v22.0.0` | [#17727](https://github.com/vitessio/vitess/pull/17727) | |
| 74 | +| `vtgate` | `QueriesProcessedByTable` | `v22.0.0` | [#17727](https://github.com/vitessio/vitess/pull/17727) | |
| 75 | +| `vtgate` | `QueriesRoutedByTable` | `v22.0.0` | [#17727](https://github.com/vitessio/vitess/pull/17727) | |
| 76 | + |
| 77 | +### <a id="new-metrics"/>New Metrics |
| 78 | + |
| 79 | +#### <a id="new-vtgate-metrics"/>VTGate |
| 80 | + |
| 81 | +| Name | Dimensions | Description | PR | |
| 82 | +|:-----------------------:|:---------------:|:-----------------------------------------------------------------------------------:|:-------------------------------------------------------:| |
| 83 | +| `TransactionsProcessed` | `Shard`, `Type` | Counts transactions processed at VTGate by shard distribution and transaction type. | [#18171](https://github.com/vitessio/vitess/pull/18171) | |
| 84 | + |
| 85 | +#### <a id="new-vtorc-metrics"/>VTOrc |
| 86 | + |
| 87 | +| Name | Dimensions | Description | PR | |
| 88 | +|:-------------------:|:---------------------------------------------:|:----------------------------------------------------:|:-------------------------------------------------------:| |
| 89 | +| `SkippedRecoveries` | `RecoveryName`, `Keyspace`, `Shard`, `Reason` | Count of the different skipped recoveries processed. | [#17985](https://github.com/vitessio/vitess/pull/17985) | |
| 90 | + |
| 91 | +### <a id="minor-changes-topo"/>Topology</a> |
| 92 | + |
| 93 | +#### <a id="consul_auth_static_file-check-creds"/>`--consul_auth_static_file` requires 1 or more credentials</a> |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +### <a id="minor-changes-vtorc"/>VTOrc</a> |
| 98 | + |
| 99 | +#### <a id="aggregated-discovery-metrics-api-removed"/>Aggregated Discovery Metrics HTTP API removed</a> |
| 100 | + |
| 101 | +VTOrc's undocumented `/api/aggregated-discovery-metrics` HTTP API endpoint was removed. The list of documented VTOrc APIs can be found [here](https://vitess.io/docs/current/reference/vtorc/ui_api_metrics/#apis). |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +#### <a id="vtorc-dynamic-ers-disabled"/>Dynamic control of `EmergencyReparentShard`-based recoveries</a> |
| 106 | + |
| 107 | +**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.** |
| 108 | + |
| 109 | +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. |
| 110 | + |
| 111 | +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. |
| 112 | + |
| 113 | +#### <a id="recoveries-stats-keyspace-shard">Recovery stats to include keyspace/shard</a> |
| 114 | + |
| 115 | +The following recovery-related stats now include labels for keyspaces and shards: |
| 116 | +1. `FailedRecoveries` |
| 117 | +2. `PendingRecoveries` |
| 118 | +3. `RecoveriesCount` |
| 119 | +4. `SuccessfulRecoveries` |
| 120 | + |
| 121 | +Previous to this release, only the recovery "type" was included in labels. |
| 122 | + |
| 123 | +#### <a id="replication-analysis-api-deprecation"/>`/api/replication-analysis` HTTP API deprecation</a> |
| 124 | + |
| 125 | +The `/api/replication-analysis` HTTP API endpoint is now deprecated and is replaced with `/api/detection-analysis`, which currently returns the same response format. |
| 126 | + |
| 127 | +### <a id="minor-changes-vttablet"/>VTTablet</a> |
| 128 | + |
| 129 | +#### <a id="api-changes"/>API Changes</a> |
| 130 | + |
| 131 | +- 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. |
| 132 | + |
| 133 | +#### <a id="flags-vttablet"/>CLI Flags</a> |
| 134 | + |
| 135 | +- `skip-user-metrics` flag if enabled, replaces the username label with "UserLabelDisabled" to prevent metric explosion in environments with many unique users. |
| 136 | + |
| 137 | +#### <a id="mysql-caching-sha2-password"/>Managed MySQL configuration defaults to caching-sha2-password</a> |
| 138 | + |
| 139 | +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. |
| 140 | + |
| 141 | +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: |
| 142 | + |
| 143 | +```sql |
| 144 | +ALTER USER 'vt_repl'@'%' IDENTIFIED WITH caching_sha2_password BY 'your-existing-password'; |
| 145 | +``` |
| 146 | + |
| 147 | +In future Vitess versions, the `mysql_native_password` authentication plugin will be disabled for managed MySQL instances. |
| 148 | + |
| 149 | +#### <a id="mysql-timezone-env"/>MySQL timezone environment propagation</a> |
| 150 | + |
| 151 | +Fixed a bug where environment variables like `TZ` were not propagated from mysqlctl to the mysqld process. |
| 152 | +As a result, timezone settings from the environment were previously ignored. Now mysqld correctly inherits environment variables. |
| 153 | +⚠️ 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. |
| 154 | + |
| 155 | +#### <a id="grpctmclient-err-changes"/>gRPC `tabletmanager` client error changes</a> |
| 156 | + |
| 157 | +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.Code`s defined in [the `proto/vtrpc.proto` protobuf](https://github.com/vitessio/vitess/blob/main/proto/vtrpc.proto#L60). |
| 158 | + |
| 159 | +### <a id="docker"/>Docker</a> |
| 160 | + |
| 161 | +[Bullseye went EOL 1 year ago](https://www.debian.org/releases/), so starting from v23, we will no longer build or publish images based on debian:bullseye. |
| 162 | + |
| 163 | +Builds will continue for Debian Bookworm, and add the recently released Debian Trixie. v23 explicitly does not change the default Debian tag to Trixie. |
| 164 | + |
| 165 | +------------ |
| 166 | +The entire changelog for this release can be found [here](https://github.com/vitessio/vitess/blob/main/changelog/23.0/23.0.0/changelog.md). |
| 167 | + |
| 168 | +The release includes 225 merged Pull Requests. |
| 169 | + |
| 170 | +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 |
| 171 | + |
0 commit comments