From b592e1f6e88fa1acf83495f79620f546d4d2e163 Mon Sep 17 00:00:00 2001 From: Paul Morie Date: Mon, 14 Dec 2015 13:59:07 -0500 Subject: [PATCH] Add information about ownership management, selinux relabeling to volumes --- pkg/api/types.go | 52 +++++++++++++++++++++++------------ pkg/api/v1/types.go | 66 +++++++++++++++++++++++++++++---------------- 2 files changed, 78 insertions(+), 40 deletions(-) diff --git a/pkg/api/types.go b/pkg/api/types.go index 292458f5f6aa5..b3c6ea25bbbc9 100644 --- a/pkg/api/types.go +++ b/pkg/api/types.go @@ -386,12 +386,14 @@ const ( ClaimBound PersistentVolumeClaimPhase = "Bound" ) -// HostPathVolumeSource represents a host directory mapped into a pod. +// Represents a host path mapped into a pod. +// Host path volumes do not support ownership management or SELinux relabeling. type HostPathVolumeSource struct { Path string `json:"path"` } -// EmptyDirVolumeSource represents an empty directory for a pod. +// Represents an empty directory for a pod. +// Empty directory volumes support ownership management and SELinux relabeling. type EmptyDirVolumeSource struct { // TODO: Longer term we want to represent the selection of underlying // media more like a scheduling problem - user says what traits they @@ -399,7 +401,7 @@ type EmptyDirVolumeSource struct { // this will cover the most common needs. // Optional: what type of storage medium should back this directory. // The default is "" which means to use the node's default medium. - Medium StorageMedium `json:"medium"` + Medium StorageMedium `json:"medium,omitempty"` } // StorageMedium defines ways that storage can be allocated to a volume. @@ -420,11 +422,12 @@ const ( ProtocolUDP Protocol = "UDP" ) -// GCEPersistentDiskVolumeSource represents a Persistent Disk resource in Google Compute Engine. +// Represents a Persistent Disk resource in Google Compute Engine. // // A GCE PD must exist and be formatted before mounting to a container. // The disk must also be in the same GCE project and zone as the kubelet. // A GCE PD can only be mounted as read/write once. +// GCE PDs support ownership management and SELinux relabeling. type GCEPersistentDiskVolumeSource struct { // Unique name of the PD resource. Used to identify the disk in GCE PDName string `json:"pdName"` @@ -442,7 +445,9 @@ type GCEPersistentDiskVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// A ISCSI Disk can only be mounted as read/write once. +// Represents an ISCSI disk. +// ISCSI volumes can only be mounted as read/write once. +// ISCSI volumes support ownership management and SELinux relabeling. type ISCSIVolumeSource struct { // Required: iSCSI target portal // the portal is either an IP or ip_addr:port if port is other than default (typically TCP ports 860 and 3260) @@ -463,7 +468,9 @@ type ISCSIVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// A Fibre Channel Disk can only be mounted as read/write once. +// Represents a Fibre Channel volume. +// Fibre Channel volumes can only be mounted as read/write once. +// Fibre Channel volumes support ownership management and SELinux relabeling. type FCVolumeSource struct { // Required: FC target world wide names (WWNs) TargetWWNs []string `json:"targetWWNs"` @@ -479,11 +486,12 @@ type FCVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// AWSElasticBlockStoreVolumeSource represents a Persistent Disk resource in AWS. +// Represents a Persistent Disk resource in AWS. // // An AWS EBS disk must exist and be formatted before mounting to a container. // The disk must also be in the same AWS zone as the kubelet. // A AWS EBS disk can only be mounted as read/write once. +// AWS EBS volumes support ownership management and SELinux relabeling. type AWSElasticBlockStoreVolumeSource struct { // Unique id of the persistent disk resource. Used to identify the disk in AWS VolumeID string `json:"volumeID"` @@ -501,7 +509,9 @@ type AWSElasticBlockStoreVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// GitRepoVolumeSource represents a volume that is pulled from git when the pod is created. +// Represents a volume that is populated with the contents of a git repository. +// Git repo volumes do not support ownership management. +// Git repo volumes support SELinux relabeling. type GitRepoVolumeSource struct { // Repository URL Repository string `json:"repository"` @@ -515,16 +525,18 @@ type GitRepoVolumeSource struct { // TODO: Consider credentials here. } -// SecretVolumeSource adapts a Secret into a VolumeSource. +// Adapts a Secret into a volume. // // The contents of the target Secret's Data field will be presented in a volume // as files using the keys in the Data field as the file names. +// Secret volumes support ownership management and SELinux relabeling. type SecretVolumeSource struct { // Name of the secret in the pod's namespace to use SecretName string `json:"secretName"` } -// NFSVolumeSource represents an NFS Mount that lasts the lifetime of a pod +// Represents an NFS mount that lasts the lifetime of a pod. +// NFS volumes do not support ownership management or SELinux relabeling. type NFSVolumeSource struct { // Server is the hostname or IP address of the NFS server Server string `json:"server"` @@ -537,7 +549,8 @@ type NFSVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// GlusterfsVolumeSource represents a Glusterfs Mount that lasts the lifetime of a pod +// Represents a Glusterfs mount that lasts the lifetime of a pod. +// Glusterfs volumes do not support ownership management or SELinux relabeling. type GlusterfsVolumeSource struct { // Required: EndpointsName is the endpoint name that details Glusterfs topology EndpointsName string `json:"endpoints"` @@ -550,7 +563,8 @@ type GlusterfsVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// RBDVolumeSource represents a Rados Block Device Mount that lasts the lifetime of a pod +// Represents a Rados Block Device mount that lasts the lifetime of a pod. +// RBD volumes support ownership management and SELinux relabeling. type RBDVolumeSource struct { // Required: CephMonitors is a collection of Ceph monitors CephMonitors []string `json:"monitors"` @@ -574,9 +588,10 @@ type RBDVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// CinderVolumeSource represents a cinder volume resource in Openstack. +// Represents a cinder volume resource in Openstack. // A Cinder volume must exist and be formatted before mounting to a container. // The volume must also be in the same region as the kubelet. +// Cinder volumes support ownership management and SELinux relabeling. type CinderVolumeSource struct { // Unique id of the volume used to identify the cinder volume VolumeID string `json:"volumeID"` @@ -589,7 +604,8 @@ type CinderVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// CephFSVolumeSource represents a Ceph Filesystem Mount that lasts the lifetime of a pod +// Represents a Ceph Filesystem mount that lasts the lifetime of a pod +// Cephfs volumes do not support ownership management or SELinux relabeling. type CephFSVolumeSource struct { // Required: Monitors is a collection of Ceph monitors Monitors []string `json:"monitors"` @@ -604,19 +620,21 @@ type CephFSVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// FlockerVolumeSource represents a Flocker volume mounted by the Flocker agent. +// Represents a Flocker volume mounted by the Flocker agent. +// Flocker volumes do not support ownership management or SELinux relabeling. type FlockerVolumeSource struct { // Required: the volume name. This is going to be store on metadata -> name on the payload for Flocker DatasetName string `json:"datasetName"` } -// DownwardAPIVolumeSource represents a volume containing downward API info +// Represents a volume containing downward API info. +// Downward API volumes support ownership management and SELinux relabeling. type DownwardAPIVolumeSource struct { // Items is a list of DownwardAPIVolume file Items []DownwardAPIVolumeFile `json:"items,omitempty"` } -// DownwardAPIVolumeFile represents a single file containing information from the downward API +// Represents a single file containing information from the downward API type DownwardAPIVolumeFile struct { // Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' Path string `json:"path"` diff --git a/pkg/api/v1/types.go b/pkg/api/v1/types.go index eceb2682751ca..0f97a77a52333 100644 --- a/pkg/api/v1/types.go +++ b/pkg/api/v1/types.go @@ -198,7 +198,7 @@ type Volume struct { VolumeSource `json:",inline"` } -// VolumeSource represents the source location of a volume to mount. +// Represents the source of a volume to mount. // Only one of its members may be specified. type VolumeSource struct { // HostPath represents a pre-existing file or directory on the host @@ -484,14 +484,16 @@ const ( ClaimBound PersistentVolumeClaimPhase = "Bound" ) -// HostPathVolumeSource represents bare host directory volume. +// Represents a host path mapped into a pod. +// Host path volumes do not support ownership management or SELinux relabeling. type HostPathVolumeSource struct { // Path of the directory on the host. // More info: http://releases.k8s.io/HEAD/docs/user-guide/volumes.md#hostpath Path string `json:"path"` } -// EmptyDirVolumeSource is temporary directory that shares a pod's lifetime. +// Represents an empty directory for a pod. +// Empty directory volumes support ownership management and SELinux relabeling. type EmptyDirVolumeSource struct { // What type of storage medium should back this directory. // The default is "" which means to use the node's default medium. @@ -500,7 +502,8 @@ type EmptyDirVolumeSource struct { Medium StorageMedium `json:"medium,omitempty"` } -// GlusterfsVolumeSource represents a Glusterfs Mount that lasts the lifetime of a pod. +// Represents a Glusterfs mount that lasts the lifetime of a pod. +// Glusterfs volumes do not support ownership management or SELinux relabeling. type GlusterfsVolumeSource struct { // EndpointsName is the endpoint name that details Glusterfs topology. // More info: http://releases.k8s.io/HEAD/examples/glusterfs/README.md#create-a-pod @@ -516,10 +519,8 @@ type GlusterfsVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// StorageMedium defines ways that storage can be allocated to a volume. -type StorageMedium string - -// RBDVolumeSource represents a Rados Block Device Mount that lasts the lifetime of a pod +// Represents a Rados Block Device mount that lasts the lifetime of a pod. +// RBD volumes support ownership management and SELinux relabeling. type RBDVolumeSource struct { // A collection of Ceph monitors. // More info: http://releases.k8s.io/HEAD/examples/rbd/README.md#how-to-use-it @@ -556,9 +557,10 @@ type RBDVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// CinderVolumeSource represents a cinder volume resource in Openstack. +// Represents a cinder volume resource in Openstack. // A Cinder volume must exist before mounting to a container. // The volume must also be in the same region as the kubelet. +// Cinder volumes support ownership management and SELinux relabeling. type CinderVolumeSource struct { // volume id used to identify the volume in cinder // More info: http://releases.k8s.io/HEAD/examples/mysql-cinder-pd/README.md @@ -574,7 +576,8 @@ type CinderVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// CephFSVolumeSource represents a Ceph Filesystem Mount that lasts the lifetime of a pod +// Represents a Ceph Filesystem mount that lasts the lifetime of a pod +// Cephfs volumes do not support ownership management or SELinux relabeling. type CephFSVolumeSource struct { // Required: Monitors is a collection of Ceph monitors // More info: http://releases.k8s.io/HEAD/examples/cephfs/README.md#how-to-use-it @@ -594,12 +597,16 @@ type CephFSVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// FlockerVolumeSource represents a Flocker volume mounted by the Flocker agent. +// Represents a Flocker volume mounted by the Flocker agent. +// Flocker volumes do not support ownership management or SELinux relabeling. type FlockerVolumeSource struct { // Required: the volume name. This is going to be store on metadata -> name on the payload for Flocker DatasetName string `json:"datasetName"` } +// StorageMedium defines ways that storage can be allocated to a volume. +type StorageMedium string + const ( StorageMediumDefault StorageMedium = "" // use whatever the default is for the node StorageMediumMemory StorageMedium = "Memory" // use memory (tmpfs) @@ -615,11 +622,12 @@ const ( ProtocolUDP Protocol = "UDP" ) -// GCEPersistentDiskVolumeSource represents a Persistent Disk resource in Google Compute Engine. +// Represents a Persistent Disk resource in Google Compute Engine. // // A GCE PD must exist and be formatted before mounting to a container. // The disk must also be in the same GCE project and zone as the kubelet. // A GCE PD can only be mounted as read/write once. +// GCE PDs support ownership management and SELinux relabeling. type GCEPersistentDiskVolumeSource struct { // Unique name of the PD resource in GCE. Used to identify the disk in GCE. // More info: http://releases.k8s.io/HEAD/docs/user-guide/volumes.md#gcepersistentdisk @@ -642,11 +650,12 @@ type GCEPersistentDiskVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// Represents a persistent disk resource in AWS. +// Represents a Persistent Disk resource in AWS. // -// An Amazon Elastic Block Store (EBS) must already be created, formatted, -// and reside in the same AWS zone as the kubelet before it can be mounted. -// Note: Amazon EBS volumes can be mounted to only one instance at a time. +// An AWS EBS disk must exist and be formatted before mounting to a container. +// The disk must also be in the same AWS zone as the kubelet. +// An AWS EBS disk can only be mounted as read/write once. +// AWS EBS volumes support ownership management and SELinux relabeling. type AWSElasticBlockStoreVolumeSource struct { // Unique ID of the persistent disk resource in AWS (Amazon EBS volume). // More info: http://releases.k8s.io/HEAD/docs/user-guide/volumes.md#awselasticblockstore @@ -668,7 +677,9 @@ type AWSElasticBlockStoreVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// GitRepoVolumeSource represents a volume that is pulled from git when the pod is created. +// Represents a volume that is populated with the contents of a git repository. +// Git repo volumes do not support ownership management. +// Git repo volumes support SELinux relabeling. type GitRepoVolumeSource struct { // Repository URL Repository string `json:"repository"` @@ -681,15 +692,19 @@ type GitRepoVolumeSource struct { Directory string `json:"directory,omitempty"` } -// SecretVolumeSource adapts a Secret into a VolumeSource. -// More info: http://releases.k8s.io/HEAD/docs/design/secrets.md +// Adapts a Secret into a volume. +// +// The contents of the target Secret's Data field will be presented in a volume +// as files using the keys in the Data field as the file names. +// Secret volumes support ownership management and SELinux relabeling. type SecretVolumeSource struct { // SecretName is the name of a secret in the pod's namespace. // More info: http://releases.k8s.io/HEAD/docs/user-guide/volumes.md#secrets SecretName string `json:"secretName"` } -// NFSVolumeSource represents an NFS mount that lasts the lifetime of a pod +// Represents an NFS mount that lasts the lifetime of a pod. +// NFS volumes do not support ownership management or SELinux relabeling. type NFSVolumeSource struct { // Server is the hostname or IP address of the NFS server. // More info: http://releases.k8s.io/HEAD/docs/user-guide/volumes.md#nfs @@ -706,7 +721,9 @@ type NFSVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// ISCSIVolumeSource describes an ISCSI Disk can only be mounted as read/write once. +// Represents an ISCSI disk. +// ISCSI volumes can only be mounted as read/write once. +// ISCSI volumes support ownership management and SELinux relabeling. type ISCSIVolumeSource struct { // iSCSI target portal. The portal is either an IP or ip_addr:port if the port // is other than default (typically TCP ports 860 and 3260). @@ -728,7 +745,9 @@ type ISCSIVolumeSource struct { ReadOnly bool `json:"readOnly,omitempty"` } -// A Fibre Channel Disk can only be mounted as read/write once. +// Represents a Fibre Channel volume. +// Fibre Channel volumes can only be mounted as read/write once. +// Fibre Channel volumes support ownership management and SELinux relabeling. type FCVolumeSource struct { // Required: FC target world wide names (WWNs) TargetWWNs []string `json:"targetWWNs"` @@ -2523,7 +2542,8 @@ type ComponentStatusList struct { Items []ComponentStatus `json:"items"` } -// DownwardAPIVolumeSource represents a volume containing downward API info +// DownwardAPIVolumeSource represents a volume containing downward API info. +// Downward API volumes support ownership management and SELinux relabeling. type DownwardAPIVolumeSource struct { // Items is a list of downward API volume file Items []DownwardAPIVolumeFile `json:"items,omitempty"`