Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Work with Shared Resources

builds for Red Hat OpenShift 1.2

Using Shared Resources CSI Driver Operator

Red Hat OpenShift Documentation Team

Abstract

This document provides procedural examples for using Shared Resources CSI Driver.

Chapter 1. Shared Resource CSI Driver Operator
Copy link

Storage vendors have traditionally provided storage drivers as a part of Kubernetes. With the implementation of the Container Storage Interface (CSI), third-party providers can deliver storage plugins by using a standard interface without changing the core Kubernetes code. CSI Operators give Builds' users storage options, such as volume snapshots that are not possible with in-tree volume plugins.

The Shared Resource CSI driver is a special type of CSI driver that allows cluster administrators to securely share Secret and ConfigMap objects across namespaces by using the csi volume type. The Shared resources CSI driver provisions inline ephemeral volumes, enabling pods and OpenShift Container Platform Builds to use these shared resources.

The Shared Resource CSI driver supports the following types of custom resources:

  • SharedSecret custom resource for sharing Secret objects
  • SharedConfigMap custom resource for sharing ConfigMap objects

1.1. Sharing a Secret object across namespaces
Copy link

A Secret object is used to store and manage sensitive information, such as passwords, OAuth tokens, and SSH keys. You can use a SharedSecret custom resource (CR) to securely share a Secret object across different namespaces within a cluster without duplicating it manually. Sharing the Secret object provides a single source for sensitive data and ensures that authorized namespaces have access to it.

1.1.1. Creating a SharedSecret custom resource
Copy link

You can create a SharedSecret custom resource (CR) to share a Secret object across namespaces.

Prerequisites

  • You have created a Secret object that you want to share in other namespaces. To create a Secret object, see "Creating Secrets".
  • You have subscribed to the cluster and have entitlement keys synced through the Insights Operator.

  • You must have permissions to perform the following actions:

    • Create the sharedsecrets.sharedresource.openshift.io CR at a cluster-scoped level.
    • Create the ClusterRole object for the SharedSecret CR.
    • Create the Role and RoleBinding objects for the Shared Resource CSI Driver.
    • Manage roles and role bindings across the namespaces in the cluster to control users.
    • Manage roles and role bindings so that the service account specified by a pod can use the SharedSecret CR to mount a CSI volume that references a Secret object.
    • Access to the namespaces that contain the Secret object you want to share.

Procedure

  1. Create the Role and RoleBinding objects that grant the Shared Resource CSI driver the permission to access the SharedSecret object by using the following example configurations:

    Example Role object

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: share-etc-pki-entitlement
    1 
    
  namespace: openshift-config-managed
rules:
  - apiGroups:
      - ""
    resources:
      - secrets
    resourceNames:
      - etc-pki-entitlement
    verbs:
      - get
      - list
      - watch
    Copy to Clipboard Toggle word wrap

    1
    Name of the Role CR.

    Example RoleBinding object

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: share-etc-pki-entitlement
    1 
    
  namespace: openshift-config-managed
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: share-etc-pki-entitlement
    2 
    
subjects:
  - kind: ServiceAccount
    name: csi-driver-shared-resource
    3 
    
    namespace: openshift-builds
    Copy to Clipboard Toggle word wrap

    1
    Name of the RoleBinding CR.
    2
    Name of the Role CR.
    3
    Name of the ServiceAccount CR.

  2. Create a SharedSecret CR by using the following example configuration: 

    apiVersion: sharedresource.openshift.io/v1alpha1
kind: SharedSecret
metadata:
  name: shared-test-secret
    1 
    
spec:
  secretRef:
    name: test-secret
    namespace: <name_of_the_source_namespace>
    Copy to Clipboard Toggle word wrap
    1
    Replace <name_of_the_source_namespace> with the name of the SharedSecret CR.

  3. Create a ClusterRole object that grants RBAC permission to use the referenced shared resource by using the following example configuration: 

    apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: use-shared-test-secret
    1 
    
rules:
  - apiGroups:
      - sharedresource.openshift.io
    resources:
      - sharedsecrets
    resourceNames:
      - shared-test-secret
    verbs:
      - use
    Copy to Clipboard Toggle word wrap
    1
    Name of the ClusterRole CR.

To access the SharedSecret custom resource (CR) from a pod, you grant role-based access control (RBAC) permission to a service account.

Prerequisites

  • You have created a SharedSecret CR instance for the Secret object that you want to share across namespaces in the cluster.

  • You must have permissions to perform the following actions:

    • Run the oc adm policy who-can use <sharedsecret_identifier> command to check if a service account is allowed to use the SharedSecret CR and the service account is listed in your namespace.
    • Confirm that the service account of your pod is allowed to use the csi volume. If you created the pod as a user, confirm that you are allowed to use the csi volume.
Note

If you are unable to complete the last two prerequisites, the cluster administrator can establish the necessary RBAC permission so that you can enable service accounts to use the SharedSecret CR.

Procedure

  1. Create the RoleBinding object in the cluster associated with the role and grant the permission to your service account to use the shared resource. See the following example configuration: 

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: use-shared-secret
    1 
    
  namespace: app-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: use-shared-secret
subjects:
  - kind: ServiceAccount
    name: <service_account_name>
    2
    Copy to Clipboard Toggle word wrap
    1
    Name of the RoleBinding CR.
    2
    Replace <service_account_name> with the service account name of your application.

  2. Mount the shared resource csi driver into a pod or any other resource that accepts csi volumes. See the following example configuration: 

    apiVersion: v1
kind: Pod
metadata:
  name: example-shared-secret
  namespace: <app_namespace>
    1 
    
spec:
  ...
  serviceAccountName: default
  volumes:
    - name: shared-secret
      csi:
        readOnly: true
        driver: csi.sharedresource.openshift.io
        volumeAttributes:
          sharedSecret: shared-test-secret
    2
    Copy to Clipboard Toggle word wrap
    1
    Replace <app_namespace> with the namespace name of your application.
    2
    Value of the sharedSecret attribute that must be same as the name of the SharedSecret CR.
    Important

    If the value of the sharedSecret attribute does not match the name of the SharedSecret instance, the pod fails to start.

1.2. Sharing a ConfigMap object across namespaces
Copy link

A ConfigMap object stores non-sensitive configuration data, such as application URLs or feature flags. A SharedConfigMap custom resource (CR) enables you to securely share a ConfigMap object across multiple namespaces in a cluster without manual duplication. By sharing a ConfigMap object, you establish a single source of configuration data and ensure consistency across the cluster.

1.2.1. Creating a SharedConfigMap custom resource
Copy link

You can create a SharedConfigMap custom resource (CR) instance to share a ConfigMap object across namespaces.

Prerequisites

  • You have created a ConfigMap object that you want to share in other namespaces. To create a ConfigMap object, see "Adding input secrets and configmaps".

  • You must have permissions to perform the following actions:

    • Create the sharedconfigmaps.sharedresource.openshift.io CR at a cluster-scoped level.
    • Create a ClusterRole object for the SharedConfigMap CR.
    • Create the Role and RoleBinding objects for the Shared Resource Container Storage Interface (CSI) Driver.
    • Manage roles and role bindings across the namespaces in the cluster to control which users can get, list, and watch instances.
    • Manage roles and role bindings so that the service account specified by a pod can use the SharedConfigMap CR to mount a csi volume that references a ConfigMap object.
    • Access the namespaces that contain the ConfigMap object you want to share.

Procedure

  1. Create a Role and RoleBinding object to grant the Shared Resource CSI Driver permission to access the ConfigMap object. See the following example configuration:

    Example Role object

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: shared-test-config
  namespace: <name_of_the_source_namespace>
    1 
    
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["shared-config"]
    verbs: ["get", "list", "watch"]
    Copy to Clipboard Toggle word wrap

    1
    Replace <name_of_the_source_namespace> with the name of the source namespace.

    Example RoleBinding object

     apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
 metadata:
   name: shared-test-config
   namespace: <name_of_the_source_namespace>
    1 
    
 roleRef:
   apiGroup: rbac.authorization.k8s.io
   kind: Role
   name: shared-test-config
 subjects:
    2 
    
   - kind: ServiceAccount
     name: csi-driver-shared-resource
     namespace: openshift-builds
    Copy to Clipboard Toggle word wrap

    1
    Replace <name_of_the_source_namespace> with the name of the source namespace.
    2
    Specifies a list of service accounts for the Shared Resource CSI driver DaemonSet. When deployed with builds for Red Hat OpenShift, the service account name is csi-driver-shared-resource, and the namespace matches the one where the Builds for Red Hat OpenShift Operator is deployed.

  2. Create a SharedConfigMap CR for the ConfigMap object that you want to share across namespaces in the cluster. The following example shows a sample configuration: 

    apiVersion: sharedresource.openshift.io/v1alpha1
kind: SharedConfigMap
metadata:
  name: share-test-config
    1 
    
spec:
  configMapRef:
    name: shared-config
    namespace: <name_of_the_source_namespace>
    2
    Copy to Clipboard Toggle word wrap
    1
    Specifies the name of the SharedConfigMap CR.
    2
    Replace <name_of_the_source_namespace> with the name of your source namespace.

  3. Create a ClusterRole CR instance that grants role-based access control (RBAC) permission to use the referenced shared resource. The following example shows a sample configuration: 

    apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <cluster_role_name>
    1 
    
rules:
  - apiGroups:
      - sharedresource.openshift.io
    resources:
      - sharedconfigmaps
    resourceNames:
      - share-test-config
    2 
    
    verbs:
      - use
    Copy to Clipboard Toggle word wrap
    1
    Replace <cluster_role_name> with the name of your cluster role.
    2
    Specifies the name of the SharedSecret CR.

To access a SharedConfigMap custom resource (CR) from a pod, you must grant the associated service account the necessary role-based access control (RBAC) permissions to use that SharedConfigMap CR.

Prerequisites

  • You have created a SharedConfigMap CR instance for the config map that you want to share across namespaces in the cluster.

  • You must have permissions to perform the following actions:

    • Run the oc get sharedconfigmaps command to get the list of the SharedConfigMap CR instances.
    • Run the oc adm policy who-can use <sharedsecret_identifier> command to check if a service account is allowed to use the SharedSecret CR and the service account is listed in your namespace.
    • Run the oc describe clusterrole <roleName> command to confirm that the service account of your pod is allowed to use csi volumes. If you created the pod as a user, confirm that you are allowed to use csi volumes.
Note

If you are unable to complete the last two prerequisites, the cluster administrator can grant you the RBAC permission to enable the service accounts to use the SharedConfigMap CR.

Procedure

  1. Create the RoleBinding object associated with the role and grant the permission to your service account to use the shared resource. 

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: use-shared-config
  namespace: <app_namespace>
    1 
    
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: use-shared-config
subjects:
  - kind: ServiceAccount
    name: <service_account_name>
    2
    Copy to Clipboard Toggle word wrap
    1
    Replace <app_namespace> with the namespace name of your application.
    2
    Replace <service_account_name> with the service account name of your application.

  2. Mount the Shared Resource Container Storage Interface (CSI) Driver into a pod or any other resource that accepts csi volumes. 

    apiVersion: v1
kind: Pod
metadata:
  name: example-shared-config
  namespace: <app_namespace>
    1 
    
spec:
  ...
  serviceAccountName: default
  volumes:
    - name: shared-config
      csi:
        readOnly: true
        driver: csi.sharedresource.openshift.io
        volumeAttributes:
          sharedConfigMap: share-test-config
    2
    Copy to Clipboard Toggle word wrap
    1
    Replace <app_namespace> with the namespace name of your application.
    2
    Specifies the name of the sharedConfigMap object.
    Important

    If the value of sharedConfigMap attribute does not match the name of sharedConfigMap instance, the pod fails to start.

1.3. Building images using RHEL entitlements
Copy link

If you have a Red Hat Enterprise Linux (RHEL) entitlement, the Insights Operator automatically manages the entitlement keys using the Simple Content Access (SCA) feature. With SCA, the RHEL systems access the subscription content without manually managing the entitlement keys. The Insights Operator imports your SCA entitlement keys and stores them in a secret called etc-pki-entitlement in the openshift-config-managed namespace.

Previously, a cluster administrator would manually copy the etc-pki-entitlement secret to the required namespace. Starting with OpenShift Container Platform 4.10 and later, builds for Red Hat OpenShift can share the etc-pki-entitlement secret from the openshift-config-managed namespace with other namespaces by using the Shared Resource Container Storage Interface (CSI) Driver Operator.

1.3.1. Sharing RHEL entitlement across namespaces
Copy link

You can use a SharedSecret object to securely share and synchronize the RHEL entitlement keys of a cluster in Builds across namespaces.

Prerequisites

  • You must have permissions to perform the following actions:

    • Create SharedSecret object.
    • Create build configs and start builds.
    • Run the oc get sharedsecrets command to discover which SharedSecret custom resource (CR) instances are available.
    • Run the oc adm policy who-can use <sharedsecret_identifier> command to check if a service account is allowed to use the SharedSecret CR and the service account is listed in your namespace.
Note

If you are unable to complete the last two prerequisites, the cluster administrator can establish the necessary RBAC permission so that you can grant service accounts to use the SharedSecret CR.

Procedure

  1. Create a SharedSecret object instance with the entitlement secret of a cluster by running the following command: 

    $ oc apply -f -<<EOF
apiVersion: sharedresource.openshift.io/v1alpha1
kind: SharedSecret
metadata:
  name: etc-pki-entitlement
spec:
  secretRef:
    name: etc-pki-entitlement
    namespace: openshift-config-managed
EOF
    Copy to Clipboard Toggle word wrap

  2. Create a ClusterRole object to grant permission to access the SharedSecret object by using the following example configuration: 

    apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: use-share-etc-pki-entitlement
    1 
    
rules:
  - apiGroups:
      - sharedresource.openshift.io
    resources:
      - sharedsecrets
    resourceNames:
      - etc-pki-entitlement
    verbs:
      - use
    Copy to Clipboard Toggle word wrap
    1
    Name of the ClusterRole CR.

  3. Create the Role and RoleBinding object that grants the Shared Resource CSI driver the permission to access the SharedSecret object:

    Example Role object

    apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: share-etc-pki-entitlement
    1 
    
  namespace: openshift-config-managed
rules:
  - apiGroups:
      - ""
    resources:
      - secrets
    resourceNames:
      - etc-pki-entitlement
    verbs:
      - get
      - list
      - watch
    Copy to Clipboard Toggle word wrap

    1
    Name of the Role CR.

    Example RoleBinding object

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: share-etc-pki-entitlement
    1 
    
  namespace: openshift-config-managed
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: share-etc-pki-entitlement
subjects:
  - kind: ServiceAccount
    name: csi-driver-shared-resource
    namespace: openshift-builds
    2
    Copy to Clipboard Toggle word wrap

    1
    Name of the RoleBinding CR.
    2
    Name of the namespace where openshift-builds is installed.

  4. Create a RoleBinding object for the builder and pipeline service accounts in the namespace where builds run: 

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: use-share-etc-pki-entitlement
    1 
    
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: use-share-etc-pki-entitlement
subjects:
  - kind: ServiceAccount
    name: pipeline
  - kind: ServiceAccount
    name: builder
    Copy to Clipboard Toggle word wrap
    1
    Name of the RoleBinding CR for the builder and pipeline service accounts.
    Note

    The service account that consumes the SharedSecret object is created and managed by the OpenShift controllers.

  5. Mount the SharedSecret object by using the buildah build strategy. See the following example: 

    $ oc apply -f -<<EOF
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-rhel
spec:
  source:
    type: Git
      git:
      url: https://github.com/redhat-openshift-builds/samples
    contextDir: buildah-build
  strategy:
    name: buildah
    kind: ClusterBuildStrategy
  paramValues:
  - name: dockerfile
    value: DockerFile
  volumes:
  - csi:
      driver: csi.sharedresource.openshift.io
      readOnly: true
    1 
    
      volumeAttributes:
        sharedSecret: <sharedsecret_object_name>
    2 
    
    name: etc-pki-entitlement
  output:
    image: <output_image_location>
    3 
    
EOF
    Copy to Clipboard Toggle word wrap
    1
    You must set readOnly to true to mount the shared resource in the build.
    2
    Replace <sharedsecret_object_name> with the name of the SharedSecret object to include it in the build.
    3
    Replace <output_image_location> with the location where you want to push the built image.

Legal Notice
Copy link

Copyright © 2025 Red Hat

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat