Chapter 2. Storage classes

The OpenShift Data Foundation operator installs a default storage class depending on the platform in use. This default storage class is owned and controlled by the operator and it cannot be deleted or modified. However, you can create custom storage classes to use other storage resources or to offer a different behavior to applications.

Note

Custom storage classes are not supported for external mode OpenShift Data Foundation clusters.

2.1. Creating storage classes and pools

You can create a storage class using an existing pool or you can create a new pool for the storage class while creating it.

Prerequisites

  • Ensure that you are logged into the OpenShift Container Platform web console and OpenShift Data Foundation cluster is in Ready state.

Procedure

  1. Click StorageStorageClasses.
  2. Click Create Storage Class.
  3. Enter the storage class Name and Description.
  4. Reclaim Policy is set to Delete as the default option. Use this setting.

    If you change the reclaim policy to Retain in the storage class, the persistent volume (PV) remains in Released state even after deleting the persistent volume claim (PVC).

  5. Volume binding mode is set to WaitForConsumer as the default option.

    If you choose the Immediate option, then the PV gets created immediately when creating the PVC.

  6. Select RBD Provisioner which is the plugin used for provisioning the persistent volumes.
  7. Select an existing Storage Pool from the list or create a new pool.

    Note

    Using 2-way replication data protection policy is not supported for the default pool. However, you can use 2-way replication if you are creating an additional pool.

    Create new pool
    1. Click Create New Pool.
    2. Enter Pool name.
    3. Choose 2-way-Replication or 3-way-Replication as the Data Protection Policy.
    4. Select Enable compression if you need to compress the data.

      Enabling compression can impact application performance and might prove ineffective when data to be written is already compressed or encrypted. Data written before enabling compression will not be compressed.

    5. Click Create to create the new storage pool.
    6. Click Finish after the pool is created.
  8. Optional: Select Enable Encryption checkbox.
  9. Click Create to create the storage class.

2.2. Storage class for persistent volume encryption

Persistent volume (PV) encryption guarantees isolation and confidentiality between tenants (applications). Before you can use PV encryption, you must create a storage class for PV encryption. Persistent volume encryption is only available for RBD PVs.

OpenShift Data Foundation supports storing encryption passphrases in HashiCorp Vault. You can create an encryption enabled storage class using an external key management system (KMS) for persistent volume encryption. You need to configure access to the KMS before creating the storage class.

Note

For PV encryption, you must have a valid Red Hat OpenShift Data Foundation Advanced subscription. For more information, see the knowledgebase article on OpenShift Data Foundation subscriptions.

2.2.1. Access configuration for Key Management System (KMS)

Based on your use case, you need to configure access to KMS using one of the following ways:

  • Using vaulttokens: allows users to authenticate using a token
  • Using vaulttenantsa (Technology Preview): allows users to use serviceaccounts to authenticate with Vault
Important

Accessing the KMS using vaulttenantsa is a Technology Preview feature. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information, see Technology Preview Features Support Scope.

2.2.1.1. Configuring access to KMS using vaulttokens

Prerequisites

  • The OpenShift Data Foundation cluster is in Ready state.
  • On the external key management system (KMS),

    • Ensure that a policy with a token exists and the key value backend path in Vault is enabled.
    • Ensure that you are using signed certificates on your Vault servers.

Procedure

Create a secret in the tenant’s namespace.

  1. In the OpenShift Container Platform web console, navigate to Workloads → Secrets.
  2. Click Create → Key/value secret.
  3. Enter Secret Name as ceph-csi-kms-token.
  4. Enter Key as token.
  5. Enter Value.

    It is the token from Vault. You can either click Browse to select and upload the file containing the token or enter the token directly in the text box.

  6. Click Create.
Note

The token can be deleted only after all the encrypted PVCs using the ceph-csi-kms-token have been deleted.

2.2.1.2. Configuring access to KMS using vaulttenantsa

Prerequisites

  • The OpenShift Data Foundation cluster is in Ready state.
  • On the external key management system (KMS),

    • Ensure that a policy exists and the key value backend path in Vault is enabled.
    • Ensure that you are using signed certificates on your Vault servers.
  • Create the following serviceaccount in the tenant namespace as shown below:

    $ cat <<EOF | oc create -f -
    apiVersion: v1
    kind: ServiceAccount
    metadata:
        name: ceph-csi-vault-sa
    EOF

Procedure

You need to configure the Kubernetes authentication method before OpenShift Data Foundation can authenticate with and start using Vault. The following instructions create and configure serviceAccount, ClusterRole, and ClusterRoleBinding required to allow OpenShift Data Foundation to authenticate with Vault.

  1. Apply the following YAML to your Openshift cluster:

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: rbd-csi-vault-token-review
    ---
    kind: ClusterRole
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: rbd-csi-vault-token-review
    rules:
      - apiGroups: ["authentication.k8s.io"]
        resources: ["tokenreviews"]
        verbs: ["create", "get", "list"]
    
    ---
    kind: ClusterRoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: rbd-csi-vault-token-review
    subjects:
      - kind: ServiceAccount
        name: rbd-csi-vault-token-review
        namespace: openshift-storage
    roleRef:
      kind: ClusterRole
      name: rbd-csi-vault-token-review
      apiGroup: rbac.authorization.k8s.io
  2. Depending on the OpenShift Container Platform version, perform one of the following:.

    • For OpenShift Container Platform 4.10:

      • Identify the secret name associated with the serviceaccount (SA) created above.

        $ VAULT_SA_SECRET_NAME=$(oc -n openshift-storage get sa <SA_NAME> -o jsonpath="{.secrets[]['name']}") | grep -o "[^[:space:]]-token-[^[:space:]]*"

        For example:

        $ VAULT_SA_SECRET_NAME=$(oc -n openshift-storage get sa rbd-csi-vault-token-review -o jsonpath="{.secrets[]['name']}" | grep -o "[^[:space:]]-token-[^[:space:]]*")
    • For OpenShift Container Platform 4.11:

      • Create a secret for the serviceaccount token and CA certificate.

        $ cat <<EOF | oc create -f -
        apiVersion: v1
        kind: Secret
        metadata:
          name: rbd-csi-vault-token-review-token
          namespace: openshift-storage
          annotations:
            kubernetes.io/service-account.name: "rbd-csi-vault-token-review"
        type: kubernetes.io/service-account-token
        data: {}
        EOF
        $ VAULT_SA_SECRET_NAME=rbd-csi-vault-token-review-token
  3. Get the token and the CA certificate from the secret.

    $ SA_JWT_TOKEN=$(oc -n openshift-storage get secret "$VAULT_SA_SECRET_NAME" -o jsonpath="{.data.token}" | base64 --decode; echo)
    $ SA_CA_CRT=$(oc -n openshift-storage get secret "$VAULT_SA_SECRET_NAME" -o jsonpath="{.data['ca\.crt']}" | base64 --decode; echo)
  4. Retrieve the OpenShift cluster endpoint.

    $ OCP_HOST=$(oc config view --minify --flatten -o jsonpath="{.clusters[0].cluster.server}")
  5. Use the information collected in the previous steps to set up the kubernetes authentication method in Vault as shown:

    $ vault auth enable kubernetes
    $ vault write auth/kubernetes/config \
              token_reviewer_jwt="$SA_JWT_TOKEN" \
              kubernetes_host="$OCP_HOST" \
              kubernetes_ca_cert="$SA_CA_CRT"
  6. Create a role in Vault for the tenant namespace:

    $ vault write "auth/kubernetes/role/csi-kubernetes" bound_service_account_names="ceph-csi-vault-sa" bound_service_account_namespaces=<tenant_namespace> policies=<policy_name_in_vault>

    csi-kubernetes is the default role name that OpenShift Data Foundation looks for in Vault. The default service account name in the tenant namespace in the OpenShift Data Foundation cluster is ceph-csi-vault-sa. These default values can be overridden by creating a ConfigMap in the tenant namespace.

    For more information about overriding the default names, see Overriding Vault connection details using tenant ConfigMap.

Sample YAML

  • To create a storageclass that uses the vaulttenantsa method for PV encrytpion, you must either edit the existing ConfigMap or create a ConfigMap named csi-kms-connection-details that will hold all the information needed to establish the connection with Vault.

    The sample yaml given below can be used to update or create the csi-kms-connection-detail ConfigMap:

    apiVersion: v1
    data:
      vault-tenant-sa: |-
        {
          "encryptionKMSType": "vaulttenantsa",
          "vaultAddress": "<https://hostname_or_ip_of_vault_server:port>",
          "vaultTLSServerName": "<vault TLS server name>",
          "vaultAuthPath": "/v1/auth/kubernetes/login",
          "vaultAuthNamespace": "<vault auth namespace name>"
          "vaultNamespace": "<vault namespace name>",
          "vaultBackendPath": "<vault backend path name>",
          "vaultCAFromSecret": "<secret containing CA cert>",
          "vaultClientCertFromSecret": "<secret containing client cert>",
          "vaultClientCertKeyFromSecret": "<secret containing client private key>",
          "tenantSAName": "<service account name in the tenant namespace>"
        }
    metadata:
      name: csi-kms-connection-details

    encryptionKMSType

    Set to vaulttenantsa to use service accounts for authentication with vault.

    vaultAddress

    The hostname or IP address of the vault server with the port number.

    vaultTLSServerName

    (Optional) The vault TLS server name

    vaultAuthPath

    (Optional) The path where kubernetes auth method is enabled in Vault. The default path is kubernetes. If the auth method is enabled in a different path other than kubernetes, this variable needs to be set as "/v1/auth/<path>/login".

    vaultAuthNamespace

    (Optional) The Vault namespace where kubernetes auth method is enabled.

    vaultNamespace

    (Optional) The Vault namespace where the backend path being used to store the keys exists

    vaultBackendPath

    The backend path in Vault where the encryption keys will be stored

    vaultCAFromSecret

    The secret in the OpenShift Data Foundation cluster containing the CA certificate from Vault

    vaultClientCertFromSecret

    The secret in the OpenShift Data Foundation cluster containing the client certificate from Vault

    vaultClientCertKeyFromSecret

    The secret in the OpenShift Data Foundation cluster containing the client private key from Vault

    tenantSAName

    (Optional) The service account name in the tenant namespace. The default value is ceph-csi-vault-sa. If a different name is to be used, this variable has to be set accordingly.

2.2.2. Creating a storage class for persistent volume encryption

Prerequisites

Based on your use case, you must ensure to configure access to KMS for one of the following:

Procedure

  1. In the OpenShift Web Console, navigate to StorageStorageClasses.
  2. Click Create Storage Class.
  3. Enter the storage class Name and Description.
  4. Select either Delete or Retain for the Reclaim Policy. By default, Delete is selected.
  5. Select either Immediate or WaitForFirstConsumer as the Volume binding mode. WaitForConsumer is set as the default option.
  6. Select RBD Provisioner openshift-storage.rbd.csi.ceph.com which is the plugin used for provisioning the persistent volumes.
  7. Select Storage Pool where the volume data is stored from the list or create a new pool.
  8. Select the Enable encryption checkbox. There are two options available to set the KMS connection details:

    • Select existing KMS connection: Select an existing KMS connection from the drop-down list. The list is populated from the the connection details available in the csi-kms-connection-details ConfigMap.
    • Create new KMS connection: This is applicable for vaulttokens only.

      1. Key Management Service Provider is set to Vault by default.
      2. Enter a unique Connection Name, host Address of the Vault server ('https://<hostname or ip>'), Port number and Token.
      3. Expand Advanced Settings to enter additional settings and certificate details based on your Vault configuration:

        1. Enter the Key Value secret path in Backend Path that is dedicated and unique to OpenShift Data Foundation.
        2. Optional: Enter TLS Server Name and Vault Enterprise Namespace.
        3. Upload the respective PEM encoded certificate file to provide the CA Certificate, Client Certificate and Client Private Key .
        4. Click Save.
      4. Click Save.
  9. Click Create.
  10. Edit the ConfigMap to add the vaultBackend parameter if the HashiCorp Vault setup does not allow automatic detection of the Key/Value (KV) secret engine API version used by the backend path.

    Note

    vaultBackend is an optional parameters that is added to the configmap to specify the version of the KV secret engine API associated with the backend path. Ensure that the value matches the KV secret engine API version that is set for the backend path, otherwise it might result in a failure during persistent volume claim (PVC) creation.

    1. Identify the encryptionKMSID being used by the newly created storage class.

      1. On the OpenShift Web Console, navigate to StorageStorage Classes.
      2. Click the Storage class name → YAML tab.
      3. Capture the encryptionKMSID being used by the storage class.

        Example:

        encryptionKMSID: 1-vault
    2. On the OpenShift Web Console, navigate to WorkloadsConfigMaps.
    3. To view the KMS connection details, click csi-kms-connection-details.
    4. Edit the ConfigMap.

      1. Click Action menu (⋮)Edit ConfigMap.
      2. Add the vaultBackend parameter depending on the backend that is configured for the previously identified encryptionKMSID.

        You can assign kv for KV secret engine API, version 1 and kv-v2 for KV secret engine API, version 2.

        Example:

         kind: ConfigMap
         apiVersion: v1
         metadata:
           name: csi-kms-connection-details
         [...]
         data:
           1-vault: |-
             {
               "encryptionKMSType": "vaulttokens",
               "kmsServiceName": "1-vault",
               [...]
               "vaultBackend": "kv-v2"
             }
           2-vault: |-
             {
               "encryptionKMSType": "vaulttenantsa",
               [...]
               "vaultBackend": "kv"
             }
      3. Click Save

Next steps

  • The storage class can be used to create encrypted persistent volumes. For more information, see managing persistent volume claims.

    Important

    Red Hat works with the technology partners to provide this documentation as a service to the customers. However, Red Hat does not provide support for the HashiCorp product. For technical assistance with this product, contact HashiCorp.

2.2.2.1. Overriding Vault connection details using tenant ConfigMap

The Vault connections details can be reconfigured per tenant by creating a ConfigMap in the Openshift namespace with configuration options that differ from the values set in the csi-kms-connection-details ConfigMap in the openshift-storage namespace. The ConfigMap needs to be located in the tenant namespace. The values in the ConfigMap in the tenant namespace will override the values set in the csi-kms-connection-details ConfigMap for the encrypted Persistent Volumes created in that namespace.

Procedure

  1. Ensure that you are in the tenant namespace.
  2. Click on Workloads → ConfigMaps.
  3. Click on Create ConfigMap.
  4. The following is a sample yaml. The values to be overidden for the given tenant namespace can be specified under the data section as shown below:

    ---
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: ceph-csi-kms-config
    data:
      vaultAddress: "<vault_address:port>"
      vaultBackendPath: "<backend_path>"
      vaultTLSServerName: "<vault_tls_server_name>"
      vaultNamespace: "<vault_namespace>"
  5. Once the yaml is edited, click on Create.