iSCSI Storage

Use this page to choose the right kind of iSCSI pool and to learn what both kinds share: portals, paths, health, and limits. The step-by-step tasks are on the two pool pages below.

UI path: Control Center -> Storage -> Instance Storage

What iSCSI Storage Is

An iSCSI pool is instance storage that lives on a SAN target. Karios hosts log in to the target over the storage network and see each disk through several paths at once (multipath). If one cable, switch port, or portal fails, the disk keeps working on the other paths.

Karios offers two kinds of iSCSI pool. Both are added from Add Instance Storage with Protocol set to iscsi.

Question

Managed array (COMSTAR)

Generic iSCSI (existing LUNs)

Who creates the LUNs

Karios. It carves one volume on the array for every VM disk.

You. Karios only attaches LUNs your target already exports.

Best for

New VM disks, root disks, and templates on SAN storage.

Bringing existing data on your own target into a VM as a data disk.

What Karios changes on the storage

Target group, host groups, volumes, and views on the array.

Nothing. It never creates, resizes, wipes, or deletes a LUN, and never changes the target’s configuration.

CHAP

Not offered.

None, CHAP, or Mutual CHAP.

Scope

Zone or Cluster.

Zone only.

Who can set it up

A platform administrator registers the array. Users with storage manage rights create pools on it.

Platform administrator only.

Pick the page for your case:

Before You Start

  • [ ] Every host in the pool’s scope has a working storage network interface.

  • [ ] Every host can reach the target portals on TCP port 3260, or on the port your target uses.

  • [ ] The target has at least two portals on the storage network, ideally on separate switches, so each disk gets two or more paths.

  • [ ] You know which storage tag (if any) should steer VM disks to this pool.

Note

An IPv4 portal can be outside the host’s storage subnet. Karios then reaches it through the node’s storage gateway with a host route that Karios adds and keeps across reboots.

Portals and Minimum Paths

A portal is one address and port where the target accepts logins. Each host opens one path per portal it can reach.

  • Every iSCSI pool needs at least one portal. The address can be an IP address or a hostname. The port defaults to 3260.

  • The same address and port cannot be listed twice in one pool.

  • Minimum paths is how many working paths a host must have to a disk. The default is 2 and the lowest value is 1. On a managed array pool the list stops at the number of portals you pick, so the default is 1 when you pick a single portal.

  • If you set Minimum paths to 1, the form shows Single path: no redundancy. To continue you must tick I understand this pool has no path redundancy and want to create it anyway. On such a pool, one failed cable or portal stalls the VMs on that host until the path returns.

Tip

Keep Minimum paths at 2 or more in production. Use 1 only for a lab target that really has a single portal.

What Happens When You Create a Pool

  1. Karios sends the pool to every host in scope. Each host logs in to the portals.

  2. If any host cannot reach or log in to the target, the create is rolled back with KF-4014. Nothing is left behind.

  3. If any host sees fewer paths than Minimum paths, the create is rolled back with KF-4013.

  4. If a host does not answer in time, the pool is created and its health reads Pending hosts until that host reports.

Pool Health

Each pool’s detail page has a Fabric card. Its Health row shows what the hosts report.

Health

Meaning

Up

Every host in scope can reach the pool.

Degraded

Some hosts cannot reach the pool, a host that can reach it is short of portals or of the minimum paths, or a disk on the pool reads Critical on a host (no usable path, or fewer than the minimum).

Pending hosts

At least one host has not answered yet, or has not reported for about three minutes, and none has refused.

Down

No host can reach the pool.

No hosts

The pool’s scope has no hosts in it.

The Registration row shows whether the pool is known to the platform:

  • up: the pool is registered and usable.

  • Waiting for the platform: the platform has not accepted the pool yet, so no disk can use it. Contact Karios support if it stays this way.

  • error: registration failed. Read Last error on the same card.

If a managed array pool stays Down for about five minutes (the default; health is checked every two minutes, so it can take a little longer), Karios stops placing new disks on it. The card then shows Placement: Disabled by the fabric. Disks already on the pool are left alone. Placement comes back by itself a few minutes after a host can reach the pool again.

Multipath Health of a Disk

Open a disk on an iSCSI pool in Control Center -> Storage -> Block Storage. The Fabric paths panel (“Live multipath health across hosts”) shows:

  • State: Healthy, Degraded, Critical, or Not connected.

  • Minimum paths and the disk’s Identity.

  • One block per host that holds the disk, with each path’s device, link, ALUA state, and whether it is usable.

The panel reads live paths only on the node that answers the request. For a disk held by any other host, that host’s block has no path rows. It carries the note held by <host>; its live paths are read on that node, and State reads Not connected. To check such a disk, read the Hosts rows on the pool’s Fabric card instead. They show each host’s path count and name any disk that is not healthy.

State

Meaning

Healthy

Attached, at or above the minimum paths, and every path is usable.

Degraded

Attached and serving I/O, but some paths are down.

Critical

Fewer usable paths than the minimum. I/O is blocked or one failure away from it. Fix the paths now.

Not connected

The disk is not open on that host, for example because its VM is stopped. It also reads this when the disk is held by a host the panel cannot read from here.

Storage Tags

  • One storage tag must point to one kind of SAN pool. Karios refuses a tag that another SAN pool with a different protocol or QoS setting already uses.

  • The tag karios-mapped-lun is reserved for generic iSCSI pools. The UI shows it as the locked chip Reserved for existing LUNs. You cannot add it to any other pool.

Limits on Both Pool Types

  • Volume snapshots are not available. The UI turns snapshot creation off for these disks and says why. A snapshot request sent through the API is refused with KF-4016. Keep disks that need snapshots on RBD storage.

  • Storage QoS (Min IOPS, Max IOPS, or custom IOPS) is refused with KF-4016 instead of being stored without effect, because these pools never enforce it. It is refused on a volume profile whose storage tags can reach a managed array pool, and when a create or resize asks for IOPS limits on a disk of that pool. The Volume Profiles form switches Storage QoS off in that case. Hypervisor QoS, which the host applies, stays available. Generic iSCSI pools never take new disks, so they do not block a profile.

  • A QoS setting stored on the pool itself through the API is kept but never enforced. The pool shows a warning, not a refusal.

Common Errors

Karios errors start with a KF- code. The pool pages list the codes specific to each pool type.

Code

What it means

What to do

KF-4013

A host sees fewer paths than Minimum paths.

Export the storage on every portal, check that each host is allowed on the target, or lower Minimum paths.

KF-4014

A host cannot reach the portals or cannot log in.

Read the line for each host. It names each failed portal and the cause. On a generic iSCSI pool it also says what to fix.

KF-4016

A snapshot, or Storage QoS (Min or Max IOPS), asked on a pool that does not support it.

Keep disks that need snapshots on RBD storage. Leave Min and Max IOPS off the volume profile, or give it a storage tag that only non-SAN pools carry.

KF-4098

The platform refused the call.

Read the details shown with the error.

KF-5022

Karios could not read what it needed to check. Nothing was sent.

Retry.

Done Criteria

  • [ ] You know which pool type fits your workload.

  • [ ] The storage network and portals meet the checklist above.

  • [ ] You finished the tasks on the matching pool page.