iscsid / tgtd¶
This page is the starting point for the iscsi role: the containers iscsid and tgtd, on the compute, control and
storage nodes of the example inventory (inventory/multinode:305-311), selected by the tag iscsi. Its play runs only
on hosts where enable_iscsid is true (site.yml:439-452, pattern &enable_iscsid_True at :444), and in 2024.1
enable_iscsid is still enable_cinder and enable_cinder_backend_iscsi only (group_vars/all.yml:794), as in
2023.1. Inside the play, iscsid runs on compute, cinder-volume and cinder-backup hosts for cinder, and on
ironic-conductor hosts when enable_ironic is set; tgtd runs only with the LVM backend and
cinder_target_helper: tgtadm (roles/iscsi/defaults/main.yml:6, :15, :62-73) CODE. Before any container task, the
play loads the configfs kernel module on the iscsid hosts (Before and after a run). The
lists below say where the study covers how to operate it, its impact, its dependencies and the evidence, what to check
around a run and what stays open; the service card follows them.
Where to look¶
Operate¶
- Scenario: Reconfigure a single service §3 (VM impact: NOT AVAILABLE)
No operation page gives a command line for the iscsi tag, and no risk register item is about a run of this tag. What
the study says about running it is in the rows linked under Impact and risk and in fact sheet D
§5.2.
Impact and risk¶
- What the tag executes (
iscsi): Tags §3 and Tags §3.1, rowsiscsi - Sequence CODE:
deploy,reconfigureandupgradeall rundeploy.yml(roles/iscsi/tasks/reconfigure.yml:2,upgrade.yml:2):config-host.yml(theconfigfsmodule),config.yml(config directories andconfig.json),check-containers.yml, then a flush of the handlers (roles/iscsi/tasks/deploy.yml:2-9). The handlersRestart iscsid containerandRestart tgtd containerare skipped whenkolla_actionisconfig(roles/iscsi/handlers/main.yml:2-17,:19-34).
Dependencies¶
- Dependencies: Component dependencies §2, Component dependencies §5
- Host side CODE: both containers are privileged with the host IPC namespace and bind-mount
/dev,/run,/lib/modules(read-only) and/sys/kernel/configas/configfs(roles/iscsi/defaults/main.yml:8-9, :17-18, :40-58);iscsidalso mounts theiscsi_infovolume as/etc/iscsi(:49).
Evidence¶
- Fact sheet: fact sheet D §5.2
- Image side: Kolla images §5 (rows
iscsid,tgtd). The kolladocker/iscsidanddocker/tgtddirectories are identical to 2023.1's; theiscsidstart script writes a new initiator name only when/etc/iscsi/initiatorname.iscsiis missing (kolladocker/iscsid/extend_start.sh:3-7) CODE. - Role diff 2023.1 → 2024.1 CODE: the module rename (
kolla_docker→kolla_container), the/runmount (Known limits and open points), and a new variabletgtd_interface_address(defaultapi_interface_address,roles/iscsi/defaults/main.yml:22), now used for the tgtd portal (roles/iscsi/templates/tgtd.json.j2:2) and the port precheck (roles/iscsi/tasks/precheck.yml:17-27). Nothing else in the role changed.
Before and after a run¶
configfsis loaded and persisted first CODE.config-host.ymlimports themodule-loadrole withmodules: [{name: configfs}], on hosts of theiscsidgroup whereiscsidis enabled (roles/iscsi/tasks/config-host.yml:2-10). Themodule-loadrole runsmodprobe configfsand writes/etc/modules-load.d/configfs.conf(fromroles/module-load/templates/module-load.conf.j2:1-2), both skipped whenkolla_actionisconfig(roles/module-load/tasks/main.yml:4-27). Sogenconfigdoes not load the module, whiledeploy,reconfigureandupgradedo, on every run (the tasks are idempotent). Still holds in 2024.1:config-host.ymland themodule-loadrole are unchanged since 2023.1.- The condition names only the
iscsidside: a host that runstgtdbut is not an enablediscsidhost gets noconfigfsload from this role, althoughtgtdalso mounts/sys/kernel/config(roles/iscsi/defaults/main.yml:58). In the example inventory everytgtdhost (storage) is also in theiscsidgroup (inventory/multinode:305-311) CODE. NOT AVAILABLE Whethertgtdneedsconfigfs. - The role never unloads
configfsand never removes/etc/modules-load.d/configfs.conf: it passes nostatetomodule-load(roles/iscsi/tasks/config-host.yml:6-7), andstop.ymlonly stops the containers (roles/iscsi/tasks/stop.yml:2-6) CODE. - Tags §3.1, row
iscsi: safe on its own "with care, per host batch"; the row names no prerequisite. - Reconfigure a single service
§3:
iscsiis one of the tags that can restart the containers that Tags §3.1 traces to running VMs CODE; what those restarts do to running VMs is NOT AVAILABLE. - Settings that the drift check cannot see CODE: both
config.jsonfiles have"config_files": [], so every setting is in the command:iscsid -d 8 -f, andtgtd … --iscsi portal=<tgtd_interface_address>:<iscsi_port>(roles/iscsi/templates/iscsid.json.j2:2-3,tgtd.json.j2:2-3).kolla_set_configs --checkcompares onlyconfig_filesentries (kolladocker/base/set_configs.py:556-559, F14). A normaldeploy/reconfigureapplies a change oftgtd_interface_addressoriscsi_port, because the changedconfig.jsontask notifies the restart handler (roles/iscsi/tasks/config.yml:15-26); after a separategenconfig,deploy-containersdoes not (Kolla images §6, item 1). - First 2024.1 check of a container that 2023.1 created CODE: the systemd unit text changed
(F16), so a container that no 2024.1 run has recreated or restarted yet is reported as
changed and
restarted at its first 2024.1
deploy/reconfigurecheck.
Known limits and open points¶
- What is not known, rows
iscsidandtgtd: the sources do not establish, for aniscsidrestart, whether existing sessions are kernel-held and whether attach/detach during the window fails; for atgtdrestart, whether tgtd loadstargets.confitself or keeps targets only in memory, and so whether a restart cuts disk I/O for VMs that use LVM volumes from that host. Same table: whether removing theiscsi_infovolume produces a new IQN at the next start, and whether that breaks backend ACLs. - fact sheet D §5.2,
bullets "Host interaction" (bootstrap-servers removes host
open-iscsi/iscsi-initiator-utils), "VM impact (NOT AVAILABLE)", "tgtd restart (consequences NOT AVAILABLE)" and "Precheck oddity" (it checks thatiscsi_port3260 is free on the iscsid hosts, but 3260 is the target (tgtd) port). - fact sheet D
§7, item
11: both still hold in 2024.1. iscsid runs
iscsid -d 8 -f(roles/iscsi/templates/iscsid.json.j2:2); the precheck tests thatiscsi_port(3260,group_vars/all.yml:442) is free ontgtd_interface_addressof the iscsid hosts while noiscsidcontainer exists yet (roles/iscsi/tasks/precheck.yml:17-27) CODE. - Changed in 2024.1: the
/runmount CODE. 2023.1 mounted/run/:/run/:shared; 2024.1 mounts/run:/run:sharedwith Docker and/run:/runwithout:sharedwith Podman (roles/iscsi/defaults/main.yml:46, :56), and appendsrun_default_volumes_<engine>to both containers' volumes (:10, :19): nothing with Docker, five/run/...:sharedsub-mounts with Podman (group_vars/all.yml:165-172). The volume check compares the bind strings as sets, without normalising a trailing slash (module_utils/kolla_docker_worker.py:124-144,module_utils/kolla_container_worker.py:400-434). NOT AVAILABLE (Docker semantics) Whether Docker reports the 2023.1 bind with its trailing slashes, and so whether this alone flags drift; the unit change above flags it anyway. - Still holds in 2024.1 CODE: the precheck fails on RedHat-family hosts when
enable_tgtdis true (roles/iscsi/tasks/precheck.yml:29-35);cinder_target_helperdefaults tolioadmthere (group_vars/all.yml:1045), sotgtdis not enabled by default on those hosts. The containers mount neither thecindervolume nor/sys/fs/cgroup, andtgtddoes not mountiscsi_info(roles/iscsi/defaults/main.yml:40-58). - Ironic without the cinder iSCSI backend CODE: the
iscsidservice is enabled forironic-conductorhosts (roles/iscsi/defaults/main.yml:6, :68-69), but the play only targets&enable_iscsid_Truehosts (site.yml:44, :444) andenable_iscsiddoes not includeenable_ironic(group_vars/all.yml:794), so in that case the play matches no host and noiscsidcontainer is deployed. Still holds in 2024.1. NOT AVAILABLE Whether ironic needs one there. - fact sheet D §8: NOT AVAILABLE: what an iscsid, tgtd or multipathd restart does to attached volumes under I/O (session state, path failover, the guest view); for tgtd, whether the LVM targets come back without a cinder-volume restart.
- R14: a
bootstrap-serversre-run on a live host removes host packages:open-iscsion Debian/Ubuntu always,iscsi-initiator-utilson RedHat only with the libvirt container (ansible-collection-kollaroles/packages/defaults/main.yml:25-34,roles/packages/tasks/main.yml:15-23) CODE. - Kolla images §6, item 19: the iSCSI initiator name is stable per
iscsi_infovolume across restart and recreate CODE. NOT AVAILABLE Whether removing the volume produces a new IQN at the next start, and whether that breaks backend ACLs keyed on the old one. - Known bugs and limitations, Open
questions and Findings have no entry specific to
iscsidortgtd; F14 and F16 apply to them as to other containers.
Service card¶
The rows of the card are explained in How to read a service card.
| Item | Value |
|---|---|
| Play | site.yml:439 |
| Tags | iscsi |
| Play host patterns | iscsid, tgtd |
| Node types in play (example inventory) | compute, control, storage |
| Node types running its containers | compute, control, storage |
| Containers | iscsid, tgtd |
deploy/reconfigure flow (tasks/) |
config-host → config → check-containers → flush handlers |
| Task files | check-containers.yml, check.yml, config-host.yml, config.yml, config_validate.yml, deploy-containers.yml, deploy.yml, main.yml, precheck.yml, pull.yml, reconfigure.yml, stop.yml, upgrade.yml |
| Templates | iscsid.json.j2, tgtd.json.j2 |
| Handlers (definition order) | Restart iscsid container; Restart tgtd container |
| Key variables | enable_iscsid, enable_cinder_backend_lvm |
| Role dependencies | none |
Related¶
- Cinder — cinder-volume (LVM) depends on this role
- Nova — nova-compute depends on it for volume attach
- Reconfigure a single service
§3 — the tags
that can restart containers traced to running VMs,
iscsiamong them - Component dependencies §5 — what lands on a compute host,
iscsidincluded - Repository architecture §5 — the
module-loadhelper role and the roles that use it - Components — the other component pages