From 3a8a465028a6b1b4f2ab265ac72a05230652fb58 Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Mon, 22 May 2017 13:57:42 -0400 Subject: [PATCH] WTD: Projected volumes (#3856) * Update projected volume task - Rename file - Build out steps - Create separate yaml file for pod configuration - Add new page to the sidenav * Add projected volume type to volumes concept page --- _data/tasks.yml | 2 +- docs/concepts/storage/volumes.md | 104 +++++++++++++++++- .../configure-projected-volume-storage.md | 67 +++++++++++ .../projected-volume.md | 76 ------------- .../projected-volume.yaml | 23 ++++ 5 files changed, 190 insertions(+), 82 deletions(-) create mode 100644 docs/tasks/configure-pod-container/configure-projected-volume-storage.md delete mode 100644 docs/tasks/configure-pod-container/projected-volume.md create mode 100644 docs/tasks/configure-pod-container/projected-volume.yaml diff --git a/_data/tasks.yml b/_data/tasks.yml index 6f8eab929e..26dfc0b5c6 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -13,7 +13,7 @@ toc: - docs/tasks/configure-pod-container/assign-cpu-ram-container.md - docs/tasks/configure-pod-container/configure-volume-storage.md - docs/tasks/configure-pod-container/configure-persistent-volume-storage.md - - docs/tasks/configure-pod-container/projected-volume.md + - docs/tasks/configure-pod-container/configure-projected-volume-storage.md - docs/tasks/configure-pod-container/configure-service-account.md - docs/tasks/configure-pod-container/pull-image-private-registry.md - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md diff --git a/docs/concepts/storage/volumes.md b/docs/concepts/storage/volumes.md index 422baa176a..d21143f2d3 100644 --- a/docs/concepts/storage/volumes.md +++ b/docs/concepts/storage/volumes.md @@ -82,6 +82,7 @@ Kubernetes supports several types of Volumes: * `secret` * `persistentVolumeClaim` * `downwardAPI` + * `projected` * `azureFileVolume` * `azureDisk` * `vsphereVolume` @@ -441,6 +442,99 @@ It mounts a directory and writes the requested data in plain text files. See the [`downwardAPI` volume example](/docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information/) for more details. +### projected + +A `projected` volume maps several existing volume sources into the same directory. + +Currently, the following types of volume sources can be projected: + +- [`secret`](#secret) +- [`downwardAPI`](#downardapi) +- `configMap` + +All sources are required to be in the same namespace as the pod. For more details, see the [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md). + +#### Example pod with a secret, a downward API, and a configmap + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: volume-test +spec: + containers: + - name: container-test + image: busybox + volumeMounts: + - name: all-in-one + mountPath: "/projected-volume" + readOnly: true + volumes: + - name: all-in-one + projected: + sources: + - secret: + name: mysecret + items: + - key: username + path: my-group/my-username + - downwardAPI: + items: + - path: "labels" + fieldRef: + fieldPath: metadata.labels + - path: "cpu_limit" + resourceFieldRef: + containerName: container-test + resource: limits.cpu + - configMap: + name: myconfigmap + items: + - key: config + path: my-group/my-config +``` + +#### Example pod with multiple secrets with a non-default permission mode set + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: volume-test +spec: + containers: + - name: container-test + image: busybox + volumeMounts: + - name: all-in-one + mountPath: "/projected-volume" + readOnly: true + volumes: + - name: all-in-one + projected: + sources: + - secret: + name: mysecret + items: + - key: username + path: my-group/my-username + - secret: + name: mysecret2 + items: + - key: password + path: my-group/my-password + mode: 511 +``` + +Each projected volume source is listed in the spec under `sources`. The +parameters are nearly the same with two exceptions: + +* For secrets, the `secretName` field has been changed to `name` to be consistent +with config maps naming. +* The `defaultMode` can only be specified at the projected level and not for each +volume source. However, as illustrated above, you can explicitly set the `mode` +for each individual projection. + ### FlexVolume A `FlexVolume` enables users to mount vendor volumes into a pod. It expects vendor @@ -464,7 +558,7 @@ More details can be found [here](https://github.com/kubernetes/kubernetes/tree/{ ### vsphereVolume -__Prerequisite: Kubernetes with vSphere Cloud Provider configured. +__Prerequisite: Kubernetes with vSphere Cloud Provider configured. For cloudprovider configuration please refer [vSphere getting started guide](http://kubernetes.io/docs/getting-started-guides/vsphere/).__ A `vsphereVolume` is used to mount a vSphere VMDK Volume into your Pod. The contents @@ -475,7 +569,7 @@ __Important: You must create VMDK using one of the following method before using #### Creating a VMDK volume * Create using vmkfstools. - + First ssh into ESX and then use following command to create vmdk, ```shell @@ -553,9 +647,9 @@ __Important: Make sure you have an existing PortworxVolume with name `pxvol` bef More details and examples can be found [here](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/volumes/portworx/README.md) ### ScaleIO -ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable -shared block networked storage. The ScaleIO volume plugin allows deployed pods to access existing ScaleIO -volumes (or it can dynamically provision new volumes for persistent volume claims, see +ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable +shared block networked storage. The ScaleIO volume plugin allows deployed pods to access existing ScaleIO +volumes (or it can dynamically provision new volumes for persistent volume claims, see [ScaleIO Persistent Volumes](/docs/user-guide/persistent-volumes/#scaleio)). __Important: You must have an existing ScaleIO cluster already setup and running with the volumes created diff --git a/docs/tasks/configure-pod-container/configure-projected-volume-storage.md b/docs/tasks/configure-pod-container/configure-projected-volume-storage.md new file mode 100644 index 0000000000..ee91d0b5d3 --- /dev/null +++ b/docs/tasks/configure-pod-container/configure-projected-volume-storage.md @@ -0,0 +1,67 @@ +--- +assignees: +- jpeeler +- pmorie +title: Configuring a Pod to Use a Projected Volume for Storage +redirect_from: +- "/docs/tasks/configure-pod-container/projected-volume/" +- "/docs/user-guide/projected-volume/" +- "/docs/user-guide/projected-volume/index.html" +--- + +{% capture overview %} +This page shows how to use a [`projected`](/docs/concepts/storage/volumes/#projected) volume to mount several existing volume sources into the same directory. Currently, `secret`, `configMap`, and `downwardAPI` volumes can be projected. +{% endcapture %} + +{% capture prerequisites %} +{% include task-tutorial-prereqs.md %} +{% endcapture %} + +{% capture steps %} +## Configure a projected volume for a pod + +In this exercise, you create username and password Secrets from local files. You then create a Pod that runs one Container, using a [`projected`](/docs/concepts/storage/volumes/#projected) Volume to mount the Secrets into the same shared directory. + +Here is the configuration file for the Pod: + +{% include code.html language="yaml" file="projected-volume.yaml" ghlink="/docs/tasks/configure-pod-container/projected-volume.yaml" %} + +1. Create the Secrets: + + # Create files containing the username and password: + echo -n "admin" > ./username.txt + echo -n "1f2d1e2e67df" > ./password.txt + + # Package these files into secrets: + kubectl create secret generic user --from-file=./username.txt + kubectl create secret generic pass --from-file=./password.txt + +1. Create the Pod: + + kubectl create -f projected-volume.yaml + +1. Verify that the Pod's Container is running, and then watch for changes to +the Pod: + + kubectl get --watch pod test-projected-volume + + The output looks like this: + + NAME READY STATUS RESTARTS AGE + test-projected-volume 1/1 Running 0 14s + +1. In another terminal, get a shell to the running Container: + + kubectl exec -it test-projected-volume -- /bin/sh + +1. In your shell, verify that the `projected-volumes` directory contains your projected sources: + + / # ls projected-volumes/ +{% endcapture %} + +{% capture whatsnext %} +* Learn more about [`projected`](/docs/concepts/storage/volumes/#projected) volumes. +* Read the the [all-in-one volume](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md) design document. +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tasks/configure-pod-container/projected-volume.md b/docs/tasks/configure-pod-container/projected-volume.md deleted file mode 100644 index 9bc47ce96f..0000000000 --- a/docs/tasks/configure-pod-container/projected-volume.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -assignees: -- jpeeler -- pmorie -title: Configuring a Pod to Use a Projected Volume for Storage -redirect_from: -- "/docs/user-guide/projected-volume/" -- "/docs/user-guide/projected-volume/index.html" ---- - -The _projected volume_ is a volume that projects several existing volume sources -into the same directory. Currently, one can project configmaps, downward API, -and secrets. The resulting pod spec is also shorter when projecting to a single -volume as opposed to multiple different locations. See [all-in-one volume design document](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/all-in-one-volume.md) -for more information. - -* TOC -{:toc} - -## Overview of a projected volume - -The projected volume encapsulates multiple volumes to be projected, with each -volume source respecting nearly the same parameters as supported by each -individual type. Consider the following example: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - sources: - - secret: - name: mysecret - items: - - key: username - path: my-group/my-username - - secret: - name: mysecret2 - items: - - key: password - path: my-group/my-password - mode: 511 -``` - -Each volume source is listed in the spec under `sources`. As stated above the -parameters are nearly the same with two exceptions: - -* For secrets, the `secretName` field has been changed to `name` to be consistent -with config maps naming. -* The `defaultMode` can only be specified at the projected level and not for each -volume source. However, as illustrated above, you can explicitly set the `mode` -for each individual projection. - -## Creating projections - -A projected volume is created by passing in the pod spec to kubectl as normally -done to create a new pod: -```shell -kubectl create -f podspec.yaml -``` - -## Restrictions - -Both secrets and config maps are required to be in the same namespace as the -pod. diff --git a/docs/tasks/configure-pod-container/projected-volume.yaml b/docs/tasks/configure-pod-container/projected-volume.yaml new file mode 100644 index 0000000000..172ca0dee5 --- /dev/null +++ b/docs/tasks/configure-pod-container/projected-volume.yaml @@ -0,0 +1,23 @@ +apiVersion: v1 +kind: Pod +metadata: + name: test-projected-volume +spec: + containers: + - name: test-projected-volume + image: busybox + args: + - sleep + - "86400" + volumeMounts: + - name: all-in-one + mountPath: "/projected-volume" + readOnly: true + volumes: + - name: all-in-one + projected: + sources: + - secret: + name: user + - secret: + name: pass