-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #174 from adambkaplan/upstream-docs-cleanup
BUILD-953: Simplify README
- Loading branch information
Showing
2 changed files
with
139 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,77 +1,138 @@ | ||
| # OpenShift Shared Resource CSI Driver | ||
|
|
||
| The OpenShift Shared Resource CSI Driver allows for the controlled (via Kubernetes RBAC) sharing of Kubernetes Secrets and ConfigMaps across | ||
| Namespaces in Openshift. | ||
| The OpenShift Shared Resource CSI Driver allows `Secrets` and `ConfigMaps` to be | ||
| shared across Kubernetes namespaces in a controlled manner. This CSI driver | ||
| ensures that the entity (ServiceAccount) accessing the shared Secret or ConfigMap | ||
| has permission to do so before mounting the data as a volume into the requesting | ||
| Pod. | ||
|
|
||
| The API used to achieve this support are: | ||
| This CSI driver only supports the `Ephemeral` volume lifecycle mode. | ||
| It also requires the following during operation: | ||
|
|
||
| - the `volume` and `volumeMount` fields of a Kubernetes Pod | ||
| - a new `SharedConfigMap` Kubernetes Custom Resource Definition which specifies which ConfigMap is to be shared, and which | ||
| serves as the resource in Kubernetes Subject Access Review checks | ||
| - a new `SharedSecret` Kubernetes Custom Resource Definition which specifies which Secret is to be shared, and which | ||
| serves as the resource in Kubernetes Subject Access Review checks | ||
|
|
||
| ## Features | ||
|
|
||
| - Supports only a subset of the Kubernetes CSIVolumeSource API. See [CSI Volume Specifics](docs/csi.md) for details. | ||
| - Initial pod requests for `SharedConfigMap` or `SharedSecret` CSI volumes are denied without both a valid `SharedConfigMap` or `SharedSecret` reference and | ||
| permissions to access that `SharedConfigMap` or `SharedSecret`. | ||
| - Changes to the `SharedConfigMap` or `SharedSecret` backing resource (namespace, name) get reflected in data stored in the user pod's CSI volume. | ||
| - Subsequent removal of permissions for a `SharedConfigMap` or `SharedSecret` results in removal of the associated data stored in the user pod's CSI volume. | ||
| - Re-granting of permission for a `SharedConfigMap` or `SharedSecret` (after having the permissions initially, then removed) results in the associated | ||
| data getting stored in the user pod's CSI volume. | ||
| - Removal of the `SharedConfigMap` or `SharedSecret` used to provision a `SharedConfigMap` or `SharedSecret` csi volume for a pod results in the associated data getting removed. | ||
| - Re-creation of a removed `SharedConfigMap` or `SharedSecret` for a previously provisioned `SharedConfigMap` or `SharedSecret` CSI volume results in the associated data | ||
| reappearing in the user pod's CSI volume. | ||
| - Supports recycling of the csi driver so that previously provisioned CSI volumes are still managed; in other words, | ||
| the driver's internal state is persisted. | ||
| - Multiple `SharedResources` within a pod are allowed. | ||
| - When multiple `SharedResources` are mounted in a pod, one `SharedConfigMap` or `SharedSecret` can be mounted as a subdirectory of another `SharedConfigMap` or `SharedSecret`. | ||
|
|
||
|
|
||
| NOTE: see [CSI Volume Specifics](docs/csi.md) for restrictions around these features for read-only Volumes. | ||
| - `podInfoOnMount: true` | ||
| - `fsGroupPolicy: File` | ||
| - `attachRequired: false` | ||
|
|
||
| ## Getting Started | ||
|
|
||
| The maintenance of the related API objects and the deployment of this CSI driver are handled via the [Openshift CSI Driver for Shared Resources Operator](https://github.com/openshift/csi-driver-shared-resource-operator) | ||
| when you are using a Tech Preview OpenShift Cluster in 4.10. The 4.10 release docs are [here](https://docs.openshift.com/container-platform/4.10/storage/container_storage_interface/ephemeral-storage-shared-resource-csi-driver-operator.html), | ||
| and these [4.10 docs](https://docs.openshift.com/container-platform/4.10/post_installation_configuration/cluster-tasks.html#post-install-tp-tasks) are | ||
| sufficient for explaining how to turn on Tech Preview features after install. | ||
| The easiest way to use the Shared Resource CSI Driver is to deploy OpenShift | ||
| v4.10 or higher, and enable the | ||
| [Tech Preview Features](https://docs.openshift.com/container-platform/latest/post_installation_configuration/cluster-tasks.html#post-install-tp-tasks). | ||
|
|
||
| ## How To Use | ||
|
|
||
| 1. Create a `Secret` or `ConfigMap` that you wish to share in a "source" namespace. | ||
|
|
||
| ```yaml | ||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: shared-config | ||
| namespace: default # This can be any desired "source" namespace | ||
| data: | ||
| config.txt: "Hello world!" | ||
| ``` | ||
|
|
||
| 2. Create a `SharedSecret` or `SharedConfigMap` instance to make your resource shareable: | ||
|
|
||
| ```yaml | ||
| apiVersion: sharedresource.openshift.io/v1alpha1 | ||
| kind: SharedConfigMap | ||
| metadata: | ||
| name: share-default-config | ||
| spec: | ||
| configMapRef: | ||
| name: shared-config | ||
| namespace: default | ||
| ``` | ||
|
|
||
| 3. Grant the desired `SeviceAccount` in the "target" namespace permission to use the shared resource above: | ||
|
|
||
| ```yaml | ||
| --- | ||
| apiVersion: rbac.authorization.k8s.io/v1 | ||
| kind: Role | ||
| metadata: | ||
| name: use-shared-default-config | ||
| namespace: app-namespace # This is the "target" namespace | ||
| rules: | ||
| - apiGroups: | ||
| - sharedresource.openshift.io | ||
| resources: | ||
| - sharedconfigmaps | ||
| resourceNames: | ||
| - share-default-config | ||
| verbs: | ||
| - use | ||
| --- | ||
| apiVersion: rbac.authorization.k8s.io/v1 | ||
| kind: RoleBinding | ||
| metadata: | ||
| name: use-shared-default-config | ||
| namespace: app-namespace | ||
| roleRef: | ||
| apiGroup: rbac.authorization.k8s.io | ||
| kind: Role | ||
| name: use-shared-default-config | ||
| subjects: | ||
| - kind: ServiceAccount | ||
| name: default | ||
| namespace: app-namespace | ||
| ``` | ||
|
|
||
| 4. Mount the shared resource into a `Pod` (or other resource that accepts `CSI` Volumes): | ||
|
|
||
| ```yaml | ||
| apiVersion: v1 | ||
| kind: Pod | ||
| metadata: | ||
| name: example-shared-config | ||
| namespace: app-namespace | ||
| spec: | ||
| ... | ||
| serviceAccountName: default | ||
| volumes: | ||
| - name: shared-config | ||
| csi: | ||
| readOnly: true | ||
| driver: csi.sharedresource.openshift.io | ||
| volumeAttributes: | ||
| sharedConfigMap: share-default-config | ||
| ``` | ||
|
|
||
| See also: | ||
|
|
||
| - [Simple example](docs/simple-example.md) | ||
| - [Tekton example](docs/tekton-example.md) | ||
| - [OpenShift BuildConfig example](docs/build-with-rhel-entitlements.md) | ||
|
|
||
| For running on a 4.10 cluster which is *NOT* a Tech Preview cluster, you must employ the methodology described in the [Local Devlopment](#local-development) | ||
| section. | ||
|
|
||
| Once installed, the permission semantics around sharing resources is the next concern to consider. In summary: | ||
| - the `ServiceAccount` associated with a `Pod` needs access to the 'use' verb on the `SharedConfigMap` or `SharedSecret` referenced by any `CSIVolume` | ||
| specified in a `Pod` that uses this repository's CSI Driver. | ||
| - separately, any `User` can discover cluster scoped `SharedResources` based on the 'get' or 'list' permissions granted to them by their cluster | ||
| or namespace administrator. | ||
|
|
||
| The full definition of the `SharedConfigMap` can be found [here](deploy/0000_10_sharedconfigmap.crd.yaml) or `SharedSecret` custom resource can be found [here](deploy/0000_10_sharedsecret.crd.yaml). | ||
|
|
||
| Under the [examples directory](examples) there is both a simple example of using a `SharedConfigMap` in a `Pod`, and an | ||
| example of performing an OpenShift `Build` from a `BuildConfig` that uses Red Hat Entitlements available from your Red Hat Subscription when | ||
| your subscription credentials are stored on your cluster via OpenShift Insights Operator, and resulting `Secret` for those | ||
| credentials is made available to additional `Namespaces` via a `SharedSecret`. Instructions for the `Pod` example are | ||
| [here](docs/simple-example.md), and for the `BuildConfig` example are [here](docs/build-with-rhel-entitlements.md). | ||
| ## Features | ||
|
|
||
| Next, for some details around support for updating `SharedConfigMap` or `SharedSecret` volumes as their corresponding Secrets or ConfigMaps change, | ||
| please visit [here](docs/content-update-details.md). | ||
| - ServiceAccounts must have the `use` permission to mount the respective | ||
| `SharedSecret` or `SharedConfigMap`. Volumes fail to mount otherwise - see | ||
| [FAQ](docs/faq.md) for more details. | ||
| - Automatic sync of the shared resource data (Secret/ConfigMap) into the mounting | ||
| `Pod`. | ||
| - Automatic removal/restoration of shared resource data if the Pod's RBAC | ||
| permissions change at runtime. | ||
| - Automatic removal/restoration of shared resource data if the backing | ||
| Secret/ConfigMap is deleted/re-created. | ||
| - Survival of shared resource data with CSI driver restarts/upgrades. | ||
| - Multiple `SharedSecret`/`SharedConfig` volumes within a `Pod`. Also supports | ||
| nested volume mounts within a container. | ||
|
|
||
| The following CSI interfaces are implemented: | ||
|
|
||
| - **Identity Service**: GetPluginInfo, GetPluginCapabilities, Probe | ||
| - **Node Service**: NodeGetInfo, NodeGetCapabilities, NodePublishVolume, NodeUnpublishVolume | ||
| - **Controller Service**: _not implemented_. | ||
|
|
||
| Lastly, for a depiction of details around the [features noted above](#features), check out this [FAQ](docs/faq.md). | ||
| NOTE: see [CSI Volume Specifics](docs/csi.md) for restrictions around these features for read-only Volumes. | ||
|
|
||
| ## Local Development | ||
| ## FAQ | ||
|
|
||
| If you are going to make code changes to this driver, and you'd like to test them against an OpenShift cluster, run the | ||
| `build-image` make target in this repository to capture those changes in an image reference whose remote registry and repository you can push | ||
| to, and then employ the steps described in the [Openshift CSI Driver for Shared Resources Operator Quick Start](https://github.com/openshift/csi-driver-shared-resource-operator/blob/master/README.md#quick-start), | ||
| where you set the `DRIVER_IMAGE` environment variable to the image reference created by your `make build-image` against | ||
| your local clone of this repository. | ||
| Please refer to the [FAQ Guide](docs/faq.md) for commonly asked questions. | ||
|
|
||
| See that operator's [quick start guide](https://github.com/openshift/csi-driver-shared-resource-operator#quick-start) for | ||
| complete details. | ||
| ## Development | ||
|
|
||
| NOTE: changes to API objects that act in concert with the driver (RBAC, CSI Driver definition, service, serviceaccounts, etc) | ||
| are defined at [https://github.com/openshift/csi-driver-shared-resource-operator/tree/master/assets](https://github.com/openshift/csi-driver-shared-resource-operator/tree/master/assets). | ||
| If your changes need adjustments to those objects, you'll need to use `make deploy` to rollout a new version of the operator, | ||
| per the same quick start guide. | ||
| See the [development guide](docs/local-development.md) on how to build and test locally. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # Local Development | ||
|
|
||
| If you are going to make code changes to this driver, and you'd like to test them against an OpenShift cluster, run the | ||
| `build-image` make target in this repository to capture those changes in an image reference whose remote registry and repository you can push | ||
| to, and then employ the steps described in the [Openshift CSI Driver for Shared Resources Operator Quick Start](https://github.com/openshift/csi-driver-shared-resource-operator/blob/master/README.md#quick-start), | ||
| where you set the `DRIVER_IMAGE` environment variable to the image reference created by your `make build-image` against | ||
| your local clone of this repository. | ||
|
|
||
| See that operator's [quick start guide](https://github.com/openshift/csi-driver-shared-resource-operator#quick-start) for | ||
| complete details. | ||
|
|
||
| NOTE: changes to API objects that act in concert with the driver (RBAC, CSI Driver definition, service, serviceaccounts, etc) | ||
| are defined at [https://github.com/openshift/csi-driver-shared-resource-operator/tree/master/assets](https://github.com/openshift/csi-driver-shared-resource-operator/tree/master/assets). | ||
| If your changes need adjustments to those objects, you'll need to use `make deploy` to rollout a new version of the operator, | ||
| per the same quick start guide. |