Storage Considerations

Persistence overview

Transformation Advisor requires persistence to be configured in order to persist the database data. When Transformation Advisor starts for the first time, it will create a PersistentVolumeClaim (unless you have set the option to use an existing claim). The persistence options provided by Transformation Advisor allow you to control the attributes of the PersistentVolumeClaim that it creates. The PersistentVolumeClaim must bind to a PersistentVolume on the cluster. The properties set for the claim must be compatible with the PersistentVolumes available on your cluster.

From Transformation Advisor 3.0.x onwards, two PersistentVolumeClaims are required.

The persistence may be configured from the UI form view or the YAML view when installing the Transformation Advisor instance.

It is not recommended to use local volumes as backing for persistence.

Supported Storage Providers

The following storage providers are supported:

• OpenShift Container Storage / OpenShift Data Foundation version 4.x, from version 4.2 or higher
• IBM Cloud Block storage and IBM Cloud File storage
• Portworx Storage, version 2.5.5 or above
• File storage from IBM Spectrum Fusion/Scale
• Amazon Elastic File Storage (EFS) for RWX mode access

Transformation Advisor Persistence Options

The following properties can be configured to control the persistence that Transformation Advisor uses. Set the options according to your requirements and constraints when installing the Transformation Advisor instance. See Example Persistence Configurations to see how to use these configuration options.

Enable / Disable

Configuration setting: persistence.enabled: <true|false>

Although it is NOT recommended for a production install, you can also turn the persistence off. Transformation Advisor will have full functionality with persistence disabled except importantly, if persistence is disabled, you will lose all of your Transformation Advisor data when the database container restarts.

Access modes

The access mode determines the PersistentVolume that the Transformation Advisor PersistentVolumeClaim can bind to. The value for access mode must be supported by the type of storage that is available on your cluster. For example, if you are installing Transformation Advisor on public cloud, the accessMode is ReadWriteOnce (RWO). Consult your storage administrator for more details.

Configuration setting: persistence.accessMode: <"ReadWriteOnce">

Transformation Advisor supports ReadWriteOnce (RWO) access mode. ReadWriteMany (RWX) and ReadOnlyMany (ROX) access modes are not supported.

Storage class

Configuration setting: persistence.storageClassName: <"storage class name">

A StorageClass provides a way for administrators to describe the "classes" of storage they offer. If the PersistentVolumes configured for your cluster have a storage class, then you can set the storageClassName property in Transformation Advisor, so that the PersistentVolumeClaim will bind to those PersistentVolumes.

If you are configuring persistence in the UI form view, the Storage Class widget will be pre-populated with the StorageClasses available on your cluster. Alternatively, you can navigate to storage classes in the OpenShift UI to see what storage classes are available on your cluster.

Alternatively, you can use the following command to see the storage classes available:

oc get storageclass

Storage type and permissions

If you are installing on an environment that uses block storage (specified using a storageClass), Transformation Advisor can bind to the storage and set the correct permissions for that storage. If you are installing on an environment that uses file system storage such as NFS, you must ensure that Transformation Advisor has read/write permissions to the storage on the host. For details, see Setting permissions for NFS.

If there are not sufficient permissions for the storage that Transformation Advisor uses, the CouchDB pod fails to start and a permission denied message is added to the couchDB pod logs:

[error] 2019-08-23T21:08:33.974674Z nonode@nohost <0.256.0>
-------- Could not open file ./data/_users.couch: permission denied

Setting permissions for NFS

When shared storage is mounted into a container, it is mounted with the same ownership and permissions that are found on the exported NFS directory. The container that uses the storage is not run with that owner and might not have permission to read or write to the storage. To enable read/write permission to the storage, consider the following options:

Option A: Control permissions with the supplementalGroups setting

Configuration setting: persistence.supplementalGroups: <[id1,id2...]>

Supplemental groups are regular Linux groups and are typically used for controlling access to shared storage, such as NFS. When a process runs in Linux, it has a UID, a GID, and one or more supplemental groups. The supplemental groups can be set for a container’s main process. The supplemental group gives the container process group ownership on the storage and consequently the group level permissions to allow the container process to read/write to the storage.

Consider the following example where the underlying host storage is located at /netstore/transadv/. The nfsnobody group might have full permissions on the shared directory when NFS is shared with the root_squash option:

> ls -ld /netstore/transadv/
drwxrwx---. 7 nfsnobody nfsnobody 182 Aug 31 22:30 /netstore/transadv/

To control permissions with the supplementalGroups setting, and give the container the ability to read/write to the storage, add the nfsnobody GID to the supplemental groups as follows:

1. Get the nfsnobody GID using the id command.

   > id nfsnobody
   uid=65534(nfsnobody) gid=65534(nfsnobody) groups=65534(nfsnobody)
   

2. Add the GID (65534 in this case) using the supplementalGroups setting, e.g. configuration.

persistence:
  ...
  <couchdb | neo4j>
    supplementalGroups: [65534]

Option B: Create a PersistentVolume specifically for use with Transformation Advisor

Configuration setting: persistence.existingClaim: <"claim name">

Creating a PersistentVolume specifically for Transformation Advisor allows you to set the access permissions for storage used by that PersistentVolume.

This option describes how to: 1. Create a NFS PersistentVolume specifically for Transformation Advisor 2. Create a PersistentVolumeClaim to bind to that volume 3. Use that claim (with appropriate permissions) for Transformation Advisor.

We will manually create a PersistentVolumeClaim and ensure that the storage backing its PersistentVolume has the correct (open) permissions. You can ensure a claim binds to a specific volume with selector and label attributes.

1. Define an NFS PersistentVolume. The following sample is an NFS volume definition. Substitute the path and server values for your own environment.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: tanfspv
  labels:
    pvc_for_app: "ta"
spec:
  capacity:
    storage: 20Gi
  accessModes:
    - ReadWriteOnce
  nfs:
    path: /nfs/ta_storage
    server: xxx.xxx.xxx.xxx
  persistentVolumeReclaimPolicy: Recycle

Make sure that the directory at the path has open permissions so that the container can read/write there:

chmod -R 777 /netstore/transadvopen/

1. Define a PersistentVolumeClaim. The following sample binds to the PersistentVolume defined above. Ensure you create the claim in the Transformation Advisor namespace.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: tapvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  selector:
    matchLabels:
      pvc_for_app: "ta"

If you want Transformation Advisor to use a specific PersistentVolumeClaim, add the name of the claim using the existingClaim property.

Option C: Update permissions for the PersistentVolume after Transformation Advisor has tried and failed to start

If you are using NFS storage, and you do not complete option A or B, when Transformation Advisor attempts to start, the CouchDB pod will not start. If you look at the logs for the CouchDB pod you will see a permissions issue:

[error] 2019-08-23T21:08:33.974674Z nonode@nohost <0.256.0>
-------- Could not open file ./data/_users.couch: permission denied

At this point, you can find the PersistentVolumeClaim that Transformation Advisor has created:

oc get pvc

That will reveal the PersistentVolume it has bound to (under the VOLUME header).

You can describe that PersistentVolume to discover the path for the storage:

oc describe pv tanfspv | grep Path:

You can then open the permissions on that path with: chmod -R 777 <path>

The CouchDB should then restart successfully within a few minutes. Or, you can delete the CouchDB pod and it will be automatically restarted.

Storage Classes Red Hat OpenShift Container Platform on IBM Cloud

IBM Cloud provides a number of storage classes for OpenShift clusters. Some of the storage classes use block storage and can be identified by the '-block-' in their name. Other storage classes use file storage and can be identified by the '-file-' in their name. The storage class with the name 'default' uses file storage also.

Transformation Advisor supports the use of any of the block-based storage classes. Transformation Advisor does not support the use of the file-based storage (including the storage class called "default"), except for the storage classes that have a -gid suffix, i.e.:

• ibmc-file-bronze-gid
• ibmc-file-silver-gid
• ibmc-file-gold-gid

These storage classes allow you to specify a supplemental group when installing so that the Transformation Advisor non-root containers can write to the storage. When using these *-gid storage classes, specify the supplementalGroups of 65531 at install time.

For more information on storage classes on Red Hat OpenShift on IBM Cloud, see Storage class reference.

Example Persistence Configurations

Please refer to the Installing document on how to apply these example configurations.

EXAMPLE 1: Using storageClass

Use the storage class to create a PersistentVolumeClaim that will bind to a PersistentVolumeClaim of that class. In this case, we are using "ibmc-block-silver" on public cloud.

For a UI install, the custom resource YAML would look like this:

...
persistence:
  enabled: true
  <couchdb | neo4j>
    accessMode: "ReadWriteOnce"
    size: 20Gi
    useDynamicProvisioning: true
    existingClaim: ""
    storageClassName: "ibmc-block-silver"
    supplementalGroups: []
...

For a CASE install the arguments would look like this:

--args "... --storageClass ibmc-block-silver --accessMode ReadWriteOnce ..."

EXAMPLE 2: Using supplementalGroups

In this example, we are using the supplementalGroups setting to ensure the database pods have sufficient permissions on NFS storage. The group ownership of the shared file system has a GID of 65534.

For a UI install, the custom resource YAML would look like this:

...
persistence:
  enabled: true
  <couchdb | neo4j>
    accessMode: "ReadWriteOnce"
    size: 20Gi
    useDynamicProvisioning: true
    existingClaim: ""
    storageClassName: ""
    supplementalGroups: [65534]
...

For a CASE install the arguments would look like this:

--args "... --supplementalGroups [65534] ..."

EXAMPLE 3: Using existingClaim

In this example, a persistence volume claim called my-ta-pvc has already been set up by the user. The claim has open permissions to allow the database container to write to it.

For a UI install, the custom resource YAML would look like this:

...
persistence:
  enabled: true
  <couchdb | neo4j>
    accessMode: "ReadWriteOnce"
    size: 20Gi
    useDynamicProvisioning: true
    existingClaim: "my-ta-pvc"
    storageClassName: ""
    supplementalGroups: []
...

For a CASE install the arguments would look like this:

--args "... --persistenceClaimCouchDB my-ta-pvc --persistenceClaimNeo4j my-ta-pvc2..."

Deleting a Persistence Volume Claim

In a normal uninstallation of Transformation Advisor, the PersistentVolumeClaim that Transformation Advisor has created will be deleted, and the PersistentVolume that the claim binds to will be released for use.

If you need to manually delete PersistentVolumes or PersistentVolumeClaims please consult the relevant Kubernetes documentation.