From 6618cdf830696be982f33d35b000094805062430 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Mon, 8 Jan 2018 19:07:32 -0800 Subject: [PATCH] Merge in missing changes from `master` --- .../tutorials/stateful-application/web.yaml | 1 - .../tutorials/stateful-application/webp.yaml | 3 +- cn/docs/user-guide/multi-pod.yaml | 1 - .../api-extension/custom-resources.md | 38 +++++++-------- .../policy/{psp.yaml => example-psp.yaml} | 9 ++-- docs/concepts/policy/privileged-psp.yaml | 27 +++++++++++ docs/concepts/policy/restricted-psp.yaml | 48 +++++++++++++++++++ docs/concepts/storage/persistent-volumes.md | 10 ++-- docs/getting-started-guides/scratch.md | 2 +- .../access-cluster.md | 3 +- .../access-application-cluster/frontend.yaml | 2 +- docs/tutorials/stateful-application/web.yaml | 1 - docs/tutorials/stateful-application/webp.yaml | 3 +- .../stateful-application/zookeeper.yaml | 1 - .../environment-guide/backend-rc.yaml | 1 - .../environment-guide/backend-srv.yaml | 1 - .../user-guide/environment-guide/show-rc.yaml | 1 - .../environment-guide/show-srv.yaml | 1 - docs/user-guide/multi-pod.yaml | 1 - test/examples_test.go | 13 ++++- 20 files changed, 120 insertions(+), 47 deletions(-) rename docs/concepts/policy/{psp.yaml => example-psp.yaml} (66%) create mode 100644 docs/concepts/policy/privileged-psp.yaml create mode 100644 docs/concepts/policy/restricted-psp.yaml diff --git a/cn/docs/tutorials/stateful-application/web.yaml b/cn/docs/tutorials/stateful-application/web.yaml index e9f9b7e5d0..e56d43b76b 100644 --- a/cn/docs/tutorials/stateful-application/web.yaml +++ b/cn/docs/tutorials/stateful-application/web.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: diff --git a/cn/docs/tutorials/stateful-application/webp.yaml b/cn/docs/tutorials/stateful-application/webp.yaml index c2ab595cf2..948a1c01d9 100644 --- a/cn/docs/tutorials/stateful-application/webp.yaml +++ b/cn/docs/tutorials/stateful-application/webp.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: @@ -42,4 +41,4 @@ spec: accessModes: [ "ReadWriteOnce" ] resources: requests: - storage: 1Gi \ No newline at end of file + storage: 1Gi diff --git a/cn/docs/user-guide/multi-pod.yaml b/cn/docs/user-guide/multi-pod.yaml index 7f7d0a5745..2ace060d89 100644 --- a/cn/docs/user-guide/multi-pod.yaml +++ b/cn/docs/user-guide/multi-pod.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Pod metadata: diff --git a/docs/concepts/api-extension/custom-resources.md b/docs/concepts/api-extension/custom-resources.md index eb24a70fb0..3acedae31c 100644 --- a/docs/concepts/api-extension/custom-resources.md +++ b/docs/concepts/api-extension/custom-resources.md @@ -48,24 +48,24 @@ When creating a new API, consider whether to [aggregate your API with the Kubern #### Declarative APIs In a Declarative API, typically: - - your API consists of a relatively small number of relatively small objects (resources). - - the objects define configuration of applications or infrastructure - - the objects are updated relatively infrequently - - humans often need to read and write the objects - - the main operations on the objects are CRUD-y (creating, reading, updating and deleting) - - transactions across objects are not required: the API represents a desired state, not an exact state. + - Your API consists of a relatively small number of relatively small objects (resources). + - The objects define configuration of applications or infrastructure. + - The objects are updated relatively infrequently. + - Humans often need to read and write the objects. + - The main operations on the objects are CRUD-y (creating, reading, updating and deleting). + - Transactions across objects are not required: the API represents a desired state, not an exact state. Imperative APIs are not declarative. Signs that your API might not be declarative include: - - the client says "do this", and then gets a synchornous response back when it is done. - - the client says "do this", and then gets an operation ID back, and has to check a separate Operation objects to determine completion of the request. - - you talk about Remote Procedure Calls (RPCs) - - directly stoing large amounts of data (e.g. > a few kB per object, or >1000s of objects) - - high bandwidth access (10s of requests per second sustained) needed - - store end-user data (such as images, PII, etc) or other large-scale data processed by applications - - the natural operations on the objects are not CRUD-y. - - the API is not easily modeled as objects. - - you chose to represent pending operations with an operation ID or operation object. + - The client says "do this", and then gets a synchornous response back when it is done. + - The client says "do this", and then gets an operation ID back, and has to check a separate Operation objects to determine completion of the request. + - You talk about Remote Procedure Calls (RPCs). + - Directly storing large amounts of data (e.g. > a few kB per object, or >1000s of objects). + - High bandwidth access (10s of requests per second sustained) needed. + - Store end-user data (such as images, PII, etc) or other large-scale data processed by applications. + - The natural operations on the objects are not CRUD-y. + - The API is not easily modeled as objects. + - You chose to represent pending operations with an operation ID or operation object. ### Should I use a configMap or a custom resource? @@ -102,7 +102,7 @@ Aggregated APIs are subordinate APIServers that sit behind the primary API serve Custom Resource Definitions (CRDS) allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs. -Regardless of whether they are installed via CRDs or AA, the new resources are called Custom Resources to distinguish them from built-in Kubernetes resources (like pods) +Regardless of whether they are installed via CRDs or AA, the new resources are called Custom Resources to distinguish them from built-in Kubernetes resources (like pods). ## CustomResourceDefinitions @@ -215,9 +215,9 @@ Kubernetes [client libraries](/docs/reference/client-libraries/) can be used to When you add a custom resource, you can access it using: - kubectl - - the kubernetes dynamic client - - a REST client that you write - - a client generated using Kubernetes client generation tools (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA). + - The kubernetes dynamic client. + - A REST client that you write. + - A client generated using Kubernetes client generation tools (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA). {% endcapture %} diff --git a/docs/concepts/policy/psp.yaml b/docs/concepts/policy/example-psp.yaml similarity index 66% rename from docs/concepts/policy/psp.yaml rename to docs/concepts/policy/example-psp.yaml index f82f7a856f..d8359220e4 100644 --- a/docs/concepts/policy/psp.yaml +++ b/docs/concepts/policy/example-psp.yaml @@ -1,8 +1,10 @@ apiVersion: extensions/v1beta1 kind: PodSecurityPolicy metadata: - name: permissive + name: example spec: + privileged: false # Don't allow privileged pods! + # The rest fills in some required fields. seLinux: rule: RunAsAny supplementalGroups: @@ -11,10 +13,5 @@ spec: rule: RunAsAny fsGroup: rule: RunAsAny - hostPorts: - - min: 8000 - max: 8080 volumes: - '*' - allowedCapabilities: - - '*' diff --git a/docs/concepts/policy/privileged-psp.yaml b/docs/concepts/policy/privileged-psp.yaml new file mode 100644 index 0000000000..6b6ec66878 --- /dev/null +++ b/docs/concepts/policy/privileged-psp.yaml @@ -0,0 +1,27 @@ +apiVersion: extensions/v1beta1 +kind: PodSecurityPolicy +metadata: + name: privileged + annotations: + seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*' +spec: + privileged: true + allowPrivilegeEscalation: true + allowedCapabilities: + - '*' + volumes: + - '*' + hostNetwork: true + hostPorts: + - min: 0 + max: 65535 + hostIPC: true + hostPID: true + runAsUser: + rule: 'RunAsAny' + seLinux: + rule: 'RunAsAny' + supplementalGroups: + rule: 'RunAsAny' + fsGroup: + rule: 'RunAsAny' diff --git a/docs/concepts/policy/restricted-psp.yaml b/docs/concepts/policy/restricted-psp.yaml new file mode 100644 index 0000000000..fe1c1d90fe --- /dev/null +++ b/docs/concepts/policy/restricted-psp.yaml @@ -0,0 +1,48 @@ +apiVersion: extensions/v1beta1 +kind: PodSecurityPolicy +metadata: + name: restricted + annotations: + seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default' + apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default' + seccomp.security.alpha.kubernetes.io/defaultProfileName: 'docker/default' + apparmor.security.beta.kubernetes.io/defaultProfileName: 'runtime/default' +spec: + privileged: false + # Required to prevent escalations to root. + allowPrivilegeEscalation: false + # This is redundant with non-root + disallow privilege escalation, + # but we can provide it for defense in depth. + requiredDropCapabilities: + - ALL + # Allow core volume types. + volumes: + - 'configMap' + - 'emptyDir' + - 'projected' + - 'secret' + - 'downwardAPI' + # Assume that persistentVolumes set up by the cluster admin are safe to use. + - 'persistentVolumeClaim' + hostNetwork: false + hostIPC: false + hostPID: false + runAsUser: + # Require the container to run without root privileges. + rule: 'MustRunAsNonRoot' + seLinux: + # This policy assumes the nodes are using AppArmor rather than SELinux. + rule: 'RunAsAny' + supplementalGroups: + rule: 'MustRunAs' + ranges: + # Forbid adding the root group. + - min: 1 + max: 65535 + fsGroup: + rule: 'MustRunAs' + ranges: + # Forbid adding the root group. + - min: 1 + max: 65535 + readOnlyRootFilesystem: false diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index c8fd40284d..bc7a57c913 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -245,10 +245,12 @@ Generally, a PV will have a specific storage capacity. This is set using the PV Currently, storage size is the only resource that can be set or requested. Future attributes may include IOPS, throughput, etc. ### Volume Mode -{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %} Prior to v1.9, the default behavior for all volume plugins was to create a filesystem on the persistent volume. With v1.9, the user can specify a volumeMode which will now support raw block devices in addition to file systems. Valid values for volumeMode are "Filesystem" or "Block". If left unspecified, volumeMode defaults to "Filesystem" internally. This is an optional API parameter. +**Note:** This feature is alpha in v1.9 and may change in the future. +{: .note} + ### Access Modes A `PersistentVolume` can be mounted on a host in any way supported by the resource provider. As shown in the table below, providers will have different capabilities and each PV's access modes are set to the specific modes supported by that particular volume. For example, NFS can support multiple read/write clients, but a specific NFS PV might be exported on the server as read-only. Each PV gets its own set of access modes describing that specific PV's capabilities. @@ -384,7 +386,7 @@ Claims use the same conventions as volumes when requesting storage with specific ### Volume Modes -Claims use the same convention as volumes to indicate the consumption of the volume as either a filesystem or block device. +Claims use the same convention as volumes to indicates the consumption of the volume as either a filesystem or block device. ### Resources @@ -470,7 +472,7 @@ spec: ## Raw Block Volume Support -Static provisioning support for Raw Block Volumes is included as an alpha feature for v1.9. Raw block volumes can be specified through new API fields. Currently, Fibre Channel is the only supported plugin for this feature. +Static provisioning support for Raw Block Volumes is included as an alpha feature for v1.9. With this change are some new API fields that need to be used to facilitate this functionality. Currently, Fibre Channel is the only supported plugin for this feature. ### Persistent Volumes using a Raw Block Volume ``` @@ -530,7 +532,7 @@ spec: ### Binding Block Volumes -If a user requests a raw block volume through the persistentVolumeClaim.volumeMode field, it can only bind to PersistentVolume with the matching volumeMode field. +If a user requests a raw block volume by indicating this using the volumeMode field in the PersistentVolumeClaim spec, the binding rules differ slighty from previous releases that didn't consider this mode as part of the spec. Listed is a table of possible combinations the user and admin might specify for requesting a raw block device. The table indicates if the volume will be bound or not given the combinations: Volume binding matrix for statically provisioned volumes: diff --git a/docs/getting-started-guides/scratch.md b/docs/getting-started-guides/scratch.md index b177f4a24b..8d1cb7b3f2 100644 --- a/docs/getting-started-guides/scratch.md +++ b/docs/getting-started-guides/scratch.md @@ -705,7 +705,7 @@ Complete this template for the scheduler pod: "containers": [ { "name": "kube-scheduler", - "image": "$HYBERKUBE_IMAGE", + "image": "$HYPERKUBE_IMAGE", "command": [ "/hyperkube", "scheduler", diff --git a/docs/tasks/access-application-cluster/access-cluster.md b/docs/tasks/access-application-cluster/access-cluster.md index 658f77515e..1e053ef34a 100644 --- a/docs/tasks/access-application-cluster/access-cluster.md +++ b/docs/tasks/access-application-cluster/access-cluster.md @@ -55,7 +55,8 @@ $ kubectl proxy --port=8080 & See [kubectl proxy](/docs/user-guide/kubectl/{{page.version}}/#proxy) for more details. -Then you can explore the API with curl, wget, or a browser, like so: +Then you can explore the API with curl, wget, or a browser, replacing localhost +with [::1] for IPv6, like so: ```shell $ curl http://localhost:8080/api/ diff --git a/docs/tasks/access-application-cluster/frontend.yaml b/docs/tasks/access-application-cluster/frontend.yaml index 382c3786e5..63631c0d05 100644 --- a/docs/tasks/access-application-cluster/frontend.yaml +++ b/docs/tasks/access-application-cluster/frontend.yaml @@ -1,5 +1,5 @@ -kind: Service apiVersion: v1 +kind: Service metadata: name: frontend spec: diff --git a/docs/tutorials/stateful-application/web.yaml b/docs/tutorials/stateful-application/web.yaml index 2bc58636ad..37c1fabf9c 100644 --- a/docs/tutorials/stateful-application/web.yaml +++ b/docs/tutorials/stateful-application/web.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: diff --git a/docs/tutorials/stateful-application/webp.yaml b/docs/tutorials/stateful-application/webp.yaml index 539eb76525..4eab2dc206 100644 --- a/docs/tutorials/stateful-application/webp.yaml +++ b/docs/tutorials/stateful-application/webp.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: @@ -45,4 +44,4 @@ spec: accessModes: [ "ReadWriteOnce" ] resources: requests: - storage: 1Gi \ No newline at end of file + storage: 1Gi diff --git a/docs/tutorials/stateful-application/zookeeper.yaml b/docs/tutorials/stateful-application/zookeeper.yaml index 964b0bc145..4afa806a54 100644 --- a/docs/tutorials/stateful-application/zookeeper.yaml +++ b/docs/tutorials/stateful-application/zookeeper.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: diff --git a/docs/user-guide/environment-guide/backend-rc.yaml b/docs/user-guide/environment-guide/backend-rc.yaml index 6c57b95dac..28c7eeb097 100644 --- a/docs/user-guide/environment-guide/backend-rc.yaml +++ b/docs/user-guide/environment-guide/backend-rc.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: ReplicationController metadata: diff --git a/docs/user-guide/environment-guide/backend-srv.yaml b/docs/user-guide/environment-guide/backend-srv.yaml index 7083b37bf8..1c306bc0f6 100644 --- a/docs/user-guide/environment-guide/backend-srv.yaml +++ b/docs/user-guide/environment-guide/backend-srv.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: diff --git a/docs/user-guide/environment-guide/show-rc.yaml b/docs/user-guide/environment-guide/show-rc.yaml index 4de94c06ca..df2f03e347 100644 --- a/docs/user-guide/environment-guide/show-rc.yaml +++ b/docs/user-guide/environment-guide/show-rc.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: ReplicationController metadata: diff --git a/docs/user-guide/environment-guide/show-srv.yaml b/docs/user-guide/environment-guide/show-srv.yaml index 25a2d7473e..1761310421 100644 --- a/docs/user-guide/environment-guide/show-srv.yaml +++ b/docs/user-guide/environment-guide/show-srv.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Service metadata: diff --git a/docs/user-guide/multi-pod.yaml b/docs/user-guide/multi-pod.yaml index 7f7d0a5745..2ace060d89 100644 --- a/docs/user-guide/multi-pod.yaml +++ b/docs/user-guide/multi-pod.yaml @@ -1,4 +1,3 @@ ---- apiVersion: v1 kind: Pod metadata: diff --git a/test/examples_test.go b/test/examples_test.go index b6d9e8c9c7..088d48387c 100644 --- a/test/examples_test.go +++ b/test/examples_test.go @@ -227,6 +227,10 @@ func walkConfigFiles(inDir string, fn func(name, path string, data [][]byte)) er if err != nil { return err } + // workaround for Jekyllr limit + if bytes.HasPrefix(data, []byte("---\n")) { + return fmt.Errorf("YAML file cannot start with \"---\", please remove the first line") + } name := strings.TrimSuffix(file, ext) var docs [][]byte @@ -245,7 +249,10 @@ func walkConfigFiles(inDir string, fn func(name, path string, data [][]byte)) er if err != nil { return fmt.Errorf("%s: %v", path, err) } - docs = append(docs, out) + // deal with "empty" document (e.g. pure comments) + if string(out) != "null" { + docs = append(docs, out) + } } } else { docs = append(docs, data) @@ -305,7 +312,9 @@ func TestExampleObjectSchemas(t *testing.T) { "nginx-deployment": {&extensions.Deployment{}}, }, "../docs/concepts/policy": { - "psp": {&extensions.PodSecurityPolicy{}}, + "privileged-psp": {&extensions.PodSecurityPolicy{}}, + "restricted-psp": {&extensions.PodSecurityPolicy{}}, + "example-psp": {&extensions.PodSecurityPolicy{}}, }, "../docs/concepts/services-networking": { "curlpod": {&extensions.Deployment{}},