View source for Resource Group Services (Multitenancy)

This page explains how to run a containerized service (eg. SFTP, FTP, Nextcloud, Resilio, RabbitMQ or Valkey) against the network shares of a [[Create Resource Group|Resource Group]]. QuantaStor runs each service in a container, gives it the group's shares, publishes its ports only on the group's network, and moves it with the storage pool when an HA pool fails over.

{| class="wikitable"
! Section !! Purpose
|-
| [[#How resource group services work|How resource group services work]] || Service Configs, shares, binding network and pool scope
|-
| [[#Available services|Available services]] || The services you can run and their default ports
|-
| [[#Before you start|Before you start]] || Shares, addresses and ports to have ready
|-
| [[#Step 1: Create the Service Config|Step 1]], [[#Step 2: Create the resource group|Step 2]], [[#Step 3: Add the network shares|Step 3]] || The workflow, start to finish
|-
| [[#Adding or changing services on an existing group|Adding or changing services]] || Changing the services on a group that already exists
|-
| [[#CLI equivalents|CLI equivalents]] || The same workflow from the {{Code|1=qs}} CLI
|-
| [[#Troubleshooting|Troubleshooting]] || A service that does not start or cannot be reached
|}

== How resource group services work ==

A resource group set up for service container management ties together three things:

* '''Service Configs''' -- one per service, holding that service's settings (user name, password, port and so on). A group can hold one Service Config of each service type.
* '''Network shares''' -- the data the service works on. Each share in the group is bind-mounted into the service's container.
* '''A binding network''' -- a subnet in CIDR form. The service's ports are published only on the appliance addresses inside that subnet, so a client on another network cannot reach it. Two resource groups cannot bind the same subnet.

The group's '''Storage Pool Scope''' decides which addresses count and where the service keeps its state:

{| class="wikitable"
! Scope !! Service binds to !! Service state lives on
|-
| Local Storage Pool(s) || physical network ports in the binding subnet || the appliance's local container directory
|-
| HA Storage Pool || HA virtual interfaces (VIFs) in the binding subnet || the HA storage pool itself, so it moves with the pool
|}

Because state for an HA-scoped group lives on the pool, settings such as the SFTP host keys survive a container restart, an upgrade and an HA failover. When the pool fails over, QuantaStor stops the group's containers on the old owner, imports the pool on the new owner and starts the containers there from the same state.

[[File:havif_overview.png|thumb|right|800px|The High-availability VIF Management tab. An HA-scoped resource group publishes its services only on an HA virtual interface whose address is in the group's binding subnet.]]

{{Note|'''An HA-scoped group needs an HA virtual interface in its subnet.''' For a group scoped to an HA Storage Pool, QuantaStor publishes the service only on a [[High-availability VIF Management|virtual interface]] of that pool whose address falls inside the group's binding subnet. If the pool has no such VIF, the service does not start. The resource group is still created and no error appears in the web interface; the only sign is a warning in the service log that it could not determine a bind address. Create the VIF before you add the service. This applies to every service type.}}

== Available services ==

We are adding new containerized services with each new release of QuantaStor but those offered at the time of this writing include '''Service Type''' of:

{| class="wikitable"
! Service !! What it is for !! Default port(s)
|-
| SFTP Module || SFTP access to the group's shares for one account, confined (chrooted) to those shares || 2222
|-
| FTP Service || FTP access to the group's shares for one account, with optional passive mode || 20, 21
|-
| Nextcloud || Web file sharing and sync; the group's shares appear as Nextcloud External Storage || 8081 (HTTP)
|-
| Resilio Agent || A Resilio Connect agent that synchronizes the group's shares || --
|-
| RabbitMQ Message Broker || An AMQP message broker with its management console, keeping its data on a share || 5672 (AMQP), 15672 (management)
|-
| Valkey Data Store || A Redis-compatible key-value store that persists to a share || 6379
|}

The SFTP, Nextcloud, RabbitMQ and Valkey services are defined by service definition files ({{Code|1=qs_containerhandler_<service>.conf}}) in {{Code|1=/opt/osnexus/quantastor/conf/}}, and their form fields come from those files. Additional definitions for MinIO, Globus Connect Server and a demonstration FTP module ship as {{Code|1=.example}} files and are not offered unless enabled. To build a service of your own, see [[Developing Service Containers]].

== Before you start ==

* Create the [[Network Shares|network shares]] the service will use. For an HA-scoped group, the shares must be on that HA pool; for a local group, on a local pool. QuantaStor refuses a share that is outside the group's scope.
* Make sure the appliance has an address in the subnet clients will use -- a physical port for a local group, or an HA virtual interface on the pool for an HA group (see the note above).
* Pick a port that nothing else on the appliance uses. Do not give Nextcloud port 8080, which the QuantaStor web interface uses, and do not give SFTP port 22, which the appliance's own SSH service uses.

== Step 1: Create the Service Config ==

{{Navigation|Multitenancy &rarr; Services ''(section)'' &rarr; Services ''(toolbar group)'' &rarr; Create Config ''(toolbar)''}}

You can also right-click in the '''Services''' section, or on a resource group, and choose '''Create Service Config...'''.

* '''Name''' -- a name for this configuration. The default is {{Code|1=service-config-N}}.
* '''Service Type''' -- the service to run, from the table above.
* '''Service Configuration Options''' -- the settings for the chosen service. This part of the dialog changes with the service type.

For the SFTP, Nextcloud, RabbitMQ and Valkey services, the options form is built from the service definition, so the fields differ from service to service. The common kinds are:

* '''User name and password''' for the account the service creates. Passwords are kept out of the service log and out of the options file the service reads. A password field never shows a default.
* '''Port''' -- a number field with a default and an allowed range.
* '''Check boxes''' for on/off settings, such as Valkey's append-only persistence.
* '''File uploads''' for keys and certificates, such as an SFTP public key or host key.
* '''Data share''' -- for Nextcloud and Valkey, which share holds the service's own data.
* An '''Advanced Settings''' group on some services. On SFTP it holds '''read-only''' access and the UID and GID that own files written through the service.

Fields the definition marks as mandatory are checked when you click '''OK'''; the form does not mark them in advance. If one is empty, the dialog reports that one or more mandatory service option fields are empty. An optional field you leave empty takes the service's default.

For the SFTP service, you must supply a password, a public key, or both. Setting read-only makes QuantaStor mount the shares read-only into the container, so clients cannot write even if the service itself would allow it. SFTP is the only service with a read-only option.

The '''FTP Service''' has fixed fields: '''FTP Username''', '''FTP Password''' and '''Repeat Password'''. Tick '''Use FTP Passive Mode''' to let clients open passive data connections; you then have to fill in the '''Passive Port Range''' (any range within 1-65535) and the '''Passive IP Address''' to advertise to clients. Passive mode is off by default.

The '''Resilio Agent''' takes an '''Agent Name''' and a '''Sync File''', both required.

Click '''OK'''. The Service Config appears in the '''Services''' section; it does nothing until you add it to a resource group.

== Step 2: Create the resource group ==

{{Navigation|Multitenancy &rarr; Resource Groups ''(section)'' &rarr; Resource Group ''(toolbar group)'' &rarr; Create ''(toolbar)''}}

The [[Create Resource Group]] page covers every tab of this dialog. For a service group:

# On the '''General''' tab, enter a '''Name''' and, optionally, a '''Description''' and '''Organization'''. Under '''Select Resource Group Use Case''', choose '''Service Container Management'''. This enables the '''Service Configs''' tab.
# On the '''Service Configs''' tab, under '''Binding Network Address Setting''', choose the '''Subnet w/CIDR''' the service listens on. The list shows the subnets on the appliance's network ports, minus any already bound to another resource group.
# Under '''Storage Pool Scope''', choose '''Local Storage Pool(s)''' or '''HA Storage Pool'''. For an HA scope, select the pool in the '''Storage Pool''' list.
# Select the Service Config you created in Step 1 in the grid.
# Click '''OK'''.

If the appliance has no subnet that is not already bound to a resource group, the dialog reports that there are no available subnets. Give a network port an address on a new subnet, then try again.

To add more binding subnets later, select the group and use '''Add Network Association''' on the toolbar.

== Step 3: Add the network shares ==

{{Navigation|Multitenancy &rarr; Resource Groups ''(section)'' &rarr; Resource Group ''(toolbar group)'' &rarr; Add/Remove Shares ''(toolbar)''}}

Move the shares the service should see into '''Select Network Shares for Resource Group Assignment''' and click '''OK'''. See [[Add Remove Resources Group Network Shares]].

Each share is bind-mounted into the container. Where it lands depends on the service: SFTP users see each share as a folder in their home directory, and Nextcloud shows them as External Storage.

== Adding or changing services on an existing group ==

{{Navigation|Multitenancy &rarr; Resource Groups ''(section)'' &rarr; Resource Group ''(toolbar group)'' &rarr; Add/Remove Service Configs ''(toolbar)''}}

Select the resource group, then select the Service Configs it should have. The selection replaces the group's list, so a config you clear is removed. A group can hold only one Service Config of each service type; selecting two of the same type is refused.

Removing a Service Config that is in use requires '''Force''', which stops the service. See [[Add/Add Remove Resources Group Service Configs]].

To delete a Service Config, use '''Delete Config''' in the '''Services''' toolbar group; see [[Service Config Delete]].

== CLI equivalents ==

List the installed service definitions and their tags with <code>[[QuantaStor CLI Command Reference#service-def-list|qs service-def-list]]</code>. Create a Service Config with <code>[[QuantaStor CLI Command Reference#service-config-create|qs service-config-create]]</code>, passing the definition tag and the options as a comma-separated key=value list. For example, an FTP config:

<pre style="font-size: smaller">
qs service-config-create --name=ftp-config1 --service-definition-tag=vsftp --service-config-options-list=ftp_user=ftpuser1,ftp_pass=aAbBcCdDeEfF
</pre>

Create a service group with <code>[[QuantaStor CLI Command Reference#resource-group-create|qs resource-group-create]]</code>, giving the binding subnet with {{Code|1=--network-list}} and the scope with {{Code|1=--scope-type}} ({{Code|1=local}} or {{Code|1=HA}}) and {{Code|1=--scope}} (the pool). Add shares and Service Configs with <code>[[QuantaStor CLI Command Reference#resource-group-resource-add|qs resource-group-resource-add]]</code>, using the {{Code|1=share}} and {{Code|1=service_config}} resource types:

<pre style="font-size: smaller">
qs resource-group-resource-add --resource-group=rg-sftp --resource-list=share1:share,sftp-config1:service_config
</pre>

== Troubleshooting ==

* '''The service does not start in an HA-scoped group.''' Check that the HA pool has a virtual interface with an address in the group's binding subnet, on the node that currently owns the pool. Without one, QuantaStor has no address to publish the service on.
* '''Clients cannot connect.''' Connect to an appliance address inside the group's binding subnet -- for an HA group, the VIF address. The service is not published on other addresses. Check the port too: the services use their own defaults (for example 2222 for SFTP), not the protocol's usual port.
* '''A share is refused when added.''' The share is on a pool outside the group's scope. Move the share, or create a group scoped to the share's pool.

== Related pages ==

* [[Create Resource Group]]
* [[Modify Resource Group]]
* [[Service Config Create]]
* [[Service Config Delete]]
* [[Add/Add Remove Resources Group Service Configs]]
* [[Add Remove Resources Group Network Shares]]
* [[High-availability VIF Management]]
* [[Network Shares]]
* [[Developing Service Containers]]

----
<small>''Verified against QuantaStor 6.9.0.''</small>

[[Category:admin_guide]]