`LinstorSatelliteConfiguration`¶

This resource controls the state of one or more LINSTOR® satellites.

`.spec`¶

Configures the desired state of satellites.

`.spec.nodeSelector`¶

Selects which nodes the LinstorSatelliteConfiguration should apply to. If empty, the configuration applies to all nodes.

Example¶

This example sets the AutoplaceTarget property to no on all nodes labelled piraeus.io/autoplace: "no".

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: disabled-nodes
spec:
  nodeSelector:
    piraeus.io/autoplace: "no"
  properties:
    - name: AutoplaceTarget
      value: "no"

`.spec.nodeAffinity`¶

Selects which nodes the LinstorSatelliteConfiguration should apply to. If empty, the configuration applies to all nodes.

When this is used together with .spec.nodeSelector, both need to match in order for the configuration to apply to a node.

Example¶

This example sets the AutoplaceTarget property to no on all non-worker nodes:

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: disabled-nodes
spec:
  nodeAffinity:
    nodeSelectorTerms:
      - matchExpressions:
          - key: node-role.kubernetes.io/control-plane
            operator: Exists
  properties:
    - name: AutoplaceTarget
      value: "no"

`.spec.resourceNameSuffixSeparator`¶

Configures the separator inserted between generated Kubernetes resource names and the Satellite name.

Defaults to ., for example linstor-satellite.node1. Set to - to generate names such as linstor-satellite-node1. This only changes the inserted separator; dots that are part of the Kubernetes Node name remain unchanged.

Example¶

This example configures Satellite resources to use - between the base name and node name:

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: satellite-name-separator
spec:
  resourceNameSuffixSeparator: "-"

`.spec.properties`¶

Sets the given properties on the LINSTOR Satellite level.

The property value can either be set directly using value, inherited from the Kubernetes Node's metadata using valueFrom, or expanded from Kubernetes Node's metadata using expandFrom. Metadata fields are specified using the same syntax as the Downward API for Pods.

Using expandFrom allows for using field references matching more than one field. Either specify a field that is already a map (metadata.labels or metadata.annotations), or select a subset by using * at the end of a key. Using * will select the keys and values matching the prefix up to the * character. There are two ways to use expandFrom:

Setting a nameTemplate will create one property per matched field. The property name is generated by taking the name field and appending the expanded nameTemplate. nameTemplate supports the following expansions:
$1 is replaced with the field key, i.e. the part matched by the * character.
$2 is replaced with the value of the matched field.

The valueTemplate is expanded using the same replacements, and sets the property value. * Setting no nameTemplate will create one property using name. The value of the property is the joined expansion of the valueTemplate field for every matched field. See above for supported expansions. The result is joined using the optional delimiter value.

In addition, setting optional to true means the property is only applied if the value is not empty. This is useful in case the property value should be inherited from the node's metadata

Example¶

This examples sets the following Properties on every satellite:

PrefNic (the preferred network interface) is always set to default-ipv6
Aux/example-property (an auxiliary property, unused by LINSTOR itself) takes the value from the piraeus.io/example label of the Kubernetes Node. If a node has no piraeus.io/example label, the property value will be "".
AutoplaceTarget (if set to no, will exclude the node from LINSTOR's Autoplacer) takes the value from the piraeus.io/autoplace annotation of the Kubernetes Node. If a node has no piraeus.io/autoplace annotation, the property will not be set.
Aux/role/ copies all node-role.kubernetes.io/* label keys and values. For example, a worker node with the node-role.kubernetes.io/worker: "true" label will have Aux/role/worker set to "true".
Aux/features copies the names of all feature.example.com/* label keys to the value, joined by ,. For example, a node with feature.example.com/gpu and feature.example.com/storage will have Aux/features set to "gpu,storage".

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: ipv6-nodes
spec:
  properties:
    - name: PrefNic
      value: "default-ipv6"
    - name: Aux/example-property
      valueFrom:
        nodeFieldRef: metadata.labels['piraeus.io/example']
    - name: AutoplaceTarget
      valueFrom:
        nodeFieldRef: metadata.annotations['piraeus.io/autoplace']
      optional: yes
    - name: Aux/role/
      expandFrom:
        nodeFieldRef: metadata.labels['node-role.kubernetes.io/*']
        nameTemplate: "$1"
        valueTemplate: "$2"
    - name: Aux/features
      expandFrom:
        nodeFieldRef: metadata.labels['feature.example.com/*']
        valueTemplate: "$1"
        delimiter: ","

`.spec.storagePools`¶

Configures LINSTOR Storage Pools.

Every Storage Pool needs at least a name, and a type. Types are specified by setting a (potentially empty) value on the matching key. Available types are:

lvmPool: Configures a LVM Volume Group as storage pool.

Arguments: * volumeGroup: Set the name of the Volume Group to use. Defaults to using the storage pool name. * physicalVolumeCreateArguments: Additional arguments to pass to the pvcreate command. Only applies when the pool is first set up from a source. * volumeGroupCreateArguments: Additional arguments to pass to the vgcreate command. Only applies when the pool is first set up from a source. * lvmThinPool: Configures a LVM Thin Pool as storage pool.

Arguments: * volumeGroup: Set the name of the Volume Group to use. Defaults to using the storage pool name prefixed with linstor_. * thinPool: Set the name of the Thinpool Logical Volume to use. Defaults to using the storage pool name. * physicalVolumeCreateArguments: Additional arguments to pass to the pvcreate command. Only applies when the pool is first set up from a source. * volumeGroupCreateArguments: Additional arguments to pass to the vgcreate command. Only applies when the pool is first set up from a source. * logicalVolumeCreateArguments: Additional arguments to pass to the lvcreate command. Only applies when the pool is first set up from a source. * filePool: Configures a file system based storage pool. Configures a host directory as location for the volume files.

Arguments: * directory: Host directory used to store volume data. Defaults to using the /var/lib/linstor-pools/<storage pool name> directory. * fileThinPool: Configures a file system based storage pool. Behaves the same as filePool, except the files will be thinly allocated on file systems that support sparse files. Supports the same arguments as filePool. * zfsPool: Configure a ZFS ZPool as storage pool. Defaults to using the storage pool name as name for the zpool. Can be overridden by setting zPool.

Arguments: * zPool: Set the name of the zpool on the host. Defaults to the storage pool name. * zPoolCreateArguments: Additional arguments to pass to the zpool create command. Only applies when the pool is first set up from a source. * zfsThinPool: Configure a ZFS ZPool as storage pool. Behaves the same as zfsPool, except the contained zVol will be created using sparse reservation. Supports the same arguments as zfsPool.

Optionally, you can configure LINSTOR to automatically create the backing pools. source.hostDevices takes a list of raw block devices, which LINSTOR will prepare as the chosen backing pool.

Before registering a storage pool, the Operator probes the node to check whether the backing Volume Group or ZFS pool already exists:

If it exists, the storage pool is registered as-is. This also applies when source.hostDevices is set but the devices have already been prepared, so the backing pool is not created a second time.
If it does not exist and source.hostDevices is set, the backing pool is created from those devices. The Operator first verifies that the configured devices exist on the node, reporting any that are missing instead of letting the creation fail with an unclear error.
If it does not exist and no source is configured, the storage pool is not registered. Instead, the Configured condition of the LinstorSatellite reports that it is waiting for the backing pool to appear. Once you create the Volume Group or ZFS pool on the node, the storage pool is registered automatically on the next reconciliation. This prevents storage pools from getting stuck in the LINSTOR error state.

All storage pools also can also be configured with properties. Properties are set on the Storage Pool level. The configuration values have the same form as Satellite Properties.

Example¶

This example configures these LINSTOR Storage Pools on all satellites:

A LVM Pool named vg1. It will use the VG vg1, which needs to exist on the nodes already.
A LVM Thin Pool named vg1-thin. It will use the thin pool vg1/thin, which also needs to exist on the nodes.
A LVM Pool named vg2-from-raw-devices. It will use the VG vg2, which will be created on demand from the raw devices /dev/sdb and /dev/sdc if it does not exist already. In addition, it sets the StorDriver/LvcreateOptions property to -i 2, which causes every created LV to be striped across 2 PVs.
A LVM Thin Pool named thin-raid. It will use the thinpool linstor_thin-raid/thin-raid, which will be created on /dev/nvme0n2 and /dev/nvme0n3. The backing VG will have a physical extent size of 512KiB and the Thinpool LV striped across both devices.
A File System Pool named fs1. It will use the /var/lib/linstor-pools/fs1 directory on the host, creating the directory if necessary.
A File System Pool named fs2, using sparse files. It will use the custom /mnt/data directory on the host.
A ZFS Pool named zfs1. It will use ZPool zfs1, which needs to exist on the nodes already.
A ZFS Thin Pool named zfs2. It will use ZPool zfs-thin2, which will be created on demand from the raw device /dev/sdd.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: storage-satellites
spec:
  storagePools:
    - name: vg1
      lvmPool: {}
    - name: vg1-thin
      lvmThinPool:
        volumeGroup: vg1
        thinPool: thin
    - name: vg2-from-raw-devices
      lvmPool:
        volumeGroup: vg2
      source:
        hostDevices:
          - /dev/sdb
          - /dev/sdc
      properties:
        - name: StorDriver/LvcreateOptions
          value: '-i 2'
    - name: thin-raid
      lvmThinPool:
        volumeGroupCreateArguments: ["-s", "512KiB"]
        logicalVolumeCreateArguments: ["-i", "2"]
      source:
        hostDevices:
          - /dev/nvme0n2
          - /dev/nvme0n3
    - name: fs1
      filePool: {}
    - name: fs2
      fileThinPool:
        directory: /mnt/data
    - name: zfs1
      zfsPool: {}
    - name: zfs2
      zfsThinPool:
        zPool: zfs-thin2
      source:
        hostDevices:
        - /dev/sdd

`.spec.internalTLS`¶

Configures a TLS secret used by the LINSTOR Satellites to:

Validate the certificate of the LINSTOR Controller, that is the Controller must have certificates signed by ca.crt.
Provide a server certificate for authentication by the LINSTOR Controller, that is tls.key and tls.crt must be accepted by the Controller.

To configure TLS communication between Satellite and Controller, LinstorCluster.spec.internalTLS must be set accordingly.

Setting a secretName is optional, it will default to <node-name>-tls, where <node-name> is replaced with the name of the Kubernetes Node.

Optional, a reference to a cert-manager Issuer can be provided to let the operator create the required secret.

Example¶

This example creates a manually provisioned TLS secret and references it in the LinstorSatelliteConfiguration, setting it for all nodes.

---
apiVersion: v1
kind: Secret
metadata:
  name: my-node-tls
  namespace: piraeus-datastore
data:
  ca.crt: LS0tLS1CRUdJT...
  tls.crt: LS0tLS1CRUdJT...
  tls.key: LS0tLS1CRUdJT...
---
apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: satellite-tls
spec:
  internalTLS:
    secretName: my-node-tls

Example¶

This example sets up automatic creation of the LINSTOR Satellite TLS secrets using a cert-manager issuer named piraeus-root.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: satellite-tls
spec:
  internalTLS:
    certManager:
      kind: Issuer
      name: piraeus-root

`.spec.deletionPolicy`¶

Configure how Satellite removal is handled. Possible policies are:

Retain, the default policy if not set. This policy will cause the Satellite to remain registered in LINSTOR when the LinstorSatellite resource is removed.
Evacuate. This policy will cause the Satellite to be evacuated, i.e. all deployed resources will be moved to a replacement node. This requires spare capacity in the cluster. Deletion will only succeed if all resources have been moved off the node.
Delete. This policy causes the Satellite to be forcefully removed from the Cluster. All Kubernetes resources will be removed, and the node will be removed from LINSTOR without regard for replica integrity.

Example¶

This example sets the deletion policy of LINSTOR Satellites to Evacuate.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: satellite-deletion-policy
spec:
 deletionPolicy: Evacuate

`.spec.evacuationStrategy`¶

Configure timeouts for Satellite Evacuation. To have any effect, deletionPolicy: Delete is required.

attachedVolumeReattachTimeout: sets the duration the evacuation waits for volumes that were attached before draining the Node to be attached on a new node. Defaults to 5 minutes. Can be set to 0 to disable waiting.
unattachedVolumeAttachTimeout: sets the duration the evacuation waits for volumes that were not attached before draining the Node to be attached on a new node. Defaults to 5 minutes. Can be set to 0 to disable waiting.

Example¶

This example sets the re-attach timeout for volumes attached to the node being evacuated to one hour, and the timeout for volumes not currently attached to 30 minutes.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: evacuation-timeout
spec:
  deletionPolicy: Evacuate
  evacuationStrategy:
    attachedVolumeReattachTimeout: "1h"
    unattachedVolumeAttachTimeout: "30m"

`.spec.ipFamilies`¶

Configures the IP Family (IPv4 or IPv6) to use to connect to the LINSTOR Satellite.

If unset, the LINSTOR Controller will attempt to reach the LINSTOR Satellite via all recognized addresses in the Satellite Pods' Status. If set, the LINSTOR Controller will only attempt to reach the LINSTOR Satellite via all addresses matching the listed IP Families.

Valid values are IPv4 and IPv6.

Example¶

This example configures the LINSTOR Controller to only use IPv4, even in a dual stack cluster.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: ipv4-only
spec:
  ipFamilies:
  - IPv4

`.spec.podTemplate`¶

Configures the Pod used to run the LINSTOR Satellite.

The template is applied as a patch (see .spec.patches) to the default resources, so it can be "sparse".

Example¶

This example configures a resource request of cpu: 100m on the satellite, and also enables host networking.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: resource-and-host-network
spec:
  podTemplate:
    spec:
      hostNetwork: true
      containers:
        - name: linstor-satellite
          resources:
            requests:
              cpu: 100m

`.spec.patches`¶

The given patches will be applied to all resources controlled by the operator. The patches are forwarded to kustomize internally, and take the same format.

The unpatched resources are available in the subdirectories of the pkg/resources/satellite directory.

Warning¶

No checks are run on the result of user-supplied patches: the resources are applied as-is. Patching some fundamental aspect, such as removing a specific volume from a container may lead to a degraded cluster.

Example¶

This example configures the LINSTOR Satellite to use the "TRACE" log level, creating very verbose output.

apiVersion: piraeus.io/v1
kind: LinstorSatelliteConfiguration
metadata:
  name: all-satellites
spec:
  patches:
    - target:
        kind: ConfigMap
        name: satellite-config
      patch: |-
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: satellite-config
        data:
          linstor_satellite.toml: |
            [logging]
              linstor_level = "TRACE"

`.status`¶

Reports the actual state of the cluster.

`.status.conditions`¶

The Operator reports the current state of the Satellite Configuration through a set of conditions. Conditions are identified by their type.

`type`	Explanation
`Applied`	The given configuration was applied to all `LinstorSatellite` resources.

LinstorSatelliteConfiguration¶

.spec¶

.spec.nodeSelector¶

Example¶

.spec.nodeAffinity¶

Example¶

.spec.resourceNameSuffixSeparator¶

Example¶

.spec.properties¶

Example¶

.spec.storagePools¶

Example¶

.spec.internalTLS¶

Example¶

Example¶

.spec.deletionPolicy¶

Example¶

.spec.evacuationStrategy¶

Example¶

.spec.ipFamilies¶

Example¶

.spec.podTemplate¶

Example¶

.spec.patches¶

Warning¶

Example¶

.status¶

.status.conditions¶

`LinstorSatelliteConfiguration`¶

`.spec`¶

`.spec.nodeSelector`¶

`.spec.nodeAffinity`¶

`.spec.resourceNameSuffixSeparator`¶

`.spec.properties`¶

`.spec.storagePools`¶

`.spec.internalTLS`¶

`.spec.deletionPolicy`¶

`.spec.evacuationStrategy`¶

`.spec.ipFamilies`¶

`.spec.podTemplate`¶

`.spec.patches`¶

`.status`¶

`.status.conditions`¶