Overview
Exports one raw (unformatted) replicated volume as a single iSCSI LUN through the kernel's LIO target, configured with targetcli. A DRBD secondary refuses to open the device, so the target can only run where the volume's primary is: the block is a singleton colocated with the primary and reached at a stable VIP. There is no multipath; on failover the initiator's own session recovery reconnects to the same portal address.
The target IQN and the LUN's WWN are derived from the block's name, so they are the same on every node and an initiator's device identity never changes across a failover.
- Shape
- Singleton on a raw replicated volume
- Reached at
- VIP
- Node package
pkgs.targetcli-fb
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.targetcli-fb, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: lun namespace: default spec: type: iscsi/target replicas: 1 strategy: kind: SINGLETON resources: requests: cpu: 100m memory: 128Mi storage: - name: lun size: 10Gi replication: 3 mountPath: /mnt/lun # unused: LIO opens the raw device filesystem: none # required config: port: 33260 # never 3260: the VIP holder binds that iqn: iqn.2026-09.io.expanse:lun network: ports: - name: iscsi port: 3260 target_port: 33260 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 33260 period_seconds: 2
filesystem: none is required: the block never formats or mounts its volume.
$ expanse ctl block apply -f target.yaml --dry-run # validate only $ expanse ctl block apply -f target.yaml
Configuration
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
port | 3260 | LIO's internal portal port. Exposed on a VIP, it must differ from the exposed 3260, so set it, such as 33260. |
iqn | derived from the block's name | Target IQN. Unset, it is iqn.2026-09.io.expanse:<namespace>-<name>-0. |
wwn | derived from the block's name | The LUN's NAA WWN, the device identity initiators see. |
chapUser | none | CHAP user required at login. Unset, any initiator may log in with read-write access. |
chapPassword | none | CHAP secret, at least 12 characters. Required with chapUser. Sealed: kept out of the stored block (block secrets). |
Using it
Do not use SendTargets discovery. LIO's discovery answer carries its own internal portal address, not the VIP, so a discovery-driven login fails. Register the target against the VIP directly:
$ iscsiadm -m node -o new -T iqn.2026-09.io.expanse:lun -p <VIP>:3260 $ iscsiadm -m node -T iqn.2026-09.io.expanse:lun -p <VIP>:3260 --login
Validated with Linux open-iscsi only; ESXi, Windows and other initiators are unverified.
When a node fails
When the serving node is lost, the VIP moves to the node that takes over as primary and LIO comes back there with the same identity. open-iscsi reconnects to the same VIP:3260 on its own, with no manual re-login. In Expanse's VM test the writer resumed about 64 s after the kill, about 54 s of it the VIP and primary moving; every acknowledged write checksummed correctly afterwards.
Limits
- SCSI-3 persistent reservations do not survive a failover: the target on the new node starts with no registered keys.
- No multipath or ALUA.
- Initiators other than Linux
open-iscsiare unverified.
Source
- docs/ISCSI.md: the Expanse guide this page follows.
- nix/blocks/iscsi/target: the type's identity and JSON Schema.