// vim: :set ft=asciidoc tw=70 fo-=a sw=8 ts=8 noet spell
[[ch-exos]]
== LINSTOR EXOS Integration

The https://www.seagate.com/support/raid-storage-systems/all-flash-and-disk-arrays/[EXOS]
storage manager from Seagate could be configured as one large block device managed by LINSTOR
like a local drive but this would prevent concurrent sharing of LINSTOR resources between
multiple servers out of the same pool.

LINSTOR integration with EXOS enables multiple server nodes to allocate and connect to
LINSTOR resources serviced by the same EXOS pool.
Thus all of the EXOS storage management features such as SSD/HDD tiering, SSD caching,
snapshots, and thin provisioning are available for LINSTOR resources and Kubernetes
Storage Classes.

After configuration, LINSTOR will dynamically map Resource replicas as LUNs
presented to server nodes through one of the two EXOS controllers.

Since the EXOS controllers are managed by a secure network API, LINSTOR must be configured
with proper networking and username/password combination.  The diagram below is
showing the relationship between LINSTOR cluster and EXOS Enclosures.

image::images/linstor-exos-integration.png[ExosIntegeration]

IMPORTANT: Multi-host setup allows up to 8 LINSTOR nodes to be directly
connected with 48Gbit SAS links for low latency and high throughput.

Load balancing and server failover are managed & enabled by LINSTOR while
volume creation is handled by the EXOS hardware RAID engine.

The EXOS storage provider in LINSTOR offers native integration with EXOS' REST-API.

This section will describe how to enable EXOS integration and configure
LINSTOR to manage storage backed by an EXOS enclosure.

EXOS storage systems offer a feature rich set of configuration options to match
any enterprise storage demand.  To maximize ease of use, this guide
is based on the following defaults and assumptions:

. Dual Controllers - EXOS systems controllers are Active/Active with automatic failover.
Both controllers IP address must be configured also in the LINSTOR properties for full support.

. Dual EXOS Pools - Optimal performance is achieved when data from pool A is
accessed through Controller A.  If a node is connected to both Controller A and B of
same controller, LINSTOR will configure Linux multipath which will detect best route.

. EXOS Pool Serial Numbers - When a EXOS pool is created, it receives a unique serial number.
Each one has to be configured as a backing storage in LINSTOR to create a link between EXOS
enclosure & LINSTOR. With that information, LINSTOR can understand if you are referring to
EXOS Pool A or Pool B.

. Creating EXOS Pools - The administrator is required to create EXOS Pools A and B prior to
configuring LINSTOR.  EXOS features such as thin provisioning, auto tiering, and snapshot options
are selected at this time.

. Replicas Within Enclosures - EXOS system have redundant controllers, power supplies and
communication paths to the drives. Some administrators may desire that resource replicas
are not stored in the same enclosure. In this case the administrator must create multiple
LINSTOR Pools configured with only one EXOS pool member from each enclosure.

=== EXOS Properties as a LINSTOR Storage Provider

LINSTOR's native integration with EXOS is configured by setting a few properties on the
LINSTOR Controller and creating the appropriate LINSTOR objects specific to your EXOS
enclosures, as described in the sections below.

The information in the table below is needed from your EXOS
enclosures. This information will be used to populate the
appropriate LINSTOR Controller properties and LINSTOR objects in the
sub-sections that follow.

.Required Information
[cols="2,5,2",opts="header,100%"]
|===
|*EXOS Information*|*Description*|*Placeholder in Command Examples*
|EXOS Enclosure Name|Uniquely selected by the Admin for a given EXOS enclosure|`<exos_encl_name>`
|Controller Hostname|The DNS resolvable hostname for one of the Controllers |`<exos_ctrlr_name>`
|Controller IP|IP address of controller |`<exos_ctrlr_ip>`
|REST-API Username|Username for REST-API of all EXOS controllers under the given enclosure|`<exos_rest_user>`
|REST-API Password|Password for REST-API of all EXOS controllers under the given enclosure|`<exos_rest_pass>`
|EXOS Pool Serial Number|The serial number of an EXOS pool to become a member of a LINSTOR Pool|`<exos_pool_sn>`
|===

=== Configuration Steps

Configuring a topology of LINSTOR server nodes and multiple EXOS Storage systems is described by these steps:

. Set global or unique EXOS Controller usernames and passwords.

. Define EXOS enclosures and Controller network identities.

. Create node to enclosure to pool mapping matching physical SAS cabling.



==== Step 1: EXOS Usernames and Passwords

Usernames and passwords can be unique for each EXOS enclosure or
be common for all enclosures depending on how the system administrator
has deployed the EXOS systems.
The default EXOS username and password will be used if not set for a given
EXOS controller.
The defaults are set as follows:

[bash]
----
# linstor exos set-defaults --username <exos_rest_name>
# linstor exos set-defaults --password <exos_rest_pass>
----

Unique usernames and passwords For EXOS controllers are set by:

[bash]
----
# linstor controller set-property
    StorDriver/Exos/<exos_encl_name>/username <exos_rest_name>
# linstor controller set-property
    StorDriver/Exos/<exos_encl_name>/Password <exos_rest_pass>
----

WARNING: Passwords entered in this fashion will
show up as plaintext when using `get-defaults`.

With the above command, LINSTOR will store your password in cleartext
in the LINSTOR properties and visible by a simple
`linstor controller list-properties` command. You can hide it under
an environment variable, and use the `UsernameEnv` and/or `PasswordEnv`
properties. This tells LINSTOR to look in environment variable for the
actual username/password, as shown in the following example:

IMPORTANT:  LINSTOR will not modify the environment variables, only read
from them. Storage admin has to make sure the env-vars are correctly set.

[bash]
----
# echo $EXOS_PW
mySecretPassword
# linstor controller set-property \
    StorDriver/Exos/<exos_encl_name>/PasswordEnv EXOS_PW
----

If both property-versions (i.e. `Password` and `PasswordEnv`) are set,
the non-environment version is preferred.

NOTE: If the satellite is started before the environment variable is
set, the satellite needs to be restarted in order to see the new
environment variable


==== Step 2: Define EXOS enclosures and controller identities.

Registering an EXOS enclosure in LINSTOR can be done with the `create`
command:

[bash]
----
# linstor exos create <exos_encl_name> <exos_ctrl_a_ip> [<exos_ctrl_b_ip>]
----

If no special `--username` or `--password` is given, the above mentioned
defaults are used.

The Controller's DNS name and IP address may be used interchangeably.

TIP: If you wish to use a hostname that is not DNS resolvable to
reference your EXOS enclosure within LINSTOR, you may use any name in
place of `<exos_hostname>`, but you will also have to supply the
enclosure's IP address: `linstor node create <desired_name> <enclosure_ip>`

Use the following example to create and inspect the current controller settings:

[bash]
----
# linstor exos create Alpha 172.16.16.12 172.16.16.13
# linstor exos list
+------------------------------------------------------------------+
| Enclosure | Ctrl A IP    | Ctrl B IP    | Health | Health Reason |
|==================================================================|
| Alpha     | 172.16.16.12 | 172.16.16.13 | OK     |               |
+------------------------------------------------------------------+
----

For a more in-depth view, you can always ask the LINSTOR controller
and/or the LINSTOR nodes for the `Exos`-related properties:

[bash]
----
# linstor controller list-properties | grep Exos
| StorDriver/Exos/Alpha/A/IP                | 172.16.16.12         |
| StorDriver/Exos/Alpha/B/IP                | 172.16.16.13         |
----


==== Step 3:  Create Node to Enclosure to Pool mapping.

A LINSTOR Satellite node can be created as usual.

[bash]
----
# linstor node create <satellite_hostname>
----

The storage pool can also be created as usual in LINSTOR. Only
the name of the previously registered EXOS enclosure as well as the
serial number of the EXOS pool needs to be specified:

[bash]
----
# linstor storage-pool create exos \
  <satellite_hostname> <linstor_pool_name> <exos_encl_name> <exos_pool_sn>
----

the linstor_pool_name can be set to (almost) any unique string for
the LINSTOR deployment.

Here is an example of mapping an EXOS Pool in EXOS enclosure Alpha to two Satellite nodes:

[bash]
----
# linstor storage-pool create exos \
   node1 poolA Alpha 00c0ff29a5f5000095a2075d01000000
# linstor storage-pool create exos \
   node2 poolA Alpha 00c0ff29a5f5000095a2075d01000000
----

After creating an `exos` storage pool the LINSTOR Satellite will scan
the given EXOS enclosure for connected ports. If cabled, these ports will be
listed in the following command:

[bash]
----
# linstor exos map -p
+----------------------------------------------+
| Node Name | Enclosure Name | Connected Ports |
|==============================================|
| node1     | Alpha          | A0, B0          |
| node2     | Alpha          | A1, B1          |
+----------------------------------------------+
----

The pool configuration is shown by:

[bash]
----
hr01u09:~ # linstor sp list -s poolA -p
+----------------------------------------------------------------------------------------------+
| StoragePool | Node  | Driver   | PoolName                               | FreeCapacity | ... |
|==============================================================================================|
| poolA       | node1 | EXOS     | Alpha_00c0ff29a5f5000095a2075d01000000 |      581 TiB | ... |
| poolA       | node2 | EXOS     | Alpha_00c0ff29a5f5000095a2075d01000000 |      581 TiB | ... |
+----------------------------------------------------------------------------------------------+
----

Detailed description of all the available EXOS commands is found with built in help.


[bash]
----
# linstor exos -h
----


=== Creating Resources Backed by EXOS Storage Pools

Creating LINSTOR resources from EXOS backed storage-pools follows
normal LINSTOR usage patterns as described in other sections of the
LINSTOR User's Guide such as the sections describing
<<s-linstor-resource-groups,LINSTOR resource groups>> or the more
granular
<<s-linstor-new-volume,resource-definition, volume-definition,
resource creation>> workflow.
