installers/charm/mariadb-k8s/README.md

   1 <!-- Copyright 2021 Canonical Ltd.
   2
   3 Licensed under the Apache License, Version 2.0 (the "License"); you may
   4 not use this file except in compliance with the License. You may obtain
   5 a copy of the License at
   6
   7         http://www.apache.org/licenses/LICENSE-2.0
   8
   9 Unless required by applicable law or agreed to in writing, software
  10 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 License for the specific language governing permissions and limitations
  13 under the License.
  14
  15 For those usages not covered by the Apache License, Version 2.0 please
  16 contact: legal@canonical.com
  17
  18 To get in touch with the maintainers, please contact:
  19 osm-charmers@lists.launchpad.net -->
  20
  21 # Overview
  22
  23 mysql for Kubernetes
  24
  25 # Usage
  26
  27 You must specify key configuration attributes when deploying,
  28 or else arbitary defaults will be used. The attributes which
  29 should be set are:
  30 - user
  31 - password
  32 - database
  33 - root_password
  34
  35 eg
  36
  37 $ juju deploy mysql \
  38 &nbsp;&nbsp;&nbsp;&nbsp;--config user=fred \
  39 &nbsp;&nbsp;&nbsp;&nbsp;--config password=secret \
  40 &nbsp;&nbsp;&nbsp;&nbsp;--config database=test \
  41 &nbsp;&nbsp;&nbsp;&nbsp;--config root_password=admin
  42
  43 These values may also be in a config.yaml file, eg
  44
  45 $ juju deploy mysql --config config.yaml
  46
  47
  48 ## Actions
  49
  50 ### Backup
  51
  52 Execute the following steps to do a backup.
  53
  54 ```bash
  55 $ juju run-action mariadb-k8s/0 backup --wait
  56 unit-mariadb-k8s-0:
  57   UnitId: mariadb-k8s/0
  58   id: "1"
  59   results:
  60     copy:
  61       cmd: kubectl cp zaza-9769f2bf245e/mariadb-k8s-0:/var/lib/mysql/backup.sql.gz
  62         backup.sql.gz
  63     restore:
  64       cmd: kubectl cp backup.sql.gz zaza-9769f2bf245e/mariadb-k8s-0:/var/lib/mysql/backup.sql.gz
  65       juju: juju run-action mariadb-k8s/0 restore --wait
  66   status: completed
  67   timing:
  68     completed: 2020-02-27 14:16:09 +0000 UTC
  69     enqueued: 2020-02-27 14:16:08 +0000 UTC
  70     started: 2020-02-27 14:16:09 +0000 UTC
  71 $ kubectl cp zaza-9769f2bf245e/mariadb-k8s-0:/var/lib/mysql/backup.sql.gz backup.sql.gz
  72 ```
  73
  74 > Additional note: You can add `--string-args target=PRIMARY|SECONDARY` if you want this action to be run in a specific mongo unit. If `SECONDARY` is set, but the mongo unit isn't the `SECONDARY`, the action will fail.
  75
  76 ### Restore
  77
  78 When the backup function is executed, you will see the commands you need to execute for restoring from a backup.
  79
  80 ```bash
  81 $ kubectl cp backup.sql.gz zaza-9769f2bf245e/mariadb-k8s-0:/var/lib/mysql/backup.sql.gz
  82 $ juju run-action mariadb-k8s/0 restore --wait
  83 unit-mariadb-k8s-0:
  84   UnitId: mariadb-k8s/0
  85   id: "2"
  86   results:
  87     message: Backup restored successfully
  88   status: completed
  89   timing:
  90     completed: 2020-02-27 14:18:17 +0000 UTC
  91     enqueued: 2020-02-27 14:18:07 +0000 UTC
  92     started: 2020-02-27 14:18:11 +0000 UTC
  93 ```
  94
  95 ### Remove backup
  96
  97 When a backup is made, it is stored in the unit. To easily remove the backup, execute this action:
  98
  99 ```bash
 100 $ juju run-action mariadb-k8s/0 remove-backup --wait
 101 unit-mariadb-k8s-0:
 102   UnitId: mariadb-k8s/0
 103   id: "3"
 104   results:
 105     Stdout: |
 106       Backup successfully removed!
 107   status: completed
 108   timing:
 109     completed: 2020-02-27 14:18:41 +0000 UTC
 110     enqueued: 2020-02-27 14:18:36 +0000 UTC
 111     started: 2020-02-27 14:18:41 +0000 UTC
 112 ```
 113
 114 ## Backup remotely
 115
 116 If we want to perform a backup remotely, follow the next steps:
 117
 118 ```bash
 119 $ sudo apt install mariadb-client-10.1 -y
 120 $ juju status mariadb-k8s
 121 Model              Controller          Cloud/Region        Version  SLA          Timestamp
 122 zaza-9769f2bf245e  microk8s-localhost  microk8s/localhost  2.7.2    unsupported  15:20:42+01:00
 123
 124 App            Version             Status  Scale  Charm        Store  Rev  OS          Address         Notes
 125 mariadb-k8s    rocks.canonical...  active  2      mariadb-k8s  local  0    kubernetes  10.152.183.109
 126
 127 Unit            Workload  Agent  Address      Ports                                Message
 128 mariadb-k8s/0*  active    idle   10.1.31.185  3306/TCP,4444/TCP,4567/TCP,4568/TCP  ready
 129 mariadb-k8s/1   active    idle   10.1.31.186  3306/TCP,4444/TCP,4567/TCP,4568/TCP  ready
 130 $ mysqldump -uroot -posm4u --single-transaction \
 131                            --databases database \
 132                            --host 10.152.183.109 \
 133                            --port 3306 | gzip > backup.sql.gz
 134 $ gunzip -c backup.sql.gz | mysql -uroot -posm4u --host 10.152.183.109 --port 3306
 135 ```
 136
 137 > Note: The remote backups should be done for each database. If `--all-databases` is step, when restoring from a database, you will see this error: `ERROR 1556 (HY000) at line 825: You can't use locks with log tables`
 138
 139 ## Testing
 140
 141 The tests of this charm are done using tox and Zaza.
 142
 143 ### Prepare environment
 144
 145 The machine in which the tests are run needs access to a juju k8s controller. The easiest way to approach this is by executing the following commands:
 146
 147 ```bash
 148 sudo apt install tox -y
 149 sudo snap install microk8s --classic
 150 sudo snap install juju
 151
 152 microk8s.status --wait-ready
 153 microk8s.enable storage dns
 154
 155 juju bootstrap microk8s k8s-cloud
 156 ```
 157
 158 ### Test charm with Tox
 159
 160 ```bash
 161 tox -e black    # Check syntax
 162 tox -e build    # Build the charm
 163 tox -e func     # Test charm
 164 ```