whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/kubernetes/website into fix-restart-always-docs

Browse Source
This commit is contained in:
Marcin Niemira
2020-04-21 19:04:13 +10:00
parent 67abb1b5ff ebf3d178c4
commit df2204ffd0
257 changed files with 14004 additions and 10733 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/tasks/access-application-cluster/ingress-minikube.md
+2 -2
View File
@@ -66,7 +66,7 @@ This page shows you how to set up a simple Ingress which routes requests to Serv
1. Create a Deployment using the following command:
```shell
kubectl run web --image=gcr.io/google-samples/hello-app:1.0 --port=8080
kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0 --port=8080
```
Output:
@@ -78,7 +78,7 @@ This page shows you how to set up a simple Ingress which routes requests to Serv
1. Expose the Deployment:
```shell
kubectl expose deployment web --target-port=8080 --type=NodePort
kubectl expose deployment web --type=NodePort --port=8080
```
Output:
content/en/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md
+4 -5
View File
@@ -251,15 +251,14 @@ The name of an APIService object must be a valid
#### Contacting the extension apiserver
Once the Kubernetes apiserver has determined a request should be sent to a extension apiserver,
Once the Kubernetes apiserver has determined a request should be sent to an extension apiserver,
it needs to know how to contact it.
The `service` stanza is a reference to the service for a extension apiserver.
The `service` stanza is a reference to the service for an extension apiserver.
The service namespace and name are required. The port is optional and defaults to 443.
The path is optional and defaults to "/".
Here is an example of an extension apiserver that is configured to be called on port "1234"
at the subpath "/my-path", and to verify the TLS connection against the ServerName
Here is an example of an extension apiserver that is configured to be called on port "1234",
and to verify the TLS connection against the ServerName
`my-service-name.my-service-namespace.svc` using a custom CA bundle.
```yaml
content/en/docs/tasks/administer-cluster/dns-debugging-resolution.md
+1 -1
View File
@@ -56,7 +56,7 @@ Take a look inside the resolv.conf file.
[Known issues](#known-issues) below for more information)
```shell
kubectl exec dnsutils cat /etc/resolv.conf
kubectl exec -ti dnsutils -- cat /etc/resolv.conf
```
Verify that the search path and name server are set up like the following
content/en/docs/tasks/administer-cluster/kms-provider.md
+43 -45
View File
@@ -79,20 +79,20 @@ To encrypt the data:
1. Create a new encryption configuration file using the appropriate properties for the `kms` provider:
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- kms:
name: myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
timeout: 3s
- identity: {}
```
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- kms:
name: myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
timeout: 3s
- identity: {}
```
2. Set the `--encryption-provider-config` flag on the kube-apiserver to point to the location of the configuration file.
3. Restart your API server.
@@ -135,22 +135,22 @@ To switch from a local encryption provider to the `kms` provider and re-encrypt
1. Add the `kms` provider as the first entry in the configuration file as shown in the following example.
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- kms:
name : myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
- aescbc:
keys:
- name: key1
secret: <BASE 64 ENCODED SECRET>
```
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- kms:
name : myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
- aescbc:
keys:
- name: key1
secret: <BASE 64 ENCODED SECRET>
```
2. Restart all kube-apiserver processes.
@@ -165,24 +165,22 @@ To disable encryption at rest:
1. Place the `identity` provider as the first entry in the configuration file:
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- identity: {}
- kms:
name : myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
```
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- identity: {}
- kms:
name : myKmsPlugin
endpoint: unix:///tmp/socketfile.sock
cachesize: 100
```
2. Restart all kube-apiserver processes.
3. Run the following command to force all secrets to be decrypted.
```
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
{{% /capture %}}
content/en/docs/tasks/administer-cluster/topology-manager.md
+41 -12
View File
@@ -6,6 +6,7 @@ reviewers:
- klueska
- lmdaly
- nolancon
- bg-chun
content_template: templates/task
min-kubernetes-server-version: v1.18
@@ -13,7 +14,7 @@ min-kubernetes-server-version: v1.18
{{% capture overview %}}
{{< feature-state state="beta" >}}
{{< feature-state state="beta" for_k8s_version="v1.18" >}}
An increasing number of systems leverage a combination of CPUs and hardware accelerators to support latency-critical execution and high-throughput parallel computation. These include workloads in fields such as telecommunications, scientific computing, machine learning, financial services and data analytics. Such hybrid systems comprise a high performance environment.
@@ -53,11 +54,16 @@ Support for the Topology Manager requires `TopologyManager` [feature gate](/docs
The Topology Manager currently:
- Works on Nodes with the `static` CPU Manager Policy enabled. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/)
- Works on Pods making CPU requests or Device requests via extended resources
- Aligns Pods of all QoS classes.
- Aligns the requested resources that Hint Provider provides topology hints for.
If these conditions are met, Topology Manager will align the requested resources.
{{< note >}}
To align CPU resources with other requested resources in a Pod Spec, the CPU Manager should be enabled and proper CPU Manager policy should be configured on a Node. See [control CPU Management Policies](/docs/tasks/administer-cluster/cpu-management-policies/).
{{< /note >}}
Topology Manager supports four allocation policies. You can set a policy via a Kubelet flag, `--topology-manager-policy`.
There are four supported policies:
@@ -72,7 +78,7 @@ This is the default policy and does not perform any topology alignment.
### best-effort policy {#policy-best-effort}
For each container in a Guaranteed Pod, kubelet, with `best-effort` topology
For each container in a Pod, the kubelet, with `best-effort` topology
management policy, calls each Hint Provider to discover their resource availability.
Using this information, the Topology Manager stores the
preferred NUMA Node affinity for that container. If the affinity is not preferred,
@@ -83,7 +89,7 @@ resource allocation decision.
### restricted policy {#policy-restricted}
For each container in a Guaranteed Pod, kubelet, with `restricted` topology
For each container in a Pod, the kubelet, with `restricted` topology
management policy, calls each Hint Provider to discover their resource availability.
Using this information, the Topology Manager stores the
preferred NUMA Node affinity for that container. If the affinity is not preferred,
@@ -97,7 +103,7 @@ resource allocation decision.
### single-numa-node policy {#policy-single-numa-node}
For each container in a Guaranteed Pod, kubelet, with `single-numa-node` topology
For each container in a Pod, the kubelet, with `single-numa-node` topology
management policy, calls each Hint Provider to discover their resource availability.
Using this information, the Topology Manager determines if a single NUMA Node affinity is possible.
If it is, Topology Manager will store this and the *Hint Providers* can then use this information when making the
@@ -135,8 +141,7 @@ spec:
This pod runs in the `Burstable` QoS class because requests are less than limits.
If the selected policy is anything other than `none` , Topology Manager would not consider either of these Pod
specifications.
If the selected policy is anything other than `none`, Topology Manager would consider these Pod specifications. The Topology Manager would consult the Hint Providers to get topology hints. In the case of the `static`, the CPU Manager policy would return default topology hint, because these Pods do not have explicity request CPU resources.
```yaml
@@ -155,7 +160,26 @@ spec:
example.com/device: "1"
```
This pod runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
This pod with integer CPU request runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
```yaml
spec:
containers:
- name: nginx
image: nginx
resources:
limits:
memory: "200Mi"
cpu: "300m"
example.com/device: "1"
requests:
memory: "200Mi"
cpu: "300m"
example.com/device: "1"
```
This pod with sharing CPU request runs in the `Guaranteed` QoS class because `requests` are equal to `limits`.
```yaml
@@ -173,10 +197,15 @@ spec:
```
This pod runs in the `BestEffort` QoS class because there are no CPU and memory requests.
The Topology Manager would consider both of the above pods. The Topology Manager would consult the Hint Providers, which are CPU and Device Manager to get topology hints for the pods.
In the case of the `Guaranteed` pod the `static` CPU Manager policy would return hints relating to the CPU request and the Device Manager would send back hints for the requested device.
The Topology Manager would consider the above pods. The Topology Manager would consult the Hint Providers, which are CPU and Device Manager to get topology hints for the pods.
In the case of the `BestEffort` pod the CPU Manager would send back the default hint as there is no CPU request and the Device Manager would send back the hints for each of the requested devices.
In the case of the `Guaranteed` pod with integer CPU request, the `static` CPU Manager policy would return topology hints relating to the exclusive CPU and the Device Manager would send back hints for the requested device.
In the case of the `Guaranteed` pod with sharing CPU request, the `static` CPU Manager policy would return default topology hint as there is no exclusive CPU request and the Device Manager would send back hints for the requested device.
In the above two cases of the `Guaranteed` pod, the `none` CPU Manager policy would return default topology hint.
In the case of the `BestEffort` pod, the `static` CPU Manager policy would send back the default topology hint as there is no CPU request and the Device Manager would send back the hints for each of the requested devices.
Using this information the Topology Manager calculates the optimal hint for the pod and stores this information, which will be used by the Hint Providers when they are making their resource assignments.
content/en/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md
+1 -1
View File
@@ -49,7 +49,7 @@ In this exercise, you create a Pod that runs a container based on the
In the configuration file, you can see that the Pod has a single `Container`.
The `periodSeconds` field specifies that the kubelet should perform a liveness
probe every 5 seconds. The `initialDelaySeconds` field tells the kubelet that it
should wait 5 second before performing the first probe. To perform a probe, the
should wait 5 seconds before performing the first probe. To perform a probe, the
kubelet executes the command `cat /tmp/healthy` in the target container. If the
command succeeds, it returns 0, and the kubelet considers the container to be alive and
healthy. If the command returns a non-zero value, the kubelet kills the container
content/en/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md
+1 -1
View File
@@ -94,7 +94,7 @@ worker node, but it can't run on that machine. Again, the information from
### My pod is crashing or otherwise unhealthy
Once your pod has been scheduled, the methods described in [Debug Running Pods](
/docs/tasks/debug-application-cluster/debug-running-pods/) are available for debugging.
/docs/tasks/debug-application-cluster/debug-running-pod/) are available for debugging.
## Debugging ReplicationControllers
content/en/docs/tasks/job/parallel-processing-expansion.md
+164 -73
View File
@@ -1,52 +1,70 @@
---
title: Parallel Processing using Expansions
content_template: templates/concept
content_template: templates/task
min-kubernetes-server-version: v1.8
weight: 20
---
{{% capture overview %}}
In this example, we will run multiple Kubernetes Jobs created from
a common template. You may want to be familiar with the basic,
non-parallel, use of [Jobs](/docs/concepts/workloads/controllers/jobs-run-to-completion/) first.
This task demonstrates running multiple {{< glossary_tooltip text="Jobs" term_id="job" >}}
based on a common template. You can use this approach to process batches of work in
parallel.
For this example there are only three items: _apple_, _banana_, and _cherry_.
The sample Jobs process each item simply by printing a string then pausing.
See [using Jobs in real workloads](#using-jobs-in-real-workloads) to learn about how
this pattern fits more realistic use cases.
{{% /capture %}}
{{% capture prerequisites %}}
You should be familiar with the basic,
non-parallel, use of [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/).
{{< include "task-tutorial-prereqs.md" >}}
For basic templating you need the command-line utility `sed`.
To follow the advanced templating example, you need a working installation of
[Python](https://www.python.org/), and the Jinja2 template
library for Python.
Once you have Python set up, you can install Jinja2 by running:
```shell
pip install --user jinja2
```
{{% /capture %}}
{{% capture body %}}
{{% capture steps %}}
## Basic Template Expansion
## Create Jobs based on a template
First, download the following template of a job to a file called `job-tmpl.yaml`
First, download the following template of a Job to a file called `job-tmpl.yaml`.
Here's what you'll download:
{{< codenew file="application/job/job-tmpl.yaml" >}}
Unlike a *pod template*, our *job template* is not a Kubernetes API type. It is just
a yaml representation of a Job object that has some placeholders that need to be filled
in before it can be used. The `$ITEM` syntax is not meaningful to Kubernetes.
```shell
# Use curl to download job-tmpl.yaml
curl -L -s -O https://k8s.io/examples/application/job/job-tmpl.yaml
```
In this example, the only processing the container does is to `echo` a string and sleep for a bit.
In a real use case, the processing would be some substantial computation, such as rendering a frame
of a movie, or processing a range of rows in a database. The `$ITEM` parameter would specify for
example, the frame number or the row range.
The file you downloaded is not yet a valid Kubernetes
{{< glossary_tooltip text="manifest" term_id="manifest" >}}.
Instead that template is a YAML representation of a Job object with some placeholders
that need to be filled in before it can be used. The `$ITEM` syntax is not meaningful to Kubernetes.
This Job and its Pod template have a label: `jobgroup=jobexample`. There is nothing special
to the system about this label. This label
makes it convenient to operate on all the jobs in this group at once.
We also put the same label on the pod template so that we can check on all Pods of these Jobs
with a single command.
After the job is created, the system will add more labels that distinguish one Job's pods
from another Job's pods.
Note that the label key `jobgroup` is not special to Kubernetes. You can pick your own label scheme.
Next, expand the template into multiple files, one for each item to be processed.
### Create manifests from the template
The following shell snippet uses `sed` to replace the string `$ITEM` with the loop
variable, writing into a temporary directory named `jobs`. Run this now:
```shell
# Download job-templ.yaml
curl -L -s -O https://k8s.io/examples/application/job/job-tmpl.yaml
# Expand files into a temporary directory
# Expand the template into multiple files, one for each item to be processed.
mkdir ./jobs
for i in apple banana cherry
do
@@ -68,11 +86,12 @@ job-banana.yaml
job-cherry.yaml
```
Here, we used `sed` to replace the string `$ITEM` with the loop variable.
You could use any type of template language (jinja2, erb) or write a program
to generate the Job objects.
You could use any type of template language (for example: Jinja2; ERB), or
write a program to generate the Job manifests.
Next, create all the jobs with one kubectl command:
### Create Jobs from the manifests
Next, create all the Jobs with one kubectl command:
```shell
kubectl create -f ./jobs
@@ -96,22 +115,23 @@ The output is similar to this:
```
NAME COMPLETIONS DURATION AGE
process-item-apple 1/1 14s 20s
process-item-banana 1/1 12s 20s
process-item-apple 1/1 14s 22s
process-item-banana 1/1 12s 21s
process-item-cherry 1/1 12s 20s
```
Here we use the `-l` option to select all jobs that are part of this
group of jobs. (There might be other unrelated jobs in the system that we
do not care to see.)
Using the `-l` option to kubectl selects only the Jobs that are part
of this group of jobs (there might be other unrelated jobs in the system).
You can check on the Pods as well using the same
{{< glossary_tooltip text="label selector" term_id="selector" >}}:
We can check on the pods as well using the same label selector:
```shell
kubectl get pods -l jobgroup=jobexample
```
The output is similar to this:
The output is similar to:
```
NAME READY STATUS RESTARTS AGE
@@ -126,7 +146,7 @@ We can use this single command to check on the output of all jobs at once:
kubectl logs -f -l jobgroup=jobexample
```
The output is:
The output should be:
```
Processing item apple
@@ -134,26 +154,40 @@ Processing item banana
Processing item cherry
```
## Multiple Template Parameters
### Clean up {#cleanup-1}
In the first example, each instance of the template had one parameter, and that parameter was also
used as a label. However label keys are limited in [what characters they can
contain](/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set).
```shell
# Remove the Jobs you created
# Your cluster automatically cleans up their Pods
kubectl delete job -l jobgroup=jobexample
```
This slightly more complex example uses the jinja2 template language to generate our objects.
We will use a one-line python script to convert the template to a file.
## Use advanced template parameters
In the [first example](#create-jobs-based-on-a-template), each instance of the template had one
parameter, and that parameter was also used in the Job's name. However,
[names](/docs/concepts/overview/working-with-objects/names/#names) are restricted
to contain only certain characters.
This slightly more complex example uses the
[Jinja template language](https://palletsprojects.com/p/jinja/) to generate manifests
and then objects from those manifests, with a multiple parameters for each Job.
For this part of the task, you are going to use a one-line Python script to
convert the template to a set of manifests.
First, copy and paste the following template of a Job object, into a file called `job.yaml.jinja2`:
```liquid
{%- set params = [{ "name": "apple", "url": "https://www.orangepippin.com/varieties/apples", },
{ "name": "banana", "url": "https://en.wikipedia.org/wiki/Banana", },
{ "name": "raspberry", "url": "https://www.raspberrypi.org/" }]
{%- set params = [{ "name": "apple", "url": "http://dbpedia.org/resource/Apple", },
{ "name": "banana", "url": "http://dbpedia.org/resource/Banana", },
{ "name": "cherry", "url": "http://dbpedia.org/resource/Cherry" }]
%}
{%- for p in params %}
{%- set name = p["name"] %}
{%- set url = p["url"] %}
---
apiVersion: batch/v1
kind: Job
metadata:
@@ -172,51 +206,108 @@ spec:
image: busybox
command: ["sh", "-c", "echo Processing URL {{ url }} && sleep 5"]
restartPolicy: Never
---
{%- endfor %}
```
The above template defines parameters for each job object using a list of
python dicts (lines 1-4). Then a for loop emits one job yaml object
for each set of parameters (remaining lines).
We take advantage of the fact that multiple yaml documents can be concatenated
with the `---` separator (second to last line).
.) We can pipe the output directly to kubectl to
create the objects.
The above template defines two parameters for each Job object using a list of
python dicts (lines 1-4). A `for` loop emits one Job manifest for each
set of parameters (remaining lines).
You will need the jinja2 package if you do not already have it: `pip install --user jinja2`.
Now, use this one-line python program to expand the template:
This example relies on a feature of YAML. One YAML file can contain multiple
documents (Kubernetes manifests, in this case), separated by `---` on a line
by itself.
You can pipe the output directly to `kubectl` to create the Jobs.
Next, use this one-line Python program to expand the template:
```shell
alias render_template='python -c "from jinja2 import Template; import sys; print(Template(sys.stdin.read()).render());"'
```
The output can be saved to a file, like this:
Use `render_template` to convert the parameters and template into a single
YAML file containing Kubernetes manifests:
```shell
# This requires the alias you defined earlier
cat job.yaml.jinja2 | render_template > jobs.yaml
```
Or sent directly to kubectl, like this:
You can view `jobs.yaml` to verify that the `render_template` script worked
correctly.
Once you are happy that `render_template` is working how you intend,
you can pipe its output into `kubectl`:
```shell
cat job.yaml.jinja2 | render_template | kubectl apply -f -
```
## Alternatives
Kubernetes accepts and runs the Jobs you created.
If you have a large number of job objects, you may find that:
### Clean up {#cleanup-2}
- Even using labels, managing so many Job objects is cumbersome.
- You exceed resource quota when creating all the Jobs at once,
and do not want to wait to create them incrementally.
- Very large numbers of jobs created at once overload the
Kubernetes apiserver, controller, or scheduler.
In this case, you can consider one of the
other [job patterns](/docs/concepts/jobs/run-to-completion-finite-workloads/#job-patterns).
```shell
# Remove the Jobs you created
# Your cluster automatically cleans up their Pods
kubectl delete job -l jobgroup=jobexample
```
{{% /capture %}}
{{% capture discussion %}}
## Using Jobs in real workloads
In a real use case, each Job performs some substantial computation, such as rendering a frame
of a movie, or processing a range of rows in a database. If you were rendering a movie
you would set `$ITEM` to the frame number. If you were processing rows from a database
table, you would set `$ITEM` to represent the range of database rows to process.
In the task, you ran a command to collect the output from Pods by fetching
their logs. In a real use case, each Pod for a Job writes its output to
durable storage before completing. You can use a PersistentVolume for each Job,
or an external storage service. For example, if you are rendering frames for a movie,
use HTTP to `PUT` the rendered frame data to a URL, using a different URL for each
frame.
## Labels on Jobs and Pods
After you create a Job, Kubernetes automatically adds additional
{{< glossary_tooltip text="labels" term_id="label" >}} that
distinguish one Job's pods from another Job's pods.
In this example, each Job and its Pod template have a label:
`jobgroup=jobexample`.
Kubernetes itself pays no attention to labels named `jobgroup`. Setting a label
for all the Jobs you create from a template makes it convenient to operate on all
those Jobs at once.
In the [first example](#create-jobs-based-on-a-template) you used a template to
create several Jobs. The template ensures that each Pod also gets the same label, so
you can check on all Pods for these templated Jobs with a single command.
{{< note >}}
The label key `jobgroup` is not special or reserved.
You can pick your own labelling scheme.
There are [recommended labels](/docs/concepts/overview/working-with-objects/common-labels/#labels)
that you can use if you wish.
{{< /note >}}
## Alternatives
If you plan to create a large number of Job objects, you may find that:
- Even using labels, managing so many Jobs is cumbersome.
- If you create many Jobs in a batch, you might place high load
on the Kubernetes control plane. Alternatively, the Kubernetes API
server could rate limit you, temporarily rejecting your requests with a 429 status.
- You are limited by a {{< glossary_tooltip text="resource quota" term_id="resource-quota" >}}
on Jobs: the API server permanently rejects some of your requests
when you create a great deal of work in one batch.
There are other [job patterns](/docs/concepts/jobs/run-to-completion-finite-workloads/#job-patterns)
that you can use to process large amounts of work without creating very many Job
objects.
You could also consider writing your own [controller](/docs/concepts/architecture/controller/)
to manage Job objects automatically.
{{% /capture %}}
content/en/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md
+1 -1
View File
@@ -239,7 +239,7 @@ the only other supported resource metric is memory. These resources do not chan
to cluster, and should always be available, as long as the `metrics.k8s.io` API is available.
You can also specify resource metrics in terms of direct values, instead of as percentages of the
requested value, by using a `target` type of `AverageValue` instead of `AverageUtilization`, and
requested value, by using a `target.type` of `AverageValue` instead of `Utilization`, and
setting the corresponding `target.averageValue` field instead of the `target.averageUtilization`.
There are two other types of metrics, both of which are considered *custom metrics*: pod metrics and
content/en/docs/tasks/run-application/run-stateless-application-deployment.md
+2 -2
View File
@@ -88,11 +88,11 @@ a Deployment that runs the nginx:1.14.2 Docker image:
nginx-deployment-1771418926-7o5ns 1/1 Running 0 16h
nginx-deployment-1771418926-r18az 1/1 Running 0 16h
1. Display information about a pod:
1. Display information about a Pod:
kubectl describe pod <pod-name>
where `<pod-name>` is the name of one of your pods.
where `<pod-name>` is the name of one of your Pods.
## Updating the deployment