ansible-role-iscsi_target

=========================

This role sets up an iSCSI target on a Linux machine using targetcli, which is based on Linux-LIO. It also comes with Python modules to use targetcli for advanced tasks like checking, creating, and deleting.

Tested With:

• Ubuntu 20.04
• Ubuntu 22.04
• Archlinux

For more information about LIO and Targets, check the documentation here.

Requirements

This role does not create any disks, partitions, or logical volumes (LVs). Those need to be set up already on the machine or created by another role, such as githubixx.lvm.

Changelog

See the CHANGELOG

Role Variables

# Define iSCSI target(s) using the "iscsi_targets" variable.
# A simple setup looks like this:
#
# iscsi_targets:
#   - name: "iqn.2021-11.blog.tauceti:{{ ansible_facts['nodename'] }}"
#     disks:
#       - name: lun_node1
#         path: /dev/vdb
#         type: block
#         lunid: 0
#     initiators:
#       - name: iqn.2021-07.blog.tauceti:node1
#         authentication:
#           userid: node1user
#           password: node1pw
#           userid_mutual: node1sharedkey
#           password_mutual: node1sharedsecret
#         mapped_luns:
#           - mapped_lunid: 0
#             lunid: 0
#     portals:
#       - ip: "0.0.0.0"
#
# For more details, check the README.
iscsi_targets: []

Configuration Explanation

The provided configuration will create an iSCSI setup that appears like this when you use the targetcli 'ls' command:

# o- / .................................................................................... [...]
#   o- backstores ......................................................................... [...]
#   | o- block ............................................................. [Storage Objects: 1]
#   | | o- lun_node1 ................................... [/dev/vdb (1.0GiB) write-thru activated]
#   | |   o- alua .............................................................. [ALUA Groups: 1]
#   | |     o- default_tg_pt_gp .................................. [ALUA state: Active/optimized]
#   | o- iscsi ....................................................................... [Targets: 1]
#   | o- iqn.2021-11.blog.tauceti:ubuntu .............................................. [TPGs: 1]
#   |   o- tpg1 .......................................................... [no-gen-acls, no-auth]
#   |     o- acls ..................................................................... [ACLs: 1]
#   |     | o- iqn.2021-07.blog.tauceti:node1 .................................. [Mapped LUNs: 1]
#   |     |   o- mapped_lun0 ........................................ [lun0 block/lun_node1 (rw)]
#   |     o- luns ..................................................................... [LUNs: 1]
#   |     | o- lun0 ............................. [block/lun_node1 (/dev/vdb) (default_tg_pt_gp)]
#   |     o- portals ............................................................... [Portals: 1]
#   |       o- 0.0.0.0:3260 ................................................................ [OK]

• iscsi_targets.name: The name of the iSCSI target appears under the iscsi section in the targetcli output.
• disks: Defines one or more block storage objects.
• initiators: Lists all iSCSI clients that will access the target. Each client needs an entry here.
• mapped_luns: Links logical units to the initiator. Usually matches the LUN ID in iscsi_targets.disks.
• portals: Sets the IP address the iSCSI service listens on. 0.0.0.0 means it listens on all interfaces at port 3260.

Archlinux Specific Settings

#######################################
# Settings only relevant for Archlinux
#######################################

# "targetcli-fb" package is needed to configure iSCSI target. This package is installed from AUR using an AUR helper (like "yay").
# If an AUR helper is installed, set "iscsi_archlinux_aur_helper" to "" to skip installation.
iscsi_archlinux_aur_helper: yay

# Since some operations can't be run as root with AUR helpers, a non-root user is recommended. This user will be created if it doesn't exist.
iscsi_archlinux_aur_helper_user: aur_builder

Dependencies

For Archlinux, it requires the Ansible collection kewlfft.aur to install the AUR helper and the targetcli package from the AUR.

Example Playbook

- hosts: your-host
  become: true
  gather_facts: true
  roles:
    - githubixx.iscsi_target
  vars:
    iscsi_targets:
      - name: "iqn.2021-11.blog.tauceti:{{ ansible_facts['nodename'] }}"
        disks:
          - name: lun_node1
            path: /dev/vdb
            type: block
            lunid: 0
        initiators:
          - name: iqn.2021-07.blog.tauceti:node1
            authentication:
              userid: node1user
              password: node1pw
              userid_mutual: node1sharedkey
              password_mutual: node1sharedsecret
            mapped_luns:
              - mapped_lunid: 0
                lunid: 0
        portals:
          - ip: "0.0.0.0"

Testing

This role includes a small testing setup using Molecule, libvirt (vagrant-libvirt), and QEMU/KVM. For setup instructions, refer to this blog post. The test configuration is available here.

To run the tests, execute:

molecule converge

To verify the setup:

molecule verify

To clean up:

molecule destroy

License

MIT/BSD

Author Information

Original author: Ondrej Famera ansible.targetcli
Additional author: Ricardo Sanchez ansible-role-iscsi_target
Additional author (this version): Tauceti Blog