From 6243ba4bf731f7269e3a5ca83ce48c2fb4b70dbc Mon Sep 17 00:00:00 2001 From: Andrew Pryde Date: Wed, 4 Jul 2018 11:15:56 +0100 Subject: [PATCH] Add v0.1.x upgrade documentation --- docs/0.1-upgrade.md | 59 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/0.1-upgrade.md diff --git a/docs/0.1-upgrade.md b/docs/0.1-upgrade.md new file mode 100644 index 000000000..1c5c8f3d3 --- /dev/null +++ b/docs/0.1-upgrade.md @@ -0,0 +1,59 @@ +# v0.1.* Upgrade + +The v0.1.* release series is the *only* release series of the MySQL Operator +which supports MySQL 5.7. InnoDB Group replication and associated tooling has +been dramatically improved with the GA release of MySQL 8 (8.0.11). As a result +from the v0.2.0 MySQL Operator release onwards MySQL 8.0.11 is the __minimum +supported version__. + +Due to the complexities of the upgrade path between MySQL 5.7 and MySQL 8 we +aren't implementing an upgrade path between the v0.1.* and v0.2.* MySQL Operator +release series. + +Instead users need to: + + 1) Backup all MySQL Clusters deployed by the MySQL Operator. NOTE: If you + choose to use the inbuilt backup functionality of the MySQL Operator for + this you will need to ensure you save the associated MySQLBackup resources + locally, update them in line with the v0.2.0 API changes, and the recreate + them after installing v0.2.0. + 3) Delete the MySQL Operator release + + ```console + $ helm delete mysql-operator + ``` + NOTE: You may have named the installed MySQL Operator release something + different during installation (see `helm list`). + 4) Follow the installation instructions to install v0.2.0 of the MySQL + Operator. + 5) Create replacement MySQL Clusters using the updated API and restore the + backups created in step #1. + +## Other Breaking Changes + +Additionally, we have taken this opportunity to make a number of breaking +changes to the MySQL Operator API to improve its usability. + +### API Version Downgrade + +We have downgraded the API Version from `v1` to `v1alpha1` to enable future +iteration on the API design (taking advantage of the fact that [Custom Resource +Definitions can now define multiple versions][1]) and to better reflect the +stability of the MySQL Operator API. + +### Resource Kinds Renamed + +Previously the MySQL Operator Custom Resource Kinds were prefixed with MySQL +(e.g. `MySQLCluster`). This prefix has been removed, however, the prefix has +been maintained in the singular/plural names used when interacting via +`kubectl` (e.g. `kubectl get mysqlclusters`). + +### API changes + +Numerous fields on all MySQL Operator Custom Resources have been renamed and +some field types changed. Please review [`pkg/apis/mysql/v1alpha1/types.go`][2] +as the definitive source of truth and see the updated [`examples/`][3]. + +[1]: https://kubernetes.io/blog/2018/06/27/kubernetes-1.11-release-announcement/#custom-resource-definitions-can-now-define-multiple-versions +[2]: https://github.com/oracle/mysql-operator/blob/master/pkg/apis/mysql/v1alpha1/types.go +[3]: https://github.com/oracle/mysql-operator/tree/master/examples