mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
OSDOCS-15380# selinuxChangePolicy and fsGroupChangePolicy per namespace (TP)
This commit is contained in:
Lisa Pettyjohn
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
4ebb33792f
commit
fc07194ff3
@@ -0,0 +1,18 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: CONCEPT
|
||||
[id="storage_persistent_storage_change_policy_overview_{context}"]
|
||||
= Reducing pod timeouts
|
||||
|
||||
A volume with many files can cause pod startup delays and timeouts. You can set certain parameters to improve this issue.
|
||||
|
||||
* *fsGroup*
|
||||
+
|
||||
Set `fsGroupChangePolicy` to `OnRootMismatch` to stop recursively changing ownership and permissions to match the fsGroup specified in a pod’s `securityContext`.
|
||||
|
||||
* *SELinux*
|
||||
+
|
||||
Set `seLinuxChangePolicy` to `MountOption` to avoid runtime recursively relabeling all files on a volume to match the pod’s SELinux context.
|
||||
54
modules/storage-persistent-storage-fsGroup-namespace.adoc
Normal file
54
modules/storage-persistent-storage-fsGroup-namespace.adoc
Normal file
@@ -0,0 +1,54 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="using_fsGroup_namespace_{context}"]
|
||||
= Changing fsGroup at the namespace level
|
||||
|
||||
After applying the desired setting for `fsGroupChangePolicy` at the namespace level, all subsequently created pods in that namespace inherit the setting. However, if desired, you can override the inherited `fsGroupChangePolicy` setting for individual pods. Setting `fsGroupChangePolicy` at the pod level overrides inheritance from the namespace level setting for that pod.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* Logged in to a running {product-title} cluster with administrator privileges.
|
||||
|
||||
* Access to the {product-title} console.
|
||||
|
||||
.Procedure
|
||||
|
||||
To set `fsGroupChangePolicy` per namespace:
|
||||
|
||||
. Select the desired namespace:
|
||||
|
||||
.. Click *Administration* > *Namespaces*.
|
||||
|
||||
.. On the *Namespaces* page, click the desired namespace. The *Namespace details* page appears.
|
||||
|
||||
. Add the `fsGroupChangePolicy` label to the namespace:
|
||||
|
||||
.. On the *Namespace details* page, next to *Labels*, click *Edit*.
|
||||
|
||||
.. In the *Edit labels* dialog, add the label `storage.openshift.io/fsgroup-change-policy` and set it equal to either:
|
||||
+
|
||||
* `OnRootMismatch`: Specifies only changing permissions and ownership if the permission and the ownership of root directory does not match with expected permissions of the volume, thus helping to avoid pod timeout problems.
|
||||
* `Always`: (Default) Specifies always changing permission and ownership of the volume when a volume is mounted.
|
||||
|
||||
.. Click *Save*.
|
||||
|
||||
.Verification
|
||||
Start up a pod in the previously edited namespace and observe that the parameter `spec.securityContext.fsGroupChangePolicy` contains the value that you set for the namespace.
|
||||
|
||||
.Example pod YAML file showing `fsGroupChangePolicy` setting
|
||||
[source,yaml]
|
||||
----
|
||||
securityContext:
|
||||
seLinuxOptions:
|
||||
level: 's0:c27,c24'
|
||||
runAsNonRoot: true
|
||||
fsGroup: 1000750000
|
||||
fsGroupChangePolicy: OnRootMismatch <1>
|
||||
...
|
||||
----
|
||||
<1> This value is inherited from the namespace.
|
||||
|
||||
64
modules/storage-persistent-storage-fsGroup-pod.adoc
Normal file
64
modules/storage-persistent-storage-fsGroup-pod.adoc
Normal file
@@ -0,0 +1,64 @@
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
[id="using_fsGroup_pod_{context}"]
|
||||
= Changing fsGroup at the pod level
|
||||
|
||||
You can set the set the `fsGroupChangePolicy` parameter in a new or existing deployment, and then the pods that it manages will have this parameter value. You can similarly do this for a statefulset. You cannot edit an existing pod to set `fsGroupChangePolicy`; however, you can set this parameter when creating a new pod.
|
||||
|
||||
This procedure describes how to set the `fsGroupChangePolicy` parameter in an existing deployment.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* Access to the {product-title} console.
|
||||
|
||||
.Procedure
|
||||
|
||||
To set the `fsGroupChangePolicy` parameter in an existing deployment:
|
||||
|
||||
. Click *Workloads* > *Deployments*.
|
||||
|
||||
. On the *Deployment* page, click the desired deployment.
|
||||
|
||||
. On the *Deployment details* page, click the *YAML* tab.
|
||||
|
||||
. Edit the deployment's YAML file under `spec.template.spec.securityContext` using the following example file:
|
||||
+
|
||||
.Example deployment YAML file setting `fsGroupChangePolicy`
|
||||
[source,yaml]
|
||||
----
|
||||
...
|
||||
spec:
|
||||
replicas: 3
|
||||
selector:
|
||||
matchLabels:
|
||||
app: my-app
|
||||
template:
|
||||
metadata:
|
||||
creationTimestamp: null
|
||||
labels:
|
||||
app: my-app
|
||||
spec:
|
||||
containers:
|
||||
- name: container
|
||||
image: 'image-registry.openshift-image-registry.svc:5000/openshift/httpd:latest'
|
||||
ports:
|
||||
- containerPort: 8080
|
||||
protocol: TCP
|
||||
resources: {}
|
||||
terminationMessagePath: /dev/termination-log
|
||||
terminationMessagePolicy: File
|
||||
imagePullPolicy: Always
|
||||
restartPolicy: Always
|
||||
terminationGracePeriodSeconds: 30
|
||||
dnsPolicy: ClusterFirst
|
||||
securityContext:
|
||||
fsGroupChangePolicy: OnRootMismatch <1>
|
||||
...
|
||||
----
|
||||
<1> `OnRootMismatch` specifies skipping recursive permission change, thus helping to avoid pod timeout problems. The default value is `Always`, which always changes permission and ownership of the volume when a volume is mounted.
|
||||
|
||||
. Click *Save*.
|
||||
@@ -3,33 +3,23 @@
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: CONCEPT
|
||||
[id="using_fsGroup_overview_{context}"]
|
||||
= Reducing pod timeouts using fsGroup
|
||||
|
||||
[id="using_fsGroup_{context}"]
|
||||
= Using fsGroup to reduce pod timeouts
|
||||
If a storage volume contains many files (for example, a million or more), you might experience pod timeouts.
|
||||
|
||||
If a storage volume contains many files (~1,000,000 or greater), you may experience pod timeouts.
|
||||
|
||||
This can occur because, by default, {product-title} recursively changes ownership and permissions for the contents of each volume to match the `fsGroup` specified in a pod's `securityContext` when that volume is mounted. For large volumes, checking and changing ownership and permissions can be time consuming, slowing pod startup. You can use the `fsGroupChangePolicy` field inside a `securityContext` to control the way that {product-title} checks and manages ownership and permissions for a volume.
|
||||
This can occur because, by default, {product-title} recursively changes ownership and permissions for the contents of each volume to match the `fsGroup` specified in a pod's `securityContext` when that volume is mounted. For volumes with many files, checking and changing ownership and permissions can be time consuming, slowing pod startup. You can use the `fsGroupChangePolicy` field inside a `securityContext` to control the way that {product-title} checks and manages ownership and permissions for a volume.
|
||||
|
||||
`fsGroupChangePolicy` defines behavior for changing ownership and permission of the volume before being exposed inside a pod. This field only applies to volume types that support `fsGroup`-controlled ownership and permissions. This field has two possible values:
|
||||
|
||||
* `OnRootMismatch`: Only change permissions and ownership if permission and ownership of root directory does not match with expected permissions of the volume. This can help shorten the time it takes to change ownership and permission of a volume to reduce pod timeouts.
|
||||
|
||||
* `Always`: Always change permission and ownership of the volume when a volume is mounted.
|
||||
|
||||
.`fsGroupChangePolicy` example
|
||||
[source,yaml]
|
||||
----
|
||||
securityContext:
|
||||
runAsUser: 1000
|
||||
runAsGroup: 3000
|
||||
fsGroup: 2000
|
||||
fsGroupChangePolicy: "OnRootMismatch" <1>
|
||||
...
|
||||
----
|
||||
<1> `OnRootMismatch` specifies skipping recursive permission change, thus helping to avoid pod timeout problems.
|
||||
* `Always`: (Default) Always change permission and ownership of the volume when a volume is mounted.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The fsGroupChangePolicyfield has no effect on ephemeral volume types, such as secret, configMap, and emptydir.
|
||||
The `fsGroupChangePolicy` field has no effect on ephemeral volume types, such as secret, configMap, and emptydir.
|
||||
====
|
||||
|
||||
You can set `fsGroupChangePolicy` at either the namespace or pod level.
|
||||
|
||||
@@ -130,7 +130,7 @@ The following table lists the access modes:
|
||||
|ReadWriteOnce
|
||||
|`RWO`
|
||||
|The volume can be mounted as read-write by a single node.
|
||||
|ReadWriteOncePod ^[1]^
|
||||
|ReadWriteOncePod
|
||||
|`RWOP`
|
||||
|The volume can be mounted as read-write by a single pod on a single node.
|
||||
ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
|
||||
@@ -142,13 +142,6 @@ ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
|
||||
|The volume can be mounted as read-write by many nodes.
|
||||
endif::[]
|
||||
|===
|
||||
--
|
||||
1. RWOP uses the SELinux mount feature. This feature is driver dependent, and enabled by default in AWS EBS
|
||||
ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
|
||||
, Azure Disk, GCP PD, IBM Cloud Block Storage volume, Cinder, vSphere,
|
||||
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
|
||||
and {rh-storage-first}. For third-party drivers, contact your storage vendor.
|
||||
--
|
||||
|
||||
.Supported access modes for persistent volumes
|
||||
[cols=",^v,^v,^v,^v", width="100%",options="header"]
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="using_selinuxChangePolicy_namespace_{context}"]
|
||||
= Changing seLinuxChangePolicy at the namespace level
|
||||
|
||||
After applying the desired setting for `seLinuxChangePolicy` at the namespace level, all subsequently created pods in that namespace inherit the setting. However, if desired, you can override the inherited `seLinuxChangePolicy` setting for individual pods. Setting `seLinuxChangePolicy` at the pod level overrides inheritance from the namespace level setting for that pod.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* Logged in to a running {product-title} cluster with administrator privileges.
|
||||
|
||||
* Access to the {product-title} console.
|
||||
|
||||
.Procedure
|
||||
|
||||
To set `SELinuxChangePolicy` per namespace:
|
||||
|
||||
. Select the desired namespace:
|
||||
|
||||
.. Click *Administration* > *Namespaces*.
|
||||
|
||||
.. On the *Namespaces* page, click the desired namespace. The *Namespace details* page appears.
|
||||
|
||||
. Add the `seLinuxChangePolicy` label to the namespace:
|
||||
|
||||
.. On the *Namespace details* page, next to *Labels*, click *Edit*.
|
||||
|
||||
.. In the *Edit labels* dialog, add the label `storage.openshift.io/selinux-change-policy=Recursive`.
|
||||
+
|
||||
This specifies recursively relabeling all files on pod volumes to the appropriate SELinux context.
|
||||
|
||||
.. Click *Save*.
|
||||
|
||||
.Verification
|
||||
Start up a pod in the previously edited namespace and observe that the parameter `spec.securityContext.seLinuxChangePolicy` is set to `Recursive`.
|
||||
|
||||
.Example pod YAML file showing `seLinuxChangePolicy` setting
|
||||
[source,yaml]
|
||||
----
|
||||
securityContext:
|
||||
seLinuxOptions:
|
||||
level: 's0:c27,c19'
|
||||
runAsNonRoot: true
|
||||
fsGroup: 1000740000
|
||||
seccompProfile:
|
||||
type: RuntimeDefault
|
||||
seLinuxChangePolicy: Recursive <1>
|
||||
...
|
||||
----
|
||||
<1> This value is inherited from the namespace.
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: CONCEPT
|
||||
[id="using_selinuxChangePolicy_pod-opt-out_{context}"]
|
||||
= Opting out of the SELinux mount option default
|
||||
|
||||
If you want to opt out of the future move to mount option as default, you can affirmatively set the `seLinuxChangePolicy` parameter to `Recursive` at either the individual pod or namespace level.
|
||||
@@ -0,0 +1,40 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="using_selinuxChangePolicy_pod_{context}"]
|
||||
= Changing seLinuxChangePolicy at the pod level
|
||||
|
||||
You can set the set the `seLinuxChangePolicy` parameter in a new or existing Deployment, and then the pods that it manages will have this parameter value. You can similarly do this for a StatefulSet. You cannot edit an existing pod to set `seLinuxChangePolicy`; however, you can set this parameter when creating a new pod.
|
||||
|
||||
This procedure describes how to set the `seLinuxChangePolicy` parameter in an existing deployment.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* Access to the {product-title} console.
|
||||
|
||||
.Procedure
|
||||
|
||||
To set the `seLinuxChangePolicy` parameter in an existing deployment:
|
||||
|
||||
. Click *Workloads* > *Deployments*.
|
||||
|
||||
. On the *Deployment* page, click the desired deployment.
|
||||
|
||||
. On the *Deployment details* page, click the *YAML* tab.
|
||||
|
||||
. Edit the deployment's YAML file under `spec.template.spec.securityContext` as per the following example file:
|
||||
+
|
||||
.Example deployment YAML file setting `seLinuxChangePolicy`
|
||||
[source,yaml]
|
||||
----
|
||||
...
|
||||
securityContext:
|
||||
seLinuxChangePolicy: Recursive <1>
|
||||
...
|
||||
----
|
||||
<1> Specifies recursively relabeling all files on all pod volumes to the appropriate SELinux context.
|
||||
|
||||
. Click *Save*.
|
||||
@@ -0,0 +1,19 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: PROCEDURE
|
||||
[id="using_selinuxChangePolicy_testing-mountoption-rwo-rwx_{context}"]
|
||||
= Testing the RWO and RWX and SELinux mount option feature
|
||||
|
||||
In {product-title} 4.20, you can evaluate the mount option feature for RWO and RWX volumes as a Technology Preview feature.
|
||||
|
||||
:FeatureName: RWO/RWX SELinux mount
|
||||
include::snippets/technology-preview.adoc[]
|
||||
|
||||
To evaluate the mount option feature:
|
||||
|
||||
* Enable Feature Gates. For information about enabling Feature Gates, see _Section Enabling features using feature gates_.
|
||||
+
|
||||
RWO and RWX volumes now have mount option as the default behavior.
|
||||
33
modules/storage-persistent-storage-selinuxChangePolicy.adoc
Normal file
33
modules/storage-persistent-storage-selinuxChangePolicy.adoc
Normal file
@@ -0,0 +1,33 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * storage/understanding-persistent-storage.adoc
|
||||
//* microshift_storage/understanding-persistent-storage-microshift.adoc
|
||||
|
||||
:_mod-docs-content-type: CONCEPT
|
||||
[id="using_selinuxChangePolicy_overview_{context}"]
|
||||
= Reducing pod timeouts using seLinuxChangePolicy
|
||||
|
||||
SELinux (Security-Enhanced Linux) is a security mechanism that assigns security labels (contexts) to all objects (files, processes, network ports, etc.) on a system. These labels determine what a process can access. In {product-title}, SELinux helps prevent containers from escaping and accessing the host system or other containers.
|
||||
|
||||
When a pod starts, the container runtime recursively relabels all files on a volume to match the pod's SELinux context. For volumes with many files, this can significantly increase pod startup times.
|
||||
|
||||
Mount option specifies avoiding recursive relabeling of all files by attempting to mount the volume with the correct SELinux label directly using the -o context mount option, thus helping to avoid pod timeout problems.
|
||||
|
||||
.RWOP and SELinux mount option
|
||||
|
||||
ReadWriteOncePod (RWOP) persistent volumes use the SELinux mount feature by default.
|
||||
|
||||
The mount option feature is driver dependent, and enabled by default in AWS EBS
|
||||
ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
|
||||
, Azure Disk, GCP PD, {ibm-cloud-title} Block Storage volume, Cinder, vSphere,
|
||||
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
|
||||
and {rh-storage-first}. For third-party drivers, contact your storage vendor.
|
||||
|
||||
.RWO and RWX and SELinux mount option
|
||||
|
||||
ReadWriteOnce (RWO) and ReadWriteMany (RWX) volumes use recursive relabeling by default.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
In a future {product-title} version, RWO and RWX volumes will use *mount option by default*.
|
||||
====
|
||||
@@ -48,4 +48,27 @@ include::modules/storage-persistent-storage-block-volume.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/storage-persistent-storage-block-volume-examples.adoc[leveloffset=+2]
|
||||
|
||||
//include::modules/storage-persistent-storage-change-policy-overview.adoc[leveloffset=+1] testing to see if I prefer letting this be two separate things (fsGroup and SELinux) as opposed to trying to tie them together.
|
||||
|
||||
include::modules/storage-persistent-storage-fsGroup.adoc[leveloffset=+1]
|
||||
|
||||
include::modules/storage-persistent-storage-fsGroup-namespace.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/storage-persistent-storage-fsGroup-pod.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/storage-persistent-storage-selinuxChangePolicy.adoc[leveloffset=+1]
|
||||
|
||||
To assist you with the upcoming move to the mount option default, {product-title} 4.20 reports SELinux-related conflicts when creating pods, and on running pods, to make you aware of potential conflicts, and to help you resolve them. For more information about this reporting, see this link:https://access.redhat.com/solutions/7131398[Kowledge Base article].
|
||||
|
||||
If you are unable to resolve the SELinux-related conflicts, you can proactively opt-out of the future move to mount option as default for selected pods or namespaces. To opt out, see _Opting out of the SELinux mount option default_.
|
||||
|
||||
include::modules/storage-persistent-storage-selinuxChangePolicy-testing-mountoption-RWO-RWX.adoc[leveloffset=+2]
|
||||
|
||||
Carefully test your applications and observe how they are using storage. Consult this link:https://access.redhat.com/solutions/7131398[Knowledge Base article] and consider opting out from using mount option if you are experiencing issues. See Section _Opting out of the SELinux mount option default_.
|
||||
|
||||
include::modules/storage-persistent-storage-selinuxChangePolicy-opt-out.adoc[leveloffset=+2]
|
||||
|
||||
include::modules/storage-persistent-storage-selinuxChangePolicy-namespace.adoc[leveloffset=+3]
|
||||
|
||||
include::modules/storage-persistent-storage-selinuxChangePolicy-pod.adoc[leveloffset=+3]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user