Merge pull request #20785 from kubernetes/dev-1.19

Official 1.19 Release Docs

Author: jimangel

config.toml

@@ -115,10 +115,10 @@ time_format_blog = "Monday, January 02, 2006"
 description = "Production-Grade Container Orchestration"
 showedit = true
 
-latest = "v1.18"
+latest = "v1.19"
 
-fullversion = "v1.18.0"
-version = "v1.18"
+fullversion = "v1.19.0"
+version = "v1.19"
 githubbranch = "master"
 docsbranch = "master"
 deprecated = false
@@ -157,39 +157,40 @@ js = [
 ]
 
 [[params.versions]]
-fullversion = "v1.18.0"
+fullversion = "v1.19.0"
+version = "v1.19"
+githubbranch = "v1.19.0"
+docsbranch = "master"
+url = "https://kubernetes.io"
+
+[[params.versions]]
+fullversion = "v1.18.8"
 version = "v1.18"
-githubbranch = "v1.18.0"
+githubbranch = "v1.18.8"
 docsbranch = "release-1.18"
-url = "https://kubernetes.io"
+url = "https://v1-18.docs.kubernetes.io"
 
 [[params.versions]]
-fullversion = "v1.17.4"
+fullversion = "v1.17.11"
 version = "v1.17"
-githubbranch = "v1.17.4"
+githubbranch = "v1.17.11"
 docsbranch = "release-1.17"
 url = "https://v1-17.docs.kubernetes.io"
 
 [[params.versions]]
-fullversion = "v1.16.8"
+fullversion = "v1.16.14"
 version = "v1.16"
-githubbranch = "v1.16.8"
+githubbranch = "v1.16.14"
 docsbranch = "release-1.16"
 url = "https://v1-16.docs.kubernetes.io"
 
 [[params.versions]]
-fullversion = "v1.15.11"
+fullversion = "v1.15.12"
 version = "v1.15"
-githubbranch = "v1.15.11"
+githubbranch = "v1.15.12"
 docsbranch = "release-1.15"
 url = "https://v1-15.docs.kubernetes.io"
 
-[[params.versions]]
-fullversion = "v1.14.10"
-version = "v1.14"
-githubbranch = "v1.14.10"
-docsbranch = "release-1.14"
-url = "https://v1-14.docs.kubernetes.io"
 
 # User interface configuration
 [params.ui]

content/en/docs/concepts/cluster-administration/logging.md

@@ -9,7 +9,7 @@ weight: 60
 
 <!-- overview -->
 
-Application and systems logs can help you understand what is happening inside your cluster. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism; as such, most container engines are likewise designed to support some kind of logging. The easiest and most embraced logging method for containerized applications is to write to the standard output and standard error streams.
+Application logs can help you understand what is happening inside your application. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism; as such, most container engines are likewise designed to support some kind of logging. The easiest and most embraced logging method for containerized applications is to write to the standard output and standard error streams.
 
 However, the native functionality provided by a container engine or runtime is usually not enough for a complete logging solution. For example, if a container crashes, a pod is evicted, or a node dies, you'll usually still want to access your application's logs. As such, logs should have a separate storage and lifecycle independent of nodes, pods, or containers. This concept is called _cluster-level-logging_. Cluster-level logging requires a separate backend to store, analyze, and query logs. Kubernetes provides no native storage solution for log data, but you can integrate many existing logging solutions into your Kubernetes cluster.
 
@@ -94,6 +94,7 @@ the rotation and there are two files, one 10MB in size and one empty,
 `kubectl logs` will return an empty response.
 {{< /note >}}
 
+[cosConfigureHelper]: https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh
 ### System component logs
 
 There are two types of system components: those that run in a container and those

content/en/docs/concepts/cluster-administration/system-logs.md

@@ -0,0 +1,119 @@
+---
+reviewers:
+- dims
+- 44past4
+title: System Logs
+content_type: concept
+weight: 60
+---
+
+<!-- overview -->
+
+System component logs record events happening in cluster, which can be very useful for debugging.
+You can configure log verbosity to see more or less detail.
+Logs can be as coarse-grained as showing errors within a component, or as fine-grained as showing step-by-step traces of events (like HTTP access logs, pod state changes, controller actions, or scheduler decisions).
+
+<!-- body -->
+
+## Klog
+
+klog is the Kubernetes logging library. [klog](https://github.com/kubernetes/klog)
+generates log messages for the Kubernetes system components.
+
+For more information about klog configuration, see the [Command line tool reference](/docs/reference/command-line-tools-reference/).
+
+An example of the klog native format:
+```
+I1025 00:15:15.525108       1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756]
+```
+
+### Structured Logging
+
+{{< feature-state for_k8s_version="v1.19" state="alpha" >}}
+
+{{<warning>}}
+Migration to structured log messages is an ongoing process. Not all log messages are structured in this version. When parsing log files, you must also handle unstructured log messages.
+
+Log formatting and value serialization are subject to change.
+{{< /warning>}}
+
+Structured logging is a effort to introduce a uniform structure in log messages allowing for easy extraction of information, making logs easier and cheaper to store and process.
+New message format is backward compatible and enabled by default.
+
+Format of structured logs:
+```
+<klog header> "<message>" <key1>="<value1>" <key2>="<value2>" ...
+```
+
+Example:
+```
+I1025 00:15:15.525108       1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready"
+```
+
+
+### JSON log format
+
+{{< feature-state for_k8s_version="v1.19" state="alpha" >}}
+
+{{<warning >}}
+JSON output does not support many standard klog flags. For list of unsupported klog flags, see the [Command line tool reference](/docs/reference/command-line-tools-reference/).
+
+Not all logs are guaranteed to be written in JSON format (for example, during process start). If you intend to parse logs, make sure you can handle log lines that are not JSON as well.
+
+Field names and JSON serialization are subject to change.
+{{< /warning >}}
+
+The `--logging-format=json` flag changes the format of logs from klog native format to JSON format.
+Example of JSON log format (pretty printed):
+```json
+{
+   "ts": 1580306777.04728,
+   "v": 4,
+   "msg": "Pod status updated",
+   "pod":{
+      "name": "nginx-1",
+      "namespace": "default"
+   },
+   "status": "ready"
+}
+```
+
+Keys with special meaning:
+* `ts` - timestamp as Unix time (required, float)
+* `v` - verbosity (required, int, default 0)
+* `err` - error string (optional, string)
+* `msg` - message (required, string)
+
+
+List of components currently supporting JSON format:
+* {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}}
+* {{< glossary_tooltip term_id="kube-apiserver" text="kube-apiserver" >}}
+* {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}}
+* {{< glossary_tooltip term_id="kubelet" text="kubelet" >}}
+
+### Log verbosity level
+
+The `-v` flag controls log verbosity. Increasing the value increases the number of logged events. Decreasing the value decreases the number of logged events.
+Increasing verbosity settings logs increasingly less severe events. A verbosity setting of 0 logs only critical events.
+
+### Log location
+
+There are two types of system components: those that run in a container and those
+that do not run in a container. For example:
+
+* The Kubernetes scheduler and kube-proxy run in a container.
+* The kubelet and container runtime, for example Docker, do not run in containers.
+
+On machines with systemd, the kubelet and container runtime write to journald.
+Otherwise, they write to `.log` files in the `/var/log` directory.
+System components inside containers always write to `.log` files in the `/var/log` directory,
+bypassing the default logging mechanism.
+Similar to the container logs, you should rotate system component logs in the `/var/log` directory.
+In Kubernetes clusters created by the `kube-up.sh` script, log rotation is configured by the `logrotate` tool.
+The `logrotate` tool rotates logs daily, or once the log size is greater than 100MB.
+
+## {{% heading "whatsnext" %}}
+
+* Read about the [Kubernetes Logging Architecture](/docs/concepts/cluster-administration/logging/)
+* Read about [Structured Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging)
+* Read about the [Conventions for logging severity](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md)

content/en/docs/concepts/cluster-administration/monitoring.md renamed to content/en/docs/concepts/cluster-administration/system-metrics.md

@@ -1,22 +1,19 @@
 ---
-title: Metrics For The Kubernetes Control Plane
+title: Metrics For Kubernetes System Components
 reviewers:
 - brancz
 - logicalhan
 - RainbowMango
 content_type: concept
 weight: 60
-aliases:
-- controller-metrics.md
 ---
 
 <!-- overview -->
 
 System component metrics can give a better look into what is happening inside them. Metrics are particularly useful for building dashboards and alerts.
 
-Metrics in Kubernetes control plane are emitted in [prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/) and are human readable.
-
-
+Kubernetes components emit metrics in [Prometheus format](https://prometheus.io/docs/instrumenting/exposition_formats/).
+This format is structured plain text, designed so that people and machines can both read it.
 
 <!-- body -->
 
@@ -39,7 +36,7 @@ Note that {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} also exposes
 
 If your cluster uses {{< glossary_tooltip term_id="rbac" text="RBAC" >}}, reading metrics requires authorization via a user, group or ServiceAccount with a ClusterRole that allows accessing `/metrics`.
 For example:
-```
+```yaml
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -101,6 +98,14 @@ Take metric `A` as an example, here assumed that `A` is deprecated in 1.n. Accor
 
 If you're upgrading from release `1.12` to `1.13`, but still depend on a metric `A` deprecated in `1.12`, you should set hidden metrics via command line: `--show-hidden-metrics=1.12` and remember to remove this metric dependency before upgrading to `1.14`
 
+## Disable accelerator metrics
+
+The kubelet collects accelerator metrics through cAdvisor. To collect these metrics, for accelerators like NVIDIA GPUs, kubelet held an open handle on the driver. This meant that in order to perform infrastructure changes (for example, updating the driver), a cluster administrator needed to stop the kubelet agent.
+
+The responsibility for collecting accelerator metrics now belongs to the vendor rather than the kubelet. Vendors must provide a container that collects metrics and exposes them to the metrics service (for example, Prometheus).
+
+The [`DisableAcceleratorUsageMetrics` feature gate](/docs/references/command-line-tools-reference/feature-gate.md#feature-gates-for-alpha-or-beta-features:~:text= DisableAcceleratorUsageMetrics,-false) disables metrics collected by the kubelet, with a [timeline for enabling this feature by default](https://github.com/kubernetes/enhancements/tree/411e51027db842355bd489691af897afc1a41a5e/keps/sig-node/1867-disable-accelerator-usage-metrics#graduation-criteria).
+
 ## Component metrics
 
 ### kube-controller-manager metrics
@@ -124,8 +129,6 @@ cloudprovider_gce_api_request_duration_seconds { request = "detach_disk"}
 cloudprovider_gce_api_request_duration_seconds { request = "list_disk"}
 ```
 
-
-
 ## {{% heading "whatsnext" %}}
 
 * Read about the [Prometheus text format](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md#text-based-format) for metrics

content/en/docs/concepts/configuration/configmap.md

@@ -213,9 +213,9 @@ when new keys are projected to the Pod can be as long as the kubelet sync period
 propagation delay, where the cache propagation delay depends on the chosen cache type
 (it equals to watch propagation delay, ttl of cache, or zero correspondingly).
 
-{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
+{{< feature-state for_k8s_version="v1.19" state="beta" >}}
 
-The Kubernetes alpha feature _Immutable Secrets and ConfigMaps_ provides an option to set
+The Kubernetes beta feature _Immutable Secrets and ConfigMaps_ provides an option to set
 individual Secrets and ConfigMaps as immutable. For clusters that extensively use ConfigMaps
 (at least tens of thousands of unique ConfigMap to Pod mounts), preventing changes to their
 data has the following advantages:

content/en/docs/concepts/configuration/pod-priority-preemption.md

@@ -51,40 +51,6 @@ Kubernetes already ships with two PriorityClasses:
 These are common classes and are used to [ensure that critical components are always scheduled first](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/).
 {{< /note >}}
 
-## How to disable preemption
-
-{{< caution >}}
-Critical pods rely on scheduler preemption to be scheduled when a cluster
-is under resource pressure. For this reason, it is not recommended to
-disable preemption.
-{{< /caution >}}
-
-{{< note >}}
-In Kubernetes 1.15 and later, if the feature `NonPreemptingPriority` is enabled,
-PriorityClasses have the option to set `preemptionPolicy: Never`.
-This will prevent pods of that PriorityClass from preempting other pods.
-{{< /note >}}
-
-Preemption is controlled by a kube-scheduler flag `disablePreemption`, which is
-set to `false` by default.
-If you want to disable preemption despite the above note, you can set
-`disablePreemption` to `true`.
-
-This option is available in component configs only and is not available in
-old-style command line options. Below is a sample component config to disable
-preemption:
-
-```yaml
-apiVersion: kubescheduler.config.k8s.io/v1alpha1
-kind: KubeSchedulerConfiguration
-algorithmSource:
-  provider: DefaultProvider
-
-...
-
-disablePreemption: true
-```
-
 ## PriorityClass
 
 A PriorityClass is a non-namespaced object that defines a mapping from a
@@ -138,7 +104,7 @@ description: "This priority class should be used for XYZ service pods only."
 
 ## Non-preempting PriorityClass {#non-preempting-priority-class}
 
-{{< feature-state for_k8s_version="v1.15" state="alpha" >}}
+{{< feature-state for_k8s_version="v1.19" state="beta" >}}
 
 Pods with `PreemptionPolicy: Never` will be placed in the scheduling queue
 ahead of lower-priority pods,
@@ -162,10 +128,6 @@ which will allow pods of that PriorityClass to preempt lower-priority pods
 If `PreemptionPolicy` is set to `Never`,
 pods in that PriorityClass will be non-preempting.
 
-The use of the `PreemptionPolicy` field requires the `NonPreemptingPriority`
-[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
-to be enabled.
-
 An example use case is for data science workloads.
 A user may submit a job that they want to be prioritized above other workloads,
 but do not wish to discard existing work by preempting running pods.

content/en/docs/concepts/configuration/secret.md

@@ -717,9 +717,9 @@ A container using a Secret as a
 Secret updates.
 {{< /note >}}
 
-{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
+{{< feature-state for_k8s_version="v1.19" state="beta" >}}
 
-The Kubernetes alpha feature _Immutable Secrets and ConfigMaps_ provides an option to set
+The Kubernetes beta feature _Immutable Secrets and ConfigMaps_ provides an option to set
 individual Secrets and ConfigMaps as immutable. For clusters that extensively use Secrets
 (at least tens of thousands of unique Secret to Pod mounts), preventing changes to their
 data has the following advantages: