ci/ansible/README.md

   1 # opensds-ansible
   2 This is an installation tool for opensds using ansible.
   3
   4 ## 1. How to install an opensds local cluster
   5 This installation document assumes there is a clean Ubuntu 16.04 environment. If golang is already installed in the environment, make sure the following parameters are configured in ```/etc/profile``` and run ``source /etc/profile``:
   6 ```conf
   7 export GOROOT=/usr/local/go
   8 export GOPATH=$HOME/gopath
   9 export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
  10 ```
  11
  12 ### Pre-config (Ubuntu 16.04)
  13 First download some system packages:
  14 ```
  15 sudo apt-get install -y openssh-server git make gcc
  16 ```
  17 Then config ```/etc/ssh/sshd_config``` file and change one line:
  18 ```conf
  19 PermitRootLogin yes
  20 ```
  21 Next generate ssh-token:
  22 ```bash
  23 ssh-keygen -t rsa
  24 ssh-copy-id -i ~/.ssh/id_rsa.pub <ip_address> # IP address of the target machine of the installation
  25 ```
  26
  27 ### Install docker
  28 If use a standalone cinder as backend, you also need to install docker to run cinder service. Please see the [docker installation document](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/) for details.
  29
  30 ### Install ansible tool
  31 ```bash
  32 sudo add-apt-repository ppa:ansible/ansible # This step is needed to upgrade ansible to version 2.4.2 which is required for the ceph backend.
  33 sudo apt-get update
  34 sudo apt-get install ansible
  35 ansible --version # Ansible version 2.4.2 or higher is required for ceph; 2.0.0.2 or higher is needed for other backends.
  36 ```
  37
  38 ### Download opensds source code
  39 ```bash
  40 mkdir -p $HOME/gopath/src/github.com/opensds && cd $HOME/gopath/src/github.com/opensds
  41 git clone https://github.com/opensds/opensds.git -b <specified_branch_name>
  42 cd opensds/contrib/ansible
  43 ```
  44
  45 ### Configure opensds cluster variables:
  46 ##### System environment:
  47 Configure the `workplace` and `container_enabled` in `group_vars/common.yml`:
  48 ```yaml
  49 workplace: /home/your_username # Change this field according to your username. If login as root, configure this parameter to '/root'
  50
  51 container_enabled: <false_or_true>
  52 ```
  53
  54 ##### LVM
  55 If `lvm` is chosen as storage backend, modify `group_vars/osdsdock.yml`:
  56 ```yaml
  57 enabled_backend: lvm # Change it according to the chosen backend. Supported backends include 'lvm', 'ceph', and 'cinder'
  58 pv_device: "your_pv_device_path" # Specify a block device and ensure it exists if lvm is chosen
  59 vg_name: "specified_vg_name" # Specify a name for VG if choosing lvm
  60 ```
  61 Modify ```group_vars/lvm/lvm.yaml```, change pool name to be the same as `vg_name` above:
  62 ```yaml
  63 "vg001" # change pool name to be the same as vg_name
  64 ```
  65 ##### Ceph
  66 If `ceph` is chosen as storage backend, modify `group_vars/osdsdock.yml`:
  67 ```yaml
  68 enabled_backend: ceph # Change it according to the chosen backend. Supported backends include 'lvm', 'ceph', and 'cinder'.
  69 ceph_pool_name: "specified_pool_name" # Specify a name for ceph pool if choosing ceph
  70 ```
  71 Modify ```group_vars/ceph/ceph.yaml```, change pool name to be the same as `ceph_pool_name`:
  72 ```yaml
  73 "rbd" # change pool name to be the same as ceph pool
  74 ```
  75 Configure two files under ```group_vars/ceph```: `all.yml` and `osds.yml`. Here is an example:
  76
  77 ```group_vars/ceph/all.yml```:
  78 ```yml
  79 ceph_origin: repository
  80 ceph_repository: community
  81 ceph_stable_release: luminous # Choose luminous as default version
  82 public_network: "192.168.3.0/24" # Run 'ip -4 address' to check the ip address
  83 cluster_network: "{{ public_network }}"
  84 monitor_interface: eth1 # Change to the network interface on the target machine
  85 ```
  86 ```group_vars/ceph/osds.yml```:
  87 ```yml
  88 devices: # For ceph devices, append one or multiple devices like the example below:
  89     - '/dev/sda' # Ensure this device exists and available if ceph is chosen
  90     - '/dev/sdb' # Ensure this device exists and available if ceph is chosen
  91 osd_scenario: collocated
  92 ```
  93
  94 ##### Cinder
  95 If `cinder` is chosen as storage backend, modify `group_vars/osdsdock.yml`:
  96 ```yaml
  97 enabled_backend: cinder # Change it according to the chosen backend. Supported backends include 'lvm', 'ceph', and 'cinder'
  98
  99 # Use block-box install cinder_standalone if true, see details in:
 100 use_cinder_standalone: true
 101 # If true, you can configure cinder_container_platform,  cinder_image_tag,
 102 # cinder_volume_group.
 103
 104 # Default: debian:stretch, and ubuntu:xenial, centos:7 is also supported.
 105 cinder_container_platform: debian:stretch
 106 # The image tag can be arbitrarily modified, as long as follow the image naming
 107 # conventions, default: debian-cinder
 108 cinder_image_tag: debian-cinder
 109 # The cinder standalone use lvm driver as default driver, therefore `volume_group`
 110 # should be configured, the default is: cinder-volumes. The volume group will be
 111 # removed when use ansible script clean environment.
 112 cinder_volume_group: cinder-volumes
 113 ```
 114
 115 Configure the auth and pool options to access cinder in `group_vars/cinder/cinder.yaml`. Do not need to make additional configure changes if using cinder standalone.
 116
 117 ### Check if the hosts can be reached
 118 ```bash
 119 sudo ansible all -m ping -i local.hosts
 120 ```
 121
 122 ### Run opensds-ansible playbook to start deploy
 123 ```bash
 124 sudo ansible-playbook site.yml -i local.hosts
 125 ```
 126
 127 ## 2. How to test opensds cluster
 128
 129 ### Configure opensds CLI tool
 130 ```bash
 131 sudo cp $GOPATH/src/github.com/opensds/opensds/build/out/bin/osdsctl /usr/local/bin
 132 export OPENSDS_ENDPOINT=http://127.0.0.1:50040
 133 osdsctl pool list # Check if the pool resource is available
 134 ```
 135
 136 ### Create a default profile first.
 137 ```
 138 osdsctl profile create '{"name": "default", "description": "default policy"}'
 139 ```
 140
 141 ### Create a volume.
 142 ```
 143 osdsctl volume create 1 --name=test-001
 144 ```
 145 For cinder, az needs to be specified.
 146 ```
 147 osdsctl volume create 1 --name=test-001 --az nova
 148 ```
 149
 150 ### List all volumes.
 151 ```
 152 osdsctl volume list
 153 ```
 154
 155 ### Delete the volume.
 156 ```
 157 osdsctl volume delete <your_volume_id>
 158 ```
 159
 160
 161 ## 3. How to purge and clean opensds cluster
 162
 163 ### Run opensds-ansible playbook to clean the environment
 164 ```bash
 165 sudo ansible-playbook clean.yml -i local.hosts
 166 ```
 167
 168 ### Run ceph-ansible playbook to clean ceph cluster if ceph is deployed
 169 ```bash
 170 cd /opt/ceph-ansible
 171 sudo ansible-playbook infrastructure-playbooks/purge-cluster.yml -i ceph.hosts
 172 ```
 173
 174 In addition, clean up the logical partition on the physical block device used by ceph, using the ```fdisk``` tool.
 175
 176 ### Remove ceph-ansible source code (optional)
 177 ```bash
 178 cd ..
 179 sudo rm -rf /opt/ceph-ansible
 180 ```