Merge pull request #34372 from tengqm/fix-links-1
Batch fixes for links (1)
This commit is contained in:
Kubernetes Prow Robot
@@ -67,4 +67,5 @@ for deploying Kubernetes is [kubeadm](/docs/setup/production-environment/tools/k
|
||||
Kubernetes is designed for its {{< glossary_tooltip term_id="control-plane" text="control plane" >}} to
|
||||
run on Linux. Within your cluster you can run applications on Linux or other operating systems, including
|
||||
Windows.
|
||||
- Learn to [set up clusters with Windows nodes](/docs/setup/production-environment/windows/)
|
||||
|
||||
- Learn to [set up clusters with Windows nodes](/docs/concepts/windows/)
|
||||
|
||||
@@ -29,7 +29,7 @@ configuration.
|
||||
|
||||
These tasks will help you to migrate:
|
||||
|
||||
* [Check whether Dockershim deprecation affects you](/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you/)
|
||||
* [Check whether Dockershim removal affects you](/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-removal-affects-you/)
|
||||
* [Migrate Docker Engine nodes from dockershim to cri-dockerd](/docs/tasks/administer-cluster/migrating-from-dockershim/migrate-dockershim-dockerd/)
|
||||
* [Migrating telemetry and security agents from dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents/)
|
||||
|
||||
|
||||
@@ -323,7 +323,7 @@ configuration of the API server:
|
||||
|
||||
To verify that the PodSecurityPolicy admission controller is no longer enabled, you can manually run
|
||||
a test by impersonating a user without access to any PodSecurityPolicies (see the
|
||||
[PodSecurityPolicy example](/docs/concepts/policy/pod-security-policy/#example)), or by verifying in
|
||||
[PodSecurityPolicy example](/docs/concepts/security/pod-security-policy/#example)), or by verifying in
|
||||
the API server logs. At startup, the API server outputs log lines listing the loaded admission
|
||||
controller plugins:
|
||||
|
||||
|
||||
@@ -36,7 +36,13 @@ kubectl cluster-info dump
|
||||
|
||||
### Example: debugging a down/unreachable node
|
||||
|
||||
Sometimes when debugging it can be useful to look at the status of a node -- for example, because you've noticed strange behavior of a Pod that's running on the node, or to find out why a Pod won't schedule onto the node. As with Pods, you can use `kubectl describe node` and `kubectl get node -o yaml` to retrieve detailed information about nodes. For example, here's what you'll see if a node is down (disconnected from the network, or kubelet dies and won't restart, etc.). Notice the events that show the node is NotReady, and also notice that the pods are no longer running (they are evicted after five minutes of NotReady status).
|
||||
Sometimes when debugging it can be useful to look at the status of a node -- for example, because
|
||||
you've noticed strange behavior of a Pod that's running on the node, or to find out why a Pod
|
||||
won't schedule onto the node. As with Pods, you can use `kubectl describe node` and `kubectl get
|
||||
node -o yaml` to retrieve detailed information about nodes. For example, here's what you'll see if
|
||||
a node is down (disconnected from the network, or kubelet dies and won't restart, etc.). Notice
|
||||
the events that show the node is NotReady, and also notice that the pods are no longer running
|
||||
(they are evicted after five minutes of NotReady status).
|
||||
|
||||
```shell
|
||||
kubectl get nodes
|
||||
@@ -222,14 +228,16 @@ of the relevant log files. On systemd-based systems, you may need to use `journ
|
||||
|
||||
### Control Plane nodes
|
||||
|
||||
* `/var/log/kube-apiserver.log` - API Server, responsible for serving the API
|
||||
* `/var/log/kube-scheduler.log` - Scheduler, responsible for making scheduling decisions
|
||||
* `/var/log/kube-controller-manager.log` - a component that runs most Kubernetes built-in {{<glossary_tooltip text="controllers" term_id="controller">}}, with the notable exception of scheduling (the kube-scheduler handles scheduling).
|
||||
* `/var/log/kube-apiserver.log` - API Server, responsible for serving the API
|
||||
* `/var/log/kube-scheduler.log` - Scheduler, responsible for making scheduling decisions
|
||||
* `/var/log/kube-controller-manager.log` - a component that runs most Kubernetes built-in
|
||||
{{<glossary_tooltip text="controllers" term_id="controller">}}, with the notable exception of scheduling
|
||||
(the kube-scheduler handles scheduling).
|
||||
|
||||
### Worker Nodes
|
||||
|
||||
* `/var/log/kubelet.log` - logs from the kubelet, responsible for running containers on the node
|
||||
* `/var/log/kube-proxy.log` - logs from `kube-proxy`, which is responsible for directing traffic to Service endpoints
|
||||
* `/var/log/kubelet.log` - logs from the kubelet, responsible for running containers on the node
|
||||
* `/var/log/kube-proxy.log` - logs from `kube-proxy`, which is responsible for directing traffic to Service endpoints
|
||||
|
||||
## Cluster failure modes
|
||||
|
||||
@@ -237,45 +245,46 @@ This is an incomplete list of things that could go wrong, and how to adjust your
|
||||
|
||||
### Contributing causes
|
||||
|
||||
- VM(s) shutdown
|
||||
- Network partition within cluster, or between cluster and users
|
||||
- Crashes in Kubernetes software
|
||||
- Data loss or unavailability of persistent storage (e.g. GCE PD or AWS EBS volume)
|
||||
- Operator error, for example misconfigured Kubernetes software or application software
|
||||
- VM(s) shutdown
|
||||
- Network partition within cluster, or between cluster and users
|
||||
- Crashes in Kubernetes software
|
||||
- Data loss or unavailability of persistent storage (e.g. GCE PD or AWS EBS volume)
|
||||
- Operator error, for example misconfigured Kubernetes software or application software
|
||||
|
||||
### Specific scenarios
|
||||
|
||||
- API server VM shutdown or apiserver crashing
|
||||
- Results
|
||||
- unable to stop, update, or start new pods, services, replication controller
|
||||
- existing pods and services should continue to work normally, unless they depend on the Kubernetes API
|
||||
- API server backing storage lost
|
||||
- Results
|
||||
- the kube-apiserver component fails to start successfully and become healthy
|
||||
- kubelets will not be able to reach it but will continue to run the same pods and provide the same service proxying
|
||||
- manual recovery or recreation of apiserver state necessary before apiserver is restarted
|
||||
- Supporting services (node controller, replication controller manager, scheduler, etc) VM shutdown or crashes
|
||||
- currently those are colocated with the apiserver, and their unavailability has similar consequences as apiserver
|
||||
- in future, these will be replicated as well and may not be co-located
|
||||
- they do not have their own persistent state
|
||||
- Individual node (VM or physical machine) shuts down
|
||||
- Results
|
||||
- pods on that Node stop running
|
||||
- Network partition
|
||||
- Results
|
||||
- partition A thinks the nodes in partition B are down; partition B thinks the apiserver is down. (Assuming the master VM ends up in partition A.)
|
||||
- Kubelet software fault
|
||||
- Results
|
||||
- crashing kubelet cannot start new pods on the node
|
||||
- kubelet might delete the pods or not
|
||||
- node marked unhealthy
|
||||
- replication controllers start new pods elsewhere
|
||||
- Cluster operator error
|
||||
- Results
|
||||
- loss of pods, services, etc
|
||||
- lost of apiserver backing store
|
||||
- users unable to read API
|
||||
- etc.
|
||||
- API server VM shutdown or apiserver crashing
|
||||
- Results
|
||||
- unable to stop, update, or start new pods, services, replication controller
|
||||
- existing pods and services should continue to work normally, unless they depend on the Kubernetes API
|
||||
- API server backing storage lost
|
||||
- Results
|
||||
- the kube-apiserver component fails to start successfully and become healthy
|
||||
- kubelets will not be able to reach it but will continue to run the same pods and provide the same service proxying
|
||||
- manual recovery or recreation of apiserver state necessary before apiserver is restarted
|
||||
- Supporting services (node controller, replication controller manager, scheduler, etc) VM shutdown or crashes
|
||||
- currently those are colocated with the apiserver, and their unavailability has similar consequences as apiserver
|
||||
- in future, these will be replicated as well and may not be co-located
|
||||
- they do not have their own persistent state
|
||||
- Individual node (VM or physical machine) shuts down
|
||||
- Results
|
||||
- pods on that Node stop running
|
||||
- Network partition
|
||||
- Results
|
||||
- partition A thinks the nodes in partition B are down; partition B thinks the apiserver is down.
|
||||
(Assuming the master VM ends up in partition A.)
|
||||
- Kubelet software fault
|
||||
- Results
|
||||
- crashing kubelet cannot start new pods on the node
|
||||
- kubelet might delete the pods or not
|
||||
- node marked unhealthy
|
||||
- replication controllers start new pods elsewhere
|
||||
- Cluster operator error
|
||||
- Results
|
||||
- loss of pods, services, etc
|
||||
- lost of apiserver backing store
|
||||
- users unable to read API
|
||||
- etc.
|
||||
|
||||
### Mitigations
|
||||
|
||||
@@ -308,9 +317,13 @@ This is an incomplete list of things that could go wrong, and how to adjust your
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Learn about the metrics available in the [Resource Metrics Pipeline](resource-metrics-pipeline)
|
||||
* Discover additional tools for [monitoring resource usage](resource-usage-monitoring)
|
||||
* Use Node Problem Detector to [monitor node health](monitor-node-health)
|
||||
* Use `crictl` to [debug Kubernetes nodes](crictl)
|
||||
* Get more information about [Kubernetes auditing](audit)
|
||||
* Use `telepresence` to [develop and debug services locally](local-debugging)
|
||||
* Learn about the metrics available in the
|
||||
[Resource Metrics Pipeline](/docs/tasks/debug/debug-cluster/resource-metrics-pipeline/)
|
||||
* Discover additional tools for
|
||||
[monitoring resource usage](/docs/tasks/debug/debug-cluster/resource-usage-monitoring/)
|
||||
* Use Node Problem Detector to
|
||||
[monitor node health](/docs/tasks/debug/debug-cluster/monitor-node-health/)
|
||||
* Use `crictl` to [debug Kubernetes nodes](/docs/tasks/debug/debug-cluster/crictl/)
|
||||
* Get more information about [Kubernetes auditing](/docs/tasks/debug/debug-cluster/audit/)
|
||||
* Use `telepresence` to [develop and debug services locally](/docs/tasks/debug/debug-cluster/local-debugging/)
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ content_type: concept
|
||||
1. My Pods are stuck at "Container Creating" or restarting over and over
|
||||
|
||||
Ensure that your pause image is compatible with your Windows OS version.
|
||||
See [Pause container](/docs/setup/production-environment/windows/intro-windows-in-kubernetes#pause-container)
|
||||
See [Pause container](/docs/concepts/windows/intro/#pause-container)
|
||||
to see the latest / recommended pause image and/or get more information.
|
||||
|
||||
{{< note >}}
|
||||
@@ -32,7 +32,7 @@ content_type: concept
|
||||
Windows Node.
|
||||
|
||||
More information on how to specify a compatible node for your Pod can be found in
|
||||
[this guide](/docs/setup/production-environment/windows/user-guide-windows-containers/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host).
|
||||
[this guide](/docs/concepts/windows/user-guide/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host).
|
||||
|
||||
## Network troubleshooting {#troubleshooting-network}
|
||||
|
||||
@@ -102,8 +102,8 @@ content_type: concept
|
||||
Get-NetAdapter | ? Name -Like "vEthernet (Ethernet*"
|
||||
```
|
||||
|
||||
Often it is worthwhile to modify the [InterfaceName](https://github.com/microsoft/SDN/blob/master/Kubernetes/flannel/start.ps1#L7) parameter of the `start.ps1` script,
|
||||
in cases where the host's network adapter isn't "Ethernet".
|
||||
Often it is worthwhile to modify the [InterfaceName](https://github.com/microsoft/SDN/blob/master/Kubernetes/flannel/start.ps1#L7)
|
||||
parameter of the `start.ps1` script, in cases where the host's network adapter isn't "Ethernet".
|
||||
Otherwise, consult the output of the `start-kubelet.ps1` script to see if there are errors during virtual network creation.
|
||||
|
||||
1. DNS resolution is not properly working
|
||||
@@ -112,9 +112,11 @@ content_type: concept
|
||||
|
||||
1. `kubectl port-forward` fails with "unable to do port forwarding: wincat not found"
|
||||
|
||||
This was implemented in Kubernetes 1.15 by including `wincat.exe` in the pause infrastructure container `mcr.microsoft.com/oss/kubernetes/pause:3.6`.
|
||||
This was implemented in Kubernetes 1.15 by including `wincat.exe` in the pause infrastructure container
|
||||
`mcr.microsoft.com/oss/kubernetes/pause:3.6`.
|
||||
Be sure to use a supported version of Kubernetes.
|
||||
If you would like to build your own pause infrastructure container be sure to include [wincat](https://github.com/kubernetes/kubernetes/tree/master/build/pause/windows/wincat).
|
||||
If you would like to build your own pause infrastructure container be sure to include
|
||||
[wincat](https://github.com/kubernetes/kubernetes/tree/master/build/pause/windows/wincat).
|
||||
|
||||
1. My Kubernetes installation is failing because my Windows Server node is behind a proxy
|
||||
|
||||
@@ -170,4 +172,5 @@ If these steps don't resolve your problem, you can get help running Windows cont
|
||||
|
||||
* StackOverflow [Windows Server Container](https://stackoverflow.com/questions/tagged/windows-server-container) topic
|
||||
* Kubernetes Official Forum [discuss.kubernetes.io](https://discuss.kubernetes.io/)
|
||||
* Kubernetes Slack [#SIG-Windows Channel](https://kubernetes.slack.com/messages/sig-windows)
|
||||
* Kubernetes Slack [#SIG-Windows Channel](https://kubernetes.slack.com/messages/sig-windows)
|
||||
|
||||
|
||||
+85
-40
@@ -188,7 +188,8 @@ kubectl get crontabs
|
||||
```
|
||||
|
||||
```none
|
||||
Error from server (NotFound): Unable to list {"stable.example.com" "v1" "crontabs"}: the server could not find the requested resource (get crontabs.stable.example.com)
|
||||
Error from server (NotFound): Unable to list {"stable.example.com" "v1" "crontabs"}: the server could not
|
||||
find the requested resource (get crontabs.stable.example.com)
|
||||
```
|
||||
|
||||
If you later recreate the same CustomResourceDefinition, it will start out empty.
|
||||
@@ -207,22 +208,28 @@ CustomResourceDefinition, the structural schema was optional.
|
||||
|
||||
A structural schema is an [OpenAPI v3.0 validation schema](#validation) which:
|
||||
|
||||
1. specifies a non-empty type (via `type` in OpenAPI) for the root, for each specified field of an object node (via `properties` or `additionalProperties` in OpenAPI) and for each item in an array node (via `items` in OpenAPI), with the exception of:
|
||||
1. specifies a non-empty type (via `type` in OpenAPI) for the root, for each specified field of an object node
|
||||
(via `properties` or `additionalProperties` in OpenAPI) and for each item in an array node
|
||||
(via `items` in OpenAPI), with the exception of:
|
||||
* a node with `x-kubernetes-int-or-string: true`
|
||||
* a node with `x-kubernetes-preserve-unknown-fields: true`
|
||||
2. for each field in an object and each item in an array which is specified within any of `allOf`, `anyOf`, `oneOf` or `not`, the schema also specifies the field/item outside of those logical junctors (compare example 1 and 2).
|
||||
3. does not set `description`, `type`, `default`, `additionalProperties`, `nullable` within an `allOf`, `anyOf`, `oneOf` or `not`, with the exception of the two pattern for `x-kubernetes-int-or-string: true` (see below).
|
||||
2. for each field in an object and each item in an array which is specified within any of `allOf`, `anyOf`,
|
||||
`oneOf` or `not`, the schema also specifies the field/item outside of those logical junctors (compare example 1 and 2).
|
||||
3. does not set `description`, `type`, `default`, `additionalProperties`, `nullable` within an `allOf`, `anyOf`,
|
||||
`oneOf` or `not`, with the exception of the two pattern for `x-kubernetes-int-or-string: true` (see below).
|
||||
4. if `metadata` is specified, then only restrictions on `metadata.name` and `metadata.generateName` are allowed.
|
||||
|
||||
|
||||
Non-structural example 1:
|
||||
|
||||
```yaml
|
||||
allOf:
|
||||
- properties:
|
||||
foo:
|
||||
...
|
||||
```
|
||||
|
||||
conflicts with rule 2. The following would be correct:
|
||||
|
||||
```yaml
|
||||
properties:
|
||||
foo:
|
||||
@@ -314,10 +321,13 @@ Violations of the structural schema rules are reported in the `NonStructural` co
|
||||
|
||||
### Field pruning
|
||||
|
||||
CustomResourceDefinitions store validated resource data in the cluster's persistence store, {{< glossary_tooltip term_id="etcd" text="etcd">}}. As with native Kubernetes resources such as {{< glossary_tooltip text="ConfigMap" term_id="configmap" >}}, if you specify a field that the API server does not recognize, the unknown field is _pruned_ (removed) before being persisted.
|
||||
CustomResourceDefinitions store validated resource data in the cluster's persistence store, {{< glossary_tooltip term_id="etcd" text="etcd">}}.
|
||||
As with native Kubernetes resources such as {{< glossary_tooltip text="ConfigMap" term_id="configmap" >}},
|
||||
if you specify a field that the API server does not recognize, the unknown field is _pruned_ (removed) before being persisted.
|
||||
|
||||
{{< note >}}
|
||||
CRDs converted from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` might lack structural schemas, and `spec.preserveUnknownFields` might be `true`.
|
||||
CRDs converted from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` might lack structural schemas,
|
||||
and `spec.preserveUnknownFields` might be `true`.
|
||||
|
||||
For legacy CustomResourceDefinition objects created as
|
||||
`apiextensions.k8s.io/v1beta1` with `spec.preserveUnknownFields` set to
|
||||
@@ -377,7 +387,10 @@ to clients, `kubectl` also checks for unknown fields and rejects those objects w
|
||||
|
||||
#### Controlling pruning
|
||||
|
||||
By default, all unspecified fields for a custom resource, across all versions, are pruned. It is possible though to opt-out of that for specifc sub-trees of fields by adding `x-kubernetes-preserve-unknown-fields: true` in the [structural OpenAPI v3 validation schema](#specifying-a-structural-schema).
|
||||
By default, all unspecified fields for a custom resource, across all versions, are pruned. It is possible though to
|
||||
opt-out of that for specifc sub-trees of fields by adding `x-kubernetes-preserve-unknown-fields: true` in the
|
||||
[structural OpenAPI v3 validation schema](#specifying-a-structural-schema).
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
@@ -456,7 +469,8 @@ properties:
|
||||
x-kubernetes-int-or-string: true
|
||||
```
|
||||
|
||||
Also those nodes are partially excluded from rule 3 in the sense that the following two patterns are allowed (exactly those, without variations in order to additional fields):
|
||||
Also those nodes are partially excluded from rule 3 in the sense that the following two patterns are allowed
|
||||
(exactly those, without variations in order to additional fields):
|
||||
|
||||
```yaml
|
||||
x-kubernetes-int-or-string: true
|
||||
@@ -489,7 +503,8 @@ RawExtensions (as in `runtime.RawExtension` defined in
|
||||
[k8s.io/apimachinery](https://github.com/kubernetes/apimachinery/blob/03ac7a9ade429d715a1a46ceaa3724c18ebae54f/pkg/runtime/types.go#L94))
|
||||
holds complete Kubernetes objects, i.e. with `apiVersion` and `kind` fields.
|
||||
|
||||
It is possible to specify those embedded objects (both completely without constraints or partially specified) by setting `x-kubernetes-embedded-resource: true`. For example:
|
||||
It is possible to specify those embedded objects (both completely without constraints or partially specified)
|
||||
by setting `x-kubernetes-embedded-resource: true`. For example:
|
||||
|
||||
```yaml
|
||||
type: object
|
||||
@@ -509,7 +524,8 @@ foo:
|
||||
...
|
||||
```
|
||||
|
||||
Because `x-kubernetes-preserve-unknown-fields: true` is specified alongside, nothing is pruned. The use of `x-kubernetes-preserve-unknown-fields: true` is optional though.
|
||||
Because `x-kubernetes-preserve-unknown-fields: true` is specified alongside, nothing is pruned.
|
||||
The use of `x-kubernetes-preserve-unknown-fields: true` is optional though.
|
||||
|
||||
With `x-kubernetes-embedded-resource: true`, the `apiVersion`, `kind` and `metadata` are implicitly specified and validated.
|
||||
|
||||
@@ -772,6 +788,7 @@ The CronTab "my-new-cron-object" is invalid:
|
||||
The `rule` under `x-kubernetes-validations` represents the expression which will be evaluated by CEL.
|
||||
|
||||
The `message` represents the message displayed when validation fails. If message is unset, the above response would be:
|
||||
|
||||
```
|
||||
The CronTab "my-new-cron-object" is invalid:
|
||||
* spec: Invalid value: map[string]interface {}{"maxReplicas":10, "minReplicas":0, "replicas":20}: failed rule: self.replicas <= self.maxReplicas
|
||||
@@ -782,16 +799,19 @@ The request of CRDs create/update will fail if compilation of validation rules f
|
||||
Compilation process includes type checking as well.
|
||||
|
||||
The compilation failure:
|
||||
|
||||
- `no_matching_overload`: this function has no overload for the types of the arguments.
|
||||
|
||||
e.g. Rule like `self == true` against a field of integer type will get error:
|
||||
e.g. Rule like `self == true` against a field of integer type will get error:
|
||||
|
||||
```
|
||||
Invalid value: apiextensions.ValidationRule{Rule:"self == true", Message:""}: compilation failed: ERROR: \<input>:1:6: found no matching overload for '_==_' applied to '(int, bool)'
|
||||
```
|
||||
|
||||
- `no_such_field`: does not contain the desired field.
|
||||
|
||||
e.g. Rule like `self.nonExistingField > 0` against a non-existing field will return the error:
|
||||
e.g. Rule like `self.nonExistingField > 0` against a non-existing field will return the error:
|
||||
|
||||
```
|
||||
Invalid value: apiextensions.ValidationRule{Rule:"self.nonExistingField > 0", Message:""}: compilation failed: ERROR: \<input>:1:5: undefined field 'nonExistingField'
|
||||
```
|
||||
@@ -799,11 +819,11 @@ The compilation failure:
|
||||
- `invalid argument`: invalid argument to macros.
|
||||
|
||||
e.g. Rule like `has(self)` will return error:
|
||||
|
||||
```
|
||||
Invalid value: apiextensions.ValidationRule{Rule:"has(self)", Message:""}: compilation failed: ERROR: <input>:1:4: invalid argument to has() macro
|
||||
```
|
||||
|
||||
|
||||
Validation Rules Examples:
|
||||
|
||||
| Rule | Purpose |
|
||||
@@ -995,16 +1015,18 @@ Here is the declarations type mapping between OpenAPIv3 and CEL type:
|
||||
| 'string' with format=datetime | timestamp (google.protobuf.Timestamp) |
|
||||
| 'string' with format=duration | duration (google.protobuf.Duration) |
|
||||
|
||||
xref: [CEL types](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef.md#values), [OpenAPI
|
||||
types](https://swagger.io/specification/#data-types), [Kubernetes Structural Schemas](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema).
|
||||
xref: [CEL types](https://github.com/google/cel-spec/blob/v0.6.0/doc/langdef.md#values),
|
||||
[OpenAPI types](https://swagger.io/specification/#data-types),
|
||||
[Kubernetes Structural Schemas](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema).
|
||||
|
||||
#### Validation functions {#available-validation-functions}
|
||||
|
||||
Functions available include:
|
||||
- CEL standard functions, defined in the [list of standard definitions](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#list-of-standard-definitions)
|
||||
- CEL standard [macros](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#macros)
|
||||
- CEL [extended string function library](https://pkg.go.dev/github.com/google/cel-go@v0.11.2/ext#Strings)
|
||||
- Kubernetes [CEL extension library](https://pkg.go.dev/k8s.io/apiextensions-apiserver@v0.24.0/pkg/apiserver/schema/cel/library#pkg-functions)
|
||||
|
||||
- CEL standard functions, defined in the [list of standard definitions](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#list-of-standard-definitions)
|
||||
- CEL standard [macros](https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md#macros)
|
||||
- CEL [extended string function library](https://pkg.go.dev/github.com/google/cel-go@v0.11.2/ext#Strings)
|
||||
- Kubernetes [CEL extension library](https://pkg.go.dev/k8s.io/apiextensions-apiserver@v0.24.0/pkg/apiserver/schema/cel/library#pkg-functions)
|
||||
|
||||
#### Transition rules
|
||||
|
||||
@@ -1039,7 +1061,8 @@ applied, e.g. "*path*: update rule *rule* cannot be set on schema because the sc
|
||||
schema is not mergeable".
|
||||
|
||||
Transition rules are only allowed on _correlatable portions_ of a schema.
|
||||
A portion of the schema is correlatable if all `array` parent schemas are of type `x-kubernetes-list-type=map`; any `set`or `atomic`array parent schemas make it impossible to unambiguously correlate a `self` with `oldSelf`.
|
||||
A portion of the schema is correlatable if all `array` parent schemas are of type `x-kubernetes-list-type=map`;
|
||||
any `set`or `atomic`array parent schemas make it impossible to unambiguously correlate a `self` with `oldSelf`.
|
||||
|
||||
Here are some examples for transition rules:
|
||||
|
||||
@@ -1071,12 +1094,13 @@ For example, a rule that asserts that `self.foo == 1` does not by itself have an
|
||||
risk of rejection on validation resource budget groups.
|
||||
But if `foo` is a string and you define a validation rule `self.foo.contains("someString")`, that rule takes
|
||||
longer to execute depending on how long `foo` is.
|
||||
Another example would be if `foo` were an array, and you specified a validation rule `self.foo.all(x, x > 5)`. The cost system always assumes the worst-case scenario if
|
||||
a limit on the length of `foo` is not given, and this will happen for anything that can be iterated
|
||||
over (lists, maps, etc.).
|
||||
Another example would be if `foo` were an array, and you specified a validation rule `self.foo.all(x, x > 5)`.
|
||||
The cost system always assumes the worst-case scenario if a limit on the length of `foo` is not
|
||||
given, and this will happen for anything that can be iterated over (lists, maps, etc.).
|
||||
|
||||
Because of this, it is considered best practice to put a limit via `maxItems`, `maxProperties`, and
|
||||
`maxLength` for anything that will be processed in a validation rule in order to prevent validation errors during cost estimation. For example, given this schema with one rule:
|
||||
`maxLength` for anything that will be processed in a validation rule in order to prevent validation
|
||||
errors during cost estimation. For example, given this schema with one rule:
|
||||
|
||||
```yaml
|
||||
openAPIV3Schema:
|
||||
@@ -1091,10 +1115,11 @@ openAPIV3Schema:
|
||||
```
|
||||
|
||||
then the API server rejects this rule on validation budget grounds with error:
|
||||
|
||||
```
|
||||
spec.validation.openAPIV3Schema.properties[spec].properties[foo].x-kubernetes-validations[0].rule: Forbidden:
|
||||
CEL rule exceeded budget by more than 100x (try simplifying the rule, or adding maxItems, maxProperties, and
|
||||
maxLength where arrays, maps, and strings are used)
|
||||
spec.validation.openAPIV3Schema.properties[spec].properties[foo].x-kubernetes-validations[0].rule: Forbidden:
|
||||
CEL rule exceeded budget by more than 100x (try simplifying the rule, or adding maxItems, maxProperties, and
|
||||
maxLength where arrays, maps, and strings are used)
|
||||
```
|
||||
|
||||
The rejection happens because `self.all` implies calling `contains()` on every string in `foo`,
|
||||
@@ -1137,7 +1162,8 @@ openAPIV3Schema:
|
||||
```
|
||||
|
||||
If a list inside of a list has a validation rule that uses `self.all`, that is significantly more expensive
|
||||
than a non-nested list with the same rule. A rule that would have been allowed on a non-nested list might need lower limits set on both nested lists in order to be allowed. For example, even without having limits set,
|
||||
than a non-nested list with the same rule. A rule that would have been allowed on a non-nested list might need
|
||||
lower limits set on both nested lists in order to be allowed. For example, even without having limits set,
|
||||
the following rule is allowed:
|
||||
|
||||
```yaml
|
||||
@@ -1248,15 +1274,20 @@ Defaulting happens on the object
|
||||
* when reading from etcd using the storage version defaults,
|
||||
* after mutating admission plugins with non-empty patches using the admission webhook object version defaults.
|
||||
|
||||
Defaults applied when reading data from etcd are not automatically written back to etcd. An update request via the API is required to persist those defaults back into etcd.
|
||||
Defaults applied when reading data from etcd are not automatically written back to etcd.
|
||||
An update request via the API is required to persist those defaults back into etcd.
|
||||
|
||||
Default values must be pruned (with the exception of defaults for `metadata` fields) and must validate against a provided schema.
|
||||
|
||||
Default values for `metadata` fields of `x-kubernetes-embedded-resources: true` nodes (or parts of a default value covering `metadata`) are not pruned during CustomResourceDefinition creation, but through the pruning step during handling of requests.
|
||||
Default values for `metadata` fields of `x-kubernetes-embedded-resources: true` nodes (or parts of
|
||||
a default value covering `metadata`) are not pruned during CustomResourceDefinition creation, but
|
||||
through the pruning step during handling of requests.
|
||||
|
||||
#### Defaulting and Nullable
|
||||
|
||||
**New in 1.20:** null values for fields that either don't specify the nullable flag, or give it a `false` value, will be pruned before defaulting happens. If a default is present, it will be applied. When nullable is `true`, null values will be conserved and won't be defaulted.
|
||||
**New in 1.20:** null values for fields that either don't specify the nullable flag, or give it a
|
||||
`false` value, will be pruned before defaulting happens. If a default is present, it will be
|
||||
applied. When nullable is `true`, null values will be conserved and won't be defaulted.
|
||||
|
||||
For example, given the OpenAPI schema below:
|
||||
|
||||
@@ -1294,13 +1325,20 @@ spec:
|
||||
bar: null
|
||||
```
|
||||
|
||||
with `foo` pruned and defaulted because the field is non-nullable, `bar` maintaining the null value due to `nullable: true`, and `baz` pruned because the field is non-nullable and has no default.
|
||||
with `foo` pruned and defaulted because the field is non-nullable, `bar` maintaining the null
|
||||
value due to `nullable: true`, and `baz` pruned because the field is non-nullable and has no
|
||||
default.
|
||||
|
||||
### Publish Validation Schema in OpenAPI v2
|
||||
|
||||
CustomResourceDefinition [OpenAPI v3 validation schemas](#validation) which are [structural](#specifying-a-structural-schema) and [enable pruning](#field-pruning) are published as part of the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions) from Kubernetes API server.
|
||||
CustomResourceDefinition [OpenAPI v3 validation schemas](#validation) which are
|
||||
[structural](#specifying-a-structural-schema) and [enable pruning](#field-pruning) are published
|
||||
as part of the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions)
|
||||
from Kubernetes API server.
|
||||
|
||||
The [kubectl](/docs/reference/kubectl/) command-line tool consumes the published schema to perform client-side validation (`kubectl create` and `kubectl apply`), schema explanation (`kubectl explain`) on custom resources. The published schema can be consumed for other purposes as well, like client generation or documentation.
|
||||
The [kubectl](/docs/reference/kubectl/) command-line tool consumes the published schema to perform
|
||||
client-side validation (`kubectl create` and `kubectl apply`), schema explanation (`kubectl explain`)
|
||||
on custom resources. The published schema can be consumed for other purposes as well, like client generation or documentation.
|
||||
|
||||
The OpenAPI v3 validation schema is converted to OpenAPI v2 schema, and
|
||||
show up in `definitions` and `paths` fields in the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions).
|
||||
@@ -1310,9 +1348,13 @@ kubectl in previous 1.13 version. These modifications prevent kubectl from being
|
||||
valid OpenAPI schemas that it doesn't understand. The conversion won't modify the validation schema defined in CRD,
|
||||
and therefore won't affect [validation](#validation) in the API server.
|
||||
|
||||
1. The following fields are removed as they aren't supported by OpenAPI v2 (in future versions OpenAPI v3 will be used without these restrictions)
|
||||
1. The following fields are removed as they aren't supported by OpenAPI v2
|
||||
(in future versions OpenAPI v3 will be used without these restrictions)
|
||||
|
||||
- The fields `allOf`, `anyOf`, `oneOf` and `not` are removed
|
||||
2. If `nullable: true` is set, we drop `type`, `nullable`, `items` and `properties` because OpenAPI v2 is not able to express nullable. To avoid kubectl to reject good objects, this is necessary.
|
||||
|
||||
2. If `nullable: true` is set, we drop `type`, `nullable`, `items` and `properties` because OpenAPI v2 is
|
||||
not able to express nullable. To avoid kubectl to reject good objects, this is necessary.
|
||||
|
||||
### Additional printer columns
|
||||
|
||||
@@ -1403,7 +1445,8 @@ differentiates between columns shown in standard view or wide view (using the `-
|
||||
|
||||
#### Type
|
||||
|
||||
A column's `type` field can be any of the following (compare [OpenAPI v3 data types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes)):
|
||||
A column's `type` field can be any of the following (compare
|
||||
[OpenAPI v3 data types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes)):
|
||||
|
||||
- `integer` – non-floating-point numbers
|
||||
- `number` – floating point numbers
|
||||
@@ -1496,8 +1539,9 @@ the status replica value in the `/scale` subresource will default to 0.
|
||||
- It must be set to work with HPA.
|
||||
- Only JSONPaths under `.status` or `.spec` and with the dot notation are allowed.
|
||||
- If there is no value under the `labelSelectorPath` in the custom resource,
|
||||
the status selector value in the `/scale` subresource will default to the empty string.
|
||||
- The field pointed by this JSON path must be a string field (not a complex selector struct) which contains a serialized label selector in string form.
|
||||
the status selector value in the `/scale` subresource will default to the empty string.
|
||||
- The field pointed by this JSON path must be a string field (not a complex selector struct)
|
||||
which contains a serialized label selector in string form.
|
||||
|
||||
In the following example, both status and scale subresources are enabled.
|
||||
|
||||
@@ -1704,3 +1748,4 @@ crontabs/my-new-cron-object 3s
|
||||
|
||||
* Serve [multiple versions](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/) of a
|
||||
CustomResourceDefinition.
|
||||
|
||||
|
||||
@@ -13,7 +13,8 @@ CronJobs was promoted to general availability in Kubernetes v1.21. If you are us
|
||||
Kubernetes, please refer to the documentation for the version of Kubernetes that you are using,
|
||||
so that you see accurate information. Older Kubernetes versions do not support the `batch/v1` CronJob API.
|
||||
|
||||
You can use a {{< glossary_tooltip text="CronJob" term_id="cronjob" >}} to run {{< glossary_tooltip text="Jobs" term_id="job" >}} on a time-based schedule.
|
||||
You can use a {{< glossary_tooltip text="CronJob" term_id="cronjob" >}} to run {{< glossary_tooltip text="Jobs" term_id="job" >}}
|
||||
on a time-based schedule.
|
||||
These automated jobs run like [Cron](https://en.wikipedia.org/wiki/Cron) tasks on a Linux or UNIX system.
|
||||
|
||||
Cron jobs are useful for creating periodic and recurring tasks, like running backups or sending emails.
|
||||
@@ -87,6 +88,7 @@ You can stop watching the job and view the cron job again to see that it schedul
|
||||
```shell
|
||||
kubectl get cronjob hello
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
```
|
||||
@@ -94,7 +96,8 @@ NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE
|
||||
hello */1 * * * * False 0 50s 75s
|
||||
```
|
||||
|
||||
You should see that the cron job `hello` successfully scheduled a job at the time specified in `LAST SCHEDULE`. There are currently 0 active jobs, meaning that the job has completed or failed.
|
||||
You should see that the cron job `hello` successfully scheduled a job at the time specified in
|
||||
`LAST SCHEDULE`. There are currently 0 active jobs, meaning that the job has completed or failed.
|
||||
|
||||
Now, find the pods that the last scheduled job created and view the standard output of one of the pods.
|
||||
|
||||
@@ -127,7 +130,7 @@ kubectl delete cronjob hello
|
||||
```
|
||||
|
||||
Deleting the cron job removes all the jobs and pods it created and stops it from creating additional jobs.
|
||||
You can read more about removing jobs in [garbage collection](/docs/concepts/workloads/controllers/garbage-collection/).
|
||||
You can read more about removing jobs in [garbage collection](/docs/concepts/architecture/garbage-collection/).
|
||||
|
||||
## Writing a Cron Job Spec
|
||||
|
||||
@@ -144,7 +147,8 @@ All modifications to a cron job, especially its `.spec`, are applied only to the
|
||||
### Schedule
|
||||
|
||||
The `.spec.schedule` is a required field of the `.spec`.
|
||||
It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format string, such as `0 * * * *` or `@hourly`, as schedule time of its jobs to be created and executed.
|
||||
It takes a [Cron](https://en.wikipedia.org/wiki/Cron) format string, such as `0 * * * *` or `@hourly`,
|
||||
as schedule time of its jobs to be created and executed.
|
||||
|
||||
The format also includes extended "Vixie cron" step values. As explained in the
|
||||
[FreeBSD manual](https://www.freebsd.org/cgi/man.cgi?crontab%285%29):
|
||||
@@ -157,13 +161,15 @@ The format also includes extended "Vixie cron" step values. As explained in the
|
||||
> asterisk, so if you want to say "every two hours", just use `*/2`.
|
||||
|
||||
{{< note >}}
|
||||
A question mark (`?`) in the schedule has the same meaning as an asterisk `*`, that is, it stands for any of available value for a given field.
|
||||
A question mark (`?`) in the schedule has the same meaning as an asterisk `*`, that is,
|
||||
it stands for any of available value for a given field.
|
||||
{{< /note >}}
|
||||
|
||||
### Job Template
|
||||
|
||||
The `.spec.jobTemplate` is the template for the job, and it is required.
|
||||
It has exactly the same schema as a [Job](/docs/concepts/workloads/controllers/job/), except that it is nested and does not have an `apiVersion` or `kind`.
|
||||
It has exactly the same schema as a [Job](/docs/concepts/workloads/controllers/job/), except that
|
||||
it is nested and does not have an `apiVersion` or `kind`.
|
||||
For information about writing a job `.spec`, see [Writing a Job Spec](/docs/concepts/workloads/controllers/job/#writing-a-job-spec).
|
||||
|
||||
### Starting Deadline
|
||||
@@ -188,8 +194,10 @@ It specifies how to treat concurrent executions of a job that is created by this
|
||||
The spec may specify only one of the following concurrency policies:
|
||||
|
||||
* `Allow` (default): The cron job allows concurrently running jobs
|
||||
* `Forbid`: The cron job does not allow concurrent runs; if it is time for a new job run and the previous job run hasn't finished yet, the cron job skips the new job run
|
||||
* `Replace`: If it is time for a new job run and the previous job run hasn't finished yet, the cron job replaces the currently running job run with a new job run
|
||||
* `Forbid`: The cron job does not allow concurrent runs; if it is time for a new job run and the
|
||||
previous job run hasn't finished yet, the cron job skips the new job run
|
||||
* `Replace`: If it is time for a new job run and the previous job run hasn't finished yet, the
|
||||
cron job replaces the currently running job run with a new job run
|
||||
|
||||
Note that concurrency policy only applies to the jobs created by the same cron job.
|
||||
If there are multiple cron jobs, their respective jobs are always allowed to run concurrently.
|
||||
@@ -203,13 +211,15 @@ Defaults to false.
|
||||
|
||||
{{< caution >}}
|
||||
Executions that are suspended during their scheduled time count as missed jobs.
|
||||
When `.spec.suspend` changes from `true` to `false` on an existing cron job without a [starting deadline](#starting-deadline), the missed jobs are scheduled immediately.
|
||||
When `.spec.suspend` changes from `true` to `false` on an existing cron job without a
|
||||
[starting deadline](#starting-deadline), the missed jobs are scheduled immediately.
|
||||
{{< /caution >}}
|
||||
|
||||
### Jobs History Limits
|
||||
|
||||
The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields are optional.
|
||||
These fields specify how many completed and failed jobs should be kept.
|
||||
By default, they are set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping none of the corresponding kind of jobs after they finish.
|
||||
By default, they are set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping
|
||||
none of the corresponding kind of jobs after they finish.
|
||||
|
||||
|
||||
|
||||
@@ -161,7 +161,7 @@ Configurations with a single API server will experience unavailability while the
|
||||
|
||||
1. Check the logs from control plane components, along with the kubelet and the kube-proxy.
|
||||
Ensure those components are not reporting any TLS errors; see
|
||||
[looking at the logs](/docs/tasks/debug-application-cluster/debug-cluster/#looking-at-logs) for more details.
|
||||
[looking at the logs](/docs/tasks/debug/debug-cluster/#looking-at-logs) for more details.
|
||||
|
||||
1. Validate logs from any aggregated api servers and pods using in-cluster config.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user