]>
Commit | Line | Data |
---|---|---|
181888fb FG |
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 | |
f67539c2 TL |
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. | |
181888fb FG |
9 | |
10 | **Requirements:** | |
11 | ||
12 | - A running Ceph Luminous (12.2.x) cluster or newer | |
13 | ||
11fdf7f2 | 14 | - Red Hat Enterprise Linux/CentOS 7.5 (or newer); Linux kernel v4.16 (or newer) |
181888fb | 15 | |
11fdf7f2 | 16 | - The ``ceph-iscsi`` package installed on all the iSCSI gateway nodes |
181888fb | 17 | |
f67539c2 | 18 | **Installation:** |
181888fb FG |
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 | ||
9f95a23c | 33 | [iscsigws] |
181888fb FG |
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 | |
9f95a23c | 39 | ``[iscsigws]`` section. |
181888fb | 40 | |
f67539c2 | 41 | **Configuration:** |
181888fb FG |
42 | |
43 | The ``ceph-ansible`` package places a file in the ``/usr/share/ceph-ansible/group_vars/`` | |
9f95a23c TL |
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. | |
181888fb FG |
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 | +--------------------------------------+--------------------------------------+ | |
9f95a23c TL |
76 | | ``api_user`` | The user name for the API. The | |
77 | | | default is `admin`. | | |
181888fb | 78 | +--------------------------------------+--------------------------------------+ |
9f95a23c TL |
79 | | ``api_password`` | The password for using the API. The | |
80 | | | default is `admin`. | | |
181888fb | 81 | +--------------------------------------+--------------------------------------+ |
9f95a23c TL |
82 | | ``api_port`` | The TCP port number for using the | |
83 | | | API. The default is `5000`. | | |
181888fb | 84 | +--------------------------------------+--------------------------------------+ |
9f95a23c TL |
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. | | |
181888fb | 95 | +--------------------------------------+--------------------------------------+ |
181888fb | 96 | |
f67539c2 | 97 | **Deployment:** |
181888fb | 98 | |
20effc67 | 99 | Perform the following steps on the Ansible installer node. |
181888fb FG |
100 | |
101 | #. As ``root``, execute the Ansible playbook: | |
102 | ||
20effc67 | 103 | .. prompt:: bash # |
181888fb | 104 | |
20effc67 TL |
105 | cd /usr/share/ceph-ansible |
106 | ansible-playbook site.yml --limit iscsigws | |
181888fb FG |
107 | |
108 | .. note:: | |
9f95a23c TL |
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. | |
181888fb FG |
114 | |
115 | #. Verify the configuration from an iSCSI gateway node: | |
116 | ||
20effc67 | 117 | .. prompt:: bash # |
181888fb | 118 | |
20effc67 | 119 | gwcli ls |
181888fb FG |
120 | |
121 | .. note:: | |
9f95a23c TL |
122 | See the `Configuring the iSCSI Target using the Command Line Interface`_ |
123 | section to create gateways, LUNs, and clients using the `gwcli` tool. | |
181888fb FG |
124 | |
125 | .. important:: | |
126 | Attempting to use the ``targetcli`` tool to change the configuration will | |
f67539c2 TL |
127 | cause problems including ALUA misconfiguration and path failover |
128 | issues. There is the potential to corrupt data, to have mismatched | |
181888fb | 129 | configuration across iSCSI gateways, and to have mismatched WWN information, |
f67539c2 | 130 | leading to client multipath problems. |
181888fb FG |
131 | |
132 | **Service Management:** | |
133 | ||
11fdf7f2 | 134 | The ``ceph-iscsi`` package installs the configuration management |
9f95a23c TL |
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 | |
181888fb FG |
137 | will restore the Linux IO state. The Ansible playbook disables the |
138 | target service during the deployment. Below are the outcomes of when | |
9f95a23c | 139 | interacting with the ``rbd-target-api`` Systemd service. |
181888fb | 140 | |
20effc67 | 141 | .. prompt:: bash # |
181888fb | 142 | |
20effc67 | 143 | systemctl <start|stop|restart|reload> rbd-target-api |
181888fb FG |
144 | |
145 | - ``reload`` | |
146 | ||
9f95a23c | 147 | A reload request will force ``rbd-target-api`` to reread the |
181888fb FG |
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 | ||
181888fb FG |
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 | ||
20effc67 TL |
189 | .. highlight:: console |
190 | ||
181888fb FG |
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 |