Blocks · Storage and file sharing

iscsi/target

iSCSI target. A raw replicated volume exported as one iSCSI LUN through LIO; initiators reconnect on their own after a failover.

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

target.yaml
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.

KeyDefaultMeaning
port3260LIO's internal portal port. Exposed on a VIP, it must differ from the exposed 3260, so set it, such as 33260.
iqnderived from the block's nameTarget IQN. Unset, it is iqn.2026-09.io.expanse:<namespace>-<name>-0.
wwnderived from the block's nameThe LUN's NAA WWN, the device identity initiators see.
chapUsernoneCHAP user required at login. Unset, any initiator may log in with read-write access.
chapPasswordnoneCHAP 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-iscsi are unverified.

Source

All block types · Fields every block shares