Merge remote-tracking branch 'upstream/main' into dev-1.23
This commit is contained in:
Jesse Butler
@@ -145,7 +145,7 @@ Coil operates with a low overhead compared to bare metal, and allows you to defi
|
||||
|
||||
### Contiv
|
||||
|
||||
[Contiv](https://github.com/contiv/netplugin) provides configurable networking (native l3 using BGP, overlay using vxlan, classic l2, or Cisco-SDN/ACI) for various use cases. [Contiv](https://contiv.io) is all open sourced.
|
||||
[Contiv](https://github.com/contiv/netplugin) provides configurable networking (native l3 using BGP, overlay using vxlan, classic l2, or Cisco-SDN/ACI) for various use cases.
|
||||
|
||||
### Contrail / Tungsten Fabric
|
||||
|
||||
@@ -248,7 +248,7 @@ Lars Kellogg-Stedman.
|
||||
|
||||
[Multus](https://github.com/Intel-Corp/multus-cni) is a Multi CNI plugin to support the Multi Networking feature in Kubernetes using CRD based network objects in Kubernetes.
|
||||
|
||||
Multus supports all [reference plugins](https://github.com/containernetworking/plugins) (eg. [Flannel](https://github.com/containernetworking/plugins/tree/master/plugins/meta/flannel), [DHCP](https://github.com/containernetworking/plugins/tree/master/plugins/ipam/dhcp), [Macvlan](https://github.com/containernetworking/plugins/tree/master/plugins/main/macvlan)) that implement the CNI specification and 3rd party plugins (eg. [Calico](https://github.com/projectcalico/cni-plugin), [Weave](https://github.com/weaveworks/weave), [Cilium](https://github.com/cilium/cilium), [Contiv](https://github.com/contiv/netplugin)). In addition to it, Multus supports [SRIOV](https://github.com/hustcat/sriov-cni), [DPDK](https://github.com/Intel-Corp/sriov-cni), [OVS-DPDK & VPP](https://github.com/intel/vhost-user-net-plugin) workloads in Kubernetes with both cloud native and NFV based applications in Kubernetes.
|
||||
Multus supports all [reference plugins](https://github.com/containernetworking/plugins) (eg. [Flannel](https://github.com/containernetworking/cni.dev/blob/main/content/plugins/v0.9/meta/flannel.md), [DHCP](https://github.com/containernetworking/plugins/tree/master/plugins/ipam/dhcp), [Macvlan](https://github.com/containernetworking/plugins/tree/master/plugins/main/macvlan)) that implement the CNI specification and 3rd party plugins (eg. [Calico](https://github.com/projectcalico/cni-plugin), [Weave](https://github.com/weaveworks/weave), [Cilium](https://github.com/cilium/cilium), [Contiv](https://github.com/contiv/netplugin)). In addition to it, Multus supports [SRIOV](https://github.com/hustcat/sriov-cni), [DPDK](https://github.com/Intel-Corp/sriov-cni), [OVS-DPDK & VPP](https://github.com/intel/vhost-user-net-plugin) workloads in Kubernetes with both cloud native and NFV based applications in Kubernetes.
|
||||
|
||||
### OVN4NFV-K8s-Plugin (OVN based CNI controller & plugin)
|
||||
|
||||
@@ -260,12 +260,6 @@ Multus supports all [reference plugins](https://github.com/containernetworking/p
|
||||
|
||||
[NSX-T Container Plug-in (NCP)](https://docs.vmware.com/en/VMware-NSX-T/2.0/nsxt_20_ncp_kubernetes.pdf) provides integration between NSX-T and container orchestrators such as Kubernetes, as well as integration between NSX-T and container-based CaaS/PaaS platforms such as Pivotal Container Service (PKS) and OpenShift.
|
||||
|
||||
### Nuage Networks VCS (Virtualized Cloud Services)
|
||||
|
||||
[Nuage](https://www.nuagenetworks.net) provides a highly scalable policy-based Software-Defined Networking (SDN) platform. Nuage uses the open source Open vSwitch for the data plane along with a feature rich SDN Controller built on open standards.
|
||||
|
||||
The Nuage platform uses overlays to provide seamless policy-based networking between Kubernetes Pods and non-Kubernetes environments (VMs and bare metal servers). Nuage's policy abstraction model is designed with applications in mind and makes it easy to declare fine-grained policies for applications.The platform's real-time analytics engine enables visibility and security monitoring for Kubernetes applications.
|
||||
|
||||
### OpenVSwitch
|
||||
|
||||
[OpenVSwitch](https://www.openvswitch.org/) is a somewhat more mature but also
|
||||
|
||||
@@ -212,7 +212,8 @@ to create a Docker registry Secret, you can do:
|
||||
kubectl create secret docker-registry secret-tiger-docker \
|
||||
--docker-username=tiger \
|
||||
--docker-password=pass113 \
|
||||
--docker-email=tiger@acme.com
|
||||
--docker-email=tiger@acme.com \
|
||||
--docker-server=my-registry.example:5000
|
||||
```
|
||||
|
||||
This command creates a Secret of type `kubernetes.io/dockerconfigjson`.
|
||||
@@ -222,15 +223,21 @@ on the fly:
|
||||
|
||||
```json
|
||||
{
|
||||
"auths": {
|
||||
"https://index.docker.io/v1/": {
|
||||
"username": "tiger",
|
||||
"password": "pass113",
|
||||
"email": "tiger@acme.com",
|
||||
"auth": "dGlnZXI6cGFzczExMw=="
|
||||
}
|
||||
}
|
||||
"apiVersion": "v1",
|
||||
"data": {
|
||||
".dockerconfigjson": "eyJhdXRocyI6eyJteS1yZWdpc3RyeTo1MDAwIjp7InVzZXJuYW1lIjoidGlnZXIiLCJwYXNzd29yZCI6InBhc3MxMTMiLCJlbWFpbCI6InRpZ2VyQGFjbWUuY29tIiwiYXV0aCI6ImRHbG5aWEk2Y0dGemN6RXhNdz09In19fQ=="
|
||||
},
|
||||
"kind": "Secret",
|
||||
"metadata": {
|
||||
"creationTimestamp": "2021-07-01T07:30:59Z",
|
||||
"name": "secret-tiger-docker",
|
||||
"namespace": "default",
|
||||
"resourceVersion": "566718",
|
||||
"uid": "e15c1d7b-9071-4100-8681-f3a7a2ce89ca"
|
||||
},
|
||||
"type": "kubernetes.io/dockerconfigjson"
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Basic authentication Secret
|
||||
|
||||
@@ -108,7 +108,7 @@ When you (or a controller) submit a new Pod to the API server, your cluster sets
|
||||
`:latest`, `imagePullPolicy` is automatically set to `Always`;
|
||||
- if you omit the `imagePullPolicy` field, and you don't specify the tag for the
|
||||
container image, `imagePullPolicy` is automatically set to `Always`;
|
||||
- if you omit the `imagePullPolicy` field, and you don't specify the tag for the
|
||||
- if you omit the `imagePullPolicy` field, and you specify the tag for the
|
||||
container image that isn't `:latest`, the `imagePullPolicy` is automatically set to
|
||||
`IfNotPresent`.
|
||||
|
||||
|
||||
@@ -35,11 +35,11 @@ On their own, custom resources let you store and retrieve structured data.
|
||||
When you combine a custom resource with a *custom controller*, custom resources
|
||||
provide a true _declarative API_.
|
||||
|
||||
A [declarative API](/docs/concepts/overview/kubernetes-api/)
|
||||
allows you to _declare_ or specify the desired state of your resource and tries to
|
||||
keep the current state of Kubernetes objects in sync with the desired state.
|
||||
The controller interprets the structured data as a record of the user's
|
||||
desired state, and continually maintains this state.
|
||||
The Kubernetes [declarative API](/docs/concepts/overview/kubernetes-api/)
|
||||
enforces a separation of responsibilities. You declare the desired state of
|
||||
your resource. The Kubernetes controller keeps the current state of Kubernetes
|
||||
objects in sync with your declared desired state. This is in contrast to an
|
||||
imperative API, where you *instruct* a server what to do.
|
||||
|
||||
You can deploy and update a custom controller on a running cluster, independently
|
||||
of the cluster's lifecycle. Custom controllers can work with any kind of resource,
|
||||
|
||||
@@ -19,11 +19,7 @@ When you deploy Kubernetes, you get a cluster.
|
||||
This document outlines the various components you need to have for
|
||||
a complete and working Kubernetes cluster.
|
||||
|
||||
Here's the diagram of a Kubernetes cluster with all the components tied together.
|
||||
|
||||
|
||||
|
||||
|
||||
{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Components of Kubernetes" caption="The components of a Kubernetes cluster" class="diagram-large" >}}
|
||||
|
||||
<!-- body -->
|
||||
## Control Plane Components
|
||||
|
||||
@@ -44,7 +44,8 @@ and the controller deletes the volume.
|
||||
|
||||
## Owner references, labels, and finalizers {#owners-labels-finalizers}
|
||||
|
||||
Like {{<glossary_tooltip text="labels" term_id="label">}}, [owner references](/concepts/overview/working-with-objects/owners-dependents/)
|
||||
Like {{<glossary_tooltip text="labels" term_id="label">}},
|
||||
[owner references](/docs/concepts/overview/working-with-objects/owners-dependents/)
|
||||
describe the relationships between objects in Kubernetes, but are used for a
|
||||
different purpose. When a
|
||||
{{<glossary_tooltip text="controller" term_id="controller">}} manages objects
|
||||
|
||||
@@ -10,8 +10,7 @@ weight: 30
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Kubernetes supports multiple virtual clusters backed by the same physical cluster.
|
||||
These virtual clusters are called namespaces.
|
||||
In Kubernetes, _namespaces_ provides a mechanism for isolating groups of resources within a single cluster. Names of resources need to be unique within a namespace, but not across namespaces. Namespace-based scoping is applicable only for namespaced objects _(e.g. Deployments, Services, etc)_ and not for cluster-wide objects _(e.g. StorageClass, Nodes, PersistentVolumes, etc)_.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
|
||||
@@ -52,7 +52,7 @@ equivalent to "Predicate" and "Scoring" is equivalent to "Priority function".
|
||||
One plugin may register at multiple extension points to perform more complex or
|
||||
stateful tasks.
|
||||
|
||||
{{< figure src="/images/docs/scheduling-framework-extensions.png" title="scheduling framework extension points" >}}
|
||||
{{< figure src="/images/docs/scheduling-framework-extensions.png" title="scheduling framework extension points" class="diagram-large">}}
|
||||
|
||||
### QueueSort {#queue-sort}
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ computing approach to security, which is widely regarded as a best practice for
|
||||
software systems.
|
||||
{{< /note >}}
|
||||
|
||||
{{< figure src="/images/docs/4c.png" title="The 4C's of Cloud Native Security" >}}
|
||||
{{< figure src="/images/docs/4c.png" title="The 4C's of Cloud Native Security" class="diagram-large" >}}
|
||||
|
||||
Each layer of the Cloud Native security model builds upon the next outermost layer.
|
||||
The Code layer benefits from strong base (Cloud, Cluster, Container) security layers.
|
||||
@@ -60,6 +60,7 @@ Amazon Web Services | https://aws.amazon.com/security/ |
|
||||
Google Cloud Platform | https://cloud.google.com/security/ |
|
||||
IBM Cloud | https://www.ibm.com/cloud/security |
|
||||
Microsoft Azure | https://docs.microsoft.com/en-us/azure/security/azure-security |
|
||||
Oracle Cloud Infrastructure | https://www.oracle.com/security/ |
|
||||
VMWare VSphere | https://www.vmware.com/security/hardening-guides.html |
|
||||
|
||||
{{< /table >}}
|
||||
|
||||
@@ -217,13 +217,13 @@ following pod-specific DNS policies. These policies are specified in the
|
||||
|
||||
- "`Default`": The Pod inherits the name resolution configuration from the node
|
||||
that the pods run on.
|
||||
See [related discussion](/docs/tasks/administer-cluster/dns-custom-nameservers/#inheriting-dns-from-the-node)
|
||||
See [related discussion](/docs/tasks/administer-cluster/dns-custom-nameservers)
|
||||
for more details.
|
||||
- "`ClusterFirst`": Any DNS query that does not match the configured cluster
|
||||
domain suffix, such as "`www.kubernetes.io`", is forwarded to the upstream
|
||||
nameserver inherited from the node. Cluster administrators may have extra
|
||||
stub-domain and upstream DNS servers configured.
|
||||
See [related discussion](/docs/tasks/administer-cluster/dns-custom-nameservers/#effects-on-pods)
|
||||
See [related discussion](/docs/tasks/administer-cluster/dns-custom-nameservers)
|
||||
for details on how DNS queries are handled in those cases.
|
||||
- "`ClusterFirstWithHostNet`": For Pods running with hostNetwork, you should
|
||||
explicitly set its DNS policy "`ClusterFirstWithHostNet`".
|
||||
|
||||
@@ -261,7 +261,7 @@ The following restrictions apply when using this field:
|
||||
at a cluster level, you (or your cluster administrator) need to disable the
|
||||
`NetworkPolicyEndPort` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
||||
for the API server with `--feature-gates=NetworkPolicyEndPort=false,…`.
|
||||
* The `endPort` field must be equal than or greater to the `port` field.
|
||||
* The `endPort` field must be equal to or greater than the `port` field.
|
||||
* `endPort` can only be defined if `port` is also defined.
|
||||
* Both ports must be numeric.
|
||||
|
||||
|
||||
@@ -183,6 +183,13 @@ Accessing a Service without a selector works the same as if it had a selector.
|
||||
In the example above, traffic is routed to the single endpoint defined in
|
||||
the YAML: `192.0.2.42:9376` (TCP).
|
||||
|
||||
{{< note >}}
|
||||
The Kubernetes API server does not allow proxying to endpoints that are not mapped to
|
||||
pods. Actions such as `kubectl proxy <service-name>` where the service has no
|
||||
selector will fail due to this constraint. This prevents the Kubernetes API server
|
||||
from being used as a proxy to endpoints the caller may not be authorized to access.
|
||||
{{< /note >}}
|
||||
|
||||
An ExternalName Service is a special case of Service that does not have
|
||||
selectors and uses DNS names instead. For more information, see the
|
||||
[ExternalName](#externalname) section later in this document.
|
||||
@@ -414,7 +421,7 @@ endpoints, the kube-proxy does not forward any traffic for the relevant Service.
|
||||
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
|
||||
If you enable the `ProxyTerminatingEndpoints`
|
||||
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
||||
`ProxyTerminatingEndpoints` for the kube-proxy, the kube-proxy checks if the node
|
||||
for the kube-proxy, the kube-proxy checks if the node
|
||||
has local endpoints and whether or not all the local endpoints are marked as terminating.
|
||||
If there are local endpoints and **all** of those are terminating, then the kube-proxy ignores
|
||||
any external traffic policy of `Local`. Instead, whilst the node-local endpoints remain as all
|
||||
@@ -1065,6 +1072,9 @@ in those modified security groups.
|
||||
|
||||
{{< /note >}}
|
||||
|
||||
Further documentation on annotations for Elastic IPs and other common use-cases may be found
|
||||
in the [AWS Load Balancer Controller documentation](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/guide/service/annotations/).
|
||||
|
||||
#### Other CLB annotations on Tencent Kubernetes Engine (TKE)
|
||||
|
||||
There are other annotations for managing Cloud Load Balancers on TKE as shown below.
|
||||
@@ -1121,7 +1131,7 @@ spec:
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
ExternalName accepts an IPv4 address string, but as a DNS names comprised of digits, not as an IP address. ExternalNames that resemble IPv4 addresses are not resolved by CoreDNS or ingress-nginx because ExternalName
|
||||
ExternalName accepts an IPv4 address string, but as a DNS name comprised of digits, not as an IP address. ExternalNames that resemble IPv4 addresses are not resolved by CoreDNS or ingress-nginx because ExternalName
|
||||
is intended to specify a canonical DNS name. To hardcode an IP address, consider using
|
||||
[headless Services](#headless-services).
|
||||
{{< /note >}}
|
||||
|
||||
@@ -146,7 +146,7 @@ features:
|
||||
parameters.
|
||||
- Typical operations on volumes are supported assuming that the driver
|
||||
supports them, including
|
||||
([snapshotting](/docs/concepts/storage/volume-snapshots/),
|
||||
[snapshotting](/docs/concepts/storage/volume-snapshots/),
|
||||
[cloning](/docs/concepts/storage/volume-pvc-datasource/),
|
||||
[resizing](/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims),
|
||||
and [storage capacity tracking](/docs/concepts/storage/storage-capacity/).
|
||||
|
||||
@@ -131,7 +131,9 @@ The `Retain` reclaim policy allows for manual reclamation of the resource. When
|
||||
|
||||
1. Delete the PersistentVolume. The associated storage asset in external infrastructure (such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume) still exists after the PV is deleted.
|
||||
1. Manually clean up the data on the associated storage asset accordingly.
|
||||
1. Manually delete the associated storage asset, or if you want to reuse the same storage asset, create a new PersistentVolume with the storage asset definition.
|
||||
1. Manually delete the associated storage asset.
|
||||
|
||||
If you want to reuse the same storage asset, create a new PersistentVolume with the same storage asset definition.
|
||||
|
||||
#### Delete
|
||||
|
||||
@@ -412,11 +414,22 @@ A PersistentVolume can be mounted on a host in any way supported by the resource
|
||||
|
||||
The access modes are:
|
||||
|
||||
* ReadWriteOnce -- the volume can be mounted as read-write by a single node
|
||||
* ReadOnlyMany -- the volume can be mounted read-only by many nodes
|
||||
* ReadWriteMany -- the volume can be mounted as read-write by many nodes
|
||||
* ReadWriteOncePod -- the volume can be mounted as read-write by a single Pod.
|
||||
This is only supported for CSI volumes and Kubernetes version 1.22+.
|
||||
`ReadWriteOnce`
|
||||
: the volume can be mounted as read-write by a single node. ReadWriteOnce access mode still can allow multiple pods to access the volume when the pods are running on the same node.
|
||||
|
||||
`ReadOnlyMany`
|
||||
: the volume can be mounted as read-only by many nodes.
|
||||
|
||||
`ReadWriteMany`
|
||||
: the volume can be mounted as read-write by many nodes.
|
||||
|
||||
`ReadWriteOncePod`
|
||||
: the volume can be mounted as read-write by a single Pod. Use ReadWriteOncePod access mode if you want to ensure that only one pod across whole cluster can read that PVC or write to it. This is only supported for CSI volumes and Kubernetes version 1.22+.
|
||||
|
||||
|
||||
|
||||
The blog article [Introducing Single Pod Access Mode for PersistentVolumes](/blog/2021/09/13/read-write-once-pod-access-mode-alpha/) covers this in more detail.
|
||||
|
||||
|
||||
In the CLI, the access modes are abbreviated to:
|
||||
|
||||
|
||||
@@ -136,11 +136,16 @@ and set this flag to `false`. For example:
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
[Cron expression format](https://en.wikipedia.org/wiki/Cron)
|
||||
documents the format of CronJob `schedule` fields.
|
||||
|
||||
For instructions on creating and working with cron jobs, and for an example of CronJob
|
||||
manifest, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs).
|
||||
|
||||
For instructions to clean up failed or completed jobs automatically, see
|
||||
[Clean up Jobs automatically](/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically)
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods/) and
|
||||
[Jobs](/docs/concepts/workloads/controllers/job/), two concepts
|
||||
that CronJobs rely upon.
|
||||
* Read about the [format](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format)
|
||||
of CronJob `.spec.schedule` fields.
|
||||
* For instructions on creating and working with CronJobs, and for an example
|
||||
of a CronJob manifest,
|
||||
see [Running automated tasks with CronJobs](/docs/tasks/job/automated-tasks-with-cron-jobs/).
|
||||
* For instructions to clean up failed or completed jobs automatically,
|
||||
see [Clean up Jobs automatically](/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically)
|
||||
* `CronJob` is part of the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/cron-job-v1" >}}
|
||||
object definition to understand the API for Kubernetes cron jobs.
|
||||
|
||||
@@ -235,3 +235,18 @@ all or certain hosts, if the DaemonSet provides node-level functionality that al
|
||||
For example, [network plugins](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) often include a component that runs as a DaemonSet. The DaemonSet component makes sure that the node where it's running has working cluster networking.
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* Learn about [static Pods](#static-pods), which are useful for running Kubernetes
|
||||
{{< glossary_tooltip text="control plane" term_id="control-plane" >}} components.
|
||||
* Find out how to use DaemonSets
|
||||
* [Perform a rolling update on a DaemonSet](/docs/tasks/manage-daemon/update-daemon-set/)
|
||||
* [Perform a rollback on a DaemonSet](/docs/tasks/manage-daemon/rollback-daemon-set/)
|
||||
(for example, if a roll out didn't work how you expected).
|
||||
* Understand [how Kubernetes assigns Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/).
|
||||
* Learn about [device plugins](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/) and
|
||||
[add ons](/docs/concepts/cluster-administration/addons/), which often run as DaemonSets.
|
||||
* `DaemonSet` is a top-level resource in the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/daemon-set-v1" >}}
|
||||
object definition to understand the API for daemon sets.
|
||||
|
||||
@@ -75,11 +75,6 @@ Follow the steps given below to create the above Deployment:
|
||||
kubectl apply -f https://k8s.io/examples/controllers/nginx-deployment.yaml
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
You can specify the `--record` flag to write the command executed in the resource annotation `kubernetes.io/change-cause`.
|
||||
The recorded change is useful for future introspection. For example, to see the commands executed in each Deployment revision.
|
||||
{{< /note >}}
|
||||
|
||||
|
||||
2. Run `kubectl get deployments` to check if the Deployment was created.
|
||||
|
||||
@@ -169,13 +164,13 @@ Follow the steps given below to update your Deployment:
|
||||
1. Let's update the nginx Pods to use the `nginx:1.16.1` image instead of the `nginx:1.14.2` image.
|
||||
|
||||
```shell
|
||||
kubectl --record deployment.apps/nginx-deployment set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
|
||||
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
|
||||
```
|
||||
|
||||
or use the following command:
|
||||
|
||||
```shell
|
||||
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1 --record
|
||||
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
|
||||
```
|
||||
|
||||
The output is similar to:
|
||||
@@ -187,7 +182,7 @@ Follow the steps given below to update your Deployment:
|
||||
Alternatively, you can `edit` the Deployment and change `.spec.template.spec.containers[0].image` from `nginx:1.14.2` to `nginx:1.16.1`:
|
||||
|
||||
```shell
|
||||
kubectl edit deployment.v1.apps/nginx-deployment
|
||||
kubectl edit deployment/nginx-deployment
|
||||
```
|
||||
|
||||
The output is similar to:
|
||||
@@ -370,7 +365,7 @@ rolled back.
|
||||
* Suppose that you made a typo while updating the Deployment, by putting the image name as `nginx:1.161` instead of `nginx:1.16.1`:
|
||||
|
||||
```shell
|
||||
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.161 --record=true
|
||||
kubectl set image deployment/nginx-deployment nginx=nginx:1.161
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -479,26 +474,25 @@ Follow the steps given below to check the rollout history:
|
||||
|
||||
1. First, check the revisions of this Deployment:
|
||||
```shell
|
||||
kubectl rollout history deployment.v1.apps/nginx-deployment
|
||||
kubectl rollout history deployment/nginx-deployment
|
||||
```
|
||||
The output is similar to this:
|
||||
```
|
||||
deployments "nginx-deployment"
|
||||
REVISION CHANGE-CAUSE
|
||||
1 kubectl apply --filename=https://k8s.io/examples/controllers/nginx-deployment.yaml --record=true
|
||||
2 kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
|
||||
3 kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.161 --record=true
|
||||
1 kubectl apply --filename=https://k8s.io/examples/controllers/nginx-deployment.yaml
|
||||
2 kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
|
||||
3 kubectl set image deployment/nginx-deployment nginx=nginx:1.161
|
||||
```
|
||||
|
||||
`CHANGE-CAUSE` is copied from the Deployment annotation `kubernetes.io/change-cause` to its revisions upon creation. You can specify the`CHANGE-CAUSE` message by:
|
||||
|
||||
* Annotating the Deployment with `kubectl annotate deployment.v1.apps/nginx-deployment kubernetes.io/change-cause="image updated to 1.16.1"`
|
||||
* Append the `--record` flag to save the `kubectl` command that is making changes to the resource.
|
||||
* Annotating the Deployment with `kubectl annotate deployment/nginx-deployment kubernetes.io/change-cause="image updated to 1.16.1"`
|
||||
* Manually editing the manifest of the resource.
|
||||
|
||||
2. To see the details of each revision, run:
|
||||
```shell
|
||||
kubectl rollout history deployment.v1.apps/nginx-deployment --revision=2
|
||||
kubectl rollout history deployment/nginx-deployment --revision=2
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -506,7 +500,7 @@ Follow the steps given below to check the rollout history:
|
||||
deployments "nginx-deployment" revision 2
|
||||
Labels: app=nginx
|
||||
pod-template-hash=1159050644
|
||||
Annotations: kubernetes.io/change-cause=kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
|
||||
Annotations: kubernetes.io/change-cause=kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
|
||||
Containers:
|
||||
nginx:
|
||||
Image: nginx:1.16.1
|
||||
@@ -523,7 +517,7 @@ Follow the steps given below to rollback the Deployment from the current version
|
||||
|
||||
1. Now you've decided to undo the current rollout and rollback to the previous revision:
|
||||
```shell
|
||||
kubectl rollout undo deployment.v1.apps/nginx-deployment
|
||||
kubectl rollout undo deployment/nginx-deployment
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -533,7 +527,7 @@ Follow the steps given below to rollback the Deployment from the current version
|
||||
Alternatively, you can rollback to a specific revision by specifying it with `--to-revision`:
|
||||
|
||||
```shell
|
||||
kubectl rollout undo deployment.v1.apps/nginx-deployment --to-revision=2
|
||||
kubectl rollout undo deployment/nginx-deployment --to-revision=2
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -567,7 +561,7 @@ Follow the steps given below to rollback the Deployment from the current version
|
||||
CreationTimestamp: Sun, 02 Sep 2018 18:17:55 -0500
|
||||
Labels: app=nginx
|
||||
Annotations: deployment.kubernetes.io/revision=4
|
||||
kubernetes.io/change-cause=kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
|
||||
kubernetes.io/change-cause=kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
|
||||
Selector: app=nginx
|
||||
Replicas: 3 desired | 3 updated | 3 total | 3 available | 0 unavailable
|
||||
StrategyType: RollingUpdate
|
||||
@@ -610,7 +604,7 @@ Follow the steps given below to rollback the Deployment from the current version
|
||||
You can scale a Deployment by using the following command:
|
||||
|
||||
```shell
|
||||
kubectl scale deployment.v1.apps/nginx-deployment --replicas=10
|
||||
kubectl scale deployment/nginx-deployment --replicas=10
|
||||
```
|
||||
The output is similar to this:
|
||||
```
|
||||
@@ -622,7 +616,7 @@ in your cluster, you can setup an autoscaler for your Deployment and choose the
|
||||
Pods you want to run based on the CPU utilization of your existing Pods.
|
||||
|
||||
```shell
|
||||
kubectl autoscale deployment.v1.apps/nginx-deployment --min=10 --max=15 --cpu-percent=80
|
||||
kubectl autoscale deployment/nginx-deployment --min=10 --max=15 --cpu-percent=80
|
||||
```
|
||||
The output is similar to this:
|
||||
```
|
||||
@@ -651,7 +645,7 @@ For example, you are running a Deployment with 10 replicas, [maxSurge](#max-surg
|
||||
|
||||
* You update to a new image which happens to be unresolvable from inside the cluster.
|
||||
```shell
|
||||
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:sometag
|
||||
kubectl set image deployment/nginx-deployment nginx=nginx:sometag
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -730,7 +724,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
|
||||
|
||||
* Pause by running the following command:
|
||||
```shell
|
||||
kubectl rollout pause deployment.v1.apps/nginx-deployment
|
||||
kubectl rollout pause deployment/nginx-deployment
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -740,7 +734,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
|
||||
|
||||
* Then update the image of the Deployment:
|
||||
```shell
|
||||
kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
|
||||
kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -750,7 +744,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
|
||||
|
||||
* Notice that no new rollout started:
|
||||
```shell
|
||||
kubectl rollout history deployment.v1.apps/nginx-deployment
|
||||
kubectl rollout history deployment/nginx-deployment
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -772,7 +766,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
|
||||
|
||||
* You can make as many updates as you wish, for example, update the resources that will be used:
|
||||
```shell
|
||||
kubectl set resources deployment.v1.apps/nginx-deployment -c=nginx --limits=cpu=200m,memory=512Mi
|
||||
kubectl set resources deployment/nginx-deployment -c=nginx --limits=cpu=200m,memory=512Mi
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -785,7 +779,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess
|
||||
|
||||
* Eventually, resume the Deployment and observe a new ReplicaSet coming up with all the new updates:
|
||||
```shell
|
||||
kubectl rollout resume deployment.v1.apps/nginx-deployment
|
||||
kubectl rollout resume deployment/nginx-deployment
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
@@ -895,7 +889,7 @@ The following `kubectl` command sets the spec with `progressDeadlineSeconds` to
|
||||
lack of progress for a Deployment after 10 minutes:
|
||||
|
||||
```shell
|
||||
kubectl patch deployment.v1.apps/nginx-deployment -p '{"spec":{"progressDeadlineSeconds":600}}'
|
||||
kubectl patch deployment/nginx-deployment -p '{"spec":{"progressDeadlineSeconds":600}}'
|
||||
```
|
||||
The output is similar to this:
|
||||
```
|
||||
@@ -1056,7 +1050,7 @@ A Deployment also needs a [`.spec` section](https://git.k8s.io/community/contrib
|
||||
|
||||
### Pod Template
|
||||
|
||||
The `.spec.template` and `.spec.selector` are the only required field of the `.spec`.
|
||||
The `.spec.template` and `.spec.selector` are the only required fields of the `.spec`.
|
||||
|
||||
The `.spec.template` is a [Pod template](/docs/concepts/workloads/pods/#pod-templates). It has exactly the same schema as a {{< glossary_tooltip text="Pod" term_id="pod" >}}, except it is nested and does not have an `apiVersion` or `kind`.
|
||||
|
||||
@@ -1176,4 +1170,12 @@ a paused Deployment and one that is not paused, is that any changes into the Pod
|
||||
Deployment will not trigger new rollouts as long as it is paused. A Deployment is not paused by default when
|
||||
it is created.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* [Run a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
|
||||
* `Deployment` is a top-level resource in the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/deployment-v1" >}}
|
||||
object definition to understand the API for deployments.
|
||||
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
|
||||
you can use it to manage application availability during disruptions.
|
||||
|
||||
@@ -25,6 +25,9 @@ due to a node hardware failure or a node reboot).
|
||||
|
||||
You can also use a Job to run multiple Pods in parallel.
|
||||
|
||||
If you want to run a Job (either a single task, or several in parallel) on a schedule,
|
||||
see [CronJob](/docs/concepts/workloads/controllers/cron-jobs/).
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Running an example Job
|
||||
@@ -204,6 +207,7 @@ Jobs with _fixed completion count_ - that is, jobs that have non null
|
||||
{{< glossary_tooltip term_id="Service" >}}, Pods within the Job can use
|
||||
the deterministic hostnames to address each other via DNS.
|
||||
- From the containarized task, in the environment variable `JOB_COMPLETION_INDEX`.
|
||||
|
||||
The Job is considered complete when there is one successfully completed Pod
|
||||
for each index. For more information about how to use this mode, see
|
||||
[Indexed Job for Parallel Processing with Static Work Assignment](/docs/tasks/job/indexed-parallel-processing-static/).
|
||||
@@ -638,6 +642,19 @@ driver, and then cleans up.
|
||||
An advantage of this approach is that the overall process gets the completion guarantee of a Job
|
||||
object, but maintains complete control over what Pods are created and how work is assigned to them.
|
||||
|
||||
## Cron Jobs {#cron-jobs}
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
You can use a [`CronJob`](/docs/concepts/workloads/controllers/cron-jobs/) to create a Job that will run at specified times/dates, similar to the Unix tool `cron`.
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* Read about different ways of running Jobs:
|
||||
* [Coarse Parallel Processing Using a Work Queue](/docs/tasks/job/coarse-parallel-processing-work-queue/)
|
||||
* [Fine Parallel Processing Using a Work Queue](/docs/tasks/job/fine-parallel-processing-work-queue/)
|
||||
* Use an [indexed Job for parallel processing with static work assignment](/docs/tasks/job/indexed-parallel-processing-static/) (beta)
|
||||
* Create multiple Jobs based on a template: [Parallel Processing using Expansions](/docs/tasks/job/parallel-processing-expansion/)
|
||||
* Follow the links within [Clean up finished jobs automatically](#clean-up-finished-jobs-automatically)
|
||||
to learn more about how your cluster can clean up completed and / or failed tasks.
|
||||
* `Job` is part of the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/job-v1" >}}
|
||||
object definition to understand the API for jobs.
|
||||
* Read about [`CronJob`](/docs/concepts/workloads/controllers/cron-jobs/), which you
|
||||
can use to define a series of Jobs that will run based on a schedule, similar to
|
||||
the Unix tool `cron`.
|
||||
|
||||
@@ -410,3 +410,14 @@ selector requirements as described in the [labels user guide](/docs/concepts/ove
|
||||
As such, ReplicaSets are preferred over ReplicationControllers
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* Learn about [Deployments](/docs/concepts/workloads/controllers/deployment/).
|
||||
* [Run a Stateless Application Using a Deployment](/docs/tasks/run-application/run-stateless-application-deployment/),
|
||||
which relies on ReplicaSets to work.
|
||||
* `ReplicaSet` is a top-level resource in the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/replica-set-v1" >}}
|
||||
object definition to understand the API for replica sets.
|
||||
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
|
||||
you can use it to manage application availability during disruptions.
|
||||
|
||||
@@ -248,7 +248,7 @@ The ReplicationController ensures that the desired number of pods matches its la
|
||||
|
||||
The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](https://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (for example, [spreading](https://issue.k8s.io/367#issuecomment-48428019)) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](https://issue.k8s.io/170)).
|
||||
|
||||
The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](https://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
|
||||
The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, scale) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](https://netflixtechblog.com/asgard-web-based-cloud-management-and-deployment-2c9fc4e4d3a1) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
|
||||
|
||||
## API Object
|
||||
|
||||
@@ -284,6 +284,11 @@ machine-level function, such as machine monitoring or machine logging. These po
|
||||
to a machine lifetime: the pod needs to be running on the machine before other pods start, and are
|
||||
safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
|
||||
|
||||
## For more information
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
Read [Run Stateless Application Deployment](/docs/tasks/run-application/run-stateless-application-deployment/).
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* Learn about [Deployment](/docs/concepts/workloads/controllers/deployment/), the replacement
|
||||
for ReplicationController.
|
||||
* `ReplicationController` is part of the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/replication-controller-v1" >}}
|
||||
object definition to understand the API for replication controllers.
|
||||
|
||||
@@ -297,7 +297,18 @@ Please note that this field only works if you enable the `StatefulSetMinReadySec
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Learn about [Pods](/docs/concepts/workloads/pods).
|
||||
* Find out how to use StatefulSets
|
||||
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set/).
|
||||
* Follow an example of [deploying Cassandra with Stateful Sets](/docs/tutorials/stateful-application/cassandra/).
|
||||
* Follow an example of [running a replicated stateful application](/docs/tasks/run-application/run-replicated-stateful-application/).
|
||||
* Learn how to [scale a StatefulSet](/docs/tasks/run-application/scale-stateful-set/).
|
||||
* Learn what's involved when you [delete a StatefulSet](/docs/tasks/run-application/delete-stateful-set/).
|
||||
* Learn how to [configure a Pod to use a volume for storage](/docs/tasks/configure-pod-container/configure-volume-storage/).
|
||||
* Learn how to [configure a Pod to use a PersistentVolume for storage](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).
|
||||
* `StatefulSet` is a top-level resource in the Kubernetes REST API.
|
||||
Read the {{< api-reference page="workload-resources/stateful-set-v1" >}}
|
||||
object definition to understand the API for stateful sets.
|
||||
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how
|
||||
you can use it to manage application availability during disruptions.
|
||||
|
||||
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set/).
|
||||
* Follow an example of [deploying Cassandra with Stateful Sets](/docs/tutorials/stateful-application/cassandra/).
|
||||
* Follow an example of [running a replicated stateful application](/docs/tasks/run-application/run-replicated-stateful-application/).
|
||||
|
||||
@@ -48,6 +48,21 @@ with shared namespaces and shared filesystem volumes.
|
||||
|
||||
## Using Pods
|
||||
|
||||
The following is an example of a Pod which consists of a container running the image `nginx:1.14.2`.
|
||||
|
||||
{{< codenew file="pods/simple-pod.yaml" >}}
|
||||
|
||||
To create the Pod shown above, run the following command:
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml
|
||||
```
|
||||
|
||||
Pods are generally not created directly and are created using workload resources.
|
||||
See [Working with Pods](#working-with-pods) for more information on how Pods are used
|
||||
with workload resources.
|
||||
|
||||
### Workload resources for managing pods
|
||||
|
||||
Usually you don't need to create Pods directly, even singleton Pods. Instead, create them using workload resources such as {{< glossary_tooltip text="Deployment"
|
||||
term_id="deployment" >}} or {{< glossary_tooltip text="Job" term_id="job" >}}.
|
||||
If your Pods need to track state, consider the
|
||||
@@ -97,7 +112,7 @@ For example, you might have a container that
|
||||
acts as a web server for files in a shared volume, and a separate "sidecar" container
|
||||
that updates those files from a remote source, as in the following diagram:
|
||||
|
||||
{{< figure src="/images/docs/pod.svg" alt="example pod diagram" width="50%" >}}
|
||||
{{< figure src="/images/docs/pod.svg" alt="Pod creation diagram" class="diagram-medium" >}}
|
||||
|
||||
Some Pods have {{< glossary_tooltip text="init containers" term_id="init-container" >}} as well as {{< glossary_tooltip text="app containers" term_id="app-container" >}}. Init containers run and complete before the app containers are started.
|
||||
|
||||
@@ -309,9 +324,9 @@ in the Pod Lifecycle documentation.
|
||||
* Read about [Pod topology spread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/).
|
||||
* Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
|
||||
* Pod is a top-level resource in the Kubernetes REST API.
|
||||
The [Pod](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core)
|
||||
The {{< api-reference page="workload-resources/pod-v1" >}}
|
||||
object definition describes the object in detail.
|
||||
* [The Distributed System Toolkit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns) explains common layouts for Pods with more than one container.
|
||||
* [The Distributed System Toolkit: Patterns for Composite Containers](/blog/2015/06/the-distributed-system-toolkit-patterns/) explains common layouts for Pods with more than one container.
|
||||
|
||||
To understand the context for why Kubernetes wraps a common Pod API in other resources (such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or {{< glossary_tooltip text="Deployments" term_id="deployment" >}}), you can read about the prior art, including:
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@ exists. If that Pod is deleted for any reason, and even if an identical replacem
|
||||
is created, the related thing (a volume, in this example) is also destroyed and
|
||||
created anew.
|
||||
|
||||
{{< figure src="/images/docs/pod.svg" title="Pod diagram" width="50%" >}}
|
||||
{{< figure src="/images/docs/pod.svg" title="Pod diagram" class="diagram-medium" >}}
|
||||
|
||||
*A multi-container Pod that contains a file puller and a
|
||||
web server that uses a persistent volume for shared storage between the containers.*
|
||||
|
||||
@@ -234,7 +234,7 @@ To overcome this situation, you can either increase the `maxSkew` or modify one
|
||||
|
||||
The scheduler will skip the non-matching nodes from the skew calculations if the incoming Pod has `spec.nodeSelector` or `spec.affinity.nodeAffinity` defined.
|
||||
|
||||
Suppose you have a 5-node cluster ranging from zoneA to zoneC:
|
||||
Suppose you have a 5-node cluster ranging from zoneA to zoneC:
|
||||
|
||||
{{<mermaid>}}
|
||||
graph BT
|
||||
@@ -268,7 +268,7 @@ The scheduler will skip the non-matching nodes from the skew calculations if the
|
||||
class zoneC cluster;
|
||||
{{< /mermaid >}}
|
||||
|
||||
and you know that "zoneC" must be excluded. In this case, you can compose the yaml as below, so that "mypod" will be placed onto "zoneB" instead of "zoneC". Similarly `spec.nodeSelector` is also respected.
|
||||
and you know that "zoneC" must be excluded. In this case, you can compose the yaml as below, so that "mypod" will be placed onto "zoneB" instead of "zoneC". Similarly `spec.nodeSelector` is also respected.
|
||||
|
||||
{{< codenew file="pods/topology-spread-constraints/one-constraint-with-nodeaffinity.yaml" >}}
|
||||
|
||||
|
||||
@@ -29,6 +29,8 @@ Kubernetes documentation contributors:
|
||||
- Translate the documentation
|
||||
- Manage and publish the documentation parts of the Kubernetes release cycle
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Getting started
|
||||
@@ -44,18 +46,98 @@ to work effectively in the Kubernetes community.
|
||||
To get involved with documentation:
|
||||
|
||||
1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md).
|
||||
1. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website)
|
||||
2. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website)
|
||||
and the website's [static site generator](https://gohugo.io).
|
||||
1. Make sure you understand the basic processes for
|
||||
3. Make sure you understand the basic processes for
|
||||
[opening a pull request](/docs/contribute/new-content/open-a-pr/) and
|
||||
[reviewing changes](/docs/contribute/review/reviewing-prs/).
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart TB
|
||||
subgraph third[Open PR]
|
||||
direction TB
|
||||
U[ ] -.-
|
||||
Q[Improve content] --- N[Create content]
|
||||
N --- O[Translate docs]
|
||||
O --- P[Manage/publish docs parts<br>of K8s release cycle]
|
||||
|
||||
end
|
||||
|
||||
subgraph second[Review]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
D[Look over the<br>K8s/website<br>repository] --- E[Check out the<br>Hugo static site<br>generator]
|
||||
E --- F[Understand basic<br>GitHub commands]
|
||||
F --- G[Review open PR<br>and change review <br>processes]
|
||||
end
|
||||
|
||||
subgraph first[Sign up]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
B[Sign the CNCF<br>Contributor<br>License Agreement] --- C[Join sig-docs<br>Slack channel]
|
||||
C --- V[Join kubernetes-sig-docs<br>mailing list]
|
||||
V --- M[Attend weekly<br>sig-docs calls<br>or slack meetings]
|
||||
end
|
||||
|
||||
A([fa:fa-user New<br>Contributor]) --> first
|
||||
A --> second
|
||||
A --> third
|
||||
A --> H[Ask Questions!!!]
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,C,D,E,F,G,H,M,Q,N,O,P,V grey
|
||||
class S,T,U spacewhite
|
||||
class first,second,third white
|
||||
{{</ mermaid >}}
|
||||
***Figure - Getting started for a new contributor***
|
||||
|
||||
The figure above outlines a roadmap for new contributors. You can follow some or all of the steps for `Sign up` and `Review`. Now you are ready to open PRs that achieve your contribution objectives with some listed under `Open PR`. Again, questions are always welcome!
|
||||
|
||||
Some tasks require more trust and more access in the Kubernetes organization.
|
||||
See [Participating in SIG Docs](/docs/contribute/participate/) for more details about
|
||||
roles and permissions.
|
||||
|
||||
## Your first contribution
|
||||
|
||||
You can prepare for your first contribution by reviewing several steps beforehand. The figure below outlines the steps and the details follow.
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph second[First Contribution]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
G[Review PRs from other<br>K8s members] -->
|
||||
A[Check K8s/website<br>issues list for<br>good first PRs] --> B[Open a PR!!]
|
||||
end
|
||||
subgraph first[Suggested Prep]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
D[Read contribution overview] -->E[Read K8s content<br>and style guides]
|
||||
E --> F[Learn about Hugo page<br>content types<br>and shortcodes]
|
||||
end
|
||||
|
||||
|
||||
first ----> second
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,D,E,F,G grey
|
||||
class S,T spacewhite
|
||||
class first,second white
|
||||
{{</ mermaid >}}
|
||||
***Figure - Preparation for your first contribution***
|
||||
|
||||
- Read the [Contribution overview](/docs/contribute/new-content/overview/) to
|
||||
learn about the different ways you can contribute.
|
||||
- Check [`kubernetes/website` issues list](https://github.com/kubernetes/website/issues/)
|
||||
@@ -92,10 +174,12 @@ SIG Docs communicates with different methods:
|
||||
introduce yourself!
|
||||
- [Join the `kubernetes-sig-docs` mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs),
|
||||
where broader discussions take place and official decisions are recorded.
|
||||
- Join the [weekly SIG Docs video meeting](https://github.com/kubernetes/community/tree/master/sig-docs). Meetings are always announced on `#sig-docs` and added to the [Kubernetes community meetings calendar](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). You'll need to download the [Zoom client](https://zoom.us/download) or dial in using a phone.
|
||||
- Join the [SIG Docs video meeting](https://github.com/kubernetes/community/tree/master/sig-docs) held every two weeks. Meetings are always announced on `#sig-docs` and added to the [Kubernetes community meetings calendar](https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles). You'll need to download the [Zoom client](https://zoom.us/download) or dial in using a phone.
|
||||
- Join the SIG Docs async Slack standup meeting on those weeks when the in-person Zoom video meeting does not take place. Meetings are always announced on `#sig-docs`. You can contribute to any one of the threads up to 24 hours after meeting announcement.
|
||||
|
||||
## Other ways to contribute
|
||||
|
||||
- Visit the [Kubernetes community site](/community/). Participate on Twitter or Stack Overflow, learn about local Kubernetes meetups and events, and more.
|
||||
- Read the [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet) to get involved with Kubernetes feature development.
|
||||
- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/).
|
||||
|
||||
|
||||
@@ -346,7 +346,7 @@ Teams must merge localized content into the same branch from which the content w
|
||||
|
||||
For example:
|
||||
- a localization branch sourced from `main` must be merged into `main`.
|
||||
- a localization branch sourced from `release-{{ skew "prevMinorVersion" }}` must be merged into `release-{{ skew "prevMinorVersion" }}`.
|
||||
- a localization branch sourced from `release-{{% skew "prevMinorVersion" %}}` must be merged into `release-{{% skew "prevMinorVersion" %}}`.
|
||||
|
||||
{{< note >}}
|
||||
If your localization branch was created from `main` branch but it is not merged into `main` before new release branch `{{< release-branch >}}` created, merge it into both `main` and new release branch `{{< release-branch >}}`. To merge your localization branch into new release branch `{{< release-branch >}}`, you need to switch upstream branch of your localization branch to `{{< release-branch >}}`.
|
||||
@@ -361,5 +361,4 @@ For more information about working from forks or directly from the repository, s
|
||||
## Upstream contributions
|
||||
|
||||
SIG Docs welcomes upstream contributions and corrections to the English source.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,4 +1,118 @@
|
||||
---
|
||||
title: Contributing new content
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 20
|
||||
---
|
||||
|
||||
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This section contains information you should know before contributing new
|
||||
content.
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph second[Before you begin]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
A[Sign the CNCF CLA] --> B[Choose Git branch]
|
||||
B --> C[One language per PR]
|
||||
C --> F[Check out<br>contributor tools]
|
||||
end
|
||||
subgraph first[Contributing Basics]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
D[Write docs in markdown<br>and build site with Hugo] --- E[source in GitHub]
|
||||
E --- G[_'/content/../docs'_ folder contains docs<br>for multiple languages]
|
||||
G --- H[Review Hugo page content<br>types and shortcodes]
|
||||
end
|
||||
|
||||
|
||||
first ----> second
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,C,D,E,F,G,H grey
|
||||
class S,T spacewhite
|
||||
class first,second white
|
||||
{{</ mermaid >}}
|
||||
|
||||
***Figure - Contributing new content preparation***
|
||||
|
||||
The figure above depicts the information you should know
|
||||
prior to submitting new content. The information details follow.
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Contributing basics
|
||||
|
||||
- Write Kubernetes documentation in Markdown and build the Kubernetes site
|
||||
using [Hugo](https://gohugo.io/).
|
||||
- The source is in [GitHub](https://github.com/kubernetes/website). You can find
|
||||
Kubernetes documentation at `/content/en/docs/`. Some of the reference
|
||||
documentation is automatically generated from scripts in
|
||||
the `update-imported-docs/` directory.
|
||||
- [Page content types](/docs/contribute/style/page-content-types/) describe the
|
||||
presentation of documentation content in Hugo.
|
||||
- In addition to the standard Hugo shortcodes, we use a number of
|
||||
[custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our
|
||||
documentation to control the presentation of content.
|
||||
- Documentation source is available in multiple languages in `/content/`. Each
|
||||
language has its own folder with a two-letter code determined by the
|
||||
[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php)
|
||||
. For example, English documentation source is stored in `/content/en/docs/`.
|
||||
- For more information about contributing to documentation in multiple languages
|
||||
or starting a new translation,
|
||||
see [localization](/docs/contribute/localization).
|
||||
|
||||
## Before you begin {#before-you-begin}
|
||||
|
||||
### Sign the CNCF CLA {#sign-the-cla}
|
||||
|
||||
All Kubernetes contributors **must** read
|
||||
the [Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)
|
||||
and [sign the Contributor License Agreement (CLA)](https://github.com/kubernetes/community/blob/master/CLA.md)
|
||||
.
|
||||
|
||||
Pull requests from contributors who haven't signed the CLA fail the automated
|
||||
tests. The name and email you provide must match those found in
|
||||
your `git config`, and your git name and email must match those used for the
|
||||
CNCF CLA.
|
||||
|
||||
### Choose which Git branch to use
|
||||
|
||||
When opening a pull request, you need to know in advance which branch to base
|
||||
your work on.
|
||||
|
||||
Scenario | Branch
|
||||
:---------|:------------
|
||||
Existing or new English language content for the current release | `main`
|
||||
Content for a feature change release | The branch which corresponds to the major and minor version the feature change is in, using the pattern `dev-<version>`. For example, if a feature changes in the `v{{< skew nextMinorVersion >}}` release, then add documentation changes to the ``dev-{{< skew nextMinorVersion >}}`` branch.
|
||||
Content in other languages (localizations) | Use the localization's convention. See the [Localization branching strategy](/docs/contribute/localization/#branching-strategy) for more information.
|
||||
|
||||
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack.
|
||||
|
||||
{{< note >}} If you already submitted your pull request and you know that the
|
||||
base branch was wrong, you (and only you, the submitter) can change it. {{<
|
||||
/note >}}
|
||||
|
||||
### Languages per PR
|
||||
|
||||
Limit pull requests to one language per PR. If you need to make an identical
|
||||
change to the same code sample in multiple languages, open a separate PR for
|
||||
each language.
|
||||
|
||||
## Tools for contributors
|
||||
|
||||
The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools)
|
||||
directory in the `kubernetes/website` repository contains tools to help your
|
||||
contribution journey go more smoothly.
|
||||
|
||||
|
||||
@@ -28,7 +28,40 @@ If your changes are large, read [Work from a local fork](#fork-the-repo) to lear
|
||||
## Changes using GitHub
|
||||
|
||||
If you're less experienced with git workflows, here's an easier method of
|
||||
opening a pull request.
|
||||
opening a pull request. The figure below outlines the steps and the details follow.
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
A([fa:fa-user New<br>Contributor]) --- id1[(K8s/Website<br>GitHub)]
|
||||
subgraph tasks[Changes using GitHub]
|
||||
direction TB
|
||||
0[ ] -.-
|
||||
1[1. Edit this page] --> 2[2. Use GitHub markdown<br>editor to make changes]
|
||||
2 --> 3[3. fill in Propose file change]
|
||||
|
||||
end
|
||||
subgraph tasks2[ ]
|
||||
direction TB
|
||||
4[4. select Propose file change] --> 5[5. select Create pull request] --> 6[6. fill in Open a pull request]
|
||||
6 --> 7[7. select Create pull request]
|
||||
end
|
||||
|
||||
id1 --> tasks --> tasks2
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,1,2,3,4,5,6,7 grey
|
||||
class 0 spacewhite
|
||||
class tasks,tasks2 white
|
||||
class id1 k8s
|
||||
{{</ mermaid >}}
|
||||
|
||||
***Figure - Steps for opening a PR using GitHub***
|
||||
|
||||
1. On the page where you see the issue, select the pencil icon at the top right.
|
||||
You can also scroll to the bottom of the page and select **Edit this page**.
|
||||
@@ -89,6 +122,37 @@ work from a local fork.
|
||||
|
||||
Make sure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your computer. You can also use a git UI application.
|
||||
|
||||
The figure below shows the steps to follow when you work from a local fork. The details for each step follow.
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
1[Fork the K8s/website<br>repository] --> 2[Create local clone<br>and set upstream]
|
||||
subgraph changes[Your changes]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
3[Create a branch<br>example: my_new_branch] --> 3a[Make changes using<br>text editor] --> 4["Preview your changes<br>locally using Hugo<br>(localhost:1313)<br>or build container image"]
|
||||
end
|
||||
subgraph changes2[Commit / Push]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
5[Commit your changes] --> 6[Push commit to<br>origin/my_new_branch]
|
||||
end
|
||||
|
||||
2 --> changes --> changes2
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class 1,2,3,3a,4,5,6 grey
|
||||
class S,T spacewhite
|
||||
class changes,changes2 white
|
||||
{{</ mermaid >}}
|
||||
***Figure - Working from a local fork to make your changes***
|
||||
|
||||
### Fork the kubernetes/website repository
|
||||
|
||||
1. Navigate to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository.
|
||||
@@ -289,6 +353,34 @@ Alternately, install and use the `hugo` command on your computer:
|
||||
|
||||
### Open a pull request from your fork to kubernetes/website {#open-a-pr}
|
||||
|
||||
The figure below shows the steps to open a PR from your fork to the K8s/website. The details follow.
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph first[ ]
|
||||
direction TB
|
||||
1[1. Go to K8s/website repository] --> 2[2. Select New Pull Request]
|
||||
2 --> 3[3. Select compare across forks]
|
||||
3 --> 4[4. Select your fork from<br>head repository drop-down menu]
|
||||
end
|
||||
subgraph second [ ]
|
||||
direction TB
|
||||
5[5. Select your branch from<br>the compare drop-down menu] --> 6[6. Select Create Pull Request]
|
||||
6 --> 7[7. Add a description<br>to your PR]
|
||||
7 --> 8[8. Select Create pull request]
|
||||
end
|
||||
|
||||
first --> second
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
class 1,2,3,4,5,6,7,8 grey
|
||||
class first,second white
|
||||
{{</ mermaid >}}
|
||||
***Figure - Steps to open a PR from your fork to the K8s/website***
|
||||
|
||||
1. In a web browser, go to the [`kubernetes/website`](https://github.com/kubernetes/website/) repository.
|
||||
2. Select **New Pull Request**.
|
||||
3. Select **compare across forks**.
|
||||
@@ -303,7 +395,7 @@ Alternately, install and use the `hugo` command on your computer:
|
||||
|
||||
8. Select the **Create pull request** button.
|
||||
|
||||
Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls).
|
||||
Congratulations! Your pull request is available in [Pull requests](https://github.com/kubernetes/website/pulls).
|
||||
|
||||
|
||||
After opening a PR, GitHub runs automated tests and tries to deploy a preview using [Netlify](https://www.netlify.com/).
|
||||
@@ -414,7 +506,6 @@ If another contributor commits changes to the same file in another PR, it can cr
|
||||
|
||||
The pull request no longer shows any conflicts.
|
||||
|
||||
|
||||
### Squashing commits
|
||||
|
||||
{{< note >}}
|
||||
@@ -500,11 +591,8 @@ Most repositories use issue and PR templates. Have a look through some open
|
||||
issues and PRs to get a feel for that team's processes. Make sure to fill out
|
||||
the templates with as much detail as possible when you file issues or PRs.
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
- Read [Reviewing](/docs/contribute/review/reviewing-prs) to learn more about the review process.
|
||||
|
||||
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: Contributing new content overview
|
||||
linktitle: Overview
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 5
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This section contains information you should know before contributing new content.
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Contributing basics
|
||||
|
||||
- Write Kubernetes documentation in Markdown and build the Kubernetes site using [Hugo](https://gohugo.io/).
|
||||
- The source is in [GitHub](https://github.com/kubernetes/website). You can find Kubernetes documentation at `/content/en/docs/`. Some of the reference documentation is automatically generated from scripts in the `update-imported-docs/` directory.
|
||||
- [Page content types](/docs/contribute/style/page-content-types/) describe the presentation of documentation content in Hugo.
|
||||
- In addition to the standard Hugo shortcodes, we use a number of
|
||||
[custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) in our documentation to control the presentation of content.
|
||||
- Documentation source is available in multiple languages in `/content/`. Each
|
||||
language has its own folder with a two-letter code determined by the
|
||||
[ISO 639-1 standard](https://www.loc.gov/standards/iso639-2/php/code_list.php). For
|
||||
example, English documentation source is stored in `/content/en/docs/`.
|
||||
- For more information about contributing to documentation in multiple languages or starting a new translation, see [localization](/docs/contribute/localization).
|
||||
|
||||
## Before you begin {#before-you-begin}
|
||||
|
||||
### Sign the CNCF CLA {#sign-the-cla}
|
||||
|
||||
All Kubernetes contributors **must** read the [Contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) and [sign the Contributor License Agreement (CLA)](https://github.com/kubernetes/community/blob/master/CLA.md).
|
||||
|
||||
Pull requests from contributors who haven't signed the CLA fail the automated tests. The name and email you provide must match those found in your `git config`, and your git name and email must match those used for the CNCF CLA.
|
||||
|
||||
### Choose which Git branch to use
|
||||
|
||||
When opening a pull request, you need to know in advance which branch to base your work on.
|
||||
|
||||
Scenario | Branch
|
||||
:---------|:------------
|
||||
Existing or new English language content for the current release | `main`
|
||||
Content for a feature change release | The branch which corresponds to the major and minor version the feature change is in, using the pattern `dev-<version>`. For example, if a feature changes in the `v{{< skew nextMinorVersion >}}` release, then add documentation changes to the ``dev-{{< skew nextMinorVersion >}}`` branch.
|
||||
Content in other languages (localizations) | Use the localization's convention. See the [Localization branching strategy](/docs/contribute/localization/#branching-strategy) for more information.
|
||||
|
||||
|
||||
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack.
|
||||
|
||||
{{< note >}}
|
||||
If you already submitted your pull request and you know that the base branch
|
||||
was wrong, you (and only you, the submitter) can change it.
|
||||
{{< /note >}}
|
||||
|
||||
### Languages per PR
|
||||
|
||||
Limit pull requests to one language per PR. If you need to make an identical change to the same code sample in multiple languages, open a separate PR for each language.
|
||||
|
||||
## Tools for contributors
|
||||
|
||||
The [doc contributors tools](https://github.com/kubernetes/website/tree/main/content/en/docs/doc-contributor-tools) directory in the `kubernetes/website` repository contains tools to help your contribution journey go more smoothly.
|
||||
|
||||
|
||||
@@ -36,7 +36,38 @@ Before you start a review:
|
||||
|
||||
## Review process
|
||||
|
||||
In general, review pull requests for content and style in English.
|
||||
In general, review pull requests for content and style in English. The figure below outlines the steps for the review process. The details for each step follow.
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph fourth[Start review]
|
||||
direction TB
|
||||
S[ ] -.-
|
||||
M[add comments] --> N[review changes]
|
||||
N --> O[new contributors should<br>choose Comment]
|
||||
end
|
||||
subgraph third[Select PR]
|
||||
direction TB
|
||||
T[ ] -.-
|
||||
J[read description<br>and comments]--> K[preview changes in<br>Netlify preview build]
|
||||
end
|
||||
|
||||
A[Review open PR list]--> B[Filter open PRs<br>by label]
|
||||
B --> third --> fourth
|
||||
|
||||
|
||||
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
|
||||
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
|
||||
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
|
||||
class A,B,J,K,M,N,O grey
|
||||
class S,T spacewhite
|
||||
class third,fourth white
|
||||
{{</ mermaid >}}
|
||||
|
||||
***Figure - Review process steps***
|
||||
|
||||
1. Go to
|
||||
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
|
||||
|
||||
@@ -134,6 +134,21 @@ The output is similar to this:
|
||||
no
|
||||
```
|
||||
|
||||
Similarly, to check whether a Service Account named `dev-sa` in Namespace `dev`
|
||||
can list Pods in the Namespace `target`:
|
||||
|
||||
```bash
|
||||
kubectl auth can-i list pods \
|
||||
--namespace target \
|
||||
--as system:serviceaccount:dev:dev-sa
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
```
|
||||
yes
|
||||
```
|
||||
|
||||
`SelfSubjectAccessReview` is part of the `authorization.k8s.io` API group, which
|
||||
exposes the API server authorization to external services. Other resources in
|
||||
this group include:
|
||||
@@ -192,22 +207,33 @@ The following flags can be used:
|
||||
You can choose more than one authorization module. Modules are checked in order
|
||||
so an earlier module has higher priority to allow or deny a request.
|
||||
|
||||
## Privilege escalation via pod creation
|
||||
## Privilege escalation via workload creation or edits {#privilege-escalation-via-pod-creation}
|
||||
|
||||
Users who have the ability to create pods in a namespace can potentially
|
||||
escalate their privileges within that namespace. They can create pods that
|
||||
access their privileges within that namespace. They can create pods that access
|
||||
secrets the user cannot themselves read, or that run under a service account
|
||||
with different/greater permissions.
|
||||
Users who can create/edit pods in a namespace, either directly or through a [controller](/docs/concepts/architecture/controller/)
|
||||
such as an operator, could escalate their privileges in that namespace.
|
||||
|
||||
{{< caution >}}
|
||||
System administrators, use care when granting access to pod creation. A user
|
||||
granted permission to create pods (or controllers that create pods) in the
|
||||
namespace can: read all secrets in the namespace; read all config maps in the
|
||||
namespace; and impersonate any service account in the namespace and take any
|
||||
action the account could take. This applies regardless of authorization mode.
|
||||
System administrators, use care when granting access to create or edit workloads.
|
||||
Details of how these can be misused are documented in [escalation paths](/docs/reference/access-authn-authz/authorization/#escalation-paths)
|
||||
{{< /caution >}}
|
||||
|
||||
### Escalation paths {#escalation-paths}
|
||||
- Mounting arbitrary secrets in that namespace
|
||||
- Can be used to access secrets meant for other workloads
|
||||
- Can be used to obtain a more privileged service account's service account token
|
||||
- Using arbitrary Service Accounts in that namespace
|
||||
- Can perform Kubernetes API actions as another workload (impersonation)
|
||||
- Can perform any privileged actions that Service Account has
|
||||
- Mounting configmaps meant for other workloads in that namespace
|
||||
- Can be used to obtain information meant for other workloads, such as DB host names.
|
||||
- Mounting volumes meant for other workloads in that namespace
|
||||
- Can be used to obtain information meant for other workloads, and change it.
|
||||
|
||||
{{< caution >}}
|
||||
System administrators should be cautious when deploying CRDs that
|
||||
change the above areas. These may open privilege escalations paths.
|
||||
This should be considered when deciding on your RBAC controls.
|
||||
{{< /caution >}}
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
@@ -67,7 +67,7 @@ See the [webhook request](#request) section for details on the data sent to webh
|
||||
See the [webhook response](#response) section for the data expected from webhooks.
|
||||
|
||||
The example admission webhook server leaves the `ClientAuth` field
|
||||
[empty](https://github.com/kubernetes/kubernetes/blob/v1.13.0/test/images/webhook/config.go#L47-L48),
|
||||
[empty](https://github.com/kubernetes/kubernetes/blob/v1.22.0/test/images/agnhost/webhook/config.go#L38-L39),
|
||||
which defaults to `NoClientCert`. This means that the webhook server does not
|
||||
authenticate the identity of the clients, supposedly apiservers. If you need
|
||||
mutual TLS or other ways to authenticate the clients, see
|
||||
@@ -79,7 +79,7 @@ The webhook server in the e2e test is deployed in the Kubernetes cluster, via
|
||||
the [deployment API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#deployment-v1-apps).
|
||||
The test also creates a [service](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core)
|
||||
as the front-end of the webhook server. See
|
||||
[code](https://github.com/kubernetes/kubernetes/blob/v1.15.0/test/e2e/apimachinery/webhook.go#L301).
|
||||
[code](https://github.com/kubernetes/kubernetes/blob/v1.22.0/test/e2e/apimachinery/webhook.go#L748).
|
||||
|
||||
You may also deploy your webhooks outside of the cluster. You will need to update
|
||||
your webhook configurations accordingly.
|
||||
|
||||
@@ -125,7 +125,6 @@ different Kubernetes components.
|
||||
| `HPAScaleToZero` | `false` | Alpha | 1.16 | |
|
||||
| `IndexedJob` | `false` | Alpha | 1.21 | 1.21 |
|
||||
| `IndexedJob` | `true` | Beta | 1.22 | |
|
||||
| `JobTrackingWithFinalizers` | `false` | Alpha | 1.22 | |
|
||||
| `IngressClassNamespacedParams` | `false` | Alpha | 1.21 | 1.21 |
|
||||
| `IngressClassNamespacedParams` | `true` | Beta | 1.22 | |
|
||||
| `InTreePluginAWSUnregister` | `false` | Alpha | 1.21 | |
|
||||
@@ -138,13 +137,13 @@ different Kubernetes components.
|
||||
| `IPv6DualStack` | `true` | Beta | 1.21 | |
|
||||
| `JobTrackingWithFinalizers` | `false` | Alpha | 1.22 | |
|
||||
| `KubeletCredentialProviders` | `false` | Alpha | 1.20 | |
|
||||
| `KubeletInUserNamespace` | `false` | Alpha | 1.22 | |
|
||||
| `KubeletPodResourcesGetAllocatable` | `false` | Alpha | 1.21 | |
|
||||
| `LocalStorageCapacityIsolation` | `false` | Alpha | 1.7 | 1.9 |
|
||||
| `LocalStorageCapacityIsolation` | `true` | Beta | 1.10 | |
|
||||
| `LocalStorageCapacityIsolationFSQuotaMonitoring` | `false` | Alpha | 1.15 | |
|
||||
| `LogarithmicScaleDown` | `false` | Alpha | 1.21 | 1.21 |
|
||||
| `LogarithmicScaleDown` | `true` | Beta | 1.22 | |
|
||||
| `KubeletInUserNamespace` | `false` | Alpha | 1.22 | |
|
||||
| `KubeletPodResourcesGetAllocatable` | `false` | Alpha | 1.21 | |
|
||||
| `MemoryManager` | `false` | Alpha | 1.21 | 1.21 |
|
||||
| `MemoryManager` | `true` | Beta | 1.22 | |
|
||||
| `MemoryQoS` | `false` | Alpha | 1.22 | |
|
||||
@@ -287,9 +286,6 @@ different Kubernetes components.
|
||||
| `DynamicKubeletConfig` | `false` | Deprecated | 1.22 | - |
|
||||
| `DynamicProvisioningScheduling` | `false` | Alpha | 1.11 | 1.11 |
|
||||
| `DynamicProvisioningScheduling` | - | Deprecated| 1.12 | - |
|
||||
| `DynamicKubeletConfig` | `false` | Alpha | 1.4 | 1.10 |
|
||||
| `DynamicKubeletConfig` | `true` | Beta | 1.11 | 1.21 |
|
||||
| `DynamicKubeletConfig` | `false` | Deprecated | 1.22 | - |
|
||||
| `DynamicVolumeProvisioning` | `true` | Alpha | 1.3 | 1.7 |
|
||||
| `DynamicVolumeProvisioning` | `true` | GA | 1.8 | - |
|
||||
| `EnableAggregatedDiscoveryTimeout` | `true` | Deprecated | 1.16 | - |
|
||||
|
||||
@@ -51,7 +51,7 @@ kubelet [flags]
|
||||
<td colspan="2">--address string Default: 0.0.0.0 </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td></td><td style="line-height: 130%; word-wrap: break-word;">The IP address for the Kubelet to serve on (set to <code>0.0.0.0</code> or <code>::</code> for listening in gll interfaces and IP families) (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's <code>--config</code> flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.)</td>
|
||||
<td></td><td style="line-height: 130%; word-wrap: break-word;">The IP address for the Kubelet to serve on (set to <code>0.0.0.0</code> or <code>::</code> for listening in all interfaces and IP families) (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's <code>--config</code> flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.)</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
|
||||
@@ -10,9 +10,9 @@ aka:
|
||||
tags:
|
||||
- fundamental
|
||||
---
|
||||
An abstraction used by Kubernetes to support multiple virtual clusters on the same physical {{< glossary_tooltip text="cluster" term_id="cluster" >}}.
|
||||
An abstraction used by Kubernetes to support isolation of groups of resources within a single {{< glossary_tooltip text="cluster" term_id="cluster" >}}.
|
||||
|
||||
<!--more-->
|
||||
|
||||
Namespaces are used to organize objects in a cluster and provide a way to divide cluster resources. Names of resources need to be unique within a namespace, but not across namespaces.
|
||||
Namespaces are used to organize objects in a cluster and provide a way to divide cluster resources. Names of resources need to be unique within a namespace, but not across namespaces. Namespace-based scoping is applicable only for namespaced objects _(e.g. Deployments, Services, etc)_ and not for cluster-wide objects _(e.g. StorageClass, Nodes, PersistentVolumes, etc)_.
|
||||
|
||||
|
||||
@@ -142,6 +142,22 @@ For information about enabling IPVS mode with kubeadm see:
|
||||
For information about passing flags to control plane components see:
|
||||
- [control-plane-flags](/docs/setup/production-environment/tools/kubeadm/control-plane-flags/)
|
||||
|
||||
### Running kubeadm without an Internet connection {#without-internet-connection}
|
||||
|
||||
For running kubeadm without an Internet connection you have to pre-pull the required control-plane images.
|
||||
|
||||
You can list and pull the images using the `kubeadm config images` sub-command:
|
||||
|
||||
```shell
|
||||
kubeadm config images list
|
||||
kubeadm config images pull
|
||||
```
|
||||
|
||||
You can pass `--config` to the above commands with a [kubeadm configuration file](#config-file)
|
||||
to control the `kubernetesVersion` and `imageRepository` fields.
|
||||
|
||||
All default `k8s.gcr.io` images that kubeadm requires support multiple architectures.
|
||||
|
||||
### Using custom images {#custom-images}
|
||||
|
||||
By default, kubeadm pulls images from `k8s.gcr.io`. If the
|
||||
@@ -151,13 +167,24 @@ requested Kubernetes version is a CI label (such as `ci/latest`)
|
||||
You can override this behavior by using [kubeadm with a configuration file](#config-file).
|
||||
Allowed customization are:
|
||||
|
||||
* To provide `kubernetesVersion` which affects the version of the images.
|
||||
* To provide an alternative `imageRepository` to be used instead of
|
||||
`k8s.gcr.io`.
|
||||
* To set `useHyperKubeImage` to `true` to use the HyperKube image.
|
||||
* To provide a specific `imageRepository` and `imageTag` for etcd or DNS add-on.
|
||||
* To provide a specific `imageRepository` and `imageTag` for etcd or CoreDNS.
|
||||
|
||||
Please note that the configuration field `kubernetesVersion` or the command line flag
|
||||
`--kubernetes-version` affect the version of the images.
|
||||
Image paths between the default `k8s.gcr.io` and a custom repository specified using
|
||||
`imageRepository` may differ for backwards compatibility reasons. For example,
|
||||
one image might have a subpath at `k8s.gcr.io/subpath/image`, but be defaulted
|
||||
to `my.customrepository.io/image` when using a custom repository.
|
||||
|
||||
To ensure you push the images to your custom repository in paths that kubeadm
|
||||
can consume, you must:
|
||||
|
||||
* Pull images from the defaults paths at `k8s.gcr.io` using `kubeadm config images {list|pull}`.
|
||||
* Push images to the paths from `kubeadm config images list --config=config.yaml`,
|
||||
where `config.yaml` contains the custom `imageRepository`, and/or `imageTag`
|
||||
for etcd and CoreDNS.
|
||||
* Pass the same `config.yaml` to `kubeadm init`.
|
||||
|
||||
### Uploading control-plane certificates to the cluster
|
||||
|
||||
@@ -209,19 +236,6 @@ value to the kubelet.
|
||||
|
||||
Be aware that overriding the hostname can [interfere with cloud providers](https://github.com/kubernetes/website/pull/8873).
|
||||
|
||||
### Running kubeadm without an internet connection
|
||||
|
||||
For running kubeadm without an internet connection you have to pre-pull the required control-plane images.
|
||||
|
||||
You can list and pull the images using the `kubeadm config images` sub-command:
|
||||
|
||||
```shell
|
||||
kubeadm config images list
|
||||
kubeadm config images pull
|
||||
```
|
||||
|
||||
All images that kubeadm requires such as `k8s.gcr.io/kube-*`, `k8s.gcr.io/etcd` and `k8s.gcr.io/pause` support multiple architectures.
|
||||
|
||||
### Automating kubeadm
|
||||
|
||||
Rather than copying the token you obtained from `kubeadm init` to each node, as
|
||||
|
||||
@@ -287,7 +287,7 @@ If your configuration is not using the latest version it is **recommended** that
|
||||
the [kubeadm config migrate](/docs/reference/setup-tools/kubeadm/kubeadm-config/) command.
|
||||
|
||||
For more information on the fields and usage of the configuration you can navigate to our
|
||||
[API reference](/docs/reference/config-api/kubeadm-config.v1beta2/).
|
||||
[API reference](/docs/reference/config-api/kubeadm-config.v1beta3/).
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ behind one command, with support for both planning an upgrade and actually perfo
|
||||
|
||||
## kubeadm upgrade guidance
|
||||
|
||||
The steps for performing a upgrade using kubeadm are outlined in [this document](/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/).
|
||||
The steps for performing an upgrade using kubeadm are outlined in [this document](/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/).
|
||||
For older versions of kubeadm, please refer to older documentation sets of the Kubernetes website.
|
||||
|
||||
You can use `kubeadm upgrade diff` to see the changes that would be applied to static pod manifests.
|
||||
|
||||
@@ -8,8 +8,7 @@ no_list: true
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
Kubernetes contains several built-in tools and external tools that are commonly used or relevant that may as well be seen as required for Kubernetes to function.
|
||||
|
||||
Kubernetes contains several tools to help you work with the Kubernetes system.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
@@ -25,10 +24,14 @@ development and testing purposes.
|
||||
to a Kubernetes cluster, troubleshoot them, and manage the cluster and its resources itself.
|
||||
|
||||
## Helm
|
||||
{{% thirdparty-content single="true" %}}
|
||||
|
||||
[Helm](https://helm.sh/) is a tool for managing packages of pre-configured
|
||||
Kubernetes resources. These packages are known as _Helm charts_.
|
||||
|
||||
Helm is a third party managed tool for managing packages of pre-configured
|
||||
Kubernetes resources, aka Kubernetes charts.
|
||||
|
||||
Use Helm to:
|
||||
|
||||
* Find and use popular software packaged as Kubernetes charts
|
||||
|
||||
@@ -109,7 +109,7 @@ objects.
|
||||
|
||||
All of this is best illustrated by examples. Imagine a Kubernetes release,
|
||||
version X, which introduces a new API group. A new Kubernetes release is made
|
||||
every approximately 3 months (4 per year). The following table describes which
|
||||
every approximately 4 months (3 per year). The following table describes which
|
||||
API versions are supported in a series of subsequent releases.
|
||||
|
||||
<table>
|
||||
|
||||
@@ -38,11 +38,13 @@ etcd also implements mutual TLS to authenticate clients and peers.
|
||||
|
||||
## Where certificates are stored
|
||||
|
||||
If you install Kubernetes with kubeadm, certificates are stored in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory.
|
||||
If you install Kubernetes with kubeadm, most certificates are stored in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory, with the exception of user account certificates which kubeadm places in `/etc/kubernetes`.
|
||||
|
||||
## Configure certificates manually
|
||||
|
||||
If you don't want kubeadm to generate the required certificates, you can create them in either of the following ways.
|
||||
If you don't want kubeadm to generate the required certificates, you can create them using a single root CA or by providing all certificates. See [Certificates](/docs/tasks/administer-cluster/certificates/) for details on creating your own certificate authority.
|
||||
See [Certificate Management with kubeadm](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/) for more on managing certificates.
|
||||
|
||||
|
||||
### Single root CA
|
||||
|
||||
@@ -57,7 +59,16 @@ Required CAs:
|
||||
| front-proxy-ca.crt,key | kubernetes-front-proxy-ca | For the [front-end proxy](/docs/tasks/extend-kubernetes/configure-aggregation-layer/) |
|
||||
|
||||
On top of the above CAs, it is also necessary to get a public/private key pair for service account management, `sa.key` and `sa.pub`.
|
||||
The following example illustrates the CA key and certificate files shown in the previous table:
|
||||
|
||||
```
|
||||
/etc/kubernetes/pki/ca.crt
|
||||
/etc/kubernetes/pki/ca.key
|
||||
/etc/kubernetes/pki/etcd/ca.crt
|
||||
/etc/kubernetes/pki/etcd/ca.key
|
||||
/etc/kubernetes/pki/front-proxy-ca.crt
|
||||
/etc/kubernetes/pki/front-proxy-ca.key
|
||||
```
|
||||
### All certificates
|
||||
|
||||
If you don't wish to copy the CA private keys to your cluster, you can generate all certificates yourself.
|
||||
@@ -127,6 +138,32 @@ Same considerations apply for the service account key pair:
|
||||
| sa.key | | kube-controller-manager | --service-account-private-key-file |
|
||||
| | sa.pub | kube-apiserver | --service-account-key-file |
|
||||
|
||||
The following example illustrates the file paths [from the previous tables](/docs/setup/best-practices/certificates/#certificate-paths) you need to provide if you are generating all of your own keys and certificates:
|
||||
|
||||
```
|
||||
/etc/kubernetes/pki/etcd/ca.key
|
||||
/etc/kubernetes/pki/etcd/ca.crt
|
||||
/etc/kubernetes/pki/apiserver-etcd-client.key
|
||||
/etc/kubernetes/pki/apiserver-etcd-client.crt
|
||||
/etc/kubernetes/pki/ca.key
|
||||
/etc/kubernetes/pki/ca.crt
|
||||
/etc/kubernetes/pki/apiserver.key
|
||||
/etc/kubernetes/pki/apiserver.crt
|
||||
/etc/kubernetes/pki/apiserver-kubelet-client.key
|
||||
/etc/kubernetes/pki/apiserver-kubelet-client.crt
|
||||
/etc/kubernetes/pki/front-proxy-ca.key
|
||||
/etc/kubernetes/pki/front-proxy-ca.crt
|
||||
/etc/kubernetes/pki/front-proxy-client.key
|
||||
/etc/kubernetes/pki/front-proxy-client.crt
|
||||
/etc/kubernetes/pki/etcd/server.key
|
||||
/etc/kubernetes/pki/etcd/server.crt
|
||||
/etc/kubernetes/pki/etcd/peer.key
|
||||
/etc/kubernetes/pki/etcd/peer.crt
|
||||
/etc/kubernetes/pki/etcd/healthcheck-client.key
|
||||
/etc/kubernetes/pki/etcd/healthcheck-client.crt
|
||||
/etc/kubernetes/pki/sa.key
|
||||
/etc/kubernetes/pki/sa.pub
|
||||
```
|
||||
## Configure certificates for user accounts
|
||||
|
||||
You must manually configure these administrator account and service accounts:
|
||||
@@ -146,7 +183,7 @@ The value of `<nodeName>` for `kubelet.conf` **must** match precisely the value
|
||||
|
||||
1. Run `kubectl` as follows for each config:
|
||||
|
||||
```shell
|
||||
```
|
||||
KUBECONFIG=<filename> kubectl config set-cluster default-cluster --server=https://<host ip>:6443 --certificate-authority <path-to-kubernetes-ca> --embed-certs
|
||||
KUBECONFIG=<filename> kubectl config set-credentials <credential-name> --client-key <path-to-key>.pem --client-certificate <path-to-cert>.pem --embed-certs
|
||||
KUBECONFIG=<filename> kubectl config set-context default-system --cluster default-cluster --user <credential-name>
|
||||
@@ -162,4 +199,11 @@ These files are used as follows:
|
||||
| controller-manager.conf | kube-controller-manager | Must be added to manifest in `manifests/kube-controller-manager.yaml` |
|
||||
| scheduler.conf | kube-scheduler | Must be added to manifest in `manifests/kube-scheduler.yaml` |
|
||||
|
||||
The following files illustrate full paths to the files listed in the previous table:
|
||||
|
||||
```
|
||||
/etc/kubernetes/admin.conf
|
||||
/etc/kubernetes/kubelet.conf
|
||||
/etc/kubernetes/controller-manager.conf
|
||||
/etc/kubernetes/scheduler.conf
|
||||
```
|
||||
|
||||
@@ -9,7 +9,7 @@ weight: 40
|
||||
<!-- overview -->
|
||||
|
||||
This page covers how to customize the components that kubeadm deploys. For control plane components
|
||||
you can use flags in the `ClusteConfiguration` structure or patches per-node. For the kubelet
|
||||
you can use flags in the `ClusterConfiguration` structure or patches per-node. For the kubelet
|
||||
and kube-proxy you can use `KubeletConfiguration` and `KubeProxyConfiguration`, accordingly.
|
||||
|
||||
All of these options are possible via the kubeadm configuration API.
|
||||
|
||||
+13
-2
@@ -83,6 +83,19 @@ kubeadm to tell it what to do. This crashloop is expected and normal.
|
||||
After you initialize your control-plane, the kubelet runs normally.
|
||||
{{< /note >}}
|
||||
|
||||
### Preparing the required container images
|
||||
|
||||
This step is optional and only applies in case you wish `kubeadm init` and `kubeadm join`
|
||||
to not download the default container images which are hosted at `k8s.gcr.io`.
|
||||
|
||||
Kubeadm has commands that can help you pre-pull the required images
|
||||
when creating a cluster without an internet connection on its nodes.
|
||||
See [Running kubeadm without an internet connection](/docs/reference/setup-tools/kubeadm/kubeadm-init#without-internet-connection) for more details.
|
||||
|
||||
Kubeadm allows you to use a custom image repository for the required images.
|
||||
See [Using custom images](docs/reference/setup-tools/kubeadm/kubeadm-init#custom-images)
|
||||
for more details.
|
||||
|
||||
### Initializing your control-plane node
|
||||
|
||||
The control-plane node is the machine where the control plane components run, including
|
||||
@@ -108,8 +121,6 @@ with the default gateway to set the advertise address for this particular contro
|
||||
To use a different network interface, specify the `--apiserver-advertise-address=<ip-address>` argument
|
||||
to `kubeadm init`. To deploy an IPv6 Kubernetes cluster using IPv6 addressing, you
|
||||
must specify an IPv6 address, for example `--apiserver-advertise-address=fd00::101`
|
||||
1. (Optional) Run `kubeadm config images pull` prior to `kubeadm init` to verify
|
||||
connectivity to the gcr.io container image registry.
|
||||
|
||||
To initialize the control-plane node run:
|
||||
|
||||
|
||||
@@ -93,6 +93,10 @@ kind: JoinConfiguration
|
||||
discovery:
|
||||
bootstrapToken:
|
||||
apiServerEndpoint: 10.100.0.1:6443
|
||||
token: "clvldh.vjjwg16ucnhp94qr"
|
||||
caCertHashes:
|
||||
- "sha256:a4863cde706cfc580a439f842cc65d5ef112b7b2be31628513a9881cf0d9fe0e"
|
||||
# change auth info above to match the actual token and CA certificate hash for your cluster
|
||||
nodeRegistration:
|
||||
kubeletExtraArgs:
|
||||
node-ip: 10.100.0.3,fd00:1:2:3::3
|
||||
@@ -109,6 +113,10 @@ controlPlane:
|
||||
discovery:
|
||||
bootstrapToken:
|
||||
apiServerEndpoint: 10.100.0.1:6443
|
||||
token: "clvldh.vjjwg16ucnhp94qr"
|
||||
caCertHashes:
|
||||
- "sha256:a4863cde706cfc580a439f842cc65d5ef112b7b2be31628513a9881cf0d9fe0e"
|
||||
# change auth info above to match the actual token and CA certificate hash for your cluster
|
||||
nodeRegistration:
|
||||
kubeletExtraArgs:
|
||||
node-ip: 10.100.0.4,fd00:1:2:3::4
|
||||
@@ -118,7 +126,7 @@ nodeRegistration:
|
||||
`advertiseAddress` in JoinConfiguration.controlPlane specifies the IP address that the API Server will advertise it is listening on. The value of `advertiseAddress` equals the `--apiserver-advertise-address` flag of `kubeadm join`.
|
||||
|
||||
```shell
|
||||
kubeadm join --config=kubeadm-config.yaml ...
|
||||
kubeadm join --config=kubeadm-config.yaml
|
||||
```
|
||||
|
||||
### Create a single-stack cluster
|
||||
@@ -150,4 +158,4 @@ networking:
|
||||
|
||||
* [Validate IPv4/IPv6 dual-stack](/docs/tasks/network/validate-dual-stack) networking
|
||||
* Read about [Dual-stack](/docs/concepts/services-networking/dual-stack/) cluster networking
|
||||
* Learn more about the kubeadm [configuration format](/docs/reference/config-api/kubeadm-config.v1beta2/)
|
||||
* Learn more about the kubeadm [configuration format](/docs/reference/config-api/kubeadm-config.v1beta3/)
|
||||
|
||||
@@ -77,7 +77,7 @@ option. Your cluster requirements may need a different configuration.
|
||||
- Make sure the address of the load balancer always matches
|
||||
the address of kubeadm's `ControlPlaneEndpoint`.
|
||||
|
||||
- Read the [Options for Software Load Balancing](https://github.com/kubernetes/kubeadm/blob/master/docs/ha-considerations.md#options-for-software-load-balancing)
|
||||
- Read the [Options for Software Load Balancing](https://git.k8s.io/kubeadm/docs/ha-considerations.md#options-for-software-load-balancing)
|
||||
guide for more details.
|
||||
|
||||
1. Add the first control plane nodes to the load balancer and test the
|
||||
|
||||
+2
-2
@@ -262,7 +262,7 @@ Error from server: Get https://10.19.0.41:10250/containerLogs/default/mysql-ddc6
|
||||
When using DigitalOcean, it can be the public one (assigned to `eth0`) or
|
||||
the private one (assigned to `eth1`) should you want to use the optional
|
||||
private network. The `kubeletExtraArgs` section of the kubeadm
|
||||
[`NodeRegistrationOptions` structure](/docs/reference/config-api/kubeadm-config.v1beta2/#kubeadm-k8s-io-v1beta2-NodeRegistrationOptions)
|
||||
[`NodeRegistrationOptions` structure](/docs/reference/config-api/kubeadm-config.v1beta3/#kubeadm-k8s-io-v1beta3-NodeRegistrationOptions)
|
||||
can be used for this.
|
||||
|
||||
Then restart `kubelet`:
|
||||
@@ -336,7 +336,7 @@ Alternatively, you can try separating the `key=value` pairs like so:
|
||||
`--apiserver-extra-args "enable-admission-plugins=LimitRanger,enable-admission-plugins=NamespaceExists"`
|
||||
but this will result in the key `enable-admission-plugins` only having the value of `NamespaceExists`.
|
||||
|
||||
A known workaround is to use the kubeadm [configuration file](/docs/reference/config-api/kubeadm-config.v1beta2/).
|
||||
A known workaround is to use the kubeadm [configuration file](/docs/reference/config-api/kubeadm-config.v1beta3/).
|
||||
|
||||
## kube-proxy scheduled before node is initialized by cloud-controller-manager
|
||||
|
||||
|
||||
+783
-1153
File diff suppressed because it is too large
Load Diff
@@ -2,6 +2,7 @@
|
||||
title: Set up Ingress on Minikube with the NGINX Ingress Controller
|
||||
content_type: task
|
||||
weight: 100
|
||||
min-kubernetes-server-version: 1.19
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
@@ -17,23 +18,21 @@ This page shows you how to set up a simple Ingress which routes requests to Serv
|
||||
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
If you are using an older Kubernetes version, switch to the documentation
|
||||
for that version.
|
||||
|
||||
|
||||
### Create a Minikube cluster
|
||||
|
||||
Using Katacoda
|
||||
: {{< kat-button >}}
|
||||
|
||||
Locally
|
||||
: If you already [installed Minikube](/docs/tasks/tools/#minikube)
|
||||
locally, run `minikube start` to create a cluster.
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
## Create a Minikube cluster
|
||||
|
||||
1. Click **Launch Terminal**
|
||||
|
||||
{{< kat-button >}}
|
||||
|
||||
1. (Optional) If you installed Minikube locally, run the following command:
|
||||
|
||||
```shell
|
||||
minikube start
|
||||
```
|
||||
|
||||
## Enable the Ingress controller
|
||||
|
||||
1. To enable the NGINX Ingress controller, run the following command:
|
||||
@@ -45,14 +44,14 @@ This page shows you how to set up a simple Ingress which routes requests to Serv
|
||||
1. Verify that the NGINX Ingress controller is running
|
||||
|
||||
|
||||
{{< tabs name="tab_with_md" >}}
|
||||
{{% tab name="minikube v1.19 or later" %}}
|
||||
{{< tabs name="tab_with_md" >}}
|
||||
{{% tab name="minikube v1.19 or later" %}}
|
||||
```shell
|
||||
kubectl get pods -n ingress-nginx
|
||||
```
|
||||
{{< note >}}This can take up to a minute.{{< /note >}}
|
||||
{{< note >}}It can take up to a minute before you see these pods running OK.{{< /note >}}
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
@@ -60,15 +59,14 @@ ingress-nginx-admission-create-g9g49 0/1 Completed 0 11m
|
||||
ingress-nginx-admission-patch-rqp78 0/1 Completed 1 11m
|
||||
ingress-nginx-controller-59b45fb494-26npt 1/1 Running 0 11m
|
||||
```
|
||||
{{% /tab %}}
|
||||
|
||||
{{% tab name="minikube v1.18.1 or earlier" %}}
|
||||
{{% /tab %}}
|
||||
{{% tab name="minikube v1.18.1 or earlier" %}}
|
||||
```shell
|
||||
kubectl get pods -n kube-system
|
||||
```
|
||||
{{< note >}}This can take up to a minute.{{< /note >}}
|
||||
{{< note >}}It can take up to a minute before you see these pods running OK.{{< /note >}}
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
@@ -79,133 +77,121 @@ kubernetes-dashboard-5498ccf677-b8p5h 1/1 Running 0 2m
|
||||
nginx-ingress-controller-5984b97644-rnkrg 1/1 Running 0 1m
|
||||
storage-provisioner 1/1 Running 0 2m
|
||||
```
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
|
||||
```shell
|
||||
kubectl get pods -n ingress-nginx
|
||||
```
|
||||
|
||||
{{< note >}}This can take up to a minute.{{< /note >}}
|
||||
|
||||
Output:
|
||||
|
||||
```shell
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
ingress-nginx-admission-create-2tgrf 0/1 Completed 0 3m28s
|
||||
ingress-nginx-admission-patch-68b98 0/1 Completed 0 3m28s
|
||||
ingress-nginx-controller-59b45fb494-lzmw2 1/1 Running 0 3m28s
|
||||
```
|
||||
|
||||
Make sure that you see a Pod with a name that starts with `nginx-ingress-controller-`.
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
## Deploy a hello, world app
|
||||
|
||||
1. Create a Deployment using the following command:
|
||||
|
||||
```shell
|
||||
kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0
|
||||
```
|
||||
```shell
|
||||
kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0
|
||||
```
|
||||
|
||||
Output:
|
||||
The output should be:
|
||||
|
||||
```shell
|
||||
deployment.apps/web created
|
||||
```
|
||||
```
|
||||
deployment.apps/web created
|
||||
```
|
||||
|
||||
1. Expose the Deployment:
|
||||
|
||||
```shell
|
||||
kubectl expose deployment web --type=NodePort --port=8080
|
||||
```
|
||||
```shell
|
||||
kubectl expose deployment web --type=NodePort --port=8080
|
||||
```
|
||||
|
||||
Output:
|
||||
The output should be:
|
||||
|
||||
```shell
|
||||
service/web exposed
|
||||
```
|
||||
```
|
||||
service/web exposed
|
||||
```
|
||||
|
||||
1. Verify the Service is created and is available on a node port:
|
||||
|
||||
```shell
|
||||
kubectl get service web
|
||||
```
|
||||
kubectl get service web
|
||||
```
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```shell
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
web NodePort 10.104.133.249 <none> 8080:31637/TCP 12m
|
||||
```
|
||||
```
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
web NodePort 10.104.133.249 <none> 8080:31637/TCP 12m
|
||||
```
|
||||
|
||||
1. Visit the service via NodePort:
|
||||
1. Visit the Service via NodePort:
|
||||
|
||||
```shell
|
||||
minikube service web --url
|
||||
```
|
||||
```shell
|
||||
minikube service web --url
|
||||
```
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```shell
|
||||
http://172.17.0.15:31637
|
||||
```
|
||||
```
|
||||
http://172.17.0.15:31637
|
||||
```
|
||||
|
||||
{{< note >}}Katacoda environment only: at the top of the terminal panel, click the plus sign, and then click **Select port to view on Host 1**. Enter the NodePort, in this case `31637`, and then click **Display Port**.{{< /note >}}
|
||||
{{< note >}}Katacoda environment only: at the top of the terminal panel, click the plus sign, and then click **Select port to view on Host 1**. Enter the NodePort, in this case `31637`, and then click **Display Port**.{{< /note >}}
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```shell
|
||||
Hello, world!
|
||||
Version: 1.0.0
|
||||
Hostname: web-55b8c6998d-8k564
|
||||
```
|
||||
```
|
||||
Hello, world!
|
||||
Version: 1.0.0
|
||||
Hostname: web-55b8c6998d-8k564
|
||||
```
|
||||
|
||||
You can now access the sample app via the Minikube IP address and NodePort. The next step lets you access
|
||||
the app using the Ingress resource.
|
||||
You can now access the sample app via the Minikube IP address and NodePort. The next step lets you access
|
||||
the app using the Ingress resource.
|
||||
|
||||
## Create an Ingress resource
|
||||
## Create an Ingress
|
||||
|
||||
The following file is an Ingress resource that sends traffic to your Service via hello-world.info.
|
||||
The following manifest defines an Ingress that sends traffic to your Service via hello-world.info.
|
||||
|
||||
1. Create `example-ingress.yaml` from the following file:
|
||||
|
||||
{{< codenew file="service/networking/example-ingress.yaml" >}}
|
||||
{{< codenew file="service/networking/example-ingress.yaml" >}}
|
||||
|
||||
1. Create the Ingress resource by running the following command:
|
||||
1. Create the Ingress object by running the following command:
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/service/networking/example-ingress.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f https://k8s.io/examples/service/networking/example-ingress.yaml
|
||||
```
|
||||
|
||||
Output:
|
||||
The output should be:
|
||||
|
||||
```shell
|
||||
ingress.networking.k8s.io/example-ingress created
|
||||
```
|
||||
```
|
||||
ingress.networking.k8s.io/example-ingress created
|
||||
```
|
||||
|
||||
1. Verify the IP address is set:
|
||||
|
||||
```shell
|
||||
kubectl get ingress
|
||||
```
|
||||
```shell
|
||||
kubectl get ingress
|
||||
```
|
||||
|
||||
{{< note >}}This can take a couple of minutes.{{< /note >}}
|
||||
{{< note >}}This can take a couple of minutes.{{< /note >}}
|
||||
|
||||
```shell
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
example-ingress <none> hello-world.info 172.17.0.15 80 38s
|
||||
```
|
||||
You should see an IPv4 address in the ADDRESS column; for example:
|
||||
|
||||
1. Add the following line to the bottom of the `/etc/hosts` file.
|
||||
```
|
||||
NAME CLASS HOSTS ADDRESS PORTS AGE
|
||||
example-ingress <none> hello-world.info 172.17.0.15 80 38s
|
||||
```
|
||||
|
||||
{{< note >}}If you are running Minikube locally, use `minikube ip` to get the external IP. The IP address displayed within the ingress list will be the internal IP.{{< /note >}}
|
||||
1. Add the following line to the bottom of the `/etc/hosts` file on
|
||||
your computer (you will need adminstrator access):
|
||||
|
||||
```
|
||||
172.17.0.15 hello-world.info
|
||||
```
|
||||
|
||||
This sends requests from hello-world.info to Minikube.
|
||||
{{< note >}}If you are running Minikube locally, use `minikube ip` to get the external IP. The IP address displayed within the ingress list will be the internal IP.{{< /note >}}
|
||||
|
||||
After you make this change, your web browser sends requests for
|
||||
hello-world.info URLs to Minikube.
|
||||
|
||||
1. Verify that the Ingress controller is directing traffic:
|
||||
|
||||
@@ -213,9 +199,9 @@ The following file is an Ingress resource that sends traffic to your Service via
|
||||
curl hello-world.info
|
||||
```
|
||||
|
||||
Output:
|
||||
You should see:
|
||||
|
||||
```shell
|
||||
```
|
||||
Hello, world!
|
||||
Version: 1.0.0
|
||||
Hostname: web-55b8c6998d-8k564
|
||||
@@ -223,34 +209,35 @@ The following file is an Ingress resource that sends traffic to your Service via
|
||||
|
||||
{{< note >}}If you are running Minikube locally, you can visit hello-world.info from your browser.{{< /note >}}
|
||||
|
||||
## Create Second Deployment
|
||||
## Create a second Deployment
|
||||
|
||||
1. Create a v2 Deployment using the following command:
|
||||
1. Create another Deployment using the following command:
|
||||
|
||||
```shell
|
||||
kubectl create deployment web2 --image=gcr.io/google-samples/hello-app:2.0
|
||||
```
|
||||
Output:
|
||||
```shell
|
||||
kubectl create deployment web2 --image=gcr.io/google-samples/hello-app:2.0
|
||||
```
|
||||
The output should be:
|
||||
|
||||
```shell
|
||||
deployment.apps/web2 created
|
||||
```
|
||||
```
|
||||
deployment.apps/web2 created
|
||||
```
|
||||
|
||||
1. Expose the Deployment:
|
||||
1. Expose the second Deployment:
|
||||
|
||||
```shell
|
||||
kubectl expose deployment web2 --port=8080 --type=NodePort
|
||||
```
|
||||
```shell
|
||||
kubectl expose deployment web2 --port=8080 --type=NodePort
|
||||
```
|
||||
|
||||
Output:
|
||||
The output should be:
|
||||
|
||||
```shell
|
||||
service/web2 exposed
|
||||
```
|
||||
```
|
||||
service/web2 exposed
|
||||
```
|
||||
|
||||
## Edit Ingress
|
||||
## Edit the existing Ingress {#edit-ingress}
|
||||
|
||||
1. Edit the existing `example-ingress.yaml` and add the following lines:
|
||||
1. Edit the existing `example-ingress.yaml` manifest, and add the
|
||||
following lines at the end:
|
||||
|
||||
```yaml
|
||||
- path: /v2
|
||||
@@ -264,47 +251,47 @@ The following file is an Ingress resource that sends traffic to your Service via
|
||||
|
||||
1. Apply the changes:
|
||||
|
||||
```shell
|
||||
kubectl apply -f example-ingress.yaml
|
||||
```
|
||||
```shell
|
||||
kubectl apply -f example-ingress.yaml
|
||||
```
|
||||
|
||||
Output:
|
||||
You should see:
|
||||
|
||||
```shell
|
||||
ingress.networking/example-ingress configured
|
||||
```
|
||||
```
|
||||
ingress.networking/example-ingress configured
|
||||
```
|
||||
|
||||
## Test Your Ingress
|
||||
## Test your Ingress
|
||||
|
||||
1. Access the 1st version of the Hello World app.
|
||||
|
||||
```shell
|
||||
curl hello-world.info
|
||||
```
|
||||
```shell
|
||||
curl hello-world.info
|
||||
```
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```shell
|
||||
Hello, world!
|
||||
Version: 1.0.0
|
||||
Hostname: web-55b8c6998d-8k564
|
||||
```
|
||||
```
|
||||
Hello, world!
|
||||
Version: 1.0.0
|
||||
Hostname: web-55b8c6998d-8k564
|
||||
```
|
||||
|
||||
1. Access the 2nd version of the Hello World app.
|
||||
|
||||
```shell
|
||||
curl hello-world.info/v2
|
||||
```
|
||||
```shell
|
||||
curl hello-world.info/v2
|
||||
```
|
||||
|
||||
Output:
|
||||
The output is similar to:
|
||||
|
||||
```shell
|
||||
Hello, world!
|
||||
Version: 2.0.0
|
||||
Hostname: web2-75cd47646f-t8cjk
|
||||
```
|
||||
```
|
||||
Hello, world!
|
||||
Version: 2.0.0
|
||||
Hostname: web2-75cd47646f-t8cjk
|
||||
```
|
||||
|
||||
{{< note >}}If you are running Minikube locally, you can visit hello-world.info and hello-world.info/v2 from your browser.{{< /note >}}
|
||||
{{< note >}}If you are running Minikube locally, you can visit hello-world.info and hello-world.info/v2 from your browser.{{< /note >}}
|
||||
|
||||
|
||||
|
||||
@@ -315,5 +302,3 @@ The following file is an Ingress resource that sends traffic to your Service via
|
||||
* Read more about [Ingress Controllers](/docs/concepts/services-networking/ingress-controllers/)
|
||||
* Read more about [Services](/docs/concepts/services-networking/service/)
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -88,11 +88,11 @@ kubectl patch pv <your-pv-name> -p "{\"spec\":{\"persistentVolumeReclaimPolicy\"
|
||||
* Learn more about [PersistentVolumes](/docs/concepts/storage/persistent-volumes/).
|
||||
* Learn more about [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims).
|
||||
|
||||
### Reference
|
||||
### References {#reference}
|
||||
|
||||
* [PersistentVolume](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#persistentvolume-v1-core)
|
||||
* [PersistentVolumeClaim](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#persistentvolumeclaim-v1-core)
|
||||
* See the `persistentVolumeReclaimPolicy` field of [PersistentVolumeSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#persistentvolumeclaim-v1-core).
|
||||
* {{< api-reference page="config-and-storage-resources/persistent-volume-v1" >}}
|
||||
* Pay attention to the `.spec.persistentVolumeReclaimPolicy` [field](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1/#PersistentVolumeSpec) of PersistentVolume.
|
||||
* {{< api-reference page="config-and-storage-resources/persistent-volume-claim-v1" >}}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -325,6 +325,10 @@ Here is an example:
|
||||
```shell
|
||||
ETCDCTL_API=3 etcdctl --endpoints 10.2.0.9:2379 snapshot restore snapshotdb
|
||||
```
|
||||
Another example for restoring using etcdutl options:
|
||||
```shell
|
||||
ETCDCTL_API=3 etcdctl --data-dir <data-dir-location> snapshot restore snapshotdb
|
||||
```
|
||||
|
||||
For more information and examples on restoring a cluster from a snapshot file, see
|
||||
[etcd disaster recovery documentation](https://etcd.io/docs/current/op-guide/recovery/#restoring-a-cluster).
|
||||
|
||||
@@ -67,7 +67,7 @@ If the `nslookup` command fails, check the following:
|
||||
### Check the local DNS configuration first
|
||||
|
||||
Take a look inside the resolv.conf file.
|
||||
(See [Inheriting DNS from the node](/docs/tasks/administer-cluster/dns-custom-nameservers/#inheriting-dns-from-the-node) and
|
||||
(See [Customizing DNS Service](/docs/tasks/administer-cluster/dns-custom-nameservers) and
|
||||
[Known issues](#known-issues) below for more information)
|
||||
|
||||
```shell
|
||||
|
||||
@@ -58,8 +58,7 @@ resources:
|
||||
Each `resources` array item is a separate config and contains a complete configuration. The
|
||||
`resources.resources` field is an array of Kubernetes resource names (`resource` or `resource.group`)
|
||||
that should be encrypted. The `providers` array is an ordered list of the possible encryption
|
||||
providers. Only one provider type may be specified per entry (`identity` or `aescbc` may be provided,
|
||||
but not both in the same item).
|
||||
providers. Only one provider type may be specified per entry (`identity` or `aescbc` may be provided, but not both in the same item).
|
||||
|
||||
The first provider in the list is used to encrypt resources going into storage. When reading
|
||||
resources from storage each provider that matches the stored data attempts to decrypt the data in
|
||||
@@ -78,9 +77,9 @@ read that resource will fail until it is deleted or a valid decryption key is pr
|
||||
Name | Encryption | Strength | Speed | Key Length | Other Considerations
|
||||
-----|------------|----------|-------|------------|---------------------
|
||||
`identity` | None | N/A | N/A | N/A | Resources written as-is without encryption. When set as the first provider, the resource will be decrypted as new values are written.
|
||||
`aescbc` | AES-CBC with PKCS#7 padding | Strongest | Fast | 32-byte | The recommended choice for encryption at rest but may be slightly slower than `secretbox`.
|
||||
`secretbox` | XSalsa20 and Poly1305 | Strong | Faster | 32-byte | A newer standard and may not be considered acceptable in environments that require high levels of review.
|
||||
`aesgcm` | AES-GCM with random nonce | Must be rotated every 200k writes | Fastest | 16, 24, or 32-byte | Is not recommended for use except when an automated key rotation scheme is implemented.
|
||||
`aescbc` | AES-CBC with PKCS#7 padding | Weak | Fast | 32-byte | Not recommended due to CBC's vulnerability to padding oracle attacks.
|
||||
`kms` | Uses envelope encryption scheme: Data is encrypted by data encryption keys (DEKs) using AES-CBC with PKCS#7 padding, DEKs are encrypted by key encryption keys (KEKs) according to configuration in Key Management Service (KMS) | Strongest | Fast | 32-bytes | The recommended choice for using a third party tool for key management. Simplifies key rotation, with a new DEK generated for each encryption, and KEK rotation controlled by the user. [Configure the KMS provider](/docs/tasks/administer-cluster/kms-provider/)
|
||||
|
||||
Each provider supports multiple keys - the keys are tried in order for decryption, and if the provider
|
||||
@@ -215,5 +214,3 @@ and restart all `kube-apiserver` processes. Then run:
|
||||
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
|
||||
```
|
||||
to force all secrets to be decrypted.
|
||||
|
||||
|
||||
|
||||
@@ -88,6 +88,7 @@ Pick a control plane node that you wish to upgrade first. It must have the `/etc
|
||||
yum install -y kubeadm-{{< skew currentVersion >}}.x-0 --disableexcludes=kubernetes
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
<br />
|
||||
|
||||
- Verify that the download works and has the expected version:
|
||||
|
||||
@@ -166,11 +167,10 @@ Also calling `kubeadm upgrade plan` and upgrading the CNI provider plugin is no
|
||||
|
||||
### Upgrade kubelet and kubectl
|
||||
|
||||
- Upgrade the kubelet and kubectl
|
||||
- Upgrade the kubelet and kubectl:
|
||||
|
||||
{{< tabs name="k8s_install_kubelet" >}}
|
||||
{{< tab name="Ubuntu, Debian or HypriotOS" >}}
|
||||
<pre>
|
||||
{{% tab name="Ubuntu, Debian or HypriotOS" %}}
|
||||
# replace x in {{< skew currentVersion >}}.x-00 with the latest patch version
|
||||
apt-mark unhold kubelet kubectl && \
|
||||
apt-get update && apt-get install -y kubelet={{< skew currentVersion >}}.x-00 kubectl={{< skew currentVersion >}}.x-00 && \
|
||||
@@ -179,15 +179,13 @@ Also calling `kubeadm upgrade plan` and upgrading the CNI provider plugin is no
|
||||
# since apt-get version 1.1 you can also use the following method
|
||||
apt-get update && \
|
||||
apt-get install -y --allow-change-held-packages kubelet={{< skew currentVersion >}}.x-00 kubectl={{< skew currentVersion >}}.x-00
|
||||
</pre>
|
||||
{{< /tab >}}
|
||||
{{< tab name="CentOS, RHEL or Fedora" >}}
|
||||
<pre>
|
||||
{{% /tab %}}
|
||||
{{% tab name="CentOS, RHEL or Fedora" %}}
|
||||
# replace x in {{< skew currentVersion >}}.x-0 with the latest patch version
|
||||
yum install -y kubelet-{{< skew currentVersion >}}.x-0 kubectl-{{< skew currentVersion >}}.x-0 --disableexcludes=kubernetes
|
||||
</pre>
|
||||
{{< /tab >}}
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
<br />
|
||||
|
||||
- Restart the kubelet:
|
||||
|
||||
@@ -268,6 +266,7 @@ without compromising the minimum required capacity for running your workloads.
|
||||
yum install -y kubelet-{{< skew currentVersion >}}.x-0 kubectl-{{< skew currentVersion >}}.x-0 --disableexcludes=kubernetes
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
<br />
|
||||
|
||||
- Restart the kubelet:
|
||||
|
||||
|
||||
@@ -27,8 +27,7 @@ If you are just looking for how to run a pod as a non-root user, see [SecurityCo
|
||||
* [Enable systemd with user session](https://rootlesscontaine.rs/getting-started/common/login/)
|
||||
* [Configure several sysctl values, depending on host Linux distribution](https://rootlesscontaine.rs/getting-started/common/sysctl/)
|
||||
* [Ensure that your unprivileged user is listed in `/etc/subuid` and `/etc/subgid`](https://rootlesscontaine.rs/getting-started/common/subuid/)
|
||||
|
||||
* `KubeletInUserNamespace` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
||||
* Enable the `KubeletInUserNamespace` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
@@ -86,9 +85,10 @@ Rootless Docker/Podman or LXC/LXD, you are all set, and you can go to the next s
|
||||
Otherwise you have to create a user namespace by yourself, by calling `unshare(2)` with `CLONE_NEWUSER`.
|
||||
|
||||
A user namespace can be also unshared by using command line tools such as:
|
||||
|
||||
- [`unshare(1)`](https://man7.org/linux/man-pages/man1/unshare.1.html)
|
||||
- [RootlessKit](https://github.com/rootless-containers/rootlesskit)
|
||||
- [become-root](https://github.com/giuseppe/become-root)
|
||||
- [`unshare(1)`](https://man7.org/linux/man-pages/man1/unshare.1.html)
|
||||
|
||||
After unsharing the user namespace, you will also have to unshare other namespaces such as mount namespace.
|
||||
|
||||
@@ -123,29 +123,37 @@ On your node, systemd must already be configured to allow delegation; for more d
|
||||
Containers documentation.
|
||||
|
||||
### Configuring network
|
||||
|
||||
{{% thirdparty-content %}}
|
||||
|
||||
The network namespace of the Node components has to have a non-loopback interface, which can be for example configured with
|
||||
slirp4netns, VPNKit, or lxc-user-nic.
|
||||
[slirp4netns](https://github.com/rootless-containers/slirp4netns),
|
||||
[VPNKit](https://github.com/moby/vpnkit), or
|
||||
[lxc-user-nic(1)](https://www.man7.org/linux/man-pages/man1/lxc-user-nic.1.html).
|
||||
|
||||
The network namespaces of the Pods can be configured with regular CNI plugins.
|
||||
For multi-node networking, Flannel (VXLAN, 8472/UDP) is known to work.
|
||||
|
||||
Ports such as the kubelet port (10250/TCP) and `NodePort` service ports have to be exposed from the Node network namespace to
|
||||
the host with an external port forwarder, such as RootlessKit, slirp4netns, or socat.
|
||||
the host with an external port forwarder, such as RootlessKit, slirp4netns, or
|
||||
[socat(1)](https://linux.die.net/man/1/socat).
|
||||
|
||||
You can use the port forwarder from K3s; see https://github.com/k3s-io/k3s/blob/v1.21.2+k3s1/pkg/rootlessports/controller.go
|
||||
You can use the port forwarder from K3s.
|
||||
See [Running K3s in Rootless Mode](https://rancher.com/docs/k3s/latest/en/advanced/#known-issues-with-rootless-mode)
|
||||
for more details.
|
||||
|
||||
### Configuring CRI
|
||||
|
||||
The kubelet relies on a container runtime. You should deploy a container runtime such as containerd or CRI-O and ensure that it is running within the user namespace before the kubelet starts.
|
||||
The kubelet relies on a container runtime. You should deploy a container runtime such as
|
||||
containerd or CRI-O and ensure that it is running within the user namespace before the kubelet starts.
|
||||
|
||||
{{< tabs name="cri" >}}
|
||||
{{% tab name="containerd" %}}
|
||||
|
||||
Running CRI plugin of containerd in a user namespace is supported since containerd 1.4.
|
||||
|
||||
Running containerd within a user namespace requires the following configuration:
|
||||
Running containerd within a user namespace requires the following configurations
|
||||
in `/etc/containerd/containerd-config.toml`.
|
||||
|
||||
```toml
|
||||
version = 2
|
||||
@@ -175,7 +183,7 @@ Running CRI-O in a user namespace is supported since CRI-O 1.22.
|
||||
|
||||
CRI-O requires an environment variable `_CRIO_ROOTLESS=1` to be set.
|
||||
|
||||
The following configuration is also recommended:
|
||||
The following configurations (in `/etc/crio/crio.conf`) are also recommended:
|
||||
|
||||
```toml
|
||||
[crio]
|
||||
@@ -197,8 +205,8 @@ The following configuration is also recommended:
|
||||
Running kubelet in a user namespace requires the following configuration:
|
||||
|
||||
```yaml
|
||||
kind: KubeletConfiguration
|
||||
apiVersion: kubelet.config.k8s.io/v1beta1
|
||||
kind: KubeletConfiguration
|
||||
featureGates:
|
||||
KubeletInUserNamespace: true
|
||||
# We use cgroupfs that is delegated by systemd, so we do not use "systemd" driver
|
||||
@@ -206,22 +214,23 @@ featureGates:
|
||||
cgroupDriver: "cgroupfs"
|
||||
```
|
||||
|
||||
When the `KubeletInUserNamespace` feature gate is enabled, kubelet ignores errors that may happen during setting the following sysctl values:
|
||||
When the `KubeletInUserNamespace` feature gate is enabled, the kubelet ignores errors
|
||||
that may happen during setting the following sysctl values on the node.
|
||||
|
||||
- `vm.overcommit_memory`
|
||||
- `vm.panic_on_oom`
|
||||
- `kernel.panic`
|
||||
- `kernel.panic_on_oops`
|
||||
- `kernel.keys.root_maxkeys`
|
||||
- `kernel.keys.root_maxbytes`.
|
||||
(these are sysctl values for the host, not for the containers).
|
||||
|
||||
Within a user namespace, the kubelet also ignores any error raised from trying to open `/dev/kmsg`.
|
||||
This feature gate also allows kube-proxy to ignore an error during setting `RLIMIT_NOFILE`.
|
||||
|
||||
The `KubeletInUserNamespace` feature gate was introduced in Kubernetes v1.22 with "alpha" status.
|
||||
|
||||
Running kubelet in a user namespace without using this feature gate is also possible by mounting a specially crafted proc filesystem,
|
||||
but not officially supported.
|
||||
Running kubelet in a user namespace without using this feature gate is also possible
|
||||
by mounting a specially crafted proc filesystem, but not officially supported.
|
||||
|
||||
### Configuring kube-proxy
|
||||
|
||||
@@ -251,9 +260,11 @@ For more on this, see the [Caveats and Future work](https://rootlesscontaine.rs/
|
||||
on the rootlesscontaine.rs website.
|
||||
|
||||
## {{% heading "seealso" %}}
|
||||
|
||||
- [rootlesscontaine.rs](https://rootlesscontaine.rs/)
|
||||
- [Rootless Containers 2020 (KubeCon NA 2020)](https://www.slideshare.net/AkihiroSuda/kubecon-na-2020-containerd-rootless-containers-2020)
|
||||
- [Running kind with Rootless Docker](https://kind.sigs.k8s.io/docs/user/rootless/)
|
||||
- [Usernetes](https://github.com/rootless-containers/usernetes)
|
||||
- [Running K3s with rootless mode](https://rancher.com/docs/k3s/latest/en/advanced/#running-k3s-with-rootless-mode-experimental)
|
||||
- [KEP-2033: Kubelet-in-UserNS (aka Rootless mode)](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2033-kubelet-in-userns-aka-rootless)
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ Having a local cache will help improve the latency in such scenarios.
|
||||
This is the path followed by DNS Queries after NodeLocal DNSCache is enabled:
|
||||
|
||||
|
||||
{{< figure src="/images/docs/nodelocaldns.svg" alt="NodeLocal DNSCache flow" title="Nodelocal DNSCache flow" caption="This image shows how NodeLocal DNSCache handles DNS queries." >}}
|
||||
{{< figure src="/images/docs/nodelocaldns.svg" alt="NodeLocal DNSCache flow" title="Nodelocal DNSCache flow" caption="This image shows how NodeLocal DNSCache handles DNS queries." class="diagram-medium" >}}
|
||||
|
||||
## Configuration
|
||||
{{< note >}} The local listen IP address for NodeLocal DNSCache can be any address that can be guaranteed to not collide with any existing IP in your cluster. It's recommended to use an address with a local scope, per example, from the link-local range 169.254.0.0/16 for IPv4 or from the Unique Local Address range in IPv6 fd00::/8.
|
||||
|
||||
@@ -258,7 +258,7 @@ In the example below the Pod did not get the credspec correctly:
|
||||
```PowerShell
|
||||
kubectl exec -it iis-auth-7776966999-n5nzr powershell.exe
|
||||
```
|
||||
nltest.exe /parentdomain` results in the following error:
|
||||
`nltest.exe /parentdomain` results in the following error:
|
||||
```
|
||||
Getting parent domain failed: Status = 1722 0x6ba RPC_S_SERVER_UNAVAILABLE
|
||||
```
|
||||
|
||||
@@ -29,13 +29,13 @@ Kompose is released via GitHub on a three-week cycle, you can see all current re
|
||||
|
||||
```sh
|
||||
# Linux
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.22.0/kompose-linux-amd64 -o kompose
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.24.0/kompose-linux-amd64 -o kompose
|
||||
|
||||
# macOS
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.22.0/kompose-darwin-amd64 -o kompose
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.24.0/kompose-darwin-amd64 -o kompose
|
||||
|
||||
# Windows
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.22.0/kompose-windows-amd64.exe -o kompose.exe
|
||||
curl -L https://github.com/kubernetes/kompose/releases/download/v1.24.0/kompose-windows-amd64.exe -o kompose.exe
|
||||
|
||||
chmod +x kompose
|
||||
sudo mv ./kompose /usr/local/bin/kompose
|
||||
|
||||
@@ -82,8 +82,8 @@ Now that the server is running, we will create the autoscaler using
|
||||
The following command will create a Horizontal Pod Autoscaler that maintains between 1 and 10 replicas of the Pods
|
||||
controlled by the php-apache deployment we created in the first step of these instructions.
|
||||
Roughly speaking, HPA will increase and decrease the number of replicas
|
||||
(via the deployment) to maintain an average CPU utilization across all Pods of 50%
|
||||
(since each pod requests 200 milli-cores by `kubectl run`), this means average CPU usage of 100 milli-cores).
|
||||
(via the deployment) to maintain an average CPU utilization across all Pods of 50%.
|
||||
Since each pod requests 200 milli-cores by `kubectl run`, this means an average CPU usage of 100 milli-cores.
|
||||
See [here](/docs/tasks/run-application/horizontal-pod-autoscale/#algorithm-details) for more details on the algorithm.
|
||||
|
||||
```shell
|
||||
|
||||
@@ -69,13 +69,13 @@ By default, the dashboard is only accessible from within the internal Kubernetes
|
||||
The `dashboard` command creates a temporary proxy to make the dashboard accessible from outside the Kubernetes virtual network.
|
||||
|
||||
To stop the proxy, run `Ctrl+C` to exit the process.
|
||||
After the command exits, the dashboard remains running in Kubernetes cluster.
|
||||
After the command exits, the dashboard remains running in the Kubernetes cluster.
|
||||
You can run the `dashboard` command again to create another proxy to access the dashboard.
|
||||
{{< /note >}}
|
||||
|
||||
## Open Dashboard with URL
|
||||
|
||||
If you don't want to open a web browser, run the dashboard command with the url flag to emit a URL:
|
||||
If you don't want to open a web browser, run the dashboard command with the `--url` flag to emit a URL:
|
||||
|
||||
```shell
|
||||
minikube dashboard --url
|
||||
@@ -185,7 +185,7 @@ Kubernetes [*Service*](/docs/concepts/services-networking/service/).
|
||||
|
||||
4. Katacoda environment only: Click the plus sign, and then click **Select port to view on Host 1**.
|
||||
|
||||
5. Katacoda environment only: Note the 5 digit port number displayed opposite to `8080` in services output. This port number is randomly generated and it can be different for you. Type your number in the port number text box, then click Display Port. Using the example from earlier, you would type `30369`.
|
||||
5. Katacoda environment only: Note the 5-digit port number displayed opposite to `8080` in services output. This port number is randomly generated and it can be different for you. Type your number in the port number text box, then click Display Port. Using the example from earlier, you would type `30369`.
|
||||
|
||||
This opens up a browser window that serves your app and shows the app's response.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user