Merge remote-tracking branch 'upstream/master' into dev-1.20
This commit is contained in:
Kristin Martin
@@ -163,10 +163,11 @@ storage classes and how to mark a storage class as default.
|
||||
### DefaultTolerationSeconds {#defaulttolerationseconds}
|
||||
|
||||
This admission controller sets the default forgiveness toleration for pods to tolerate
|
||||
the taints `notready:NoExecute` and `unreachable:NoExecute` for 5 minutes,
|
||||
if the pods don't already have toleration for taints
|
||||
`node.kubernetes.io/not-ready:NoExecute` or
|
||||
`node.alpha.kubernetes.io/unreachable:NoExecute`.
|
||||
the taints `notready:NoExecute` and `unreachable:NoExecute` based on the k8s-apiserver input parameters
|
||||
`default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` if the pods don't already
|
||||
have toleration for taints `node.kubernetes.io/not-ready:NoExecute` or
|
||||
`node.kubernetes.io/unreachable:NoExecute`.
|
||||
The default value for `default-not-ready-toleration-seconds` and `default-unreachable-toleration-seconds` is 5 minutes.
|
||||
|
||||
### DenyExecOnPrivileged {#denyexeconprivileged}
|
||||
|
||||
@@ -202,8 +203,6 @@ is recommended instead.
|
||||
This admission controller mitigates the problem where the API server gets flooded by
|
||||
event requests. The cluster admin can specify event rate limits by:
|
||||
|
||||
* Ensuring that `eventratelimit.admission.k8s.io/v1alpha1=true` is included in the
|
||||
`--runtime-config` flag for the API server;
|
||||
* Enabling the `EventRateLimit` admission controller;
|
||||
* Referencing an `EventRateLimit` configuration file from the file provided to the API
|
||||
server's command line flag `--admission-control-config-file`:
|
||||
|
||||
@@ -30,10 +30,10 @@ 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
|
||||
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
|
||||
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. For more details, refer to the normal users topic in
|
||||
[certificate request](/docs/reference/access-authn-authz/certificate-signing-requests/#normal-user)
|
||||
@@ -329,7 +329,7 @@ Kubernetes does not provide an OpenID Connect Identity Provider.
|
||||
You can use an existing public OpenID Connect Identity Provider (such as Google, or
|
||||
[others](https://connect2id.com/products/nimbus-oauth-openid-connect-sdk/openid-connect-providers)).
|
||||
Or, you can run your own Identity Provider, such as CoreOS [dex](https://github.com/coreos/dex),
|
||||
[Keycloak](https://github.com/keycloak/keycloak),
|
||||
[Keycloak](https://github.com/keycloak/keycloak),
|
||||
CloudFoundry [UAA](https://github.com/cloudfoundry/uaa), or
|
||||
Tremolo Security's [OpenUnison](https://github.com/tremolosecurity/openunison).
|
||||
|
||||
@@ -443,7 +443,7 @@ current-context: webhook
|
||||
contexts:
|
||||
- context:
|
||||
cluster: name-of-remote-authn-service
|
||||
user: name-of-api-sever
|
||||
user: name-of-api-server
|
||||
name: webhook
|
||||
```
|
||||
|
||||
|
||||
@@ -108,7 +108,6 @@ Kubernetes provides built-in signers that each have a well-known `signerName`:
|
||||
|
||||
1. `kubernetes.io/legacy-unknown`: has no guarantees for trust at all. Some distributions may honor these as client
|
||||
certs, but that behavior is not standard Kubernetes behavior.
|
||||
This signerName can only be requested in CertificateSigningRequests created via the `certificates.k8s.io/v1beta1` API version.
|
||||
Never auto-approved by {{< glossary_tooltip term_id="kube-controller-manager" >}}.
|
||||
1. Trust distribution: None. There is no standard trust or distribution for this signer in a Kubernetes cluster.
|
||||
1. Permitted subjects - any
|
||||
@@ -245,7 +244,7 @@ Create a CertificateSigningRequest and submit it to a Kubernetes Cluster via kub
|
||||
|
||||
```
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: certificates.k8s.io/v1beta1
|
||||
apiVersion: certificates.k8s.io/v1
|
||||
kind: CertificateSigningRequest
|
||||
metadata:
|
||||
name: john
|
||||
@@ -253,6 +252,7 @@ spec:
|
||||
groups:
|
||||
- system:authenticated
|
||||
request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ1ZqQ0NBVDRDQVFBd0VURVBNQTBHQTFVRUF3d0dZVzVuWld4aE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTByczhJTHRHdTYxakx2dHhWTTJSVlRWMDNHWlJTWWw0dWluVWo4RElaWjBOCnR2MUZtRVFSd3VoaUZsOFEzcWl0Qm0wMUFSMkNJVXBGd2ZzSjZ4MXF3ckJzVkhZbGlBNVhwRVpZM3ExcGswSDQKM3Z3aGJlK1o2MVNrVHF5SVBYUUwrTWM5T1Nsbm0xb0R2N0NtSkZNMUlMRVI3QTVGZnZKOEdFRjJ6dHBoaUlFMwpub1dtdHNZb3JuT2wzc2lHQ2ZGZzR4Zmd4eW8ybmlneFNVekl1bXNnVm9PM2ttT0x1RVF6cXpkakJ3TFJXbWlECklmMXBMWnoyalVnald4UkhCM1gyWnVVV1d1T09PZnpXM01LaE8ybHEvZi9DdS8wYk83c0x0MCt3U2ZMSU91TFcKcW90blZtRmxMMytqTy82WDNDKzBERHk5aUtwbXJjVDBnWGZLemE1dHJRSURBUUFCb0FBd0RRWUpLb1pJaHZjTgpBUUVMQlFBRGdnRUJBR05WdmVIOGR4ZzNvK21VeVRkbmFjVmQ1N24zSkExdnZEU1JWREkyQTZ1eXN3ZFp1L1BVCkkwZXpZWFV0RVNnSk1IRmQycVVNMjNuNVJsSXJ3R0xuUXFISUh5VStWWHhsdnZsRnpNOVpEWllSTmU3QlJvYXgKQVlEdUI5STZXT3FYbkFvczFqRmxNUG5NbFpqdU5kSGxpT1BjTU1oNndLaTZzZFhpVStHYTJ2RUVLY01jSVUyRgpvU2djUWdMYTk0aEpacGk3ZnNMdm1OQUxoT045UHdNMGM1dVJVejV4T0dGMUtCbWRSeEgvbUNOS2JKYjFRQm1HCkkwYitEUEdaTktXTU0xMzhIQXdoV0tkNjVoVHdYOWl4V3ZHMkh4TG1WQzg0L1BHT0tWQW9FNkpsYWFHdTlQVmkKdjlOSjVaZlZrcXdCd0hKbzZXdk9xVlA3SVFjZmg3d0drWm89Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
|
||||
signerName: kubernetes.io/kube-apiserver-client
|
||||
usages:
|
||||
- client auth
|
||||
EOF
|
||||
|
||||
@@ -46,7 +46,7 @@ This group and user name format match the identity created for each kubelet as p
|
||||
[kubelet TLS bootstrapping](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/).
|
||||
|
||||
The value of `<nodeName>` **must** match precisely the name of the node as registered by the kubelet. By default, this is the host name as provided by `hostname`, or overridden via the [kubelet option](/docs/reference/command-line-tools-reference/kubelet/) `--hostname-override`. However, when using the `--cloud-provider` kubelet option, the specific hostname may be determined by the cloud provider, ignoring the local `hostname` and the `--hostname-override` option.
|
||||
For specifics about how the kubelet determines the hostname, as well as cloud provider overrides, see the [kubelet options reference](/docs/reference/command-line-tools-reference/kubelet/) and the [cloud provider details](/docs/concepts/cluster-administration/cloud-providers/).
|
||||
For specifics about how the kubelet determines the hostname, see the [kubelet options reference](/docs/reference/command-line-tools-reference/kubelet/).
|
||||
|
||||
To enable the Node authorizer, start the apiserver with `--authorization-mode=Node`.
|
||||
|
||||
|
||||
@@ -891,6 +891,7 @@ rules:
|
||||
- apiGroups: ["rbac.authorization.k8s.io"]
|
||||
resources: ["clusterroles"]
|
||||
verbs: ["bind"]
|
||||
# omit resourceNames to allow binding any ClusterRole
|
||||
resourceNames: ["admin","edit","view"]
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
|
||||
@@ -425,7 +425,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
||||
- `CustomResourceWebhookConversion`: Enable webhook-based conversion
|
||||
on resources created from [CustomResourceDefinition](/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
|
||||
troubleshoot a running Pod.
|
||||
- `DisableAcceleratorUsageMetrics`: [Disable accelerator metrics collected by the kubelet](/docs/concepts/cluster-administration/monitoring.md).
|
||||
- `DisableAcceleratorUsageMetrics`: [Disable accelerator metrics collected by the kubelet](/docs/concepts/cluster-administration/system-metrics/).
|
||||
- `DevicePlugins`: Enable the [device-plugins](/docs/concepts/cluster-administration/device-plugins/)
|
||||
based resource provisioning on nodes.
|
||||
- `DefaultPodTopologySpread`: Enables the use of `PodTopologySpread` scheduling plugin to do
|
||||
@@ -477,9 +477,6 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
||||
- `LegacyNodeRoleBehavior`: When disabled, legacy behavior in service load balancers and node disruption will ignore the `node-role.kubernetes.io/master` label in favor of the feature-specific labels provided by `NodeDisruptionExclusion` and `ServiceNodeExclusion`.
|
||||
- `LocalStorageCapacityIsolation`: Enable the consumption of [local ephemeral storage](/docs/concepts/configuration/manage-compute-resources-container/) and also the `sizeLimit` property of an [emptyDir volume](/docs/concepts/storage/volumes/#emptydir).
|
||||
- `LocalStorageCapacityIsolationFSQuotaMonitoring`: When `LocalStorageCapacityIsolation` is enabled for [local ephemeral storage](/docs/concepts/configuration/manage-compute-resources-container/) and the backing filesystem for [emptyDir volumes](/docs/concepts/storage/volumes/#emptydir) supports project quotas and they are enabled, use project quotas to monitor [emptyDir volume](/docs/concepts/storage/volumes/#emptydir) storage consumption rather than filesystem walk for better performance and accuracy.
|
||||
[local ephemeral storage](/docs/concepts/configuration/manage-resources-containers/) and the backing filesystem for
|
||||
[emptyDir volumes](/docs/concepts/storage/volumes/#emptydir) supports project quotas and they are enabled, use project quotas to monitor
|
||||
[emptyDir volume](/docs/concepts/storage/volumes/#emptydir) storage consumption rather than filesystem walk for better performance and accuracy.
|
||||
- `MountContainers`: Enable using utility containers on host as the volume mounter.
|
||||
- `MountPropagation`: Enable sharing volume mounted by one container to other containers or pods.
|
||||
For more details, please see [mount propagation](/docs/concepts/storage/volumes/#mount-propagation).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -15,7 +15,7 @@ A piece of code that intercepts requests to the Kubernetes API server prior to p
|
||||
|
||||
<!--more-->
|
||||
|
||||
Admission controllers are configurable for the Kubernetes API server and may be “validating”, “mutating”, or
|
||||
Admission controllers are configurable for the Kubernetes API server and may be "validating", "mutating", or
|
||||
both. Any admission controller may reject the request. Mutating controllers may modify the objects they admit;
|
||||
validating controllers may not.
|
||||
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
title: Cloud Provider
|
||||
id: cloud-provider
|
||||
date: 2018-04-12
|
||||
full_link: /docs/concepts/cluster-administration/cloud-providers
|
||||
short_description: >
|
||||
An organization that offers a cloud computing platform.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ id: configmap
|
||||
date: 2018-04-12
|
||||
full_link: /docs/concepts/configuration/configmap/
|
||||
short_description: >
|
||||
An API object used to store non-confidential data in key-value pairs. Can be consumed as environment variables, command-line arguments, or configuraton files in a volume.
|
||||
An API object used to store non-confidential data in key-value pairs. Can be consumed as environment variables, command-line arguments, or configuration files in a volume.
|
||||
|
||||
aka:
|
||||
tags:
|
||||
|
||||
@@ -6,13 +6,13 @@ full_link: /docs/reference/generated/kubelet
|
||||
short_description: >
|
||||
An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.
|
||||
|
||||
aka:
|
||||
aka:
|
||||
tags:
|
||||
- fundamental
|
||||
- core-object
|
||||
---
|
||||
An agent that runs on each {{< glossary_tooltip text="node" term_id="node" >}} in the cluster. It makes sure that {{< glossary_tooltip text="containers" term_id="container" >}} are running in a {{< glossary_tooltip text="Pod" term_id="pod" >}}.
|
||||
|
||||
<!--more-->
|
||||
<!--more-->
|
||||
|
||||
The kubelet takes a set of PodSpecs that are provided through various mechanisms and ensures that the containers described in those PodSpecs are running and healthy. The kubelet doesn’t manage containers which were not created by Kubernetes.
|
||||
The kubelet takes a set of PodSpecs that are provided through various mechanisms and ensures that the containers described in those PodSpecs are running and healthy. The kubelet doesn't manage containers which were not created by Kubernetes.
|
||||
|
||||
@@ -6,14 +6,14 @@ full_link: /docs/concepts/architecture/nodes/
|
||||
short_description: >
|
||||
A node is a worker machine in Kubernetes.
|
||||
|
||||
aka:
|
||||
aka:
|
||||
tags:
|
||||
- fundamental
|
||||
---
|
||||
A node is a worker machine in Kubernetes.
|
||||
|
||||
<!--more-->
|
||||
<!--more-->
|
||||
|
||||
A worker node may be a VM or physical machine, depending on the cluster. It has local daemons or services necessary to run {{< glossary_tooltip text="Pods" term_id="pod" >}} and is managed by the control plane. The daemons on a node include {{< glossary_tooltip text="kubelet" term_id="kubelet" >}}, {{< glossary_tooltip text="kube-proxy" term_id="kube-proxy" >}}, and a container runtime implementing the {{< glossary_tooltip text="CRI" term_id="cri" >}} such as {{< glossary_tooltip term_id="docker" >}}.
|
||||
|
||||
In early Kubernetes versions, Nodes were called “Minions”.
|
||||
In early Kubernetes versions, Nodes were called "Minions".
|
||||
|
||||
@@ -14,8 +14,8 @@ tags:
|
||||
|
||||
<!--more-->
|
||||
|
||||
A platform developer may, for example, use [Custom Resources](/docs/concepts/extend-Kubernetes/api-extension/custom-resources/) or
|
||||
[Extend the Kubernetes API with the aggregation layer](/docs/concepts/extend-Kubernetes/api-extension/apiserver-aggregation/)
|
||||
A platform developer may, for example, use [Custom Resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/) or
|
||||
[Extend the Kubernetes API with the aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
|
||||
to add functionality to their instance of Kubernetes, specifically for their application.
|
||||
Some Platform Developers are also {{< glossary_tooltip text="contributors" term_id="contributor" >}} and
|
||||
develop extensions which are contributed to the Kubernetes community.
|
||||
|
||||
@@ -23,7 +23,7 @@ You can also subscribe to an RSS feed of the above using [this link](https://gro
|
||||
|
||||
## Report a Vulnerability
|
||||
|
||||
We’re extremely grateful for security researchers and users that report vulnerabilities to the Kubernetes Open Source Community. All reports are thoroughly investigated by a set of community volunteers.
|
||||
We're extremely grateful for security researchers and users that report vulnerabilities to the Kubernetes Open Source Community. All reports are thoroughly investigated by a set of community volunteers.
|
||||
|
||||
To make a report, submit your vulnerability to the [Kubernetes bug bounty program](https://hackerone.com/kubernetes). This allows triage and handling of the vulnerability with standardized response times.
|
||||
|
||||
|
||||
@@ -29,14 +29,14 @@ For `kubectl run` to satisfy infrastructure as code:
|
||||
* Check in the script for an image that is heavily parameterized.
|
||||
* Switch to configuration files checked into source control for features that are needed, but not expressible via `kubectl run` flags.
|
||||
|
||||
You can use the `--dry-run` flag to preview the object that would be sent to your cluster, without really submitting it.
|
||||
You can use the `--dry-run=client` flag to preview the object that would be sent to your cluster, without really submitting it.
|
||||
|
||||
{{< note >}}
|
||||
All `kubectl` generators are deprecated. See the Kubernetes v1.17 documentation for a [list](https://v1-17.docs.kubernetes.io/docs/reference/kubectl/conventions/#generators) of generators and how they were used.
|
||||
{{< /note >}}
|
||||
|
||||
#### Generators
|
||||
You can generate the following resources with a kubectl command, `kubectl create --dry-run -o yaml`:
|
||||
You can generate the following resources with a kubectl command, `kubectl create --dry-run=client -o yaml`:
|
||||
```
|
||||
clusterrole Create a ClusterRole.
|
||||
clusterrolebinding Create a ClusterRoleBinding for a particular ClusterRole.
|
||||
|
||||
@@ -42,6 +42,7 @@ kubectl create deployment --image=nginx nginx-app
|
||||
# add env to nginx-app
|
||||
kubectl set env deployment/nginx-app DOMAIN=cluster
|
||||
```
|
||||
```
|
||||
deployment.apps/nginx-app created
|
||||
```
|
||||
|
||||
@@ -52,7 +53,6 @@ kubectl set env deployment/nginx-app DOMAIN=cluster
|
||||
```
|
||||
deployment.apps/nginx-app env updated
|
||||
```
|
||||
deployment.apps/nginx-app env updated
|
||||
|
||||
{{< note >}}
|
||||
`kubectl` commands print the type and name of the resource created or mutated, which can then be used in subsequent commands. You can expose a new Service after a Deployment is created.
|
||||
|
||||
@@ -98,4 +98,16 @@ kubectl get pods -o=jsonpath="{range .items[*]}{.metadata.name}{\"\t\"}{.status.
|
||||
```
|
||||
{{< /note >}}
|
||||
|
||||
{{< note >}}
|
||||
|
||||
JSONPath regular expressions are not supported. If you want to match using regular expressions, you can use a tool such as `jq`.
|
||||
|
||||
```shell
|
||||
# kubectl does not support regular expressions for JSONpath output
|
||||
# The following command does not work
|
||||
kubectl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}'
|
||||
|
||||
# The following command achieves the desired result
|
||||
kubectl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).spec.containers[].image'
|
||||
```
|
||||
{{< /note >}}
|
||||
|
||||
@@ -127,14 +127,15 @@ To learn more about command operations, see the [kubectl](/docs/reference/kubect
|
||||
|
||||
The following table includes a list of all the supported resource types and their abbreviated aliases.
|
||||
|
||||
(This output can be retrieved from `kubectl api-resources`, and was accurate as of Kubernetes 1.13.3.)
|
||||
(This output can be retrieved from `kubectl api-resources`, and was accurate as of Kubernetes 1.19.1.)
|
||||
|
||||
| Resource Name | Short Names | API Group | Namespaced | Resource Kind |
|
||||
| NAME | SHORTNAMES | APIGROUP | NAMESPACED | KIND |
|
||||
|---|---|---|---|---|
|
||||
| `bindings` | | | true | Binding|
|
||||
| `bindings` | | | true | Binding |
|
||||
| `componentstatuses` | `cs` | | false | ComponentStatus |
|
||||
| `configmaps` | `cm` | | true | ConfigMap |
|
||||
| `endpoints` | `ep` | | true | Endpoints |
|
||||
| `events` | `ev` | | true | Event |
|
||||
| `limitranges` | `limits` | | true | LimitRange |
|
||||
| `namespaces` | `ns` | | false | Namespace |
|
||||
| `nodes` | `no` | | false | Node |
|
||||
@@ -142,14 +143,14 @@ The following table includes a list of all the supported resource types and thei
|
||||
| `persistentvolumes` | `pv` | | false | PersistentVolume |
|
||||
| `pods` | `po` | | true | Pod |
|
||||
| `podtemplates` | | | true | PodTemplate |
|
||||
| `replicationcontrollers` | `rc` | | true| ReplicationController |
|
||||
| `replicationcontrollers` | `rc` | | true | ReplicationController |
|
||||
| `resourcequotas` | `quota` | | true | ResourceQuota |
|
||||
| `secrets` | | | true | Secret |
|
||||
| `serviceaccounts` | `sa` | | true | ServiceAccount |
|
||||
| `services` | `svc` | | true | Service |
|
||||
| `mutatingwebhookconfigurations` | | admissionregistration.k8s.io | false | MutatingWebhookConfiguration |
|
||||
| `validatingwebhookconfigurations` | | admissionregistration.k8s.io | false | ValidatingWebhookConfiguration |
|
||||
| `customresourcedefinitions` | `crd`, `crds` | apiextensions.k8s.io | false | CustomResourceDefinition |
|
||||
| `customresourcedefinitions` | `crd,crds` | apiextensions.k8s.io | false | CustomResourceDefinition |
|
||||
| `apiservices` | | apiregistration.k8s.io | false | APIService |
|
||||
| `controllerrevisions` | | apps | true | ControllerRevision |
|
||||
| `daemonsets` | `ds` | apps | true | DaemonSet |
|
||||
@@ -166,9 +167,15 @@ The following table includes a list of all the supported resource types and thei
|
||||
| `jobs` | | batch | true | Job |
|
||||
| `certificatesigningrequests` | `csr` | certificates.k8s.io | false | CertificateSigningRequest |
|
||||
| `leases` | | coordination.k8s.io | true | Lease |
|
||||
| `endpointslices` | | discovery.k8s.io | true | EndpointSlice |
|
||||
| `events` | `ev` | events.k8s.io | true | Event |
|
||||
| `ingresses` | `ing` | extensions | true | Ingress |
|
||||
| `flowschemas` | | flowcontrol.apiserver.k8s.io | false | FlowSchema |
|
||||
| `prioritylevelconfigurations` | | flowcontrol.apiserver.k8s.io | false | PriorityLevelConfiguration |
|
||||
| `ingressclasses` | | networking.k8s.io | false | IngressClass |
|
||||
| `ingresses` | `ing` | networking.k8s.io | true | Ingress |
|
||||
| `networkpolicies` | `netpol` | networking.k8s.io | true | NetworkPolicy |
|
||||
| `runtimeclasses` | | node.k8s.io | false | RuntimeClass |
|
||||
| `poddisruptionbudgets` | `pdb` | policy | true | PodDisruptionBudget |
|
||||
| `podsecuritypolicies` | `psp` | policy | false | PodSecurityPolicy |
|
||||
| `clusterrolebindings` | | rbac.authorization.k8s.io | false | ClusterRoleBinding |
|
||||
@@ -178,7 +185,7 @@ The following table includes a list of all the supported resource types and thei
|
||||
| `priorityclasses` | `pc` | scheduling.k8s.io | false | PriorityClass |
|
||||
| `csidrivers` | | storage.k8s.io | false | CSIDriver |
|
||||
| `csinodes` | | storage.k8s.io | false | CSINode |
|
||||
| `storageclasses` | `sc` | storage.k8s.io | false | StorageClass |
|
||||
| `storageclasses` | `sc` | storage.k8s.io | false | StorageClass |
|
||||
| `volumeattachments` | | storage.k8s.io | false | VolumeAttachment |
|
||||
|
||||
## Output options
|
||||
|
||||
@@ -32,7 +32,7 @@ The following *predicates* implement filtering:
|
||||
- `PodFitsResources`: Checks if the Node has free resources (eg, CPU and Memory)
|
||||
to meet the requirement of the Pod.
|
||||
|
||||
- `PodMatchNodeSelector`: Checks if a Pod's Node {{< glossary_tooltip term_id="selector" >}}
|
||||
- `MatchNodeSelector`: Checks if a Pod's Node {{< glossary_tooltip term_id="selector" >}}
|
||||
matches the Node's {{< glossary_tooltip text="label(s)" term_id="label" >}}.
|
||||
|
||||
- `NoVolumeZoneConflict`: Evaluate if the {{< glossary_tooltip text="Volumes" term_id="volume" >}}
|
||||
|
||||
@@ -8,7 +8,7 @@ card:
|
||||
weight: 40
|
||||
---
|
||||
|
||||
<img src="https://raw.githubusercontent.com/kubernetes/kubeadm/master/logos/stacked/color/kubeadm-stacked-color.png" align="right" width="150px">Kubeadm is a tool built to provide `kubeadm init` and `kubeadm join` as best-practice “fast paths” for creating Kubernetes clusters.
|
||||
<img src="https://raw.githubusercontent.com/kubernetes/kubeadm/master/logos/stacked/color/kubeadm-stacked-color.png" align="right" width="150px">Kubeadm is a tool built to provide `kubeadm init` and `kubeadm join` as best-practice "fast paths" for creating Kubernetes clusters.
|
||||
|
||||
kubeadm performs the actions necessary to get a minimum viable cluster up and running. By design, it cares only about bootstrapping, not about provisioning machines. Likewise, installing various nice-to-have addons, like the Kubernetes Dashboard, monitoring solutions, and cloud-specific addons, is not in scope.
|
||||
|
||||
|
||||
@@ -30,9 +30,12 @@ Kubernetes generally leverages standard RESTful terminology to describe the API
|
||||
All resource types are either scoped by the cluster (`/apis/GROUP/VERSION/*`) or to a namespace (`/apis/GROUP/VERSION/namespaces/NAMESPACE/*`). A namespace-scoped resource type will be deleted when its namespace is deleted and access to that resource type is controlled by authorization checks on the namespace scope. The following paths are used to retrieve collections and resources:
|
||||
|
||||
* Cluster-scoped resources:
|
||||
|
||||
* `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of resources of the resource type
|
||||
* `GET /apis/GROUP/VERSION/RESOURCETYPE/NAME` - return the resource with NAME under the resource type
|
||||
|
||||
* Namespace-scoped resources:
|
||||
|
||||
* `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of all instances of the resource type across all namespaces
|
||||
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - return collection of all instances of the resource type in NAMESPACE
|
||||
* `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` - return the instance of the resource type with NAME in NAMESPACE
|
||||
@@ -57,33 +60,39 @@ For example:
|
||||
|
||||
1. List all of the pods in a given namespace.
|
||||
|
||||
GET /api/v1/namespaces/test/pods
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {"resourceVersion":"10245"},
|
||||
"items": [...]
|
||||
}
|
||||
```console
|
||||
GET /api/v1/namespaces/test/pods
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {"resourceVersion":"10245"},
|
||||
"items": [...]
|
||||
}
|
||||
```
|
||||
|
||||
2. Starting from resource version 10245, receive notifications of any creates, deletes, or updates as individual JSON objects.
|
||||
|
||||
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
|
||||
---
|
||||
200 OK
|
||||
Transfer-Encoding: chunked
|
||||
Content-Type: application/json
|
||||
{
|
||||
"type": "ADDED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
|
||||
}
|
||||
{
|
||||
"type": "MODIFIED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
|
||||
}
|
||||
...
|
||||
```
|
||||
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245
|
||||
---
|
||||
200 OK
|
||||
Transfer-Encoding: chunked
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"type": "ADDED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
|
||||
}
|
||||
{
|
||||
"type": "MODIFIED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "11020", ...}, ...}
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
A given Kubernetes server will only preserve a historical list of changes for a limited time. Clusters using etcd3 preserve changes in the last 5 minutes by default. When the requested watch operations fail because the historical version of that resource is not available, clients must handle the case by recognizing the status code `410 Gone`, clearing their local cache, performing a list operation, and starting the watch from the `resourceVersion` returned by that new list operation. Most client libraries offer some form of standard tool for this logic. (In Go this is called a `Reflector` and is located in the `k8s.io/client-go/cache` package.)
|
||||
|
||||
@@ -91,24 +100,28 @@ A given Kubernetes server will only preserve a historical list of changes for a
|
||||
|
||||
To mitigate the impact of short history window, we introduced a concept of `bookmark` watch event. It is a special kind of event to mark that all changes up to a given `resourceVersion` the client is requesting have already been sent. Object returned in that event is of the type requested by the request, but only `resourceVersion` field is set, e.g.:
|
||||
|
||||
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
|
||||
---
|
||||
200 OK
|
||||
Transfer-Encoding: chunked
|
||||
Content-Type: application/json
|
||||
{
|
||||
"type": "ADDED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
|
||||
}
|
||||
...
|
||||
{
|
||||
"type": "BOOKMARK",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
|
||||
}
|
||||
```console
|
||||
GET /api/v1/namespaces/test/pods?watch=1&resourceVersion=10245&allowWatchBookmarks=true
|
||||
---
|
||||
200 OK
|
||||
Transfer-Encoding: chunked
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"type": "ADDED",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "10596", ...}, ...}
|
||||
}
|
||||
...
|
||||
{
|
||||
"type": "BOOKMARK",
|
||||
"object": {"kind": "Pod", "apiVersion": "v1", "metadata": {"resourceVersion": "12746"} }
|
||||
}
|
||||
```
|
||||
|
||||
`Bookmark` events can be requested by `allowWatchBookmarks=true` option in watch requests, but clients shouldn't assume bookmarks are returned at any specific interval, nor may they assume the server will send any `bookmark` event.
|
||||
|
||||
## Retrieving large results sets in chunks
|
||||
|
||||
{{< feature-state for_k8s_version="v1.9" state="beta" >}}
|
||||
|
||||
On large clusters, retrieving the collection of some resource types may result in very large responses that can impact the server and client. For instance, a cluster may have tens of thousands of pods, each of which is 1-2kb of encoded JSON. Retrieving all pods across all namespaces may result in a very large response (10-20MB) and consume a large amount of server resources. Starting in Kubernetes 1.9 the server supports the ability to break a single large collection request into many smaller chunks while preserving the consistency of the total request. Each chunk can be returned sequentially which reduces both the total size of the request and allows user-oriented clients to display results incrementally to improve responsiveness.
|
||||
@@ -121,54 +134,63 @@ For example, if there are 1,253 pods on the cluster and the client wants to rece
|
||||
|
||||
1. List all of the pods on a cluster, retrieving up to 500 pods each time.
|
||||
|
||||
GET /api/v1/pods?limit=500
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "ENCODED_CONTINUE_TOKEN",
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 1-500
|
||||
}
|
||||
```console
|
||||
GET /api/v1/pods?limit=500
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "ENCODED_CONTINUE_TOKEN",
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 1-500
|
||||
}
|
||||
```
|
||||
|
||||
2. Continue the previous call, retrieving the next set of 500 pods.
|
||||
|
||||
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "ENCODED_CONTINUE_TOKEN_2",
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 501-1000
|
||||
}
|
||||
```console
|
||||
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "ENCODED_CONTINUE_TOKEN_2",
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 501-1000
|
||||
}
|
||||
```
|
||||
|
||||
3. Continue the previous call, retrieving the last 253 pods.
|
||||
|
||||
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "", // continue token is empty because we have reached the end of the list
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 1001-1253
|
||||
}
|
||||
```console
|
||||
GET /api/v1/pods?limit=500&continue=ENCODED_CONTINUE_TOKEN_2
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"kind": "PodList",
|
||||
"apiVersion": "v1",
|
||||
"metadata": {
|
||||
"resourceVersion":"10245",
|
||||
"continue": "", // continue token is empty because we have reached the end of the list
|
||||
...
|
||||
},
|
||||
"items": [...] // returns pods 1001-1253
|
||||
}
|
||||
```
|
||||
|
||||
Note that the `resourceVersion` of the list remains constant across each request, indicating the server is showing us a consistent snapshot of the pods. Pods that are created, updated, or deleted after version `10245` would not be shown unless the user makes a list request without the `continue` token. This allows clients to break large requests into smaller chunks and then perform a watch operation on the full set without missing any updates.
|
||||
|
||||
@@ -180,52 +202,56 @@ A few limitations of that approach include non-trivial logic when dealing with c
|
||||
|
||||
In order to avoid potential limitations as described above, clients may request the Table representation of objects, delegating specific details of printing to the server. The Kubernetes API implements standard HTTP content type negotiation: passing an `Accept` header containing a value of `application/json;as=Table;g=meta.k8s.io;v=v1beta1` with a `GET` call will request that the server return objects in the Table content type.
|
||||
|
||||
For example:
|
||||
For example, list all of the pods on a cluster in the Table format.
|
||||
|
||||
1. List all of the pods on a cluster in the Table format.
|
||||
```console
|
||||
GET /api/v1/pods
|
||||
Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
GET /api/v1/pods
|
||||
Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "Table",
|
||||
"apiVersion": "meta.k8s.io/v1beta1",
|
||||
...
|
||||
"columnDefinitions": [
|
||||
...
|
||||
]
|
||||
}
|
||||
{
|
||||
"kind": "Table",
|
||||
"apiVersion": "meta.k8s.io/v1beta1",
|
||||
...
|
||||
"columnDefinitions": [
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
For API resource types that do not have a custom Table definition on the server, a default Table response is returned by the server, consisting of the resource's `name` and `creationTimestamp` fields.
|
||||
|
||||
GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
...
|
||||
```console
|
||||
GET /apis/crd.example.com/v1alpha1/namespaces/default/resources
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
...
|
||||
|
||||
{
|
||||
"kind": "Table",
|
||||
"apiVersion": "meta.k8s.io/v1beta1",
|
||||
...
|
||||
"columnDefinitions": [
|
||||
{
|
||||
"kind": "Table",
|
||||
"apiVersion": "meta.k8s.io/v1beta1",
|
||||
"name": "Name",
|
||||
"type": "string",
|
||||
...
|
||||
},
|
||||
{
|
||||
"name": "Created At",
|
||||
"type": "date",
|
||||
...
|
||||
"columnDefinitions": [
|
||||
{
|
||||
"name": "Name",
|
||||
"type": "string",
|
||||
...
|
||||
},
|
||||
{
|
||||
"name": "Created At",
|
||||
"type": "date",
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Table responses are available beginning in version 1.10 of the kube-apiserver. As such, not all API resource types will support a Table response, specifically when using a client against older clusters. Clients that must work against all resource types, or can potentially deal with older clusters, should specify multiple content types in their `Accept` header to support fallback to non-Tabular JSON:
|
||||
|
||||
```
|
||||
```console
|
||||
Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1, application/json
|
||||
```
|
||||
|
||||
@@ -240,42 +266,47 @@ For example:
|
||||
|
||||
1. List all of the pods on a cluster in Protobuf format.
|
||||
|
||||
GET /api/v1/pods
|
||||
Accept: application/vnd.kubernetes.protobuf
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/vnd.kubernetes.protobuf
|
||||
... binary encoded PodList object
|
||||
```console
|
||||
GET /api/v1/pods
|
||||
Accept: application/vnd.kubernetes.protobuf
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/vnd.kubernetes.protobuf
|
||||
|
||||
... binary encoded PodList object
|
||||
```
|
||||
|
||||
2. Create a pod by sending Protobuf encoded data to the server, but request a response in JSON.
|
||||
|
||||
POST /api/v1/namespaces/test/pods
|
||||
Content-Type: application/vnd.kubernetes.protobuf
|
||||
Accept: application/json
|
||||
... binary encoded Pod object
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"kind": "Pod",
|
||||
"apiVersion": "v1",
|
||||
...
|
||||
}
|
||||
```console
|
||||
POST /api/v1/namespaces/test/pods
|
||||
Content-Type: application/vnd.kubernetes.protobuf
|
||||
Accept: application/json
|
||||
... binary encoded Pod object
|
||||
---
|
||||
200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"kind": "Pod",
|
||||
"apiVersion": "v1",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Not all API resource types will support Protobuf, specifically those defined via Custom Resource Definitions or those that are API extensions. Clients that must work against all resource types should specify multiple content types in their `Accept` header to support fallback to JSON:
|
||||
|
||||
```
|
||||
```console
|
||||
Accept: application/vnd.kubernetes.protobuf, application/json
|
||||
```
|
||||
|
||||
|
||||
### Protobuf encoding
|
||||
|
||||
Kubernetes uses an envelope wrapper to encode Protobuf responses. That wrapper starts with a 4 byte magic number to help identify content in disk or in etcd as Protobuf (as opposed to JSON), and then is followed by a Protobuf encoded wrapper message, which describes the encoding and type of the underlying object and then contains the object.
|
||||
|
||||
The wrapper format is:
|
||||
|
||||
```
|
||||
```console
|
||||
A four byte magic number prefix:
|
||||
Bytes 0-3: "k8s\x00" [0x6b, 0x38, 0x73, 0x00]
|
||||
|
||||
@@ -362,9 +393,11 @@ Dry-run is triggered by setting the `dryRun` query parameter. This parameter is
|
||||
|
||||
For example:
|
||||
|
||||
POST /api/v1/namespaces/test/pods?dryRun=All
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
```console
|
||||
POST /api/v1/namespaces/test/pods?dryRun=All
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
The response would look the same as for non-dry-run request, but the values of some generated fields may differ.
|
||||
|
||||
@@ -400,7 +433,7 @@ Some values of an object are typically generated before the object is persisted.
|
||||
|
||||
{{< feature-state for_k8s_version="v1.16" state="beta" >}}
|
||||
|
||||
{{< note >}}Starting from Kubernetes v1.18, if you have Server Side Apply enabled then the control plane tracks managed fields for all newly created objects.{{< /note >}}
|
||||
Starting from Kubernetes v1.18, if you have Server Side Apply enabled then the control plane tracks managed fields for all newly created objects.
|
||||
|
||||
### Introduction
|
||||
|
||||
@@ -484,10 +517,12 @@ data:
|
||||
|
||||
The above object contains a single manager in `metadata.managedFields`. The
|
||||
manager consists of basic information about the managing entity itself, like
|
||||
operation type, api version, and the fields managed by it.
|
||||
operation type, API version, and the fields managed by it.
|
||||
|
||||
{{< note >}} This field is managed by the apiserver and should not be changed by
|
||||
the user. {{< /note >}}
|
||||
{{< note >}}
|
||||
This field is managed by the API server and should not be changed by
|
||||
the user.
|
||||
{{< /note >}}
|
||||
|
||||
Nevertheless it is possible to change `metadata.managedFields` through an
|
||||
`Update` operation. Doing so is highly discouraged, but might be a reasonable
|
||||
@@ -537,7 +572,7 @@ a little differently.
|
||||
|
||||
{{< note >}}
|
||||
Whether you are submitting JSON data or YAML data, use `application/apply-patch+yaml` as the
|
||||
Content-Type header value.
|
||||
`Content-Type` header value.
|
||||
|
||||
All JSON documents are valid YAML.
|
||||
{{< /note >}}
|
||||
@@ -580,8 +615,8 @@ In this example, a second operation was run as an `Update` by the manager called
|
||||
`kube-controller-manager`. The update changed a value in the data field which
|
||||
caused the field's management to change to the `kube-controller-manager`.
|
||||
|
||||
{{< note >}}If this update would have been an `Apply` operation, the operation
|
||||
would have failed due to conflicting ownership.{{< /note >}}
|
||||
If this update would have been an `Apply` operation, the operation
|
||||
would have failed due to conflicting ownership.
|
||||
|
||||
### Merge strategy
|
||||
|
||||
@@ -603,13 +638,13 @@ merging, see
|
||||
A number of markers were added in Kubernetes 1.16 and 1.17, to allow API
|
||||
developers to describe the merge strategy supported by lists, maps, and
|
||||
structs. These markers can be applied to objects of the respective type,
|
||||
in Go files or in the [OpenAPI schema definition of the
|
||||
CRD](/docs/reference/generated/kubernetes-api/{{< param "version" >}}#jsonschemaprops-v1-apiextensions-k8s-io):
|
||||
in Go files or in the
|
||||
[OpenAPI schema definition of the CRD](/docs/reference/generated/kubernetes-api/{{< param "version" >}}#jsonschemaprops-v1-apiextensions-k8s-io):
|
||||
|
||||
| Golang marker | OpenAPI extension | Accepted values | Description | Introduced in |
|
||||
|---|---|---|---|---|
|
||||
| `//+listType` | `x-kubernetes-list-type` | `atomic`/`set`/`map` | Applicable to lists. `atomic` and `set` apply to lists with scalar elements only. `map` applies to lists of nested types only. If configured as `atomic`, the entire list is replaced during merge; a single manager manages the list as a whole at any one time. If `granular`, different managers can manage entries separately. | 1.16 |
|
||||
| `//+listMapKeys` | `x-kubernetes-list-map-keys` | Slice of map keys that uniquely identify entries for example `["port", "protocol"]` | Only applicable when `+listType=map`. A slice of strings whose values in combination must uniquely identify list entries. | 1.16 |
|
||||
| `//+listMapKey` | `x-kubernetes-list-map-keys` | Slice of map keys that uniquely identify entries for example `["port", "protocol"]` | Only applicable when `+listType=map`. A slice of strings whose values in combination must uniquely identify list entries. While there can be multiple keys, `listMapKey` is singular because keys need to be specified individually in the Go type. | 1.16 |
|
||||
| `//+mapType` | `x-kubernetes-map-type` | `atomic`/`granular` | Applicable to maps. `atomic` means that the map can only be entirely replaced by a single manager. `granular` means that the map supports separate managers updating individual fields. | 1.17 |
|
||||
| `//+structType` | `x-kubernetes-map-type` | `atomic`/`granular` | Applicable to structs; otherwise same usage and OpenAPI annotation as `//+mapType`.| 1.17 |
|
||||
|
||||
@@ -641,8 +676,8 @@ might not be able to resolve or act on these conflicts.
|
||||
|
||||
### Transferring Ownership
|
||||
|
||||
In addition to the concurrency controls provided by [conflict
|
||||
resolution](#conflicts), Server Side Apply provides ways to perform coordinated
|
||||
In addition to the concurrency controls provided by [conflict resolution](#conflicts),
|
||||
Server Side Apply provides ways to perform coordinated
|
||||
field ownership transfers from users to controllers.
|
||||
|
||||
This is best explained by example. Let's look at how to safely transfer
|
||||
@@ -657,12 +692,12 @@ Say a user has defined deployment with `replicas` set to the desired value:
|
||||
And the user has created the deployment using server side apply like so:
|
||||
|
||||
```shell
|
||||
kubectl apply -f application/ssa/nginx-deployment.yaml --server-side
|
||||
kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment.yaml --server-side
|
||||
```
|
||||
|
||||
Then later, HPA is enabled for the deployment, e.g.:
|
||||
|
||||
```
|
||||
```shell
|
||||
kubectl autoscale deployment nginx-deployment --cpu-percent=50 --min=1 --max=10
|
||||
```
|
||||
|
||||
@@ -691,7 +726,7 @@ First, the user defines a new configuration containing only the `replicas` field
|
||||
The user applies that configuration using the field manager name `handover-to-hpa`:
|
||||
|
||||
```shell
|
||||
kubectl apply -f application/ssa/nginx-deployment-replicas-only.yaml --server-side --field-manager=handover-to-hpa --validate=false
|
||||
kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment-replicas-only.yaml --server-side --field-manager=handover-to-hpa --validate=false
|
||||
```
|
||||
|
||||
If the apply results in a conflict with the HPA controller, then do nothing. The
|
||||
@@ -737,7 +772,7 @@ case.
|
||||
Client-side apply users who manage a resource with `kubectl apply` can start
|
||||
using server-side apply with the following flag.
|
||||
|
||||
```
|
||||
```shell
|
||||
kubectl apply --server-side [--dry-run=server]
|
||||
```
|
||||
|
||||
@@ -745,7 +780,9 @@ By default, field management of the object transfers from client-side apply
|
||||
to kubectl server-side apply without encountering conflicts.
|
||||
|
||||
{{< caution >}}
|
||||
Keep the `last-applied-configuration` annotation up to date. The annotation infers client-side apply's managed fields. Any fields not managed by client-side apply raise conflicts.
|
||||
Keep the `last-applied-configuration` annotation up to date.
|
||||
The annotation infers client-side apply's managed fields.
|
||||
Any fields not managed by client-side apply raise conflicts.
|
||||
|
||||
For example, if you used `kubectl scale` to update the replicas field after client-side apply,
|
||||
then this field is not owned by client-side apply and creates conflicts on `kubectl apply --server-side`.
|
||||
@@ -756,7 +793,7 @@ an exception, you can opt-out of this behavior by specifying a different,
|
||||
non-default field manager, as seen in the following example. The default field manager for kubectl
|
||||
server-side apply is `kubectl`.
|
||||
|
||||
```
|
||||
```shell
|
||||
kubectl apply --server-side --field-manager=my-manager [--dry-run=server]
|
||||
```
|
||||
|
||||
@@ -774,7 +811,7 @@ an exception, you can opt-out of this behavior by specifying a different,
|
||||
non-default field manager, as seen in the following example. The default field manager for kubectl
|
||||
server-side apply is `kubectl`.
|
||||
|
||||
```
|
||||
```shell
|
||||
kubectl apply --server-side --field-manager=my-manager [--dry-run=server]
|
||||
```
|
||||
|
||||
@@ -793,14 +830,14 @@ using `MergePatch`, `StrategicMergePatch`, `JSONPatch` or `Update`, so every
|
||||
non-apply operation. This can be done by overwriting the managedFields field
|
||||
with an empty entry. Two examples are:
|
||||
|
||||
```json
|
||||
```console
|
||||
PATCH /api/v1/namespaces/default/configmaps/example-cm
|
||||
Content-Type: application/merge-patch+json
|
||||
Accept: application/json
|
||||
Data: {"metadata":{"managedFields": [{}]}}
|
||||
```
|
||||
|
||||
```json
|
||||
```console
|
||||
PATCH /api/v1/namespaces/default/configmaps/example-cm
|
||||
Content-Type: application/json-patch+json
|
||||
Accept: application/json
|
||||
@@ -818,10 +855,12 @@ the managedFields, this will result in the managedFields being reset first and
|
||||
the other changes being processed afterwards. As a result the applier takes
|
||||
ownership of any fields updated in the same request.
|
||||
|
||||
{{< caution >}} Server Side Apply does not correctly track ownership on
|
||||
{{< caution >}}
|
||||
Server Side Apply does not correctly track ownership on
|
||||
sub-resources that don't receive the resource object type. If you are
|
||||
using Server Side Apply with such a sub-resource, the changed fields
|
||||
won't be tracked. {{< /caution >}}
|
||||
won't be tracked.
|
||||
{{< /caution >}}
|
||||
|
||||
### Disabling the feature
|
||||
|
||||
@@ -859,12 +898,13 @@ For get and list, the semantics of resource version are:
|
||||
|
||||
**List:**
|
||||
|
||||
v1.19+ API servers and newer support the `resourceVersionMatch` parameter, which
|
||||
v1.19+ API servers support the `resourceVersionMatch` parameter, which
|
||||
determines how resourceVersion is applied to list calls. It is highly
|
||||
recommended that `resourceVersionMatch` be set for list calls where
|
||||
`resourceVersion` is set. If `resourceVersion` is unset, `resourceVersionMatch`
|
||||
is not allowed. For backward compatibility, clients must tolerate the server
|
||||
ignoring `resourceVersionMatch`:
|
||||
|
||||
- When using `resourceVersionMatch=NotOlderThan` and limit is set, clients must
|
||||
handle HTTP 410 "Gone" responses. For example, the client might retry with a
|
||||
newer `resourceVersion` or fall back to `resourceVersion=""`.
|
||||
@@ -878,27 +918,29 @@ a known `resourceVersion` is preferable since it can achieve better performance
|
||||
of your cluster than leaving `resourceVersion` and `resourceVersionMatch` unset, which requires
|
||||
quorum read to be served.
|
||||
|
||||
{{< table caption="resourceVersionMatch and paging parameters for list" >}}
|
||||
|
||||
| resourceVersionMatch param | paging params | resourceVersion unset | resourceVersion="0" | resourceVersion="{value other than 0}" |
|
||||
|---------------------------------------|-------------------------------|-----------------------|-------------------------------------------|----------------------------------------|
|
||||
| resourceVersionMatch unset | limit unset | Most Recent | Any | Not older than |
|
||||
| resourceVersionMatch unset | limit="n", continue unset | Most Recent | Any | Exact |
|
||||
| resourceVersionMatch unset | limit="n", continue="<token>" | Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
|
||||
| resourceVersionMatch=Exact[^1] | limit unset | Invalid | Invalid | Exact |
|
||||
| resourceVersionMatch=Exact[^1] | limit="n", continue unset | Invalid | Invalid | Exact |
|
||||
| resourceVersionMatch=NotOlderThan[^1] | limit unset | Invalid | Any | Not older than |
|
||||
| resourceVersionMatch=NotOlderThan[^1] | limit="n", continue unset | Invalid | Any | Not older than |
|
||||
| resourceVersionMatch unset | limit=\<n\>, continue unset | Most Recent | Any | Exact |
|
||||
| resourceVersionMatch unset | limit=\<n\>, continue=\<token\> | Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
|
||||
| resourceVersionMatch=Exact [1] | limit unset | Invalid | Invalid | Exact |
|
||||
| resourceVersionMatch=Exact [1] | limit=\<n\>, continue unset | Invalid | Invalid | Exact |
|
||||
| resourceVersionMatch=NotOlderThan [1] | limit unset | Invalid | Any | Not older than |
|
||||
| resourceVersionMatch=NotOlderThan [1] | limit=\<n\>, continue unset | Invalid | Any | Not older than |
|
||||
|
||||
[^1]: If the server does not honor the `resourceVersionMatch` parameter, it is treated as if it is unset.
|
||||
| paging | resourceVersion unset | resourceVersion="0" | resourceVersion="{value other than 0}" |
|
||||
|---------------------------------|-----------------------|------------------------------------------------|----------------------------------------|
|
||||
| limit unset | Most Recent | Any | Not older than |
|
||||
| limit="n", continue unset | Most Recent | Any | Exact |
|
||||
| limit="n", continue="\<token\>" | Continue Token, Exact | Invalid, but treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
|
||||
{{< /table >}}
|
||||
|
||||
**Footnotes:**
|
||||
|
||||
[1] If the server does not honor the `resourceVersionMatch` parameter, it is treated as if it is unset.
|
||||
|
||||
The meaning of the get and list semantics are:
|
||||
|
||||
- **Most Recent:** Return data at the most recent resource version. The returned data must be
|
||||
consistent (i.e. served from etcd via a quorum read).
|
||||
|
||||
- **Any:** Return data at any resource version. The newest available resource version is preferred,
|
||||
but strong consistency is not required; data at any resource version may be served. It is possible
|
||||
for the request to return data at a much older resource version that the client has previously
|
||||
@@ -911,6 +953,7 @@ The meaning of the get and list semantics are:
|
||||
but does not make any guarantee about the resourceVersion in the ObjectMeta of the list items
|
||||
since ObjectMeta.resourceVersion tracks when an object was last updated, not how up-to-date the
|
||||
object is when served.
|
||||
|
||||
- **Exact:** Return data at the exact resource version provided. If the provided resourceVersion is
|
||||
unavailable, the server responds with HTTP 410 "Gone". For list requests to servers that honor the
|
||||
resourceVersionMatch parameter, this guarantees that resourceVersion in the ListMeta is the same as
|
||||
@@ -925,10 +968,14 @@ For watch, the semantics of resource version are:
|
||||
|
||||
**Watch:**
|
||||
|
||||
{{< table caption="resourceVersion for watch" >}}
|
||||
|
||||
| resourceVersion unset | resourceVersion="0" | resourceVersion="{value other than 0}" |
|
||||
|-------------------------------------|----------------------------|----------------------------------------|
|
||||
| Get State and Start at Most Recent | Get State and Start at Any | Start at Exact |
|
||||
|
||||
{{< /table >}}
|
||||
|
||||
The meaning of the watch semantics are:
|
||||
|
||||
- **Get State and Start at Most Recent:** Start a watch at the most recent resource version, which must be consistent (i.e. served from etcd via a quorum read). To establish initial state, the watch begins with synthetic "Added" events of all resources instances that exist at the starting resource version. All following watch events are for all changes that occurred after the resource version the watch started at.
|
||||
|
||||
@@ -13,62 +13,60 @@ card:
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
This page provides an overview of the Kubernetes API.
|
||||
|
||||
This page provides an overview of the Kubernetes API.
|
||||
|
||||
<!-- body -->
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and communications between components, and external user commands are REST API calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||
|
||||
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||
communications between components, and external user commands are REST API
|
||||
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
Most operations can be performed through the
|
||||
[kubectl](/docs/reference/kubectl/overview/) command-line interface or other
|
||||
command-line tools, such as [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/), which in turn use
|
||||
the API. However, you can also access the API directly using REST calls.
|
||||
|
||||
Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/)
|
||||
if you are writing an application using the Kubernetes API.
|
||||
|
||||
## API versioning
|
||||
|
||||
To eliminate fields or restructure resource representations, Kubernetes supports
|
||||
multiple API versions, each at a different API path. For example: `/api/v1` or
|
||||
`/apis/rbac.authorization.k8s.io/v1alpha1`.
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||
schema changes. The following descriptions cover both formats.
|
||||
|
||||
The version is set at the API level rather than at the resource or field level to:
|
||||
The API versioning and software versioning are indirectly related.
|
||||
The [API and release versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
|
||||
describes the relationship between API versioning and software versioning.
|
||||
|
||||
- Ensure that the API presents a clear and consistent view of system resources and behavior.
|
||||
- Enable control access to end-of-life and/or experimental APIs.
|
||||
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for schema changes. The following descriptions cover both formats.
|
||||
|
||||
{{< note >}}
|
||||
The API versioning and software versioning are indirectly related. The [API and release
|
||||
versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) describes the relationship between API versioning and software versioning.
|
||||
{{< /note >}}
|
||||
|
||||
Different API versions indicate different levels of stability and support. You can find more information about the criteria for each level in the [API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
||||
Different API versions indicate different levels of stability and support. You
|
||||
can find more information about the criteria for each level in the
|
||||
[API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
||||
|
||||
Here's a summary of each level:
|
||||
|
||||
- Alpha:
|
||||
- The version names contain `alpha` (for example, `v1alpha1`).
|
||||
- The software may contain bugs. Enabling a feature may expose bugs. A feature may be disabled by default.
|
||||
- The software may contain bugs. Enabling a feature may expose bugs. A
|
||||
feature may be disabled by default.
|
||||
- The support for a feature may be dropped at any time without notice.
|
||||
- The API may change in incompatible ways in a later software release without notice.
|
||||
- The software is recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
|
||||
- The software is recommended for use only in short-lived testing clusters,
|
||||
due to increased risk of bugs and lack of long-term support.
|
||||
|
||||
- Beta:
|
||||
- The version names contain `beta` (for example, `v2beta3`).
|
||||
- The software is well tested. Enabling a feature is considered safe. Features are enabled by default.
|
||||
- The software is well tested. Enabling a feature is considered safe.
|
||||
Features are enabled by default.
|
||||
- The support for a feature will not be dropped, though the details may change.
|
||||
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, migration instructions are provided. This may require deleting, editing, and re-creating
|
||||
API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
|
||||
- The software is recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have multiple clusters which can be upgraded independently, you may be able to relax this restriction.
|
||||
|
||||
- The schema and/or semantics of objects may change in incompatible ways in
|
||||
a subsequent beta or stable release. When this happens, migration
|
||||
instructions are provided. Schema changes may require deleting, editing, and
|
||||
re-creating API objects. The editing process may not be straightforward.
|
||||
The migration may require downtime for applications that rely on the feature.
|
||||
- The software is not recommended for production uses. Subsequent releases
|
||||
may introduce incompatible changes. If you have multiple clusters which
|
||||
can be upgraded independently, you may be able to relax this restriction.
|
||||
|
||||
{{< note >}}
|
||||
Try the beta features and provide feedback. After the features exit beta, it may not be practical to make more changes.
|
||||
{{< /note >}}
|
||||
{{< note >}}
|
||||
Try the beta features and provide feedback. After the features exit beta, it
|
||||
may not be practical to make more changes.
|
||||
{{< /note >}}
|
||||
|
||||
- Stable:
|
||||
- The version name is `vX` where `X` is an integer.
|
||||
@@ -76,33 +74,44 @@ Try the beta features and provide feedback. After the features exit beta, it may
|
||||
|
||||
## API groups
|
||||
|
||||
[*API groups*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md) make it easier to extend the Kubernetes API. The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
|
||||
[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)
|
||||
make it easier to extend the Kubernetes API.
|
||||
The API group is specified in a REST path and in the `apiVersion` field of a
|
||||
serialized object.
|
||||
|
||||
Currently, there are several API groups in use:
|
||||
|
||||
* The *core* (also called *legacy*) group, which is at REST path `/api/v1` and is not specified as part of the `apiVersion` field, for example, `apiVersion: v1`.
|
||||
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
|
||||
(for example, `apiVersion: batch/v1`). You can find the full list of supported API groups in [Kubernetes API reference](/docs/reference/).
|
||||
* The *core* (also called *legacy*) group is found at REST path `/api/v1`.
|
||||
The core group is not specified as part of the `apiVersion` field, for
|
||||
example, `apiVersion: v1`.
|
||||
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
|
||||
`apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
|
||||
You can find the full list of supported API groups in
|
||||
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
The two paths that support extending the API with [custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/) are:
|
||||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||
|
||||
- [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
|
||||
for basic CRUD needs.
|
||||
- [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md) for a full set of Kubernetes API semantics to implement their own apiserver.
|
||||
|
||||
Certain resources and API groups are enabled by default. You can enable or
|
||||
disable them by setting `--runtime-config` on the API server. The
|
||||
`--runtime-config` flag accepts comma separated `<key>=<value>` pairs
|
||||
describing the runtime configuration of the API server. For example:
|
||||
|
||||
## Enabling or disabling API groups
|
||||
|
||||
Certain resources and API groups are enabled by default. You can enable or disable them by setting `--runtime-config`
|
||||
on the apiserver. `--runtime-config` accepts comma separated values. For example:
|
||||
|
||||
- to disable batch/v1, set `--runtime-config=batch/v1=false`
|
||||
- to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`
|
||||
|
||||
The flag accepts comma separated set of key=value pairs describing runtime configuration of the apiserver.
|
||||
- to disable `batch/v1`, set `--runtime-config=batch/v1=false`
|
||||
- to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
|
||||
|
||||
{{< note >}}
|
||||
When you enable or disable groups or resources, you need to restart the apiserver and controller-manager
|
||||
to pick up the `--runtime-config` changes.
|
||||
When you enable or disable groups or resources, you need to restart the API
|
||||
server and controller manager to pick up the `--runtime-config` changes.
|
||||
{{< /note >}}
|
||||
|
||||
## Persistence
|
||||
|
||||
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
||||
{{< glossary_tooltip term_id="etcd" >}}.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||||
- Read the design documentation for
|
||||
[aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)
|
||||
|
||||
|
||||
@@ -40,6 +40,8 @@ The following client libraries are officially maintained by
|
||||
|
||||
## Community-maintained client libraries
|
||||
|
||||
{{% thirdparty-content %}}
|
||||
|
||||
The following Kubernetes API client libraries are provided and maintained by
|
||||
their authors, not the Kubernetes team.
|
||||
|
||||
@@ -60,6 +62,7 @@ their authors, not the Kubernetes team.
|
||||
| PHP | [github.com/allansun/kubernetes-php-client](https://github.com/allansun/kubernetes-php-client) |
|
||||
| PHP | [github.com/maclof/kubernetes-client](https://github.com/maclof/kubernetes-client) |
|
||||
| PHP | [github.com/travisghansen/kubernetes-client-php](https://github.com/travisghansen/kubernetes-client-php) |
|
||||
| PHP | [github.com/renoki-co/php-k8s](https://github.com/renoki-co/php-k8s) |
|
||||
| Python | [github.com/eldarion-gondor/pykube](https://github.com/eldarion-gondor/pykube) |
|
||||
| Python | [github.com/fiaas/k8s](https://github.com/fiaas/k8s) |
|
||||
| Python | [github.com/mnubo/kubernetes-py](https://github.com/mnubo/kubernetes-py) |
|
||||
|
||||
@@ -303,12 +303,12 @@ Starting in Kubernetes v1.19, making an API request to a deprecated REST API end
|
||||
2. Adds a `"k8s.io/deprecated":"true"` annotation to the [audit event](/docs/tasks/debug-application-cluster/audit/) recorded for the request.
|
||||
3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver`
|
||||
process. The metric has labels for `group`, `version`, `resource`, `subresource` that can be joined
|
||||
to the `apiserver_request_total` metric, and a `removed_version` label that indicates the
|
||||
to the `apiserver_request_total` metric, and a `removed_release` label that indicates the
|
||||
Kubernetes release in which the API will no longer be served. The following Prometheus query
|
||||
returns information about requests made to deprecated APIs which will be removed in v1.22:
|
||||
|
||||
|
||||
```promql
|
||||
apiserver_requested_deprecated_apis{removed_version="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
|
||||
apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
|
||||
```
|
||||
|
||||
### Fields of REST resources
|
||||
|
||||
@@ -94,7 +94,7 @@ The output show that the `etcd` check is excluded:
|
||||
{{< 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 schema for the individual health checks is `/livez/<healthcheck-name>` where `livez` and `readyz` and be used to indicate if you want to check the 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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user