ceph iscsi #0

Supports: focal
Add to new model


The iSCSI gateway is integrating Ceph Storage with the iSCSI standard to provide a Highly Available (HA) iSCSI target that exports RADOS Block Device (RBD) images as SCSI disks.


The charm provides the Ceph iSCSI gateway service. It is intended to be used in conjunction with the ceph-osd and ceph-mon charms.

Warning: This charm is in a preview state for testing and should not be used outside of the lab.



When deploying ceph-iscsi ensure that exactly two units of the charm are being deployed, this will provide multiple data paths to clients.

Note: Deploying four units is also theoretical possible but has not been tested.

The charm cannot be placed in a lxd container. However, it can be located with the ceph-osd charms. Co-location with other charms is likely to be fine but is untested.

A sample bundle.yaml file's contents:

    series: focal
        charm: cs:ceph-iscsi
        num_units: 2
        - '0'
        - '1'
        charm: cs:ceph-osd
        num_units: 3
          osd-devices: /dev/vdb
        - '0'
        - '1'
        - '2'
        charm: cs:ceph-mon
        num_units: 3
          monitor-count: '3'
        - lxd:0
        - lxd:1
        - lxd:2
    - - ceph-mon:client
      - ceph-iscsi:ceph-client
    - - ceph-osd:mon
      - ceph-mon:osd

Important: Make sure the designated block device passed to the ceph-osd charms exists and is not currently in use.

Deploy the bundle:

juju deploy ./bundle.yaml

Managing Targets

The charm provides an action for creating a simple target. If more complex managment of targets is requires then the gwcli tool should be used. gwcli is available from the root account on the gateway nodes.

   $ juju ssh ceph-iscsi/1
   $ sudo gwcli
   /> ls


This section covers Juju actions supported by the charm. Actions allow specific operations to be performed on a per-unit basis.


Run this action to create an iscsi target.

    $ juju run-action --wait ceph-iscsi/0 create-target \
        image-size=2G \
        image-name=bob \
        pool-name=superssd \
        client-initiatorname=iqn.1993-08.org.debian:01:aaa2299be916 \
        client-username=usera \
      UnitId: ceph-iscsi/0
      id: "28"
        iqn: iqn.2003-01.com.ubuntu.iscsi-gw:iscsi-igw
      status: completed
        completed: 2020-05-08 09:49:52 +0000 UTC
        enqueued: 2020-05-08 09:49:36 +0000 UTC
        started: 2020-05-08 09:49:37 +0000 UTC

### pause

Pause the ceph-iscsi unit. This action will stop the rbd services.

### resume

Resume the ceph-iscsi unit. This action will start the rbd services if paused.

## Network spaces

This charm supports the use of Juju [network spaces][juju-docs-spaces] (Juju
`v.2.0`). This feature optionally allows specific types of the application's
network traffic to be bound to subnets that the underlying hardware is
connected to.

> **Note**: Spaces must be configured in the backing cloud prior to deployment.

The ceph-iscsi charm exposes the following traffic types (bindings):

- 'public' (front-side)
- 'cluster' (back-side)

For example, providing that spaces 'data-space' and 'cluster-space' exist, the
deploy command above could look like this:

    juju deploy --config ceph-iscsi.yaml -n 2 ceph-iscsi \
       --bind "public=data-space cluster=cluster-space"

Alternatively, configuration can be provided as part of a bundle:

      charm: cs:ceph-iscsi
      num_units: 2
        public: data-space
        cluster: cluster-space

VMWare integration

  1. Create ceph pool if required.

To create a new pool to back the iscsi targets run the create-pool action from the ceph-mon charm.

   $ juju run-action --wait ceph-mon/0 create-pool name=iscsi-targets
   UnitId: ceph-mon/0
     Stderr: |
       pool 'iscsi-targets' created
       set pool 2 size to 3
       set pool 2 target_size_ratio to 0.1
       enabled application 'unknown' on pool 'iscsi-targets'
       set pool 2 pg_autoscale_mode to on
   status: completed
     completed: 2020-04-08 06:42:00 +0000 UTC
     enqueued: 2020-04-08 06:41:38 +0000 UTC
     started: 2020-04-08 06:41:42 +0000 UTC
  1. Collect the Initiator name for adapter.

From the VMWare admin UI select the Adapters tab in the Storage context. Ensure iSCSI enabled is set to Enabled.

Click 'Configure iSCSI' and take a note of the iqn name.

  1. Create iSCSI target.

Run the action to create a target for VMWare to use.

Note: The username should be more than eight characters and the password between twelve and sixteen characters.

   $ juju run-action --wait ceph-iscsi/0 create-target \
       client-initiatorname="iqn.1998-01.com.vmware:node-caloric-02f98bac" \
       client-username=vmwareclient \
       client-password=12to16characters \
       image-size=10G \
       image-name=disk_1 \
   UnitId: ceph-iscsi/0
     Stdout: |
       Warning: Could not load preferences file /root/.gwcli/prefs.bin.
     iqn: iqn.2003-01.com.ubuntu.iscsi-gw:iscsi-igw
   status: completed
     completed: 2020-04-08 06:58:34 +0000 UTC
     enqueued: 2020-04-08 06:58:15 +0000 UTC
     started: 2020-04-08 06:58:19 +0000 UTC
  1. Add target to VMWare.

Follow the Ceph iSCSI Gateway documentation to use the new target. Use CHAP username and password provided to the create-target action.

Warning: As of the time of writing the workaround to set the CHAP credentials via the esx cli is still needed.


The charm needs to pull in its dependencies before it can be deployed. To pull in the dependency versions that correspond to this version of the charm then run the build tox target.

To update all dependencies to their latest versions then run the update-deps tox target.


(string) The IP address and netmask of the public (front-side) network (e.g., If multiple networks are to be used, a space-delimited list of a.b.c.d/x can be provided.
(string) Key ID to import to the apt keyring to support use with arbitary source configuration from outside of Launchpad archives or PPA's.
(int) Mon and OSD debug level. Max is 20.
(boolean) If True enables IPv6 support. The charm will expect network interfaces to be configured with an IPv6 address. If set to False (default) IPv4 is expected. NOTE: these charms do not currently support IPv6 privacy extension. In order for this charm to function correctly, the privacy extension must be disabled and a non-temporary address must be configured/available on your network interface.
(string) RBD pool to use to store gateway configuration.
(string) Optional configuration to support use of additional sources such as: - ppa:myteam/ppa - cloud:trusty-proposed/kilo - http://my.archive.com/ubuntu main The last option should be used in conjunction with the key configuration option. Note that a minimum ceph version of 0.48.2 is required for use with this charm which is NOT provided by the packages in the main Ubuntu archive for precise but is provided in the Ubuntu cloud archive.
(boolean) If set to True, supporting services will log to syslog.