ceph/doc/rbd/iscsi-target-ansible.rst

   1 ==========================================
   2 Configuring the iSCSI Target using Ansible
   3 ==========================================
   4
   5 The Ceph iSCSI gateway is the iSCSI target node and also a Ceph client
   6 node. The Ceph iSCSI gateway can be provisioned on dedicated node
   7 or be colocated on a Ceph Object Store Disk (OSD) node. The following steps will
   8 install and configure the Ceph iSCSI gateway for basic operation.
   9
  10 **Requirements:**
  11
  12 -  A running Ceph Luminous (12.2.x) cluster or newer
  13
  14 -  Red Hat Enterprise Linux/CentOS 7.5 (or newer); Linux kernel v4.16 (or newer)
  15
  16 -  The ``ceph-iscsi`` package installed on all the iSCSI gateway nodes
  17
  18 **Installation:**
  19
  20 #. On the Ansible installer node, which could be either the administration node
  21    or a dedicated deployment node, perform the following steps:
  22
  23    #. As ``root``, install the ``ceph-ansible`` package:
  24
  25       ::
  26
  27           # yum install ceph-ansible
  28
  29    #. Add an entry in ``/etc/ansible/hosts`` file for the gateway group:
  30
  31       ::
  32
  33           [iscsigws]
  34           ceph-igw-1
  35           ceph-igw-2
  36
  37 .. note::
  38   If co-locating the iSCSI gateway with an OSD node, then add the OSD node to the
  39   ``[iscsigws]`` section.
  40
  41 **Configuration:**
  42
  43 The ``ceph-ansible`` package places a file in the ``/usr/share/ceph-ansible/group_vars/``
  44 directory called ``iscsigws.yml.sample``. Create a copy of this sample file named
  45 ``iscsigws.yml``. Review the following Ansible variables and descriptions,
  46 and update accordingly. See the ``iscsigws.yml.sample`` for a full list of
  47 advanced variables.
  48
  49 +--------------------------------------+--------------------------------------+
  50 | Variable                             | Meaning/Purpose                      |
  51 +======================================+======================================+
  52 | ``seed_monitor``                     | Each gateway needs access to the     |
  53 |                                      | ceph cluster for rados and rbd       |
  54 |                                      | calls. This means the iSCSI gateway  |
  55 |                                      | must have an appropriate             |
  56 |                                      | ``/etc/ceph/`` directory defined.    |
  57 |                                      | The ``seed_monitor`` host is used to |
  58 |                                      | populate the iSCSI gateway’s         |
  59 |                                      | ``/etc/ceph/`` directory.            |
  60 +--------------------------------------+--------------------------------------+
  61 | ``cluster_name``                     | Define a custom storage cluster      |
  62 |                                      | name.                                |
  63 +--------------------------------------+--------------------------------------+
  64 | ``gateway_keyring``                  | Define a custom keyring name.        |
  65 +--------------------------------------+--------------------------------------+
  66 | ``deploy_settings``                  | If set to ``true``, then deploy the  |
  67 |                                      | settings when the playbook is ran.   |
  68 +--------------------------------------+--------------------------------------+
  69 | ``perform_system_checks``            | This is a boolean value that checks  |
  70 |                                      | for multipath and lvm configuration  |
  71 |                                      | settings on each gateway. It must be |
  72 |                                      | set to true for at least the first   |
  73 |                                      | run to ensure multipathd and lvm are |
  74 |                                      | configured properly.                 |
  75 +--------------------------------------+--------------------------------------+
  76 | ``api_user``                         | The user name for the API. The       |
  77 |                                      | default is `admin`.                  |
  78 +--------------------------------------+--------------------------------------+
  79 | ``api_password``                     | The password for using the API. The  |
  80 |                                      | default is `admin`.                  |
  81 +--------------------------------------+--------------------------------------+
  82 | ``api_port``                         | The TCP port number for using the    |
  83 |                                      | API. The default is `5000`.          |
  84 +--------------------------------------+--------------------------------------+
  85 | ``api_secure``                       | True if TLS must be used. The        |
  86 |                                      | default is `false`. If true the user |
  87 |                                      | must create the necessary            |
  88 |                                      | certificate and key files. See the   |
  89 |                                      | gwcli man file for details.          |
  90 +--------------------------------------+--------------------------------------+
  91 | ``trusted_ip_list``                  | A list of IPv4 or IPv6 addresses     |
  92 |                                      | who have access to the API. By       |
  93 |                                      | default, only the iSCSI gateway      |
  94 |                                      | nodes have access.                   |
  95 +--------------------------------------+--------------------------------------+
  96
  97 **Deployment:**
  98
  99 Perform the following steps on the Ansible installer node.
 100
 101 #. As ``root``, execute the Ansible playbook:
 102
 103    .. prompt:: bash #
 104
 105       cd /usr/share/ceph-ansible
 106       ansible-playbook site.yml --limit iscsigws
 107
 108    .. note::
 109     The Ansible playbook will handle RPM dependencies, setting up daemons,
 110     and installing gwcli so it can be used to create iSCSI targets and export
 111     RBD images as LUNs. In past versions, ``iscsigws.yml`` could define the
 112     iSCSI target and other objects like clients, images and LUNs, but this is
 113     no longer supported.
 114
 115 #. Verify the configuration from an iSCSI gateway node:
 116
 117    .. prompt:: bash #
 118
 119       gwcli ls
 120
 121    .. note::
 122     See the `Configuring the iSCSI Target using the Command Line Interface`_
 123     section to create gateways, LUNs, and clients using the `gwcli` tool.
 124
 125    .. important::
 126     Attempting to use the ``targetcli`` tool to change the configuration will
 127     cause problems including ALUA misconfiguration and path failover
 128     issues. There is the potential to corrupt data, to have mismatched
 129     configuration across iSCSI gateways, and to have mismatched WWN information,
 130     leading to client multipath problems.
 131
 132 **Service Management:**
 133
 134 The ``ceph-iscsi`` package installs the configuration management
 135 logic and a Systemd service called ``rbd-target-api``. When the Systemd
 136 service is enabled, the ``rbd-target-api`` will start at boot time and
 137 will restore the Linux IO state. The Ansible playbook disables the
 138 target service during the deployment. Below are the outcomes of when
 139 interacting with the ``rbd-target-api`` Systemd service.
 140
 141 .. prompt:: bash #
 142
 143    systemctl <start|stop|restart|reload> rbd-target-api
 144
 145 -  ``reload``
 146
 147    A reload request will force ``rbd-target-api`` to reread the
 148    configuration and apply it to the current running environment. This
 149    is normally not required, since changes are deployed in parallel from
 150    Ansible to all iSCSI gateway nodes
 151
 152 -  ``stop``
 153
 154    A stop request will close the gateway’s portal interfaces, dropping
 155    connections to clients and wipe the current LIO configuration from
 156    the kernel. This returns the iSCSI gateway to a clean state. When
 157    clients are disconnected, active I/O is rescheduled to the other
 158    iSCSI gateways by the client side multipathing layer.
 159
 160 **Removing the Configuration:**
 161
 162 The ``ceph-ansible`` package provides an Ansible playbook to
 163 remove the iSCSI gateway configuration and related RBD images. The
 164 Ansible playbook is ``/usr/share/ceph-ansible/purge_gateways.yml``. When
 165 this Ansible playbook is ran a prompted for the type of purge to
 166 perform:
 167
 168 *lio* :
 169
 170 In this mode the LIO configuration is purged on all iSCSI gateways that
 171 are defined. Disks that were created are left untouched within the Ceph
 172 storage cluster.
 173
 174 *all* :
 175
 176 When ``all`` is chosen, the LIO configuration is removed together with
 177 **all** RBD images that were defined within the iSCSI gateway
 178 environment, other unrelated RBD images will not be removed. Ensure the
 179 correct mode is chosen, this operation will delete data.
 180
 181 .. warning::
 182   A purge operation is destructive action against your iSCSI gateway
 183   environment.
 184
 185 .. warning::
 186   A purge operation will fail, if RBD images have snapshots or clones
 187   and are exported through the Ceph iSCSI gateway.
 188
 189 .. highlight:: console
 190
 191 ::
 192
 193     [root@rh7-iscsi-client ceph-ansible]# ansible-playbook purge_gateways.yml
 194     Which configuration elements should be purged? (all, lio or abort) [abort]: all
 195
 196
 197     PLAY [Confirm removal of the iSCSI gateway configuration] *********************
 198
 199
 200     GATHERING FACTS ***************************************************************
 201     ok: [localhost]
 202
 203
 204     TASK: [Exit playbook if user aborted the purge] *******************************
 205     skipping: [localhost]
 206
 207
 208     TASK: [set_fact ] *************************************************************
 209     ok: [localhost]
 210
 211
 212     PLAY [Removing the gateway configuration] *************************************
 213
 214
 215     GATHERING FACTS ***************************************************************
 216     ok: [ceph-igw-1]
 217     ok: [ceph-igw-2]
 218
 219
 220     TASK: [igw_purge | purging the gateway configuration] *************************
 221     changed: [ceph-igw-1]
 222     changed: [ceph-igw-2]
 223
 224
 225     TASK: [igw_purge | deleting configured rbd devices] ***************************
 226     changed: [ceph-igw-1]
 227     changed: [ceph-igw-2]
 228
 229
 230     PLAY RECAP ********************************************************************
 231     ceph-igw-1                 : ok=3    changed=2    unreachable=0    failed=0
 232     ceph-igw-2                 : ok=3    changed=2    unreachable=0    failed=0
 233     localhost                  : ok=2    changed=0    unreachable=0    failed=0
 234
 235
 236 .. _Configuring the iSCSI Target using the Command Line Interface: ../iscsi-target-cli