Quick-start - Containers

Note

  • Please replace 4.1.0-1.c1 with the desired version in the following steps.

1 Register with the Virtalica software and downloads portal

To gain access to StorageFabric documentation and software, register at https://content.virtalica.com.

2 Download and install the StorageFabric software

Choose to either download and install the rpm, or to download and extract the tar file.

RPM

2a Download the StorageFabric rpm

curl -s -S -u USERNAME URL --output storagefabric-4.1.0-1.c1.x86_64.rpm

In the above commands, replace USERNAME with your registered user name with https://content.virtalica.com. Replace URL based on your selected distribution:

RedHat 8.x

https://repos.virtalica.com/fabric/enterprise/rhel/8/x86_64/storagefabric-4.1.0-1.c1.x86_64.rpm

Rocky 8.x

https://repos.virtalica.com/fabric/enterprise/rocky/8/x86_64/storagefabric-4.1.0-1.c1.x86_64.rpm

Enter your password when prompted to download the software.

2b Import StorageFabric RPM-GPG key

Download the repository key using the below command based on your distribution:

RedHat

curl "https://repos.virtalica.com/fabric/enterprise/rhel/RPM-GPG-KEY-StorageFabric" \
  -u USERNAME > /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric

Rocky

curl "https://repos.virtalica.com/fabric/enterprise/rocky/RPM-GPG-KEY-StorageFabric" \
  -u USERNAME > /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric

In the above commands, replace USERNAME with your registered user name. You will be prompted to enter the password.

Import the repository key.

rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-StorageFabric

2c Install the StorageFabric rpm

The below command will create a directory /opt/storagefabric-4.1.0-1.c1/ which contains the files necessary for running StorageFabric containers.

rpm -i storagefabric-4.1.0-1.c1.x86_64.rpm

TAR

2a Download the StorageFabric tar

First, set your working directory to where you’d like the tar file stored. Then, download the tar file by using the below command.

curl -O -u USERNAME https://repos.virtalica.com/fabric/enterprise/files/storagefabric-4.1.0-1.c1.tar.gz

In the above commands, replace USERNAME with your registered user name. You will be prompted to enter the password.

The -O flag will result in the downloaded tar file having the same name as on the remote server, which is storagefabric-4.1.0-1.c1.tar.gz

2b Create directory

A new directory needs to be created, which will be used in the next step to hold the extracted tar contents.

sudo mkdir -p /opt/storagefabric-4.1.0-1.c1

2c Extract tar

While in the directory with the tar downloaded in the first step, run the below command to extract its contents to the /opt/storagefabric-4.1.0-1.c1 directory.

tar -xvzf storagefabric-4.1.0-1.c1.tar.gz -C /opt/storagefabric-4.1.0-1.c1

The /opt/storagefabric-4.1.0-1.c1 directory now contains everything needed to start running containers.

Note

After this point, all steps will be the same, regardless of which option (rpm or tar) you selected.

3 Import the StorageFabric container image

Run the below command to make the image available to your container manager.

Docker

docker load < /opt/storagefabric-4.1.0-1.c1/storagefabric-docker-image-4.1.0-1.c1.tar.gz

Podman

podman load < /opt/storagefabric-4.1.0-1.c1/storagefabric-docker-image-4.1.0-1.c1.tar.gz

4 Create volumes

Although you can use bind mounts, we recommend using volumes instead. Volumes are more portable, allow the use of alternative storage drivers (such as NFS), and do not require uid/gid mapping.

Create volumes for StorageFabric containers as shown below.

Note

If your use case requires uid/gid, please set uid=997 and gid=995.

Docker Volumes

Configuration Manager & Gateway

docker volume create storagefabric-logs

docker volume create storagefabric-conf

# Update the size to match your needs
docker volume create storagefabric-cm-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

docker volume create storagefabric-gw-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Configuration Manager only

docker volume create storagefabric-logs

docker volume create storagefabric-conf

# Update the size to match your needs
docker volume create storagefabric-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Gateway only

docker volume create storagefabric-logs

docker volume create storagefabric-conf

# Update the size to match your needs
docker volume create storagefabric-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Podman Volumes

Note

If using Podman on RHEL, be advised that the size option is only supported on file systems that were mounted with prjquota enabled. If an error is encountered, see xfs_quota(8) man page.

Configuration Manager & Gateway

podman volume create storagefabric-logs

podman volume create storagefabric-conf

# Update the size to match your needs
podman volume create storagefabric-cm-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

podman volume create storagefabric-gw-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Configuration Manager only

podman volume create storagefabric-logs

podman volume create storagefabric-conf

# Update the size to match your needs
podman volume create storagefabric-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

Gateway only

podman volume create storagefabric-logs

podman volume create storagefabric-conf

# Update the size to match your needs
podman volume create storagefabric-memstore \
    --opt type=tmpfs --opt device=tmpfs --opt o=size=256m

5 Set up the StorageFabric configuration

Enable which StorageFabric components are running within a container by setting the file /opt/storagefabric-4.1.0-1.c1/storagefabric/storagefabric.env on the host. For example, to enable only the StorageFabric Gateway, use:

STORAGEFABRIC_CONFIGURATION_MANAGER_ENABLED=false
STORAGEFABRIC_GATEWAY_ENABLED=true

Then, change your StorageFabric configuration by editing the configuration files on the host:

Configuration Manager

Minimum configuration options that need to be set in /opt/storagefabric-4.1.0-1.c1/storagefabric/configuration_manager.yml:

################################# SYNC CONFIGURATION #################################

storagefabric_cm_sync:
  #***
  #*  StorageFabric Master Encryption Key.
  #*
  #*  To generate a new Master Encryption Key, use one of the following:
  #*
  #*  * storagefabric-keygen --master-encryption-key
  #*
  #*  * echo $(openssl rand -hex 32)$(printf %X $(date +%s)) | tr '[:lower:]' '[:upper:]'
  #*
  #*  * Generate using your enterprise KMS.
  master_encryption_key: ""
  configuration:
    #***
    #* Base url for the provider's s3 endpoint. E.g., s3.amazonaws.com
    provider_url:      ""
    #***
    #* API type can be one of s3, s3_v4, azure.
    #* provider_region must be specified if API type is s3_v4.
    provider_api_type: ""
    #***
    #* Bucket where StorageFabric configuration data is stored.
    bucket:            ""
    #***
    #* Access Key id. Used by StorageFabric to access the configuration bucket.
    access_key_id:     ""
    #***
    #* Secret Access Key corresponding to .
    secret_access_key: ""

storagefabric_cm_configuration:
  views:
    #***
    #* View name
    - name: default
      #***
      #* Use one of:
      #*
      #* - provide a known View encryption key
      #*
      #* - generate a new one with one of:
      #*
      #*    * storagefabric-keygen --view-encryption-key
      #*
      #*    * echo $(openssl rand -hex 32)$(printf %X $(date +%s)) | tr '[:lower:]' '[:upper:]'
      encryption_key: ""
  users:
    #***
    #* Define users for the StorageFabric WEB UI.
    - name: admin
      password: ""

#################################### LICENSE ################################

#***
#* Entire license in PEM format. The license will be saved in the file.
#* /etc/storagefabric/licenses/license_ansible.pem.
#* The license contents pasted below should be formatted such that
#* it starts with a space, then a pipe (vertical line), with your
#* license contents pasted directly below that. Each line of the license
#* should be prepended by two spaces. Example:
#* storagefabric_license: |
#*   -----BEGIN CERTIFICATE-----
#*   MIOPkTCCA3mgAgIBAgIUKvJ+4taG07SCKEYdOJjJRj0/khkwDQYJKoZIhvcNAQEL
#*   BQAwVzELMAkGs1UEBhMCVVMxCzAJBgNVBAgMAk5ZMRcwFQMNAQQKDA5WaXJ0YWxp
#*   ...
storagefabric_license: |

############################# OTHER WEB SETTINGS ###############################

# To generate the following keys, use the command: openssl rand -hex 50
storagefabric_cm_django_web_secret_key: ""
storagefabric_cm_django_system_web_secret_key: ""

Gateway

Minimum configuration options that need to be set in /opt/storagefabric-4.1.0-1.c1/storagefabric/gateway.yml:

################################# SYNC CONFIGURATION #################################

storagefabric_gw_sync:
  view:
    #***
    #* View name
    name: default
    #***
    #* Use one of:
    #*
    #* - provide a known View encryption key
    #*
    #* - generate a new one with one of:
    #*
    #*    * storagefabric-keygen --view-encryption-key
    #*
    #*    * echo $(openssl rand -hex 32)$(printf %X $(date +%s)) | tr '[:lower:]' '[:upper:]'
    encryption_key: ""
  configuration:
    #***
    #* Base url for the provider's s3 endpoint. E.g., s3.amazonaws.com
    provider_url: ""
    #***
    #* API type can be one of s3, s3_v4, azure.
    #* provider_region must be specified if API type is s3_v4.
    provider_api_type: ""
    #***
    #* Bucket where StorageFabric configuration data is stored.
    bucket:            ""
    #***
    #* Access Key id. Used by StorageFabric to access the configuration bucket.
    access_key_id:     ""
    #***
    #* Secret Access Key corresponding to .
    secret_access_key: ""

Note

For detailed help and a complete list of all configuration options, refer to the StorageFabric Ansible roles documentation:

6 Run the StorageFabric Container

Note

For optimal network performance, running containers in host network mode is strongly recommended.

Virtualized networking can be used instead by replacing --network host with -p [port]:[port] in the following commands.

For more details, see the documentation:

Docker

Podman

Docker Run

Configuration Manager & Gateway

docker run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-cm-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
    -v storagefabric-gw-memstore:/etc/storagefabric/gateway/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --cap-add CAP_NET_ADMIN \
    --ulimit nofile=17000:17000 \
    virtalica/storagefabric:4.1.0-1.c1

Configuration Manager only

docker run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --ulimit nofile=17000:17000 \
    virtalica/storagefabric:4.1.0-1.c1

Gateway only

docker run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-memstore:/etc/storagefabric/gateway/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --cap-add CAP_NET_ADMIN \
    --ulimit nofile=17000:17000 \
    virtalica/storagefabric:4.1.0-1.c1

Podman Run

Configuration Manager & Gateway

podman run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-cm-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
    -v storagefabric-gw-memstore:/etc/storagefabric/gateway/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --cap-add CAP_NET_ADMIN \
    --cap-add=CAP_AUDIT_WRITE \
    --ulimit nofile=17000:17000 \
    localhost/virtalica/storagefabric:4.1.0-1.c1

Configuration Manager only

podman run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-memstore:/etc/storagefabric/configuration-manager/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --cap-add=CAP_AUDIT_WRITE \
    --ulimit nofile=17000:17000 \
    localhost/virtalica/storagefabric:4.1.0-1.c1

Gateway only

podman run -d --network host \
    --name "storagefabric" \
    -v storagefabric-logs:/var/log/storagefabric:Z \
    -v storagefabric-conf:/etc/storagefabric:Z \
    -v storagefabric-memstore:/etc/storagefabric/gateway/memstore:Z \
    -v /opt/storagefabric-4.1.0-1.c1/storagefabric:/storagefabric:ro \
    --cap-add CAP_NET_ADMIN \
    --cap-add=CAP_AUDIT_WRITE \
    --ulimit nofile=17000:17000 \
    localhost/virtalica/storagefabric:4.1.0-1.c1

Note

  • The capability CAP_NET_ADMIN is required for StorageFabric’s the full product documentation. Certain gateway services in the container will fail to start without this capability.

  • The capability CAP_AUDIT_WRITE is required on RedHat for Audit system logging to function properly.

  • The option --ulimit nofile=17000:17000 specifies the hard and soft limit of open files that are consistent with StorageFabric default settings.

Note

Kernel-level settings for container should be configured on the host. For more information, see Configuring kernel parameters at runtime.

fs.inotify.max_user_instances

  1. Edit /etc/sysctl.conf and add the following line: fs.inotify.max_user_instances=256.

  2. Execute the following command to load the new settings: sudo sysctl -p

fs.inotify.max_user_instances should be at least twice the number of logical cores for Gateways. See the full product documentation.

Note

SELinux settings on the host need updates to let certain StorageFabric features work properly on the container.

QoS

To let the the full product documentation feature work on the container if using Podman and if SELinux is enabled on the host, please run the following command on the host:

setsebool -P domain_kernel_load_modules 1

Note

To run the container in the foreground, remove the -d option.

Note

Logs from within the container can be retrieved using the below commands.

Docker

# stdout and stderr
docker logs [-f] storagefabric

# Configuration logs
docker exec -it storagefabric bash -c 'cat /var/log/storagefabric/ansible/ansible*log'

The -f flag can be used to follow the container output

Podman

# stdout and stderr
podman logs [-f] storagefabric

# Configuration logs
podman exec -it storagefabric bash -c 'cat /var/log/storagefabric/ansible/ansible*log'

The -f flag can be used to follow the container output

Wait a few moments for StorageFabric to start up before connecting to the StorageFabric Configuration Manager or StorageFabric Gateway.

Using StorageFabric

Once the StorageFabric container is running, use the endpoints described in the following table:

Endpoint

Description

http://localhost:5600

The StorageFabric Configuration Manager web interface and API endpoint. To login to the web interface, use the user admin and the password that you set in configuration_manager.yml.

http://localhost:8080

The StorageFabric Gateway endpoint. Use this endpoint for unified S3 data operations across all backend providers.

Next Step