Configuring iSCSI on Flatcar Container Linux

iSCSI is a protocol which provides block-level access to storage devices over IP. This allows applications to treat remote storage devices as if they were local disks. iSCSI handles taking requests from clients and carrying them out on the remote SCSI devices.

Flatcar Container Linux has integrated support for mounting devices. This guide covers iSCSI configuration manually or automatically with Butane Configs .

Manual iSCSI configuration

Set the Flatcar Container Linux iSCSI initiator name

iSCSI clients each have a unique initiator name. Flatcar Container Linux generates a unique initiator name on each install and stores it in /etc/iscsi/initiatorname.iscsi. This may be replaced if necessary.

Configure the global iSCSI credentials

If all iSCSI mounts on a Flatcar Container Linux system use the same credentials, these may be configured locally by editing /etc/iscsi/iscsid.conf and setting the node.session.auth.username and node.session.auth.password fields. If the iSCSI target is configured to support mutual authentication (allowing the initiator to verify that it is speaking to the correct client), these should be set in node.session.auth.username_in and node.session.auth.password_in.

Start the iSCSI daemon

systemctl start iscsid

Discover available iSCSI targets

To discover targets, run:

iscsiadm -m discovery -t sendtargets -p target_ip:target_port

Provide target-specific credentials

For each unique --targetname, first enter the username:

iscsiadm -m node \
  --targetname=custom_target \
  --op update \
  --name=node.session.auth.username \
  --value=my_username

And then the password:

iscsiadm -m node \
  --targetname=custom_target \
  --op update \
  --name=node.session.auth.password \
  --value=my_secret_passphrase

Log into an iSCSI target

The following command will log into all discovered targets.

iscsiadm -m node --login

Then, to log into a specific target use:

iscsiadm -m node --targetname=custom_target --login

If you want to connect to iSCSI targets automatically at boot you first need to enable the systemd service:

systemctl enable iscsi

Automatic iSCSI configuration

To configure and start iSCSI automatically after a machine is provisioned, credentials need to be written to disk and the iSCSI service started.

A Butane Config will be used to write the file /etc/iscsi/iscsid.conf to disk:

isns.address = host_ip
isns.port = host_port
node.session.auth.username = my_username
node.session.auth.password = my_secret_password
discovery.sendtargets.auth.username = my_username
discovery.sendtargets.auth.password = my_secret_password

The Butane Config

variant: flatcar
version: 1.0.0
systemd:
  units:
    - name: iscsi.service
      enabled: true
storage:
  files:
    - path: /etc/iscsi/iscsid.conf
      mode: 0644
      contents:
        inline: |
          isns.address = host_ip
          isns.port = host_port
          node.session.auth.username = my_username
          node.session.auth.password = my_secret_password
          discovery.sendtargets.auth.username = my_username
          discovery.sendtargets.auth.password = my_secret_password

Mounting iSCSI targets

See the mounting storage docs for an example.