Add local volume documentation #4050

msau42 · 2017-06-09T21:33:07Z

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For 1.7 Features: set Milestone to 1.7 and Base Branch to release-1.7
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NOTE: Please check the “Allow edits from maintainers” box below to allow
reviewers fix problems on your patch and speed up the review process.
Please delete this note before submitting the pull request.

This change is

msau42 · 2017-06-09T21:34:16Z

/assign @chenopis @vishh

cc @kubernetes/sig-storage-pr-reviews

jsafrane · 2017-06-13T08:22:11Z

docs/concepts/storage/volumes.md

+### local
+This volume type is alpha in 1.7.
+
+A `local` volume represents a mount point or directory that has node affinity.


I am not sure that users would understand what node affinity means. I would appreciate more "user-friendly" description, like "local volume represents a mounted local storage device such as a disk, a partition or even a local directory". And that scheduler makes sure that pods that use a local volume are scheduled to the right nodes.

In addition, some comparison with HostPath volumes would be nice. When should the user use HostPath and when a local volume?

Updated. PTAL

vishh · 2017-06-13T22:45:23Z

docs/concepts/storage/volumes.md

+A `local` volume represents a mounted local storage device such as a disk,
+partition or directory.
+
+Local volumes can only be used as a statically created PersistentVolume source.


This doesn't read well. How about Local volumes can only be used as a statically created PersistentVolumes or Local volumes can only be used as a source in statically created PersistentVolumes ?

vishh · 2017-06-13T22:45:52Z

docs/concepts/storage/volumes.md

+node and are not suitable for all applications.
+
+For further detail, please see the [local volume
+user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume)


WHy is the user guide for local volumes in an incubator repo?

I wanted one place to put all the local storage documentation and examples. The user guide includes details about how to run the daemonset, and that repo is where it lives.

The good part about keeping docs in this repo is that it is versioned controlled and easily discoverable. Would it be possible to avoid this redirect once the feature moves out of alpha?

It looks like most of the other volume plugins put their docs and examples under the main kubernetes examples source tree. So I could place it there instead. Then in the external-storage repo, I could point the readme to the kubernetes repo.

@steveperry-53 @pwittrock Any suggestions on how storage user guides should be organized?

@chenopis ^^

From what I understand, kubernetes/examples will be where we keep some "real world" examples, which we will use in the tutorials. If there's going to be an accompanying tutorial to walk users through local persistent storage, then I'm okay w/ it going there. I think @ahmetb is managing that repo, so maybe he should chime in too.

You can submit an example to kubernetes/examples for completeness, however local is a native/1st party volume type and any user guide and sample snippets should be in this docs repository instead.

The local volume has two portions. The volume type is 1st party, but the provisioning/management is in the outside repo. For the most hands-off experience, folks should use the external provisioner and not have to manage the volume directly.

chenopis · 2017-06-19T18:17:43Z

FYI, I tagged this w/ the 1.7 milestone and changed the base branch to master.

chenopis · 2017-06-20T22:18:42Z

Is this tech lgtm?

chenopis · 2017-06-20T23:29:23Z

@msau42 There's a conflict that came up in the docs/concepts/storage/volumes.md file. When you resolve that, I can merge this PR. Thx

msau42 · 2017-06-20T23:32:29Z

Did we want to move the non-provisioner parts of the user guide here? (ie just the pv and pvc example?)

msau42 · 2017-06-21T00:28:04Z

ah sorry, i rebased to master instead of 1.7. let me fix that...

msau42 · 2017-06-21T00:31:44Z

Ok, I rebased, and also added an example of specifying the local volume in the PV spec.

msau42 · 2017-06-21T00:32:26Z

PTAL again @vishh @chenopis @ahmetb

ahmetb

Not familiar with the technical area, left some comments on markdown and wording.

ahmetb · 2017-06-21T02:41:53Z

docs/concepts/storage/volumes.md

@@ -738,6 +739,53 @@ spec:

 For more information including Dynamic Provisioning and Persistent Volume Claims, please see the [StorageOS examples](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/volumes/storageos).

+### local


add a space after this.

ahmetb · 2017-06-21T02:42:16Z

docs/concepts/storage/volumes.md

+node and are not suitable for all applications.
+
+The following is an example PersistentVolume spec using a `local` volume:
+``` yaml


this doesnt render correctly because you need an empty line before the code block, and after the paragraph

ahmetb · 2017-06-21T02:43:49Z

docs/concepts/storage/volumes.md

+      path: /mnt/disks/ssd1
+```
+
+For further detail, please see the [local volume


Remove please. Suggested rewrite:

For details on the local volume type, see Local Persistent Storage user guide.

msau42 · 2017-06-21T03:28:31Z

fixed

ahmetb · 2017-06-21T03:43:30Z

I am not super familiar with YAML multi-line string syntax but is the backtick valid for multi-line string values?

msau42 · 2017-06-21T16:40:58Z

Fixed

chenopis · 2017-06-21T22:00:57Z

@ahmetb is this lgtm for you?

ahmetb

/lgtm

@nikhiljindal

* Minor fixes in the Deployment doc Signed-off-by: Michail Kargakis <mkargaki@redhat.com> * add NodeRestriction to admission-controllers (#3842) * Admins Can Configure Zones in Storage Class The PR #38505 (kubernetes/kubernetes#38505) added zones optional parameter to Storage Class for AWS and GCE provisioners. That's why documentation needs to be updated accordingly. * document custom resource definitions * add host paths to psp (#3971) * add host paths to psp * add italics * Update ConfigMap doc to explain TTL-based cache updates (#3989) * Update ConfigMap doc to explain TTL-based cache updates * swap word order Change "When a ConfigMap being already consumed..." to "When a ConfigMap already being consumed..." * Update NetworkPolicy docs for v1 * StorageOS Volume plugin * Update GPU docs * docs: HPA autoscaling/v2alpha1 status conditions This commit documents the new status conditions feature for HPA autoscaling/v2alpha1. It demonstrates how to get the status conditions using `kubectl describe`, and how to interpret them. * Update description about NodeRestriction kubelet node can alse create mirror pods for their own static pods. * adding storage as a supported resource to node allocatable Signed-off-by: Vishnu kannan <vishnuk@google.com> * Add documentation for podpreset opt-out annotation This adds the annotation for having the podpreset admission controller to skip (opt-out) manipulating the pod spec. Also, the annotation format for what presets have acted on a pod has been modified to add a prefix of "podpreset-". The new naming makes it such that there is no chance of collision with the newly introduced opt-out annotation (or future ones yet to be added). Opt-out annotation PR: kubernetes/kubernetes#44965 * Update PDB documentation to explain new field (#3885) * update-docs-pdb * Addressed erictune@'s comments * Fix title and add a TOC to the logging concept page * Patch #4118 for typos * Describe setting coredns server in nameserver resolv chain * Address comments in PR #3997. Comment is in https://github.com/kubernetes/kubernetes.github.io/pull/3997/files/f6eb59c67e28efc298c87b1ef49a96bc6adacd1e#diff-7a14981f3dd8eb203f897ce6c11d9828 * Update task for DaemonSet history and rollback (#4098) * Update task for DaemonSet history and rollback Also remove mentions of templateGeneration field because it's deprecated * Address comments * removed lt and gt as operators (#4152) * removed lt and gt as operators * replace lt and gt for node-affinfity * updated based on bsalamat review * Initial draft of upgrade guide for kubeadm clusters. In-place upgrades are supported between 1.6 and 1.7 releases. Rollback instructions to come in a separate commit. Fixes kubernetes/kubeadm#278 * Add local volume documentation (#4050) * Add local volume documentation * Add PV local volume example * Patch PR #3999 * Add documentation for Stackdriver event exporter * Add documentation about controller metrics * Federation: Add task for setting up placement policies (#4075) * Add task for setting up placement policies * Update version of management sidecar in policy engine deployment * Address @nikhiljindal's comments - Lower case filenames - Comments in policy - Typo fixes - Removed type LoadBalancer from OPA Service * Add example that sets cluster selector Per-@nikhiljindal's suggestion * Fix wording and templating per @chenopis * PodDisruptionBudget documentation Improvements (#4140) * Changes from #3885 Title: Update PDB documentation to explain new field Author: foxish * Added Placeholder Disruptions Concept Guide New file: docs/concepts/workloads/pods/disruptions.md Intented contents: concept for Pod Disruption Budget, cross reference to Eviction and Preemption docs. Linked from: concepts > workloads > pods * Added placeholder Configuring PDB Task New file: docs/tasks/run-application/configure-pdb.md Intented contents: task for writing a Pod Disruption Budget. Linked from: tasks > configuring-applications > configure pdb. * Add refs to the "drain a node" task. * Refactor PDB docs. Move the "Requesting an eviction" section from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md -- which is going away -- to: docs/tasks/administer-cluster/safely-drain-node.md The move is verbatim, except for an introductory sentence. Also added assignees. * Refactor of PDB docs Moved the section: Specifying a PodDisruptionBudget from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md to: docs/tasks/run-application/configure-pdb.md because that former file is going away. Move is verbatim. * Explain how Eviction tools should handle failures * Refactor PDB docs Move text from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md to: docs/concepts/workloads/pods/disruptions.md Delete the now empty: docs/tasks/administer-cluster/configure-pod-disruption-budget.md Added a redirects_from section to the new doc, containing the path of the now-deleted doc, plus all the redirects from the deleted doc. * Expand PDB Concept guide Building on a little content from the old task, greatly expanded the Disruptions concept guide, including an abstract example. * Update creating a pdb Task. * Address review comments. * Fixed for all cody-clark's review comments * Address review comments from mml * Address review comments from maisem * Fix missing backtick * Api and Kubectl reference docs updates for 1.7 (#4193) * Fix includes groups * Generated kubectl docs for 1.7 * Generated references docs for 1.7 api * Document node authorization mode * API Aggregator (#4173) * API Aggregator * Additional bullet points * incorporated feedback for apiserver-aggregation.md * split setup-api-aggregator.md into two docs and address feedback * fix link * addressed docs feedback * incorporate feedback * integrate feedback * Add documentation for DNS stub domains (#4063) * Add documentation for DNS stub domains * add additional prereq * fix image path * review feedback * minor grammar and style nits * documentation for using hostAliases to manage hosts file (#4080) * documentation for using hostAliases to manage hosts file * add to table of contents * review comments * update the right command to see hosts file * reformat doc based on suggestion and change some wording * Fix typo for #4080 * Patch PR #4063 * Fix wording in placement policy task introduction * Add update to statefulset concepts and basic tutorial (#4174) * Add update to statefulset concpets and basic tutorial * Address tech comments. * Update ESIPP docs for new added API fields * Custom resource docs * update audit document with advanced audit features added in 1.7 * kubeadm v1.7 documentation updates (#4018) * v1.7 updates for kubeadm * Address review comments * Address Luke's comments * Encrypting secrets at rest and cluster security guide * Edits for Custom DNS Documentation (#4207) * reorganize custom dns doc * format fixes * Update version numbers to 1.7 * Patch PR #4140 (#4215) * Patch PR #4140 * fix link and typos * Update PR template * Update TLS bootstrapping with 1.7 features This includes documenting the new CSR approver built into the controller manager and the kubelet alpha features for certificate rotation. Since the CSR approver changed over the 1.7 release cycle we need to call out the migration steps for those using the alpha feature. This document as a whole could probably use some updates, but the main focus of this PR is just to get these features minimally documented before the release. * Federated ClusterSelector formatting updates from review * complete PR #4181 (#4223) * complete PR #4181 * fix security link * Extensible admission controller (#4092) * extensible-admission-controllers * Update extensible-admission-controllers.md * more on initializers * fixes * Expand external admission webhooks documentation * wrap at 80 chars * more * add reference * Use correct apigroup for network policy * Docs changes to PR #4092 (#4224) * Docs changes to PR #4092 * address feedback * add doc for --as-group in cli Add doc for this pr: kubernetes/kubernetes#43696

* Add local volume documentation * Add PV local volume example

@nikhiljindal

* Minor fixes in the Deployment doc Signed-off-by: Michail Kargakis <mkargaki@redhat.com> * add NodeRestriction to admission-controllers (#3842) * Admins Can Configure Zones in Storage Class The PR #38505 (kubernetes/kubernetes#38505) added zones optional parameter to Storage Class for AWS and GCE provisioners. That's why documentation needs to be updated accordingly. * document custom resource definitions * add host paths to psp (#3971) * add host paths to psp * add italics * Update ConfigMap doc to explain TTL-based cache updates (#3989) * Update ConfigMap doc to explain TTL-based cache updates * swap word order Change "When a ConfigMap being already consumed..." to "When a ConfigMap already being consumed..." * Update NetworkPolicy docs for v1 * StorageOS Volume plugin * Update GPU docs * docs: HPA autoscaling/v2alpha1 status conditions This commit documents the new status conditions feature for HPA autoscaling/v2alpha1. It demonstrates how to get the status conditions using `kubectl describe`, and how to interpret them. * Update description about NodeRestriction kubelet node can alse create mirror pods for their own static pods. * adding storage as a supported resource to node allocatable Signed-off-by: Vishnu kannan <vishnuk@google.com> * Add documentation for podpreset opt-out annotation This adds the annotation for having the podpreset admission controller to skip (opt-out) manipulating the pod spec. Also, the annotation format for what presets have acted on a pod has been modified to add a prefix of "podpreset-". The new naming makes it such that there is no chance of collision with the newly introduced opt-out annotation (or future ones yet to be added). Opt-out annotation PR: kubernetes/kubernetes#44965 * Update PDB documentation to explain new field (#3885) * update-docs-pdb * Addressed erictune@'s comments * Fix title and add a TOC to the logging concept page * Patch #4118 for typos * Describe setting coredns server in nameserver resolv chain * Address comments in PR #3997. Comment is in https://github.com/kubernetes/kubernetes.github.io/pull/3997/files/f6eb59c67e28efc298c87b1ef49a96bc6adacd1e#diff-7a14981f3dd8eb203f897ce6c11d9828 * Update task for DaemonSet history and rollback (#4098) * Update task for DaemonSet history and rollback Also remove mentions of templateGeneration field because it's deprecated * Address comments * removed lt and gt as operators (#4152) * removed lt and gt as operators * replace lt and gt for node-affinfity * updated based on bsalamat review * Initial draft of upgrade guide for kubeadm clusters. In-place upgrades are supported between 1.6 and 1.7 releases. Rollback instructions to come in a separate commit. Fixes kubernetes/kubeadm#278 * Add local volume documentation (#4050) * Add local volume documentation * Add PV local volume example * Patch PR #3999 * Add documentation for Stackdriver event exporter * Add documentation about controller metrics * Federation: Add task for setting up placement policies (#4075) * Add task for setting up placement policies * Update version of management sidecar in policy engine deployment * Address @nikhiljindal's comments - Lower case filenames - Comments in policy - Typo fixes - Removed type LoadBalancer from OPA Service * Add example that sets cluster selector Per-@nikhiljindal's suggestion * Fix wording and templating per @chenopis * PodDisruptionBudget documentation Improvements (#4140) * Changes from #3885 Title: Update PDB documentation to explain new field Author: foxish * Added Placeholder Disruptions Concept Guide New file: docs/concepts/workloads/pods/disruptions.md Intented contents: concept for Pod Disruption Budget, cross reference to Eviction and Preemption docs. Linked from: concepts > workloads > pods * Added placeholder Configuring PDB Task New file: docs/tasks/run-application/configure-pdb.md Intented contents: task for writing a Pod Disruption Budget. Linked from: tasks > configuring-applications > configure pdb. * Add refs to the "drain a node" task. * Refactor PDB docs. Move the "Requesting an eviction" section from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md -- which is going away -- to: docs/tasks/administer-cluster/safely-drain-node.md The move is verbatim, except for an introductory sentence. Also added assignees. * Refactor of PDB docs Moved the section: Specifying a PodDisruptionBudget from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md to: docs/tasks/run-application/configure-pdb.md because that former file is going away. Move is verbatim. * Explain how Eviction tools should handle failures * Refactor PDB docs Move text from: docs/tasks/administer-cluster/configure-pod-disruption-budget.md to: docs/concepts/workloads/pods/disruptions.md Delete the now empty: docs/tasks/administer-cluster/configure-pod-disruption-budget.md Added a redirects_from section to the new doc, containing the path of the now-deleted doc, plus all the redirects from the deleted doc. * Expand PDB Concept guide Building on a little content from the old task, greatly expanded the Disruptions concept guide, including an abstract example. * Update creating a pdb Task. * Address review comments. * Fixed for all cody-clark's review comments * Address review comments from mml * Address review comments from maisem * Fix missing backtick * Api and Kubectl reference docs updates for 1.7 (#4193) * Fix includes groups * Generated kubectl docs for 1.7 * Generated references docs for 1.7 api * Document node authorization mode * API Aggregator (#4173) * API Aggregator * Additional bullet points * incorporated feedback for apiserver-aggregation.md * split setup-api-aggregator.md into two docs and address feedback * fix link * addressed docs feedback * incorporate feedback * integrate feedback * Add documentation for DNS stub domains (#4063) * Add documentation for DNS stub domains * add additional prereq * fix image path * review feedback * minor grammar and style nits * documentation for using hostAliases to manage hosts file (#4080) * documentation for using hostAliases to manage hosts file * add to table of contents * review comments * update the right command to see hosts file * reformat doc based on suggestion and change some wording * Fix typo for #4080 * Patch PR #4063 * Fix wording in placement policy task introduction * Add update to statefulset concepts and basic tutorial (#4174) * Add update to statefulset concpets and basic tutorial * Address tech comments. * Update ESIPP docs for new added API fields * Custom resource docs * update audit document with advanced audit features added in 1.7 * kubeadm v1.7 documentation updates (#4018) * v1.7 updates for kubeadm * Address review comments * Address Luke's comments * Encrypting secrets at rest and cluster security guide * Edits for Custom DNS Documentation (#4207) * reorganize custom dns doc * format fixes * Update version numbers to 1.7 * Patch PR #4140 (#4215) * Patch PR #4140 * fix link and typos * Update PR template * Update TLS bootstrapping with 1.7 features This includes documenting the new CSR approver built into the controller manager and the kubelet alpha features for certificate rotation. Since the CSR approver changed over the 1.7 release cycle we need to call out the migration steps for those using the alpha feature. This document as a whole could probably use some updates, but the main focus of this PR is just to get these features minimally documented before the release. * Federated ClusterSelector formatting updates from review * complete PR #4181 (#4223) * complete PR #4181 * fix security link * Extensible admission controller (#4092) * extensible-admission-controllers * Update extensible-admission-controllers.md * more on initializers * fixes * Expand external admission webhooks documentation * wrap at 80 chars * more * add reference * Use correct apigroup for network policy * Docs changes to PR #4092 (#4224) * Docs changes to PR #4092 * address feedback * add doc for --as-group in cli Add doc for this pr: kubernetes/kubernetes#43696

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jun 9, 2017

k8s-ci-robot added the sig/storage label Jun 9, 2017

k8s-ci-robot assigned chenopis and vishh Jun 9, 2017

jsafrane reviewed Jun 13, 2017

View reviewed changes

vishh reviewed Jun 13, 2017

View reviewed changes

msau42 mentioned this pull request Jun 13, 2017

[Storage] Add support for persistent local storage kubernetes/kubernetes#43640

Closed

chenopis added this to the 1.7 milestone Jun 19, 2017

chenopis changed the base branch from master to release-1.7 June 19, 2017 18:17

chenopis added kind/feature labels Jun 19, 2017

vishh added the Tech Review LGTM label Jun 20, 2017

msau42 force-pushed the local-docs branch from 980c7f7 to 43a2652 Compare June 21, 2017 00:16

Add local volume documentation

b42feeb

msau42 force-pushed the local-docs branch from 43a2652 to 96984ea Compare June 21, 2017 00:30

ahmetb suggested changes Jun 21, 2017

View reviewed changes

msau42 force-pushed the local-docs branch from 96984ea to b9e4d52 Compare June 21, 2017 03:27

Add PV local volume example

8cabbc2

msau42 force-pushed the local-docs branch from b9e4d52 to 8cabbc2 Compare June 21, 2017 16:40

ahmetb approved these changes Jun 22, 2017

View reviewed changes

k8s-ci-robot assigned ahmetb Jun 22, 2017

k8s-ci-robot added the lgtm label Jun 22, 2017

chenopis merged commit 034c792 into kubernetes:release-1.7 Jun 22, 2017

jesscodez pushed a commit that referenced this pull request Sep 22, 2017

Add local volume documentation (#4050)

a7a24bf

* Add local volume documentation * Add PV local volume example

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add local volume documentation #4050

Add local volume documentation #4050

msau42 commented Jun 9, 2017 •

edited by k8s-reviewable

Loading

msau42 commented Jun 9, 2017

jsafrane Jun 13, 2017

msau42 Jun 13, 2017

vishh Jun 13, 2017

vishh Jun 13, 2017

msau42 Jun 13, 2017

vishh Jun 13, 2017

msau42 Jun 13, 2017

vishh Jun 13, 2017

vishh Jun 19, 2017

chenopis Jun 20, 2017

ahmetb Jun 20, 2017

msau42 Jun 20, 2017

chenopis commented Jun 19, 2017

chenopis commented Jun 20, 2017

chenopis commented Jun 20, 2017

msau42 commented Jun 20, 2017

msau42 commented Jun 21, 2017

msau42 commented Jun 21, 2017

msau42 commented Jun 21, 2017

ahmetb left a comment

ahmetb Jun 21, 2017

ahmetb Jun 21, 2017

ahmetb Jun 21, 2017

msau42 commented Jun 21, 2017

ahmetb commented Jun 21, 2017

msau42 commented Jun 21, 2017

chenopis commented Jun 21, 2017

ahmetb left a comment

		@@ -738,6 +739,53 @@ spec:

		For more information including Dynamic Provisioning and Persistent Volume Claims, please see the [StorageOS examples](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/volumes/storageos).

		### local

Add local volume documentation #4050

Add local volume documentation #4050

Conversation

msau42 commented Jun 9, 2017 • edited by k8s-reviewable Loading

msau42 commented Jun 9, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chenopis commented Jun 19, 2017

chenopis commented Jun 20, 2017

chenopis commented Jun 20, 2017

msau42 commented Jun 20, 2017

msau42 commented Jun 21, 2017

msau42 commented Jun 21, 2017

msau42 commented Jun 21, 2017

ahmetb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msau42 commented Jun 21, 2017

ahmetb commented Jun 21, 2017

msau42 commented Jun 21, 2017

chenopis commented Jun 21, 2017

ahmetb left a comment

Choose a reason for hiding this comment

msau42 commented Jun 9, 2017 •

edited by k8s-reviewable

Loading