Usage

Cluster creation

Create SaunaFS cluster resource. For description and more fields check SaunafsCluster CRD.

apiVersion: saunafs.sarkan.io/v1beta1
kind: SaunafsCluster
metadata:
  name: saunafs-cluster
  namespace: saunafs-operator
spec:
  pvSelectors:
    metadataStorage: example-cluster=metadata
    chunkStorage: example-cluster=chunks
  pvcSelectors:
    metadataStorage: example-cluster=metadata
    chunkStorage: example-cluster=chunks

Display saunafs cluster information:

kubectl get saunafscluster saunafs-cluster --namespace saunafs-operator

For SaunaFS cluster to work you must create at least one Metadata volume and one Chunk volume. Create metadata and chunk volumes using one of below methods.

• Labeling persistent volumes
• Labeling persistent volume claims
• Manual volumes creation

TIP

Metadata servers should be on different nodes for better failure tolerance. Metadata server node is chosen by kube-scheduler based on PVC used by metadata volume, so it's recommended to set proper node affinity for PVC used for metadata volumes.

WARNING

Two SaunaFS clusters shouldn't have same pvSelectors in cluster nor same pvcSelectors in single namespace.

SaunaFS volumes creation from persistent volumes

When both PV and PVC selectors are defined in SaunaFS Cluster resource, you can label PV to automatically create a labeled PVC that SaunaFS component will then use:

1. List available persistent volumes:

   kubectl get persistentvolume
   

2. Add label to persistent volume

   kubectl label pv <pv_name>... <pv_selector>
   

3. Display created volumes status

   kubectl get saunafschunkvolumes,saunafsmetadatavolumes
   

SaunaFS volumes creation from persistent volume claims

If you've configured the PVC selector in SaunaFS Cluster resource, you can use it to label PVC that SaunaFS component will then use

1. List available persistent volume claims:

   kubectl get persistentvolumeclaims
   

2. Add label to persistent volume claim

   kubectl label pvc <pvc_name>... <pvc_selector>
   

3. Display created volumes status

   kubectl get saunafschunkvolumes,saunafsmetadatavolumes
   

Manual SaunaFS volumes creation

You can manually create SaunaFS volumes using arbitrary PVC.

1. Create SaunaFS Metadata Volume and SaunaFS Chunk Volume resources with properly set persistent volume claim name.
   • clusterName - Name of the SaunaFS cluster this metadata volume belongs to.
   • persistentVolumeClaimName - name of the PVC to use

   apiVersion: saunafs.sarkan.io/v1beta1
   kind: SaunafsMetadataVolume
   metadata:
     name: example-metadata-volume
     namespace: saunafs-operator
   spec:
     clusterName: saunafs-cluster
     persistentVolumeClaimName: pvc-1
   ---
   apiVersion: saunafs.sarkan.io/v1beta1
   kind: SaunafsChunkVolume
   metadata:
     name: example-chunks-volume
     namespace: saunafs-operator
   spec:
     clusterName: saunafs-cluster
     persistentVolumeClaimName: pvc-2
   

WARNING

SaunaFS Volumes must be in the same namespace as cluster to which they're assigned.

SaunaFS resources status

You can check status of all SaunaFS resources in namespace using kubectl:

kubectl get saunafsmetadatavolumes,saunafschunkvolumes,saunafsclusters --namespace saunafs-operator

kubectl get saunafs --namespace saunafs-operator # Same as above

SaunaFS admin password

SaunaFS admin password is automatically created on cluster creation. To obtain the admin password for the SaunaFS cluster:

kubectl get secret "<SAUNAFS-CLUSTER-NAME>-admin-secret" --template={{.data.password}} | base64 --decode

SaunaFS CGI

SaunaFS CGI offers a web-based GUI that presents SaunaFS status and various statistics.

To access SaunaFS CGI find its load balancer IP:

1. $ kubectl get svc -n saunafs-operator 
   
   NAME                       TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)
   saunafs-cgi-service        LoadBalancer   10.102.184.175   10.20.32.97   9425:30224/TCP
   saunafs-cluster-internal   ClusterIP      10.105.20.190    <none>        9419/TCP,9420/TCP,9421/TCP
   

2. In internet browser enter "<CGI EXTERNAL IP>:9425"
3. In master address enter "<SAUNAFS CLUSTER NAME>-internal", for example saunafs-cluster-internal.

Mounting SaunaFS

1. Install SaunaFS client
2. Get SaunaFS master address

   • kubectl get svc -n saunafs-operator
     

     • Get SaunaFS cluster internal IP for inside kubernetes cluster usage
     • Get SaunaFS cluster external IP for outside kubernetes cluster usage
3. By default saunafs exports are password protected. Export password is stored in kubernetes secret named <CLUSTER_NAME>-default-exports-secret, you can get it using kubectl:

   • $ kubectl get secrets saunafs-test-cluster-default-exports-secret -o jsonpath={.data.saunafs-export-password} | base64 --decode
     

4. Use SaunaFS client to mount filesystem

   • $ mkdir -p /mnt/sarkan
     $ sfsmount -o askpassword -H "<MASTER IP>" /mnt/sarkan
     

TIP

You need to specify spec.exposeExternally in SaunafsCluster resource for external load balancer to be created. More about access from outside kubernetes cluster here.

SaunaFS Exports

SaunaFS Exports serve as access control for sfsmounts.

You can create custom exports by creating SaunafsExport custom resource.

• Example SaunaFS Export for /volume directory:
  • spec.clusterName - Name of the SaunaFS cluster this export applies to.
  • spec.address - IP address, network or address range this export can be accessed from.
  • spec.path - Path to be exported relative to your SaunaFS root.
  • spec.options - Comma separated list of export options, refer to SaunaFS documentation for list of possible options. Defaults to 'readonly'.
  • spec.exportSecret - Kubernetes secret with password that should protect the export. Secret must contain field with key 'saunafs-export-password'. Secret must be in the same namespace as SaunaFS Cluster.

  apiVersion: saunafs.sarkan.io/v1beta1
  kind: SaunafsExport
  metadata:
    name: saunafs-export-volumes
  spec:
    clusterName: saunafs-cluster
    address: "*"
    path: "/volumes"
    options: "rw"
  

• To create password protected export create Secret with key saunafs-export-password equal to password and SaunafsExport with exportSecret field:

  kind: Secret
  apiVersion: v1
  metadata:
    name: saunafs-export
    namespace: saunafs-operator 
  type: Opaque
  stringData:
    saunafs-export-password: my_secure_password
  ---
  apiVersion: saunafs.sarkan.io/v1beta1
  kind: SaunafsExport
  metadata:
    name: saunafs-export-password-protected
  spec:
    clusterName: saunafs-cluster
    path: "/my-password-protected-export"
    exportSecretName: saunafs-export
  

Default exports

Root / and metadata . exports are created by default and you don't have to create them.