whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #2386 from steveperry-53/commands-capabilities

Browse Source 
Move Commands and Capabilities out of User Guide.
This commit is contained in:
Steve Perry
2017-02-01 15:19:11 -08:00
committed by GitHub
parent c4bbf9a8c7 9891d65d3e
commit 214e749bf7
6 changed files with 216 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_data/concepts.yml
+12
View File
@@ -2,19 +2,31 @@ 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
- docs/concepts/tools/kubectl/object-management-using-imperative-commands.md
- docs/concepts/tools/kubectl/object-management-using-imperative-config.md
- docs/concepts/tools/kubectl/object-management-using-declarative-config.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
_includes/user-guide-content-moved.md
+3
View File
@@ -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:
docs/concepts/configuration/commands.yaml
+12
View File
@@ -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"]
docs/concepts/configuration/container-command-args.md
+84
View File
@@ -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 %}
docs/concepts/policy/container-capabilities.md
+102
View File
@@ -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 %}
docs/user-guide/containers.md
+3 -109
View File
@@ -4,113 +4,7 @@ assignees:
title: Commands and Capabilities
---
* TOC
{:toc}
{% include user-guide-content-moved.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/)