From 3185b43411363d83692fd19d73cf48915120688d Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Mon, 30 Jan 2017 16:17:18 -0800 Subject: [PATCH 1/2] Move Commands and Capabilities out of User Guide. --- _data/concepts.yml | 12 ++ _includes/redirection-note.md | 3 + docs/concepts/configuration/commands.yaml | 12 ++ .../configuration/container-command-args.md | 84 +++++++++++++ .../concepts/policy/container-capabilities.md | 102 ++++++++++++++++ docs/user-guide/containers.md | 112 +----------------- 6 files changed, 216 insertions(+), 109 deletions(-) create mode 100644 _includes/redirection-note.md create mode 100644 docs/concepts/configuration/commands.yaml create mode 100644 docs/concepts/configuration/container-command-args.md create mode 100644 docs/concepts/policy/container-capabilities.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 71c6512909..5699ef430c 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -2,16 +2,28 @@ bigheader: "Concepts" abstract: "Detailed explanations of Kubernetes system concepts and abstractions." toc: - docs/concepts/index.md + - title: Kubectl Command Line section: - docs/concepts/tools/kubectl/object-management-overview.md + - title: Kubernetes Objects section: - docs/concepts/abstractions/overview.md - docs/concepts/abstractions/pod.md + - title: Controllers section: - docs/concepts/abstractions/controllers/statefulsets.md + - title: Object Metadata section: - docs/concepts/object-metadata/annotations.md + +- title: Configuration + section: + - docs/concepts/configuration/container-command-args.md + +- title: Policies + section: + - docs/concepts/policy/container-capabilities.md diff --git a/_includes/redirection-note.md b/_includes/redirection-note.md new file mode 100644 index 0000000000..8b93e29f12 --- /dev/null +++ b/_includes/redirection-note.md @@ -0,0 +1,3 @@ +The topics in the [User Guide](/docs/user-guide/) section of the Kubernetes docs +are being moved to the [Tasks](/docs/tasks/), [Tutorials](/docs/tutorials/), and +[Concepts](/docs/concepts) sections. The content in this topic has moved to: diff --git a/docs/concepts/configuration/commands.yaml b/docs/concepts/configuration/commands.yaml new file mode 100644 index 0000000000..8d58007db4 --- /dev/null +++ b/docs/concepts/configuration/commands.yaml @@ -0,0 +1,12 @@ +apiVersion: v1 +kind: Pod +metadata: + name: command-demo + labels: + purpose: demonstrate-command +spec: + containers: + - name: command-demo-container + image: debian + command: ["printenv"] + args: ["HOSTNAME", "KUBERNETES_PORT"] diff --git a/docs/concepts/configuration/container-command-args.md b/docs/concepts/configuration/container-command-args.md new file mode 100644 index 0000000000..54fe3afcb9 --- /dev/null +++ b/docs/concepts/configuration/container-command-args.md @@ -0,0 +1,84 @@ +--- +title: Container Command and Arguments +--- + +{% capture overview %} + +In the configuration file for a Container, you can set the `command` and `args` +fields to override the default Entrypoint and Cmd of the the Container's image. + +{% endcapture %} + +{% capture body %} + +## Container entry points and arguments + +The configuration file for a Container has an `image` field that specifies the +the Docker image to be run in the Container. A Docker image has metadata that includes +a default Entrypoint and a default Cmd. + +When Kubernetes starts a Container, it runs the image's default Entrypoint and +passes the image's default Cmd as arguments. + +If you want override the image's default Entrypoint and Cmd, you can use the +`command` and `args` fields in the Container's configuration. + +* The `command` field specifies the actual command run by the Container. +* The `args` field specifies the arguments passed to the command. + +This table summarizes the field names used by Docker and Kubernetes. + +| Description | Docker field name | Kubernetes field name | +|----------------------------------------|------------------------|-----------------------| +| The command run by the container | Entrypoint | command | +| The arguments passed to the command | Cmd | args | + +Here's an example of a configuration file for a Pod that has one Container. + +{% include code.html language="yaml" file="commands.yaml" ghlink="/docs/concepts/configuration/commands.yaml" %} + +When Kubernetes starts the Container, it runs this command: + +```shell +printenv HOSTNAME KUBERNETES_PORT +``` + +When you override the default Entrypoint and Cmd, these rules apply: + +* If you do not supply `command` or `args` for a Container, the defaults defined +in the Docker image are used. + +* If you supply a `command` but no `args` for a Container, only the supplied +`command` is used. The default EntryPoint and the default Cmd defined in the Docker +image are ignored. + +* If you supply only `args` for a Container, the default Entrypoint defined in +the Docker image is run with the `args` that you supplied. + +* If you supply a `command` and `args`, the default Entrypoint and the default +Cmd defined in the Docker image are ignored. Your `command` is run with your +`args`. + +Here are some examples: + +| Image Entrypoint | Image Cmd | Container command | Container args | Command run | +|--------------------|------------------|---------------------|--------------------|------------------| +| `[/ep-1]` | `[foo bar]` | <not set> | <not set> | `[ep-1 foo bar]` | +| `[/ep-1]` | `[foo bar]` | `[/ep-2]` | <not set> | `[ep-2]` | +| `[/ep-1]` | `[foo bar]` | <not set> | `[zoo boo]` | `[ep-1 zoo boo]` | + +{% endcapture %} + +{% capture whatsnext %} + +* [Defining a Command and Arguments for a Container](/docs/tasks/configure-pod-container/define-command-argument-container/) + +* [Running Commands in a Container with kubectl exec](/docs/user-guide/getting-into-containers/) + +* [Container](/docs/api-reference/v1/definitions/#_v1_container) + +* [Docker Entrypoint field](https://docs.docker.com/engine/reference/builder/) + +{% endcapture %} + +{% include templates/concept.md %} diff --git a/docs/concepts/policy/container-capabilities.md b/docs/concepts/policy/container-capabilities.md new file mode 100644 index 0000000000..21c6b38a17 --- /dev/null +++ b/docs/concepts/policy/container-capabilities.md @@ -0,0 +1,102 @@ +--- +title: Container Capabilities +--- + +{% capture overview %} + +You can specify Container capabilities by using the `securityContext` field of a +Container's configuration. + +{% endcapture %} + +{% capture body %} + +## Capabilities + +By default, Docker containers are unprivileged. For example, in the default case, +you cannot run a Docker daemon inside a Docker container. To give you control +over a container's capabilities, Docker supports `cap-add` +and `cap-drop`. For more details, see +[Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#/runtime-privilege-and-linux-capabilities). + +This table shows the relationship between Docker capabilities and +[Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html): + +| Docker's capabilities | Linux capabilities | +| ---- | ---- | +| SETPCAP | CAP_SETPCAP | +| SYS_MODULE | CAP_SYS_MODULE | +| SYS_RAWIO | CAP_SYS_RAWIO | +| SYS_PACCT | CAP_SYS_PACCT | +| SYS_ADMIN | CAP_SYS_ADMIN | +| SYS_NICE | CAP_SYS_NICE | +| SYS_RESOURCE | CAP_SYS_RESOURCE | +| SYS_TIME | CAP_SYS_TIME | +| SYS_TTY_CONFIG | CAP_SYS_TTY_CONFIG | +| MKNOD | CAP_MKNOD | +| AUDIT_WRITE | CAP_AUDIT_WRITE | +| AUDIT_CONTROL | CAP_AUDIT_CONTROL | +| MAC_OVERRIDE | CAP_MAC_OVERRIDE | +| MAC_ADMIN | CAP_MAC_ADMIN | +| NET_ADMIN | CAP_NET_ADMIN | +| SYSLOG | CAP_SYSLOG | +| CHOWN | CAP_CHOWN | +| NET_RAW | CAP_NET_RAW | +| DAC_OVERRIDE | CAP_DAC_OVERRIDE | +| FOWNER | CAP_FOWNER | +| DAC_READ_SEARCH | CAP_DAC_READ_SEARCH | +| FSETID | CAP_FSETID | +| KILL | CAP_KILL | +| SETGID | CAP_SETGID | +| SETUID | CAP_SETUID | +| LINUX_IMMUTABLE | CAP_LINUX_IMMUTABLE | +| NET_BIND_SERVICE | CAP_NET_BIND_SERVICE | +| NET_BROADCAST | CAP_NET_BROADCAST | +| IPC_LOCK | CAP_IPC_LOCK | +| IPC_OWNER | CAP_IPC_OWNER | +| SYS_CHROOT | CAP_SYS_CHROOT | +| SYS_PTRACE | CAP_SYS_PTRACE | +| SYS_BOOT | CAP_SYS_BOOT | +| LEASE | CAP_LEASE | +| SETFCAP | CAP_SETFCAP | +| WAKE_ALARM | CAP_WAKE_ALARM | +| BLOCK_SUSPEND | CAP_BLOCK_SUSPEND | + +In Kubernetes, you can add or drop capabilities in the +[`SecurityContext`](/docs/resources-reference/v1.5/#securitycontext-v1) +field of a Container: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: hello-world +spec: + containers: + - name: friendly-container + image: "alpine:3.4" + command: ["/bin/echo", "hello", "world"] + securityContext: + capabilities: + add: + - SYS_NICE + drop: + - KILL +``` + +{% endcapture %} + +{% capture whatsnext %} + +* [Security Context](/docs/user-guide/security-context/) + +* [Pod Security Policy](/docs/user-guide/pod-security-policy/) + +* [SecurityContext](/docs/resources-reference/v1.5/#securitycontext-v1) + +* [Container](/docs/api-reference/v1/definitions/#_v1_container) + +{% endcapture %} + +{% include templates/concept.md %} + diff --git a/docs/user-guide/containers.md b/docs/user-guide/containers.md index e6c135e5ea..14d1ded7fb 100644 --- a/docs/user-guide/containers.md +++ b/docs/user-guide/containers.md @@ -4,113 +4,7 @@ assignees: title: Commands and Capabilities --- -* TOC -{:toc} +{% include redirection-note.md %} -## Containers and commands - -So far the Pods we've seen have all used the `image` field to indicate what process Kubernetes -should run in a container. In this case, Kubernetes runs the image's default command. If we want -to run a particular command or override the image's defaults, there are two additional fields that -we can use: - -1. `command`: Controls the actual command run by the image -2. `args`: Controls the arguments passed to the command - -### How docker handles command and arguments - -Docker images have metadata associated with them that is used to store information about the image. -The image author may use this to define defaults for the command and arguments to run a container -when the user does not supply values. Docker calls the fields for commands and arguments -`Entrypoint` and `Cmd` respectively. The full details for this feature are too complicated to -describe here, mostly due to the fact that the docker API allows users to specify both of these -fields as either a string array or a string and there are subtle differences in how those cases are -handled. We encourage the curious to check out Docker's documentation for this feature. - -Kubernetes allows you to override both the image's default command (docker `Entrypoint`) and args -(docker `Cmd`) with the `command` and `args` fields of `container`. The rules are: - -1. If you do not supply a `command` or `args` for a container, the defaults defined by the image - will be used. -2. If you supply a `command` but no `args` for a container, only the supplied `command` will be - used; the image's default arguments are ignored. -3. If you supply only `args`, the image's default command will be used with the arguments you - supply. -4. If you supply a `command` **and** `args`, the image's defaults will be ignored and the values - you supply will be used. - -Here are examples for these rules in table format - -| Image `Entrypoint` | Image `Cmd` | Container `command` | Container `args` | Command Run | -|--------------------|------------------|---------------------|--------------------|------------------| -| `[/ep-1]` | `[foo bar]` | <not set> | <not set> | `[ep-1 foo bar]` | -| `[/ep-1]` | `[foo bar]` | `[/ep-2]` | <not set> | `[ep-2]` | -| `[/ep-1]` | `[foo bar]` | <not set> | `[zoo boo]` | `[ep-1 zoo boo]` | -| `[/ep-1]` | `[foo bar]` | `[/ep-2]` | `[zoo boo]` | `[ep-2 zoo boo]` | - - -## Capabilities - -By default, Docker containers are "unprivileged" and cannot, for example, run a Docker daemon inside a Docker container. We can have fine grain control over the capabilities using cap-add and cap-drop. More details [here](https://docs.docker.com/engine/reference/run/#/runtime-privilege-and-linux-capabilities). - -The relationship between Docker's capabilities and [Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) - -| Docker's capabilities | Linux capabilities | -| ---- | ---- | -| SETPCAP | CAP_SETPCAP | -| SYS_MODULE | CAP_SYS_MODULE | -| SYS_RAWIO | CAP_SYS_RAWIO | -| SYS_PACCT | CAP_SYS_PACCT | -| SYS_ADMIN | CAP_SYS_ADMIN | -| SYS_NICE | CAP_SYS_NICE | -| SYS_RESOURCE | CAP_SYS_RESOURCE | -| SYS_TIME | CAP_SYS_TIME | -| SYS_TTY_CONFIG | CAP_SYS_TTY_CONFIG | -| MKNOD | CAP_MKNOD | -| AUDIT_WRITE | CAP_AUDIT_WRITE | -| AUDIT_CONTROL | CAP_AUDIT_CONTROL | -| MAC_OVERRIDE | CAP_MAC_OVERRIDE | -| MAC_ADMIN | CAP_MAC_ADMIN | -| NET_ADMIN | CAP_NET_ADMIN | -| SYSLOG | CAP_SYSLOG | -| CHOWN | CAP_CHOWN | -| NET_RAW | CAP_NET_RAW | -| DAC_OVERRIDE | CAP_DAC_OVERRIDE | -| FOWNER | CAP_FOWNER | -| DAC_READ_SEARCH | CAP_DAC_READ_SEARCH | -| FSETID | CAP_FSETID | -| KILL | CAP_KILL | -| SETGID | CAP_SETGID | -| SETUID | CAP_SETUID | -| LINUX_IMMUTABLE | CAP_LINUX_IMMUTABLE | -| NET_BIND_SERVICE | CAP_NET_BIND_SERVICE | -| NET_BROADCAST | CAP_NET_BROADCAST | -| IPC_LOCK | CAP_IPC_LOCK | -| IPC_OWNER | CAP_IPC_OWNER | -| SYS_CHROOT | CAP_SYS_CHROOT | -| SYS_PTRACE | CAP_SYS_PTRACE | -| SYS_BOOT | CAP_SYS_BOOT | -| LEASE | CAP_LEASE | -| SETFCAP | CAP_SETFCAP | -| WAKE_ALARM | CAP_WAKE_ALARM | -| BLOCK_SUSPEND | CAP_BLOCK_SUSPEND | - -You can add or drop capabilities in the [`SecurityContext`](http://kubernetes.io/docs/api-reference/v1/definitions/#_v1_securitycontext), e.g.: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: hello-world -spec: - containers: - - name: friendly-container - image: "alpine:3.4" - command: ["/bin/echo", "hello", "world"] - securityContext: - capabilities: - add: - - SYS_NICE - drop: - - KILL -``` +* [Container Command and Arguments](/docs/concepts/configuration/container-command-args/) +* [Container Capabilities](/docs/concepts/policy/container-capabilities/) From 9891d65d3e27511e9e4ed2ff5c75b481ee8c4a57 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Wed, 1 Feb 2017 15:05:34 -0800 Subject: [PATCH 2/2] Change name of include file for moved content. --- _includes/{redirection-note.md => user-guide-content-moved.md} | 0 docs/user-guide/containers.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename _includes/{redirection-note.md => user-guide-content-moved.md} (100%) diff --git a/_includes/redirection-note.md b/_includes/user-guide-content-moved.md similarity index 100% rename from _includes/redirection-note.md rename to _includes/user-guide-content-moved.md diff --git a/docs/user-guide/containers.md b/docs/user-guide/containers.md index 14d1ded7fb..dfe48ade49 100644 --- a/docs/user-guide/containers.md +++ b/docs/user-guide/containers.md @@ -4,7 +4,7 @@ assignees: title: Commands and Capabilities --- -{% include redirection-note.md %} +{% include user-guide-content-moved.md %} * [Container Command and Arguments](/docs/concepts/configuration/container-command-args/) * [Container Capabilities](/docs/concepts/policy/container-capabilities/)