Merge pull request #16225 from simplytunde/merged-master-dev-1.16
Merged master into dev-1.16
This commit is contained in:
Kubernetes Prow Robot
@@ -224,13 +224,14 @@ rules:
|
||||
|
||||
The following cloud providers have implemented CCMs:
|
||||
|
||||
* [Digital Ocean](https://github.com/digitalocean/digitalocean-cloud-controller-manager)
|
||||
* [Oracle](https://github.com/oracle/oci-cloud-controller-manager)
|
||||
* [Azure](https://github.com/kubernetes/cloud-provider-azure)
|
||||
* [GCP](https://github.com/kubernetes/cloud-provider-gcp)
|
||||
* [AWS](https://github.com/kubernetes/cloud-provider-aws)
|
||||
* [Azure](https://github.com/kubernetes/cloud-provider-azure)
|
||||
* [BaiduCloud](https://github.com/baidu/cloud-provider-baiducloud)
|
||||
* [Digital Ocean](https://github.com/digitalocean/digitalocean-cloud-controller-manager)
|
||||
* [GCP](https://github.com/kubernetes/cloud-provider-gcp)
|
||||
* [Linode](https://github.com/linode/linode-cloud-controller-manager)
|
||||
* [OpenStack](https://github.com/kubernetes/cloud-provider-openstack)
|
||||
* [Oracle](https://github.com/oracle/oci-cloud-controller-manager)
|
||||
|
||||
## Cluster Administration
|
||||
|
||||
|
||||
@@ -120,9 +120,6 @@ Node affinity is like the existing `nodeSelector` (but with the first two benefi
|
||||
while inter-pod affinity/anti-affinity constrains against pod labels rather than node labels, as
|
||||
described in the third item listed above, in addition to having the first and second properties listed above.
|
||||
|
||||
`nodeSelector` continues to work as usual, but will eventually be deprecated, as node affinity can express
|
||||
everything that `nodeSelector` can express.
|
||||
|
||||
### Node affinity
|
||||
|
||||
Node affinity is conceptually similar to `nodeSelector` -- it allows you to constrain which nodes your
|
||||
|
||||
@@ -142,7 +142,7 @@ When using Docker:
|
||||
- The `spec.containers[].resources.requests.cpu` is converted to its core value,
|
||||
which is potentially fractional, and multiplied by 1024. The greater of this number
|
||||
or 2 is used as the value of the
|
||||
[`--cpu-shares`](https://docs.docker.com/engine/reference/run/#/cpu-share-constraint)
|
||||
[`--cpu-shares`](https://docs.docker.com/engine/reference/run/#cpu-share-constraint)
|
||||
flag in the `docker run` command.
|
||||
|
||||
- The `spec.containers[].resources.limits.cpu` is converted to its millicore value and
|
||||
|
||||
@@ -69,7 +69,7 @@ detail:
|
||||
to provide durable database storage, a StatefulSet to run SampleDB and
|
||||
a Job to handle initial configuration.
|
||||
* If you delete it, the Operator takes a snapshot, then makes sure that
|
||||
the the StatefulSet and Volumes are also removed.
|
||||
the StatefulSet and Volumes are also removed.
|
||||
6. The operator also manages regular database backups. For each SampleDB
|
||||
resource, the operator determines when to create a Pod that can connect
|
||||
to the database and take backups. These Pods would rely on a ConfigMap
|
||||
|
||||
@@ -81,7 +81,7 @@ Kubernetes:
|
||||
* Does not dictate logging, monitoring, or alerting solutions. It provides some integrations as proof of concept, and mechanisms to collect and export metrics.
|
||||
* Does not provide nor mandate a configuration language/system (for example, jsonnet). It provides a declarative API that may be targeted by arbitrary forms of declarative specifications.
|
||||
* Does not provide nor adopt any comprehensive machine configuration, maintenance, management, or self-healing systems.
|
||||
* Additionally, Kubernetes is not a mere orchestration system. In fact, it eliminates the need for orchestration. The technical definition of orchestration is execution of a defined workflow: first do A, then B, then C. In contrast, Kubernetes is comprised of a set of independent, composable control processes that continuously drive the current state towards the provided desired state. It shouldn’t matter how you get from A to C. Centralized control is also not required. This results in a system that is easier to use and more powerful, robust, resilient, and extensible.
|
||||
* Additionally, Kubernetes is not a mere orchestration system. In fact, it eliminates the need for orchestration. The technical definition of orchestration is execution of a defined workflow: first do A, then B, then C. In contrast, Kubernetes comprises a set of independent, composable control processes that continuously drive the current state towards the provided desired state. It shouldn’t matter how you get from A to C. Centralized control is also not required. This results in a system that is easier to use and more powerful, robust, resilient, and extensible.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -1,382 +1,382 @@
|
||||
---
|
||||
reviewers:
|
||||
- nelvadas
|
||||
title: Limit Ranges
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
By default, containers run with unbounded [compute resources](/docs/user-guide/compute-resources) on a Kubernetes cluster.
|
||||
With Resource quotas, cluster administrators can restrict the resource consumption and creation on a namespace basis.
|
||||
Within a namespace, a Pod or Container can consume as much CPU and memory as defined by the namespace's resource quota. There is a concern that one Pod or Container could monopolize all of the resources. Limit Range is a policy to constrain resource by Pod or Container in a namespace.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
A limit range, defined by a `LimitRange` object, provides constraints that can:
|
||||
|
||||
- Enforce minimum and maximum compute resources usage per Pod or Container in a namespace.
|
||||
- Enforce minimum and maximum storage request per PersistentVolumeClaim in a namespace.
|
||||
- Enforce a ratio between request and limit for a resource in a namespace.
|
||||
- Set default request/limit for compute resources in a namespace and automatically inject them to Containers at runtime.
|
||||
|
||||
## Enabling Limit Range
|
||||
|
||||
Limit Range support is enabled by default for many Kubernetes distributions. It is
|
||||
enabled when the apiserver `--enable-admission-plugins=` flag has `LimitRanger` admission controller as
|
||||
one of its arguments.
|
||||
|
||||
A limit range is enforced in a particular namespace when there is a
|
||||
`LimitRange` object in that namespace.
|
||||
|
||||
### Overview of Limit Range:
|
||||
|
||||
- The administrator creates one `LimitRange` in one namespace.
|
||||
- Users create resources like Pods, Containers, and PersistentVolumeClaims in the namespace.
|
||||
- The `LimitRanger` admission controller enforces defaults limits for all Pods and Container that do not set compute resource requirements and tracks usage to ensure it does not exceed resource minimum , maximum and ratio defined in any `LimitRange` present in the namespace.
|
||||
- If creating or updating a resource (Pod, Container, PersistentVolumeClaim) violates a limit range constraint, the request to the API server will fail with HTTP status code `403 FORBIDDEN` and a message explaining the constraint that would have been violated.
|
||||
- If limit range is activated in a namespace for compute resources like `cpu` and `memory`, users must specify
|
||||
requests or limits for those values; otherwise, the system may reject pod creation.
|
||||
- LimitRange validations occurs only at Pod Admission stage, not on Running pods.
|
||||
|
||||
|
||||
Examples of policies that could be created using limit range are:
|
||||
|
||||
- In a 2 node cluster with a capacity of 8 GiB RAM, and 16 cores, constrain Pods in a namespace to request 100m and not exceeds 500m for CPU , request 200Mi and not exceed 600Mi
|
||||
- Define default CPU limits and request to 150m and Memory default request to 300Mi for containers started with no cpu and memory requests in their spec.
|
||||
|
||||
In the case where the total limits of the namespace is less than the sum of the limits of the Pods/Containers,
|
||||
there may be contention for resources; The Containers or Pods will not be created.
|
||||
|
||||
Neither contention nor changes to limitrange will affect already created resources.
|
||||
|
||||
## Limiting Container compute resources
|
||||
|
||||
The following section discusses the creation of a LimitRange acting at Container Level.
|
||||
A Pod with 04 containers is first created; each container within the Pod has a specific `spec.resource` configuration
|
||||
each containerwithin the pod is handled differently by the LimitRanger admission controller.
|
||||
|
||||
Create a namespace `limitrange-demo` using the following kubectl command
|
||||
|
||||
```shell
|
||||
kubectl create namespace limitrange-demo
|
||||
```
|
||||
|
||||
To avoid passing the target limitrange-demo in your kubectl commands, change your context with the following command
|
||||
|
||||
```shell
|
||||
kubectl config set-context --current --namespace=limitrange-demo
|
||||
```
|
||||
|
||||
Here is the configuration file for a LimitRange object:
|
||||
{{< codenew file="admin/resource/limit-mem-cpu-container.yaml" >}}
|
||||
|
||||
This object defines minimum and maximum Memory/CPU limits, default cpu/Memory requests and default limits for CPU/Memory resources to be apply to containers.
|
||||
|
||||
Create the `limit-mem-cpu-per-container` LimitRange in the `limitrange-demo` namespace with the following kubectl command.
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/limit-mem-cpu-container.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
```shell
|
||||
kubectl describe limitrange/limit-mem-cpu-per-container -n limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
```shell
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Container cpu 100m 800m 110m 700m -
|
||||
Container memory 99Mi 1Gi 111Mi 900Mi -
|
||||
```
|
||||
|
||||
|
||||
|
||||
Here is the configuration file for a Pod with 04 containers to demonstrate LimitRange features :
|
||||
{{< codenew file="admin/resource/limit-range-pod-1.yaml" >}}
|
||||
|
||||
Create the `busybox1` Pod :
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-1.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
### Container spec with valid CPU/Memory requests and limits
|
||||
View the the `busybox-cnt01` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[0].resources"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "100m",
|
||||
"memory": "100Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt01` Container inside `busybox` Pod defined `requests.cpu=100m` and `requests.memory=100Mi`.
|
||||
- `100m <= 500m <= 800m` , The container cpu limit (500m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 200Mi <= 1Gi` , The container memory limit (200Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio validation for CPU/Memory , thus the container is valid and created.
|
||||
|
||||
|
||||
### Container spec with a valid CPU/Memory requests but no limits
|
||||
|
||||
View the `busybox-cnt02` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[1].resources"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "700m",
|
||||
"memory": "900Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "100m",
|
||||
"memory": "100Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
- The `busybox-cnt02` Container inside `busybox1` Pod defined `requests.cpu=100m` and `requests.memory=100Mi` but not limits for cpu and memory.
|
||||
- The container do not have a limits section, the default limits defined in the limit-mem-cpu-per-container LimitRange object are injected to this container `limits.cpu=700mi` and `limits.memory=900Mi`.
|
||||
- `100m <= 700m <= 800m` , The container cpu limit (700m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 900Mi <= 1Gi` , The container memory limit (900Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
|
||||
### Container spec with a valid CPU/Memory limits but no requests
|
||||
View the `busybox-cnt03` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[2].resources"
|
||||
```
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt03` Container inside `busybox1` Pod defined `limits.cpu=500m` and `limits.memory=200Mi` but no `requests` for cpu and memory.
|
||||
- The container do not define a request section, the defaultRequest defined in the limit-mem-cpu-per-container LimitRange is not used to fill its limits section but the limits defined by the container are set as requests `limits.cpu=500m` and `limits.memory=200Mi`.
|
||||
- `100m <= 500m <= 800m` , The container cpu limit (500m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 200Mi <= 1Gi` , The container memory limit (200Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
|
||||
|
||||
### Container spec with no CPU/Memory requests/limits
|
||||
View the `busybox-cnt04` resource configuration
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[3].resources"
|
||||
```
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "700m",
|
||||
"memory": "900Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "110m",
|
||||
"memory": "111Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt04` Container inside `busybox1` define neither `limits` nor `requests`.
|
||||
- The container do not define a limit section, the default limit defined in the limit-mem-cpu-per-container LimitRange is used to fill its request
|
||||
`limits.cpu=700m and` `limits.memory=900Mi` .
|
||||
- The container do not define a request section, the defaultRequest defined in the limit-mem-cpu-per-container LimitRange is used to fill its request section requests.cpu=110m and requests.memory=111Mi
|
||||
- `100m <= 700m <= 800m` , The container cpu limit (700m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 900Mi <= 1Gi` , The container memory limit (900Mi) falls inside the authorized Memory limitrange .
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
All containers defined in the `busybox` Pod passed LimitRange validations, this the Pod is valid and create in the namespace.
|
||||
|
||||
## Limiting Pod compute resources
|
||||
The following section discusses how to constrain resources at Pod level.
|
||||
|
||||
{{< codenew file="admin/resource/limit-mem-cpu-pod.yaml" >}}
|
||||
|
||||
Without having to delete `busybox1` Pod, create the `limit-mem-cpu-pod` LimitRange in the `limitrange-demo` namespace
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-mem-cpu-pod.yaml -n limitrange-demo
|
||||
```
|
||||
The limitrange is created and limits CPU to 2 Core and Memory to 2Gi per Pod.
|
||||
```shell
|
||||
limitrange/limit-mem-cpu-per-pod created
|
||||
```
|
||||
Describe the `limit-mem-cpu-per-pod` limit object using the following kubectl command
|
||||
```shell
|
||||
kubectl describe limitrange/limit-mem-cpu-per-pod
|
||||
```
|
||||
|
||||
```shell
|
||||
Name: limit-mem-cpu-per-pod
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Pod cpu - 2 - - -
|
||||
Pod memory - 2Gi - - -
|
||||
```
|
||||
Now create the `busybox2` Pod.
|
||||
|
||||
{{< codenew file="admin/resource/limit-range-pod-2.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-2.yaml -n limitrange-demo
|
||||
```
|
||||
The `busybox2` Pod definition is identical to `busybox1` but an error is reported since Pod's resources are now limited
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "limit-range-pod-2.yaml": pods "busybox2" is forbidden: [maximum cpu usage per Pod is 2, but limit is 2400m., maximum memory usage per Pod is 2Gi, but limit is 2306867200.]
|
||||
```
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[].resources.limits.memory"
|
||||
"200Mi"
|
||||
"900Mi"
|
||||
"200Mi"
|
||||
"900Mi"
|
||||
```
|
||||
`busybox2` Pod will not be admitted on the cluster since the total memory limit of its container is greater than the limit defined in the LimitRange.
|
||||
`busybox1` will not be evicted since it was created and admitted on the cluster before the LimitRange creation.
|
||||
|
||||
|
||||
## Limiting Storage resources
|
||||
|
||||
You can enforce minimum and maximum size of [storage resources](/docs/concepts/storage/persistent-volumes/) that can be requested by each PersistentVolumeClaim in a namespace using a LimitRange.
|
||||
|
||||
{{< codenew file="admin/resource/storagelimits.yaml" >}}
|
||||
|
||||
Apply the YAML using `kubectl create`.
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/storagelimits.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
```shell
|
||||
limitrange/storagelimits created
|
||||
```
|
||||
Describe the created object,
|
||||
|
||||
```shell
|
||||
kubectl describe limits/storagelimits
|
||||
```
|
||||
the output should look like
|
||||
|
||||
```shell
|
||||
Name: storagelimits
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
PersistentVolumeClaim storage 1Gi 2Gi - - -
|
||||
```
|
||||
|
||||
{{< codenew file="admin/resource/pvc-limit-lower.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource//pvc-limit-lower.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
While creating a PVC with `requests.storage` lower than the Min value in the LimitRange, an Error thrown by the server
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "pvc-limit-lower.yaml": persistentvolumeclaims "pvc-limit-lower" is forbidden: minimum storage usage per PersistentVolumeClaim is 1Gi, but request is 500Mi.
|
||||
```
|
||||
|
||||
Same behaviour is noted if the `requests.storage` is greater than the Max value in the LimitRange
|
||||
|
||||
{{< codenew file="admin/resource/pvc-limit-greater.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/pvc-limit-greater.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "pvc-limit-greater.yaml": persistentvolumeclaims "pvc-limit-greater" is forbidden: maximum storage usage per PersistentVolumeClaim is 2Gi, but request is 5Gi.
|
||||
```
|
||||
|
||||
## Limits/Requests Ratio
|
||||
|
||||
If `LimitRangeItem.maxLimitRequestRatio` if specified in th `LimitRangeSpec`, the named resource must have a request and limit that are both non-zero where limit divided by request is less than or equal to the enumerated value
|
||||
|
||||
the following `LimitRange` enforces memory limit to be at most twice the amount of the memory request for any pod in the namespace.
|
||||
|
||||
{{< codenew file="admin/resource/limit-memory-ratio-pod.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-memory-ratio-pod.yaml
|
||||
```
|
||||
|
||||
Describe the <limit-memory-ratio-pod> LimitRange with the following kubectl command:
|
||||
|
||||
```shell
|
||||
$ kubectl describe limitrange/limit-memory-ratio-pod
|
||||
```
|
||||
|
||||
```shell
|
||||
Name: limit-memory-ratio-pod
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Pod memory - - - - 2
|
||||
```
|
||||
|
||||
|
||||
Let's create a pod with `requests.memory=100Mi` and `limits.memory=300Mi`
|
||||
{{< codenew file="admin/resource/limit-range-pod-3.yaml" >}}
|
||||
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-3.yaml
|
||||
```
|
||||
|
||||
The pod creation failed as the ratio here (`3`) is greater than the enforced limit (`2`) in `limit-memory-ratio-pod` LimitRange
|
||||
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "limit-range-pod-3.yaml": pods "busybox3" is forbidden: memory max limit to request ratio per Pod is 2, but provided ratio is 3.000000.
|
||||
```
|
||||
|
||||
|
||||
### Clean up
|
||||
Delete the `limitrange-demo` namespace to free all resources
|
||||
```shell
|
||||
kubectl delete ns limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
- See [a tutorial on how to limit compute resources per namespace](/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace/) .
|
||||
- Check [how to limit storage consumption](/docs/tasks/administer-cluster/limit-storage-consumption/#limitrange-to-limit-requests-for-storage).
|
||||
- See a [detailed example on quota per namespace](/docs/tasks/administer-cluster/quota-memory-cpu-namespace/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
See [LimitRanger design doc](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_limit_range.md) for more information.
|
||||
|
||||
{{% /capture %}}
|
||||
---
|
||||
reviewers:
|
||||
- nelvadas
|
||||
title: Limit Ranges
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
By default, containers run with unbounded [compute resources](/docs/user-guide/compute-resources) on a Kubernetes cluster.
|
||||
With Resource quotas, cluster administrators can restrict the resource consumption and creation on a namespace basis.
|
||||
Within a namespace, a Pod or Container can consume as much CPU and memory as defined by the namespace's resource quota. There is a concern that one Pod or Container could monopolize all of the resources. Limit Range is a policy to constrain resource by Pod or Container in a namespace.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
A limit range, defined by a `LimitRange` object, provides constraints that can:
|
||||
|
||||
- Enforce minimum and maximum compute resources usage per Pod or Container in a namespace.
|
||||
- Enforce minimum and maximum storage request per PersistentVolumeClaim in a namespace.
|
||||
- Enforce a ratio between request and limit for a resource in a namespace.
|
||||
- Set default request/limit for compute resources in a namespace and automatically inject them to Containers at runtime.
|
||||
|
||||
## Enabling Limit Range
|
||||
|
||||
Limit Range support is enabled by default for many Kubernetes distributions. It is
|
||||
enabled when the apiserver `--enable-admission-plugins=` flag has `LimitRanger` admission controller as
|
||||
one of its arguments.
|
||||
|
||||
A limit range is enforced in a particular namespace when there is a
|
||||
`LimitRange` object in that namespace.
|
||||
|
||||
### Overview of Limit Range:
|
||||
|
||||
- The administrator creates one `LimitRange` in one namespace.
|
||||
- Users create resources like Pods, Containers, and PersistentVolumeClaims in the namespace.
|
||||
- The `LimitRanger` admission controller enforces defaults limits for all Pods and Container that do not set compute resource requirements and tracks usage to ensure it does not exceed resource minimum , maximum and ratio defined in any `LimitRange` present in the namespace.
|
||||
- If creating or updating a resource (Pod, Container, PersistentVolumeClaim) violates a limit range constraint, the request to the API server will fail with HTTP status code `403 FORBIDDEN` and a message explaining the constraint that would have been violated.
|
||||
- If limit range is activated in a namespace for compute resources like `cpu` and `memory`, users must specify
|
||||
requests or limits for those values; otherwise, the system may reject pod creation.
|
||||
- LimitRange validations occurs only at Pod Admission stage, not on Running pods.
|
||||
|
||||
|
||||
Examples of policies that could be created using limit range are:
|
||||
|
||||
- In a 2 node cluster with a capacity of 8 GiB RAM, and 16 cores, constrain Pods in a namespace to request 100m and not exceeds 500m for CPU , request 200Mi and not exceed 600Mi
|
||||
- Define default CPU limits and request to 150m and Memory default request to 300Mi for containers started with no cpu and memory requests in their spec.
|
||||
|
||||
In the case where the total limits of the namespace is less than the sum of the limits of the Pods/Containers,
|
||||
there may be contention for resources; The Containers or Pods will not be created.
|
||||
|
||||
Neither contention nor changes to limitrange will affect already created resources.
|
||||
|
||||
## Limiting Container compute resources
|
||||
|
||||
The following section discusses the creation of a LimitRange acting at Container Level.
|
||||
A Pod with 04 containers is first created; each container within the Pod has a specific `spec.resource` configuration
|
||||
each containerwithin the pod is handled differently by the LimitRanger admission controller.
|
||||
|
||||
Create a namespace `limitrange-demo` using the following kubectl command
|
||||
|
||||
```shell
|
||||
kubectl create namespace limitrange-demo
|
||||
```
|
||||
|
||||
To avoid passing the target limitrange-demo in your kubectl commands, change your context with the following command
|
||||
|
||||
```shell
|
||||
kubectl config set-context --current --namespace=limitrange-demo
|
||||
```
|
||||
|
||||
Here is the configuration file for a LimitRange object:
|
||||
{{< codenew file="admin/resource/limit-mem-cpu-container.yaml" >}}
|
||||
|
||||
This object defines minimum and maximum Memory/CPU limits, default cpu/Memory requests and default limits for CPU/Memory resources to be apply to containers.
|
||||
|
||||
Create the `limit-mem-cpu-per-container` LimitRange in the `limitrange-demo` namespace with the following kubectl command.
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/limit-mem-cpu-container.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
```shell
|
||||
kubectl describe limitrange/limit-mem-cpu-per-container -n limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
```shell
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Container cpu 100m 800m 110m 700m -
|
||||
Container memory 99Mi 1Gi 111Mi 900Mi -
|
||||
```
|
||||
|
||||
|
||||
|
||||
Here is the configuration file for a Pod with 04 containers to demonstrate LimitRange features :
|
||||
{{< codenew file="admin/resource/limit-range-pod-1.yaml" >}}
|
||||
|
||||
Create the `busybox1` Pod :
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-1.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
### Container spec with valid CPU/Memory requests and limits
|
||||
View the the `busybox-cnt01` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[0].resources"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "100m",
|
||||
"memory": "100Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt01` Container inside `busybox` Pod defined `requests.cpu=100m` and `requests.memory=100Mi`.
|
||||
- `100m <= 500m <= 800m` , The container cpu limit (500m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 200Mi <= 1Gi` , The container memory limit (200Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio validation for CPU/Memory , thus the container is valid and created.
|
||||
|
||||
|
||||
### Container spec with a valid CPU/Memory requests but no limits
|
||||
|
||||
View the `busybox-cnt02` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[1].resources"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "700m",
|
||||
"memory": "900Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "100m",
|
||||
"memory": "100Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
- The `busybox-cnt02` Container inside `busybox1` Pod defined `requests.cpu=100m` and `requests.memory=100Mi` but not limits for cpu and memory.
|
||||
- The container do not have a limits section, the default limits defined in the limit-mem-cpu-per-container LimitRange object are injected to this container `limits.cpu=700mi` and `limits.memory=900Mi`.
|
||||
- `100m <= 700m <= 800m` , The container cpu limit (700m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 900Mi <= 1Gi` , The container memory limit (900Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
|
||||
### Container spec with a valid CPU/Memory limits but no requests
|
||||
View the `busybox-cnt03` resource configuration
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[2].resources"
|
||||
```
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "500m",
|
||||
"memory": "200Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt03` Container inside `busybox1` Pod defined `limits.cpu=500m` and `limits.memory=200Mi` but no `requests` for cpu and memory.
|
||||
- The container do not define a request section, the defaultRequest defined in the limit-mem-cpu-per-container LimitRange is not used to fill its limits section but the limits defined by the container are set as requests `limits.cpu=500m` and `limits.memory=200Mi`.
|
||||
- `100m <= 500m <= 800m` , The container cpu limit (500m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 200Mi <= 1Gi` , The container memory limit (200Mi) falls inside the authorized Memory limit range.
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
|
||||
|
||||
### Container spec with no CPU/Memory requests/limits
|
||||
View the `busybox-cnt04` resource configuration
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[3].resources"
|
||||
```
|
||||
```json
|
||||
{
|
||||
"limits": {
|
||||
"cpu": "700m",
|
||||
"memory": "900Mi"
|
||||
},
|
||||
"requests": {
|
||||
"cpu": "110m",
|
||||
"memory": "111Mi"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- The `busybox-cnt04` Container inside `busybox1` define neither `limits` nor `requests`.
|
||||
- The container do not define a limit section, the default limit defined in the limit-mem-cpu-per-container LimitRange is used to fill its request
|
||||
`limits.cpu=700m and` `limits.memory=900Mi` .
|
||||
- The container do not define a request section, the defaultRequest defined in the limit-mem-cpu-per-container LimitRange is used to fill its request section requests.cpu=110m and requests.memory=111Mi
|
||||
- `100m <= 700m <= 800m` , The container cpu limit (700m) falls inside the authorized CPU limit range.
|
||||
- `99Mi <= 900Mi <= 1Gi` , The container memory limit (900Mi) falls inside the authorized Memory limitrange .
|
||||
- No request/limits ratio set , thus the container is valid and created.
|
||||
|
||||
All containers defined in the `busybox` Pod passed LimitRange validations, this the Pod is valid and create in the namespace.
|
||||
|
||||
## Limiting Pod compute resources
|
||||
The following section discusses how to constrain resources at Pod level.
|
||||
|
||||
{{< codenew file="admin/resource/limit-mem-cpu-pod.yaml" >}}
|
||||
|
||||
Without having to delete `busybox1` Pod, create the `limit-mem-cpu-pod` LimitRange in the `limitrange-demo` namespace
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-mem-cpu-pod.yaml -n limitrange-demo
|
||||
```
|
||||
The limitrange is created and limits CPU to 2 Core and Memory to 2Gi per Pod.
|
||||
```shell
|
||||
limitrange/limit-mem-cpu-per-pod created
|
||||
```
|
||||
Describe the `limit-mem-cpu-per-pod` limit object using the following kubectl command
|
||||
```shell
|
||||
kubectl describe limitrange/limit-mem-cpu-per-pod
|
||||
```
|
||||
|
||||
```shell
|
||||
Name: limit-mem-cpu-per-pod
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Pod cpu - 2 - - -
|
||||
Pod memory - 2Gi - - -
|
||||
```
|
||||
Now create the `busybox2` Pod.
|
||||
|
||||
{{< codenew file="admin/resource/limit-range-pod-2.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-2.yaml -n limitrange-demo
|
||||
```
|
||||
The `busybox2` Pod definition is identical to `busybox1` but an error is reported since Pod's resources are now limited
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "limit-range-pod-2.yaml": pods "busybox2" is forbidden: [maximum cpu usage per Pod is 2, but limit is 2400m., maximum memory usage per Pod is 2Gi, but limit is 2306867200.]
|
||||
```
|
||||
|
||||
```shell
|
||||
kubectl get po/busybox1 -n limitrange-demo -o json | jq ".spec.containers[].resources.limits.memory"
|
||||
"200Mi"
|
||||
"900Mi"
|
||||
"200Mi"
|
||||
"900Mi"
|
||||
```
|
||||
`busybox2` Pod will not be admitted on the cluster since the total memory limit of its container is greater than the limit defined in the LimitRange.
|
||||
`busybox1` will not be evicted since it was created and admitted on the cluster before the LimitRange creation.
|
||||
|
||||
|
||||
## Limiting Storage resources
|
||||
|
||||
You can enforce minimum and maximum size of [storage resources](/docs/concepts/storage/persistent-volumes/) that can be requested by each PersistentVolumeClaim in a namespace using a LimitRange.
|
||||
|
||||
{{< codenew file="admin/resource/storagelimits.yaml" >}}
|
||||
|
||||
Apply the YAML using `kubectl create`.
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/storagelimits.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
```shell
|
||||
limitrange/storagelimits created
|
||||
```
|
||||
Describe the created object,
|
||||
|
||||
```shell
|
||||
kubectl describe limits/storagelimits
|
||||
```
|
||||
the output should look like
|
||||
|
||||
```shell
|
||||
Name: storagelimits
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
PersistentVolumeClaim storage 1Gi 2Gi - - -
|
||||
```
|
||||
|
||||
{{< codenew file="admin/resource/pvc-limit-lower.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource//pvc-limit-lower.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
While creating a PVC with `requests.storage` lower than the Min value in the LimitRange, an Error thrown by the server
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "pvc-limit-lower.yaml": persistentvolumeclaims "pvc-limit-lower" is forbidden: minimum storage usage per PersistentVolumeClaim is 1Gi, but request is 500Mi.
|
||||
```
|
||||
|
||||
Same behaviour is noted if the `requests.storage` is greater than the Max value in the LimitRange
|
||||
|
||||
{{< codenew file="admin/resource/pvc-limit-greater.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl create -f https://k8s.io/examples/admin/resource/pvc-limit-greater.yaml -n limitrange-demo
|
||||
```
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "pvc-limit-greater.yaml": persistentvolumeclaims "pvc-limit-greater" is forbidden: maximum storage usage per PersistentVolumeClaim is 2Gi, but request is 5Gi.
|
||||
```
|
||||
|
||||
## Limits/Requests Ratio
|
||||
|
||||
If `LimitRangeItem.maxLimitRequestRatio` if specified in th `LimitRangeSpec`, the named resource must have a request and limit that are both non-zero where limit divided by request is less than or equal to the enumerated value
|
||||
|
||||
the following `LimitRange` enforces memory limit to be at most twice the amount of the memory request for any pod in the namespace.
|
||||
|
||||
{{< codenew file="admin/resource/limit-memory-ratio-pod.yaml" >}}
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-memory-ratio-pod.yaml
|
||||
```
|
||||
|
||||
Describe the <limit-memory-ratio-pod> LimitRange with the following kubectl command:
|
||||
|
||||
```shell
|
||||
$ kubectl describe limitrange/limit-memory-ratio-pod
|
||||
```
|
||||
|
||||
```shell
|
||||
Name: limit-memory-ratio-pod
|
||||
Namespace: limitrange-demo
|
||||
Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio
|
||||
---- -------- --- --- --------------- ------------- -----------------------
|
||||
Pod memory - - - - 2
|
||||
```
|
||||
|
||||
|
||||
Let's create a pod with `requests.memory=100Mi` and `limits.memory=300Mi`
|
||||
{{< codenew file="admin/resource/limit-range-pod-3.yaml" >}}
|
||||
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/admin/resource/limit-range-pod-3.yaml
|
||||
```
|
||||
|
||||
The pod creation failed as the ratio here (`3`) is greater than the enforced limit (`2`) in `limit-memory-ratio-pod` LimitRange
|
||||
|
||||
|
||||
```shell
|
||||
Error from server (Forbidden): error when creating "limit-range-pod-3.yaml": pods "busybox3" is forbidden: memory max limit to request ratio per Pod is 2, but provided ratio is 3.000000.
|
||||
```
|
||||
|
||||
|
||||
### Clean up
|
||||
Delete the `limitrange-demo` namespace to free all resources
|
||||
```shell
|
||||
kubectl delete ns limitrange-demo
|
||||
```
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
- See [a tutorial on how to limit compute resources per namespace](/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace/) .
|
||||
- Check [how to limit storage consumption](/docs/tasks/administer-cluster/limit-storage-consumption/#limitrange-to-limit-requests-for-storage).
|
||||
- See a [detailed example on quota per namespace](/docs/tasks/administer-cluster/quota-memory-cpu-namespace/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
See [LimitRanger design doc](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_limit_range.md) for more information.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -268,7 +268,7 @@ Expanding EBS volumes is a time consuming operation. Also, there is a per-volume
|
||||
* AzureDisk
|
||||
* CSI
|
||||
* FC (Fibre Channel)
|
||||
* Flexvolume
|
||||
* FlexVolume
|
||||
* Flocker
|
||||
* NFS
|
||||
* iSCSI
|
||||
|
||||
@@ -53,6 +53,7 @@ provisioner: kubernetes.io/aws-ebs
|
||||
parameters:
|
||||
type: gp2
|
||||
reclaimPolicy: Retain
|
||||
allowVolumeExpansion: true
|
||||
mountOptions:
|
||||
- debug
|
||||
volumeBindingMode: Immediate
|
||||
@@ -110,6 +111,31 @@ either `Delete` or `Retain`. If no `reclaimPolicy` is specified when a
|
||||
Persistent Volumes that are created manually and managed via a storage class will have
|
||||
whatever reclaim policy they were assigned at creation.
|
||||
|
||||
### Allow Volume Expansion
|
||||
|
||||
{{< feature-state for_k8s_version="v1.11" state="beta" >}}
|
||||
|
||||
Persistent Volumes can be configured to be expandable. This feature when set to `true`,
|
||||
allows the users to resize the volume by editing the corresponding PVC object.
|
||||
|
||||
The following types of volumes support volume expansion, when the underlying
|
||||
Storage Class has the field `allowVolumeExpansion` set to true.
|
||||
|
||||
* gcePersistentDisk
|
||||
* awsElasticBlockStore
|
||||
* Cinder
|
||||
* glusterfs
|
||||
* rbd
|
||||
* Azure File
|
||||
* Azure Disk
|
||||
* Portworx
|
||||
* FlexVolumes
|
||||
* CSI {{< feature-state for_k8s_version="v1.14" state="alpha" >}}
|
||||
|
||||
{{< note >}}
|
||||
This feature cannot be used to shrink volumes.
|
||||
{{< /note >}}
|
||||
|
||||
### Mount Options
|
||||
|
||||
Persistent Volumes that are dynamically created by a storage class will have the
|
||||
|
||||
@@ -15,10 +15,6 @@ weight: 40
|
||||
|
||||
StatefulSet is the workload API object used to manage stateful applications.
|
||||
|
||||
{{< note >}}
|
||||
StatefulSets are stable (GA) in 1.9.
|
||||
{{< /note >}}
|
||||
|
||||
{{< glossary_definition term_id="statefulset" length="all" >}}
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -43,7 +39,6 @@ provides a set of stateless replicas. Controllers such as
|
||||
|
||||
## Limitations
|
||||
|
||||
* StatefulSet was a beta resource prior to 1.9 and not available in any Kubernetes release prior to 1.5.
|
||||
* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin.
|
||||
* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the StatefulSet. This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources.
|
||||
* StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service.
|
||||
|
||||
@@ -62,7 +62,8 @@ yourself, but the project is better in the long term when we have a diversity of
|
||||
active participants.
|
||||
|
||||
Before you start reviewing PRs, make sure you are familiar with the
|
||||
[Documentation Style Guide](/docs/contribute/style/style-guide/)
|
||||
[Documentation Content Guide](/docs/contribute/style/content-guide/), the
|
||||
[Documentation Style Guide](/docs/contribute/style/style-guide/),
|
||||
and the [code of conduct](/community/code-of-conduct/).
|
||||
|
||||
### Find a PR to review
|
||||
|
||||
@@ -44,6 +44,15 @@ called SIG Docs. We [communicate](#participate-in-sig-docs-discussions) using a
|
||||
weekly video meetings. New participants are welcome. For more information, see
|
||||
[Participating in SIG Docs](/docs/contribute/participating/).
|
||||
|
||||
### Content guildelines
|
||||
|
||||
The SIG Docs community created guidelines about what kind of content is allowed
|
||||
in the Kubernetes documentation. Look over the [Documentation Content
|
||||
Guide](/docs/contribute/style/content-guide/) to determine if the content
|
||||
contribution you want to make is allowed. You can ask questions about allowed
|
||||
content in the [#sig-docs]((#participate-in-sig-docs-discussions)) Slack
|
||||
channel.
|
||||
|
||||
### Style guidelines
|
||||
|
||||
We maintain a [style guide](/docs/contribute/style/style-guide/) with information
|
||||
@@ -330,7 +339,7 @@ commercial in nature and should consist of content that will apply broadly to
|
||||
the Kubernetes community.
|
||||
|
||||
To submit a blog post, you can either submit it using the
|
||||
[Kubernetes blog submission form](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform),
|
||||
[Kubernetes blog submission form](https://docs.google.com/forms/d/e/1FAIpQLSdMpMoSIrhte5omZbTE7nB84qcGBy8XnnXhDFoW0h7p2zwXrw/viewform),
|
||||
or follow the steps below.
|
||||
|
||||
1. [Sign the CLA](#sign-the-cla) if you have not yet done so.
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Documentation Content Guide
|
||||
linktitle: Content guide
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
card:
|
||||
name: contribute
|
||||
weight: 20
|
||||
title: Documentation Content Guide
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page contains guidelines for adding content to the Kubernetes documentation.
|
||||
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask! Use your best judgment, and feel free to
|
||||
propose changes to this document in a pull request.
|
||||
|
||||
For additional information on creating new content for the Kubernetes
|
||||
docs, follow the instructions in the [Style guide](/docs/contribute/style/style-guide).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
## Contributing content
|
||||
|
||||
The Kubernetes documentation comprises the content of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) source repository.
|
||||
Located in the `kubernetes/website/content/<language_code>/docs` folder, the
|
||||
majority of the Kubernetes documentation is specific to the [Kubernetes
|
||||
project](https://github.com/kubernetes/kubernetes). The Kubernetes
|
||||
documentation may also include content from projects in the
|
||||
[kubernetes](https://github.com/kubernetes) and
|
||||
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations if
|
||||
those projects do not have their own documentation. Linking to active kubernetes,
|
||||
kubernetes-sigs, and ({{< glossary_tooltip text="CNCF" term_id="cncf" >}}) projects from the Kubernetes documentation is always
|
||||
allowed, but linking to vendor-specific products is not. Check the CNCF project lists
|
||||
([Graduated/Incubating](https://www.cncf.io/projects/),
|
||||
[Sandbox](https://www.cncf.io/sandbox-projects/),
|
||||
[Archived](https://www.cncf.io/archived-projects/)) if you are unsure of a
|
||||
project's CNCF status.
|
||||
|
||||
### Dual-sourced content
|
||||
|
||||
Kubernetes documentation does not include duplicate content sourced from multiple
|
||||
locations (*dual-sourced* content). Dual-sourced content requires duplicated
|
||||
effort from project maintainers and tends to become outdated more quickly.
|
||||
Before adding content, ask yourself this:
|
||||
|
||||
- Is the content about an active CNCF project OR a project in the kubernetes or kubernetes-sigs GitHub organizations?
|
||||
- If yes, then:
|
||||
- Does the project have its own documentation?
|
||||
- if yes, link to the project's documention from the Kubernetes documentation
|
||||
- if no, add the content to the project's repository if possible and then link to it from the Kubernetes documentation
|
||||
- If no, then:
|
||||
- Stop!
|
||||
- Adding content about vendor-specific products is not allowed
|
||||
- Linking to vendor-specific documentation and websites is not allowed
|
||||
|
||||
### What is and isn't allowed
|
||||
|
||||
There are some scenarios in which the Kubernetes documentation includes content from non-Kubernetes projects.
|
||||
Below are general categories of non-Kubernetes project content along with guidelines of what is and is not allowed:
|
||||
|
||||
1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes
|
||||
- Allowed:
|
||||
- Referring to or linking to existing documentation about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations
|
||||
- Example: for installating Kubernetes in a learning environment, including a prerequisite stating that successful installation and configuration of minikube is required and linking to the relevant minikube documentation
|
||||
- Adding content for kubernetes or kubernetes-sigs projects that don't have their own instructional content
|
||||
- Example: including [kubadm](https://github.com/kubernetes/kubeadm) installation and troubleshooting instructions
|
||||
- Not Allowed:
|
||||
- Adding content that duplicates documentation in another repository
|
||||
- Examples:
|
||||
- Including minikube installation and configuration instructions; minikube has its own [documentation](https://minikube.sigs.k8s.io/docs/) that provides those instructions
|
||||
- Including instructions for installing Docker, CRI-O, containerd, and other container runtimes on various operating systems
|
||||
- Including instructions for installing Kubernetes on production environments using various projects:
|
||||
- Kubernetes Rebar Integrated Bootstrap (KRIB) is a vendor-specific project and content belongs in the vendor's documentation
|
||||
- [Kubernetes Operations (kops)](https://github.com/kubernetes/kops) has installation instructions and tutorials in its GitHub repository
|
||||
- [Kubespray](https://kubespray.io) has its own documenation
|
||||
- Adding a tutorial that explains how to perform a task using a vendor-specific product or an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
|
||||
- Adding a tutorial on how to use a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations if the project has its own documentation
|
||||
1. Detailed technical content about how to use a non-Kubernetes project or how that project is designed
|
||||
|
||||
Adding this type of content to the Kubernetes documentation is not allowed.
|
||||
1. Content that describes a non-Kubernetes project
|
||||
- Allowed:
|
||||
- Adding a brief introductory paragraph about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations; the paragraph may contain links to the project
|
||||
- Not Allowed:
|
||||
- Adding content describing a vendor-specific product
|
||||
- Adding content describing an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
|
||||
- Adding content that duplicates documentation from another project, regardless of source repository
|
||||
- Example: adding [Kubernetes in Docker (KinD)](https://kind.sigs.k8s.io) documentation to the Kubernetes documentation
|
||||
1. Content that simply links to information about a non-Kubernetes project
|
||||
- Allowed:
|
||||
- Linking to projects in the kubernetes and kubernetes-sigs GitHub organizations
|
||||
- Example: linking to Kubernetes in Docker (KinD) [documentation](https://kind.sigs.k8s.io/docs/user/quick-start), which resides in the kubernetes-sigs GitHub organization
|
||||
- Linking to active CNCF projects
|
||||
- Example: linking to the Prometheus [documentation](https://prometheus.io/docs/introduction/overview/); Prometheus is an active CNCF project
|
||||
- Not Allowed:
|
||||
- Linking to vendor-specific products
|
||||
- Linking to archived CNCF projects
|
||||
- Linking to inactive projects in the kubernetes and kubernetes-sigs GitHub organizations
|
||||
- Linking to open source projects that are not CNCF projects or do not reside in the kubernetes or kubernetes-sigs GitHub organizations
|
||||
1. Content about training courses
|
||||
- Allowed:
|
||||
- Linking to vendor-neutral Kubernetes training courses offered by the [CNCF](https://www.cncf.io/), the [Linux Foundation](https://www.linuxfoundation.org/), and the [Linux Academy](https://linuxacademy.com/), which is a partner of the Linux Foundation
|
||||
- Example: linking to Linux Academy courses such as [Kubernetes Quick Start](https://linuxacademy.com/course/kubernetes-quick-start/) and [Kubernetes Security](https://linuxacademy.com/course/kubernetes-security/)
|
||||
- Not Allowed:
|
||||
- Linking to online training outside of the CNCF, the Linux Foundation, or the Linux Academy; the Kubernetes documentation does not link to third-party content
|
||||
- Example: linking to Kubernetes tutorials or courses on Medium, KodeKloud, Udacity, Coursera, learnk8s, and similar websites
|
||||
- Linking to vendor-specific tutorials regardless of the training provider
|
||||
- Example: linking to Linux Academy courses such as [Google Kubernetes Engine Deep Dive](https://linuxacademy.com/google-cloud-platform/training/course/name/google-kubernetes-engine-deep-dive) and [Amazon EKS Deep Dive](https://linuxacademy.com/course/amazon-eks-deep-dive/)
|
||||
|
||||
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask!
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* Read the [Style guide](/docs/contribute/style/style-guide).
|
||||
{{% /capture %}}
|
||||
@@ -14,10 +14,12 @@ This page gives writing style guidelines for the Kubernetes documentation.
|
||||
These are guidelines, not rules. Use your best judgment, and feel free to
|
||||
propose changes to this document in a pull request.
|
||||
|
||||
For additional information on creating new content for the Kubernetes
|
||||
docs, follow the instructions on
|
||||
[using page templates](/docs/contribute/style/page-templates/) and
|
||||
[creating a documentation pull request](/docs/contribute/start/#improve-existing-content).
|
||||
For additional information on creating new content for the Kubernetes
|
||||
documentation, read the [Documentation Content
|
||||
Guide](/docs/contribute/style/content-guide/) and follow the instructions on
|
||||
[using page templates](/docs/contribute/style/page-templates/) and [creating a
|
||||
documentation pull request](/docs/contribute/start/#improve-existing-content).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
@@ -53,14 +55,16 @@ PodTemplateList, not Pod Template List.
|
||||
Refer to API objects without saying "object," unless omitting "object"
|
||||
leads to an awkward construction.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
|
||||
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
|
||||
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
|
||||
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
|
||||
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - API objects" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
The Pod has two containers. | The pod has two containers.
|
||||
The Deployment is responsible for ... | The Deployment object is responsible for ...
|
||||
A PodList is a list of Pods. | A Pod List is a list of pods.
|
||||
The two ContainerPorts ... | The two ContainerPort objects ...
|
||||
The two ContainerStateTerminated objects ... | The two ContainerStateTerminateds ...
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
@@ -75,36 +79,40 @@ represents.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
|
||||
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Bold interface elements" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Click **Fork**. | Click "Fork".
|
||||
Select **Other**. | Select "Other".
|
||||
{{< /table >}}
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
|
||||
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
|
||||
</table>
|
||||
|
||||
{{< table caption = "Do and Don't - Use italics for new terms" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
A _cluster_ is a set of nodes ... | A "cluster" is a set of nodes ...
|
||||
These components form the _control plane_. | These components form the **control plane**.
|
||||
{{< /table >}}
|
||||
|
||||
### Use code style for filenames, directories, and paths
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
|
||||
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code><!--to-unbreak-atom-highlighting_--> file.</td><td>Open the /_data/concepts.yaml<!--to-unbreak-atom-highlighting_--> file.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use code style for filenames, directories, and paths" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Open the `envars.yaml` file. | Open the envars.yaml file.
|
||||
Go to the `/docs/tutorials` directory. | Go to the /docs/tutorials directory.
|
||||
Open the `/_data/concepts.yaml` file. | Open the /_data/concepts.yaml file.
|
||||
{{< /table >}}
|
||||
|
||||
### Use the international standard for punctuation inside quotes
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
|
||||
<tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use the international standard for punctuation inside quotes" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
events are recorded with an associated "stage". | events are recorded with an associated "stage."
|
||||
The copy is called a "fork". | The copy is called a "fork."
|
||||
{{< /table >}}
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
@@ -113,13 +121,17 @@ represents.
|
||||
For inline code in an HTML document, use the `<code>` tag. In a Markdown
|
||||
document, use the backtick (`).
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
|
||||
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
|
||||
<tr><td>Enclose code samples with triple backticks. <code>(```)</code></td><td>Enclose code samples with any other syntax.</td></tr>
|
||||
<tr><td>Use single backticks to enclose inline code. For example, `var example = true`.</td><td>Use two asterisks (**) or an underscore (_) to enclose inline code. For example, **var example = true**.</td></tr><tr><td>Use triple backticks before and after a multi-line block of code for fenced code blocks.</td><td>Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.</td></tr><tr><td>Use meaningful variable names that have a context.</td><td>Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.</td></tr><tr><td>Remove trailing spaces in the code.</td><td>Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use code style for inline code and commands" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
The `kubectl run`command creates a Deployment. | The "kubectl run" command creates a Deployment.
|
||||
For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply".
|
||||
Enclose code samples with triple backticks. `(```)`| Enclose code samples with any other syntax.
|
||||
Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (**) or an underscore (_) to enclose inline code. For example, **var example = true**.
|
||||
Use triple backticks before and after a multi-line block of code for fenced code blocks. | Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.
|
||||
Use meaningful variable names that have a context. | Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.
|
||||
Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.
|
||||
{{< /table >}}
|
||||
|
||||
{{< note >}}
|
||||
The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the [contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum)
|
||||
@@ -127,31 +139,36 @@ The website supports syntax highlighting for code samples, but specifying a lang
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
|
||||
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use code style for object field names" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file.
|
||||
The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object.
|
||||
{{< /table >}}
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
|
||||
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use normal style for string and integer field values" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Set the value of `imagePullPolicy` to Always. | Set the value of `imagePullPolicy` to "Always".
|
||||
Set the value of `image` to nginx:1.8. | Set the value of `image` to `nginx:1.8`.
|
||||
Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### Don't include the command prompt
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Don't include the command prompt" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
kubectl get pods | $ kubectl get pods
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Separate commands from output
|
||||
|
||||
@@ -198,13 +215,14 @@ kind: Pod
|
||||
|
||||
A list of Kubernetes-specific terms and words to be used consistently across the site.
|
||||
|
||||
<table>
|
||||
<tr><th>Term</th><th>Usage</th></tr>
|
||||
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
|
||||
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
|
||||
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
|
||||
<tr><td>On-premises</td><td>On-premises or On-prem rather than On-premise or other variations.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Kubernetes.io word list" >}}
|
||||
Term | Usage
|
||||
:--- | :----
|
||||
Kubernetes | Kubernetes should always be capitalized.
|
||||
Docker | Docker should always be capitalized.
|
||||
SIG Docs | SIG Docs rather than SIG-DOCS or other variations.
|
||||
On-premises | On-premises or On-prem rather than On-premise or other variations.
|
||||
{{< /table >}}
|
||||
|
||||
## Shortcodes
|
||||
|
||||
@@ -377,26 +395,33 @@ Use a single newline to separate block-level content like headings, lists, image
|
||||
### Headings
|
||||
People accessing this documentation may use a screen reader or other assistive technology (AT). [Screen readers](https://en.wikipedia.org/wiki/Screen_reader) are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Update the title in the front matter of the page or blog post.</td><td>Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.</td></tr><tr><td>Use ordered headings to provide a meaningful high-level outline of your content.</td><td>Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.</td>
|
||||
<tr><td>Use pound or hash signs (#) for non-blog post content.</td><td> Use underlines (--- or ===) to designate first-level headings.</td></tr>
|
||||
<tr><td>Use sentence case for headings. For example, <b>Extend kubectl with plugins</b></td><td>Use title case for headings. For example, <b>Extend Kubectl With Plugins</b></td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Headings" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Update the title in the front matter of the page or blog post. | Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.
|
||||
Use ordered headings to provide a meaningful high-level outline of your content. | Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.
|
||||
Use pound or hash signs (#) for non-blog post content. | Use underlines (--- or ===) to designate first-level headings.
|
||||
Use sentence case for headings. For example, **Extend kubectl with plugins** | Use title case for headings. For example, **Extend Kubectl With Plugins**
|
||||
{{< /table >}}
|
||||
|
||||
### Paragraphs
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Try to keep paragraphs under 6 sentences.</td><td>Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.</td></tr>
|
||||
<tr><td>Use three hyphens (---) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section.</td><td>Use horizontal rules for decoration.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Paragraphs" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Try to keep paragraphs under 6 sentences. | Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.
|
||||
Use three hyphens (---) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. | Use horizontal rules for decoration.
|
||||
{{< /table >}}
|
||||
|
||||
### Links
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See <a href="#check-required-ports">Check required ports</a> for more details.</td><td>Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See <a href="#check-required-ports">here</a> for more details.</td></tr> <tr><td>Write Markdown-style links ([link text](URL)). For example, <code>[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)</code> and the output is <a href="/docs/contribute/style/hugo-shortcodes/#table-captions">Hugo shortcodes.</td><td>Write HTML-style links <code>(<link href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!)</code> or create links that open in new tabs or windows. For example, <code>[example website](https://example.com){target="_blank"}</code></td></tr>
|
||||
</table>
|
||||
|
||||
{{< table caption = "Do and Don't - Links" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See <a href="#check-required-ports">Check required ports</a> for more details. | Use ambiguous terms such as “click here”. For example: Certain ports are open on your machines. See <a href="#check-required-ports">here</a> for more details.
|
||||
Write Markdown-style links: `[link text](URL)`. For example: `[Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions)` and the output is [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions). | Write HTML-style links: `<a href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!</a>`, or create links that open in new tabs or windows. For example: `[example website](https://example.com){target="_blank"}`
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Lists
|
||||
Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list.
|
||||
@@ -428,21 +453,25 @@ This section contains suggested best practices for clear, concise, and consisten
|
||||
|
||||
### Use present tense
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use present tense" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
This command starts a proxy. | This command will start a proxy.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
|
||||
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use active voice" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
You can explore the API using a browser. | The API can be explored using a browser.
|
||||
The YAML file specifies the replica count. | The replica count is specified in the YAML file.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
@@ -450,31 +479,35 @@ Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
|
||||
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
|
||||
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
|
||||
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Use simple and direct language" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
To create a ReplicaSet, ... | In order to create a ReplicaSet, ...
|
||||
See the configuration file. | Please see the configuration file.
|
||||
View the Pods. | With this next command, we'll view the Pods.
|
||||
{{< /table >}}
|
||||
|
||||
### Address the reader as "you"
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
|
||||
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Addressing the reader" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
You can create a Deployment by ... | We'll create a Deployment by ...
|
||||
In the preceding output, you can see... | In the preceding output, we can see ...
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Avoid Latin phrases
|
||||
|
||||
Prefer English terms over Latin abbreviations.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>For example, ...</td><td>e.g., ...</td></tr>
|
||||
<tr><td>That is, ...</td><td>i.e., ...</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Avoid Latin phrases" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
For example, ... | e.g., ...
|
||||
That is, ...| i.e., ...
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
Exception: Use "etc." for et cetera.
|
||||
|
||||
@@ -485,22 +518,26 @@ Exception: Use "etc." for et cetera.
|
||||
Using "we" in a sentence can be confusing, because the reader might not know
|
||||
whether they're part of the "we" you're describing.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
|
||||
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
|
||||
<tr><td>This page teaches you how to use Pods.</td><td>In this page, we are going to learn about Pods.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Patterns to avoid" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Version 1.4 includes ... | In version 1.4, we have added ...
|
||||
Kubernetes provides a new feature for ... | We provide a new feature ...
|
||||
This page teaches you how to use Pods. | In this page, we are going to learn about Pods.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
|
||||
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Avoid jargon and idioms" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
Internally, ... | Under the hood, ...
|
||||
Create a new cluster. | Turn up a new cluster.
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
@@ -513,11 +550,13 @@ information.
|
||||
Avoid words like "currently" and "new." A feature that is new today might not be
|
||||
considered new in a few months.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
|
||||
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
|
||||
</table>
|
||||
{{< table caption = "Do and Don't - Avoid statements that will soon be out of date" >}}
|
||||
Do | Don't
|
||||
:--| :-----
|
||||
In version 1.4, ... | In the current version, ...
|
||||
The Federation feature provides ... | The new Federation feature provides ...
|
||||
{{< /table >}}
|
||||
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
@@ -19,24 +19,13 @@ Create a fork of the Kubernetes documentation repository as described in
|
||||
|
||||
As you prepare to write a new topic, think about the page type that would fit your content the best:
|
||||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tutorial</td>
|
||||
<td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
{{< table caption = "Guidelines for choosing a page type" >}}
|
||||
Type | Description
|
||||
:--- | :----------
|
||||
Concept | A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.
|
||||
Task | A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a>
|
||||
Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
|
||||
{{< /table >}}
|
||||
|
||||
Use a template for each new page. Each page type has a
|
||||
[template](/docs/contribute/style/page-templates/)
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
# See the OWNERS docs at https://go.k8s.io/owners
|
||||
|
||||
reviewers:
|
||||
- errordeveloper
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: "Independent Solutions"
|
||||
weight: 50
|
||||
---
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
reviewers:
|
||||
- pwittrock
|
||||
title: Deprecated Alternatives
|
||||
---
|
||||
|
||||
# *Stop. These guides are superseded by [Minikube](../minikube/). They are only listed here for completeness.*
|
||||
|
||||
* [Using Vagrant](https://git.k8s.io/community/contributors/devel/vagrant.md)
|
||||
* *Advanced:* [Directly using Kubernetes raw binaries (Linux Only)](https://git.k8s.io/community/contributors/devel/running-locally.md)
|
||||
@@ -1,7 +0,0 @@
|
||||
# See the OWNERS docs at https://go.k8s.io/owners
|
||||
|
||||
reviewers:
|
||||
- aveshagarwal
|
||||
- eparis
|
||||
- thockin
|
||||
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: "Bare Metal"
|
||||
weight: 60
|
||||
---
|
||||
|
||||
@@ -1,177 +0,0 @@
|
||||
---
|
||||
reviewers:
|
||||
- aveshagarwal
|
||||
- eparis
|
||||
- thockin
|
||||
title: Fedora (Single Node)
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. You need 2 or more machines with Fedora installed. These can be either bare metal machines or virtual machines.
|
||||
|
||||
## Instructions
|
||||
|
||||
This is a getting started guide for Fedora. It is a manual configuration so you understand all the underlying packages / services / ports, etc...
|
||||
|
||||
This guide will only get ONE node (previously minion) working. Multiple nodes require a functional [networking configuration](/docs/concepts/cluster-administration/networking/) done outside of Kubernetes. Although the additional Kubernetes configuration requirements should be obvious.
|
||||
|
||||
The Kubernetes package provides a few services: kube-apiserver, kube-scheduler, kube-controller-manager, kubelet, kube-proxy. These services are managed by systemd and the configuration resides in a central location: `/etc/kubernetes`. We will break the services up between the hosts. The first host, fed-master, will be the Kubernetes master. This host will run the kube-apiserver, kube-controller-manager, and kube-scheduler. In addition, the master will also run _etcd_ (not needed if _etcd_ runs on a different host but this guide assumes that _etcd_ and Kubernetes master run on the same host). The remaining host, fed-node will be the node and run kubelet, proxy and docker.
|
||||
|
||||
**System Information:**
|
||||
|
||||
Hosts:
|
||||
|
||||
```conf
|
||||
fed-master = 192.168.121.9
|
||||
fed-node = 192.168.121.65
|
||||
```
|
||||
|
||||
**Prepare the hosts:**
|
||||
|
||||
* Install Kubernetes on all hosts - fed-{master,node}. This will also pull in docker. Also install etcd on fed-master. This guide has been tested with Kubernetes-0.18 and beyond.
|
||||
* Running on AWS EC2 with RHEL 7.2, you need to enable "extras" repository for yum by editing `/etc/yum.repos.d/redhat-rhui.repo` and changing the `enable=0` to `enable=1` for extras.
|
||||
|
||||
```shell
|
||||
dnf -y install kubernetes
|
||||
```
|
||||
|
||||
* Install etcd
|
||||
|
||||
```shell
|
||||
dnf -y install etcd
|
||||
```
|
||||
|
||||
* Add master and node to `/etc/hosts` on all machines (not needed if hostnames already in DNS). Make sure that communication works between fed-master and fed-node by using a utility such as ping.
|
||||
|
||||
```shell
|
||||
echo "192.168.121.9 fed-master
|
||||
192.168.121.65 fed-node" >> /etc/hosts
|
||||
```
|
||||
|
||||
* Edit `/etc/kubernetes/config` (which should be the same on all hosts) to set
|
||||
the name of the master server:
|
||||
|
||||
```shell
|
||||
# Comma separated list of nodes in the etcd cluster
|
||||
KUBE_MASTER="--master=http://fed-master:8080"
|
||||
```
|
||||
|
||||
* Disable the firewall on both the master and node, as Docker does not play well with other firewall rule managers. Please note that iptables.service does not exist on the default Fedora Server install.
|
||||
|
||||
```shell
|
||||
systemctl mask firewalld.service
|
||||
systemctl stop firewalld.service
|
||||
|
||||
systemctl disable --now iptables.service
|
||||
```
|
||||
|
||||
**Configure the Kubernetes services on the master.**
|
||||
|
||||
* Edit `/etc/kubernetes/apiserver` to appear as such. The service-cluster-ip-range IP addresses must be an unused block of addresses, not used anywhere else. They do not need to be routed or assigned to anything.
|
||||
|
||||
```shell
|
||||
# The address on the local server to listen to.
|
||||
KUBE_API_ADDRESS="--address=0.0.0.0"
|
||||
|
||||
# Comma separated list of nodes in the etcd cluster
|
||||
KUBE_ETCD_SERVERS="--etcd-servers=http://127.0.0.1:2379"
|
||||
|
||||
# Address range to use for services
|
||||
KUBE_SERVICE_ADDRESSES="--service-cluster-ip-range=10.254.0.0/16"
|
||||
|
||||
# Add your own!
|
||||
KUBE_API_ARGS=""
|
||||
```
|
||||
|
||||
* Edit `/etc/etcd/etcd.conf` to let etcd listen on all available IPs instead of 127.0.0.1. If you have not done this, you might see an error such as "connection refused".
|
||||
|
||||
```shell
|
||||
ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379"
|
||||
```
|
||||
|
||||
* Start the appropriate services on master:
|
||||
|
||||
```shell
|
||||
for SERVICES in etcd kube-apiserver kube-controller-manager kube-scheduler; do
|
||||
systemctl enable --now $SERVICES
|
||||
systemctl status $SERVICES
|
||||
done
|
||||
```
|
||||
|
||||
**Configure the Kubernetes services on the node.**
|
||||
|
||||
***We need to configure the kubelet on the node.***
|
||||
|
||||
* Edit `/etc/kubernetes/kubelet` to appear as such:
|
||||
|
||||
```shell
|
||||
###
|
||||
# Kubernetes kubelet (node) config
|
||||
|
||||
# The address for the info server to serve on (set to 0.0.0.0 or "" for all interfaces)
|
||||
KUBELET_ADDRESS="--address=0.0.0.0"
|
||||
|
||||
# You may leave this blank to use the actual hostname
|
||||
KUBELET_HOSTNAME="--hostname-override=fed-node"
|
||||
|
||||
# location of the api-server
|
||||
KUBELET_ARGS="--cgroup-driver=systemd --kubeconfig=/etc/kubernetes/master-kubeconfig.yaml"
|
||||
|
||||
```
|
||||
|
||||
* Edit `/etc/kubernetes/master-kubeconfig.yaml` to contain the following information:
|
||||
|
||||
```yaml
|
||||
kind: Config
|
||||
clusters:
|
||||
- name: local
|
||||
cluster:
|
||||
server: http://fed-master:8080
|
||||
users:
|
||||
- name: kubelet
|
||||
contexts:
|
||||
- context:
|
||||
cluster: local
|
||||
user: kubelet
|
||||
name: kubelet-context
|
||||
current-context: kubelet-context
|
||||
```
|
||||
|
||||
* Start the appropriate services on the node (fed-node).
|
||||
|
||||
```shell
|
||||
for SERVICES in kube-proxy kubelet docker; do
|
||||
systemctl enable --now $SERVICES
|
||||
systemctl status $SERVICES
|
||||
done
|
||||
```
|
||||
|
||||
* Check to make sure now the cluster can see the fed-node on fed-master, and its status changes to _Ready_.
|
||||
|
||||
```shell
|
||||
kubectl get nodes
|
||||
NAME STATUS AGE VERSION
|
||||
fed-node Ready 4h
|
||||
```
|
||||
|
||||
* Deletion of nodes:
|
||||
|
||||
To delete _fed-node_ from your Kubernetes cluster, one should run the following on fed-master (Please do not do it, it is just for information):
|
||||
|
||||
```shell
|
||||
kubectl delete -f ./node.json
|
||||
```
|
||||
|
||||
*You should be finished!*
|
||||
|
||||
**The cluster should be running! Launch a test pod.**
|
||||
|
||||
## Support Level
|
||||
|
||||
|
||||
IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level
|
||||
-------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ----------------------------
|
||||
Bare-metal | custom | Fedora | _none_ | [docs](/docs/getting-started-guides/fedora/fedora_manual_config) | | Project
|
||||
@@ -1,196 +0,0 @@
|
||||
---
|
||||
reviewers:
|
||||
- dchen1107
|
||||
- erictune
|
||||
- thockin
|
||||
title: Fedora (Multi Node)
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
This document describes how to deploy Kubernetes on multiple hosts to set up a multi-node cluster and networking with flannel. Follow fedora [getting started guide](/docs/getting-started-guides/fedora/fedora_manual_config/) to setup 1 master (fed-master) and 2 or more nodes. Make sure that all nodes have different names (fed-node1, fed-node2 and so on) and labels (fed-node1-label, fed-node2-label, and so on) to avoid any conflict. Also make sure that the Kubernetes master host is running etcd, kube-controller-manager, kube-scheduler, and kube-apiserver services, and the nodes are running docker, kube-proxy and kubelet services. Now install flannel on Kubernetes nodes. Flannel on each node configures an overlay network that docker uses. Flannel runs on each node to setup a unique class-C container network.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You need 2 or more machines with Fedora installed.
|
||||
|
||||
## Master Setup
|
||||
|
||||
**Perform following commands on the Kubernetes master**
|
||||
|
||||
* Configure flannel by creating a `flannel-config.json` in your current directory on fed-master. Flannel provides udp and vxlan among other overlay networking backend options. In this guide, we choose kernel based vxlan backend. The contents of the json are:
|
||||
|
||||
```json
|
||||
{
|
||||
"Network": "18.16.0.0/16",
|
||||
"SubnetLen": 24,
|
||||
"Backend": {
|
||||
"Type": "vxlan",
|
||||
"VNI": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
Choose an IP range that is *NOT* part of the public IP address range.
|
||||
{{< /note >}}
|
||||
|
||||
Add the configuration to the etcd server on fed-master.
|
||||
|
||||
```shell
|
||||
etcdctl set /coreos.com/network/config < flannel-config.json
|
||||
```
|
||||
|
||||
* Verify that the key exists in the etcd server on fed-master.
|
||||
|
||||
```shell
|
||||
etcdctl get /coreos.com/network/config
|
||||
```
|
||||
|
||||
## Node Setup
|
||||
|
||||
**Perform following commands on all Kubernetes nodes**
|
||||
|
||||
Install the flannel package
|
||||
|
||||
```shell
|
||||
# dnf -y install flannel
|
||||
```
|
||||
|
||||
Edit the flannel configuration file /etc/sysconfig/flanneld as follows:
|
||||
|
||||
```shell
|
||||
# Flanneld configuration options
|
||||
|
||||
# etcd url location. Point this to the server where etcd runs
|
||||
FLANNEL_ETCD="http://fed-master:2379"
|
||||
|
||||
# etcd config key. This is the configuration key that flannel queries
|
||||
# For address range assignment
|
||||
FLANNEL_ETCD_KEY="/coreos.com/network"
|
||||
|
||||
# Any additional options that you want to pass
|
||||
FLANNEL_OPTIONS=""
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
By default, flannel uses the interface for the default route. If you have multiple interfaces and would like to use an interface other than the default route one, you could add "-iface=" to FLANNEL_OPTIONS. For additional options, run `flanneld --help` on command line.
|
||||
{{< /note >}}
|
||||
|
||||
Enable the flannel service.
|
||||
|
||||
```shell
|
||||
systemctl enable flanneld
|
||||
```
|
||||
|
||||
If docker is not running, then starting flannel service is enough and skip the next step.
|
||||
|
||||
```shell
|
||||
systemctl start flanneld
|
||||
```
|
||||
|
||||
If docker is already running, then stop docker, delete docker bridge (docker0), start flanneld and restart docker as follows. Another alternative is to just reboot the system (`systemctl reboot`).
|
||||
|
||||
```shell
|
||||
systemctl stop docker
|
||||
ip link delete docker0
|
||||
systemctl start flanneld
|
||||
systemctl start docker
|
||||
```
|
||||
|
||||
|
||||
## Test the cluster and flannel configuration
|
||||
|
||||
Now check the interfaces on the nodes. Notice there is now a flannel.1 interface, and the ip addresses of docker0 and flannel.1 interfaces are in the same network. You will notice that docker0 is assigned a subnet (18.16.29.0/24 as shown below) on each Kubernetes node out of the IP range configured above. A working output should look like this:
|
||||
|
||||
```shell
|
||||
# ip -4 a|grep inet
|
||||
inet 127.0.0.1/8 scope host lo
|
||||
inet 192.168.122.77/24 brd 192.168.122.255 scope global dynamic eth0
|
||||
inet 18.16.29.0/16 scope global flannel.1
|
||||
inet 18.16.29.1/24 scope global docker0
|
||||
```
|
||||
|
||||
From any node in the cluster, check the cluster members by issuing a query to etcd server via curl (only partial output is shown using `grep -E "\{|\}|key|value"`). If you set up a 1 master and 3 nodes cluster, you should see one block for each node showing the subnets they have been assigned. You can associate those subnets to each node by the MAC address (VtepMAC) and IP address (Public IP) that is listed in the output.
|
||||
|
||||
```shell
|
||||
curl -s http://fed-master:2379/v2/keys/coreos.com/network/subnets | python -mjson.tool
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"node": {
|
||||
"key": "/coreos.com/network/subnets",
|
||||
{
|
||||
"key": "/coreos.com/network/subnets/18.16.29.0-24",
|
||||
"value": "{\"PublicIP\":\"192.168.122.77\",\"BackendType\":\"vxlan\",\"BackendData\":{\"VtepMAC\":\"46:f1:d0:18:d0:65\"}}"
|
||||
},
|
||||
{
|
||||
"key": "/coreos.com/network/subnets/18.16.83.0-24",
|
||||
"value": "{\"PublicIP\":\"192.168.122.36\",\"BackendType\":\"vxlan\",\"BackendData\":{\"VtepMAC\":\"ca:38:78:fc:72:29\"}}"
|
||||
},
|
||||
{
|
||||
"key": "/coreos.com/network/subnets/18.16.90.0-24",
|
||||
"value": "{\"PublicIP\":\"192.168.122.127\",\"BackendType\":\"vxlan\",\"BackendData\":{\"VtepMAC\":\"92:e2:80:ba:2d:4d\"}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
From all nodes, review the `/run/flannel/subnet.env` file. This file was generated automatically by flannel.
|
||||
|
||||
```shell
|
||||
# cat /run/flannel/subnet.env
|
||||
FLANNEL_SUBNET=18.16.29.1/24
|
||||
FLANNEL_MTU=1450
|
||||
FLANNEL_IPMASQ=false
|
||||
```
|
||||
|
||||
At this point, we have etcd running on the Kubernetes master, and flannel / docker running on Kubernetes nodes. Next steps are for testing cross-host container communication which will confirm that docker and flannel are configured properly.
|
||||
|
||||
Issue the following commands on any 2 nodes:
|
||||
|
||||
```shell
|
||||
# docker run -it fedora:latest bash
|
||||
bash-4.3#
|
||||
```
|
||||
|
||||
This will place you inside the container. Install iproute and iputils packages to install ip and ping utilities. Due to a [bug](https://bugzilla.redhat.com/show_bug.cgi?id=1142311), it is required to modify capabilities of ping binary to work around "Operation not permitted" error.
|
||||
|
||||
```shell
|
||||
bash-4.3# dnf -y install iproute iputils
|
||||
bash-4.3# setcap cap_net_raw-ep /usr/bin/ping
|
||||
```
|
||||
|
||||
Now note the IP address on the first node:
|
||||
|
||||
```shell
|
||||
bash-4.3# ip -4 a l eth0 | grep inet
|
||||
inet 18.16.29.4/24 scope global eth0
|
||||
```
|
||||
|
||||
And also note the IP address on the other node:
|
||||
|
||||
```shell
|
||||
bash-4.3# ip a l eth0 | grep inet
|
||||
inet 18.16.90.4/24 scope global eth0
|
||||
```
|
||||
Now ping from the first node to the other node:
|
||||
|
||||
```shell
|
||||
bash-4.3# ping 18.16.90.4
|
||||
PING 18.16.90.4 (18.16.90.4) 56(84) bytes of data.
|
||||
64 bytes from 18.16.90.4: icmp_seq=1 ttl=62 time=0.275 ms
|
||||
64 bytes from 18.16.90.4: icmp_seq=2 ttl=62 time=0.372 ms
|
||||
```
|
||||
|
||||
Now Kubernetes multi-node cluster is set up with overlay networking set up by flannel.
|
||||
|
||||
## Support Level
|
||||
|
||||
|
||||
IaaS Provider | Config. Mgmt | OS | Networking | Docs | Conforms | Support Level
|
||||
-------------------- | ------------ | ------ | ---------- | --------------------------------------------- | ---------| ----------------------------
|
||||
Bare-metal | custom | Fedora | flannel | [docs](/docs/getting-started-guides/fedora/flannel_multi_node_cluster/) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))
|
||||
libvirt | custom | Fedora | flannel | [docs](/docs/getting-started-guides/fedora/flannel_multi_node_cluster/) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))
|
||||
KVM | custom | Fedora | flannel | [docs](/docs/getting-started-guides/fedora/flannel_multi_node_cluster/) | | Community ([@aveshagarwal](https://github.com/aveshagarwal))
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: Kubernetes on Ubuntu
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
There are multiple ways to run a Kubernetes cluster with Ubuntu on public and
|
||||
private clouds, as well as bare metal.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
## The Charmed Distribution of Kubernetes(CDK)
|
||||
|
||||
[CDK](https://www.ubuntu.com/cloud/kubernetes) is a distribution of Kubernetes
|
||||
packaged as a bundle of *charms* for Juju, the open source application modeller.
|
||||
|
||||
CDK is the latest version of Kubernetes with upstream binaries, packaged in a format
|
||||
which makes it fast and easy to deploy. It supports various public
|
||||
and private clouds including AWS, GCE, Azure, Joyent, OpenStack, VMware, Bare Metal
|
||||
and localhost deployments.
|
||||
|
||||
See the [Official documentation](https://www.ubuntu.com/kubernetes/docs) for
|
||||
more information.
|
||||
|
||||
## MicroK8s
|
||||
|
||||
[MicroK8s](https://microk8s.io) is a minimal install of Kubernetes designed to run locally.
|
||||
It can be installed on Ubuntu (or any snap enabled operating system) with the command:
|
||||
|
||||
```shell
|
||||
snap install microk8s --classic
|
||||
```
|
||||
|
||||
Full documentation is available on the [MicroK8s website](https://microk8s.io/docs)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
{{% /capture %}}
|
||||
@@ -8,10 +8,6 @@ title: Using ABAC Authorization
|
||||
content_template: templates/concept
|
||||
weight: 80
|
||||
---
|
||||
{{< note >}}
|
||||
{{< feature-state state="deprecated" for_k8s_version="1.6" >}}
|
||||
The ABAC Authorization feature has been considered deprecated from the Kubernetes 1.6 release.
|
||||
{{< /note >}}
|
||||
|
||||
{{% capture overview %}}
|
||||
Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together.
|
||||
|
||||
@@ -75,6 +75,7 @@ different Kubernetes components.
|
||||
| `CustomPodDNS` | `false` | Alpha | 1.9 | 1.9 |
|
||||
| `CustomPodDNS` | `true` | Beta| 1.10 | 1.13 |
|
||||
| `CustomPodDNS` | `true` | GA | 1.14 | - |
|
||||
| `CustomResourceDefaulting` | `false` | Alpha| 1.15 | |
|
||||
| `CustomResourcePublishOpenAPI` | `false` | Alpha| 1.14 | 1.14 |
|
||||
| `CustomResourcePublishOpenAPI` | `true` | Beta| 1.15 | |
|
||||
| `CustomResourceSubresources` | `false` | Alpha | 1.10 | 1.11 |
|
||||
@@ -117,6 +118,7 @@ different Kubernetes components.
|
||||
| `KubeletPluginsWatcher` | `true` | GA | 1.13 | - |
|
||||
| `KubeletPodResources` | `false` | Alpha | 1.13 | 1.14 |
|
||||
| `KubeletPodResources` | `true` | Beta | 1.15 | |
|
||||
| `LegacyNodeRoleBehavior` | `true` | Alpha | 1.16 | |
|
||||
| `LocalStorageCapacityIsolation` | `false` | Alpha | 1.7 | 1.9 |
|
||||
| `LocalStorageCapacityIsolation` | `true` | Beta| 1.10 | |
|
||||
| `LocalStorageCapacityIsolationFSQuotaMonitoring` | `false` | Alpha| 1.15 | |
|
||||
@@ -124,6 +126,7 @@ different Kubernetes components.
|
||||
| `MountPropagation` | `false` | Alpha | 1.8 | 1.9 |
|
||||
| `MountPropagation` | `true` | Beta | 1.10 | 1.11 |
|
||||
| `MountPropagation` | `true` | GA | 1.12 | |
|
||||
| `NodeDisruptionExclusion` | `false` | Alpha | 1.16 | |
|
||||
| `NodeLease` | `false` | Alpha | 1.12 | 1.13 |
|
||||
| `NodeLease` | `true` | Beta | 1.14 | |
|
||||
| `NonPreemptingPriority` | `false` | Alpha | 1.15 | |
|
||||
@@ -274,6 +277,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
||||
- `CustomPodDNS`: Enable customizing the DNS settings for a Pod using its `dnsConfig` property.
|
||||
Check [Pod's DNS Config](/docs/concepts/services-networking/dns-pod-service/#pods-dns-config)
|
||||
for more details.
|
||||
- `CustomResourceDefaulting`: Enable CRD support for default values in OpenAPI v3 validation schemas.
|
||||
- `CustomResourcePublishOpenAPI`: Enables publishing of CRD OpenAPI specs.
|
||||
- `CustomResourceSubresources`: Enable `/status` and `/scale` subresources
|
||||
on resources created from [CustomResourceDefinition](/docs/concepts/api-extension/custom-resources/).
|
||||
@@ -314,11 +318,13 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
||||
to discover plugins such as [CSI volume drivers](/docs/concepts/storage/volumes/#csi).
|
||||
- `KubeletPodResources`: Enable the kubelet's pod resources grpc endpoint.
|
||||
See [Support Device Monitoring](https://git.k8s.io/community/keps/sig-node/compute-device-assignment.md) for more details.
|
||||
- `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.
|
||||
- `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.
|
||||
- `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).
|
||||
- `NodeDisruptionExclusion`: Enable use of the node label `node.kubernetes.io/exclude-disruption` which prevents nodes from being evacuated during zone failures.
|
||||
- `NodeLease`: Enable the new Lease API to report node heartbeats, which could be used as a node health signal.
|
||||
- `NonPreemptingPriority`: Enable NonPreempting option for PriorityClass and Pod.
|
||||
- `PersistentLocalVolumes`: Enable the usage of `local` volume type in Pods.
|
||||
@@ -352,7 +358,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
|
||||
- `ServerSideApply`: Enables the [Sever Side Apply (SSA)](/docs/reference/using-api/api-concepts/#server-side-apply) path at the API Server.
|
||||
- `ServiceLoadBalancerFinalizer`: Enable finalizer protection for Service load balancers.
|
||||
- `ServiceNodeExclusion`: Enable the exclusion of nodes from load balancers created by a cloud provider.
|
||||
A node is eligible for exclusion if annotated with "`alpha.service-controller.kubernetes.io/exclude-balancer`" key.
|
||||
A node is eligible for exclusion if labelled with "`alpha.service-controller.kubernetes.io/exclude-balancer`" key (when `LegacyNodeRoleBehavior` is on) or `node.kubernetes.io/exclude-from-external-load-balancers`.
|
||||
- `StartupProbe`: Enable the [startup](/docs/concepts/workloads/pods/pod-lifecycle/#when-should-you-use-a-startup-probe) probe in the kubelet.
|
||||
- `StorageObjectInUseProtection`: Postpone the deletion of PersistentVolume or
|
||||
PersistentVolumeClaim objects if they are still being used.
|
||||
|
||||
@@ -5,7 +5,6 @@ date: 2019-05-12
|
||||
full_link:
|
||||
short_description: >
|
||||
The layer where various containerized applications run.
|
||||
|
||||
aka:
|
||||
tags:
|
||||
- fundamental
|
||||
|
||||
@@ -2,13 +2,17 @@
|
||||
title: Static Pod
|
||||
id: static-pod
|
||||
date: 2019-02-12
|
||||
full_link: /docs/tasks/administer-cluster/static-pod/
|
||||
full_link: /docs/tasks/configure-pod-container/static-pod/
|
||||
short_description: >
|
||||
A pod managed directly by kubelet daemon on a specific node
|
||||
A pod managed directly by the kubelet daemon on a specific node.
|
||||
|
||||
aka:
|
||||
tags:
|
||||
- fundamental
|
||||
---
|
||||
A {{< glossary_tooltip text="pod" term_id="pod" >}} managed directly by the kubelet
|
||||
daemon on a specific node, without the API server observing it.
|
||||
|
||||
A {{< glossary_tooltip text="pod" term_id="pod" >}} managed directly by the kubelet
|
||||
daemon on a specific node,
|
||||
<!--more-->
|
||||
|
||||
without the API server observing it.
|
||||
@@ -1,28 +1,22 @@
|
||||
---
|
||||
title: Workloads
|
||||
title: Workload
|
||||
id: workloads
|
||||
date: 2019-02-13
|
||||
full_link: /docs/concepts/workloads/
|
||||
short_description: >
|
||||
Workloads are objects you use to manage and run your containers on the cluster.
|
||||
A workload is an application running on Kubernetes.
|
||||
|
||||
aka:
|
||||
tags:
|
||||
- fundamental
|
||||
- core-object
|
||||
- workload
|
||||
---
|
||||
Workloads are objects you use to manage and run your containers on the cluster.
|
||||
A workload is an application running on Kubernetes.
|
||||
|
||||
<!--more-->
|
||||
|
||||
Kubernetes performs the
|
||||
deployment and updates the workload with the current state of the application.
|
||||
Workloads include the DaemonSet, Deployments, Jobs, Pods, ReplicaSet, ReplicationController, and StatefulSet objects.
|
||||
|
||||
For example, a workload that has a web element and a database element might run the
|
||||
database in one {{< glossary_tooltip term_id="StatefulSet" >}} of
|
||||
{{< glossary_tooltip text="pods" term_id="pod" >}} and the webserver via
|
||||
a {{< glossary_tooltip term_id="Deployment" >}} that consists of many web app
|
||||
{{< glossary_tooltip text="pods" term_id="pod" >}}, all alike.
|
||||
Various core objects that represent different types or parts of a workload
|
||||
include the DaemonSet, Deployment, Job, ReplicaSet, and StatefulSet objects.
|
||||
|
||||
For example, a workload that has a web server and a database might run the
|
||||
database in one {{< glossary_tooltip term_id="StatefulSet" >}} and the web server
|
||||
in a {{< glossary_tooltip term_id="Deployment" >}}.
|
||||
|
||||
@@ -82,7 +82,7 @@ The following production environment solutions table lists the providers and the
|
||||
| [Docker Enterprise](https://www.docker.com/products/docker-enterprise) | |✔ | ✔ | | | ✔
|
||||
| [Fedora (Multi Node)](https://kubernetes.io/docs/getting-started-guides/fedora/flannel_multi_node_cluster/) | | | | | ✔ | ✔
|
||||
| [Fedora (Single Node)](https://kubernetes.io/docs/getting-started-guides/fedora/fedora_manual_config/) | | | | | | ✔
|
||||
| [Gardener](https://gardener.cloud/) | |✔ | | ✔ | |
|
||||
| [Gardener](https://gardener.cloud/) | ✔ | ✔ | ✔ (via OpenStack) | ✔ | |
|
||||
| [Giant Swarm](https://giantswarm.io/) | ✔ | ✔ | ✔ | |
|
||||
| [Google](https://cloud.google.com/) | [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/) | [Google Compute Engine (GCE)](https://cloud.google.com/compute/)|[GKE On-Prem](https://cloud.google.com/gke-on-prem/) | | | | | | | |
|
||||
| [IBM](https://www.ibm.com/in-en/cloud) | [IBM Cloud Kubernetes Service](https://cloud.ibm.com/kubernetes/catalog/cluster)| |[IBM Cloud Private](https://www.ibm.com/in-en/cloud/private) | |
|
||||
@@ -109,5 +109,6 @@ The following production environment solutions table lists the providers and the
|
||||
| [Tencent Cloud](https://intl.cloud.tencent.com/) | [Tencent Kubernetes Engine](https://intl.cloud.tencent.com/product/tke) | ✔ | ✔ | | | ✔ |
|
||||
| [VEXXHOST](https://vexxhost.com/) | ✔ | ✔ | | | |
|
||||
| [VMware](https://cloud.vmware.com/) | [VMware Cloud PKS](https://cloud.vmware.com/vmware-cloud-pks) |[VMware Enterprise PKS](https://cloud.vmware.com/vmware-enterprise-pks) | [VMware Enterprise PKS](https://cloud.vmware.com/vmware-enterprise-pks) | [VMware Essential PKS](https://cloud.vmware.com/vmware-essential-pks) | |[VMware Essential PKS](https://cloud.vmware.com/vmware-essential-pks)
|
||||
| [Z.A.R.V.I.S.](https://zarvis.ai/) | ✔ | | | | | |
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -28,8 +28,8 @@ The Kubernetes project maintains release branches for the most recent three mino
|
||||
|
||||
Applicable fixes, including security fixes, may be backported to those three release branches, depending on severity and feasibility.
|
||||
Patch releases are cut from those branches at a regular cadence, or as needed.
|
||||
This decision is owned by the [patch release manager](https://github.com/kubernetes/sig-release/blob/master/release-team/role-handbooks/patch-release-manager/README.md#release-timing).
|
||||
The patch release manager is a member of the [release team for each release](https://github.com/kubernetes/sig-release/tree/master/releases/).
|
||||
This decision is owned by the [patch release manager](https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/patch-release-manager.md#release-timing).
|
||||
The patch release manager is a member of the [release team for each release](https://github.com/kubernetes/sig-release/tree/master/release-team).
|
||||
|
||||
Minor releases occur approximately every 3 months, so each minor release branch is maintained for approximately 9 months.
|
||||
|
||||
@@ -37,7 +37,7 @@ Minor releases occur approximately every 3 months, so each minor release branch
|
||||
|
||||
### kube-apiserver
|
||||
|
||||
In [highly-available (HA) clusters](/docs/setup/production-environment/tools/independent/high-availability/), the newest and oldest `kube-apiserver` instances must be within one minor version.
|
||||
In [highly-available (HA) clusters](/docs/setup/production-environment/tools/kubeadm/high-availability/), the newest and oldest `kube-apiserver` instances must be within one minor version.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -120,7 +120,7 @@ Upgrade `kube-apiserver` to **1.(n+1)**
|
||||
|
||||
{{< note >}}
|
||||
Project policies for [API deprecation](/docs/reference/using-api/deprecation-policy/) and
|
||||
[API change guidelines](https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md)
|
||||
[API change guidelines](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md)
|
||||
require `kube-apiserver` to not skip minor versions when upgrading, even in single-instance clusters.
|
||||
{{< /note >}}
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Dashboard also provides information on the state of Kubernetes resources in your
|
||||
The Dashboard UI is not deployed by default. To deploy it, run the following command:
|
||||
|
||||
```
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta1/aio/deploy/recommended.yaml
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta4/aio/deploy/recommended.yaml
|
||||
```
|
||||
|
||||
## Accessing the Dashboard UI
|
||||
|
||||
@@ -36,7 +36,7 @@ may be disabled by setting `--feature-gates=PodShareProcessNamespace=false`.
|
||||
|
||||
## Configure a Pod
|
||||
|
||||
Process Namespace Sharing is enabled using the `ShareProcessNamespace` field of
|
||||
Process Namespace Sharing is enabled using the `shareProcessNamespace` field of
|
||||
`v1.PodSpec`. For example:
|
||||
|
||||
{{< codenew file="pods/share-process-namespace.yaml" >}}
|
||||
|
||||
@@ -490,6 +490,18 @@ let users route data where they want. For example, users can emit audit events t
|
||||
plugin which supports full-text search and analytics.
|
||||
|
||||
|
||||
[kube-apiserver]: /docs/admin/kube-apiserver
|
||||
[auditing-proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/auditing.md
|
||||
[auditing-api]: https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/pkg/apis/audit/v1/types.go
|
||||
[gce-audit-profile]: https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh#L735
|
||||
[kubeconfig]: /docs/tasks/access-application-cluster/configure-access-multiple-clusters/
|
||||
[fluentd]: http://www.fluentd.org/
|
||||
[fluentd_install_doc]: https://docs.fluentd.org/v1.0/articles/quickstart#step-1:-installing-fluentd
|
||||
[fluentd_plugin_management_doc]: https://docs.fluentd.org/v1.0/articles/plugin-management
|
||||
[logstash]: https://www.elastic.co/products/logstash
|
||||
[logstash_install_doc]: https://www.elastic.co/guide/en/logstash/current/installing-logstash.html
|
||||
[kube-aggregator]: /docs/concepts/api-extension/apiserver-aggregation
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
Reference in New Issue
Block a user