installers/charm/mongodb-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 Mongo for Juju CAAS
  24
  25 ## Actions
  26
  27 ### Backup
  28
  29 Execute the following steps to do a backup.
  30
  31 ```bash
  32 $ juju run-action mongodb-k8s/0 backup --wait
  33 unit-mongodb-k8s-0:
  34   UnitId: mongodb-k8s/0
  35   id: "7"
  36   results:
  37     Stderr: "2020-02-26T14:13:56.448+0000\twriting admin.system.version to archive
  38       '/data/backup.archive'\n2020-02-26T14:13:56.451+0000\tdone dumping admin.system.version
  39       (1 document)\n"
  40     copy:
  41       cmd: kubectl cp mongo-ha/mongodb-k8s-0:/data/backup.archive backup.archive
  42     restore:
  43       cmd: kubectl cp backup.archive mongo-ha/mongodb-k8s-0:/data/backup.archive
  44       juju: juju action mongodb-k8s/0 restore --wait
  45   status: completed
  46   timing:
  47     completed: 2020-02-26 14:13:57 +0000 UTC
  48     enqueued: 2020-02-26 14:13:55 +0000 UTC
  49     started: 2020-02-26 14:13:56 +0000 UTC
  50 $ kubectl cp mongo-ha/mongodb-k8s-0:/data/backup.archive backup.archive
  51 ```
  52
  53 > 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.
  54
  55 ### Restore
  56
  57 When the backup function is executed, you will see the commands you need to execute for restoring from a backup.
  58
  59 ```bash
  60 $ kubectl cp backup.archive mongo-ha/mongodb-k8s-0:/data/backup.archive
  61 Defaulting container name to mongodb-k8s.
  62 $ juju run-action mongodb-k8s/0 restore --wait
  63 unit-mongodb-k8s-0:
  64   UnitId: mongodb-k8s/0
  65   id: "8"
  66   results:
  67     Stderr: "2020-02-26T14:17:00.300+0000\tpreparing collections to restore from\n2020-02-26T14:17:00.312+0000\t0
  68       document(s) restored successfully. 0 document(s) failed to restore.\n"
  69   status: completed
  70   timing:
  71     completed: 2020-02-26 14:17:01 +0000 UTC
  72     enqueued: 2020-02-26 14:16:57 +0000 UTC
  73     started: 2020-02-26 14:17:00 +0000 UTC
  74 ```
  75
  76 ### Remove backup
  77
  78 When a backup is made, it is stored in the unit. To easily remove the backup, execute this action:
  79
  80 ```bash
  81 $ juju run-action mongodb-k8s/0 remove-backup --wait
  82 unit-mongodb-k8s-0:
  83   UnitId: mongodb-k8s/0
  84   id: "4"
  85   results:
  86     Stdout: |
  87       Backup successfully removed!
  88   status: completed
  89   timing:
  90     completed: 2020-02-26 16:31:11 +0000 UTC
  91     enqueued: 2020-02-26 16:31:08 +0000 UTC
  92     started: 2020-02-26 16:31:10 +0000 UTC
  93 ```
  94
  95 ### Is primary?
  96
  97 To check if the unit is primary:
  98
  99 ```bash
 100 $ juju run-action mongodb-k8s/0 is-primary --wait
 101 unit-mongodb-k8s-0:
 102   UnitId: mongodb-k8s/0
 103   id: "5"
 104   results:
 105     unit:
 106       ip: 10.1.31.92
 107       primary: "true"
 108   status: completed
 109   timing:
 110     completed: 2020-02-26 16:32:10 +0000 UTC
 111     enqueued: 2020-02-26 16:32:08 +0000 UTC
 112     started: 2020-02-26 16:32:09 +0000 UTC
 113 $ juju run-action mongodb-k8s/1 is-primary --wait
 114 unit-mongodb-k8s-1:
 115   UnitId: mongodb-k8s/1
 116   id: "6"
 117   results:
 118     unit:
 119       ip: 10.1.31.93
 120       primary: "false"
 121   status: completed
 122   timing:
 123     completed: 2020-02-26 16:32:34 +0000 UTC
 124     enqueued: 2020-02-26 16:32:32 +0000 UTC
 125     started: 2020-02-26 16:32:33 +0000 UTC
 126 ```
 127
 128 ## Backup remotely
 129
 130 If we want to perform a backup remotely, follow the next steps:
 131
 132 ```bash
 133 $ sudo apt install mongo-tools-y
 134 $ juju status mongodb-k8s
 135 Model     Controller          Cloud/Region        Version  SLA          Timestamp
 136 mongo-ha  microk8s-localhost  microk8s/localhost  2.7.2    unsupported  16:26:02+01:00
 137
 138 App          Version       Status  Scale  Charm        Store  Rev  OS          Address        Notes
 139 mongodb-k8s  mongo:latest  active      2  mongodb-k8s  local    0  kubernetes  10.152.183.90
 140
 141 Unit            Workload  Agent  Address     Ports      Message
 142 mongodb-k8s/0*  active    idle   10.1.31.75  27017/TCP  ready
 143 mongodb-k8s/1   active    idle   10.1.31.76  27017/TCP  ready
 144 $ mongodump --host 10.152.183.90 --port 27017 --gzip --archive=backup.archive --forceTableScan
 145 2020-02-26T16:41:23.777+0100    writing admin.system.version to archive 'backup.archive'
 146 2020-02-26T16:41:23.779+0100    done dumping admin.system.version (1 document)
 147 $ mongorestore --host 10.152.183.90 --port 27017 --gzip --archive=backup.archive
 148 ```
 149
 150 ## Testing
 151
 152 The tests of this charm are done using tox and Zaza.
 153
 154 ### Prepare environment
 155
 156 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:
 157
 158 ```bash
 159 sudo apt install tox -y
 160 sudo snap install microk8s --classic
 161 sudo snap install juju
 162
 163 microk8s.status --wait-ready
 164 microk8s.enable storage dashboard dns
 165
 166 juju bootstrap microk8s k8s-cloud
 167 ```
 168
 169 ### Test charm with Tox
 170
 171 ```bash
 172 tox -e black    # Check syntax
 173 tox -e build    # Build the charm
 174 tox -e func     # Test charm
 175 ```