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

Release 1.7 (#4094)

Browse Source 
* 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 (https://github.com/kubernetes/kubernetes/pull/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 https://github.com/kubernetes/kubeadm/issues/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:
https://github.com/kubernetes/kubernetes/pull/43696
This commit is contained in:
zhangchaolei
2017-06-30 13:39:40 +08:00
committed by Dawn Chen
parent cbdb17706f
commit aae3bfaf3e
1620 changed files with 297157 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
-116
View File
@@ -1,116 +0,0 @@
---
assignees:
- davidopp
title: Configure a Pod Disruption Budget
redirect_from:
- "/docs/admin/disruptions/"
- "/docs/admin/disruptions.html"
- "/docs/tasks/configure-pod-container/configure-pod-disruption-budget/"
- "/docs/tasks/configure-pod-container/configure-pod-disruption-budget/"
---
This guide is for anyone wishing to specify safety constraints on pods or anyone
wishing to write software (typically automation software) that respects those
constraints.
* TOC
{:toc}
## Rationale
Various cluster management operations may voluntarily evict pods. "Voluntary"
means an eviction can be safely delayed for a reasonable period of time. The
principal examples today are draining a node for maintenance or upgrade
(`kubectl drain`), and cluster autoscaling down. In the future the
[rescheduler](https://git.k8s.io/community/contributors/design-proposals/rescheduling.md)
may also perform voluntary evictions. By contrast, something like evicting pods
because a node has become unreachable or reports `NotReady`, is not "voluntary."
For voluntary evictions, it can be useful for applications to be able to limit
the number of pods that are down simultaneously. For example, a quorum-based application would
like to ensure that the number of replicas running is never brought below the
number needed for a quorum, even temporarily. Or a web front end might want to
ensure that the number of replicas serving load never falls below a certain
percentage of the total, even briefly. `PodDisruptionBudget` is an API object
that specifies the minimum number or percentage of replicas of a collection that
must be up at a time. Components that wish to evict a pod subject to disruption
budget use the `/eviction` subresource; unlike a regular pod deletion, this
operation may be rejected by the API server if the eviction would cause a
disruption budget to be violated.
## Specifying a PodDisruptionBudget
A `PodDisruptionBudget` has two components: a label selector `selector` to specify the set of
pods to which it applies, and `minAvailable` which is a description of the number of pods from that
set that must still be available after the eviction, i.e. even in the absence
of the evicted pod. `minAvailable` can be either an absolute number or a percentage.
So for example, 100% means no voluntary evictions from the set are permitted. In
typical usage, a single budget would be used for a collection of pods managed by
a controller—for example, the pods in a single ReplicaSet.
Note that a disruption budget does not truly guarantee that the specified
number/percentage of pods will always be up. For example, a node that hosts a
pod from the collection may fail when the collection is at the minimum size
specified in the budget, thus bringing the number of available pods from the
collection below the specified size. The budget can only protect against
voluntary evictions, not all causes of unavailability.
You can find an example of a pod disruption budget defined below. It matches pods with the label
`app: zookeeper`.
```yaml
apiVersion: policy/v1beta1
kind: PodDisruptionBudget
metadata:
name: zk-pdb
spec:
minAvailable: 2
selector:
matchLabels:
app: zookeeper
```
## Requesting an eviction
If you are writing infrastructure software that wants to produce these voluntary
evictions, you will need to use the eviction API. The eviction subresource of a
pod can be thought of as a kind of policy-controlled DELETE operation on the pod
itself. To attempt an eviction (perhaps more REST-precisely, to attempt to
*create* an eviction), you POST an attempted operation. Here's an example:
```json
{
"apiVersion": "policy/v1beta1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
You can attempt an eviction using `curl`:
```bash
$ curl -v -H 'Content-type: application/json' http://127.0.0.1:8080/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json
```
The API can respond in one of three ways.
1. If the eviction is granted, then the pod is deleted just as if you had sent
a `DELETE` request to the pod's URL and you get back `200 OK`.
2. If the current state of affairs wouldn't allow an eviction by the rules set
forth in the budget, you get back `429 Too Many Requests`. This is
typically used for generic rate limiting of *any* requests, but here we mean
that this request isn't allowed *right now* but it may be allowed later.
Currently, callers do not get any `Retry-After` advice, but they may in
future versions.
3. If there is some kind of misconfiguration, like multiple budgets pointing at
the same pod, you will get `500 Internal Server Error`.
For a given eviction request, there are two cases.
1. There is no budget that matches this pod. In this case, the server always
returns `200 OK`.
2. There is at least one budget. In this case, any of the three above responses may
apply.
docs/tasks/administer-cluster/declare-network-policy.md
+4 -27
View File
@@ -1,6 +1,7 @@
---
assignees:
- caseydavenport
- danwinship
title: Declare Network Policy
redirect_from:
- "/docs/getting-started-guides/network-policy/walkthrough/"
@@ -68,35 +69,11 @@ Connecting to nginx (10.100.0.16:80)
## Limit access to the `nginx` service
Let's say you want to limit access to the `nginx` service so that only pods with the label `access: true` can query it. The first step is to enable ingress isolation on the `default` namespace. This prevents **_any_** pods from accessing the `nginx` service.
```console
$ kubectl annotate ns default "net.beta.kubernetes.io/network-policy={\"ingress\": {\"isolation\": \"DefaultDeny\"}}"
```
## Test the access limitation
Test to see that with ingress isolation in place, you no longer have access to the `nginx` service:
```console
$ kubectl run busybox --rm -ti --image=busybox /bin/sh
Waiting for pod default/busybox-472357175-y0m47 to be running, status is Pending, pod ready: false
Hit enter for command prompt
/ # wget --spider --timeout=1 nginx
Connecting to nginx (10.100.0.16:80)
wget: download timed out
/ #
```
## Create a policy that allows connections from authorized pods
Next, create a `NetworkPolicy` that allows connections from pods with the label `access: true`.
Let's say you want to limit access to the `nginx` service so that only pods with the label `access: true` can query it. To do that, create a `NetworkPolicy` that allows connections only from those pods:
```yaml
kind: NetworkPolicy
apiVersion: extensions/v1beta1
apiVersion: networking/v1
metadata:
name: access-nginx
spec:
@@ -119,7 +96,7 @@ networkpolicy "access-nginx" created
```
## Test access to the service when access label is not defined
If we attempt to access the nginx Service from a pod without the correct labels, the request will still time out:
If we attempt to access the nginx Service from a pod without the correct labels, the request will now time out:
```console
$ kubectl run busybox --rm -ti --image=busybox /bin/sh
docs/tasks/administer-cluster/dns-custom-nameservers.md
+147
View File
@@ -0,0 +1,147 @@
---
assignees:
- bowei
- zihongz
title: Configure private DNS zones and upstream nameservers in Kubernetes
---
{% capture overview %}
This page shows how to add custom private DNS zones (stub domains) and upstream
nameservers.
{% endcapture %}
{% capture prerequisites %}
* {% include task-tutorial-prereqs.md %}
* Kubernetes version 1.6 and above.
* The cluster must be configured to use the `kube-dns` addon.
{% endcapture %}
{% capture steps %}
## Configure stub-domain and upstream DNS servers
Cluster administrators can specify custom stub domains and upstream nameservers
by providing a ConfigMap for kube-dns (`kube-system:kube-dns`).
For example, the following ConfigMap sets up a DNS configuration with a single stub domain and two
upstream nameservers.
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kube-dns
namespace: kube-system
data:
stubDomains: |
{“acme.local”: [“1.2.3.4”]}
upstreamNameservers: |
[“8.8.8.8”, “8.8.4.4”]
```
As specified, DNS requests with the “.acme.local” suffix
are forwarded to a DNS listening at 1.2.3.4. Google Public DNS
serves the upstream queries.
The table below describes how queries with certain domain names would map to their destination DNS servers:
| Domain name | Server answering the query |
| ----------- | -------------------------- |
| kubernetes.default.svc.cluster.local| kube-dns |
| foo.acme.local| custom DNS (1.2.3.4) |
| widget.com | upstream DNS (one of 8.8.8.8, 8.8.4.4) |
See [ConfigMap options](#configmap-options) for
details about the configuration option format.
{% endcapture %}
{% capture discussion %}
## Understanding name resolution in Kubernetes
DNS policies can be set on a per-pod basis. Currently Kubernetes supports two pod-specific DNS policies: “Default” and “ClusterFirst”. These policies are specified with the `dnsPolicy` flag.
*NOTE: "Default" is not the default DNS policy. If `dnsPolicy` is not
explicitly specified, then “ClusterFirst” is used.*
### "Default" DNS Policy
If `dnsPolicy` is set to “Default”, then the name resolution configuration is
inherited from the node that the pods run on. Custom upstream nameservers and stub domains cannot be used in conjunction with this policy.
### "ClusterFirst" DNS Policy
If the `dnsPolicy` is set to "ClusterFirst", name resolution is handled differently, *depending on whether stub-domain and upstream DNS servers are configured*.
**Without custom configurations**: Any query that does not match the configured cluster domain suffix, such as "www.kubernetes.io", is forwarded to the upstream nameserver inherited from the node.
**With custom configurations**: If stub domains and upstream DNS servers are configured (as in the [previous example](#configuring-stub-domain-and-upstream-dns-servers)), DNS queries will be
routed according to the following flow:
1. The query is first sent to the DNS caching layer in kube-dns.
1. From the caching layer, the suffix of the request is examined and then forwarded to the appropriate DNS, based on the following cases:
* *Names with the cluster suffix* (e.g.".cluster.local"): The request is sent to kube-dns.
* *Names with the stub domain suffix* (e.g. ".acme.local"): The request is sent to the configured custom DNS resolver (e.g. listening at 1.2.3.4).
* *Names without a matching suffix* (e.g."widget.com"): The request is forwarded to the upstream DNS (e.g. Google public DNS servers at 8.8.8.8 and 8.8.4.4).
![DNS lookup flow](/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png)
## ConfigMap options
Options for the kube-dns `kube-system:kube-dns` ConfigMap
| Field | Format | Description |
| ----- | ------ | ----------- |
| `stubDomains` (optional) | A JSON map using a DNS suffix key (e.g. “acme.local”) and a value consisting of a JSON array of DNS IPs. | The target nameserver may itself be a Kubernetes service. For instance, you can run your own copy of dnsmasq to export custom DNS names into the ClusterDNS namespace. |
| `upstreamNameservers` (optional) | A JSON array of DNS IPs. | Note: If specified, then the values specified replace the nameservers taken by default from the node’s `/etc/resolv.conf`. Limits: a maximum of three upstream nameservers can be specified. |
## Additional examples
### Example: Stub domain
In this example, the user has a Consul DNS service discovery system that they wish to
integrate with kube-dns. The consul domain server is located at 10.150.0.1, and
all consul names have the suffix “.consul.local”. To configure Kubernetes, the
cluster administrator simply creates a ConfigMap object as shown below.
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kube-dns
namespace: kube-system
data:
stubDomains: |
{“consul.local”: [“10.150.0.1”]}
```
Note that the cluster administrator did not wish to override the node’s
upstream nameservers, so they did not specify the optional
`upstreamNameservers` field.
### Example: Upstream nameserver
In this example the cluster administrator wants to explicitly force all
non-cluster DNS lookups to go through their own nameserver at 172.16.0.1.
Again, this is easy to accomplish; they just need to create a ConfigMap with the
`upstreamNameservers` field specifying the desired nameserver.
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kube-dns
namespace: kube-system
data:
upstreamNameservers: |
[“172.16.0.1”]
```
{% endcapture %}
{% include templates/task.md %}
docs/tasks/administer-cluster/dns-custom-nameservers/dns.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

docs/tasks/administer-cluster/encrypt-data.md
+197
View File
@@ -0,0 +1,197 @@
---
assignees:
- smarterclayton
title: Encrypting data at rest
---
{% capture overview %}
This page shows how to enable and configure encryption of secret data at rest.
{% endcapture %}
{% capture prerequisites %}
* {% include task-tutorial-prereqs.md %}
* Kubernetes version 1.7.0 or later is required
* Encryption at rest is alpha in 1.7.0 which means it may change without notice. Users may be required to decrypt their data prior to upgrading to 1.8.0.
{% endcapture %}
{% capture steps %}
## Configuration and determining whether encryption at rest is already enabled
The `kube-apiserver` process accepts an argument `--experimental-encryption-provider-config`
that controls how API data is encrypted in etcd. An example configuration
is provided below.
## Understanding the encryption at rest configuration.
```yaml
kind: EncryptionConfig
apiVersion: v1
resources:
- resources:
- secrets
providers:
- identity: {}
- aesgcm:
keys:
- name: key1
secret: c2VjcmV0IGlzIHNlY3VyZQ==
- name: key2
secret: dGhpcyBpcyBwYXNzd29yZA==
- aescbc:
keys:
- name: key1
secret: c2VjcmV0IGlzIHNlY3VyZQ==
- name: key2
secret: dGhpcyBpcyBwYXNzd29yZA==
- secretbox:
keys:
- name: key1
secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=
```
Each `resources` array item is a separate config and contains a complete configuration. The
`resources.resources` field is an array of Kubernetes resource names (`resource` or `resource.group`)
that should be encrypted. The `providers` array is an ordered list of the possible encryption
providers. Only one provider type may be specified per entry (`identity` or `aescbc` may be provided,
but not both in the same item).
The first provider in the list is used to encrypt resources going into storage. When reading
resources from storage each provider that matches the stored data attempts to decrypt the data in
order. If no provider can read the stored data due to a mismatch in format or secret key, an error
is returned which prevents clients from accessing that resource.
**IMPORTANT:** If any resource is not readable via the encryption config (because keys were changed),
the only recourse is to delete that key from the underlying etcd directly. Calls that attempt to
read that resource will fail until it is deleted or a valid decryption key is provided.
### Providers:
Name | Encryption | Strength | Speed | Key Length | Other Considerations
-----|------------|----------|-------|------------|---------------------
`identity` | None | N/A | N/A | N/A | Resources written as-is without encryption. When set as the first provider, the resource will be decrypted as new values are written.
`aescbc` | AES-CBC with PKCS#7 padding | Strongest | Fast | 32-byte | The recommended choice for encryption at rest but may be slightly slower than `secretbox`.
`secretbox` | XSalsa20 and Poly1305 | Strong | Faster | 32-byte | A newer standard and may not be considered acceptable in environments that require high levels of review.
`aesgcm` | AES-GCM with random nonce | Must be rotated every 200k writes | Fastest | 16, 24, or 32-byte | Is not recommended for use except when an automated key rotation scheme is implemented.
Each provider supports multiple keys - the keys are tried in order for decryption, and if the provider
is the first provider, the first key is used for encryption.
## Encrypting your data
Create a new encryption config file
```yaml
kind: EncryptionConfig
apiVersion: v1
resources:
- resources:
- secrets
providers:
- aescbc:
keys:
- name: key1
secret: <BASE 64 ENCODED SECRET>
- identity: {}
```
To create a new secret perform the following steps:
1. Generate a 32 byte random key and base64 encode it. If you're on Linux or Mac OS X, run the following command:
```
head -c 32 /dev/urandom | base64 -i - -o -
```
2. Place that value in the secret field.
3. Set the `--experimental-encryption-provider-config` flag on the `kube-apiserver` to point to the location of the config file
4. restart your API server.
**IMPORTANT:** Your config file contains keys that can decrypt content in etcd, so you must properly restrict permissions on your masters so only the user who runs the kube-apiserver can read it.
## Verifying that data is encrypted
Data is encrypted when written to etcd. After restarting your `kube-apiserver`, any newly created or
updated secret should be encrypted when stored. To check, you can use the `etcdctl` command line
program to retrieve the contents of your secret.
1. Create a new secret called `secret1` in the `default` namespace:
```
kubectl create secret generic secret1 -n default --from-literal=mykey=mydata
```
2. Using the etcdctl commandline, read that secret out of etcd:
```
ETCDCTL_API=3 etcdctl get /kubernetes.io/secrets/default/secret1 [...] | hexdump -C
```
where `[...]` must be the additional arguments for connecting to the etcd server.
3. Verify the stored secret is prefixed with `k8s:enc:aescbc:v1:` which indicates the `aescbc` provider has encrypted the resulting data.
4. Verify the secret is correctly decrypted when retrieved via the API:
```
kubectl describe secret generic -n default
```
should match `mykey: mydata`
## Ensure all secrets are encrypted
Since secrets are encrypted on write, performing an update on a secret will encrypt that content.
```
kubectl get secrets -o json | kubectl update -f -
```
The command above reads all secrets and then updates them to apply server side encryption.
If an error occurs due to a conflicting write, retry the command.
For larger clusters, you may wish to subdivide the secrets by namespace or script an update.
## Rotating a decryption key
Changing the secret without incurring downtime requires a multi step operation, especially in
the presence of a highly available deployment where multiple `kube-apiserver` processes are running.
1. Generate a new key and add it as the second key entry for the current provider on all servers
2. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key
3. Make the new key the first entry in the `keys` array so that it is used for encryption in the config
4. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key
5. Run `kubectl get secrets -o json | kubectl update -f -` to update all secrets
6. Remove the old decryption key from the config after you back up etcd with the new key in use and update all secrets
With a single `kube-apiserver`, step 2 may be skipped
## Decrypting all data
To disable encryption at rest place the `identity` provider as the first entry in the config:
```yaml
kind: EncryptionConfig
apiVersion: v1
resources:
- resources:
- secrets
providers:
- identity: {}
- aescbc:
keys:
- name: key1
secret: <BASE 64 ENCODED SECRET>
```
and restart all `kube-apiserver` processes. Then run the command `kubectl get secrets -o json | kubectl update -f -`
to force all secrets to be decrypted.
{% endcapture %}
{% include templates/task.md %}
docs/tasks/administer-cluster/kubeadm-upgrade-1-7.md
+94
View File
@@ -0,0 +1,94 @@
---
assignees:
- pipejakob
title: Upgrading kubeadm clusters from 1.6 to 1.7
redirect_from:
- "/docs/admin/kubeadm-upgrade-1-7/"
- "/docs/admin/kubeadm-upgrade-1-7.html"
---
{% capture overview %}
This guide is for upgrading kubeadm clusters from version 1.6.x to 1.7.x.
Upgrades are not supported for clusters lower than 1.6, which is when kubeadm
became Beta.
**WARNING**: These instructions will **overwrite** all of the resources managed
by kubeadm (static pod manifest files, service accounts and RBAC rules in the
`kube-system` namespace, etc.), so any customizations you may have made to these
resources after cluster setup will need to be reapplied after the upgrade. The
upgrade will not disturb other static pod manifest files or objects outside the
`kube-system` namespace.
{% endcapture %}
{% capture prerequisites %}
You need to have a Kubernetes cluster running version 1.6.x.
{% endcapture %}
{% capture steps %}
## On the master
1. Upgrade system packages.
Upgrade your OS packages for kubectl, kubeadm, kubelet, and kubernetes-cni.
a. On Debian, this can be accomplished with:
sudo apt-get update
sudo apt-get upgrade
b. On CentOS/Fedora, you would instead run:
sudo yum update
2. Restart kubelet.
sudo systemctl restart kubelet
3. Delete the `kube-proxy` DaemonSet.
Although most components are automatically upgraded by the next step,
`kube-proxy` currently needs to be manually deleted so it can be recreated at
the correct version:
sudo KUBECONFIG=/etc/kubernetes/admin.conf kubectl delete daemonset kube-proxy -n kube-system
4. Perform kubeadm upgrade.
sudo kubeadm init --skip-preflight-checks --kubernetes-version <DESIRED_VERSION>
For instance, if you want to upgrade to `1.7.0`, you would run:
sudo kubeadm init --skip-preflight-checks --kubernetes-version v1.7.0
5. Upgrade CNI provider.
Your CNI provider might have its own upgrade instructions to follow now.
Check the [addons](/docs/concepts/cluster-administration/addons/) page to
find your CNI provider and see if there are additional upgrade steps
necessary.
## On each node
1. Upgrade system packages.
Upgrade your OS packages for kubectl, kubeadm, kubelet, and kubernetes-cni.
a. On Debian, this can be accomplished with:
sudo apt-get update
sudo apt-get upgrade
b. On CentOS/Fedora, you would instead run:
sudo yum update
2. Restart kubelet.
sudo systemctl restart kubelet
{% endcapture %}
{% include templates/task.md %}
docs/tasks/administer-cluster/reserve-compute-resources.md
+16 -13
View File
@@ -45,8 +45,7 @@ on each node.
`Allocatable` on a Kubernetes node is defined as the amount of compute resources
that are available for pods. The scheduler does not over-subscribe
`Allocatable`. `CPU` and `memory` are supported as of now. Support for `storage`
is expected to be added in the future.
`Allocatable`. `CPU`, `memory` and `storage` are supported as of now.
Node Allocatable is exposed as part of `v1.Node` object in the API and as part
of `kubectl describe node` in the CLI.
@@ -81,7 +80,7 @@ be configured to use the `systemd` cgroup driver.
### Kube Reserved
- **Kubelet Flag**: `--kube-reserved=[cpu=100m][,][memory=100Mi]`
- **Kubelet Flag**: `--kube-reserved=[cpu=100m][,][memory=100Mi][,][storage=1Gi]`
- **Kubelet Flag**: `--kube-reserved-cgroup=`
`kube-reserved` is meant to capture resource reservation for kubernetes system
@@ -111,7 +110,7 @@ exist. Kubelet will fail if an invalid cgroup is specified.
### System Reserved
- **Kubelet Flag**: `--system-reserved=[cpu=100mi][,][memory=100Mi]`
- **Kubelet Flag**: `--system-reserved=[cpu=100mi][,][memory=100Mi][,][storage=1Gi]`
- **Kubelet Flag**: `--system-reserved-cgroup=`
@@ -194,20 +193,22 @@ So expect a drop in `Allocatable` capacity in future releases.
Here is an example to illustrate Node Allocatable computation:
* Node has `32Gi` of `memory` and `16 CPUs`
* `--kube-reserved` is set to `cpu=1,memory=2Gi`
* `--system-reserved` is set to `cpu=500m,memory=1Gi`
* `--eviction-hard` is set to `memory.available<500Mi`
* Node has `32Gi` of `memory`, `16 CPUs` and `100Gi` of `Storage`
* `--kube-reserved` is set to `cpu=1,memory=2Gi,storage=1Gi`
* `--system-reserved` is set to `cpu=500m,memory=1Gi,storage=1Gi`
* `--eviction-hard` is set to `memory.available<500Mi,nodefs.available<10%`
Under this scenario, `Allocatable` will be `14.5 CPUs` & `28.5Gi` of memory.
Scheduler ensures that the total `requests` across all pods on this node does
not exceed `28.5Gi`. Kubelet evicts pods whenever the overall memory usage
exceeds across pods exceed `28.5Gi`. If all processes on the node consume as
Under this scenario, `Allocatable` will be `14.5 CPUs`, `28.5Gi` of memory and
`98Gi` of local storage.
Scheduler ensures that the total memory `requests` across all pods on this node does
not exceed `28.5Gi` and storage doesn't exceed `88Gi`.
Kubelet evicts pods whenever the overall memory usage exceeds across pods exceed `28.5Gi`,
or if overall disk usage exceeds `88Gi` If all processes on the node consume as
much CPU as they can, pods together cannot consume more than `14.5 CPUs`.
If `kube-reserved` and/or `system-reserved` is not enforced and system daemons
exceed their reservation, `kubelet` evicts pods whenever the overall node memory
usage is higher than `31.5Gi`.
usage is higher than `31.5Gi` or `storage` is greater than `90Gi`
## Feature Availability
@@ -231,3 +232,5 @@ required to drain their nodes prior to upgrade of the `kubelet` from prior
versions in order to ensure pods and their associated containers are launched in
the proper part of the cgroup hierarchy.
As of Kubernetes version 1.7, `kubelet` supports specifying `storage` as a resource
for `kube-reserved` and `system-reserved`.
docs/tasks/administer-cluster/safely-drain-node.md
+74 -3
View File
@@ -1,6 +1,9 @@
---
assignees:
- davidopp
- mml
- foxish
- kow3ns
title: Safely Drain a Node while Respecting Application SLOs
---
@@ -14,8 +17,12 @@ disruption SLOs you have specified using PodDisruptionBudget.
This task assumes that you have met the following prerequisites:
* You are using Kubernetes release >= 1.5.
* You have created [PodDisruptionBudget(s)](/docs/tasks/configure-pod-container/configure-pod-disruption-budget/) to express the
application-level disruption SLOs you want the system to enforce.
* Either:
1. You do not require your applications to be highly available during the
node drain, or
1. You have read about the [PodDisruptionBudget concept](/docs/concepts/workloads/pods/disruptions.md)
and [Configured PodDisruptionBudgets](/docs/tasks/run-application/configure-pdb.md) for
applications that need them.
{% endcapture %}
@@ -81,11 +88,75 @@ that only one pod is unavailable at any given time. Any drains that
would cause the number of ready replicas to fall below the specified
budget are blocked.
## The Eviction API
If you prefer not to use [kubectl drain](/docs/user-guide/kubectl/v1.6/#drain) (such as
to avoid calling to an external command, or to get finer control over over the pod
eviction process), you can also programmatically cause evictions using the eviction API.
You should first be familiar with using [Kubernetes language clients](/docs/tasks/administer-cluster/access-cluster-api.md#programmatic-access-to-the-api).
The eviction subresource of a
pod can be thought of as a kind of policy-controlled DELETE operation on the pod
itself. To attempt an eviction (perhaps more REST-precisely, to attempt to
*create* an eviction), you POST an attempted operation. Here's an example:
```json
{
"apiVersion": "policy/v1beta1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
You can attempt an eviction using `curl`:
```bash
$ curl -v -H 'Content-type: application/json' http://127.0.0.1:8080/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json
```
The API can respond in one of three ways:
- If the eviction is granted, then the pod is deleted just as if you had sent
a `DELETE` request to the pod's URL and you get back `200 OK`.
- If the current state of affairs wouldn't allow an eviction by the rules set
forth in the budget, you get back `429 Too Many Requests`. This is
typically used for generic rate limiting of *any* requests, but here we mean
that this request isn't allowed *right now* but it may be allowed later.
Currently, callers do not get any `Retry-After` advice, but they may in
future versions.
- If there is some kind of misconfiguration, like multiple budgets pointing at
the same pod, you will get `500 Internal Server Error`.
For a given eviction request, there are two cases.
- There is no budget that matches this pod. In this case, the server always
returns `200 OK`.
- There is at least one budget. In this case, any of the three above responses may
apply.
In some cases, an application may reach a broken state where it will never return anything
other than 429 or 500. This can happen, for example, if the replacement pod created by the
application's controller does not become ready, or if the last pod evicted has a very long
termination grace period.
In this case, there are two potential solutions:
- Abort or pause the automated operation. Investigate the reason for the stuck application, and restart the automation.
- After a suitably long wait, `DELETE` the pod instead of using the eviction API.
Kubernetes does not specify what the behavior should be in this case; it is up to the
application owners and cluster owners to establish an agreement on behavior in these cases.
{% endcapture %}
{% capture whatsnext %}
*TODO: link to other docs about Stateful Set?*
* Follow steps to protect your application by [configuring a Pod Disruption Budget](/docs/tasks/run-application//configure-pdb.md).
{% endcapture %}
{% include templates/task.md %}
docs/tasks/administer-cluster/securing-a-cluster.md
+205
View File
@@ -0,0 +1,205 @@
---
assignees:
- smarterclayton
title: Securing a Cluster
---
{% capture overview %}
This document covers topics related to protecting a cluster from accidental or malicious access
and provides recommendations on overall security.
{% endcapture %}
{% capture prerequisites %}
* {% include task-tutorial-prereqs.md %}
{% endcapture %}
{% capture steps %}
## Controlling access to the Kubernetes API
As Kubernetes is entirely API driven, controlling and limiting who can access the cluster and what actions
they are allowed to perform is the first line of defense.
### Use Transport Level Security (TLS) for all API traffic
Kubernetes expects that all API communication in the cluster is encrypted by default with TLS, and the
majority of installation methods will allow the necessary certificates to be created and distributed to
the cluster components. Note that some components and installation methods may enable local ports over
HTTP and administrators should familiarize themselves with the settings of each component to identify
potentially unsecured traffic.
### API Authentication
Choose an authentication mechanism for the API servers to use that matches the common access patterns
when you install a cluster. For instance, small single user clusters may wish to use a simple certificate
or static Bearer token approach. Larger clusters may wish to integrate an existing or OIDC or LDAP server that
allow users to be subdivided into groups.
All API clients must be authenticated, even those that are part of the infrastructure like nodes,
proxies, the scheduler, and volume plugins. These clients are typically [service accounts](/docs/admin/service-accounts-admin/) or use x509 client certificates, and they are created automatically at cluster startup or are setup as part of the cluster installation.
Consult the [authentication reference document](/docs/admin/authentication/) for more information.
### API Authorization
Once authenticated, every API call is also expected to pass an authorization check. Kubernetes ships
an integrated [Role-Based Access Control (RBAC)](/docs/admin/authorization/rbac/) component that matches an incoming user or group to a
set of permissions bundled into roles. These permissions combine verbs (get, create, delete) with
resources (pods, services, nodes) and can be namespace or cluster scoped. A set of out of the box
roles are provided that offer reasonable default separation of responsibility depending on what
actions a client might want to perform. It is recommended that you use the [Node](/docs/admin/authorization/node/) and [RBAC](/docs/admin/authorization/rbac/) authorizers together, in combination with the
[NodeRestriction](/docs/admin/admission-controllers/#noderestriction) admission plugin.
As with authentication, simple and broad roles may be appropriate for smaller clusters, but as
more users interact with the cluster, it may become necessary to separate teams into separate
namespaces with more limited roles.
With authorization, it is important to understand how updates on one object may cause actions in
other places. For instance, a user may not be able to create pods directly, but allowing them to
create a deployment, which creates pods on their behalf, will let them create those pods
indirectly. Likewise, deleting a node from the API will result in the pods scheduled to that node
being terminated and recreated on other nodes. The out of the box roles represent a balance
between flexibility and the common use cases, but more limited roles should be carefully reviewed
to prevent accidental escalation. You can make roles specific to your use case if the out-of-box ones don't meet your needs.
Consult the [authorization reference section](/docs/admin/authorization) for more information.
## Controlling the capabilities of a workload or user at runtime
Authorization in Kubernetes is intentionally high level, focused on coarse actions on resources.
More powerful controls exist as **policies** to limit by use case how those objects act on the
cluster, themselves, and other resources.
### Limiting resource usage on a cluster
[Resource quota](/docs/concepts/policy/resource-quotas/) limits the number or capacity of
resources granted to a namespace. This is most often used to limit the amount of CPU, memory,
or persistent disk a namespace can allocate, but can also control how many pods, services, or
volumes exist in each namespace.
[Limit ranges](/docs/admin/limitrange) restrict the maximum or minimum size of some of the
resources above, to prevent users from requesting unreasonably high or low values for commonly
reserved resources like memory, or to provide default limits when none are specified.
### Controlling what privileges containers run with
A pod definition contains a [security context](/docs/tasks/configure-pod-container/security-context/)
that allows it to request access to running as a specific Linux user on a node (like root),
access to run privileged or access the host network, and other controls that would otherwise
allow it to run unfettered on a hosting node. [Pod security policies](/docs/concepts/policy/pod-security-policy/)
can limit which users or service accounts can provide dangerous security context settings. For example, pod security policies can limit volume mounts, especially `hostPath`, which are aspects of a pod that should be controlled.
Generally, most application workloads need limited access to host resources so they can
successfully run as a root process (uid 0) without access to host information. However,
considering the privileges associated with the root user, you should write application
containers to run as a non-root user. Similarly, administrators who wish to prevent
client applications from escaping their containers should use a restrictive pod security
policy.
### Restricting network access
The [network policies](/docs/tasks/administer-cluster/declare-network-policy/) for a namespace
allows application authors to restrict which pods in other namespaces may access pods and ports
within their namespace. Many of the supported [Kubernetes networking providers](/docs/concepts/cluster-administration/networking/)
now respect network policy.
Quota and limit ranges can also be used to control whether users may request node ports or
load balanced services, which on many clusters can control whether those users applications
are visible outside of the cluster.
Additional protections may be available that control network rules on a per plugin or per
environment basis, such as per-node firewalls, physically separating cluster nodes to
prevent cross talk, or advanced networking policy.
### Controlling which nodes pods may access
By default, there are no restrictions on which nodes may run a pod. Kubernetes offers a
[rich set of policies for controlling placement of pods onto nodes](/docs/concepts/configuration/assign-pod-node/)
that are available to end users. For many clusters use of these policies to separate workloads
can be a convention that authors adopt or enforce via tooling.
As an administrator, a beta admission plugin `PodNodeSelector` can be used to force pods
within a namespace to default or require a specific node selector, and if end users cannot
alter namespaces, this can strongly limit the placement of all of the pods in a specific workload.
## Protecting cluster components from compromise
This section describes some common patterns for protecting clusters from compromise.
### Restrict access to etcd
Write access to the etcd backend for the API is equivalent to gaining root on the entire cluster,
and read access can be used to escalate fairly quickly. Administrators should always use strong
credentials from the API servers to their etcd server, such as mutual auth via TLS client certificates,
and it is often recommended to isolate the etcd servers behind a firewall that only the API servers
may access.
**CAUTION:** Allowing other components within the cluster to access the master etcd instance with
read or write access to the full keyspace is equivalent to granting cluster-admin access. Using
separate etcd instances for non-master components or using etcd ACLs to restrict read and write
access to a subset of the keyspace is strongly recommended.
### Enable audit logging
The [audit logger](/docs/admin/audit/) is an alpha feature that records actions taken by the
API for later analysis in the event of a compromise. It is recommended to enable audit logging
and archive the audit file on a secure server.
### Restrict access to alpha or beta features
Alpha and beta Kubernetes features are in active development and may have limitations or bugs
that result in security vulnerabilities. Always assess the value an alpha or beta feature may
provide against the possible risk to your security posture. When in doubt, disable features you
do not use.
### Rotate infrastructure credentials frequently
The shorter the lifetime of a secret or credential the harder it is for an attacker to make
use of that credential. Set short lifetimes on certificates and automate their rotation. Use
an authentication provider that can control how long issued tokens are available and use short
lifetimes where possible. If you use service account tokens in external integrations, plan to
rotate those tokens frequently. For example, once the bootstrap phase is complete, a bootstrap token used for setting up nodes should be revoked or its authorization removed.
### Review third party integrations before enabling them
Many third party integrations to Kubernetes may alter the security profile of your cluster. When
enabling an integration, always review the permissions that an extension requests before granting
it access. For example, many security integrations may request access to view all secrets on
your cluster which is effectively making that component a cluster admin. When in doubt,
restrict the integration to functioning in a single namespace if possible.
Components that create pods may also be unexpectedly powerful if they can do so inside namespaces
like the `kube-system` namespace, because those pods can gain access to service account secrets
or run with elevated permissions if those service accounts are granted access to permissive
[pod security policies](/docs/concepts/policy/pod-security-policy/).
### Encrypt secrets at rest
In general, the etcd database will contain any information accessible via the Kubernetes API
and may grant an attacker significant visibility into the state of your cluster. Always encrypt
your backups using a well reviewed backup and encryption solution, and consider using full disk
encryption where possible.
Kubernetes 1.7 contains [encryption at rest](/docs/tasks/administer-cluster/encrypt-data/), an alpha feature that will encrypt `Secret` resources in etcd, preventing
parties that gain access to your etcd backups from viewing the content of those secrets. While
this feature is currently experimental, it may offer an additional level of defense when backups
are not encrypted or an attacker gains read access to etcd.
### Receiving alerts for security updates and reporting vulnerabilities
Join the [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce)
group for emails about security announcements. See the [security reporting](/security/)
page for more on how to report vulnerabilities.
{% endcapture %}
{% include templates/task.md %}