From 170c0e7866e48e1c035525b319ffc68e1122a25c Mon Sep 17 00:00:00 2001 From: Di Xu Date: Tue, 26 Sep 2017 09:17:31 +0800 Subject: [PATCH] add doc for hostpath type (#5503) --- docs/concepts/storage/volumes.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/concepts/storage/volumes.md b/docs/concepts/storage/volumes.md index ba86333dd0a5f..56bf83acd0c60 100644 --- a/docs/concepts/storage/volumes.md +++ b/docs/concepts/storage/volumes.md @@ -141,7 +141,7 @@ spec: ### hostPath A `hostPath` volume mounts a file or directory from the host node's filesystem -into your pod. This is not something that most Pods will need, but it offers a +into your pod. This is not something that most Pods will need, but it offers a powerful escape hatch for some applications. For example, some uses for a `hostPath` are: @@ -149,6 +149,24 @@ For example, some uses for a `hostPath` are: * running a container that needs access to Docker internals; use a `hostPath` of `/var/lib/docker` * running cAdvisor in a container; use a `hostPath` of `/dev/cgroups` +* allowing a pod to specify whether a given hostPath should exist prior to the + pod running, whether it should be created, and what it should exist as + +In addition to the required `path` property, user can optionally specify a `type` for a `hostPath` volume. + +The supported values for field `type` are: + + +| Value | Behavior | +|:------|:---------| +| | Empty string (default) is for backward compatibility, which means that no checks will be performed before mounting the hostPath volume. | +| `DirectoryOrCreate` | If nothing exists at the given path, an empty directory will be created there as needed with permission set to 0755, having the same group and ownership with Kubelet. | +| `Directory` | A directory must exist at the given path | +| `FileOrCreate` | If nothing exists at the given path, an empty file will be created there as needed with permission set to 0644, having the same group and ownership with Kubelet. | +| `File` | A file must exist at the given path | +| `Socket` | A UNIX socket must exist at the given path | +| `CharDevice` | A character device must exist at the given path | +| `BlockDevice` | A block device must exist at the given path | Watch out when using this type of volume, because: @@ -156,7 +174,7 @@ Watch out when using this type of volume, because: behave differently on different nodes due to different files on the nodes * when Kubernetes adds resource-aware scheduling, as is planned, it will not be able to account for resources used by a `hostPath` -* the directories created on the underlying hosts are only writable by root. You +* the files or directories created on the underlying hosts are only writable by root. You either need to run your process as root in a [privileged container](/docs/user-guide/security-context) or modify the file permissions on the host to be able to write to a `hostPath` volume @@ -180,6 +198,8 @@ spec: hostPath: # directory location on host path: /data + # this field is optional + type: Directory ``` ### gcePersistentDisk