Merge remote-tracking branch 'upstream/master' into dev-1.19

2020-07-27 19:10:42 -04:00
parent c5a2bb2edd e1485cd5d7
commit e2a861c2f9
556 changed files with 9174 additions and 6944 deletions
@@ -677,9 +677,6 @@ for more information.
 This admission controller acts on creation and modification of the pod and determines if it should be admitted
 based on the requested security context and the available Pod Security Policies.

-For Kubernetes < 1.6.0, the API Server must enable the extensions/v1beta1/podsecuritypolicy API
-extensions group (`--runtime-config=extensions/v1beta1/podsecuritypolicy=true`).
-
 See also [Pod Security Policy documentation](/docs/concepts/policy/pod-security-policy/)
 for more information.

@@ -26,7 +26,7 @@ even a file with a list of usernames and passwords. In this regard, _Kubernetes
 does not have objects which represent normal user accounts._ Normal users
 cannot be added to a cluster through an API call.

-Even though normal user cannot be added via an API call, but any user that presents a valid certificate signed by the cluster’s certificate authority (CA) is considered authenticated. In this configuration, Kubernetes determines the username from the common name field in the ‘subject’ of the cert (e.g., “/CN=bob”). From there, the role based access control (RBAC) sub-system would determine whether the user is authorized to perform a specific operation a resource. You can refer to [creating user certificate request](/docs/reference/access-authn-authz/certificate-signing-requests/#user-csr) for more details about this.
+Even though normal user cannot be added via an API call, but any user that presents a valid certificate signed by the cluster’s certificate authority (CA) is considered authenticated. In this configuration, Kubernetes determines the username from the common name field in the ‘subject’ of the cert (e.g., “/CN=bob”). From there, the role based access control (RBAC) sub-system would determine whether the user is authorized to perform a specific operation on a resource. You can refer to [creating user certificate request](/docs/reference/access-authn-authz/certificate-signing-requests/#user-csr) for more details about this.

 In contrast, service accounts are users managed by the Kubernetes API. They are
 bound to specific namespaces, and created automatically by the API server or
@@ -997,7 +997,7 @@ See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels for
 ### Matching requests: matchPolicy

 API servers can make objects available via multiple API groups or versions.
-For example, the Kubernetes API server allows creating and modifying `Deployment` objects
+For example, the Kubernetes API server may allow creating and modifying `Deployment` objects
 via `extensions/v1beta1`, `apps/v1beta1`, `apps/v1beta2`, and `apps/v1` APIs.

 For example, if a webhook only specified a rule for some API groups/versions (like `apiGroups:["apps"], apiVersions:["v1","v1beta1"]`),
@@ -606,12 +606,15 @@ either do not manually edit the role, or disable auto-reconciliation.

 <table>
 <caption>Kubernetes RBAC API discovery roles</caption>
-<colgroup><col width="25%" /><col width="25%" /><col /></colgroup>
+<colgroup><col style="width: 25%;" /><col style="width: 25%;" /><col /></colgroup>
+<thead>
 <tr>
 <th>Default ClusterRole</th>
 <th>Default ClusterRoleBinding</th>
 <th>Description</th>
 </tr>
+</thead>
+<tbody>
 <tr>
 <td><b>system:basic-user</b></td>
 <td><b>system:authenticated</b> group</td>
@@ -627,6 +630,7 @@ either do not manually edit the role, or disable auto-reconciliation.
 <td><b>system:authenticated</b> and <b>system:unauthenticated</b> groups</td>
 <td>Allows read-only access to non-sensitive information about the cluster. Introduced in Kubernetes v1.14.</td>
 </tr>
+</tbody>
 </table>

 ### User-facing roles
@@ -649,12 +653,15 @@ metadata:
 ```

 <table>
-<colgroup><col width="25%"><col width="25%"><col></colgroup>
+<colgroup><col style="width: 25%;" /><col style="width: 25%;" /><col /></colgroup>
+<thead>
 <tr>
 <th>Default ClusterRole</th>
 <th>Default ClusterRoleBinding</th>
 <th>Description</th>
 </tr>
+</thead>
+<tbody>
 <tr>
 <td><b>cluster-admin</b></td>
 <td><b>system:masters</b> group</td>
@@ -691,17 +698,21 @@ the contents of Secrets enables access to ServiceAccount credentials
 in the namespace, which would allow API access as any ServiceAccount
 in the namespace (a form of privilege escalation).</td>
 </tr>
+</tbody>
 </table>

 ### Core component roles

 <table>
-<colgroup><col width="25%"><col width="25%"><col></colgroup>
+<colgroup><col style="width: 25%;" /><col style="width: 25%;" /><col /></colgroup>
+<thead>
 <tr>
 <th>Default ClusterRole</th>
 <th>Default ClusterRoleBinding</th>
 <th>Description</th>
 </tr>
+</thead>
+<tbody>
 <tr>
 <td><b>system:kube-scheduler</b></td>
 <td><b>system:kube-scheduler</b> user</td>
@@ -733,17 +744,21 @@ The <tt>system:node</tt> role only exists for compatibility with Kubernetes clus
 <td><b>system:kube-proxy</b> user</td>
 <td>Allows access to the resources required by the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}} component.</td>
 </tr>
+</tbody>
 </table>

 ### Other component roles

 <table>
-<colgroup><col width="25%"><col width="25%"><col></colgroup>
+<colgroup><col style="width: 25%;" /><col style="width: 25%;" /><col /></colgroup>
+<thead>
 <tr>
 <th>Default ClusterRole</th>
 <th>Default ClusterRoleBinding</th>
 <th>Description</th>
 </tr>
+</thead>
+<tbody>
 <tr>
 <td><b>system:auth-delegator</b></td>
 <td>None</td>
@@ -786,6 +801,7 @@ This is commonly used by add-on API servers for unified authentication and autho
 <td>None</td>
 <td>Allows access to the resources required by most <a href="/docs/concepts/storage/persistent-volumes/#provisioner">dynamic volume provisioners</a>.</td>
 </tr>
+<tbody>
 </table>

 ### Roles for built-in controllers {#controller-roles}
@@ -2,7 +2,7 @@
 title: Pod
 id: pod
 date: 2018-04-12
-full_link: /docs/concepts/workloads/pods/pod-overview/
+full_link: /docs/concepts/workloads/pods/
 short_description: >
  A Pod represents a set of running containers in your cluster.

@@ -33,7 +33,7 @@ if you are writing an application using the Kubernetes API.

 To eliminate fields or restructure resource representations, Kubernetes supports
 multiple API versions, each at a different API path. For example: `/api/v1` or
-`/apis/extensions/v1beta1`.
+`/apis/rbac.authorization.k8s.io/v1alpha1`.

 The version is set at the API level rather than at the resource or field level to:

@@ -106,10 +106,3 @@ When you enable or disable groups or resources, you need to restart the apiserve
 to pick up the `--runtime-config` changes.
 {{< /note >}}

-## Enabling specific resources in the extensions/v1beta1 group
-
-DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies and ReplicaSets in the `extensions/v1beta1` API group are disabled by default.
-For example: to enable deployments and daemonsets, set
-`--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true`.
-
-{{< note >}}Individual resource enablement/disablement is only supported in the `extensions/v1beta1` API group for legacy reasons.{{< /note >}}
@@ -0,0 +1,103 @@
+---
+title: Kubernetes API health endpoints
+reviewers:
+- logicalhan
+content_type: concept
+weight: 50
+---
+
+<!-- overview -->
+The Kubernetes {{< glossary_tooltip term_id="kube-apiserver" text="API server" >}} provides API endpoints to indicate the current status of the API server.
+This page describes these API endpoints and explains how you can use them.
+
+<!-- body -->
+
+## API endpoints for health
+
+The Kubernetes API server provides 3 API endpoints (`healthz`, `livez` and `readyz`) to indicate the current status of the API server.
+The `healthz` endpoint is deprecated (since Kubernetes v1.16), and you should use the more specific `livez` and `readyz` endpoints instead.
+The `livez` endpoint can be used with the `--livez-grace-period` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) to specify the startup duration.
+For a graceful shutdown you can specify the `--shutdown-delay-duration` [flag](/docs/reference/command-line-tools-reference/kube-apiserver) with the `/readyz` endpoint.
+Machines that check the `health`/`livez`/`readyz` of the API server should rely on the HTTP status code.
+A status code `200` indicates the the API server is `healthy`/`live`/`ready`, depending of the called endpoint.
+The more verbose options shown below are intended to be used by human operators to debug their cluster or specially the state of the API server.
+
+The following examples will show how you can interact with the health API endpoints.
+
+For all endpoints you can use the `verbose` parameter to print out the checks and their status.
+This can be useful for a human operator to debug the current status of the Api server, it is not intended to be consumed by a machine:
+
+    ```shell
+    curl -k https://localhost:6443/livez?verbose
+    ```
+
+or from a remote host with authentication:
+
+    ```shell
+    kubectl get --raw='/readyz?verbose'
+    ```
+
+The output will look like this:
+
+    [+]ping ok
+    [+]log ok
+    [+]etcd ok
+    [+]poststarthook/start-kube-apiserver-admission-initializer ok
+    [+]poststarthook/generic-apiserver-start-informers ok
+    [+]poststarthook/start-apiextensions-informers ok
+    [+]poststarthook/start-apiextensions-controllers ok
+    [+]poststarthook/crd-informer-synced ok
+    [+]poststarthook/bootstrap-controller ok
+    [+]poststarthook/rbac/bootstrap-roles ok
+    [+]poststarthook/scheduling/bootstrap-system-priority-classes ok
+    [+]poststarthook/start-cluster-authentication-info-controller ok
+    [+]poststarthook/start-kube-aggregator-informers ok
+    [+]poststarthook/apiservice-registration-controller ok
+    [+]poststarthook/apiservice-status-available-controller ok
+    [+]poststarthook/kube-apiserver-autoregistration ok
+    [+]autoregister-completion ok
+    [+]poststarthook/apiservice-openapi-controller ok
+    healthz check passed
+
+The Kubernetes API server also supports to exclude specific checks.
+The query parameters can also be combined like in this example:
+
+    ```shell
+    curl -k 'https://localhost:6443/readyz?verbose&exclude=etcd'
+    ```
+
+The output show that the `etcd` check is excluded:
+
+    [+]ping ok
+    [+]log ok
+    [+]etcd excluded: ok
+    [+]poststarthook/start-kube-apiserver-admission-initializer ok
+    [+]poststarthook/generic-apiserver-start-informers ok
+    [+]poststarthook/start-apiextensions-informers ok
+    [+]poststarthook/start-apiextensions-controllers ok
+    [+]poststarthook/crd-informer-synced ok
+    [+]poststarthook/bootstrap-controller ok
+    [+]poststarthook/rbac/bootstrap-roles ok
+    [+]poststarthook/scheduling/bootstrap-system-priority-classes ok
+    [+]poststarthook/start-cluster-authentication-info-controller ok
+    [+]poststarthook/start-kube-aggregator-informers ok
+    [+]poststarthook/apiservice-registration-controller ok
+    [+]poststarthook/apiservice-status-available-controller ok
+    [+]poststarthook/kube-apiserver-autoregistration ok
+    [+]autoregister-completion ok
+    [+]poststarthook/apiservice-openapi-controller ok
+    [+]shutdown ok
+    healthz check passed
+
+## Individual health checks
+
+{{< feature-state state="alpha" >}}
+
+Each individual health check exposes an http endpoint and could can be checked individually.
+The schema for the individual health checks is `/livez/<healthcheck-name>` where `livez` and `readyz` and be used to indicate if you want to check thee liveness or the readiness of the API server.
+The `<healthcheck-name>` path can be discovered using the `verbose` flag from above and take the path between `[+]` and `ok`.
+These individual health checks should not be consumed by machines but can be helpful for a human operator to debug a system:
+
+    ```shell
+    curl -k https://localhost:6443/livez/etcd
+    ```