Merge branch 'master' of https://github.com/kubernetes/kubernetes.github.io into release-1.6

* 'master' of https://github.com/kubernetes/kubernetes.github.io: Revert "Updated description for kubeadm init --kubernetes-version" Updated description for kubeadm init --kubernetes-version Remove details about where authenticator is implemented replace petset with statefulsets Updated result of command replace argumment with argument Highlight some keyworks in garbage-collection.md. Fixed typos in persistent volume index.md Remove reference to port-forward to services add an example fix typo Fix typo in concepts Parallel Jobs with a *work queue*: Add more options for self-registration. dedent yaml code blocks Add kubelet eviction in GC doc (#2484)
2017-02-21 12:43:53 -08:00
parent 7b17b51997 bd7607a066
commit 578123e106
12 changed files with 84 additions and 62 deletions
@@ -85,9 +85,9 @@ See [APPENDIX](#appendix) for how to generate a client cert.
 The API server reads bearer tokens from a file when given the `--token-auth-file=SOMEFILE` option on the command line.  Currently, tokens last indefinitely, and the token list cannot be
 changed without restarting API server.

-The token file format is implemented in `plugin/pkg/auth/authenticator/token/tokenfile/...`
-and is a csv file with a minimum of 3 columns: token, user name, user uid, followed by
-optional group names. Note, if you have more than one group the column must be double quoted e.g.
+The token file is a csv file with a minimum of 3 columns: token, user name, user uid,
+followed by optional group names. Note, if you have more than one group the column must be
+double quoted e.g.

 ```conf
 token,user,uid,"group1,group2,group3"
@@ -115,9 +115,9 @@ and the password cannot be changed without restarting API server. Note that basi
 authentication is currently supported for convenience while we finish making the
 more secure modes described above easier to use.

-The basic auth file format is implemented in `plugin/pkg/auth/authenticator/password/passwordfile/...`
-and is a csv file with a minimum of 3 columns: password, user name, user id, followed by
-optional group names. Note, if you have more than one group the column must be double quoted e.g.
+The basic auth file is a csv file with a minimum of 3 columns: password,
+user name, user id, followed by optional group names. Note, if you have more than
+one group the column must be double quoted e.g.

 ```conf
 password,user,uid,"group1,group2,group3"
@@ -24,9 +24,9 @@ threshold has been met.
 ### Container Collection

 The policy for garbage collecting containers considers three user-defined variables. `MinAge` is the minimum age at which a container can be garbage collected. `MaxPerPodContainer` is the maximum number of dead containers any single
-pod (UID, container name) pair is allowed to have. `MaxContainers` is the maximum number of total dead containers. These variables can be individually disabled by setting 'MinAge' to zero and setting 'MaxPerPodContainer' and 'MaxContainers' respectively to less than zero.
+pod (UID, container name) pair is allowed to have. `MaxContainers` is the maximum number of total dead containers. These variables can be individually disabled by setting `MinAge` to zero and setting `MaxPerPodContainer` and `MaxContainers` respectively to less than zero.

-Kubelet will act on containers that are unidentified, deleted, or outside of the boundaries set by the previously mentioned flags. The oldest containers will generally be removed first. 'MaxPerPodContainer' and 'MaxContainer' may potentially conflict with each other in situations where retaining the maximum number of containers per pod ('MaxPerPodContainer') would go outside the allowable range of global dead containers ('MaxContainers'). 'MaxPerPodContainer' would be adjusted in this situation: A worst case scenario would be to downgrade 'MaxPerPodContainer' to 1 and evict the oldest containers. Additionally, containers owned by pods that have been deleted are removed once they are older than `MinAge`.
+Kubelet will act on containers that are unidentified, deleted, or outside of the boundaries set by the previously mentioned flags. The oldest containers will generally be removed first. `MaxPerPodContainer` and `MaxContainer` may potentially conflict with each other in situations where retaining the maximum number of containers per pod (`MaxPerPodContainer`) would go outside the allowable range of global dead containers (`MaxContainers`). `MaxPerPodContainer` would be adjusted in this situation: A worst case scenario would be to downgrade `MaxPerPodContainer` to 1 and evict the oldest containers. Additionally, containers owned by pods that have been deleted are removed once they are older than `MinAge`.

 Containers that are not managed by kubelet are not subject to container garbage collection.

@@ -42,15 +42,34 @@ to free. Default is 80%.
 We also allow users to customize garbage collection policy through the following kubelet flags:

 1. `minimum-container-ttl-duration`, minimum age for a finished container before it is
-garbage collected. Default is 1 minute.
+garbage collected. Default is 0 minute, which means any finished container will be garbaged collected.
 2. `maximum-dead-containers-per-container`, maximum number of old instances to retain
-per container. Default is 2.
+per container. Default is 1.
 3. `maximum-dead-containers`, maximum number of old instances of containers to retain globally.
-Default is 100.
+Default is -1, which means there is no global limit.

 Containers can potentially be garbage collected before their usefulness has expired. These containers
 can contain logs and other data that can be useful for troubleshooting. A sufficiently large value for
-`maximum-dead-containers-per-container` is highly recommended to allow at least 2 dead containers to be
+`maximum-dead-containers-per-container` is highly recommended to allow at least 1 dead container to be
 retained per expected container. A higher value for `maximum-dead-containers` is also recommended for a
 similar reason.
 See [this issue](https://github.com/kubernetes/kubernetes/issues/13287) for more details.
+
+
+### Deprecation
+
+Some kubelet Garbage Collection features in this doc will be replaced by kubelet eviction in the future.
+
+Including:
+
+| Existing Flag | New Flag | Rationale |
+| ------------- | -------- | --------- |
+| `--image-gc-high-threshold` | `--eviction-hard` or `eviction-soft` | existing eviction signals can trigger image garbage collection |
+| `--image-gc-low-threshold` | `--eviction-minimum-reclaim` | eviction reclaims achieve the same behavior |
+| `--maximum-dead-containers` | | deprecated once old logs are stored outside of container's context |
+| `--maximum-dead-containers-per-container` | | deprecated once old logs are stored outside of container's context |
+| `--minimum-container-ttl-duration` | | deprecated once old logs are stored outside of container's context |
+| `--low-diskspace-threshold-mb` | `--eviction-hard` or `eviction-soft` | eviction generalizes disk thresholds to other resources |
+| `--outofdisk-transition-frequency` | `--eviction-pressure-transition-period` | eviction generalizes disk pressure transition to other resources |
+
+See [kubelet eviction design doc](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/kubelet-eviction.md) for more details.
@@ -181,49 +181,49 @@ available as configuration file options.

 ### Sample Master Configuration

-    ```yaml
-    apiVersion: kubeadm.k8s.io/v1alpha1
-    kind: MasterConfiguration
-    api:
-      advertiseAddresses:
-      - <address1|string>
-      - <address2|string>
-      bindPort: <int>
-      externalDNSNames:
-      - <dnsname1|string>
-      - <dnsname2|string>
-    authorizationMode: <string>
-    cloudProvider: <string>
-    discovery:
-      bindPort: <int>
-    etcd:
-      endpoints:
-      - <endpoint1|string>
-      - <endpoint2|string>
-      caFile: <path|string>
-      certFile: <path|string>
-      keyFile: <path|string>
-    kubernetesVersion: <string>
-    networking:
-      dnsDomain: <string>
-      serviceSubnet: <cidr>
-      podSubnet: <cidr>
-    secrets:
-      givenToken: <token|string>
-    ```
+```yaml
+apiVersion: kubeadm.k8s.io/v1alpha1
+kind: MasterConfiguration
+api:
+  advertiseAddresses:
+  - <address1|string>
+  - <address2|string>
+  bindPort: <int>
+  externalDNSNames:
+  - <dnsname1|string>
+  - <dnsname2|string>
+authorizationMode: <string>
+cloudProvider: <string>
+discovery:
+  bindPort: <int>
+etcd:
+  endpoints:
+  - <endpoint1|string>
+  - <endpoint2|string>
+  caFile: <path|string>
+  certFile: <path|string>
+  keyFile: <path|string>
+kubernetesVersion: <string>
+networking:
+  dnsDomain: <string>
+  serviceSubnet: <cidr>
+  podSubnet: <cidr>
+secrets:
+  givenToken: <token|string>
+```

 ### Sample Node Configuration

-    ```yaml
-    apiVersion: kubeadm.k8s.io/v1alpha1
-    kind: NodeConfiguration
-    apiPort: <int>
-    discoveryPort: <int>
-    masterAddresses:
-    - <master1>
-    secrets:
-      givenToken: <token|string>
-    ```
+```yaml
+apiVersion: kubeadm.k8s.io/v1alpha1
+kind: NodeConfiguration
+apiPort: <int>
+discoveryPort: <int>
+masterAddresses:
+- <master1>
+secrets:
+  givenToken: <token|string>
+```

 ## Automating kubeadm

@@ -49,7 +49,7 @@ The plugin requires a few things:

 * The standard CNI `bridge`, `lo` and `host-local` plugins are required, at minimum version 0.2.0. Kubenet will first search for them in `/opt/cni/bin`. Specify `network-plugin-dir` to supply additional search path. The first found match will take effect.
 * Kubelet must be run with the `--network-plugin=kubenet` argument to enable the plugin
-* Kubelet should also be run with the `--non-masquerade-cidr=<clusterCidr>` argumment to ensure traffic to IPs outside this range will use IP masquerade.
+* Kubelet should also be run with the `--non-masquerade-cidr=<clusterCidr>` argument to ensure traffic to IPs outside this range will use IP masquerade.
 * The node must be assigned an IP subnet through either the `--pod-cidr` kubelet command-line option or the `--allocate-node-cidrs=true --cluster-cidr=<cidr>` controller-manager command-line options.

 ### Customizing the MTU (with kubenet)
@@ -176,6 +176,9 @@ For self-registration, the kubelet is started with the following options:
  - `--kubeconfig=` - Path to credentials to authenticate itself to the apiserver.
  - `--cloud-provider=` - How to talk to a cloud provider to read metadata about itself.
  - `--register-node` - Automatically register with the API server.
+  - `--node-ip`   IP address of the node.
+  - `--node-labels` - Labels to add when registering the node in the cluster.
+  - `--node-status-update-frequency` - Specifies how often kubelet posts node status to master.

 Currently, any kubelet is authorized to create/modify any node resource, but in practice it only creates/modifies
 its own. (In the future, we plan to only allow a kubelet to modify its own node resource.)