diff --git a/Makefile b/Makefile index 4b3ca99864..dedd387eb6 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ CONTAINER_ENGINE ?= docker IMAGE_REGISTRY ?= gcr.io/k8s-staging-sig-docs IMAGE_VERSION=$(shell scripts/hash-files.sh Dockerfile Makefile | cut -c 1-12) CONTAINER_IMAGE = $(IMAGE_REGISTRY)/k8s-website-hugo:v$(HUGO_VERSION)-$(IMAGE_VERSION) -CONTAINER_RUN = $(CONTAINER_ENGINE) run --rm --interactive --tty --volume $(CURDIR):/src +CONTAINER_RUN = "$(CONTAINER_ENGINE)" run --rm --interactive --tty --volume "$(CURDIR):/src" CCRED=\033[0;31m CCEND=\033[0m @@ -95,7 +95,7 @@ docker-internal-linkcheck: container-internal-linkcheck: link-checker-image-pull $(CONTAINER_RUN) $(CONTAINER_IMAGE) hugo --config config.toml,linkcheck-config.toml --buildFuture --environment test - $(CONTAINER_ENGINE) run --mount type=bind,source=$(CURDIR),target=/test --rm wjdp/htmltest htmltest + $(CONTAINER_ENGINE) run --mount "type=bind,source=$(CURDIR),target=/test" --rm wjdp/htmltest htmltest clean-api-reference: ## Clean all directories in API reference directory, preserve _index.md rm -rf content/en/docs/reference/kubernetes-api/*/ diff --git a/README-ko.md b/README-ko.md index c3e1068b2e..fd17e2b655 100644 --- a/README-ko.md +++ b/README-ko.md @@ -4,6 +4,9 @@ 이 저장소에는 [쿠버네티스 웹사이트 및 문서](https://kubernetes.io/)를 빌드하는 데 필요한 자산이 포함되어 있습니다. 기여해주셔서 감사합니다! +- [문서에 기여하기](#contributing-to-the-docs) +- [`README.md`에 대한 쿠버네티스 문서 현지화](#localization-readmemds) + # 저장소 사용하기 Hugo(확장 버전)를 사용하여 웹사이트를 로컬에서 실행하거나, 컨테이너 런타임에서 실행할 수 있습니다. 라이브 웹사이트와의 배포 일관성을 제공하므로, 컨테이너 런타임을 사용하는 것을 적극 권장합니다. @@ -40,6 +43,8 @@ make container-image make container-serve ``` +에러가 발생한다면, Hugo 컨테이너를 위한 컴퓨팅 리소스가 충분하지 않기 때문일 수 있습니다. 이를 해결하려면, 머신에서 도커에 허용할 CPU 및 메모리 사용량을 늘립니다([MacOSX](https://docs.docker.com/docker-for-mac/#resources) / [Windows](https://docs.docker.com/docker-for-windows/#resources)). + 웹사이트를 보려면 브라우저를 http://localhost:1313 으로 엽니다. 소스 파일을 변경하면 Hugo가 웹사이트를 업데이트하고 브라우저를 강제로 새로 고칩니다. ## Hugo를 사용하여 로컬에서 웹사이트 실행하기 @@ -56,7 +61,45 @@ make serve 그러면 포트 1313에서 로컬 Hugo 서버가 시작됩니다. 웹사이트를 보려면 http://localhost:1313 으로 브라우저를 엽니다. 소스 파일을 변경하면, Hugo가 웹사이트를 업데이트하고 브라우저를 강제로 새로 고칩니다. +## API 레퍼런스 페이지 빌드하기 + +`content/en/docs/reference/kubernetes-api`에 있는 API 레퍼런스 페이지는 를 사용하여 Swagger 명세로부터 빌드되었습니다. + +새로운 쿠버네티스 릴리스를 위해 레퍼런스 페이지를 업데이트하려면 다음 단계를 수행합니다. + +1. `api-ref-generator` 서브모듈을 받아옵니다. + + ```bash + git submodule update --init --recursive --depth 1 + ``` + +2. Swagger 명세를 업데이트합니다. + + ```bash + curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json + ``` + +3. `api-ref-assets/config/`에서, 새 릴리스의 변경 사항이 반영되도록 `toc.yaml` 및 `fields.yaml` 파일을 업데이트합니다. + +4. 다음으로, 페이지를 빌드합니다. + + ```bash + make api-reference + ``` + + 로컬에서 결과를 테스트하기 위해 컨테이너 이미지를 이용하여 사이트를 빌드 및 실행합니다. + + ```bash + make container-image + make container-serve + ``` + + 웹 브라우저에서, 로 이동하여 API 레퍼런스를 확인합니다. + +5. 모든 API 변경사항이 `toc.yaml` 및 `fields.yaml` 구성 파일에 반영되었다면, 새로 생성된 API 레퍼런스 페이지에 대한 PR을 엽니다. + ## 문제 해결 + ### error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version Hugo는 기술적인 이유로 2개의 바이너리 세트로 제공됩니다. 현재 웹사이트는 **Hugo 확장** 버전 기반에서만 실행됩니다. [릴리스 페이지](https://github.com/gohugoio/hugo/releases)에서 이름에 `extended` 가 포함된 아카이브를 찾습니다. 확인하려면, `hugo version` 을 실행하고 `extended` 라는 단어를 찾습니다. @@ -97,17 +140,17 @@ sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist 이 내용은 Catalina와 Mojave macOS에서 작동합니다. - # SIG Docs에 참여하기 [커뮤니티 페이지](https://github.com/kubernetes/community/tree/master/sig-docs#meetings)에서 SIG Docs 쿠버네티스 커뮤니티 및 회의에 대한 자세한 내용을 확인합니다. 이 프로젝트의 메인테이너에게 연락을 할 수도 있습니다. -- [슬랙](https://kubernetes.slack.com/messages/sig-docs) [슬랙에 초대 받기](https://slack.k8s.io/) +- [슬랙](https://kubernetes.slack.com/messages/sig-docs) + - [슬랙에 초대 받기](https://slack.k8s.io/) - [메일링 리스트](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) -# 문서에 기여하기 +# 문서에 기여하기 {#contributing-to-the-docs} 이 저장소에 대한 복제본을 여러분의 GitHub 계정에 생성하기 위해 화면 오른쪽 위 영역에 있는 **Fork** 버튼을 클릭하면 됩니다. 이 복제본은 *fork* 라고 부릅니다. 여러분의 fork에서 원하는 임의의 변경 사항을 만들고, 해당 변경 사항을 보낼 준비가 되었다면, 여러분의 fork로 이동하여 새로운 풀 리퀘스트를 만들어 우리에게 알려주시기 바랍니다. @@ -124,7 +167,15 @@ sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist * [문서화 스타일 가이드](http://kubernetes.io/docs/contribute/style/style-guide/) * [쿠버네티스 문서 현지화](https://kubernetes.io/docs/contribute/localization/) -# `README.md`에 대한 쿠버네티스 문서 현지화(localization) +### 신규 기여자 대사(ambassadors) + +기여 과정에서 도움이 필요하다면, [신규 기여자 대사](https://kubernetes.io/docs/contribute/advanced/#serve-as-a-new-contributor-ambassador)에게 연락하는 것이 좋습니다. 이들은 신규 기여자를 멘토링하고 첫 PR 과정에서 도움을 주는 역할도 담당하는 SIG Docs 승인자입니다. 신규 기여자 대사에게 문의할 가장 좋은 곳은 [쿠버네티스 슬랙](https://slack.k8s.io/)입니다. 현재 SIG Docs 신규 기여자 대사는 다음과 같습니다. + +| Name | Slack | GitHub | +| -------------------------- | -------------------------- | -------------------------- | +| Arsh Sharma | @arsh | @RinkiyaKeDad | + +# `README.md`에 대한 쿠버네티스 문서 현지화(localization) {#localization-readmemds} ## 한국어 @@ -135,6 +186,7 @@ sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist * 손석호 ([GitHub - @seokho-son](https://github.com/seokho-son)) * [슬랙 채널](https://kubernetes.slack.com/messages/kubernetes-docs-ko) + # 행동 강령 쿠버네티스 커뮤니티 참여는 [CNCF 행동 강령](https://github.com/cncf/foundation/blob/master/code-of-conduct-languages/ko.md)을 따릅니다. diff --git a/README-zh.md b/README-zh.md index e3ac58fb93..5f0f83c80f 100644 --- a/README-zh.md +++ b/README-zh.md @@ -80,7 +80,7 @@ To build the site in a container, run the following to build the container image 要在容器中构建网站，请通过以下命令来构建容器镜像并运行： ```bash -make container-image +# 你可以将 $CONTAINER_ENGINE 设置为任何 Docker 类容器工具的名称 make container-serve ``` diff --git a/content/de/docs/concepts/overview/what-is-kubernetes.md b/content/de/docs/concepts/overview/what-is-kubernetes.md index f84a0a2cde..e7ff2c2537 100644 --- a/content/de/docs/concepts/overview/what-is-kubernetes.md +++ b/content/de/docs/concepts/overview/what-is-kubernetes.md @@ -61,7 +61,7 @@ Dieses [Design](https://git.k8s.io/community/contributors/design-proposals/archi Kubernetes ist kein traditionelles, allumfassendes PaaS (Plattform als ein Service) System. Da Kubernetes nicht auf Hardware-, sondern auf Containerebene arbeitet, bietet es einige allgemein anwendbare Funktionen, die PaaS-Angeboten gemeinsam sind, wie Bereitstellung, Skalierung, Lastausgleich, Protokollierung und Überwachung. -Kubernetes ist jedoch nicht monolithisch, und diese Standardlösungen sind optional und modular etweiterbar. +Kubernetes ist jedoch nicht monolithisch, und diese Standardlösungen sind optional und modular erweiterbar. Kubernetes liefert die Bausteine für den Aufbau von Entwicklerplattformen, bewahrt aber die Wahlmöglichkeiten und Flexibilität der Benutzer, wo es wichtig ist. @@ -79,7 +79,7 @@ Kubernetes: Cluster-Speichersysteme (z.B. Ceph) als eingebaute Dienste. Solche Komponenten können auf Kubernetes laufen und/oder von Anwendungen, die auf Kubernetes laufen, über portable Mechanismen wie den Open Service Broker angesprochen werden. -* Bietet keine Konfigurationssprache bzw. kein Konfigurationssystem (z.B.[jsonnet](https://github.com/google/jsonnet)). +* Bietet keine Konfigurationssprache bzw. kein Konfigurationssystem (z.B. [jsonnet](https://github.com/google/jsonnet)). Es bietet eine deklarative API, die von beliebigen Formen deklarativer Spezifikationen angesprochen werden kann. * Bietet keine umfassenden Systeme zur Maschinenkonfiguration, Wartung, Verwaltung oder Selbstheilung. @@ -135,17 +135,17 @@ Zusammenfassung der Container-Vorteile: * **Dev und Ops Trennung der Bedenken**: Erstellen Sie Anwendungscontainer-Images nicht zum Deployment-, sondern zum Build-Releasezeitpunkt und entkoppeln Sie so Anwendungen von der Infrastruktur. -* **Überwachbarkeit** +* **Überwachbarkeit**: Nicht nur Informationen und Metriken auf Betriebssystemebene werden angezeigt, sondern auch der Zustand der Anwendung und andere Signale. * **Umgebungskontinuität in Entwicklung, Test und Produktion**: Läuft auf einem Laptop genauso wie in der Cloud. -* **Cloud- und OS-Distribution portabilität**: +* **Cloud- und OS-Distribution-Portabilität**: Läuft auf Ubuntu, RHEL, CoreOS, On-Prem, Google Kubernetes Engine und überall sonst. * **Anwendungsorientiertes Management**: Erhöht den Abstraktionsgrad vom Ausführen eines Betriebssystems auf virtueller Hardware bis zum Ausführen einer Anwendung auf einem Betriebssystem unter Verwendung logischer Ressourcen. -* **Locker gekoppelte, verteilte, elastische, freie [micro-services](https://martinfowler.com/articles/microservices.html)**: +* **Locker gekoppelte, verteilte, elastische, freie [Microservices](https://martinfowler.com/articles/microservices.html)**: Anwendungen werden in kleinere, unabhängige Teile zerlegt und können dynamisch bereitgestellt und verwaltet werden -- nicht ein monolithischer Stack, der auf einer großen Single-Purpose-Maschine läuft. * **Ressourcenisolierung**: diff --git a/content/en/_index.html b/content/en/_index.html index 7557fe8f99..09b4f8d06a 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -43,12 +43,12 @@ Kubernetes is open source giving you the freedom to take advantage of on-premise

- Attend KubeCon Europe on May 17-20, 2022 -
-
-
-
Attend KubeCon North America on October 24-28, 2022 +
+
+
+
+ Attend KubeCon Europe on April 17-21, 2023
diff --git a/content/en/blog/_posts/2022-01-10-meet-our-contributors-APAC-India-region-01.md b/content/en/blog/_posts/2022-01-10-meet-our-contributors-APAC-India-region-01.md index 4c969ff50c..a1ac132c48 100644 --- a/content/en/blog/_posts/2022-01-10-meet-our-contributors-APAC-India-region-01.md +++ b/content/en/blog/_posts/2022-01-10-meet-our-contributors-APAC-India-region-01.md @@ -1,9 +1,9 @@ --- layout: blog title: "Meet Our Contributors - APAC (India region)" -date: 2022-01-10T12:00:00+0000 +date: 2022-01-10 slug: meet-our-contributors-india-ep-01 -canonicalUrl: https://kubernetes.dev/blog/2022/01/10/meet-our-contributors-india-ep-01/ +canonicalUrl: https://www.kubernetes.dev/blog/2022/01/10/meet-our-contributors-india-ep-01/ --- **Authors & Interviewers:** [Anubhav Vardhan](https://github.com/anubha-v-ardhan), [Atharva Shinde](https://github.com/Atharva-Shinde), [Avinesh Tripathi](https://github.com/AvineshTripathi), [Debabrata Panigrahi](https://github.com/Debanitrkl), [Kunal Verma](https://github.com/verma-kunal), [Pranshu Srivastava](https://github.com/PranshuSrivastava), [Pritish Samal](https://github.com/CIPHERTron), [Purneswar Prasad](https://github.com/PurneswarPrasad), [Vedant Kakde](https://github.com/vedant-kakde) @@ -19,7 +19,7 @@ Welcome to the first episode of the APAC edition of the "Meet Our Contributors" In this post, we'll introduce you to five amazing folks from the India region who have been actively contributing to the upstream Kubernetes projects in a variety of ways, as well as being the leaders or maintainers of numerous community initiatives. -💫 *Let's get started, so without further ado…* +💫 *Let's get started, so without further ado…* ## [Arsh Sharma](https://github.com/RinkiyaKeDad) @@ -39,7 +39,7 @@ To the newcomers, Arsh helps plan their early contributions sustainably. Kunal Kushwaha is a core member of the Kubernetes marketing council. He is also a CNCF ambassador and one of the founders of the [CNCF Students Program](https://community.cncf.io/cloud-native-students/).. He also served as a Communications role shadow during the 1.22 release cycle. -At the end of his first year, Kunal began contributing to the [fabric8io kubernetes-client](https://github.com/fabric8io/kubernetes-client) project. He was then selected to work on the same project as part of Google Summer of Code. Kunal mentored people on the same project, first through Google Summer of Code then through Google Code-in. +At the end of his first year, Kunal began contributing to the [fabric8io kubernetes-client](https://github.com/fabric8io/kubernetes-client) project. He was then selected to work on the same project as part of Google Summer of Code. Kunal mentored people on the same project, first through Google Summer of Code then through Google Code-in. As an open-source enthusiast, he believes that diverse participation in the community is beneficial since it introduces new perspectives and opinions and respect for one's peers. He has worked on various open-source projects, and his participation in communities has considerably assisted his development as a developer. @@ -103,4 +103,3 @@ If you have any recommendations/suggestions for who we should interview next, pl We'll see you all in the next one. Everyone, till then, have a happy contributing! 👋 - diff --git a/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md b/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-02.md similarity index 98% rename from content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md rename to content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-02.md index 5a8a4a2989..e8d9cfdf89 100644 --- a/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md +++ b/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-02.md @@ -1,7 +1,7 @@ --- layout: blog title: "Meet Our Contributors - APAC (Aus-NZ region)" -date: 2022-03-16T12:00:00+0000 +date: 2022-03-16 slug: meet-our-contributors-au-nz-ep-02 canonicalUrl: https://www.kubernetes.dev/blog/2022/03/14/meet-our-contributors-au-nz-ep-02/ --- @@ -60,19 +60,13 @@ Nick Young works at VMware as a technical lead for Contour, a CNCF ingress contr His contribution path was notable in that he began working on major areas of the Kubernetes project early on, skewing his trajectory. -He asserts the best thing a new contributor can do is to "start contributing". Naturally, if it is relevant to their employment, that is excellent; however, investing non-work time in contributing can pay off in the long run in terms of work. He believes that new contributors, particularly those who are currently Kubernetes users, should be encouraged to participate in higher-level project discussions. +He asserts the best thing a new contributor can do is to "start contributing". Naturally, if it is relevant to their employment, that is excellent; however, investing non-work time in contributing can pay off in the long run in terms of work. He believes that new contributors, particularly those who are currently Kubernetes users, should be encouraged to participate in higher-level project discussions. > _Just being active and contributing will get you a long way. Once you've been active for a while, you'll find that you're able to answer questions, which will mean you're asked questions, and before you know it you are an expert._ - - - --- If you have any recommendations/suggestions for who we should interview next, please let us know in #sig-contribex. Your suggestions would be much appreciated. We're thrilled to have additional folks assisting us in reaching out to even more wonderful individuals of the community. We'll see you all in the next one. Everyone, till then, have a happy contributing! 👋 - - - diff --git a/content/en/docs/concepts/architecture/control-plane-node-communication.md b/content/en/docs/concepts/architecture/control-plane-node-communication.md index df384800e9..785040cda3 100644 --- a/content/en/docs/concepts/architecture/control-plane-node-communication.md +++ b/content/en/docs/concepts/architecture/control-plane-node-communication.md @@ -33,7 +33,7 @@ are allowed. Nodes should be provisioned with the public root certificate for the cluster such that they can connect securely to the API server along with valid client credentials. A good approach is that the client credentials provided to the kubelet are in the form of a client certificate. See -[kubelet TLS bootstrapping](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/) +[kubelet TLS bootstrapping](/docs/reference/access-authn-authz/kubelet-tls-bootstrapping/) for automated provisioning of kubelet client certificates. Pods that wish to connect to the API server can do so securely by leveraging a service account so diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index 2321fc6474..f57179df8e 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -479,29 +479,24 @@ these pods will be stuck in terminating status on the shutdown node forever. To mitigate the above situation, a user can manually add the taint `node kubernetes.io/out-of-service` with either `NoExecute` or `NoSchedule` effect to a Node marking it out-of-service. -If the `NodeOutOfServiceVolumeDetach` [feature gate](/docs/reference/ -command-line-tools-reference/feature-gates/) is enabled on -`kube-controller-manager`, and a Node is marked out-of-service with this taint, the -pods on the node will be forcefully deleted if there are no matching tolerations on -it and volume detach operations for the pods terminating on the node will happen -immediately. This allows the Pods on the out-of-service node to recover quickly on a -different node. +If the `NodeOutOfServiceVolumeDetach`[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +is enabled on `kube-controller-manager`, and a Node is marked out-of-service with this taint, the +pods on the node will be forcefully deleted if there are no matching tolerations on it and volume +detach operations for the pods terminating on the node will happen immediately. This allows the +Pods on the out-of-service node to recover quickly on a different node. During a non-graceful shutdown, Pods are terminated in the two phases: 1. Force delete the Pods that do not have matching `out-of-service` tolerations. 2. Immediately perform detach volume operation for such pods. - {{< note >}} - Before adding the taint `node.kubernetes.io/out-of-service` , it should be verified -that the node is already in shutdown or power off state (not in the middle of -restarting). + that the node is already in shutdown or power off state (not in the middle of + restarting). - The user is required to manually remove the out-of-service taint after the pods are -moved to a new node and the user has checked that the shutdown node has been -recovered since the user was the one who originally added the taint. - - + moved to a new node and the user has checked that the shutdown node has been + recovered since the user was the one who originally added the taint. {{< /note >}} ### Pod Priority based graceful node shutdown {#pod-priority-graceful-node-shutdown} diff --git a/content/en/docs/concepts/cluster-administration/_index.md b/content/en/docs/concepts/cluster-administration/_index.md index ace5297b33..d5d6a273e2 100644 --- a/content/en/docs/concepts/cluster-administration/_index.md +++ b/content/en/docs/concepts/cluster-administration/_index.md @@ -11,31 +11,37 @@ no_list: true --- + The cluster administration overview is for anyone creating or administering a Kubernetes cluster. It assumes some familiarity with core Kubernetes [concepts](/docs/concepts/). - + ## Planning a cluster -See the guides in [Setup](/docs/setup/) for examples of how to plan, set up, and configure Kubernetes clusters. The solutions listed in this article are called *distros*. +See the guides in [Setup](/docs/setup/) for examples of how to plan, set up, and configure +Kubernetes clusters. The solutions listed in this article are called *distros*. - {{< note >}} - Not all distros are actively maintained. Choose distros which have been tested with a recent version of Kubernetes. - {{< /note >}} +{{< note >}} +Not all distros are actively maintained. Choose distros which have been tested with a recent +version of Kubernetes. +{{< /note >}} Before choosing a guide, here are some considerations: - - Do you want to try out Kubernetes on your computer, or do you want to build a high-availability, multi-node cluster? Choose distros best suited for your needs. - - Will you be using **a hosted Kubernetes cluster**, such as [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), or **hosting your own cluster**? - - Will your cluster be **on-premises**, or **in the cloud (IaaS)**? Kubernetes does not directly support hybrid clusters. Instead, you can set up multiple clusters. - - **If you are configuring Kubernetes on-premises**, consider which [networking model](/docs/concepts/cluster-administration/networking/) fits best. - - Will you be running Kubernetes on **"bare metal" hardware** or on **virtual machines (VMs)**? - - Do you **want to run a cluster**, or do you expect to do **active development of Kubernetes project code**? If the - latter, choose an actively-developed distro. Some distros only use binary releases, but - offer a greater variety of choices. - - Familiarize yourself with the [components](/docs/concepts/overview/components/) needed to run a cluster. - +- Do you want to try out Kubernetes on your computer, or do you want to build a high-availability, + multi-node cluster? Choose distros best suited for your needs. +- Will you be using **a hosted Kubernetes cluster**, such as + [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), or **hosting your own cluster**? +- Will your cluster be **on-premises**, or **in the cloud (IaaS)**? Kubernetes does not directly + support hybrid clusters. Instead, you can set up multiple clusters. +- **If you are configuring Kubernetes on-premises**, consider which + [networking model](/docs/concepts/cluster-administration/networking/) fits best. +- Will you be running Kubernetes on **"bare metal" hardware** or on **virtual machines (VMs)**? +- Do you **want to run a cluster**, or do you expect to do **active development of Kubernetes project code**? + If the latter, choose an actively-developed distro. Some distros only use binary releases, but + offer a greater variety of choices. +- Familiarize yourself with the [components](/docs/concepts/overview/components/) needed to run a cluster. ## Managing a cluster @@ -45,29 +51,43 @@ Before choosing a guide, here are some considerations: ## Securing a cluster -* [Generate Certificates](/docs/tasks/administer-cluster/certificates/) describes the steps to generate certificates using different tool chains. +* [Generate Certificates](/docs/tasks/administer-cluster/certificates/) describes the steps to + generate certificates using different tool chains. -* [Kubernetes Container Environment](/docs/concepts/containers/container-environment/) describes the environment for Kubelet managed containers on a Kubernetes node. +* [Kubernetes Container Environment](/docs/concepts/containers/container-environment/) describes + the environment for Kubelet managed containers on a Kubernetes node. -* [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access) describes how Kubernetes implements access control for its own API. +* [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access) describes + how Kubernetes implements access control for its own API. -* [Authenticating](/docs/reference/access-authn-authz/authentication/) explains authentication in Kubernetes, including the various authentication options. +* [Authenticating](/docs/reference/access-authn-authz/authentication/) explains authentication in + Kubernetes, including the various authentication options. -* [Authorization](/docs/reference/access-authn-authz/authorization/) is separate from authentication, and controls how HTTP calls are handled. +* [Authorization](/docs/reference/access-authn-authz/authorization/) is separate from + authentication, and controls how HTTP calls are handled. -* [Using Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/) explains plug-ins which intercepts requests to the Kubernetes API server after authentication and authorization. +* [Using Admission Controllers](/docs/reference/access-authn-authz/admission-controllers/) + explains plug-ins which intercepts requests to the Kubernetes API server after authentication + and authorization. -* [Using Sysctls in a Kubernetes Cluster](/docs/tasks/administer-cluster/sysctl-cluster/) describes to an administrator how to use the `sysctl` command-line tool to set kernel parameters . +* [Using Sysctls in a Kubernetes Cluster](/docs/tasks/administer-cluster/sysctl-cluster/) + describes to an administrator how to use the `sysctl` command-line tool to set kernel parameters +. -* [Auditing](/docs/tasks/debug/debug-cluster/audit/) describes how to interact with Kubernetes' audit logs. +* [Auditing](/docs/tasks/debug/debug-cluster/audit/) describes how to interact with Kubernetes' + audit logs. ### Securing the kubelet - * [Control Plane-Node communication](/docs/concepts/architecture/control-plane-node-communication/) - * [TLS bootstrapping](/docs/reference/access-authn-authz/kubelet-tls-bootstrapping/) - * [Kubelet authentication/authorization](/docs/reference/acess-authn-authz/kubelet-authn-authz/) + +* [Control Plane-Node communication](/docs/concepts/architecture/control-plane-node-communication/) +* [TLS bootstrapping](/docs/reference/access-authn-authz/kubelet-tls-bootstrapping/) +* [Kubelet authentication/authorization](/docs/reference/access-authn-authz/kubelet-authn-authz/) ## Optional Cluster Services -* [DNS Integration](/docs/concepts/services-networking/dns-pod-service/) describes how to resolve a DNS name directly to a Kubernetes service. +* [DNS Integration](/docs/concepts/services-networking/dns-pod-service/) describes how to resolve + a DNS name directly to a Kubernetes service. + +* [Logging and Monitoring Cluster Activity](/docs/concepts/cluster-administration/logging/) + explains how logging in Kubernetes works and how to implement it. -* [Logging and Monitoring Cluster Activity](/docs/concepts/cluster-administration/logging/) explains how logging in Kubernetes works and how to implement it. diff --git a/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md b/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md index ee83692419..8e4214991c 100644 --- a/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md +++ b/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md @@ -8,21 +8,29 @@ card: --- -This page explains how Kubernetes objects are represented in the Kubernetes API, and how you can express them in `.yaml` format. - +This page explains how Kubernetes objects are represented in the Kubernetes API, and how you can +express them in `.yaml` format. ## Understanding Kubernetes objects {#kubernetes-objects} -*Kubernetes objects* are persistent entities in the Kubernetes system. Kubernetes uses these entities to represent the state of your cluster. Specifically, they can describe: +*Kubernetes objects* are persistent entities in the Kubernetes system. Kubernetes uses these +entities to represent the state of your cluster. Specifically, they can describe: * What containerized applications are running (and on which nodes) * The resources available to those applications * The policies around how those applications behave, such as restart policies, upgrades, and fault-tolerance -A Kubernetes object is a "record of intent"--once you create the object, the Kubernetes system will constantly work to ensure that object exists. By creating an object, you're effectively telling the Kubernetes system what you want your cluster's workload to look like; this is your cluster's *desired state*. +A Kubernetes object is a "record of intent"--once you create the object, the Kubernetes system +will constantly work to ensure that object exists. By creating an object, you're effectively +telling the Kubernetes system what you want your cluster's workload to look like; this is your +cluster's *desired state*. -To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the [Kubernetes API](/docs/concepts/overview/kubernetes-api/). When you use the `kubectl` command-line interface, for example, the CLI makes the necessary Kubernetes API calls for you. You can also use the Kubernetes API directly in your own programs using one of the [Client Libraries](/docs/reference/using-api/client-libraries/). +To work with Kubernetes objects--whether to create, modify, or delete them--you'll need to use the +[Kubernetes API](/docs/concepts/overview/kubernetes-api/). When you use the `kubectl` command-line +interface, for example, the CLI makes the necessary Kubernetes API calls for you. You can also use +the Kubernetes API directly in your own programs using one of the +[Client Libraries](/docs/reference/using-api/client-libraries/). ### Object Spec and Status @@ -48,11 +56,17 @@ the status to match your spec. If any of those instances should fail between spec and status by making a correction--in this case, starting a replacement instance. -For more information on the object spec, status, and metadata, see the [Kubernetes API Conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md). +For more information on the object spec, status, and metadata, see the +[Kubernetes API Conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md). ### Describing a Kubernetes object -When you create an object in Kubernetes, you must provide the object spec that describes its desired state, as well as some basic information about the object (such as a name). When you use the Kubernetes API to create the object (either directly or via `kubectl`), that API request must include that information as JSON in the request body. **Most often, you provide the information to `kubectl` in a .yaml file.** `kubectl` converts the information to JSON when making the API request. +When you create an object in Kubernetes, you must provide the object spec that describes its +desired state, as well as some basic information about the object (such as a name). When you use +the Kubernetes API to create the object (either directly or via `kubectl`), that API request must +include that information as JSON in the request body. **Most often, you provide the information to +`kubectl` in a .yaml file.** `kubectl` converts the information to JSON when making the API +request. Here's an example `.yaml` file that shows the required fields and object spec for a Kubernetes Deployment: @@ -81,7 +95,9 @@ In the `.yaml` file for the Kubernetes object you want to create, you'll need to * `metadata` - Data that helps uniquely identify the object, including a `name` string, `UID`, and optional `namespace` * `spec` - What state you desire for the object -The precise format of the object `spec` is different for every Kubernetes object, and contains nested fields specific to that object. The [Kubernetes API Reference](/docs/reference/kubernetes-api/) can help you find the spec format for all of the objects you can create using Kubernetes. +The precise format of the object `spec` is different for every Kubernetes object, and contains +nested fields specific to that object. The [Kubernetes API Reference](/docs/reference/kubernetes-api/) +can help you find the spec format for all of the objects you can create using Kubernetes. For example, see the [`spec` field](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec) for the Pod API reference. @@ -103,5 +119,3 @@ detail the structure of that `.status` field, and its content for each different * Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes. * [Using the Kubernetes API](/docs/reference/using-api/) explains some more API concepts. - - diff --git a/content/en/docs/concepts/overview/working-with-objects/object-management.md b/content/en/docs/concepts/overview/working-with-objects/object-management.md index b85c622823..10b6dacf85 100644 --- a/content/en/docs/concepts/overview/working-with-objects/object-management.md +++ b/content/en/docs/concepts/overview/working-with-objects/object-management.md @@ -169,9 +169,9 @@ Disadvantages compared to imperative object configuration: ## {{% heading "whatsnext" %}} - [Managing Kubernetes Objects Using Imperative Commands](/docs/tasks/manage-kubernetes-objects/imperative-command/) -- [Managing Kubernetes Objects Using Object Configuration (Imperative)](/docs/tasks/manage-kubernetes-objects/imperative-config/) -- [Managing Kubernetes Objects Using Object Configuration (Declarative)](/docs/tasks/manage-kubernetes-objects/declarative-config/) -- [Managing Kubernetes Objects Using Kustomize (Declarative)](/docs/tasks/manage-kubernetes-objects/kustomization/) +- [Imperative Management of Kubernetes Objects Using Configuration Files](/docs/tasks/manage-kubernetes-objects/imperative-config/) +- [Declarative Management of Kubernetes Objects Using Configuration Files](/docs/tasks/manage-kubernetes-objects/declarative-config/) +- [Declarative Management of Kubernetes Objects Using Kustomize](/docs/tasks/manage-kubernetes-objects/kustomization/) - [Kubectl Command Reference](/docs/reference/generated/kubectl/kubectl-commands/) - [Kubectl Book](https://kubectl.docs.kubernetes.io) - [Kubernetes API Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) diff --git a/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md b/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md index 6142c050c6..78835c3a7d 100644 --- a/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md +++ b/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md @@ -66,8 +66,8 @@ the signal. The value for `memory.available` is derived from the cgroupfs instead of tools like `free -m`. This is important because `free -m` does not work in a -container, and if users use the [node -allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) feature, out of resource decisions +container, and if users use the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) +feature, out of resource decisions are made local to the end user Pod part of the cgroup hierarchy as well as the root node. This [script](/examples/admin/resource/memory-available.sh) reproduces the same set of steps that the kubelet performs to calculate @@ -87,7 +87,8 @@ does not support other configurations. {{}} Some kubelet garbage collection features are deprecated in favor of eviction. -For a list of the deprecated features, see [kubelet garbage collection deprecation](/docs/concepts/cluster-administration/kubelet-garbage-collection/#deprecation). +For a list of the deprecated features, see +[kubelet garbage collection deprecation](/docs/concepts/architecture/garbage-collection/#deprecation). {{}} ### Eviction thresholds diff --git a/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md b/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md index 4bb3471745..82e812c53b 100644 --- a/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md +++ b/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md @@ -15,14 +15,15 @@ is a property of {{< glossary_tooltip text="Pods" term_id="pod" >}} that *attrac a set of {{< glossary_tooltip text="nodes" term_id="node" >}} (either as a preference or a hard requirement). _Taints_ are the opposite -- they allow a node to repel a set of pods. -_Tolerations_ are applied to pods. Tolerations allow the scheduler to schedule pods with matching taints. Tolerations allow scheduling but don't guarantee scheduling: the scheduler also [evaluates other parameters](/docs/concepts/scheduling-eviction/pod-priority-preemption/) as part of its function. +_Tolerations_ are applied to pods. Tolerations allow the scheduler to schedule pods with matching +taints. Tolerations allow scheduling but don't guarantee scheduling: the scheduler also +[evaluates other parameters](/docs/concepts/scheduling-eviction/pod-priority-preemption/) +as part of its function. Taints and tolerations work together to ensure that pods are not scheduled onto inappropriate nodes. One or more taints are applied to a node; this marks that the node should not accept any pods that do not tolerate the taints. - - ## Concepts @@ -266,7 +267,8 @@ This ensures that DaemonSet pods are never evicted due to these problems. ## Taint Nodes by Condition The control plane, using the node {{}}, -automatically creates taints with a `NoSchedule` effect for [node conditions](/docs/concepts/scheduling-eviction/node-pressure-eviction/#node-conditions). +automatically creates taints with a `NoSchedule` effect for +[node conditions](/docs/concepts/scheduling-eviction/node-pressure-eviction/#node-conditions). The scheduler checks taints, not node conditions, when it makes scheduling decisions. This ensures that node conditions don't directly affect scheduling. @@ -297,7 +299,7 @@ arbitrary tolerations to DaemonSets. ## {{% heading "whatsnext" %}} -* Read about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/) and how you can configure it +* Read about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/) + and how you can configure it * Read about [Pod Priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/) - diff --git a/content/en/docs/concepts/security/controlling-access.md b/content/en/docs/concepts/security/controlling-access.md index 04b13a82c5..1718aa4a54 100644 --- a/content/en/docs/concepts/security/controlling-access.md +++ b/content/en/docs/concepts/security/controlling-access.md @@ -23,10 +23,11 @@ following diagram: ## Transport security -In a typical Kubernetes cluster, the API serves on port 443, protected by TLS. +By default, the Kubernetes API server listens on port 6443 on the first non-localhost network interface, protected by TLS. In a typical production Kubernetes cluster, the API serves on port 443. The port can be changed with the `--secure-port`, and the listening IP address with the `--bind-address` flag. + The API server presents a certificate. This certificate may be signed using a private certificate authority (CA), or based on a public key infrastructure linked -to a generally recognized CA. +to a generally recognized CA. The certificate and corresponding private key can be set by using the `--tls-cert-file` and `--tls-private-key-file` flags. If your cluster uses a private certificate authority, you need a copy of that CA certificate configured into your `~/.kube/config` on the client, so that you can @@ -137,34 +138,6 @@ The cluster audits the activities generated by users, by applications that use t For more information, see [Auditing](/docs/tasks/debug/debug-cluster/audit/). -## API server ports and IPs - -The previous discussion applies to requests sent to the secure port of the API server -(the typical case). The API server can actually serve on 2 ports: - -By default, the Kubernetes API server serves HTTP on 2 ports: - - 1. `localhost` port: - - - is intended for testing and bootstrap, and for other components of the master node - (scheduler, controller-manager) to talk to the API - - no TLS - - default is port 8080 - - default IP is localhost, change with `--insecure-bind-address` flag. - - request **bypasses** authentication and authorization modules. - - request handled by admission control module(s). - - protected by need to have host access - - 2. “Secure port”: - - - use whenever possible - - uses TLS. Set cert with `--tls-cert-file` and key with `--tls-private-key-file` flag. - - default is port 6443, change with `--secure-port` flag. - - default IP is first non-localhost network interface, change with `--bind-address` flag. - - request handled by authentication and authorization modules. - - request handled by admission control module(s). - - authentication and authorization modules run. - ## {{% heading "whatsnext" %}} Read more documentation on authentication, authorization and API access control: diff --git a/content/en/docs/concepts/security/multi-tenancy.md b/content/en/docs/concepts/security/multi-tenancy.md index f68b25dae3..0ba9eb8d10 100755 --- a/content/en/docs/concepts/security/multi-tenancy.md +++ b/content/en/docs/concepts/security/multi-tenancy.md @@ -129,7 +129,7 @@ Namespace management tools may simplify the creation of default or common networ Network policies require a [CNI plugin](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/#cni) that supports the implementation of network policies. Otherwise, NetworkPolicy resources will be ignored. {{< /warning >}} -More advanced network isolation may be provided by service meshes, which provide OSI Layer 7 policies based on workload identity, in addition to namespaces. These higher-level policies can make it easier to manage namespaced based multi-tenancy, especially when multiple namespaces are dedicated to a single tenant. They frequently also offer encryption using mutual TLS, protecting your data even in the presence of a compromised node, and work across dedicated or virtual clusters. However, they can be significantly more complex to manage and may not be appropriate for all users. +More advanced network isolation may be provided by service meshes, which provide OSI Layer 7 policies based on workload identity, in addition to namespaces. These higher-level policies can make it easier to manage namespace-based multi-tenancy, especially when multiple namespaces are dedicated to a single tenant. They frequently also offer encryption using mutual TLS, protecting your data even in the presence of a compromised node, and work across dedicated or virtual clusters. However, they can be significantly more complex to manage and may not be appropriate for all users. ### Storage isolation diff --git a/content/en/docs/concepts/security/pod-security-standards.md b/content/en/docs/concepts/security/pod-security-standards.md index 47e93d3e9e..d60f3b0ae1 100644 --- a/content/en/docs/concepts/security/pod-security-standards.md +++ b/content/en/docs/concepts/security/pod-security-standards.md @@ -462,11 +462,11 @@ of individual policies are not defined here. {{% thirdparty-content %}} Other alternatives for enforcing policies are being developed in the Kubernetes ecosystem, such as: + - [Kubewarden](https://github.com/kubewarden) - [Kyverno](https://kyverno.io/policies/pod-security/) - [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) - ## FAQ ### Why isn't there a profile between privileged and baseline? @@ -493,9 +493,9 @@ built-in [Pod Security Admission Controller](/docs/concepts/security/pod-securit ### What profiles should I apply to my Windows Pods? Windows in Kubernetes has some limitations and differentiators from standard Linux-based -workloads. Specifically, many of the Pod SecurityContext fields [have no effect on -Windows](/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#v1-podsecuritycontext). As -such, no standardized Pod Security profiles currently exist. +workloads. Specifically, many of the Pod SecurityContext fields +[have no effect on Windows](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext). +As such, no standardized Pod Security profiles currently exist. If you apply the restricted profile for a Windows pod, this **may** have an impact on the pod at runtime. The restricted profile requires enforcing Linux-specific restrictions (such as seccomp @@ -504,7 +504,9 @@ these Linux-specific values, then the Windows pod should still work normally wit profile. However, the lack of enforcement means that there is no additional restriction, for Pods that use Windows containers, compared to the baseline profile. -The use of the HostProcess flag to create a HostProcess pod should only be done in alignment with the privileged policy. Creation of a Windows HostProcess pod is blocked under the baseline and restricted policies, so any HostProcess pod should be considered privileged. +The use of the HostProcess flag to create a HostProcess pod should only be done in alignment with the privileged policy. +Creation of a Windows HostProcess pod is blocked under the baseline and restricted policies, +so any HostProcess pod should be considered privileged. ### What about sandboxed Pods? @@ -518,3 +520,4 @@ kernel. This allows for workloads requiring heightened permissions to still be i Additionally, the protection of sandboxed workloads is highly dependent on the method of sandboxing. As such, no single recommended profile is recommended for all sandboxed workloads. + diff --git a/content/en/docs/concepts/security/rbac-good-practices.md b/content/en/docs/concepts/security/rbac-good-practices.md index cfcc8b3cb9..42436bb202 100644 --- a/content/en/docs/concepts/security/rbac-good-practices.md +++ b/content/en/docs/concepts/security/rbac-good-practices.md @@ -15,7 +15,8 @@ execute their roles. It is important to ensure that, when designing permissions users, the cluster administrator understands the areas where privilge escalation could occur, to reduce the risk of excessive access leading to security incidents. -The good practices laid out here should be read in conjunction with the general [RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update). +The good practices laid out here should be read in conjunction with the general +[RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update). @@ -34,7 +35,8 @@ some general rules that can be applied are : not just to all object types presently in the cluster, but also to all future object types which are created in the future. - Administrators should not use `cluster-admin` accounts except where specifically needed. - Providing a low privileged account with [impersonation rights](/docs/reference/access-authn-authz/authentication/#user-impersonation) + Providing a low privileged account with + [impersonation rights](/docs/reference/access-authn-authz/authentication/#user-impersonation) can avoid accidental modification of cluster resources. - Avoid adding users to the `system:masters` group. Any user who is a member of this group bypasses all RBAC rights checks and will always have unrestricted superuser access, which cannot be @@ -44,15 +46,17 @@ some general rules that can be applied are : ### Minimize distribution of privileged tokens -Ideally, pods shouldn't be assigned service accounts that have been granted powerful permissions (for example, any of the rights listed under -[privilege escalation risks](#privilege-escalation-risks)). +Ideally, pods shouldn't be assigned service accounts that have been granted powerful permissions +(for example, any of the rights listed under [privilege escalation risks](#privilege-escalation-risks)). In cases where a workload requires powerful permissions, consider the following practices: - Limit the number of nodes running powerful pods. Ensure that any DaemonSets you run are necessary and are run with least privilege to limit the blast radius of container escapes. - Avoid running powerful pods alongside untrusted or publicly-exposed ones. Consider using - [Taints and Toleration](/docs/concepts/scheduling-eviction/taint-and-toleration/), [NodeAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity), or [PodAntiAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity) to ensure - pods don't run alongside untrusted or less-trusted Pods. Pay especial attention to + [Taints and Toleration](/docs/concepts/scheduling-eviction/taint-and-toleration/), + [NodeAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity), or + [PodAntiAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity) + to ensure pods don't run alongside untrusted or less-trusted Pods. Pay especial attention to situations where less-trustworthy Pods are not meeting the **Restricted** Pod Security Standard. ### Hardening @@ -107,7 +111,7 @@ with the ability to create suitably secure and isolated Pods, you should enforce You can use [Pod Security admission](/docs/concepts/security/pod-security-admission/) or other (third party) mechanisms to implement that enforcement. -You can also use the deprecated [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) mechanism +You can also use the deprecated [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) mechanism to restrict users' abilities to create privileged Pods (N.B. PodSecurityPolicy is scheduled for removal in version 1.25). @@ -117,7 +121,9 @@ Secrets they would not have through RBAC directly. ### Persistent volume creation -As noted in the [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems) documentation, access to create PersistentVolumes can allow for escalation of access to the underlying host. Where access to persistent storage is required trusted administrators should create +As noted in the [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/#volumes-and-file-systems) +documentation, access to create PersistentVolumes can allow for escalation of access to the underlying host. +Where access to persistent storage is required trusted administrators should create PersistentVolumes, and constrained users should use PersistentVolumeClaims to access that storage. ### Access to `proxy` subresource of Nodes @@ -130,7 +136,8 @@ granting rights to this resource. ### Escalate verb Generally the RBAC system prevents users from creating clusterroles with more rights than -they possess. The exception to this is the `escalate` verb. As noted in the [RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update), +they possess. The exception to this is the `escalate` verb. As noted in the +[RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update), users with this right can effectively escalate their privileges. ### Bind verb @@ -173,8 +180,11 @@ objects to create a denial of service condition either based on the size or numb specifically relevant in multi-tenant clusters if semi-trusted or untrusted users are allowed limited access to a system. -One option for mitigation of this issue would be to use [resource quotas](/docs/concepts/policy/resource-quotas/#object-count-quota) +One option for mitigation of this issue would be to use +[resource quotas](/docs/concepts/policy/resource-quotas/#object-count-quota) to limit the quantity of objects which can be created. ## {{% heading "whatsnext" %}} + * To learn more about RBAC, see the [RBAC documentation](/docs/reference/access-authn-authz/rbac/). + diff --git a/content/en/docs/concepts/security/windows-security.md b/content/en/docs/concepts/security/windows-security.md index 8c0704ac2b..c6523e3a43 100644 --- a/content/en/docs/concepts/security/windows-security.md +++ b/content/en/docs/concepts/security/windows-security.md @@ -22,34 +22,41 @@ storage (as compared to using tmpfs / in-memory filesystems on Linux). As a clus operator, you should take both of the following additional measures: 1. Use file ACLs to secure the Secrets' file location. -1. Apply volume-level encryption using [BitLocker](https://docs.microsoft.com/windows/security/information-protection/bitlocker/bitlocker-how-to-deploy-on-windows-server). +1. Apply volume-level encryption using + [BitLocker](https://docs.microsoft.com/windows/security/information-protection/bitlocker/bitlocker-how-to-deploy-on-windows-server). ## Container users [RunAsUsername](/docs/tasks/configure-pod-container/configure-runasusername) can be specified for Windows Pods or containers to execute the container processes as specific user. This is roughly equivalent to -[RunAsUser](/docs/concepts/policy/pod-security-policy/#users-and-groups). +[RunAsUser](/docs/concepts/security/pod-security-policy/#users-and-groups). Windows containers offer two default user accounts, ContainerUser and ContainerAdministrator. The differences between these two user accounts are covered in -[When to use ContainerAdmin and ContainerUser user accounts](https://docs.microsoft.com/virtualization/windowscontainers/manage-containers/container-security#when-to-use-containeradmin-and-containeruser-user-accounts) within Microsoft's _Secure Windows containers_ documentation. +[When to use ContainerAdmin and ContainerUser user accounts](https://docs.microsoft.com/virtualization/windowscontainers/manage-containers/container-security#when-to-use-containeradmin-and-containeruser-user-accounts) +within Microsoft's _Secure Windows containers_ documentation. Local users can be added to container images during the container build process. {{< note >}} -* [Nano Server](https://hub.docker.com/_/microsoft-windows-nanoserver) based images run as `ContainerUser` by default -* [Server Core](https://hub.docker.com/_/microsoft-windows-servercore) based images run as `ContainerAdministrator` by default +* [Nano Server](https://hub.docker.com/_/microsoft-windows-nanoserver) based images run as + `ContainerUser` by default +* [Server Core](https://hub.docker.com/_/microsoft-windows-servercore) based images run as + `ContainerAdministrator` by default {{< /note >}} -Windows containers can also run as Active Directory identities by utilizing [Group Managed Service Accounts](/docs/tasks/configure-pod-container/configure-gmsa/) +Windows containers can also run as Active Directory identities by utilizing +[Group Managed Service Accounts](/docs/tasks/configure-pod-container/configure-gmsa/) ## Pod-level security isolation Linux-specific pod security context mechanisms (such as SELinux, AppArmor, Seccomp, or custom POSIX capabilities) are not supported on Windows nodes. -Privileged containers are [not supported](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext) on Windows. -Instead [HostProcess containers](/docs/tasks/configure-pod-container/create-hostprocess-pod) can be used on Windows to perform many of the tasks performed by privileged containers on Linux. +Privileged containers are [not supported](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext) +on Windows. +Instead [HostProcess containers](/docs/tasks/configure-pod-container/create-hostprocess-pod) +can be used on Windows to perform many of the tasks performed by privileged containers on Linux. diff --git a/content/en/docs/concepts/services-networking/ingress-controllers.md b/content/en/docs/concepts/services-networking/ingress-controllers.md index 5516306ffa..f2d593448e 100644 --- a/content/en/docs/concepts/services-networking/ingress-controllers.md +++ b/content/en/docs/concepts/services-networking/ingress-controllers.md @@ -46,6 +46,7 @@ Kubernetes as a project supports and maintains [AWS](https://github.com/kubernet is an [Istio](https://istio.io/) based ingress controller. * The [Kong Ingress Controller for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller#readme) is an ingress controller driving [Kong Gateway](https://konghq.com/kong/). +* [Kusk Gateway](https://kusk.kubeshop.io/) is an OpenAPI-driven ingress controller based on [Envoy](https://www.envoyproxy.io). * The [NGINX Ingress Controller for Kubernetes](https://www.nginx.com/products/nginx-ingress-controller/) works with the [NGINX](https://www.nginx.com/resources/glossary/nginx/) webserver (as a proxy). * The [Pomerium Ingress Controller](https://www.pomerium.com/docs/k8s/ingress.html) is based on [Pomerium](https://pomerium.com/), which offers context-aware access policy. diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index ad5af427ec..c88375164b 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -299,9 +299,14 @@ thus is only available to use as-is. ### Configuration Note that the kube-proxy starts up in different modes, which are determined by its configuration. -- The kube-proxy's configuration is done via a ConfigMap, and the ConfigMap for kube-proxy effectively deprecates the behaviour for almost all of the flags for the kube-proxy. +- The kube-proxy's configuration is done via a ConfigMap, and the ConfigMap for kube-proxy + effectively deprecates the behaviour for almost all of the flags for the kube-proxy. - The ConfigMap for the kube-proxy does not support live reloading of configuration. -- The ConfigMap parameters for the kube-proxy cannot all be validated and verified on startup. For example, if your operating system doesn't allow you to run iptables commands, the standard kernel kube-proxy implementation will not work. Likewise, if you have an operating system which doesn't support `netsh`, it will not run in Windows userspace mode. +- The ConfigMap parameters for the kube-proxy cannot all be validated and verified on startup. + For example, if your operating system doesn't allow you to run iptables commands, + the standard kernel kube-proxy implementation will not work. + Likewise, if you have an operating system which doesn't support `netsh`, + it will not run in Windows userspace mode. ### User space proxy mode {#proxy-mode-userspace} @@ -492,7 +497,11 @@ variables and DNS. ### Environment variables When a Pod is run on a Node, the kubelet adds a set of environment variables -for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables, where the Service name is upper-cased and dashes are converted to underscores. It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) that are compatible with Docker Engine's "_[legacy container links](https://docs.docker.com/network/links/)_" feature. +for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables, +where the Service name is upper-cased and dashes are converted to underscores. +It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) +that are compatible with Docker Engine's +"_[legacy container links](https://docs.docker.com/network/links/)_" feature. For example, the Service `redis-master` which exposes TCP port 6379 and has been allocated cluster IP address 10.0.0.11, produces the following environment @@ -604,8 +613,10 @@ The default is `ClusterIP`. to use the `ExternalName` type. {{< /note >}} -You can also use [Ingress](/docs/concepts/services-networking/ingress/) to expose your Service. Ingress is not a Service type, but it acts as the entry point for your cluster. It lets you consolidate your routing rules -into a single resource as it can expose multiple services under the same IP address. +You can also use [Ingress](/docs/concepts/services-networking/ingress/) to expose your Service. +Ingress is not a Service type, but it acts as the entry point for your cluster. +It lets you consolidate your routing rules into a single resource as it can expose multiple +services under the same IP address. ### Type NodePort {#type-nodeport} @@ -620,9 +631,14 @@ field of the [kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/) to particular IP block(s). -This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) to specify IP address ranges that kube-proxy should consider as local to this node. +This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) +to specify IP address ranges that kube-proxy should consider as local to this node. -For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, kube-proxy only selects the loopback interface for NodePort Services. The default for `--nodeport-addresses` is an empty list. This means that kube-proxy should consider all available network interfaces for NodePort. (That's also compatible with earlier Kubernetes releases). +For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, +kube-proxy only selects the loopback interface for NodePort Services. +The default for `--nodeport-addresses` is an empty list. +his means that kube-proxy should consider all available network interfaces for NodePort. +(That's also compatible with earlier Kubernetes releases). If you want a specific port number, you can specify a value in the `nodePort` field. The control plane will either allocate you that port or report that @@ -689,7 +705,8 @@ status: - ip: 192.0.2.127 ``` -Traffic from the external load balancer is directed at the backend Pods. The cloud provider decides how it is load balanced. +Traffic from the external load balancer is directed at the backend Pods. +The cloud provider decides how it is load balanced. Some cloud providers allow you to specify the `loadBalancerIP`. In those cases, the load-balancer is created with the user-specified `loadBalancerIP`. If the `loadBalancerIP` field is not specified, @@ -704,7 +721,11 @@ to create a static type public IP address resource. This public IP address resou be in the same resource group of the other automatically created resources of the cluster. For example, `MC_myResourceGroup_myAKSCluster_eastus`. -Specify the assigned IP address as loadBalancerIP. Ensure that you have updated the securityGroupName in the cloud provider configuration file. For information about troubleshooting `CreatingLoadBalancerFailed` permission issues see, [Use a static IP address with the Azure Kubernetes Service (AKS) load balancer](https://docs.microsoft.com/en-us/azure/aks/static-ip) or [CreatingLoadBalancerFailed on AKS cluster with advanced networking](https://github.com/Azure/AKS/issues/357). +Specify the assigned IP address as loadBalancerIP. Ensure that you have updated the +`securityGroupName` in the cloud provider configuration file. +For information about troubleshooting `CreatingLoadBalancerFailed` permission issues see, +[Use a static IP address with the Azure Kubernetes Service (AKS) load balancer](https://docs.microsoft.com/en-us/azure/aks/static-ip) +or [CreatingLoadBalancerFailed on AKS cluster with advanced networking](https://github.com/Azure/AKS/issues/357). {{< /note >}} @@ -760,7 +781,8 @@ Unprefixed names are reserved for end-users. In a mixed environment it is sometimes necessary to route traffic from Services inside the same (virtual) network address block. -In a split-horizon DNS environment you would need two Services to be able to route both external and internal traffic to your endpoints. +In a split-horizon DNS environment you would need two Services to be able to route both external +and internal traffic to your endpoints. To set an internal load balancer, add one of the following annotations to your Service depending on the cloud Service provider you're using. @@ -925,7 +947,9 @@ you can use the following annotations: In the above example, if the Service contained three ports, `80`, `443`, and `8443`, then `443` and `8443` would use the SSL certificate, but `80` would be proxied HTTP. -From Kubernetes v1.9 onwards you can use [predefined AWS SSL policies](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) with HTTPS or SSL listeners for your Services. +From Kubernetes v1.9 onwards you can use +[predefined AWS SSL policies](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) +with HTTPS or SSL listeners for your Services. To see which policies are available for use, you can use the `aws` command line tool: ```bash @@ -981,14 +1005,17 @@ specifies the logical hierarchy you created for your Amazon S3 bucket. metadata: name: my-service annotations: - service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "true" # Specifies whether access logs are enabled for the load balancer - service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "60" + service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "true" + # The interval for publishing the access logs. You can specify an interval of either 5 or 60 (minutes). - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: "my-bucket" + service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "60" + # The name of the Amazon S3 bucket where the access logs are stored - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "my-bucket-prefix/prod" + service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: "my-bucket" + # The logical hierarchy you created for your Amazon S3 bucket, for example `my-bucket-prefix/prod` + service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "my-bucket-prefix/prod" ``` #### Connection Draining on AWS @@ -997,7 +1024,8 @@ Connection draining for Classic ELBs can be managed with the annotation `service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled` set to the value of `"true"`. The annotation `service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout` can -also be used to set maximum time, in seconds, to keep the existing connections open before deregistering the instances. +also be used to set maximum time, in seconds, to keep the existing connections open before +deregistering the instances. ```yaml metadata: @@ -1015,50 +1043,56 @@ There are other annotations to manage Classic Elastic Load Balancers that are de metadata: name: my-service annotations: + # The time, in seconds, that the connection is allowed to be idle (no data has been sent + # over the connection) before it is closed by the load balancer service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "60" - # The time, in seconds, that the connection is allowed to be idle (no data has been sent over the connection) before it is closed by the load balancer - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" # Specifies whether cross-zone load balancing is enabled for the load balancer + service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" - service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "environment=prod,owner=devops" # A comma-separated list of key-value pairs which will be recorded as # additional tags in the ELB. + service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "environment=prod,owner=devops" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "" # The number of successive successful health checks required for a backend to # be considered healthy for traffic. Defaults to 2, must be between 2 and 10 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3" # The number of unsuccessful health checks required for a backend to be # considered unhealthy for traffic. Defaults to 6, must be between 2 and 10 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "20" # The approximate interval, in seconds, between health checks of an # individual instance. Defaults to 10, must be between 5 and 300 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "20" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "5" # The amount of time, in seconds, during which no response means a failed # health check. This value must be less than the service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval # value. Defaults to 5, must be between 2 and 60 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "5" - service.beta.kubernetes.io/aws-load-balancer-security-groups: "sg-53fae93f" # A list of existing security groups to be configured on the ELB created. Unlike the annotation - # service.beta.kubernetes.io/aws-load-balancer-extra-security-groups, this replaces all other security groups previously assigned to the ELB and also overrides the creation + # service.beta.kubernetes.io/aws-load-balancer-extra-security-groups, this replaces all other + # security groups previously assigned to the ELB and also overrides the creation # of a uniquely generated security group for this ELB. - # The first security group ID on this list is used as a source to permit incoming traffic to target worker nodes (service traffic and health checks). - # If multiple ELBs are configured with the same security group ID, only a single permit line will be added to the worker node security groups, that means if you delete any + # The first security group ID on this list is used as a source to permit incoming traffic to + # target worker nodes (service traffic and health checks). + # If multiple ELBs are configured with the same security group ID, only a single permit line + # will be added to the worker node security groups, that means if you delete any # of those ELBs it will remove the single permit line and block access for all ELBs that shared the same security group ID. # This can cause a cross-service outage if not used properly + service.beta.kubernetes.io/aws-load-balancer-security-groups: "sg-53fae93f" - service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-53fae93f,sg-42efd82e" - # A list of additional security groups to be added to the created ELB, this leaves the uniquely generated security group in place, this ensures that every ELB - # has a unique security group ID and a matching permit line to allow traffic to the target worker nodes (service traffic and health checks). + # A list of additional security groups to be added to the created ELB, this leaves the uniquely + # generated security group in place, this ensures that every ELB + # has a unique security group ID and a matching permit line to allow traffic to the target worker nodes + # (service traffic and health checks). # Security groups defined here can be shared between services. + service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-53fae93f,sg-42efd82e" - service.beta.kubernetes.io/aws-load-balancer-target-node-labels: "ingress-gw,gw-name=public-api" # A comma separated list of key-value pairs which are used # to select the target nodes for the load balancer + service.beta.kubernetes.io/aws-load-balancer-target-node-labels: "ingress-gw,gw-name=public-api" ``` #### Network Load Balancer support on AWS {#aws-nlb-support} @@ -1075,7 +1109,8 @@ To use a Network Load Balancer on AWS, use the annotation `service.beta.kubernet ``` {{< note >}} -NLB only works with certain instance classes; see the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) +NLB only works with certain instance classes; see the +[AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) on Elastic Load Balancing for a list of supported instance types. {{< /note >}} @@ -1182,7 +1217,8 @@ spec: ``` {{< note >}} -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 +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 >}} @@ -1196,9 +1232,13 @@ can start its Pods, add appropriate selectors or endpoints, and change the Service's `type`. {{< warning >}} -You may have trouble using ExternalName for some common protocols, including HTTP and HTTPS. If you use ExternalName then the hostname used by clients inside your cluster is different from the name that the ExternalName references. +You may have trouble using ExternalName for some common protocols, including HTTP and HTTPS. +If you use ExternalName then the hostname used by clients inside your cluster is different from +the name that the ExternalName references. -For protocols that use hostnames this difference may lead to errors or unexpected responses. HTTP requests will have a `Host:` header that the origin server does not recognize; TLS servers will not be able to provide a certificate matching the hostname that the client connected to. +For protocols that use hostnames this difference may lead to errors or unexpected responses. +HTTP requests will have a `Host:` header that the origin server does not recognize; +TLS servers will not be able to provide a certificate matching the hostname that the client connected to. {{< /warning >}} {{< note >}} @@ -1357,12 +1397,15 @@ through a load-balancer, though in those cases the client IP does get altered. #### IPVS iptables operations slow down dramatically in large scale cluster e.g 10,000 Services. -IPVS is designed for load balancing and based on in-kernel hash tables. So you can achieve performance consistency in large number of Services from IPVS-based kube-proxy. Meanwhile, IPVS-based kube-proxy has more sophisticated load balancing algorithms (least conns, locality, weighted, persistence). +IPVS is designed for load balancing and based on in-kernel hash tables. +So you can achieve performance consistency in large number of Services from IPVS-based kube-proxy. +Meanwhile, IPVS-based kube-proxy has more sophisticated load balancing algorithms +(least conns, locality, weighted, persistence). ## API Object Service is a top-level resource in the Kubernetes REST API. You can find more details -about the API object at: [Service API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core). +about the [Service API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core). ## Supported protocols {#protocol-support} @@ -1388,7 +1431,8 @@ provider offering this facility. (Most do not). ##### Support for multihomed SCTP associations {#caveat-sctp-multihomed} {{< warning >}} -The support of multihomed SCTP associations requires that the CNI plugin can support the assignment of multiple interfaces and IP addresses to a Pod. +The support of multihomed SCTP associations requires that the CNI plugin can support the +assignment of multiple interfaces and IP addresses to a Pod. NAT for multihomed SCTP associations requires special logic in the corresponding kernel modules. {{< /warning >}} @@ -1437,3 +1481,4 @@ followed by the data from the client. * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) * Read about [Ingress](/docs/concepts/services-networking/ingress/) * Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) + diff --git a/content/en/docs/concepts/storage/ephemeral-volumes.md b/content/en/docs/concepts/storage/ephemeral-volumes.md index 27ea999ccf..045bcafe76 100644 --- a/content/en/docs/concepts/storage/ephemeral-volumes.md +++ b/content/en/docs/concepts/storage/ephemeral-volumes.md @@ -76,8 +76,8 @@ is managed by kubelet, or injecting different data. {{< feature-state for_k8s_version="v1.16" state="beta" >}} -This feature requires the `CSIInlineVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. It -is enabled by default starting with Kubernetes 1.16. +This feature requires the `CSIInlineVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +to be enabled. It is enabled by default starting with Kubernetes 1.16. {{< note >}} CSI ephemeral volumes are only supported by a subset of CSI drivers. @@ -136,8 +136,11 @@ should not be exposed to users through the use of inline ephemeral volumes. Cluster administrators who need to restrict the CSI drivers that are allowed to be used as inline volumes within a Pod spec may do so by: -- Removing `Ephemeral` from `volumeLifecycleModes` in the CSIDriver spec, which prevents the driver from being used as an inline ephemeral volume. -- Using an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) to restrict how this driver is used. + +- Removing `Ephemeral` from `volumeLifecycleModes` in the CSIDriver spec, which prevents the + driver from being used as an inline ephemeral volume. +- Using an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) + to restrict how this driver is used. ### Generic ephemeral volumes @@ -207,7 +210,7 @@ because then the scheduler is free to choose a suitable node for the Pod. With immediate binding, the scheduler is forced to select a node that has access to the volume once it is available. -In terms of [resource ownership](/docs/concepts/workloads/controllers/garbage-collection/#owners-dependents), +In terms of [resource ownership](/docs/concepts/architecture/garbage-collection/#owners-dependents), a Pod that has generic ephemeral storage is the owner of the PersistentVolumeClaim(s) that provide that ephemeral storage. When the Pod is deleted, the Kubernetes garbage collector deletes the PVC, which then usually @@ -252,10 +255,11 @@ Enabling the GenericEphemeralVolume feature allows users to create PVCs indirectly if they can create Pods, even if they do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit their security model, they should -use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) that rejects objects like Pods that have a generic ephemeral volume. +use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) +that rejects objects like Pods that have a generic ephemeral volume. -The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) still applies, so -even if users are allowed to use this new mechanism, they cannot use +The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) +still applies, so even if users are allowed to use this new mechanism, they cannot use it to circumvent other policies. ## {{% heading "whatsnext" %}} @@ -266,11 +270,13 @@ See [local ephemeral storage](/docs/concepts/configuration/manage-resources-cont ### CSI ephemeral volumes -- For more information on the design, see the [Ephemeral Inline CSI - volumes KEP](https://github.com/kubernetes/enhancements/blob/ad6021b3d61a49040a3f835e12c8bb5424db2bbb/keps/sig-storage/20190122-csi-inline-volumes.md). -- For more information on further development of this feature, see the [enhancement tracking issue #596](https://github.com/kubernetes/enhancements/issues/596). +- For more information on the design, see the + [Ephemeral Inline CSI volumes KEP](https://github.com/kubernetes/enhancements/blob/ad6021b3d61a49040a3f835e12c8bb5424db2bbb/keps/sig-storage/20190122-csi-inline-volumes.md). +- For more information on further development of this feature, see the + [enhancement tracking issue #596](https://github.com/kubernetes/enhancements/issues/596). ### Generic ephemeral volumes - For more information on the design, see the -[Generic ephemeral inline volumes KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1698-generic-ephemeral-volumes/README.md). + [Generic ephemeral inline volumes KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1698-generic-ephemeral-volumes/README.md). + diff --git a/content/en/docs/concepts/workloads/_index.md b/content/en/docs/concepts/workloads/_index.md index 2c9dd8aa8e..dffd727505 100644 --- a/content/en/docs/concepts/workloads/_index.md +++ b/content/en/docs/concepts/workloads/_index.md @@ -70,7 +70,7 @@ visit [Configuration](/docs/concepts/configuration/). There are two supporting concepts that provide backgrounds about how Kubernetes manages pods for applications: -* [Garbage collection](/docs/concepts/workloads/controllers/garbage-collection/) tidies up objects +* [Garbage collection](/docs/concepts/architecture/garbage-collection/) tidies up objects from your cluster after their _owning resource_ has been removed. * The [_time-to-live after finished_ controller](/docs/concepts/workloads/controllers/ttlafterfinished/) removes Jobs once a defined time has passed since they completed. diff --git a/content/en/docs/concepts/workloads/controllers/replicaset.md b/content/en/docs/concepts/workloads/controllers/replicaset.md index 470a5e5024..a282b8455a 100644 --- a/content/en/docs/concepts/workloads/controllers/replicaset.md +++ b/content/en/docs/concepts/workloads/controllers/replicaset.md @@ -13,9 +13,6 @@ weight: 20 A ReplicaSet's purpose is to maintain a stable set of replica Pods running at any given time. As such, it is often used to guarantee the availability of a specified number of identical Pods. - - - ## How a ReplicaSet works @@ -26,14 +23,14 @@ it should create to meet the number of replicas criteria. A ReplicaSet then fulf and deleting Pods as needed to reach the desired number. When a ReplicaSet needs to create new Pods, it uses its Pod template. -A ReplicaSet is linked to its Pods via the Pods' [metadata.ownerReferences](/docs/concepts/workloads/controllers/garbage-collection/#owners-and-dependents) +A ReplicaSet is linked to its Pods via the Pods' [metadata.ownerReferences](/docs/concepts/architecture/garbage-collection/#owners-and-dependents) field, which specifies what resource the current object is owned by. All Pods acquired by a ReplicaSet have their owning ReplicaSet's identifying information within their ownerReferences field. It's through this link that the ReplicaSet knows of the state of the Pods it is maintaining and plans accordingly. -A ReplicaSet identifies new Pods to acquire by using its selector. If there is a Pod that has no OwnerReference or the -OwnerReference is not a {{< glossary_tooltip term_id="controller" >}} and it matches a ReplicaSet's selector, it will be immediately acquired by said -ReplicaSet. +A ReplicaSet identifies new Pods to acquire by using its selector. If there is a Pod that has no +OwnerReference or the OwnerReference is not a {{< glossary_tooltip term_id="controller" >}} and it +matches a ReplicaSet's selector, it will be immediately acquired by said ReplicaSet. ## When to use a ReplicaSet @@ -253,7 +250,9 @@ In the ReplicaSet, `.spec.template.metadata.labels` must match `spec.selector`, be rejected by the API. {{< note >}} -For 2 ReplicaSets specifying the same `.spec.selector` but different `.spec.template.metadata.labels` and `.spec.template.spec` fields, each ReplicaSet ignores the Pods created by the other ReplicaSet. +For 2 ReplicaSets specifying the same `.spec.selector` but different +`.spec.template.metadata.labels` and `.spec.template.spec` fields, each ReplicaSet ignores the +Pods created by the other ReplicaSet. {{< /note >}} ### Replicas @@ -267,11 +266,14 @@ If you do not specify `.spec.replicas`, then it defaults to 1. ### Deleting a ReplicaSet and its Pods -To delete a ReplicaSet and all of its Pods, use [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete). The [Garbage collector](/docs/concepts/workloads/controllers/garbage-collection/) automatically deletes all of the dependent Pods by default. +To delete a ReplicaSet and all of its Pods, use +[`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete). The +[Garbage collector](/docs/concepts/architecture/garbage-collection/) automatically deletes all of +the dependent Pods by default. + +When using the REST API or the `client-go` library, you must set `propagationPolicy` to +`Background` or `Foreground` in the `-d` option. For example: -When using the REST API or the `client-go` library, you must set `propagationPolicy` to `Background` or `Foreground` in -the -d option. -For example: ```shell kubectl proxy --port=8080 curl -X DELETE 'localhost:8080/apis/apps/v1/namespaces/default/replicasets/frontend' \ @@ -281,9 +283,12 @@ curl -X DELETE 'localhost:8080/apis/apps/v1/namespaces/default/replicasets/fron ### Deleting just a ReplicaSet -You can delete a ReplicaSet without affecting any of its Pods using [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete) with the `--cascade=orphan` option. +You can delete a ReplicaSet without affecting any of its Pods using +[`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete) +with the `--cascade=orphan` option. When using the REST API or the `client-go` library, you must set `propagationPolicy` to `Orphan`. For example: + ```shell kubectl proxy --port=8080 curl -X DELETE 'localhost:8080/apis/apps/v1/namespaces/default/replicasets/frontend' \ @@ -295,7 +300,8 @@ Once the original is deleted, you can create a new ReplicaSet to replace it. As as the old and new `.spec.selector` are the same, then the new one will adopt the old Pods. However, it will not make any effort to make existing Pods match a new, different pod template. To update Pods to a new spec in a controlled way, use a -[Deployment](/docs/concepts/workloads/controllers/deployment/#creating-a-deployment), as ReplicaSets do not support a rolling update directly. +[Deployment](/docs/concepts/workloads/controllers/deployment/#creating-a-deployment), as +ReplicaSets do not support a rolling update directly. ### Isolating Pods from a ReplicaSet @@ -310,17 +316,19 @@ ensures that a desired number of Pods with a matching label selector are availab When scaling down, the ReplicaSet controller chooses which pods to delete by sorting the available pods to prioritize scaling down pods based on the following general algorithm: - 1. Pending (and unschedulable) pods are scaled down first - 2. If `controller.kubernetes.io/pod-deletion-cost` annotation is set, then - the pod with the lower value will come first. - 3. Pods on nodes with more replicas come before pods on nodes with fewer replicas. - 4. If the pods' creation times differ, the pod that was created more recently - comes before the older pod (the creation times are bucketed on an integer log scale - when the `LogarithmicScaleDown` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) + +1. Pending (and unschedulable) pods are scaled down first +1. If `controller.kubernetes.io/pod-deletion-cost` annotation is set, then + the pod with the lower value will come first. +1. Pods on nodes with more replicas come before pods on nodes with fewer replicas. +1. If the pods' creation times differ, the pod that was created more recently + comes before the older pod (the creation times are bucketed on an integer log scale + when the `LogarithmicScaleDown` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) If all of the above match, then selection is random. ### Pod deletion cost + {{< feature-state for_k8s_version="v1.22" state="beta" >}} Using the [`controller.kubernetes.io/pod-deletion-cost`](/docs/reference/labels-annotations-taints/#pod-deletion-cost) @@ -344,6 +352,7 @@ This feature is beta and enabled by default. You can disable it using the {{< /note >}} #### Example Use Case + The different pods of an application could have different utilization levels. On scale down, the application may prefer to remove the pods with lower utilization. To avoid frequently updating the pods, the application should update `controller.kubernetes.io/pod-deletion-cost` once before issuing a scale down (setting the @@ -387,12 +396,17 @@ As such, it is recommended to use Deployments when you want ReplicaSets. ### Bare Pods -Unlike the case where a user directly created Pods, a ReplicaSet replaces Pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicaSet even if your application requires only a single Pod. Think of it similarly to a process supervisor, only it supervises multiple Pods across multiple nodes instead of individual processes on a single node. A ReplicaSet delegates local container restarts to some agent on the node such as Kubelet. +Unlike the case where a user directly created Pods, a ReplicaSet replaces Pods that are deleted or +terminated for any reason, such as in the case of node failure or disruptive node maintenance, +such as a kernel upgrade. For this reason, we recommend that you use a ReplicaSet even if your +application requires only a single Pod. Think of it similarly to a process supervisor, only it +supervises multiple Pods across multiple nodes instead of individual processes on a single node. A +ReplicaSet delegates local container restarts to some agent on the node such as Kubelet. ### Job -Use a [`Job`](/docs/concepts/workloads/controllers/job/) instead of a ReplicaSet for Pods that are expected to terminate on their own -(that is, batch jobs). +Use a [`Job`](/docs/concepts/workloads/controllers/job/) instead of a ReplicaSet for Pods that are +expected to terminate on their own (that is, batch jobs). ### DaemonSet @@ -402,12 +416,12 @@ to a machine lifetime: the Pod needs to be running on the machine before other P safe to terminate when the machine is otherwise ready to be rebooted/shutdown. ### ReplicationController -ReplicaSets are the successors to [_ReplicationControllers_](/docs/concepts/workloads/controllers/replicationcontroller/). + +ReplicaSets are the successors to [ReplicationControllers](/docs/concepts/workloads/controllers/replicationcontroller/). The two serve the same purpose, and behave similarly, except that a ReplicationController does not support set-based selector requirements as described in the [labels user guide](/docs/concepts/overview/working-with-objects/labels/#label-selectors). As such, ReplicaSets are preferred over ReplicationControllers - ## {{% heading "whatsnext" %}} * Learn about [Pods](/docs/concepts/workloads/pods). @@ -419,3 +433,4 @@ As such, ReplicaSets are preferred over ReplicationControllers 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. + diff --git a/content/en/docs/concepts/workloads/controllers/statefulset.md b/content/en/docs/concepts/workloads/controllers/statefulset.md index 2ae481a431..1687399abd 100644 --- a/content/en/docs/concepts/workloads/controllers/statefulset.md +++ b/content/en/docs/concepts/workloads/controllers/statefulset.md @@ -39,10 +39,18 @@ that provides a set of stateless replicas. ## Limitations -* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. -* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the StatefulSet. This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources. -* StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service. -* StatefulSets do not provide any guarantees on the termination of pods when a StatefulSet is deleted. To achieve ordered and graceful termination of the pods in the StatefulSet, it is possible to scale the StatefulSet down to 0 prior to deletion. +* The storage for a given Pod must either be provisioned by a + [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/README.md) + based on the requested `storage class`, or pre-provisioned by an admin. +* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the + StatefulSet. This is done to ensure data safety, which is generally more valuable than an + automatic purge of all related StatefulSet resources. +* StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) + to be responsible for the network identity of the Pods. You are responsible for creating this + Service. +* StatefulSets do not provide any guarantees on the termination of pods when a StatefulSet is + deleted. To achieve ordered and graceful termination of the pods in the StatefulSet, it is + possible to scale the StatefulSet down to 0 prior to deletion. * When using [Rolling Updates](#rolling-updates) with the default [Pod Management Policy](#pod-management-policies) (`OrderedReady`), it's possible to get into a broken state that requires @@ -108,18 +116,24 @@ In the above example: * A Headless Service, named `nginx`, is used to control the network domain. * The StatefulSet, named `web`, has a Spec that indicates that 3 replicas of the nginx container will be launched in unique Pods. -* The `volumeClaimTemplates` will provide stable storage using [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume Provisioner. +* The `volumeClaimTemplates` will provide stable storage using + [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a + PersistentVolume Provisioner. The name of a StatefulSet object must be a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). ### Pod Selector -You must set the `.spec.selector` field of a StatefulSet to match the labels of its `.spec.template.metadata.labels`. Failing to specify a matching Pod Selector will result in a validation error during StatefulSet creation. +You must set the `.spec.selector` field of a StatefulSet to match the labels of its +`.spec.template.metadata.labels`. Failing to specify a matching Pod Selector will result in a +validation error during StatefulSet creation. ### Volume Claim Templates -You can set the `.spec.volumeClaimTemplates` which can provide stable storage using [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume Provisioner. +You can set the `.spec.volumeClaimTemplates` which can provide stable storage using +[PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume +Provisioner. ### Minimum ready seconds @@ -128,9 +142,11 @@ You can set the `.spec.volumeClaimTemplates` which can provide stable storage u `.spec.minReadySeconds` is an optional field that specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. -Please note that this feature is beta and enabled by default. Please opt out by unsetting the StatefulSetMinReadySeconds flag, if you don't +Please note that this feature is beta and enabled by default. Please opt out by unsetting the +StatefulSetMinReadySeconds flag, if you don't want this feature to be enabled. This field defaults to 0 (the Pod will be considered -available as soon as it is ready). To learn more about when a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). +available as soon as it is ready). To learn more about when a Pod is considered ready, see +[Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). ## Pod Identity @@ -166,8 +182,8 @@ remembered and reused, even after the Pod is running, for at least a few seconds If you need to discover Pods promptly after they are created, you have a few options: - Query the Kubernetes API directly (for example, using a watch) rather than relying on DNS lookups. -- Decrease the time of caching in your Kubernetes DNS provider (typically this means editing the config map for CoreDNS, which currently caches for 30 seconds). - +- Decrease the time of caching in your Kubernetes DNS provider (typically this means editing the + config map for CoreDNS, which currently caches for 30 seconds). As mentioned in the [limitations](#limitations) section, you are responsible for creating the [Headless Service](/docs/concepts/services-networking/service/#headless-services) @@ -189,7 +205,9 @@ Cluster Domain will be set to `cluster.local` unless ### Stable Storage -For each VolumeClaimTemplate entry defined in a StatefulSet, each Pod receives one PersistentVolumeClaim. In the nginx example above, each Pod receives a single PersistentVolume with a StorageClass of `my-storage-class` and 1 Gib of provisioned storage. If no StorageClass +For each VolumeClaimTemplate entry defined in a StatefulSet, each Pod receives one +PersistentVolumeClaim. In the nginx example above, each Pod receives a single PersistentVolume +with a StorageClass of `my-storage-class` and 1 Gib of provisioned storage. If no StorageClass is specified, then the default StorageClass will be used. When a Pod is (re)scheduled onto a node, its `volumeMounts` mount the PersistentVolumes associated with its PersistentVolume Claims. Note that, the PersistentVolumes associated with the @@ -210,7 +228,9 @@ the StatefulSet. * Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready. * Before a Pod is terminated, all of its successors must be completely shutdown. -The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of 0. This practice is unsafe and strongly discouraged. For further explanation, please refer to [force deleting StatefulSet Pods](/docs/tasks/run-application/force-delete-stateful-set-pod/). +The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of 0. This practice +is unsafe and strongly discouraged. For further explanation, please refer to +[force deleting StatefulSet Pods](/docs/tasks/run-application/force-delete-stateful-set-pod/). When the nginx example above is created, three Pods will be deployed in the order web-0, web-1, web-2. web-1 will not be deployed before web-0 is @@ -256,7 +276,8 @@ annotations for the Pods in a StatefulSet. There are two possible values: create new Pods that reflect modifications made to a StatefulSet's `.spec.template`. `RollingUpdate` -: The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a StatefulSet. This is the default update strategy. +: The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a + StatefulSet. This is the default update strategy. ## Rolling Updates @@ -299,7 +320,7 @@ unavailable Pod in the range `0` to `replicas - 1`, it will be counted towards {{< note >}} The `maxUnavailable` field is in Alpha stage and it is honored only by API servers that are running with the `MaxUnavailableStatefulSet` -[feature gate](/docs/reference/commmand-line-tools-reference/feature-gates/) +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled. {{< /note >}} @@ -375,8 +396,8 @@ spec: ... ``` -The StatefulSet {{}} adds [owner -references](/docs/concepts/overview/working-with-objects/owners-dependents/#owner-references-in-object-specifications) +The StatefulSet {{}} adds +[owner references](/docs/concepts/overview/working-with-objects/owners-dependents/#owner-references-in-object-specifications) to its PVCs, which are then deleted by the {{}} after the Pod is terminated. This enables the Pod to cleanly unmount all volumes before the PVCs are deleted (and before the backing PV and diff --git a/content/en/docs/contribute/localization.md b/content/en/docs/contribute/localization.md index fa405372c2..1c741b32e5 100644 --- a/content/en/docs/contribute/localization.md +++ b/content/en/docs/contribute/localization.md @@ -278,7 +278,7 @@ For an example of adding a new localization, see the PR to enable To guide other localization contributors, add a new [`README-**.md`](https://help.github.com/articles/about-readmes/) to the top level of -[k/website](https://github.com/kubernetes/website/), where `**` is the two-letter language code. +[kubernetes/website](https://github.com/kubernetes/website/), where `**` is the two-letter language code. For example, a German README file would be `README-de.md`. Provide guidance to localization contributors in the localized `README-**.md` file. @@ -418,7 +418,7 @@ To collaborate on a localization branch: `dev--.` For example, an approver on a German localization team opens the localization branch - `dev-1.12-de.1` directly against the k/website repository, based on the source branch for + `dev-1.12-de.1` directly against the `kubernetes/website` repository, based on the source branch for Kubernetes v1.12. 2. Individual contributors open feature branches based on the localization branch. diff --git a/content/en/docs/reference/access-authn-authz/authorization.md b/content/en/docs/reference/access-authn-authz/authorization.md index 3e7d71977c..ea6147fcba 100644 --- a/content/en/docs/reference/access-authn-authz/authorization.md +++ b/content/en/docs/reference/access-authn-authz/authorization.md @@ -74,6 +74,10 @@ PUT | update PATCH | patch DELETE | delete (for individual resources), deletecollection (for collections) +{{< caution >}} +The `get`, `list` and `watch` verbs can all return the full details of a resource. In terms of the returned data they are equivalent. For example, `list` on `secrets` will still reveal the `data` attributes of any returned resources. +{{< /caution >}} + Kubernetes sometimes checks authorization for additional permissions using specialized verbs. For example: * [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) diff --git a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md index 6f7154cc8a..05f9b8369c 100644 --- a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md @@ -16,8 +16,8 @@ In addition to [compiled-in admission plugins](/docs/reference/access-authn-auth admission plugins can be developed as extensions and run as webhooks configured at runtime. This page describes how to build, configure, use, and monitor admission webhooks. - + ## What are admission webhooks? Admission webhooks are HTTP callbacks that receive admission requests and do @@ -37,29 +37,25 @@ should use a validating admission webhook, since objects can be modified after b ## Experimenting with admission webhooks Admission webhooks are essentially part of the cluster control-plane. You should -write and deploy them with great caution. Please read the [user -guides](/docs/reference/access-authn-authz/extensible-admission-controllers/#write-an-admission-webhook-server) for -instructions if you intend to write/deploy production-grade admission webhooks. +write and deploy them with great caution. Please read the +[user guides](/docs/reference/access-authn-authz/extensible-admission-controllers/#write-an-admission-webhook-server) +for instructions if you intend to write/deploy production-grade admission webhooks. In the following, we describe how to quickly experiment with admission webhooks. ### Prerequisites -* Ensure that the Kubernetes cluster is at least as new as v1.16 (to use `admissionregistration.k8s.io/v1`), - or v1.9 (to use `admissionregistration.k8s.io/v1beta1`). - * Ensure that MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controllers are enabled. [Here](/docs/reference/access-authn-authz/admission-controllers/#is-there-a-recommended-set-of-admission-controllers-to-use) is a recommended set of admission controllers to enable in general. -* Ensure that the `admissionregistration.k8s.io/v1` or `admissionregistration.k8s.io/v1beta1` API is enabled. +* Ensure that the `admissionregistration.k8s.io/v1` API is enabled. ### Write an admission webhook server -Please refer to the implementation of the [admission webhook -server](https://github.com/kubernetes/kubernetes/blob/release-1.21/test/images/agnhost/webhook/main.go) +Please refer to the implementation of the [admission webhook server](https://github.com/kubernetes/kubernetes/blob/release-1.21/test/images/agnhost/webhook/main.go) that is validated in a Kubernetes e2e test. The webhook handles the -`AdmissionReview` request sent by the apiservers, and sends back its decision +`AdmissionReview` request sent by the API servers, and sends back its decision as an `AdmissionReview` object in the same version it received. See the [webhook request](#request) section for details on the data sent to webhooks. @@ -69,9 +65,9 @@ See the [webhook response](#response) section for the data expected from webhook The example admission webhook server leaves the `ClientAuth` field [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 +authenticate the identity of the clients, supposedly API servers. If you need mutual TLS or other ways to authenticate the clients, see -how to [authenticate apiservers](#authenticate-apiservers). +how to [authenticate API servers](#authenticate-apiservers). ### Deploy the admission webhook service @@ -95,8 +91,6 @@ or The following is an example `ValidatingWebhookConfiguration`, a mutating webhook configuration is similar. See the [webhook configuration](#webhook-configuration) section for details about each config field. -{{< tabs name="ValidatingWebhookConfiguration_example_1" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration @@ -114,39 +108,18 @@ webhooks: service: namespace: "example-namespace" name: "example-service" - caBundle: "Ci0tLS0tQk...<`caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate.>...tLS0K" - admissionReviewVersions: ["v1", "v1beta1"] + caBundle: + admissionReviewVersions: ["v1"] sideEffects: None timeoutSeconds: 5 ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -metadata: - name: "pod-policy.example.com" -webhooks: -- name: "pod-policy.example.com" - rules: - - apiGroups: [""] - apiVersions: ["v1"] - operations: ["CREATE"] - resources: ["pods"] - scope: "Namespaced" - clientConfig: - service: - namespace: "example-namespace" - name: "example-service" - caBundle: "Ci0tLS0tQk...<`caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate>...tLS0K" - admissionReviewVersions: ["v1beta1"] - timeoutSeconds: 5 -``` -{{% /tab %}} -{{< /tabs >}} -The scope field specifies if only cluster-scoped resources ("Cluster") or namespace-scoped +{{< note >}} +You must replace the `` in the above example by a valid CA bundle +which is a PEM-encoded CA bundle for validating the webhook's server certificate. +{{< /note >}} + +The `scope` field specifies if only cluster-scoped resources ("Cluster") or namespace-scoped resources ("Namespaced") will match this rule. "∗" means that there are no scope restrictions. {{< note >}} @@ -155,27 +128,26 @@ When using `clientConfig.service`, the server cert must be valid for {{< /note >}} {{< note >}} -Default timeout for a webhook call is 10 seconds for webhooks registered created using `admissionregistration.k8s.io/v1`, -and 30 seconds for webhooks created using `admissionregistration.k8s.io/v1beta1`. Starting in kubernetes 1.14 you -can set the timeout and it is encouraged to use a small timeout for webhooks. +Default timeout for a webhook call is 10 seconds, +You can set the `timeout` and it is encouraged to use a short timeout for webhooks. If the webhook call times out, the request is handled according to the webhook's failure policy. {{< /note >}} -When an apiserver receives a request that matches one of the `rules`, the -apiserver sends an `admissionReview` request to webhook as specified in the +When an API server receives a request that matches one of the `rules`, the +API server sends an `admissionReview` request to webhook as specified in the `clientConfig`. After you create the webhook configuration, the system will take a few seconds to honor the new configuration. -### Authenticate apiservers +### Authenticate API servers {#authenticate-apiservers} If your admission webhooks require authentication, you can configure the -apiservers to use basic auth, bearer token, or a cert to authenticate itself to +API servers to use basic auth, bearer token, or a cert to authenticate itself to the webhooks. There are three steps to complete the configuration. -* When starting the apiserver, specify the location of the admission control +* When starting the API server, specify the location of the admission control configuration file via the `--admission-control-config-file` flag. * In the admission control configuration file, specify where the @@ -228,55 +200,55 @@ For more information about `AdmissionConfiguration`, see the [AdmissionConfiguration (v1) reference](/docs/reference/config-api/apiserver-webhookadmission.v1/). See the [webhook configuration](#webhook-configuration) section for details about each config field. -* In the kubeConfig file, provide the credentials: +In the kubeConfig file, provide the credentials: - ```yaml - apiVersion: v1 - kind: Config - users: - # name should be set to the DNS name of the service or the host (including port) of the URL the webhook is configured to speak to. - # If a non-443 port is used for services, it must be included in the name when configuring 1.16+ API servers. - # - # For a webhook configured to speak to a service on the default port (443), specify the DNS name of the service: - # - name: webhook1.ns1.svc - # user: ... - # - # For a webhook configured to speak to a service on non-default port (e.g. 8443), specify the DNS name and port of the service in 1.16+: - # - name: webhook1.ns1.svc:8443 - # user: ... - # and optionally create a second stanza using only the DNS name of the service for compatibility with 1.15 API servers: - # - name: webhook1.ns1.svc - # user: ... - # - # For webhooks configured to speak to a URL, match the host (and port) specified in the webhook's URL. Examples: - # A webhook with `url: https://www.example.com`: - # - name: www.example.com - # user: ... - # - # A webhook with `url: https://www.example.com:443`: - # - name: www.example.com:443 - # user: ... - # - # A webhook with `url: https://www.example.com:8443`: - # - name: www.example.com:8443 - # user: ... - # - - name: 'webhook1.ns1.svc' - user: - client-certificate-data: "" - client-key-data: "" - # The `name` supports using * to wildcard-match prefixing segments. - - name: '*.webhook-company.org' - user: - password: "" - username: "" - # '*' is the default match. - - name: '*' - user: - token: "" - ``` +```yaml +apiVersion: v1 +kind: Config +users: +# name should be set to the DNS name of the service or the host (including port) of the URL the webhook is configured to speak to. +# If a non-443 port is used for services, it must be included in the name when configuring 1.16+ API servers. +# +# For a webhook configured to speak to a service on the default port (443), specify the DNS name of the service: +# - name: webhook1.ns1.svc +# user: ... +# +# For a webhook configured to speak to a service on non-default port (e.g. 8443), specify the DNS name and port of the service in 1.16+: +# - name: webhook1.ns1.svc:8443 +# user: ... +# and optionally create a second stanza using only the DNS name of the service for compatibility with 1.15 API servers: +# - name: webhook1.ns1.svc +# user: ... +# +# For webhooks configured to speak to a URL, match the host (and port) specified in the webhook's URL. Examples: +# A webhook with `url: https://www.example.com`: +# - name: www.example.com +# user: ... +# +# A webhook with `url: https://www.example.com:443`: +# - name: www.example.com:443 +# user: ... +# +# A webhook with `url: https://www.example.com:8443`: +# - name: www.example.com:8443 +# user: ... +# +- name: 'webhook1.ns1.svc' + user: + client-certificate-data: "" + client-key-data: "" +# The `name` supports using * to wildcard-match prefixing segments. +- name: '*.webhook-company.org' + user: + password: "" + username: "" +# '*' is the default match. +- name: '*' + user: + token: "" +``` -Of course you need to set up the webhook server to handle these authentications. +Of course you need to set up the webhook server to handle these authentication requests. ## Webhook request and response @@ -289,39 +261,17 @@ serialized to JSON as the body. Webhooks can specify what versions of `AdmissionReview` objects they accept with the `admissionReviewVersions` field in their configuration: -{{< tabs name="ValidatingWebhookConfiguration_admissionReviewVersions" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com admissionReviewVersions: ["v1", "v1beta1"] - ... ``` -`admissionReviewVersions` is a required field when creating -`admissionregistration.k8s.io/v1` webhook configurations. +`admissionReviewVersions` is a required field when creating webhook configurations. Webhooks are required to support at least one `AdmissionReview` version understood by the current and previous API server. -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - admissionReviewVersions: ["v1beta1"] - ... -``` - -If no `admissionReviewVersions` are specified, the default when creating -`admissionregistration.k8s.io/v1beta1` webhook configurations is `v1beta1`. -{{% /tab %}} -{{< /tabs >}} API servers send the first `AdmissionReview` version in the `admissionReviewVersions` list they support. If none of the versions in the list are supported by the API server, the configuration will not be allowed to be created. @@ -331,154 +281,100 @@ versions the API server knows how to send, attempts to call to the webhook will This example shows the data contained in an `AdmissionReview` object for a request to update the `scale` subresource of an `apps/v1` `Deployment`: - -{{< tabs name="AdmissionReview_request" >}} -{{% tab name="admission.k8s.io/v1" %}} ```yaml -{ - "apiVersion": "admission.k8s.io/v1", - "kind": "AdmissionReview", - "request": { - # Random uid uniquely identifying this admission call - "uid": "705ab4f5-6393-11e8-b7cc-42010a800002", +apiVersion: admission.k8s.io/v1 +kind: AdmissionReview +request: + # Random uid uniquely identifying this admission call + uid: 705ab4f5-6393-11e8-b7cc-42010a800002 - # Fully-qualified group/version/kind of the incoming object - "kind": {"group":"autoscaling","version":"v1","kind":"Scale"}, - # Fully-qualified group/version/kind of the resource being modified - "resource": {"group":"apps","version":"v1","resource":"deployments"}, - # subresource, if the request is to a subresource - "subResource": "scale", + # Fully-qualified group/version/kind of the incoming object + kind: + group: autoscaling + version: v1 + kind: Scale - # Fully-qualified group/version/kind of the incoming object in the original request to the API server. - # This only differs from `kind` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - "requestKind": {"group":"autoscaling","version":"v1","kind":"Scale"}, - # Fully-qualified group/version/kind of the resource being modified in the original request to the API server. - # This only differs from `resource` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - "requestResource": {"group":"apps","version":"v1","resource":"deployments"}, - # subresource, if the request is to a subresource - # This only differs from `subResource` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - "requestSubResource": "scale", + # Fully-qualified group/version/kind of the resource being modified + resource: + group: apps + version: v1 + resource: deployments - # Name of the resource being modified - "name": "my-deployment", - # Namespace of the resource being modified, if the resource is namespaced (or is a Namespace object) - "namespace": "my-namespace", + # subresource, if the request is to a subresource + subResource: scale - # operation can be CREATE, UPDATE, DELETE, or CONNECT - "operation": "UPDATE", + # Fully-qualified group/version/kind of the incoming object in the original request to the API server. + # This only differs from `kind` if the webhook specified `matchPolicy: Equivalent` and the + # original request to the API server was converted to a version the webhook registered for. + requestKind: + group: autoscaling + version: v1 + kind: Scale - "userInfo": { - # Username of the authenticated user making the request to the API server - "username": "admin", - # UID of the authenticated user making the request to the API server - "uid": "014fbff9a07c", - # Group memberships of the authenticated user making the request to the API server - "groups": ["system:authenticated","my-admin-group"], - # Arbitrary extra info associated with the user making the request to the API server. - # This is populated by the API server authentication layer and should be included - # if any SubjectAccessReview checks are performed by the webhook. - "extra": { - "some-key":["some-value1", "some-value2"] - } - }, + # Fully-qualified group/version/kind of the resource being modified in the original request to the API server. + # This only differs from `resource` if the webhook specified `matchPolicy: Equivalent` and the + # original request to the API server was converted to a version the webhook registered for. + requestResource: + group: apps + version: v1 + resource: deployments - # object is the new object being admitted. - # It is null for DELETE operations. - "object": {"apiVersion":"autoscaling/v1","kind":"Scale",...}, - # oldObject is the existing object. - # It is null for CREATE and CONNECT operations. - "oldObject": {"apiVersion":"autoscaling/v1","kind":"Scale",...}, - # options contains the options for the operation being admitted, like meta.k8s.io/v1 CreateOptions, UpdateOptions, or DeleteOptions. - # It is null for CONNECT operations. - "options": {"apiVersion":"meta.k8s.io/v1","kind":"UpdateOptions",...}, + # subresource, if the request is to a subresource + # This only differs from `subResource` if the webhook specified `matchPolicy: Equivalent` and the + # original request to the API server was converted to a version the webhook registered for. + requestSubResource: scale - # dryRun indicates the API request is running in dry run mode and will not be persisted. - # Webhooks with side effects should avoid actuating those side effects when dryRun is true. - # See http://k8s.io/docs/reference/using-api/api-concepts/#make-a-dry-run-request for more details. - "dryRun": false - } -} + # Name of the resource being modified + name: my-deployment + + # Namespace of the resource being modified, if the resource is namespaced (or is a Namespace object) + namespace: my-namespace + + # operation can be CREATE, UPDATE, DELETE, or CONNECT + operation: UPDATE + + userInfo: + # Username of the authenticated user making the request to the API server + username: admin + + # UID of the authenticated user making the request to the API server + uid: 014fbff9a07c + + # Group memberships of the authenticated user making the request to the API server + groups: + - system:authenticated + - my-admin-group + # Arbitrary extra info associated with the user making the request to the API server. + # This is populated by the API server authentication layer and should be included + # if any SubjectAccessReview checks are performed by the webhook. + extra: + some-key: + - some-value1 + - some-value2 + + # object is the new object being admitted. + # It is null for DELETE operations. + object: + apiVersion: autoscaling/v1 + kind: Scale + + # oldObject is the existing object. + # It is null for CREATE and CONNECT operations. + oldObject: + apiVersion: autoscaling/v1 + kind: Scale + + # options contains the options for the operation being admitted, like meta.k8s.io/v1 CreateOptions, UpdateOptions, or DeleteOptions. + # It is null for CONNECT operations. + options: + apiVersion: meta.k8s.io/v1 + kind: UpdateOptions + + # dryRun indicates the API request is running in dry run mode and will not be persisted. + # Webhooks with side effects should avoid actuating those side effects when dryRun is true. + # See http://k8s.io/docs/reference/using-api/api-concepts/#make-a-dry-run-request for more details. + dryRun: False ``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```yaml -{ - # Deprecated in v1.16 in favor of admission.k8s.io/v1 - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "request": { - # Random uid uniquely identifying this admission call - "uid": "705ab4f5-6393-11e8-b7cc-42010a800002", - - # Fully-qualified group/version/kind of the incoming object - "kind": {"group":"autoscaling","version":"v1","kind":"Scale"}, - # Fully-qualified group/version/kind of the resource being modified - "resource": {"group":"apps","version":"v1","resource":"deployments"}, - # subresource, if the request is to a subresource - "subResource": "scale", - - # Fully-qualified group/version/kind of the incoming object in the original request to the API server. - # This only differs from `kind` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - # Only sent by v1.15+ API servers. - "requestKind": {"group":"autoscaling","version":"v1","kind":"Scale"}, - # Fully-qualified group/version/kind of the resource being modified in the original request to the API server. - # This only differs from `resource` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - # Only sent by v1.15+ API servers. - "requestResource": {"group":"apps","version":"v1","resource":"deployments"}, - # subresource, if the request is to a subresource - # This only differs from `subResource` if the webhook specified `matchPolicy: Equivalent` and the - # original request to the API server was converted to a version the webhook registered for. - # Only sent by v1.15+ API servers. - "requestSubResource": "scale", - - # Name of the resource being modified - "name": "my-deployment", - # Namespace of the resource being modified, if the resource is namespaced (or is a Namespace object) - "namespace": "my-namespace", - - # operation can be CREATE, UPDATE, DELETE, or CONNECT - "operation": "UPDATE", - - "userInfo": { - # Username of the authenticated user making the request to the API server - "username": "admin", - # UID of the authenticated user making the request to the API server - "uid": "014fbff9a07c", - # Group memberships of the authenticated user making the request to the API server - "groups": ["system:authenticated","my-admin-group"], - # Arbitrary extra info associated with the user making the request to the API server. - # This is populated by the API server authentication layer and should be included - # if any SubjectAccessReview checks are performed by the webhook. - "extra": { - "some-key":["some-value1", "some-value2"] - } - }, - - # object is the new object being admitted. - # It is null for DELETE operations. - "object": {"apiVersion":"autoscaling/v1","kind":"Scale",...}, - # oldObject is the existing object. - # It is null for CREATE and CONNECT operations (and for DELETE operations in API servers prior to v1.15.0) - "oldObject": {"apiVersion":"autoscaling/v1","kind":"Scale",...}, - # options contains the options for the operation being admitted, like meta.k8s.io/v1 CreateOptions, UpdateOptions, or DeleteOptions. - # It is null for CONNECT operations. - # Only sent by v1.15+ API servers. - "options": {"apiVersion":"meta.k8s.io/v1","kind":"UpdateOptions",...}, - - # dryRun indicates the API request is running in dry run mode and will not be persisted. - # Webhooks with side effects should avoid actuating those side effects when dryRun is true. - # See http://k8s.io/docs/reference/using-api/api-concepts/#make-a-dry-run-request for more details. - "dryRun": false - } -} -``` -{{% /tab %}} -{{< /tabs >}} ### Response @@ -492,8 +388,7 @@ At a minimum, the `response` stanza must contain the following fields: * `allowed`, either set to `true` or `false` Example of a minimal response from a webhook to allow a request: -{{< tabs name="AdmissionReview_response_allow" >}} -{{% tab name="admission.k8s.io/v1" %}} + ```json { "apiVersion": "admission.k8s.io/v1", @@ -504,55 +399,26 @@ Example of a minimal response from a webhook to allow a request: } } ``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": true - } -} -``` -{{% /tab %}} -{{< /tabs >}} Example of a minimal response from a webhook to forbid a request: -{{< tabs name="AdmissionReview_response_forbid_minimal" >}} -{{% tab name="admission.k8s.io/v1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": false - } -} -``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": false - } -} -``` -{{% /tab %}} -{{< /tabs >}} -When rejecting a request, the webhook can customize the http code and message returned to the user using the `status` field. -The specified status object is returned to the user. -See the [API documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#status-v1-meta) for details about the status type. +```json +{ + "apiVersion": "admission.k8s.io/v1", + "kind": "AdmissionReview", + "response": { + "uid": "", + "allowed": false + } +} +``` + +When rejecting a request, the webhook can customize the http code and message returned to the user +using the `status` field. The specified status object is returned to the user. +See the [API documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#status-v1-meta) +for details about the `status` type. Example of a response to forbid a request, customizing the HTTP status code and message presented to the user: -{{< tabs name="AdmissionReview_response_forbid_details" >}} -{{% tab name="admission.k8s.io/v1" %}} + ```json { "apiVersion": "admission.k8s.io/v1", @@ -567,24 +433,6 @@ Example of a response to forbid a request, customizing the HTTP status code and } } ``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": false, - "status": { - "code": 403, - "message": "You cannot do this because it is Tuesday and your name starts with A" - } - } -} -``` -{{% /tab %}} -{{< /tabs >}} When allowing a request, a mutating admission webhook may optionally modify the incoming object as well. This is done using the `patch` and `patchType` fields in the response. @@ -592,13 +440,13 @@ The only currently supported `patchType` is `JSONPatch`. See [JSON patch](https://jsonpatch.com/) documentation for more details. For `patchType: JSONPatch`, the `patch` field contains a base64-encoded array of JSON patch operations. -As an example, a single patch operation that would set `spec.replicas` would be `[{"op": "add", "path": "/spec/replicas", "value": 3}]` +As an example, a single patch operation that would set `spec.replicas` would be +`[{"op": "add", "path": "/spec/replicas", "value": 3}]` Base64-encoded, this would be `W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0=` So a webhook response to add that label would be: -{{< tabs name="AdmissionReview_response_modify" >}} -{{% tab name="admission.k8s.io/v1" %}} + ```json { "apiVersion": "admission.k8s.io/v1", @@ -611,27 +459,12 @@ So a webhook response to add that label would be: } } ``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": true, - "patchType": "JSONPatch", - "patch": "W3sib3AiOiAiYWRkIiwgInBhdGgiOiAiL3NwZWMvcmVwbGljYXMiLCAidmFsdWUiOiAzfV0=" - } -} -``` -{{% /tab %}} -{{< /tabs >}} -Starting in v1.19, admission webhooks can optionally return warning messages that are returned to the requesting client +Admission webhooks can optionally return warning messages that are returned to the requesting client in HTTP `Warning` headers with a warning code of 299. Warnings can be sent with allowed or rejected admission responses. If you're implementing a webhook that returns a warning: + * Don't include a "Warning:" prefix in the message * Use warning messages to describe problems the client making the API request should correct or be aware of * Limit warnings to 120 characters if possible @@ -641,8 +474,6 @@ Individual warning messages over 256 characters may be truncated by the API serv If more than 4096 characters of warning messages are added (from all sources), additional warning messages are ignored. {{< /caution >}} -{{< tabs name="AdmissionReview_response_warning" >}} -{{% tab name="admission.k8s.io/v1" %}} ```json { "apiVersion": "admission.k8s.io/v1", @@ -657,24 +488,6 @@ If more than 4096 characters of warning messages are added (from all sources), a } } ``` -{{% /tab %}} -{{% tab name="admission.k8s.io/v1beta1" %}} -```json -{ - "apiVersion": "admission.k8s.io/v1beta1", - "kind": "AdmissionReview", - "response": { - "uid": "", - "allowed": true, - "warnings": [ - "duplicate envvar entries specified with name MY_ENV", - "memory request less than 4MB specified for container mycontainer, which will not start successfully" - ] - } -} -``` -{{% /tab %}} -{{< /tabs >}} ## Webhook configuration @@ -683,9 +496,9 @@ The name of a `MutatingWebhookConfiguration` or a `ValidatingWebhookConfiguratio [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). Each configuration can contain one or more webhooks. -If multiple webhooks are specified in a single configuration, each should be given a unique name. -This is required in `admissionregistration.k8s.io/v1`, but strongly recommended when using `admissionregistration.k8s.io/v1beta1`, -in order to make resulting audit logs and metrics easier to match up to active configurations. +If multiple webhooks are specified in a single configuration, each must be given a unique name. +This is required in order to make resulting audit logs and metrics easier to match up to active +configurations. Each webhook defines the following things. @@ -694,27 +507,31 @@ Each webhook defines the following things. Each webhook must specify a list of rules used to determine if a request to the API server should be sent to the webhook. Each rule specifies one or more operations, apiGroups, apiVersions, and resources, and a resource scope: -* `operations` lists one or more operations to match. Can be `"CREATE"`, `"UPDATE"`, `"DELETE"`, `"CONNECT"`, or `"*"` to match all. +* `operations` lists one or more operations to match. Can be `"CREATE"`, `"UPDATE"`, `"DELETE"`, `"CONNECT"`, + or `"*"` to match all. * `apiGroups` lists one or more API groups to match. `""` is the core API group. `"*"` matches all API groups. * `apiVersions` lists one or more API versions to match. `"*"` matches all API versions. * `resources` lists one or more resources to match. - * `"*"` matches all resources, but not subresources. - * `"*/*"` matches all resources and subresources. - * `"pods/*"` matches all subresources of pods. - * `"*/status"` matches all status subresources. -* `scope` specifies a scope to match. Valid values are `"Cluster"`, `"Namespaced"`, and `"*"`. Subresources match the scope of their parent resource. Supported in v1.14+. Default is `"*"`, matching pre-1.14 behavior. - * `"Cluster"` means that only cluster-scoped resources will match this rule (Namespace API objects are cluster-scoped). - * `"Namespaced"` means that only namespaced resources will match this rule. - * `"*"` means that there are no scope restrictions. -If an incoming request matches one of the specified operations, groups, versions, resources, and scope for any of a webhook's rules, the request is sent to the webhook. + * `"*"` matches all resources, but not subresources. + * `"*/*"` matches all resources and subresources. + * `"pods/*"` matches all subresources of pods. + * `"*/status"` matches all status subresources. + +* `scope` specifies a scope to match. Valid values are `"Cluster"`, `"Namespaced"`, and `"*"`. + Subresources match the scope of their parent resource. Default is `"*"`. + + * `"Cluster"` means that only cluster-scoped resources will match this rule (Namespace API objects are cluster-scoped). + * `"Namespaced"` means that only namespaced resources will match this rule. + * `"*"` means that there are no scope restrictions. + +If an incoming request matches one of the specified `operations`, `groups`, `versions`, +`resources`, and `scope` for any of a webhook's `rules`, the request is sent to the webhook. Here are other examples of rules that could be used to specify which resources should be intercepted. Match `CREATE` or `UPDATE` requests to `apps/v1` and `apps/v1beta1` `deployments` and `replicasets`: -{{< tabs name="ValidatingWebhookConfiguration_rules_1" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration @@ -729,123 +546,56 @@ webhooks: scope: "Namespaced" ... ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - rules: - - operations: ["CREATE", "UPDATE"] - apiGroups: ["apps"] - apiVersions: ["v1", "v1beta1"] - resources: ["deployments", "replicasets"] - scope: "Namespaced" - ... -``` -{{% /tab %}} -{{< /tabs >}} Match create requests for all resources (but not subresources) in all API groups and versions: -{{< tabs name="ValidatingWebhookConfiguration_rules_2" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "*" - ... + - name: my-webhook.example.com + rules: + - operations: ["CREATE"] + apiGroups: ["*"] + apiVersions: ["*"] + resources: ["*"] + scope: "*" ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "*" - ... -``` -{{% /tab %}} -{{< /tabs >}} Match update requests for all `status` subresources in all API groups and versions: -{{< tabs name="ValidatingWebhookConfiguration_rules_3" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - rules: - - operations: ["UPDATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*/status"] - scope: "*" - ... + - name: my-webhook.example.com + rules: + - operations: ["UPDATE"] + apiGroups: ["*"] + apiVersions: ["*"] + resources: ["*/status"] + scope: "*" ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - rules: - - operations: ["UPDATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*/status"] - scope: "*" - ... -``` -{{% /tab %}} -{{< /tabs >}} ### Matching requests: objectSelector -In v1.15+, webhooks may optionally limit which requests are intercepted based on the labels of the +Webhooks may optionally limit which requests are intercepted based on the labels of the objects they would be sent, by specifying an `objectSelector`. If specified, the objectSelector is evaluated against both the object and oldObject that would be sent to the webhook, and is considered to match if either object matches the selector. -A null object (oldObject in the case of create, or newObject in the case of delete), +A null object (`oldObject` in the case of create, or `newObject` in the case of delete), or an object that cannot have labels (like a `DeploymentRollback` or a `PodProxyOptions` object) is not considered to match. -Use the object selector only if the webhook is opt-in, because end users may skip the admission webhook by setting the labels. +Use the object selector only if the webhook is opt-in, because end users may skip +the admission webhook by setting the labels. This example shows a mutating webhook that would match a `CREATE` of any resource with the label `foo: bar`: -{{< tabs name="objectSelector_example" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com objectSelector: @@ -857,32 +607,10 @@ webhooks: apiVersions: ["*"] resources: ["*"] scope: "*" - ... ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - objectSelector: - matchLabels: - foo: bar - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "*" - ... -``` -{{% /tab %}} -{{< /tabs >}} -See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels for more examples of label selectors. +See [labels concept](/docs/concepts/overview/working-with-objects/labels) +for more examples of label selectors. ### Matching requests: namespaceSelector @@ -897,128 +625,75 @@ If the object is a cluster scoped resource other than a Namespace, `namespaceSel This example shows a mutating webhook that matches a `CREATE` of any namespaced resource inside a namespace that does not have a "runlevel" label of "0" or "1": -{{< tabs name="MutatingWebhookConfiguration_namespaceSelector_1" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - namespaceSelector: - matchExpressions: - - key: runlevel - operator: NotIn - values: ["0","1"] - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "Namespaced" - ... + - name: my-webhook.example.com + namespaceSelector: + matchExpressions: + - key: runlevel + operator: NotIn + values: ["0","1"] + rules: + - operations: ["CREATE"] + apiGroups: ["*"] + apiVersions: ["*"] + resources: ["*"] + scope: "Namespaced" ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - namespaceSelector: - matchExpressions: - - key: runlevel - operator: NotIn - values: ["0","1"] - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "Namespaced" - ... -``` -{{% /tab %}} -{{< /tabs >}} -This example shows a validating webhook that matches a `CREATE` of any namespaced resource inside a namespace -that is associated with the "environment" of "prod" or "staging": +This example shows a validating webhook that matches a `CREATE` of any namespaced resource inside +a namespace that is associated with the "environment" of "prod" or "staging": -{{< tabs name="ValidatingWebhookConfiguration_namespaceSelector_2" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - namespaceSelector: - matchExpressions: - - key: environment - operator: In - values: ["prod","staging"] - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "Namespaced" - ... + - name: my-webhook.example.com + namespaceSelector: + matchExpressions: + - key: environment + operator: In + values: ["prod","staging"] + rules: + - operations: ["CREATE"] + apiGroups: ["*"] + apiVersions: ["*"] + resources: ["*"] + scope: "Namespaced" ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - namespaceSelector: - matchExpressions: - - key: environment - operator: In - values: ["prod","staging"] - rules: - - operations: ["CREATE"] - apiGroups: ["*"] - apiVersions: ["*"] - resources: ["*"] - scope: "Namespaced" - ... -``` -{{% /tab %}} -{{< /tabs >}} -See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels for more examples of label selectors. +See [labels concept](/docs/concepts/overview/working-with-objects/labels) +for more examples of label selectors. ### Matching requests: matchPolicy API servers can make objects available via multiple API groups or versions. -For example, the Kubernetes API server may allow creating and modifying `Deployment` objects -via `extensions/v1beta1`, `apps/v1beta1`, `apps/v1beta2`, and `apps/v1` APIs. -For example, if a webhook only specified a rule for some API groups/versions (like `apiGroups:["apps"], apiVersions:["v1","v1beta1"]`), +For example, if a webhook only specified a rule for some API groups/versions +(like `apiGroups:["apps"], apiVersions:["v1","v1beta1"]`), and a request was made to modify the resource via another API group/version (like `extensions/v1beta1`), the request would not be sent to the webhook. -In v1.15+, `matchPolicy` lets a webhook define how its `rules` are used to match incoming requests. +The `matchPolicy` lets a webhook define how its `rules` are used to match incoming requests. Allowed values are `Exact` or `Equivalent`. * `Exact` means a request should be intercepted only if it exactly matches a specified rule. -* `Equivalent` means a request should be intercepted if modifies a resource listed in `rules`, even via another API group or version. +* `Equivalent` means a request should be intercepted if modifies a resource listed in `rules`, + even via another API group or version. In the example given above, the webhook that only registered for `apps/v1` could use `matchPolicy`: * `matchPolicy: Exact` would mean the `extensions/v1beta1` request would not be sent to the webhook -* `matchPolicy: Equivalent` means the `extensions/v1beta1` request would be sent to the webhook (with the objects converted to a version the webhook had specified: `apps/v1`) +* `matchPolicy: Equivalent` means the `extensions/v1beta1` request would be sent to the webhook + (with the objects converted to a version the webhook had specified: `apps/v1`) Specifying `Equivalent` is recommended, and ensures that webhooks continue to intercept the resources they expect when upgrades enable new versions of the resource in the API server. -When a resource stops being served by the API server, it is no longer considered equivalent to other versions of that resource that are still served. +When a resource stops being served by the API server, it is no longer considered equivalent to +other versions of that resource that are still served. For example, `extensions/v1beta1` deployments were first deprecated and then removed (in Kubernetes v1.16). Since that removal, a webhook with a `apiGroups:["extensions"], apiVersions:["v1beta1"], resources:["deployments"]` rule @@ -1028,12 +703,9 @@ for stable versions of resources. This example shows a validating webhook that intercepts modifications to deployments (no matter the API group or version), and is always sent an `apps/v1` `Deployment` object: -{{< tabs name="ValidatingWebhookConfiguration_matchPolicy" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com matchPolicy: Equivalent @@ -1043,32 +715,9 @@ webhooks: apiVersions: ["v1"] resources: ["deployments"] scope: "Namespaced" - ... ``` -Admission webhooks created using `admissionregistration.k8s.io/v1` default to `Equivalent`. -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - matchPolicy: Equivalent - rules: - - operations: ["CREATE","UPDATE","DELETE"] - apiGroups: ["apps"] - apiVersions: ["v1"] - resources: ["deployments"] - scope: "Namespaced" - ... -``` - -Admission webhooks created using `admissionregistration.k8s.io/v1beta1` default to `Exact`. -{{% /tab %}} -{{< /tabs >}} +The `matchPolicy` for an admission webhooks defaults to `Equivalent`. ### Contacting the webhook @@ -1086,51 +735,32 @@ and can optionally include a custom CA bundle to use to verify the TLS connectio The `host` should not refer to a service running in the cluster; use a service reference by specifying the `service` field instead. -The host might be resolved via external DNS in some apiservers +The host might be resolved via external DNS in some API servers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts -which run an apiserver which might need to make calls to this +which run an API server which might need to make calls to this webhook. Such installations are likely to be non-portable or not readily run in a new cluster. The scheme must be "https"; the URL must begin with "https://". -Attempting to use a user or basic auth (for example "user:password@") is not allowed. -Fragments ("#...") and query parameters ("?...") are also not allowed. +Attempting to use a user or basic auth (for example `user:password@`) is not allowed. +Fragments (`#...`) and query parameters (`?...`) are also not allowed. Here is an example of a mutating webhook configured to call a URL (and expects the TLS certificate to be verified using system trust roots, so does not specify a caBundle): -{{< tabs name="MutatingWebhookConfiguration_url" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com clientConfig: url: "https://my-webhook.example.com:9443/my-webhook-path" - ... ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - clientConfig: - url: "https://my-webhook.example.com:9443/my-webhook-path" - ... -``` -{{% /tab %}} -{{< /tabs >}} #### Service reference @@ -1143,43 +773,24 @@ Here is an example of a mutating webhook configured to call a service on port "1 at the subpath "/my-path", and to verify the TLS connection against the ServerName `my-service-name.my-service-namespace.svc` using a custom CA bundle: -{{< tabs name="MutatingWebhookConfiguration_service" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com clientConfig: - caBundle: "Ci0tLS0tQk......tLS0K" + caBundle: service: namespace: my-service-namespace name: my-service-name path: /my-path port: 1234 - ... ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - clientConfig: - caBundle: "Ci0tLS0tQk...<`caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate>...tLS0K" - service: - namespace: my-service-namespace - name: my-service-name - path: /my-path - port: 1234 - ... -``` -{{% /tab %}} -{{< /tabs >}} + +{{< note >}} +You must replace the `` in the above example by a valid CA bundle +which is a PEM-encoded CA bundle for validating the webhook's server certificate. +{{< /note >}} ### Side effects @@ -1199,46 +810,20 @@ or the dry-run request will not be sent to the webhook and the API request will Webhooks indicate whether they have side effects using the `sideEffects` field in the webhook configuration: -* `Unknown`: no information is known about the side effects of calling the webhook. -If a request with `dryRun: true` would trigger a call to this webhook, the request will instead fail, and the webhook will not be called. * `None`: calling the webhook will have no side effects. -* `Some`: calling the webhook will possibly have side effects. -If a request with the dry-run attribute would trigger a call to this webhook, the request will instead fail, and the webhook will not be called. -* `NoneOnDryRun`: calling the webhook will possibly have side effects, -but if a request with `dryRun: true` is sent to the webhook, the webhook will suppress the side effects (the webhook is `dryRun`-aware). - -Allowed values: - -* In `admissionregistration.k8s.io/v1beta1`, `sideEffects` may be set to `Unknown`, `None`, `Some`, or `NoneOnDryRun`, and defaults to `Unknown`. -* In `admissionregistration.k8s.io/v1`, `sideEffects` must be set to `None` or `NoneOnDryRun`. +* `NoneOnDryRun`: calling the webhook will possibly have side effects, but if a request with + `dryRun: true` is sent to the webhook, the webhook will suppress the side effects (the webhook + is `dryRun`-aware). Here is an example of a validating webhook indicating it has no side effects on `dryRun: true` requests: -{{< tabs name="ValidatingWebhookConfiguration_sideEffects" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - sideEffects: NoneOnDryRun - ... + - name: my-webhook.example.com + sideEffects: NoneOnDryRun ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - sideEffects: NoneOnDryRun - ... -``` -{{% /tab %}} -{{< /tabs >}} ### Timeouts @@ -1253,35 +838,15 @@ The timeout value must be between 1 and 30 seconds. Here is an example of a validating webhook with a custom timeout of 2 seconds: -{{< tabs name="ValidatingWebhookConfiguration_timeoutSeconds" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration -... webhooks: -- name: my-webhook.example.com - timeoutSeconds: 2 - ... + - name: my-webhook.example.com + timeoutSeconds: 2 ``` -Admission webhooks created using `admissionregistration.k8s.io/v1` default timeouts to 10 seconds. -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - timeoutSeconds: 2 - ... -``` - -Admission webhooks created using `admissionregistration.k8s.io/v1` default timeouts to 30 seconds. -{{% /tab %}} -{{< /tabs >}} +The timeout for an admission webhook defaults to 10 seconds. ### Reinvocation policy @@ -1290,50 +855,35 @@ A single ordering of mutating admissions plugins (including webhooks) does not w to the object (like adding a `container` to a `pod`), and other mutating plugins which have already run may have opinions on those new structures (like setting an `imagePullPolicy` on all containers). -In v1.15+, to allow mutating admission plugins to observe changes made by other plugins, +To allow mutating admission plugins to observe changes made by other plugins, built-in mutating admission plugins are re-run if a mutating webhook modifies an object, and mutating webhooks can specify a `reinvocationPolicy` to control whether they are reinvoked as well. `reinvocationPolicy` may be set to `Never` or `IfNeeded`. It defaults to `Never`. -* `Never`: the webhook must not be called more than once in a single admission evaluation +* `Never`: the webhook must not be called more than once in a single admission evaluation. * `IfNeeded`: the webhook may be called again as part of the admission evaluation if the object -being admitted is modified by other admission plugins after the initial webhook call. + being admitted is modified by other admission plugins after the initial webhook call. The important elements to note are: * The number of additional invocations is not guaranteed to be exactly one. -* If additional invocations result in further modifications to the object, webhooks are not guaranteed to be invoked again. +* If additional invocations result in further modifications to the object, webhooks are not + guaranteed to be invoked again. * Webhooks that use this option may be reordered to minimize the number of additional invocations. -* To validate an object after all mutations are guaranteed complete, use a validating admission webhook instead (recommended for webhooks with side-effects). +* To validate an object after all mutations are guaranteed complete, use a validating admission + webhook instead (recommended for webhooks with side-effects). -Here is an example of a mutating webhook opting into being re-invoked if later admission plugins modify the object: +Here is an example of a mutating webhook opting into being re-invoked if later admission plugins +modify the object: -{{< tabs name="MutatingWebhookConfiguration_reinvocationPolicy" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com reinvocationPolicy: IfNeeded - ... ``` -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - reinvocationPolicy: IfNeeded - ... -``` -{{% /tab %}} -{{< /tabs >}} Mutating webhooks must be [idempotent](#idempotence), able to successfully process an object they have already admitted and potentially modified. This is true for all mutating admission webhooks, since any change they can make @@ -1349,35 +899,15 @@ are handled. Allowed values are `Ignore` or `Fail`. Here is a mutating webhook configured to reject an API request if errors are encountered calling the admission webhook: -{{< tabs name="MutatingWebhookConfiguration_failurePolicy" >}} -{{% tab name="admissionregistration.k8s.io/v1" %}} ```yaml apiVersion: admissionregistration.k8s.io/v1 kind: MutatingWebhookConfiguration -... webhooks: - name: my-webhook.example.com failurePolicy: Fail - ... ``` -Admission webhooks created using `admissionregistration.k8s.io/v1` default `failurePolicy` to `Fail`. -{{% /tab %}} -{{% tab name="admissionregistration.k8s.io/v1beta1" %}} -```yaml -# Deprecated in v1.16 in favor of admissionregistration.k8s.io/v1 -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration -... -webhooks: -- name: my-webhook.example.com - failurePolicy: Fail - ... -``` - -Admission webhooks created using `admissionregistration.k8s.io/v1beta1` default `failurePolicy` to `Ignore`. -{{% /tab %}} -{{< /tabs >}} +The default `failurePolicy` for an admission webhooks is `Fail`. ## Monitoring admission webhooks @@ -1388,121 +918,123 @@ monitoring mechanisms help cluster admins to answer questions like: 2. What change did the mutating webhook applied to the object? -3. Which webhooks are frequently rejecting API requests? What's the reason for a - rejection? +3. Which webhooks are frequently rejecting API requests? What's the reason for a rejection? ### Mutating webhook auditing annotations Sometimes it's useful to know which mutating webhook mutated the object in a API request, and what change did the webhook apply. -In v1.16+, kube-apiserver performs [auditing](/docs/tasks/debug/debug-cluster/audit/) on each mutating webhook -invocation. Each invocation generates an auditing annotation -capturing if a request object is mutated by the invocation, and optionally generates an annotation capturing the applied -patch from the webhook admission response. The annotations are set in the audit event for given request on given stage of -its execution, which is then pre-processed according to a certain policy and written to a backend. +The Kubernetes API server performs [auditing](/docs/tasks/debug/debug-cluster/audit/) on each +mutating webhook invocation. Each invocation generates an auditing annotation +capturing if a request object is mutated by the invocation, and optionally generates an annotation +capturing the applied patch from the webhook admission response. The annotations are set in the +audit event for given request on given stage of its execution, which is then pre-processed +according to a certain policy and written to a backend. The audit level of a event determines which annotations get recorded: - At `Metadata` audit level or higher, an annotation with key -`mutation.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` gets logged with JSON payload indicating -a webhook gets invoked for given request and whether it mutated the object or not. + `mutation.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` gets logged with JSON + payload indicating a webhook gets invoked for given request and whether it mutated the object or not. -For example, the following annotation gets recorded for a webhook being reinvoked. The webhook is ordered the third in the -mutating webhook chain, and didn't mutated the request object during the invocation. + For example, the following annotation gets recorded for a webhook being reinvoked. The webhook is + ordered the third in the mutating webhook chain, and didn't mutated the request object during the + invocation. -```yaml -# the audit event recorded -{ - "kind": "Event", - "apiVersion": "audit.k8s.io/v1", - "annotations": { - "mutation.webhook.admission.k8s.io/round_1_index_2": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook.example.com\",\"mutated\": false}" - # other annotations - ... - } - # other fields - ... -} -``` + ```yaml + # the audit event recorded + { + "kind": "Event", + "apiVersion": "audit.k8s.io/v1", + "annotations": { + "mutation.webhook.admission.k8s.io/round_1_index_2": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook.example.com\",\"mutated\": false}" + # other annotations + ... + } + # other fields + ... + } + ``` + + ```yaml + # the annotation value deserialized + { + "configuration": "my-mutating-webhook-configuration.example.com", + "webhook": "my-webhook.example.com", + "mutated": false + } + ``` + + The following annotation gets recorded for a webhook being invoked in the first round. The webhook + is ordered the first in the mutating webhook chain, and mutated the request object during the + invocation. -```yaml -# the annotation value deserialized -{ - "configuration": "my-mutating-webhook-configuration.example.com", - "webhook": "my-webhook.example.com", - "mutated": false -} -``` - -The following annotation gets recorded for a webhook being invoked in the first round. The webhook is ordered the first in\ -the mutating webhook chain, and mutated the request object during the invocation. - -```yaml -# the audit event recorded -{ - "kind": "Event", - "apiVersion": "audit.k8s.io/v1", - "annotations": { - "mutation.webhook.admission.k8s.io/round_0_index_0": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"mutated\": true}" - # other annotations - ... - } - # other fields - ... -} -``` - -```yaml -# the annotation value deserialized -{ - "configuration": "my-mutating-webhook-configuration.example.com", - "webhook": "my-webhook-always-mutate.example.com", - "mutated": true -} -``` + ```yaml + # the audit event recorded + { + "kind": "Event", + "apiVersion": "audit.k8s.io/v1", + "annotations": { + "mutation.webhook.admission.k8s.io/round_0_index_0": "{\"configuration\":\"my-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"mutated\": true}" + # other annotations + ... + } + # other fields + ... + } + ``` + + ```yaml + # the annotation value deserialized + { + "configuration": "my-mutating-webhook-configuration.example.com", + "webhook": "my-webhook-always-mutate.example.com", + "mutated": true + } + ``` - At `Request` audit level or higher, an annotation with key -`patch.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` gets logged with JSON payload indicating -a webhook gets invoked for given request and what patch gets applied to the request object. + `patch.webhook.admission.k8s.io/round_{round idx}_index_{order idx}` gets logged with JSON payload indicating + a webhook gets invoked for given request and what patch gets applied to the request object. -For example, the following annotation gets recorded for a webhook being reinvoked. The webhook is ordered the fourth in the -mutating webhook chain, and responded with a JSON patch which got applied to the request object. - -```yaml -# the audit event recorded -{ - "kind": "Event", - "apiVersion": "audit.k8s.io/v1", - "annotations": { - "patch.webhook.admission.k8s.io/round_1_index_3": "{\"configuration\":\"my-other-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"patch\":[{\"op\":\"add\",\"path\":\"/data/mutation-stage\",\"value\":\"yes\"}],\"patchType\":\"JSONPatch\"}" - # other annotations - ... - } - # other fields - ... -} -``` - -```yaml -# the annotation value deserialized -{ - "configuration": "my-other-mutating-webhook-configuration.example.com", - "webhook": "my-webhook-always-mutate.example.com", - "patchType": "JSONPatch", - "patch": [ - { - "op": "add", - "path": "/data/mutation-stage", - "value": "yes" - } - ] -} -``` + For example, the following annotation gets recorded for a webhook being reinvoked. The webhook is ordered the fourth in the + mutating webhook chain, and responded with a JSON patch which got applied to the request object. + + ```yaml + # the audit event recorded + { + "kind": "Event", + "apiVersion": "audit.k8s.io/v1", + "annotations": { + "patch.webhook.admission.k8s.io/round_1_index_3": "{\"configuration\":\"my-other-mutating-webhook-configuration.example.com\",\"webhook\":\"my-webhook-always-mutate.example.com\",\"patch\":[{\"op\":\"add\",\"path\":\"/data/mutation-stage\",\"value\":\"yes\"}],\"patchType\":\"JSONPatch\"}" + # other annotations + ... + } + # other fields + ... + } + ``` + + ```yaml + # the annotation value deserialized + { + "configuration": "my-other-mutating-webhook-configuration.example.com", + "webhook": "my-webhook-always-mutate.example.com", + "patchType": "JSONPatch", + "patch": [ + { + "op": "add", + "path": "/data/mutation-stage", + "value": "yes" + } + ] + } + ``` ### Admission webhook metrics -Kube-apiserver exposes Prometheus metrics from the `/metrics` endpoint, which can be used for monitoring and +The API server exposes Prometheus metrics from the `/metrics` endpoint, which can be used for monitoring and diagnosing API server status. The following metrics record status related to admission webhooks. #### API server admission webhook rejection count @@ -1510,7 +1042,7 @@ diagnosing API server status. The following metrics record status related to adm Sometimes it's useful to know which admission webhooks are frequently rejecting API requests, and the reason for a rejection. -In v1.16+, kube-apiserver exposes a Prometheus counter metric recording admission webhook rejections. The +The API server exposes a Prometheus counter metric recording admission webhook rejections. The metrics are labelled to identify the causes of webhook rejection(s): - `name`: the name of the webhook that rejected a request. @@ -1519,11 +1051,13 @@ metrics are labelled to identify the causes of webhook rejection(s): - `type`: the admission webhook type, can be one of `admit` and `validating`. - `error_type`: identifies if an error occurred during the webhook invocation that caused the rejection. Its value can be one of: - - `calling_webhook_error`: unrecognized errors or timeout errors from the admission webhook happened and the - webhook's [Failure policy](#failure-policy) is set to `Fail`. - - `no_error`: no error occurred. The webhook rejected the request with `allowed: false` in the admission - response. The metrics label `rejection_code` records the `.status.code` set in the admission response. - - `apiserver_internal_error`: an API server internal error happened. + + - `calling_webhook_error`: unrecognized errors or timeout errors from the admission webhook happened and the + webhook's [Failure policy](#failure-policy) is set to `Fail`. + - `no_error`: no error occurred. The webhook rejected the request with `allowed: false` in the admission + response. The metrics label `rejection_code` records the `.status.code` set in the admission response. + - `apiserver_internal_error`: an API server internal error happened. + - `rejection_code`: the HTTP status code set in the admission response when a webhook rejected a request. @@ -1553,7 +1087,8 @@ the initial application. 2. For a `CREATE` pod request, if the field `.spec.containers[].resources.limits` of a container is not set, set default resource limits. -3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container with the name `foo-sidecar` already exists. +3. For a `CREATE` pod request, inject a sidecar container with name `foo-sidecar` if no container + with the name `foo-sidecar` already exists. In the cases above, the webhook can be safely reinvoked, or admit an object that already has the fields set. @@ -1587,21 +1122,25 @@ versions. See [Matching requests: matchPolicy](#matching-requests-matchpolicy) f ### Availability -It is recommended that admission webhooks should evaluate as quickly as possible (typically in milliseconds), since they add to API request latency. +It is recommended that admission webhooks should evaluate as quickly as possible (typically in +milliseconds), since they add to API request latency. It is encouraged to use a small timeout for webhooks. See [Timeouts](#timeouts) for more detail. -It is recommended that admission webhooks should leverage some format of load-balancing, to provide high availability and -performance benefits. If a webhook is running within the cluster, you can run multiple webhook backends behind a service -to leverage the load-balancing that service supports. +It is recommended that admission webhooks should leverage some format of load-balancing, to +provide high availability and performance benefits. If a webhook is running within the cluster, +you can run multiple webhook backends behind a service to leverage the load-balancing that service +supports. ### Guaranteeing the final state of the object is seen Admission webhooks that need to guarantee they see the final state of the object in order to enforce policy should use a validating admission webhook, since objects can be modified after being seen by mutating webhooks. -For example, a mutating admission webhook is configured to inject a sidecar container with name "foo-sidecar" on every -`CREATE` pod request. If the sidecar *must* be present, a validating admisson webhook should also be configured to intercept `CREATE` pod requests, and validate -that a container with name "foo-sidecar" with the expected configuration exists in the to-be-created object. +For example, a mutating admission webhook is configured to inject a sidecar container with name +"foo-sidecar" on every `CREATE` pod request. If the sidecar *must* be present, a validating +admisson webhook should also be configured to intercept `CREATE` pod requests, and validate that a +container with name "foo-sidecar" with the expected configuration exists in the to-be-created +object. ### Avoiding deadlocks in self-hosted webhooks @@ -1614,7 +1153,8 @@ When a node that runs the webhook server pods becomes unhealthy, the webhook deployment will try to reschedule the pods to another node. However the requests will get rejected by the existing webhook server since the `"env"` label is unset, and the migration cannot happen. -It is recommended to exclude the namespace where your webhook is running with a [namespaceSelector](#matching-requests-namespaceselector). +It is recommended to exclude the namespace where your webhook is running with a +[namespaceSelector](#matching-requests-namespaceselector). ### Side effects @@ -1636,4 +1176,3 @@ If your admission webhooks don't intend to modify the behavior of the Kubernetes plane, exclude the `kube-system` namespace from being intercepted using a [`namespaceSelector`](#matching-requests-namespaceselector). - diff --git a/content/en/docs/reference/command-line-tools-reference/kubelet.md b/content/en/docs/reference/command-line-tools-reference/kubelet.md index b10e1b7057..abaa00af1f 100644 --- a/content/en/docs/reference/command-line-tools-reference/kubelet.md +++ b/content/en/docs/reference/command-line-tools-reference/kubelet.md @@ -187,27 +187,6 @@ kubelet [flags] Domain for this cluster. If set, kubelet will configure all containers to search this domain in addition to the host's search domains (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---cni-bin-dir string     Default: /opt/cni/bin - - -A comma-separated list of full paths of directories in which to search for CNI plugin binaries. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - - ---cni-cache-dir string     Default: /var/lib/cni/cache - - -The full path of the directory in which CNI should store cache files. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - - ---cni-conf-dir string     Default: /etc/cni/net.d - - -<Warning: Alpha feature> The full path of the directory in which to search for CNI config files. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - --config string @@ -230,20 +209,19 @@ kubelet [flags] ---container-runtime string     Default: docker +--container-runtime string     Default: remote -The container runtime to use. Possible values: docker, remote. +The container runtime to use. Possible values: docker, remote. (DEPRECATED: will be removed in 1.27 as the only valid value is 'remote') ---container-runtime-endpoint string     Default: unix:///var/run/dockershim.sock +--container-runtime-endpoint string -[Experimental] The endpoint of remote runtime service. Currently unix socket endpoint is supported on Linux, while npipe and tcp endpoints are supported on windows. Examples: unix:///var/run/dockershim.sock, npipe:////./pipe/dockershim. +The endpoint of remote runtime service. Unix Domain SOckets are supported on Linux, while npipe and tcp endpoints are supported on windows. Examples: unix:///var/run/dockershim.sock, npipe:////./pipe/dockershim. - --contention-profiling @@ -276,7 +254,7 @@ kubelet [flags] --cpu-manager-policy-options mapStringString -Comma-separated list of options to fine-tune the behavior of the selected CPU Manager policy. If not supplied, keep the default behaviour. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) +A set of key=value CPU Manager policy options to use, to fine tune their behaviour. If not supplied, keep the default behaviour. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) @@ -286,20 +264,6 @@ kubelet [flags] <Warning: Alpha feature> CPU Manager reconciliation period. Examples: 10s, or 1m. If not supplied, defaults to node status update frequency. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---docker-endpoint string     Default: unix:///var/run/docker.sock - - -Use this for the docker endpoint to communicate with. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - - ---dynamic-config-dir string - - -The Kubelet will use this directory for checkpointing downloaded configurations and tracking configuration health. The Kubelet will create this directory if it does not already exist. The path may be absolute or relative; relative paths start at the Kubelet's current working directory. Providing this flag enables dynamic Kubelet configuration. The DynamicKubeletConfig feature gate must be enabled to pass this flag. (DEPRECATED: Feature DynamicKubeletConfig is deprecated in 1.22 and will not move to GA. It is planned to be removed from Kubernetes in the version 1.24 or later. Please use alternative ways to update kubelet configuration.) - - --enable-controller-attach-detach     Default: true @@ -398,13 +362,6 @@ kubelet [flags] When set to true, hard eviction thresholds will be ignored while calculating node allocatable. See here for more details. (DEPRECATED: will be removed in 1.24 or later) - ---experimental-check-node-capabilities-before-mount - - -[Experimental] if set to true, the kubelet will check the underlying node for required components (binaries, etc.) before performing the mount (DEPRECATED: will be removed in 1.24 or later, in favor of using CSI.) - - --experimental-kernel-memcg-notification @@ -412,13 +369,6 @@ kubelet [flags] Use kernelMemcgNotification configuration, this flag will be removed in 1.24 or later. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---experimental-log-sanitization bool - - -[Experimental] When enabled, prevents logging of fields tagged as sensitive (passwords, keys, tokens). Runtime log sanitization may introduce significant computation overhead and therefore should not be enabled in production. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - - --experimental-mounter-path string     Default: mount @@ -445,83 +395,76 @@ APIServerIdentity=true|false (ALPHA - default=false)
APIServerTracing=true|false (ALPHA - default=false)
AllAlpha=true|false (ALPHA - default=false)
AllBeta=true|false (BETA - default=false)
-AnyVolumeDataSource=true|false (ALPHA - default=false)
+AnyVolumeDataSource=true|false (BETA - default=true)
AppArmor=true|false (BETA - default=true)
CPUManager=true|false (BETA - default=true)
CPUManagerPolicyAlphaOptions=true|false (ALPHA - default=false)
CPUManagerPolicyBetaOptions=true|false (BETA - default=true)
-CPUManagerPolicyOptions=true|false (ALPHA - default=false)
+CPUManagerPolicyOptions=true|false (BETA - default=true)
CSIInlineVolume=true|false (BETA - default=true)
CSIMigration=true|false (BETA - default=true)
-CSIMigrationAWS=true|false (BETA - default=false)
-CSIMigrationAzureDisk=true|false (BETA - default=true)
-CSIMigrationAzureFile=true|false (BETA - default=false)
+CSIMigrationAWS=true|false (BETA - default=true)
+CSIMigrationAzureFile=true|false (BETA - default=true)
CSIMigrationGCE=true|false (BETA - default=true)
-CSIMigrationOpenStack=true|false (BETA - default=true)
CSIMigrationPortworx=true|false (ALPHA - default=false)
+CSIMigrationRBD=true|false (ALPHA - default=false)
CSIMigrationvSphere=true|false (BETA - default=false)
-CSIStorageCapacity=true|false (BETA - default=true)
CSIVolumeHealth=true|false (ALPHA - default=false)
-CSRDuration=true|false (BETA - default=true)
-ControllerManagerLeaderMigration=true|false (BETA - default=true)
+ContextualLogging=true|false (ALPHA - default=false)
+CronJobTimeZone=true|false (ALPHA - default=false)
CustomCPUCFSQuotaPeriod=true|false (ALPHA - default=false)
CustomResourceValidationExpressions=true|false (ALPHA - default=false)
DaemonSetUpdateSurge=true|false (BETA - default=true)
-DefaultPodTopologySpread=true|false (BETA - default=true)
DelegateFSGroupToCSIDriver=true|false (BETA - default=true)
DevicePlugins=true|false (BETA - default=true)
DisableAcceleratorUsageMetrics=true|false (BETA - default=true)
DisableCloudProviders=true|false (ALPHA - default=false)
DisableKubeletCloudCredentialProviders=true|false (ALPHA - default=false)
DownwardAPIHugePages=true|false (BETA - default=true)
-EfficientWatchResumption=true|false (BETA - default=true)
EndpointSliceTerminatingCondition=true|false (BETA - default=true)
EphemeralContainers=true|false (BETA - default=true)
-ExpandCSIVolumes=true|false (BETA - default=true)
-ExpandInUsePersistentVolumes=true|false (BETA - default=true)
-ExpandPersistentVolumes=true|false (BETA - default=true)
ExpandedDNSConfig=true|false (ALPHA - default=false)
ExperimentalHostUserNamespaceDefaulting=true|false (BETA - default=false)
-GRPCContainerProbe=true|false (ALPHA - default=false)
+GRPCContainerProbe=true|false (BETA - default=true)
GracefulNodeShutdown=true|false (BETA - default=true)
-GracefulNodeShutdownBasedOnPodPriority=true|false (ALPHA - default=false)
+GracefulNodeShutdownBasedOnPodPriority=true|false (BETA - default=true)
HPAContainerMetrics=true|false (ALPHA - default=false)
HPAScaleToZero=true|false (ALPHA - default=false)
HonorPVReclaimPolicy=true|false (ALPHA - default=false)
-IdentifyPodOS=true|false (ALPHA - default=false)
+IdentifyPodOS=true|false (BETA - default=true)
InTreePluginAWSUnregister=true|false (ALPHA - default=false)
InTreePluginAzureDiskUnregister=true|false (ALPHA - default=false)
InTreePluginAzureFileUnregister=true|false (ALPHA - default=false)
InTreePluginGCEUnregister=true|false (ALPHA - default=false)
InTreePluginOpenStackUnregister=true|false (ALPHA - default=false)
InTreePluginPortworxUnregister=true|false (ALPHA - default=false)
-InTreePluginRBDUnregister=true|false (ALPHA - default=false)
+InTreePluginRBDUnregister=true|false (ALPHA - default=false)
InTreePluginvSphereUnregister=true|false (ALPHA - default=false)
-IndexedJob=true|false (BETA - default=true)
JobMutableNodeSchedulingDirectives=true|false (BETA - default=true)
-JobReadyPods=true|false (ALPHA - default=false)
-JobTrackingWithFinalizers=true|false (BETA - default=true)
-KubeletCredentialProviders=true|false (ALPHA - default=false)
+JobReadyPods=true|false (BETA - default=true)
+JobTrackingWithFinalizers=true|false (BETA - default=false)
+KubeletCredentialProviders=true|false (BETA - default=true)
KubeletInUserNamespace=true|false (ALPHA - default=false)
KubeletPodResources=true|false (BETA - default=true)
KubeletPodResourcesGetAllocatable=true|false (BETA - default=true)
+LegacyServiceAccountTokenNoAutoGeneration=true|false (BETA - default=true)
LocalStorageCapacityIsolation=true|false (BETA - default=true)
LocalStorageCapacityIsolationFSQuotaMonitoring=true|false (ALPHA - default=false)
LogarithmicScaleDown=true|false (BETA - default=true)
+MaxUnavailableStatefulSet=true|false (ALPHA - default=false)
MemoryManager=true|false (BETA - default=true)
MemoryQoS=true|false (ALPHA - default=false)
-MixedProtocolLBService=true|false (ALPHA - default=false)
+MinDomainsInPodTopologySpread=true|false (ALPHA - default=false)
+MixedProtocolLBService=true|false (BETA - default=true)
NetworkPolicyEndPort=true|false (BETA - default=true)
+NetworkPolicyStatus=true|false (ALPHA - default=false)
+NodeOutOfServiceVolumeDetach=true|false (ALPHA - default=false)
NodeSwap=true|false (ALPHA - default=false)
-NonPreemptingPriority=true|false (BETA - default=true)
-OpenAPIEnums=true|false (ALPHA - default=false)
-OpenAPIV3=true|false (ALPHA - default=false)
-PodAffinityNamespaceSelector=true|false (BETA - default=true)
+OpenAPIEnums=true|false (BETA - default=true)
+OpenAPIV3=true|false (BETA - default=true)
PodAndContainerStatsFromCRI=true|false (ALPHA - default=false)
PodDeletionCost=true|false (BETA - default=true)
-PodOverhead=true|false (BETA - default=true)
PodSecurity=true|false (BETA - default=true)
-PreferNominatedNode=true|false (BETA - default=true)
ProbeTerminationGracePeriod=true|false (BETA - default=false)
ProcMountType=true|false (ALPHA - default=false)
ProxyTerminatingEndpoints=true|false (ALPHA - default=false)
@@ -529,25 +472,22 @@ QOSReserved=true|false (ALPHA - default=false)
ReadWriteOncePod=true|false (ALPHA - default=false)
RecoverVolumeExpansionFailure=true|false (ALPHA - default=false)
RemainingItemCount=true|false (BETA - default=true)
-RemoveSelfLink=true|false (BETA - default=true)
RotateKubeletServerCertificate=true|false (BETA - default=true)
SeccompDefault=true|false (ALPHA - default=false)
+ServerSideFieldValidation=true|false (ALPHA - default=false)
+ServiceIPStaticSubrange=true|false (ALPHA - default=false)
ServiceInternalTrafficPolicy=true|false (BETA - default=true)
-ServiceLBNodePortControl=true|false (BETA - default=true)
-ServiceLoadBalancerClass=true|false (BETA - default=true)
SizeMemoryBackedVolumes=true|false (BETA - default=true)
StatefulSetAutoDeletePVC=true|false (ALPHA - default=false)
StatefulSetMinReadySeconds=true|false (BETA - default=true)
StorageVersionAPI=true|false (ALPHA - default=false)
StorageVersionHash=true|false (BETA - default=true)
-SuspendJob=true|false (BETA - default=true)
TopologyAwareHints=true|false (BETA - default=true)
TopologyManager=true|false (BETA - default=true)
VolumeCapacityPriority=true|false (ALPHA - default=false)
WinDSR=true|false (ALPHA - default=false)
WinOverlay=true|false (BETA - default=true)
WindowsHostProcessContainers=true|false (BETA - default=true)
-csiMigrationRBD=true|false (ALPHA - default=false)
(DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) @@ -628,18 +568,11 @@ csiMigrationRBD=true|false (ALPHA - default=false)
The percent of disk usage before which image garbage collection is never run. Lowest disk usage to garbage collect to. Values must be within the range [0, 100] and should not be larger than that of --image-gc-high-threshold. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---image-pull-progress-deadline duration     Default: 1m0s - - -If no pulling progress is made before this deadline, the image pulling will be cancelled. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - --image-service-endpoint string -[Experimental] The endpoint of remote image service. If not specified, it will be the same with --container-runtime-endpoint by default. Currently UNIX socket endpoint is supported on Linux, while npipe and TCP endpoints are supported on Windows. Examples: unix:///var/run/dockershim.sock, npipe:////./pipe/dockershim +[Experimental] The endpoint of remote image service. If not specified, it will be the same with --container-runtime-endpoint by default. Unix Domain Socket are supported on Linux, while npipe and TCP endpoints are supported on Windows. Examples: unix:///var/run/dockershim.sock, npipe:////./pipe/dockershim @@ -866,20 +799,6 @@ csiMigrationRBD=true|false (ALPHA - default=false)
Minimum age for an unused image before it is garbage collected. Examples: '300ms', '10s' or '2h45m'. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---network-plugin string - - -The name of the network plugin to be invoked for various events in kubelet/pod lifecycle. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - - ---network-plugin-mtu int32 - - -The MTU to be passed to the network plugin, to override the default. Set to 0 to use the default 1460 MTU. This docker-specific flag only works when container-runtime is set to docker. (DEPRECATED: will be removed along with dockershim.) - - --node-ip string @@ -908,13 +827,6 @@ csiMigrationRBD=true|false (ALPHA - default=false)
Specifies how often kubelet posts node status to master. Note: be cautious when changing the constant, it must work with nodeMonitorGracePeriod in Node controller. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---non-masquerade-cidr string     Default: 10.0.0.0/8 - - -Traffic to IPs outside this range will use IP masquerade. Set to '0.0.0.0/0' to never masquerade. (DEPRECATED: will be removed in a future version) - - --one-output @@ -999,13 +911,6 @@ csiMigrationRBD=true|false (ALPHA - default=false)
The read-only port for the kubelet to serve on with no authentication/authorization (set to 0 to disable). (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) - ---really-crash-for-testing - - -If true, when panics occur crash. Intended for testing. (DEPRECATED: will be removed in a future version.) - - --register-node     Default: true @@ -1105,7 +1010,7 @@ csiMigrationRBD=true|false (ALPHA - default=false)
---seccomp-default RuntimeDefault +--seccomp-default string <Warning: Alpha feature> Enable the use of RuntimeDefault as the default seccomp profile for all workloads. The SeccompDefault feature gate must be enabled to allow this flag, which is disabled by default. @@ -1187,10 +1092,10 @@ csiMigrationRBD=true|false (ALPHA - default=false)
Comma-separated list of cipher suites for the server. If omitted, the default Go cipher suites will be used.
Preferred values: -TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_256_GCM_SHA384
-Insecure values: -TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_RC4_128_SHA. -(DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See kubelet-config-file for more information.) +`TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`, `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`
+Insecure values:
+`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_RC4_128_SHA`, `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_RC4_128_SHA`, `TLS_RSA_WITH_3DES_EDE_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_RC4_128_SHA`.
+(DEPRECATED: This parameter should be set via the config file specified by the Kubelet's `--config` flag. See kubelet-config-file for more information.) @@ -1237,7 +1142,7 @@ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_E ---vmodule <A list of 'pattern=N' string> +--vmodule <A list of 'pattern=N' strings> Comma-separated list of pattern=N settings for file-filtered logging diff --git a/content/en/docs/reference/config-api/kubeadm-config.v1beta2.md b/content/en/docs/reference/config-api/kubeadm-config.v1beta2.md index 377ac021b6..a6e2bd98cd 100644 --- a/content/en/docs/reference/config-api/kubeadm-config.v1beta2.md +++ b/content/en/docs/reference/config-api/kubeadm-config.v1beta2.md @@ -113,7 +113,7 @@ components by adding customized setting or overriding kubeadm default settings.<

The KubeProxyConfiguration type should be used to change the configuration passed to kube-proxy instances deployed in the cluster. If this object is not provided or provided only partially, kubeadm applies defaults.

See https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/ or -https://godoc.org/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration +https://pkg.go.dev/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration for kube proxy official documentation.

apiVersion: kubelet.config.k8s.io/v1beta1
 kind: KubeletConfiguration
@@ -121,7 +121,7 @@ for kube proxy official documentation.

The KubeletConfiguration type should be used to change the configurations that will be passed to all kubelet instances deployed in the cluster. If this object is not provided or provided only partially, kubeadm applies defaults.

See https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/ or -https://godoc.org/k8s.io/kubelet/config/v1beta1#KubeletConfiguration +https://pkg.go.dev/k8s.io/kubelet/config/v1beta1#KubeletConfiguration for kubelet official documentation.

Here is a fully populated example of a single YAML file containing multiple configuration types to be used during a kubeadm init run.

@@ -1307,4 +1307,4 @@ current node is registered.

- + \ No newline at end of file diff --git a/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md b/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md index 35518ec197..20f5e44d93 100644 --- a/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md +++ b/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md @@ -122,7 +122,7 @@ components by adding customized setting or overriding kubeadm default settings.<

The KubeProxyConfiguration type should be used to change the configuration passed to kube-proxy instances deployed in the cluster. If this object is not provided or provided only partially, kubeadm applies defaults.

See https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/ or -https://godoc.org/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration +https://pkg.go.dev/k8s.io/kube-proxy/config/v1alpha1#KubeProxyConfiguration for kube-proxy official documentation.

apiVersion: kubelet.config.k8s.io/v1beta1
 kind: KubeletConfiguration
@@ -130,7 +130,7 @@ for kube-proxy official documentation.

The KubeletConfiguration type should be used to change the configurations that will be passed to all kubelet instances deployed in the cluster. If this object is not provided or provided only partially, kubeadm applies defaults.

See https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/ or -https://godoc.org/k8s.io/kubelet/config/v1beta1#KubeletConfiguration +https://pkg.go.dev/k8s.io/kubelet/config/v1beta1#KubeletConfiguration for kubelet official documentation.

Here is a fully populated example of a single YAML file containing multiple configuration types to be used during a kubeadm init run.

@@ -1159,7 +1159,7 @@ This information will be annotated to the Node API object, for later re-use

[]core/v1.Taint -

tains specifies the taints the Node API object should be registered with. +

taints specifies the taints the Node API object should be registered with. If this field is unset, i.e. nil, in the kubeadm init process it will be defaulted with a control-plane taint for control-plane nodes. If you don't want to taint your control-plane node, set this field to an empty list, diff --git a/content/en/docs/reference/kubectl/cheatsheet.md b/content/en/docs/reference/kubectl/cheatsheet.md index 8769e32b15..fa7e9bffe0 100644 --- a/content/en/docs/reference/kubectl/cheatsheet.md +++ b/content/en/docs/reference/kubectl/cheatsheet.md @@ -68,6 +68,11 @@ kubectl config get-contexts # display list of contexts kubectl config current-context # display the current-context kubectl config use-context my-cluster-name # set the default context to my-cluster-name +kubectl config set-cluster my-cluster-name # set a cluster entry in the kubeconfig + +# configure the URL to a proxy server to use for requests made by this client in the kubeconfig +kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url + # add a new user to your kubeconf that supports basic auth kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword @@ -182,6 +187,9 @@ kubectl get pods --selector=app=cassandra -o \ kubectl get configmap myconfig \ -o jsonpath='{.data.ca\.crt}' +# Retrieve a base64 encoded value with dashes instead of underscores. +kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}' + # Get all worker nodes (use a selector to exclude results that have a label # named 'node-role.kubernetes.io/control-plane') kubectl get node --selector='!node-role.kubernetes.io/control-plane' diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md index a308b8d704..39f7d0cce9 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md +++ b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md @@ -6,7 +6,9 @@ title: kubeadm init content_type: concept weight: 20 --- + + This command initializes a Kubernetes control-plane node. @@ -26,12 +28,12 @@ following steps: 1. Generates a self-signed CA to set up identities for each component in the cluster. The user can provide their own CA cert and/or key by dropping it in the cert directory configured via `--cert-dir` (`/etc/kubernetes/pki` by default). - The APIServer certs will have additional SAN entries for any `--apiserver-cert-extra-sans` arguments, lowercased if necessary. + The APIServer certs will have additional SAN entries for any `--apiserver-cert-extra-sans` + arguments, lowercased if necessary. -1. Writes kubeconfig files in `/etc/kubernetes/` for - the kubelet, the controller-manager and the scheduler to use to connect to the - API server, each with its own identity, as well as an additional - kubeconfig file for administration named `admin.conf`. +1. Writes kubeconfig files in `/etc/kubernetes/` for the kubelet, the controller-manager and the + scheduler to use to connect to the API server, each with its own identity, as well as an + additional kubeconfig file for administration named `admin.conf`. 1. Generates static Pod manifests for the API server, controller-manager and scheduler. In case an external etcd is not provided, @@ -76,10 +78,12 @@ following steps: Kubeadm allows you to create a control-plane node in phases using the `kubeadm init phase` command. -To view the ordered list of phases and sub-phases you can call `kubeadm init --help`. The list will be located at the top of the help screen and each phase will have a description next to it. +To view the ordered list of phases and sub-phases you can call `kubeadm init --help`. The list +will be located at the top of the help screen and each phase will have a description next to it. Note that by calling `kubeadm init` all of the phases and sub-phases will be executed in this exact order. -Some phases have unique flags, so if you want to have a look at the list of available options add `--help`, for example: +Some phases have unique flags, so if you want to have a look at the list of available options add +`--help`, for example: ```shell sudo kubeadm init phase control-plane controller-manager --help @@ -91,7 +95,8 @@ You can also use `--help` to see the list of sub-phases for a certain parent pha sudo kubeadm init phase control-plane --help ``` -`kubeadm init` also exposes a flag called `--skip-phases` that can be used to skip certain phases. The flag accepts a list of phase names and the names can be taken from the above ordered list. +`kubeadm init` also exposes a flag called `--skip-phases` that can be used to skip certain phases. +The flag accepts a list of phase names and the names can be taken from the above ordered list. An example: @@ -102,7 +107,10 @@ sudo kubeadm init phase etcd local --config=configfile.yaml sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml ``` -What this example would do is write the manifest files for the control plane and etcd in `/etc/kubernetes/manifests` based on the configuration in `configfile.yaml`. This allows you to modify the files and then skip these phases using `--skip-phases`. By calling the last command you will create a control plane node with the custom manifest files. +What this example would do is write the manifest files for the control plane and etcd in +`/etc/kubernetes/manifests` based on the configuration in `configfile.yaml`. This allows you to +modify the files and then skip these phases using `--skip-phases`. By calling the last command you +will create a control plane node with the custom manifest files. {{< feature-state for_k8s_version="v1.22" state="beta" >}} @@ -245,7 +253,7 @@ To set a custom image for these you need to configure this in your to use the image. Consult the documentation for your container runtime to find out how to change this setting; for selected container runtimes, you can also find advice within the -[Container Runtimes]((/docs/setup/production-environment/container-runtimes/) topic. +[Container Runtimes](/docs/setup/production-environment/container-runtimes/) topic. ### Uploading control-plane certificates to the cluster @@ -280,30 +288,35 @@ and certificate renewal. ### Managing the kubeadm drop-in file for the kubelet {#kubelet-drop-in} -The `kubeadm` package ships with a configuration file for running the `kubelet` by `systemd`. Note that the kubeadm CLI never touches this drop-in file. This drop-in file is part of the kubeadm DEB/RPM package. +The `kubeadm` package ships with a configuration file for running the `kubelet` by `systemd`. +Note that the kubeadm CLI never touches this drop-in file. This drop-in file is part of the kubeadm +DEB/RPM package. -For further information, see [Managing the kubeadm drop-in file for systemd](/docs/setup/production-environment/tools/kubeadm/kubelet-integration/#the-kubelet-drop-in-file-for-systemd). +For further information, see +[Managing the kubeadm drop-in file for systemd](/docs/setup/production-environment/tools/kubeadm/kubelet-integration/#the-kubelet-drop-in-file-for-systemd). ### Use kubeadm with CRI runtimes -By default kubeadm attempts to detect your container runtime. For more details on this detection, see -the [kubeadm CRI installation guide](/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-runtime). +By default kubeadm attempts to detect your container runtime. For more details on this detection, +see the [kubeadm CRI installation guide](/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-runtime). ### Setting the node name -By default, `kubeadm` assigns a node name based on a machine's host address. You can override this setting with the `--node-name` flag. +By default, `kubeadm` assigns a node name based on a machine's host address. +You can override this setting with the `--node-name` flag. The flag passes the appropriate [`--hostname-override`](/docs/reference/command-line-tools-reference/kubelet/#options) value to the kubelet. -Be aware that overriding the hostname can [interfere with cloud providers](https://github.com/kubernetes/website/pull/8873). +Be aware that overriding the hostname can +[interfere with cloud providers](https://github.com/kubernetes/website/pull/8873). ### Automating kubeadm Rather than copying the token you obtained from `kubeadm init` to each node, as -in the [basic kubeadm tutorial](/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/), you can parallelize the -token distribution for easier automation. To implement this automation, you must -know the IP address that the control-plane node will have after it is started, -or use a DNS name or an address of a load balancer. +in the [basic kubeadm tutorial](/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/), +you can parallelize the token distribution for easier automation. To implement this automation, +you must know the IP address that the control-plane node will have after it is started, or use a +DNS name or an address of a load balancer. 1. Generate a token. This token must have the form `<6 character string>.<16 character string>`. More formally, it must match the regex: @@ -337,7 +350,11 @@ provisioned). For details, see the [kubeadm join](/docs/reference/setup-tools/ku ## {{% heading "whatsnext" %}} * [kubeadm init phase](/docs/reference/setup-tools/kubeadm/kubeadm-init-phase/) to understand more about -`kubeadm init` phases -* [kubeadm join](/docs/reference/setup-tools/kubeadm/kubeadm-join/) to bootstrap a Kubernetes worker node and join it to the cluster -* [kubeadm upgrade](/docs/reference/setup-tools/kubeadm/kubeadm-upgrade/) to upgrade a Kubernetes cluster to a newer version -* [kubeadm reset](/docs/reference/setup-tools/kubeadm/kubeadm-reset/) to revert any changes made to this host by `kubeadm init` or `kubeadm join` + `kubeadm init` phases +* [kubeadm join](/docs/reference/setup-tools/kubeadm/kubeadm-join/) to bootstrap a Kubernetes + worker node and join it to the cluster +* [kubeadm upgrade](/docs/reference/setup-tools/kubeadm/kubeadm-upgrade/) to upgrade a Kubernetes + cluster to a newer version +* [kubeadm reset](/docs/reference/setup-tools/kubeadm/kubeadm-reset/) to revert any changes made + to this host by `kubeadm init` or `kubeadm join` + diff --git a/content/en/docs/setup/production-environment/container-runtimes.md b/content/en/docs/setup/production-environment/container-runtimes.md index dd432afd3d..b9b38521c4 100644 --- a/content/en/docs/setup/production-environment/container-runtimes.md +++ b/content/en/docs/setup/production-environment/container-runtimes.md @@ -179,9 +179,9 @@ Follow the instructions for [getting started with containerd](https://github.com {{% tab name="Linux" %}} You can find this file under the path `/etc/containerd/config.toml`. {{% /tab %}} -{{< tab name="Windows" >}} +{{% tab name="Windows" %}} You can find this file under the path `C:\Program Files\containerd\config.toml`. -{{< /tab >}} +{{% /tab %}} {{< /tabs >}} On Linux the default CRI socket for containerd is `/run/containerd/containerd.sock`. diff --git a/content/en/docs/tasks/administer-cluster/kubelet-in-userns.md b/content/en/docs/tasks/administer-cluster/kubelet-in-userns.md index 2b088b7a5d..90e4a11f63 100644 --- a/content/en/docs/tasks/administer-cluster/kubelet-in-userns.md +++ b/content/en/docs/tasks/administer-cluster/kubelet-in-userns.md @@ -41,13 +41,12 @@ See [Running kind with Rootless Docker](https://kind.sigs.k8s.io/docs/user/rootl ### minikube -[minikube](https://minikube.sigs.k8s.io/) also supports running Kubernetes inside Rootless Docker. +[minikube](https://minikube.sigs.k8s.io/) also supports running Kubernetes inside Rootless Docker or Rootless Podman. -See the page about the [docker](https://minikube.sigs.k8s.io/docs/drivers/docker/) driver in the Minikube documentation. +See the Minikube documentation: -Rootless Podman is not supported. - - +* [Rootless Docker](https://minikube.sigs.k8s.io/docs/drivers/docker/) +* [Rootless Podman](https://minikube.sigs.k8s.io/docs/drivers/podman/) ## Running Kubernetes inside Unprivileged Containers diff --git a/content/en/docs/tasks/administer-cluster/verify-signed-images.md b/content/en/docs/tasks/administer-cluster/verify-signed-images.md index 5ae1db1134..fec6d1e59d 100644 --- a/content/en/docs/tasks/administer-cluster/verify-signed-images.md +++ b/content/en/docs/tasks/administer-cluster/verify-signed-images.md @@ -68,5 +68,5 @@ e.g. [conformance image](https://github.com/kubernetes/kubernetes/blob/master/te admission controller. To get started with `cosigned` here are a few helpful resources: -* [Installation](https://github.com/sigstore/helm-charts/tree/main/charts/cosigned) +* [Installation](https://github.com/sigstore/cosign#installation) * [Configuration Options](https://github.com/sigstore/cosign/tree/main/config) diff --git a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md index e99ea5473c..ca51410340 100644 --- a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md +++ b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md @@ -26,21 +26,16 @@ Therefore, jobs should be idempotent. For more limitations, see [CronJobs](/docs/concepts/workloads/controllers/cron-jobs). - - ## {{% heading "prerequisites" %}} - * {{< include "task-tutorial-prereqs.md" >}} - - -## Creating a Cron Job +## Creating a CronJob {#creating-a-cron-job} Cron jobs require a config file. -This example cron job config `.spec` file prints the current time and a hello message every minute: +Here is a manifest for a CronJob that runs a simple demonstration task every minute: {{< codenew file="application/job/cronjob.yaml" >}} @@ -60,6 +55,7 @@ After creating the cron job, get its status using this command: ```shell kubectl get cronjob hello ``` + The output is similar to this: ``` @@ -102,14 +98,14 @@ You should see that the cron job `hello` successfully scheduled a job at the tim Now, find the pods that the last scheduled job created and view the standard output of one of the pods. {{< note >}} -The job name and pod name are different. +The job name is different from the pod name. {{< /note >}} ```shell # Replace "hello-4111706356" with the job name in your system pods=$(kubectl get pods --selector=job-name=hello-4111706356 --output=jsonpath={.items[*].metadata.name}) ``` -Show pod log: +Show the pod log: ```shell kubectl logs $pods @@ -121,7 +117,7 @@ Fri Feb 22 11:02:09 UTC 2019 Hello from the Kubernetes cluster ``` -## Deleting a Cron Job +## Deleting a CronJob {#deleting-a-cron-job} When you don't need a cron job any more, delete it with `kubectl delete cronjob `: @@ -132,16 +128,20 @@ kubectl delete cronjob hello Deleting the cron job removes all the jobs and pods it created and stops it from creating additional jobs. You can read more about removing jobs in [garbage collection](/docs/concepts/architecture/garbage-collection/). -## Writing a Cron Job Spec +## Writing a CronJob Spec {#writing-a-cron-job-spec} -As with all other Kubernetes configs, a cron job needs `apiVersion`, `kind`, and `metadata` fields. For general -information about working with config files, see [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/), +As with all other Kubernetes objects, a CronJob must have `apiVersion`, `kind`, and `metadata` fields. +For more information about working with Kubernetes objects and their +{{< glossary_tooltip text="manifests" term_id="manifest" >}}, see the +[managing resources](/docs/concepts/cluster-administration/manage-deployment/), and [using kubectl to manage resources](/docs/concepts/overview/working-with-objects/object-management/) documents. -A cron job config also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status). +Each manifest for a CrobJob also needs a [`.spec`](/docs/concepts/overview/working-with-objects/kubernetes-objects/#object-spec-and-status) section. {{< note >}} -All modifications to a cron job, especially its `.spec`, are applied only to the following runs. +If you modify a CronJob, the changes you make will apply to new jobs that start to run after your modification +is complete. Jobs (and their Pods) that have already started continue to run without changes. +That is, the CronJob does _not_ update existing jobs, even if those remain running. {{< /note >}} ### Schedule @@ -153,11 +153,11 @@ as schedule time of its jobs to be created and executed. The format also includes extended "Vixie cron" step values. As explained in the [FreeBSD manual](https://www.freebsd.org/cgi/man.cgi?crontab%285%29): -> Step values can be used in conjunction with ranges. Following a range -> with `/` specifies skips of the number's value through the -> range. For example, `0-23/2` can be used in the hours field to specify -> command execution every other hour (the alternative in the V7 standard is -> `0,2,4,6,8,10,12,14,16,18,20,22`). Steps are also permitted after an +> Step values can be used in conjunction with ranges. Following a range +> with `/` specifies skips of the number's value through the +> range. For example, `0-23/2` can be used in the hours field to specify +> command execution every other hour (the alternative in the V7 standard is +> `0,2,4,6,8,10,12,14,16,18,20,22`). Steps are also permitted after an > asterisk, so if you want to say "every two hours", just use `*/2`. {{< note >}} @@ -221,5 +221,3 @@ The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields These fields specify how many completed and failed jobs should be kept. By default, they are set to 3 and 1 respectively. Setting a limit to `0` corresponds to keeping none of the corresponding kind of jobs after they finish. - - diff --git a/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md b/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md index 8e0670a89f..07c631bc3a 100644 --- a/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md +++ b/content/en/docs/tasks/manage-kubernetes-objects/imperative-command.md @@ -165,8 +165,8 @@ kubectl create --edit -f /tmp/srv.yaml ## {{% heading "whatsnext" %}} -* [Managing Kubernetes Objects Using Object Configuration (Imperative)](/docs/tasks/manage-kubernetes-objects/imperative-config/) -* [Managing Kubernetes Objects Using Object Configuration (Declarative)](/docs/tasks/manage-kubernetes-objects/declarative-config/) +* [Imperative Management of Kubernetes Objects Using Configuration Files](/docs/tasks/manage-kubernetes-objects/imperative-config/) +* [Declarative Management of Kubernetes Objects Using Configuration Files](/docs/tasks/manage-kubernetes-objects/declarative-config/) * [Kubectl Command Reference](/docs/reference/generated/kubectl/kubectl-commands/) * [Kubernetes API Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) diff --git a/content/en/docs/tasks/manage-kubernetes-objects/imperative-config.md b/content/en/docs/tasks/manage-kubernetes-objects/imperative-config.md index 87cc423da7..4e59491c62 100644 --- a/content/en/docs/tasks/manage-kubernetes-objects/imperative-config.md +++ b/content/en/docs/tasks/manage-kubernetes-objects/imperative-config.md @@ -161,7 +161,7 @@ template: * [Managing Kubernetes Objects Using Imperative Commands](/docs/tasks/manage-kubernetes-objects/imperative-command/) -* [Managing Kubernetes Objects Using Object Configuration (Declarative)](/docs/tasks/manage-kubernetes-objects/declarative-config/) +* [Declarative Management of Kubernetes Objects Using Configuration Files](/docs/tasks/manage-kubernetes-objects/declarative-config/) * [Kubectl Command Reference](/docs/reference/generated/kubectl/kubectl-commands/) * [Kubernetes API Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) diff --git a/content/en/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice.md b/content/en/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice.md index dccf214c47..8055f6774e 100644 --- a/content/en/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice.md +++ b/content/en/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice.md @@ -6,34 +6,63 @@ weight: 10 -In this tutorial you will learn how and why to externalize your microservice’s configuration. Specifically, you will learn how to use Kubernetes ConfigMaps and Secrets to set environment variables and then consume them using MicroProfile Config. +In this tutorial you will learn how and why to externalize your microservice’s configuration. +Specifically, you will learn how to use Kubernetes ConfigMaps and Secrets to set environment +variables and then consume them using MicroProfile Config. ## {{% heading "prerequisites" %}} ### Creating Kubernetes ConfigMaps & Secrets -There are several ways to set environment variables for a Docker container in Kubernetes, including: Dockerfile, kubernetes.yml, Kubernetes ConfigMaps, and Kubernetes Secrets. In the tutorial, you will learn how to use the latter two for setting your environment variables whose values will be injected into your microservices. One of the benefits for using ConfigMaps and Secrets is that they can be re-used across multiple containers, including being assigned to different environment variables for the different containers. -ConfigMaps are API Objects that store non-confidential key-value pairs. In the Interactive Tutorial you will learn how to use a ConfigMap to store the application's name. For more information regarding ConfigMaps, you can find the documentation [here](/docs/tasks/configure-pod-container/configure-pod-configmap/). +There are several ways to set environment variables for a Docker container in Kubernetes, +including: Dockerfile, kubernetes.yml, Kubernetes ConfigMaps, and Kubernetes Secrets. In the +tutorial, you will learn how to use the latter two for setting your environment variables whose +values will be injected into your microservices. One of the benefits for using ConfigMaps and +Secrets is that they can be re-used across multiple containers, including being assigned to +different environment variables for the different containers. -Although Secrets are also used to store key-value pairs, they differ from ConfigMaps in that they're intended for confidential/sensitive information and are stored using Base64 encoding. This makes secrets the appropriate choice for storing such things as credentials, keys, and tokens, the former of which you'll do in the Interactive Tutorial. For more information on Secrets, you can find the documentation [here](/docs/concepts/configuration/secret/). +ConfigMaps are API Objects that store non-confidential key-value pairs. In the Interactive +Tutorial you will learn how to use a ConfigMap to store the application's name. For more +information regarding ConfigMaps, you can find the documentation +[here](/docs/tasks/configure-pod-container/configure-pod-configmap/). + +Although Secrets are also used to store key-value pairs, they differ from ConfigMaps in that +they're intended for confidential/sensitive information and are stored using Base64 encoding. +This makes secrets the appropriate choice for storing such things as credentials, keys, and +tokens, the former of which you'll do in the Interactive Tutorial. For more information on +Secrets, you can find the documentation [here](/docs/concepts/configuration/secret/). ### Externalizing Config from Code -Externalized application configuration is useful because configuration usually changes depending on your environment. In order to accomplish this, we'll use Java's Contexts and Dependency Injection (CDI) and MicroProfile Config. MicroProfile Config is a feature of MicroProfile, a set of open Java technologies for developing and deploying cloud-native microservices. -CDI provides a standard dependency injection capability enabling an application to be assembled from collaborating, loosely-coupled beans. MicroProfile Config provides apps and microservices a standard way to obtain config properties from various sources, including the application, runtime, and environment. Based on the source's defined priority, the properties are automatically combined into a single set of properties that the application can access via an API. Together, CDI & MicroProfile will be used in the Interactive Tutorial to retrieve the externally provided properties from the Kubernetes ConfigMaps and Secrets and get injected into your application code. +Externalized application configuration is useful because configuration usually changes depending +on your environment. In order to accomplish this, we'll use Java's Contexts and Dependency +Injection (CDI) and MicroProfile Config. MicroProfile Config is a feature of MicroProfile, a set +of open Java technologies for developing and deploying cloud-native microservices. -Many open source frameworks and runtimes implement and support MicroProfile Config. Throughout the interactive tutorial, you'll be using Open Liberty, a flexible open-source Java runtime for building and running cloud-native apps and microservices. However, any MicroProfile compatible runtime could be used instead. +CDI provides a standard dependency injection capability enabling an application to be assembled +from collaborating, loosely-coupled beans. MicroProfile Config provides apps and microservices a +standard way to obtain config properties from various sources, including the application, runtime, +and environment. Based on the source's defined priority, the properties are automatically +combined into a single set of properties that the application can access via an API. Together, +CDI & MicroProfile will be used in the Interactive Tutorial to retrieve the externally provided +properties from the Kubernetes ConfigMaps and Secrets and get injected into your application code. + +Many open source frameworks and runtimes implement and support MicroProfile Config. Throughout +the interactive tutorial, you'll be using Open Liberty, a flexible open-source Java runtime for +building and running cloud-native apps and microservices. However, any MicroProfile compatible +runtime could be used instead. ## {{% heading "objectives" %}} * Create a Kubernetes ConfigMap and Secret * Inject microservice configuration using MicroProfile Config - ## Example: Externalizing config using MicroProfile, ConfigMaps and Secrets -### [Start Interactive Tutorial](/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice-interactive/) + +[Start Interactive Tutorial](/docs/tutorials/configuration/configure-java-microservice/configure-java-microservice-interactive/) + diff --git a/content/en/docs/tutorials/security/cluster-level-pss.md b/content/en/docs/tutorials/security/cluster-level-pss.md index 8a303af651..3b662efc60 100644 --- a/content/en/docs/tutorials/security/cluster-level-pss.md +++ b/content/en/docs/tutorials/security/cluster-level-pss.md @@ -17,7 +17,8 @@ created. This tutorial shows you how to enforce the `baseline` Pod Security Standard at the cluster level which applies a standard configuration to all namespaces in a cluster. -To apply Pod Security Standards to specific namespaces, refer to [Apply Pod Security Standards at the namespace level](/docs/tutorials/security/ns-level-pss). +To apply Pod Security Standards to specific namespaces, refer to +[Apply Pod Security Standards at the namespace level](/docs/tutorials/security/ns-level-pss). If you are running a version of Kubernetes other than v{{< skew currentVersion >}}, check the documentation for that version. diff --git a/content/en/docs/tutorials/security/ns-level-pss.md b/content/en/docs/tutorials/security/ns-level-pss.md index 4a20895df7..43a48d0932 100644 --- a/content/en/docs/tutorials/security/ns-level-pss.md +++ b/content/en/docs/tutorials/security/ns-level-pss.md @@ -17,7 +17,7 @@ one namespace at a time. You can also apply Pod Security Standards to multiple namespaces at once at the cluster level. For instructions, refer to -[Apply Pod Security Standards at the cluster level](/docs/tutorials/security/cluster-level-pss). +[Apply Pod Security Standards at the cluster level](/docs/tutorials/security/cluster-level-pss/). ## {{% heading "prerequisites" %}} diff --git a/content/en/docs/tutorials/stateful-application/zookeeper.md b/content/en/docs/tutorials/stateful-application/zookeeper.md index cc2bd853f6..3f57ab3ad4 100644 --- a/content/en/docs/tutorials/stateful-application/zookeeper.md +++ b/content/en/docs/tutorials/stateful-application/zookeeper.md @@ -123,7 +123,7 @@ zk-2 1/1 Running 0 40s ``` The StatefulSet controller creates three Pods, and each Pod has a container with -a [ZooKeeper](https://www-us.apache.org/dist/zookeeper/stable/) server. +a [ZooKeeper](https://archive.apache.org/dist/zookeeper/stable/) server. ### Facilitating leader election @@ -305,7 +305,7 @@ numChildren = 0 ### Providing durable storage -As mentioned in the [ZooKeeper Basics](#zookeeper-basics) section, +As mentioned in the [ZooKeeper Basics](#zookeeper) section, ZooKeeper commits all entries to a durable WAL, and periodically writes snapshots in memory state, to storage media. Using WALs to provide durability is a common technique for applications that use consensus protocols to achieve a replicated diff --git a/content/en/releases/release.md b/content/en/releases/release.md index 6775401a11..af08831dac 100644 --- a/content/en/releases/release.md +++ b/content/en/releases/release.md @@ -136,7 +136,7 @@ The general labeling process should be consistent across artifact types. ## The Release Cycle -![Image of one Kubernetes release cycle](release-cycle.jpg) +![Image of one Kubernetes release cycle](/images/releases/release-cycle.jpg) Kubernetes releases currently happen approximately three times per year. @@ -204,7 +204,7 @@ back to the release branch. The release is built from the release branch. Each release is part of a broader Kubernetes lifecycle: -![Image of Kubernetes release lifecycle spanning three releases](release-lifecycle.jpg) +![Image of Kubernetes release lifecycle spanning three releases](/images/releases/release-lifecycle.jpg) ## Removal Of Items From The Milestone diff --git a/content/fr/docs/reference/kubectl/cheatsheet.md b/content/fr/docs/reference/kubectl/cheatsheet.md index a50eb8f320..e1d86f7dac 100644 --- a/content/fr/docs/reference/kubectl/cheatsheet.md +++ b/content/fr/docs/reference/kubectl/cheatsheet.md @@ -36,7 +36,7 @@ Vous pouvez de plus déclarer un alias pour `kubectl` qui fonctionne aussi avec ```bash alias k=kubectl -complete -F __start_kubectl k +complete -o default -F __start_kubectl k ``` ### ZSH diff --git a/content/fr/docs/tasks/tools/install-kubectl.md b/content/fr/docs/tasks/tools/install-kubectl.md index 2d57145edd..651b224987 100644 --- a/content/fr/docs/tasks/tools/install-kubectl.md +++ b/content/fr/docs/tasks/tools/install-kubectl.md @@ -363,7 +363,7 @@ Vous devez maintenant vérifier que le script de completion de kubectl est bien ```shell echo 'alias k=kubectl' >>~/.bashrc - echo 'complete -F __start_kubectl k' >>~/.bashrc + echo 'complete -o default -F __start_kubectl k' >>~/.bashrc ``` {{< note >}} @@ -431,7 +431,7 @@ Si vous n'avez pas installé via Homebrew, vous devez maintenant vous assurer qu ```shell echo 'alias k=kubectl' >>~/.bashrc - echo 'complete -F __start_kubectl k' >>~/.bashrc + echo 'complete -o default -F __start_kubectl k' >>~/.bashrc ``` Si vous avez installé kubectl avec Homebrew (comme expliqué [ici](#installer-avec-homebrew-sur-macos)), alors le script de complétion a été automatiquement installé dans `/usr/local/etc/bash_completion.d/kubectl`. Dans ce cas, vous n'avez rien à faire. diff --git a/content/ja/docs/concepts/cluster-administration/addons.md b/content/ja/docs/concepts/cluster-administration/addons.md index 70619ab3c1..f1740c56c8 100644 --- a/content/ja/docs/concepts/cluster-administration/addons.md +++ b/content/ja/docs/concepts/cluster-administration/addons.md @@ -17,19 +17,20 @@ content_type: concept * [ACI](https://www.github.com/noironetworks/aci-containers)は、統合されたコンテナネットワークとネットワークセキュリティをCisco ACIを使用して提供します。 * [Antrea](https://antrea.io/)は、L3またはL4で動作して、Open vSwitchをネットワークデータプレーンとして活用する、Kubernetes向けのネットワークとセキュリティサービスを提供します。 -* [Calico](https://docs.projectcalico.org/latest/introduction/)はネットワークとネットワークプリシーのプロバイダーです。Calicoは、BGPを使用または未使用の非オーバーレイおよびオーバーレイネットワークを含む、フレキシブルなさまざまなネットワークオプションをサポートします。Calicoはホスト、Pod、そして(IstioとEnvoyを使用している場合には)サービスメッシュ上のアプリケーションに対してネットワークポリシーを強制するために、同一のエンジンを使用します。 -* [Canal](https://github.com/tigera/canal/tree/master/k8s-install)はFlannelとCalicoをあわせたもので、ネットワークとネットワークポリシーを提供します。 +* [Calico](https://docs.projectcalico.org/latest/introduction/)はネットワークとネットワークポリシーのプロバイダーです。Calicoは、BGPを使用または未使用の非オーバーレイおよびオーバーレイネットワークを含む、フレキシブルなさまざまなネットワークオプションをサポートします。Calicoはホスト、Pod、そして(IstioとEnvoyを使用している場合には)サービスメッシュ上のアプリケーションに対してネットワークポリシーを強制するために、同一のエンジンを使用します。 +* [Canal](https://projectcalico.docs.tigera.io/getting-started/kubernetes/flannel/flannel)はFlannelとCalicoをあわせたもので、ネットワークとネットワークポリシーを提供します。 * [Cilium](https://github.com/cilium/cilium)は、L3のネットワークとネットワークポリシーのプラグインで、HTTP/API/L7のポリシーを透過的に強制できます。ルーティングとoverlay/encapsulationモードの両方をサポートしており、他のCNIプラグイン上で機能できます。 -* [CNI-Genie](https://github.com/Huawei-PaaS/CNI-Genie)は、KubernetesをCalico、Canal、Flannel、Romana、Weaveなど選択したCNIプラグインをシームレスに接続できるようにするプラグインです。 +* [CNI-Genie](https://github.com/cni-genie/CNI-Genie)は、KubernetesをCalico、Canal、Flannel、Weaveなど選択したCNIプラグインをシームレスに接続できるようにするプラグインです。 +* [Contiv](https://contivpp.io/)は、さまざまなユースケースと豊富なポリシーフレームワーク向けに設定可能なネットワーク(BGPを使用したネイティブのL3、vxlanを使用したオーバーレイ、古典的なL2、Cisco-SDN/ACI)を提供します。Contivプロジェクトは完全に[オープンソース](https://github.com/contiv)です。[インストーラー](https://github.com/contiv/install)はkubeadmとkubeadm以外の両方をベースとしたインストールオプションがあります。 * [Contrail](https://www.juniper.net/us/en/products-services/sdn/contrail/contrail-networking/)は、[Tungsten Fabric](https://tungsten.io)をベースにしている、オープンソースでマルチクラウドに対応したネットワーク仮想化およびポリシー管理プラットフォームです。ContrailおよびTungsten Fabricは、Kubernetes、OpenShift、OpenStack、Mesosなどのオーケストレーションシステムと統合されており、仮想マシン、コンテナ/Pod、ベアメタルのワークロードに隔離モードを提供します。 * [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually)は、Kubernetesで使用できるオーバーレイネットワークプロバイダーです。 * [Knitter](https://github.com/ZTE/Knitter/)は、1つのKubernetes Podで複数のネットワークインターフェイスをサポートするためのプラグインです。 -* Multus は、すべてのCNIプラグイン(たとえば、Calico、Cilium、Contiv、Flannel)に加えて、SRIOV、DPDK、OVS-DPDK、VPPをベースとするKubernetes上のワークロードをサポートする、複数のネットワークサポートのためのマルチプラグインです。 -* [OVN-Kubernetes](https://github.com/ovn-org/ovn-kubernetes/)は、Open vSwitch(OVS)プロジェクトから生まれた仮想ネットワーク実装である[OVN(Open Virtual Network)](https://github.com/ovn-org/ovn/)をベースとする、Kubernetesのためのネットワークプロバイダです。OVN-Kubernetesは、OVSベースのロードバランサーおよびネットワークポリシーの実装を含む、Kubernetes向けのオーバーレイベースのネットワーク実装を提供します。 +* [Multus](https://github.com/k8snetworkplumbingwg/multus-cni)は、すべてのCNIプラグイン(たとえば、Calico、Cilium、Contiv、Flannel)に加えて、SRIOV、DPDK、OVS-DPDK、VPPをベースとするKubernetes上のワークロードをサポートする、複数のネットワークサポートのためのマルチプラグインです。 +* [OVN-Kubernetes](https://github.com/ovn-org/ovn-kubernetes/)は、Open vSwitch(OVS)プロジェクトから生まれた仮想ネットワーク実装である[OVN(Open Virtual Network)](https://github.com/ovn-org/ovn/)をベースとする、Kubernetesのためのネットワークプロバイダーです。OVN-Kubernetesは、OVSベースのロードバランサーおよびネットワークポリシーの実装を含む、Kubernetes向けのオーバーレイベースのネットワーク実装を提供します。 * [OVN4NFV-K8S-Plugin](https://github.com/opnfv/ovn4nfv-k8s-plugin)は、クラウドネイティブベースのService function chaining(SFC)、Multiple OVNオーバーレイネットワーク、動的なサブネットの作成、動的な仮想ネットワークの作成、VLANプロバイダーネットワーク、Directプロバイダーネットワークを提供し、他のMulti-networkプラグインと付け替え可能なOVNベースのCNIコントローラープラグインです。 -* [NSX-T](https://docs.vmware.com/en/VMware-NSX-T/2.0/nsxt_20_ncp_kubernetes.pdf) Container Plug-in(NCP)は、VMware NSX-TとKubernetesなどのコンテナオーケストレーター間のインテグレーションを提供します。また、NSX-Tと、Pivotal Container Service(PKS)とOpenShiftなどのコンテナベースのCaaS/PaaSプラットフォームとのインテグレーションも提供します。 +* [NSX-T](https://docs.vmware.com/en/VMware-NSX-T-Data-Center/index.html) Container Plug-in(NCP)は、VMware NSX-TとKubernetesなどのコンテナオーケストレーター間のインテグレーションを提供します。また、NSX-Tと、Pivotal Container Service(PKS)とOpenShiftなどのコンテナベースのCaaS/PaaSプラットフォームとのインテグレーションも提供します。 * [Nuage](https://github.com/nuagenetworks/nuage-kubernetes/blob/v5.1.1-1/docs/kubernetes-1-installation.rst)は、Kubernetes Podと非Kubernetes環境間で可視化とセキュリティモニタリングを使用してポリシーベースのネットワークを提供するSDNプラットフォームです。 -* [Romana](https://github.com/romana/romana)は、[NetworkPolicy API](/ja/docs/concepts/services-networking/network-policies/)もサポートするPodネットワーク向けのL3のネットワークソリューションです。Kubeadmアドオンのインストールの詳細は[こちら](https://github.com/romana/romana/tree/master/containerize)で確認できます。 +* [Romana](https://github.com/romana)は、[NetworkPolicy](/ja/docs/concepts/services-networking/network-policies/) APIもサポートするPodネットワーク向けのL3のネットワークソリューションです。 * [Weave Net](https://www.weave.works/docs/net/latest/kubernetes/kube-addon/)は、ネットワークパーティションの両面で機能し、外部データベースを必要とせずに、ネットワークとネットワークポリシーを提供します。 ## サービスディスカバリ @@ -44,6 +45,7 @@ content_type: concept ## インフラストラクチャ * [KubeVirt](https://kubevirt.io/user-guide/#/installation/installation)は仮想マシンをKubernetes上で実行するためのアドオンです。通常、ベアメタルのクラスタで実行します。 +* [node problem detector](https://github.com/kubernetes/node-problem-detector)はLinuxノード上で動作し、システムの問題を[Event](/docs/reference/kubernetes-api/cluster-resources/event-v1/)または[ノードのCondition](/ja/docs/concepts/architecture/nodes/#condition)として報告します。 ## レガシーなアドオン diff --git a/content/ko/blog/_posts/2020-12-02-dont-panic-kubernetes-and-docker.md b/content/ko/blog/_posts/2020-12-02-dont-panic-kubernetes-and-docker.md index d540565187..13e137f3b5 100644 --- a/content/ko/blog/_posts/2020-12-02-dont-panic-kubernetes-and-docker.md +++ b/content/ko/blog/_posts/2020-12-02-dont-panic-kubernetes-and-docker.md @@ -3,6 +3,13 @@ layout: blog title: "당황하지 마세요. 쿠버네티스와 도커" date: 2020-12-02 slug: dont-panic-kubernetes-and-docker +evergreen: true +--- + +**업데이트:** _쿠버네티스의 `dockershim`을 통한 도커 지원이 제거되었습니다. +더 자세한 정보는 [제거와 관련된 자주 묻는 질문](/dockershim/)을 참고하세요. +또는 지원 중단에 대한 [GitHub 이슈](https://github.com/kubernetes/kubernetes/issues/106917)에서 논의를 할 수도 있습니다._ + --- **저자:** Jorge Castro, Duffie Cooley, Kat Cosgrove, Justin Garrison, Noah Kantrowitz, Bob Killen, Rey Lejano, Dan “POP” Papandrea, Jeffrey Sica, Davanum “Dims” Srinivas @@ -10,8 +17,7 @@ slug: dont-panic-kubernetes-and-docker **번역:** 박재화(삼성SDS), 손석호(한국전자통신연구원) 쿠버네티스는 v1.20 이후 컨테이너 런타임으로서 -[도커를 -사용 중단(deprecating)](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md#deprecation)합니다. +[도커를 사용 중단(deprecating)](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md#deprecation)합니다. **당황할 필요는 없습니다. 말처럼 극적이진 않습니다.** @@ -26,7 +32,7 @@ slug: dont-panic-kubernetes-and-docker 빌드하는 데 유용한 도구이며, `docker build` 실행 결과로 만들어진 이미지도 여전히 쿠버네티스 클러스터에서 동작합니다. -GKE, EKS 또는 AKS([containerd가 기본](https://github.com/Azure/AKS/releases/tag/2020-11-16)인)와 같은 관리형 쿠버네티스 서비스를 +AKS, EKS 또는 GKE와 같은 관리형 쿠버네티스 서비스를 사용하는 경우 쿠버네티스의 향후 버전에서 도커에 대한 지원이 없어지기 전에, 워커 노드가 지원되는 컨테이너 런타임을 사용하고 있는지 확인해야 합니다. 노드에 사용자 정의가 적용된 경우 사용자 환경 및 런타임 요구 사항에 따라 업데이트가 필요할 수도 @@ -35,8 +41,8 @@ GKE, EKS 또는 AKS([containerd가 기본](https://github.com/Azure/AKS/releases 자체 클러스터를 운영하는 경우에도, 클러스터의 고장을 피하기 위해서 변경을 수행해야 합니다. v1.20에서는 도커에 대한 지원 중단 경고(deprecation warning)가 표시됩니다. -도커 런타임 지원이 쿠버네티스의 향후 릴리스(현재는 2021년 하반기의 -1.22 릴리스로 계획됨)에서 제거되면 더 이상 지원되지 +도커 런타임 지원이 쿠버네티스의 향후 릴리스(현재는 2021년 하반기의 +1.22 릴리스로 계획됨)에서 제거되면 더 이상 지원되지 않으며, containerd 또는 CRI-O와 같은 다른 호환 컨테이너 런타임 중 하나로 전환해야 합니다. 선택한 런타임이 현재 사용 중인 도커 데몬 구성(예: 로깅)을 지원하는지 확인하세요. @@ -103,4 +109,4 @@ containerd가 정말 필요로 하는 것들을 확보하기 위해서 도커심 모든 사람이 다가오는 변경 사항에 대해 최대한 많은 교육을 받을 수 있도록 하는 것입니다. 이 글이 여러분이 가지는 대부분의 질문에 대한 답이 되었고, 불안을 약간은 진정시켰기를 바랍니다! ❤️ -더 많은 답변을 찾고 계신가요? 함께 제공되는 [도커심 사용 중단 FAQ](/blog/2020/12/02/dockershim-faq/)를 확인하세요. +더 많은 답변을 찾고 계신가요? 함께 제공되는 [도커심 제거 FAQ](/blog/2022/02/17/dockershim-faq/)(2022년 2월에 갱신됨)를 확인하세요. diff --git a/content/ko/blog/_posts/2021-08-04-kubernetes-release-1.22.md b/content/ko/blog/_posts/2021-08-04-kubernetes-release-1.22.md index d6df46ac55..c67cc47ea1 100644 --- a/content/ko/blog/_posts/2021-08-04-kubernetes-release-1.22.md +++ b/content/ko/blog/_posts/2021-08-04-kubernetes-release-1.22.md @@ -3,6 +3,7 @@ layout: blog title: '쿠버네티스 1.22: 새로운 정점에 도달(Reaching New Peaks)' date: 2021-08-04 slug: kubernetes-1-22-release-announcement +evergreen: true --- **저자:** [쿠버네티스 1.22 릴리스 팀](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.22/release-team.md) @@ -50,7 +51,7 @@ SIG Windows는 계속해서 성장하는 개발자 커뮤니티를 지원하기 ### 기본(default) seccomp 프로파일 -알파 기능인 기본 seccomp 프로파일이 신규 커맨드라인 플래그 및 설정과 함께 kubelet에 추가되었습니다. 이 신규 기능을 사용하면, `Unconfined`대신 `RuntimeDefault` seccomp 프로파일을 기본으로 사용하는 seccomp이 클러스터 전반에서 기본이 됩니다. 이는 쿠버네티스 디플로이먼트(Deployment)의 기본 보안을 강화합니다. 워크로드에 대한 보안이 기본으로 더 강화되었으므로, 이제 보안 관리자도 조금 더 안심하고 쉴 수 있습니다. 이 기능에 대한 자세한 사항은 공식적인 [seccomp 튜토리얼](https://kubernetes.io/docs/tutorials/clusters/seccomp/#enable-the-use-of-runtimedefault-as-the-default-seccomp-profile-for-all-workloads)을 참고하시기 바랍니다. +알파 기능인 기본 seccomp 프로파일이 신규 커맨드라인 플래그 및 설정과 함께 kubelet에 추가되었습니다. 이 신규 기능을 사용하면, `Unconfined`대신 `RuntimeDefault` seccomp 프로파일을 기본으로 사용하는 seccomp이 클러스터 전반에서 기본이 됩니다. 이는 쿠버네티스 디플로이먼트(Deployment)의 기본 보안을 강화합니다. 워크로드에 대한 보안이 기본으로 더 강화되었으므로, 이제 보안 관리자도 조금 더 안심하고 쉴 수 있습니다. 이 기능에 대한 자세한 사항은 공식적인 [seccomp 튜토리얼](/docs/tutorials/security/seccomp/#enable-the-use-of-runtimedefault-as-the-default-seccomp-profile-for-all-workloads)을 참고하시기 바랍니다. ### kubeadm을 통한 보안성이 더 높은 컨트롤 플레인 diff --git a/content/ko/community/_index.html b/content/ko/community/_index.html index 30ede236bc..867916e208 100644 --- a/content/ko/community/_index.html +++ b/content/ko/community/_index.html @@ -1,257 +1,183 @@ --- -title: 커뮤니티 +title: Community layout: basic cid: community +community_styles_migrated: true --- + -

-
- 쿠버네티스 컨퍼런스 갤러리 - 쿠버네티스 컨퍼런스 갤러리 +
+

사용자, 기여자, 그리고 우리가 함께 구축한 문화를 통해 구성된 쿠버네티스 커뮤니티는 + 본 오픈소스 프로젝트가 급부상하는 가장 큰 이유 중 하나입니다. + 프로젝트 자체가 성장하고 변화함에 따라 + 우리의 문화와 가치관 또한 지속적으로 성장하고 변화하고 있습니다. + 우리 모두는 프로젝트와 작업 방식을 지속적으로 개선하기 위해 함께 노력합니다.

+

우리는 이슈(issue)와 풀 리퀘스트(pull request)를 제출하고, SIG 미팅과 쿠버네티스 모임 그리고 KubeCon에 참석하고, + 도입(adoption)과 혁신(innovation)을 지지하며, + kubectl get pods 를 실행하고, + 다른 수천가지 중요한 방법으로 기여하는 사람들 입니다. + 어떻게 하면 이 놀라운 공동체의 일부가 될 수 있는지 계속 읽어보세요.

-
-
-

사용자, 기여자, 그리고 우리가 함께 구축한 문화를 통해 구성된 쿠버네티스 커뮤니티는 본 오픈소스 프로젝트가 급부상하는 가장 큰 이유 중 하나입니다. 프로젝트 자체가 성장하고 변화함에 따라 우리의 문화와 가치관 또한 지속적으로 성장하고 변화하고 있습니다. 우리 모두는 프로젝트와 작업 방식을 지속적으로 개선하기 위해 함께 노력합니다. -

우리는 이슈(issue)와 풀 리퀘스트(pull request)를 제출하고, SIG 미팅과 쿠버네티스 모임 그리고 KubeCon에 참석하고, 도입(adoption)과 혁신(innovation)을 지지하며, kubectl get pods 를 실행하고, 다른 수천가지 중요한 방법으로 기여하는 사람들 입니다. 어떻게 하면 이 놀라운 공동체의 일부가 될 수 있는지 계속 읽어보세요.

-
-
- -
- -기여자 커뮤니티      -커뮤니티 가치      -행동 강령       -비디오      -토론      -이벤트와 모임들      -새소식      -릴리즈 - -
-

-
-
-
- 쿠버네티스 컨퍼런스 갤러리 +