Ansible Module Package

The Ansible module package contains the following components:

  • Ansible modules that configure the KumoScale storage nodes, provision their storage, and provide the building blocks for the KumoScale resiliency solution.
  • Example Playbooks that configure KumoScale software and the Syslog server, provision storage over KumoScale software, and execute the self-healing mechanism.
  • A variable file containing the configuration parameters, to be edited by the data center DevOps engineer prior to provisioning storage volumes.
  • Initiator installation files containing the installation files for the initiator.

KumoScale Software Ansible Modules

The Ansible modules are located in the ~/library directory.

Each of the following modules is a Python™ module which has a corresponding playbook with a matching name (e.g., if the module’s name is module1.py, the playbook’s name is module1.yml). The modules provide the basic functionality and abstract KumoScale software REST APIs or CLI commands.

Table 2. KumoScale Software Ansible Modules and Playbooks

Module / Playbook

Description

ks_token

Generates a Role-Based Access Control (RBAC) token for accessing KumoScale software or the KumoScale Provisioner Service.

ks_volume

Creates, deletes or expands volume(s) or snapshot volumes on KumoScale software, according to the requested capacity and storage class.

ks_host

Deletes the host (initiator) from the Provisioner. If the host can’t be deleted an error will be displayed.

ks_snapshot

Takes a snapshot of a volume.

ks_publish

Creates a target for a specific initiator (if none exists) on KumoScale software, attaches a volume as a namespace to it, and grants access to the initiator.

ks_connect

Connects an initiator to a target as a block device.

ks_mirror

Creates the resiliency configuration (replication) from the attached volumes.

ks_replica

Adds or removes a replica from a resilient volume.

ks_mount

Creates a file system and mounts on the initiator.

 

Module Parameters

The following sections detail the module input parameters.

ks_token

When authorization mode is

  • Local, it creates a token according to the role of the input username.
  • OpenIDC, it uses authorization server parameters to generate the authorization token before using Provisioner REST commands.

Parameter

Options/Defaults

Description

provisioner_url

string

(required)

KumoScale Provisioner URL

ks_url

list

(required for Local authorization mode)

KumoScale Appliance Management URL

 

username

string

(required for Local authorization mode)

The username for the admin user

password

string

(required for Local authorization mode)

The password for using Role-based access control authentication method

expiration

string

(required for Local authorization mode)

The expiration period of the token, in seconds

token_url

string

(required for OpenIDC authorization mode)

The authorization server token URL

client_id

string

(required for OpenIDC authorization mode)

The client identifier

client_secret

string

(required for OpenIDC authorization mode)

The secret string of the client

For example:

Local authorization mode

- name: generate token

ks_token:

   provisioner_url: https://10.10.10.2:8090

   ks_url: https://10.10.10.1

   username: admin

   password: password

   expiration: 3600

OpenIDC authorization mode

- name: generate token

ks_token:

   provisioner_url: https://10.10.10.2:8090

   token_url: https://10.10.10.3

   client_id: Ansible_client_id

   client_secret: example_ansible_secret

ks_volume

Create or deletes a volume or a snapshot volume over a snapshot.

Parameter

Options/Defaults

Description

provisioner_url

string

(required)

The KumoScale Provisioner service URL.

vol_name

string

The name of the new volume.

vol_uuid

string

The UUID of the volume. Optional only when creating the volume.

capacity

int

The required volume size in GB.
Mandatory when state = Present; otherwise, it will fail.

token

String

(required)

The authentication token for the KumoScale Provisioner service.

replicas

  • 1
  • 2
  • 3

Number of replicas.
Mandatory when state = Present; otherwise, it will fail.

racks

list of strings

A list of racks from which the volume should be allocated (optional).

regions

list of strings

A list of regions from which the volume should be accessible (optional).

zones

list of strings

A list of zones from which the volume should be accessible (optional).

maxIOPSPerGB

int

Upper limit for input/output operations per second IOPS/Gigabyte[1] (GB) (optional) – Quality of Service (QoS).

desiredIOPSPerGB

int

The desired IOPS/GB (optional) - QoS.

maxBWPerGB

int

The upper limit for bandwidth per GB, in kilobytes per second (KB/s) (per GB) (optional) - QoS.

desiredBWPerGB

int

The desired bandwidth per GB, in KB/s (per GB) (optional) - QoS.

blockSize

  • 512
  • 4096

The required volume block size (optional).

maxReplicaDownTime

int

(optional)

  • 0 – no automatic recovery
  • Minimum: 5 minutes.
  • Maximum: 1440 (1 day).

The maximum duration in minutes to wait when detecting degradation in the replicated volume before initiating the autonomous self-healing process.

provisioningType

  • thick
  • thin

Should the volume be fully pre-allocated (thick) or thin-provisioned (thin)?

reservedSpacePercentage

10% of the volume’s capacity

The reserved space in percentage. Used for a thin-provisioned volume or a writable snapshot volume (the percentage of the parent volume to reserve for the log space).

snap_name

String

(required)

The snapshot name, when creating a snapshot volume. Required for a snapshot volume when snap_uuid is not provided.

snap_uuid

String

(required)

The snapshot UUID, when creating a snapshot volume. Required for a snapshot volume when snap_name is not provided.

writable

  • True
  • False

For snapshot volumes only: indicates whether the snapshot volume is writable or not.

tenant_id

string

The tenant ID (virtual cluster)

state

  • present
  • modify
  • absent

The state.

  • present - Create the volume.
  • modify - Expand the volume.
  • absent - Delete the volume.

 

ks_snapshot

Take a snapshot over a volume.

Parameter

Options/Defaults

Description

provisioner_url

String

(required)

The KumoScale Provisioner service URL.

token

String

(required)

The authentication token for the KumoScale Provisioner service.

vol_uuid

string

The UUID of the parent volume.
Mandatory when state = Present.

snap_name

string

The name of the new snapshot.
Mandatory when state = Present.

snap_uuid

string

The UUID of the snapshot, if provided by the user (optional only when creating the volume).

reservedSpacePercentage

The default is 10% of the volume’s capacity.

The reserved space for the change log in percentage.

tenant_id

string

The tenant ID (virtual cluster).

state

  • absent
  • present

The state.

  • absent: Delete a snapshot.
  • present: Take a snapshot.

 

For example, to create a volume snapshot named snap_vol1:

ks_snapshot:

   provisioner_url: https://10.10.10.2:8090

vol_uuid: ######-####-####-####-###########

snapshot_name: snap_vol1

token: token

state: present

To delete a volume snapshot named snap_vol1:

ks_snapshot:

   provisioner_url: https://10.10.10.2:8090

snapshot_uuid: ######-####-####-####-###########

token: token

state: absent

 

ks_host

Deletes hosts (initiators) from the Provisioner. If the host (initiator) can’t be deleted, the appropriate error will be displayed.

Parameter

Options/Defaults

Description

provisioner_url

string

(required)

The KumoScale Provisioner service URL

host_uuid

string

Require one of two parameters host_uuid or host_name

Host UUID

 

host_name

 

String

Require one of two parameters host_uuid or host_name

Host name

token

 

string

A token provided to the KumoScale Provisioner to allow communication and automation

state

string

(required)

absent

 

 

For example:

Delete an initiator via UUID 1234567-####-####-####-###########:

ks_host:

   provisioner_url: https://10.10.10.2:8090

host_uuid: 1234567-####-####-####-###########

token: token

state: absent

Delete an initiator via name my_host:

ks_host:

   provisioner_url: https://10.10.10.2:8090

host_name: my_host

token: token

state: absent

ks_publish

Publishes or un-publishes the volume to a specific initiator.

Parameter

Options/ Defaults

Description

vol_name

string

The name of the volume to be (un)published.

Either vol_name or vol_uuid must be provided.

vol_uuid

int

The UUID of the volume to be (un)published.

provisioner_url

string

(required)

The URL address of the KumoScale Provisioner service.

host

string

(required)

The application host (initiator) name.

tenant_id

string

 

The tenant ID (virtual cluster).

token

string

(required)

The authentication token for the KumoScale Provisioner service.

state

  • absent
  • present

The state.

  • absent: Un-publish the volume.
  • present: Publish the volume.

 

ks_connect

Connect the application host (initiator) to the volume (namespace) via NVMe connect.

Parameter

Options/Defaults

Description

vol_name

string

The name of the replica (physical).

Either vol_name or vol_uuid must be provided.

vol_uuid

string

The UUID of the replica (physical).

snapshot_volume

  • False
  • True

Is the volume a volume of a snapshot or not.

provisioner_url

string

(required)

The URL address of the KumoScale Provisioner service.

tenant_id

string

The tenant ID (virtual cluster).

token

string

(required)

The authentication token for the KumoScale Provisioner service.

state

  • absent
  • present

The state.

  • absent: Disconnect the initiator from the volume.
  • present: Connect the initiator to the volume.

 

For example, to disconnect a volume from the initiator:

ks_connect:

   provisioner_url: https://10.10.10.2:8090

   vol_name: vol1

   vol_uuid: ########-####-####-#############

   token: token

   state: absent

ks_mirror

Create (or delete) the RAID over N volumes (replicas).

Parameter

Options/Defaults

Description

vol_name

String

The name of the resilient volume.

Either vol_name or vol_uuid must be provided.

vol_uuid

String

The UUID of the resilient volume.

provisioner_url

string

(required)

The URL address of the KumoScale Provisioner service.

token

String

(required)

The authentication token for the KumoScale Provisioner service.

snapshot_volume

  • False
  • True

Is the volume a volume of a snapshot or not.

readonly

  • False
  • True

Relevant only to a snapshot volume – is the volume read-only or read/write.

state

  • Absent
  • Present
    (required)

The state.

  • absent: Break the RAID (mdadm mirror).
  • present: Create the RAID (mdadm mirror).

Bitmap

  • internal
  • clustered
    (optional)
Default: internal

Bitmap assignment

  • internal – regular RAID
  • clustered- RAID in a clustered environment

max_nodes

Integer
Default: 16

User when bitmap = clustered
Minimum-2; Maximum-16

Maximum number of connected nodes

 

ks_replica

Adds or removes a replica to a resilient volume.

Note – This function only adds the replica to the KumoScale Provisioner Service. The self-healing module adds or removes it to the RAID.

Parameter

Options/Defaults

Description

vol_uuid

string

(required)

The UUID of the resilient volume.

replica_uuid

String

(required)

The UUID of the volume replica.

Required only when state = Absent.

provisioner_url

string

(required)

KumoScale Provisioner service URL.

sameRackAllowed

False

True

Whether or not replicas can be allocated on the same rack.

racks

list of strings

List of racks on which the volume(s) should reside.

zones

list of strings

List of zones from which the volume(s) should be accessible.

regions

list of strings

List of regions from which the volumes should be accessible.

tenant_id

string

The tenant ID (virtual cluster).

token

string

(required)

The authentication token for the KumoScale Provisioner service.

state

  • absent
  • present

The state.

  • absent: Delete the replica on the KumoScale Provisioner service.
  • present: Add a replica on the KumoScale Provisioner service.

 

For example,

Add replica to volume:

ks_replica:

   provisioner_url: http://10.10.10.1:8090

   vol_uuid: #########-###-####-####-###########

   racks: ['Rack3']

   token: token

   state: present

Delete replica from volume:

ks_replica:

   provisioner_url: http://10.10.10.1:8090

   vol_uuid: #########-###-####-####-###########

   replica_uuid: #########-###-####-####-###########

   token: token

   state: absent

 

ks_mount

Creates a file system and mounts on an initiator.

Parameter

Options/Defaults

Description

vol_name

string

The name of the replica (physical).

Either vol_name or vol_uuid must be provided.

provisioner_url

string

(required)

The URL address of KumoScale Provisioner service.

token

String

(required)

The authentication token for the KumoScale Provisioner service.

fstype

String

(required)

Type of file system to be created.

opts

 

Options for the file system.

 

Example Playbooks

The example playbooks, located in the library subdirectory, can be used as-is, or as a reference design for implementation in the data center. The playbooks retrieve their input parameters from the variable file: vars.yml, which resides in library, the same subdirectory as the playbooks.

The following playbooks are provided in addition to the playbooks with matching names with the modules, and contain a sequence of commands:

Table 3. KumoScale Software Example Playbooks

Playbook

Description

Parameters

ks_snapshot

Takes a snapshot of a volume or deletes one.

ks_url, username, admin_password, expiration, vol_name, vol_uuid,snap_name, snap_uuid, provisioner_url, tenant_id, reservedSpacePercentage, state

ks_replica

Adds or removes a replica to a resilient volume.

ks_url, username, admin_password, expiration, vol_uuid, replicas, replica_uuid, provisioner_url, tenant_id

configure_host

Reconfigures the agent parameters and restarts the service. It copies the agent conf file to /usr/lib/systemd/system/ks-agent.conf

 

configure_mdadm_syslog

Configures the application initiators to send md events to your Syslog server.

syslog_server

create_snapshot_volume

Creates a volume from a snapshot.

ks_url, username, admin_password, expiration, vol_name, vol_uuid, snap_uuid, provisioner_url, maxIOPSPerGB, maxBWPerGB, reservedSpacePercentage, tenant_id, host, path, fstype

create_volume_replicated

Creates one or more resilient volumes, creates a file system over them, mounts them, and connects them to a initiator via a target.

ks_url, username, admin_password, expiration, vol_name, vol_uuid, capacity, provisioner_url, replicas, maxReplicaDownTime, storageClassName, tenant_id, host, fstype, path, opts

create_volume_simple

Creates one or more non-resilient volumes, creates a file system over them, mounts them, and connects them to an initiator via a target.

ks_url, username, admin_password, expiration, vol_name, vol_uuid, capacity, replicas, spanAllowed provisioner_url, storageClassName, tenant_id, host, fstype, path, opts

delete_host

Deletes the specified the host (initiator). If the specified initiator is unavailable or missing, an error will be returned.

host_name or host_uuid

delete_snapshot_volume

Deletes a volume of a snapshot.

ks_url, username, admin_password, expiration, vol_name, provisioner_url, reservedSpacePercentage, tenant_id, host, path, fstype

delete_volume_replicated

Deletes one or more resilient volumes (it assumes that the volumes are connected to initiators and have a mounted file system).

ks_url, username, admin_password, expiration, vol_name, capacity, provisioner_url, replicas, tenant_id, host, fstype, path

delete_volume_simple

Deletes one or more non-resilient volumes (it assumes that the volumes are connected to initiators and have a mounted file system).

ks_url, username, admin_password, expiration, vol_name, capacity, provisioner_url, replicas, tenant_id, host, fstype, path

install_host

Installs the KumoScale software on an application host (initiator) after verifying that the environment is compatible. Runs the service at the end of a successful installation.

Note: this does not support OpenID Connect authentication mode, but the ks_token.py modules support it. If you need to operate in the OIDC authentication mode, contact technical support for guidelines and assistance.

ks_url, username, password, provisioner_url, token_url, client_id, client_secretagent_rpm_path, agent_deb_path, hosts_group

uninstall_host

This playbook will uninstall the agent rpm and execute delete host (initiator) from the Provisioner. Uninstalls the KumoScale software client from an initiator.

hosts_group

Uses ks_host and ks_token modules

upgrade_host

Upgrades the KumoScale software client on an initiator t to a newer version.

agent_rpm_path, agent_deb_path, hosts_group

 1. Definition of capacity - KIOXIA Corporation defines a megabyte (MB) as 1,000,000 bytes, a gigabyte (GB) as 1,000,000,000 bytes and a terabyte (TB) as 1,000,000,000,000 bytes. A computer operating system, however, reports storage capacity using powers of 2 for the definition of 1Gbit = 230 bits = 1,073,741,824 bits, 1GB = 230 bytes = 1,073,741,824 bytes and 1TB = 240 bytes = 1,099,511,627,776 bytes and therefore shows less storage capacity. Available storage capacity (including examples of various media files) will vary based on file size, formatting, settings, software and operating system, and/or pre-installed software applications, or media content. Actual formatted capacity may vary. 

 

Next: Ansible Variable File