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

Merge branch 'kubernetes:main' into main

Browse Source
This commit is contained in:
Mahé
2022-03-02 19:23:58 +01:00
committed by GitHub
parent e00fe1d2cb 2cb30790dd
commit 876f452d0e
346 changed files with 18678 additions and 9179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README-de.md
+13 -13
View File
@@ -3,13 +3,13 @@
[![Build Status](https://api.travis-ci.org/kubernetes/website.svg?branch=master)](https://travis-ci.org/kubernetes/website)
[![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest)
Herzlich willkommen! Dieses Repository enthält alle Assets, die zur Erstellung der [Kubernetes-Website und Dokumentation](https://kubernetes.io/) erforderlich sind. Wir freuen uns sehr, dass Sie dazu beitragen wollen!
Herzlich Willkommen! Dieses Repository enthält alle Assets, die zur Erstellung der [Kubernetes-Website und Dokumentation](https://kubernetes.io/) erforderlich sind. Wir freuen uns sehr, dass Sie dazu beitragen wollen!
## Beiträge zur Dokumentation
Sie können auf die Schaltfläche **Fork** im oberen rechten Bereich des Bildschirms klicken, um eine Kopie dieses Repositorys in Ihrem GitHub-Konto zu erstellen. Diese Kopie wird als *Fork* bezeichnet. Nehmen Sie die gewünschten Änderungen an Ihrem Fork vor. Wenn Sie bereit sind, diese Änderungen an uns zu senden, gehen Sie zu Ihrem Fork und erstellen Sie eine neue Pull-Anforderung, um uns darüber zu informieren.
Sie können auf die Schaltfläche **Fork** im oberen rechten Bereich des Bildschirms klicken, um eine Kopie dieses Repositorys in Ihrem GitHub-Konto zu erstellen. Diese Kopie wird als *Fork* bezeichnet. Nehmen Sie die gewünschten Änderungen an Ihrem Fork vor. Wenn Sie bereit sind, diese Änderungen an uns zu senden, gehen Sie zu Ihrem Fork und erstellen Sie eine neue Pull-Request, um uns darüber zu informieren.
Sobald Ihre Pull-Anfrage erstellt wurde, übernimmt ein Rezensent von Kubernetes die Verantwortung für klares, umsetzbares Feedback. Als Eigentümer des Pull-Request **liegt es in Ihrer Verantwortung Ihren Pull-Reqest entsprechend des Feedbacks, dass Sie vom Kubernetes-Reviewer erhalten haben abzuändern.** Beachten Sie auch, dass Sie am Ende mehr als einen Rezensenten von Kubernetes erhalten, der Ihnen Feedback gibt, oder dass Sie Rückmeldungen von einem Rezensenten von Kubernetes erhalten, der sich von demjenigen unterscheidet, der ursprünglich für das Feedback zugewiesen wurde. In einigen Fällen kann es vorkommen, dass einer Ihrer Prüfer bei Bedarf eine technische Überprüfung von einem [Kubernetes Tech-Reviewer](https://github.com/kubernetes/website/wiki/tech-reviewers) anfordert. Reviewer geben ihr Bestes, um zeitnah Feedback zu geben, die Antwortzeiten können jedoch je nach den Umständen variieren.
Sobald Ihre Pull-Request erstellt wurde, übernimmt ein Rezensent von Kubernetes die Verantwortung für klares, umsetzbares Feedback. Als Eigentümer des Pull-Request **liegt es in Ihrer Verantwortung Ihre Pull-Request entsprechend des Feedbacks, welches Sie vom Kubernetes-Reviewer erhalten haben, abzuändern.** Beachten Sie auch, dass Sie am Ende mehr als einen Rezensenten von Kubernetes erhalten, der Ihnen Feedback gibt, oder dass Sie Rückmeldungen von einem Rezensenten von Kubernetes erhalten, der sich von demjenigen unterscheidet, der ursprünglich für das Feedback zugewiesen wurde. In einigen Fällen kann es vorkommen, dass einer Ihrer Prüfer bei Bedarf eine technische Überprüfung von einem [Kubernetes Tech-Reviewer](https://github.com/kubernetes/website/wiki/tech-reviewers) anfordert. Reviewer geben ihr Bestes, um zeitnah Feedback zu geben, die Antwortzeiten können jedoch je nach den Umständen variieren.
Weitere Informationen zum Beitrag zur Kubernetes-Dokumentation finden Sie unter:
@@ -28,14 +28,14 @@ Die Betreuer der deutschen Lokalisierung erreichen Sie unter:
* Max Körbächer ([@mkorbi](https://github.com/mkorbi))
* [Slack Kanal](https://kubernetes.slack.com/messages/kubernetes-docs-de)
## Site lokal mit Docker ausführen
## Website lokal mit Docker ausführen
Um die Kubernetes-Website lokal laufen zu lassen, empfiehlt es sich, ein spezielles [Docker](https://docker.com) Image auszuführen, das den statischen Site-Generator [Hugo](https://gohugo.io) enthält.
Um die Kubernetes-Website lokal laufen zu lassen, empfiehlt es sich, ein spezielles [Docker](https://docker.com) Image auszuführen, das den statischen Website-Generator [Hugo](https://gohugo.io) enthält.
> Unter Windows benötigen Sie einige weitere Tools, die Sie mit [Chocolatey](https://chocolatey.org) installieren können.
`choco install make`
> Wenn Sie die Website lieber lokal ohne Docker ausführen möchten, finden Sie weitere Informationen unter [Website lokal mit Hugo ausführen](#Die-Site-lokal-mit-Hugo-ausführen).
> Wenn Sie die Website lieber lokal ohne Docker ausführen möchten, finden Sie weitere Informationen unter [Website lokal mit Hugo ausführen](#Die-Website-lokal-mit-Hugo-ausführen).
Das benötigte [Docsy Hugo theme](https://github.com/google/docsy#readme) muss als git submodule installiert werden:
@@ -50,26 +50,26 @@ Wenn Sie Docker [installiert](https://www.docker.com/get-started) haben, erstell
make container-image
```
Nachdem das Image erstellt wurde, können Sie die Site lokal ausführen:
Nachdem das Image erstellt wurde, können Sie die Website lokal öffnen:
```bash
make container-serve
```
Öffnen Sie Ihren Browser unter http://localhost:1313, um die Site anzuzeigen. Wenn Sie Änderungen an den Quelldateien vornehmen, aktualisiert Hugo die Site und erzwingt eine Browseraktualisierung.
Öffnen Sie Ihren Browser unter http://localhost:1313, um die Website anzuzeigen. Wenn Sie Änderungen an den Quelldateien vornehmen, aktualisiert Hugo die Website und erzwingt eine Browseraktualisierung.
## Die Site lokal mit Hugo ausführen
## Die Website lokal mit Hugo ausführen
Hugo-Installationsanweisungen finden Sie in der [offiziellen Hugo-Dokumentation](https://gohugo.io/getting-started/installing/). Stellen Sie sicher, dass Sie die Hugo-Version installieren, die in der Umgebungsvariablen `HUGO_VERSION` in der Datei [`netlify.toml`](netlify.toml#L9) angegeben ist.
Das benötigte [Docsy Hugo theme](https://github.com/google/docsy#readme) muss als git submodule installiert werden:
Das benötigte [Docsy Hugo-Theme](https://github.com/google/docsy#readme) muss als git submodule installiert werden:
```
#Füge das Docsy submodule hinzu
git submodule update --init --recursive --depth 1
```
So führen Sie die Site lokal aus, wenn Sie Hugo installiert haben:
So führen Sie die Website lokal aus, wenn Sie Hugo installiert haben:
```bash
# Installieren der JavaScript Abhängigkeiten
@@ -77,7 +77,7 @@ npm ci
make serve
```
Dadurch wird der lokale Hugo-Server an Port 1313 gestartet. Öffnen Sie Ihren Browser unter http://localhost:1313, um die Site anzuzeigen. Wenn Sie Änderungen an den Quelldateien vornehmen, aktualisiert Hugo die Site und erzwingt eine Browseraktualisierung.
Dadurch wird der lokale Hugo-Server an Port 1313 gestartet. Öffnen Sie Ihren Browser unter http://localhost:1313, um die Website anzuzeigen. Wenn Sie Änderungen an den Quelldateien vornehmen, aktualisiert Hugo die Website und erzwingt eine Browseraktualisierung.
## Community, Diskussion, Beteiligung und Unterstützung
@@ -94,4 +94,4 @@ Die Teilnahme an der Kubernetes-Community unterliegt dem [Kubernetes-Verhaltensk
## Vielen Dank!
Kubernetes lebt vom Community Engagement und wir freuen uns sehr über Ihre Beiträge zu unserer Website und unserer Dokumentation!
Kubernetes lebt vom Community-Engagement und wir freuen uns sehr über Ihre Beiträge zu unserer Website und unserer Dokumentation!
assets/scss/_custom.scss
+32 -2
View File
@@ -329,6 +329,11 @@ main {
.td-content>table td {
word-break: break-word;
}
table.no-word-break td,
table.no-word-break code {
word-break: normal;
}
}
@@ -396,16 +401,24 @@ body {
}
.deprecation-warning, .pageinfo.deprecation-warning {
padding: 20px;
margin: 20px 0;
padding: clamp(10px, 2vmin, 20px);
margin: clamp(10px, 1vh, 20px) 0;
background-color: #faf5b6;
color: #000;
}
.deprecation-warning.outdated-blog, .pageinfo.deprecation-warning.outdated-blog {
background-color: $blue;
color: $white;
}
body.td-home .deprecation-warning, body.td-blog .deprecation-warning, body.td-documentation .deprecation-warning {
border-radius: 3px;
}
.deprecation-warning p:only-child {
margin-bottom: 0;
}
.td-documentation .td-content > .highlight {
max-width: initial;
@@ -766,6 +779,10 @@ figure {
max-width: clamp(0vw, 95vw, 100%);
max-height: calc(80vh - 8rem);
}
figure + noscript > *{
max-width: calc(max(100%, 100vw));
}
}
@media only screen and (min-width: 768px) {
@@ -788,6 +805,9 @@ figure {
max-height: calc(100vh - 10rem);
}
}
figure + noscript > * {
max-width: 80%;
}
}
// Indent definition lists
@@ -820,3 +840,13 @@ dl {
margin-bottom: 1em;
}
}
.no-js .mermaid {
display: none;
}
div.alert > em.javascript-required {
display: inline-block;
min-height: 1.5em;
margin: calc(max(4em, ( 8vh + 4em ) / 2)) 0 0.25em 0;
}
assets/scss/_reset.scss
Executable → Regular
View File
assets/scss/_skin.scss
Executable → Regular
View File
content/en/blog/_posts/2019-12-09-kubernetes-1.17-release-announcement.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: "Kubernetes 1.17: Stability"
date: 2019-12-09T13:00:00-08:00
slug: kubernetes-1-17-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.17 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.17/release_team.md)
content/en/blog/_posts/2020-03-25-kubernetes-1.18-release-announcement.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.18: Fit & Finish'
date: 2020-03-25
slug: kubernetes-1-18-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.18 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.18/release_team.md)
content/en/blog/_posts/2020-08-26-kubernetes-release-1.19.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.19: Accentuate the Paw-sitive'
date: 2020-08-26
slug: kubernetes-release-1.19-accentuate-the-paw-sitive
evergreen: true
---
**Authors:** [Kubernetes 1.19 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.19/release_team.md)
content/en/blog/_posts/2020-09-03-warnings/index.md
+2 -5
View File
@@ -3,9 +3,10 @@ layout: blog
title: "Warning: Helpful Warnings Ahead"
date: 2020-09-03
slug: warnings
evergreen: true
---
**Author**: Jordan Liggitt (Google)
**Author**: [Jordan Liggitt](https://github.com/liggitt) (Google)
As Kubernetes maintainers, we're always looking for ways to improve usability while preserving compatibility.
As we develop features, triage bugs, and answer support questions, we accumulate information that would be helpful for Kubernetes users to know.
@@ -327,7 +328,3 @@ A couple areas we're looking at next are warning about [known problematic values
we cannot reject outright for compatibility reasons, and warning about use of deprecated fields or field values
(like selectors using beta os/arch node labels, [deprecated in v1.14](/docs/reference/labels-annotations-taints/#beta-kubernetes-io-arch-deprecated)).
I'm excited to see progress in this area, continuing to make it easier to use Kubernetes.
---
_[Jordan Liggitt](https://twitter.com/liggitt) is a software engineer at Google, and helps lead Kubernetes authentication, authorization, and API efforts._
content/en/blog/_posts/2020-12-02-dockershim-faq.md
+3 -1
View File
@@ -3,9 +3,11 @@ layout: blog
title: "Dockershim Deprecation FAQ"
date: 2020-12-02
slug: dockershim-faq
aliases: [ '/dockershim' ]
---
_**Update**: There is a [newer version](/blog/2022/02/17/dockershim-faq/) of this article available._
This document goes over some frequently asked questions regarding the Dockershim
deprecation announced as a part of the Kubernetes v1.20 release. For more detail
on the deprecation of Docker as a container runtime for Kubernetes kubelets, and
content/en/blog/_posts/2020-12-02-dont-panic-kubernetes-and-docker.md
+1 -1
View File
@@ -101,4 +101,4 @@ questions regardless of experience level or complexity! Our goal is to make sure
everyone is educated as much as possible on the upcoming changes. We hope
this has answered most of your questions and soothed some anxieties! ❤️
Looking for more answers? Check out our accompanying [Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/).
Looking for more answers? Check out our accompanying [Dockershim Removal FAQ](/blog/2022/02/17/dockershim-faq/) _(updated February 2022)_.
content/en/blog/_posts/2020-12-08-kubernetes-release-1.20.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.20: The Raddest Release'
date: 2020-12-08
slug: kubernetes-1-20-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.20 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.20/release_team.md)
content/en/blog/_posts/2021-04-08-kubernetes-release-1.21.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.21: Power to the Community'
date: 2021-04-08
slug: kubernetes-1-21-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.21 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.21/release-team.md)
content/en/blog/_posts/2021-08-04-kubernetes-release-1.22.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.22: Reaching New Peaks'
date: 2021-08-04
slug: kubernetes-1-22-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.22 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.22/release-team.md)
content/en/blog/_posts/2021-08-30-volume-populators-alpha.md
+5 -4
View File
@@ -96,15 +96,16 @@ out.
First install the volume-data-source-validator controller.
```terminal
kubectl apply -f https://github.com/kubernetes-csi/volume-data-source-validator/blob/master/deploy/kubernetes/rbac-data-source-validator.yaml
kubectl apply -f https://github.com/kubernetes-csi/volume-data-source-validator/blob/master/deploy/kubernetes/setup-data-source-validator.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/volume-data-source-validator/master/client/config/crd/populator.storage.k8s.io_volumepopulators.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/volume-data-source-validator/master/deploy/kubernetes/rbac-data-source-validator.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/volume-data-source-validator/master/deploy/kubernetes/setup-data-source-validator.yaml
```
Next install the example populator.
```terminal
kubectl apply -f https://github.com/kubernetes-csi/lib-volume-populator/blob/master/example/hello-populator/crd.yaml
kubectl apply -f https://github.com/kubernetes-csi/lib-volume-populator/blob/master/example/hello-populator/deploy.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/lib-volume-populator/master/example/hello-populator/crd.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/lib-volume-populator/master/example/hello-populator/deploy.yaml
```
Create an instance of the `Hello` CR, with some text.
content/en/blog/_posts/2021-12-07-kubernetes-release-1.23.md
+1
View File
@@ -3,6 +3,7 @@ layout: blog
title: 'Kubernetes 1.23: The Next Frontier'
date: 2021-12-07
slug: kubernetes-1-23-release-announcement
evergreen: true
---
**Authors:** [Kubernetes 1.23 Release Team](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.23/release-team.md)
content/en/blog/_posts/2022-02-07-sig-multicluster-spotlight/index.md
+63
View File
@@ -0,0 +1,63 @@
---
layout: blog
title: "Spotlight on SIG Multicluster"
date: 2022-02-07
slug: sig-multicluster-spotlight-2022
canonicalUrl: https://www.kubernetes.dev/blog/2022/02/04/sig-multicluster-spotlight-2022/
---
**Authors:** Dewan Ahmed (Aiven) and Chris Short (AWS)
## Introduction
[SIG Multicluster](https://github.com/kubernetes/community/tree/master/sig-multicluster) is the SIG focused on how Kubernetes concepts are expanded and used beyond the cluster boundary. Historically, Kubernetes resources only interacted within that boundary - KRU or Kubernetes Resource Universe (not an actual Kubernetes concept). Kubernetes clusters, even now, don't really know anything about themselves or, about other clusters. Absence of cluster identifiers is a case in point. With the growing adoption of multicloud and multicluster deployments, the work SIG Multicluster doing is gaining a lot of attention. In this blog, [Jeremy Olmsted-Thompson, Google](https://twitter.com/jeremyot) and [Chris Short, AWS](https://twitter.com/ChrisShort) discuss the interesting problems SIG Multicluster is solving and how you can get involved. Their initials **JOT** and **CS** will be used for brevity.
## A summary of their conversation
**CS**: How long has the SIG Multicluster existed and how was the SIG in its infancy? How long have you been with this SIG?
**JOT**: I've been around for almost two years in the SIG Multicluster. All I know about the infancy years is from the lore but even in the early days, it was always about solving this same problem. Early efforts have been things like [KubeFed](https://github.com/kubernetes-sigs/kubefed). I think there are still folks using KubeFed but it's a smaller slice. Back then, I think people out there deploying large numbers of Kubernetes clusters were really not at a point where we had a ton of real concrete use cases. Projects like KubeFed and [Cluster Registry](https://github.com/kubernetes-retired/cluster-registry) were developed around that time and the need back then can be associated to these projects. The motivation for these projects were how do we solve the problems that we think people are **going to have**, when they start expanding to multiple clusters. Honestly, in some ways, it was trying to do too much at that time.
**CS**: How does KubeFed differ from the current state of SIG Multicluster? How does the **lore** differ from the **now**?
**JOT**: Yeah, it was like trying to get ahead of potential problems instead of addressing specific problems. I think towards the end of 2019, there was a slow down in SIG multicluster work and we kind of picked it back up with one of the most active recent projects that is the [SIG Multicluster services (MCS)](https://github.com/kubernetes-sigs/mcs-api).
Now this is the shift to solving real specific problems. For example,
> I've got workloads that are spread across multiple clusters and I need them to talk to each other.
Okay, that's very straightforward and we know that we need to solve that. To get started, let's make sure that these projects can work together on a common API so you get the same kind of portability that you get with Kubernetes.
There's a few implementations of the MCS API out there and more are being developed. But, we didn't build an implementation because depending on how you're deploying things there could be hundreds of implementations. As long as you only need the basic Multicluster service functionality, it'll just work on whatever background you want, whether it's Submariner, GKE, or a service mesh.
My favorite example of "then vs. now" is cluster ID. A few years ago, there was an effort to define a cluster ID. A lot of really good thought went into this concept, for example, how do we make a cluster ID is unique across multiple clusters. How do we make this ID globally unique so it'll work in every contact? Let's say, there's an acquisition or merger of teams - does the cluster IDs still remain unique for those teams?
With Multicluster services, we found the need for an actual cluster ID, and it has a very specific need. To address this specific need, we're no longer considering every single Kubernetes cluster out there rather the ClusterSets - a grouping of clusters that work together in some kind of bounds. That's a much narrower scope than considering clusters everywhere in time and space. It also leaves flexibility for an implementer to define the boundary (a ClusterSet) beyond which this cluster ID will no longer be unique.
**CS**: How do you feel about the current state of SIG Multicluster versus where you're hoping to be in future?
**JOT**: There's a few projects that are kind of getting started, for example, Work API. In the future, I think that some common practices around how do we deploy things across clusters are going to develop.
> If I have clusters deployed in a bunch of different regions; what's the best way to actually do that?
The answer is, almost always, "it depends". Why are you doing this? Is it because there's some kind of compliance that makes you care about locality? Is it performance? Is it availability?
I think revisiting registry patterns will probably be a natural step after we have cluster IDs, that is, how do you actually associate these clusters together? Maybe you've got a distributed deployment that you run in your own data centers all over the world. I imagine that expanding the API in that space is going to be important as more multi cluster features develop. It really depends on what the community starts doing with these tools.
**CS**: In the early days of Kubernetes, we used to have a few large Kubernetes clusters and now we're dealing with many small Kubernetes clusters - even multiple clusters for our own dev environments. How has this shift from a few large clusters to many small clusters affected the SIG? Has it accelerated the work or make it challenging in any way?
**JOT**: I think that it has created a lot of ambiguity that needs solving. Originally, you'd have a dev cluster, a staging cluster, and a prod cluster. When the multi region thing came in, we started needing dev/staging/prod clusters, per region. And then, sometimes clusters really need more isolation due to compliance or some regulations issues. Thus, we're ending up with a lot of clusters. I think figuring out the right balance on how many clusters should you actually have is important. The power of Kubernetes is being able to deploy a lot of things managed by a single control plane. So, it's not like every single workload that gets deployed should be in its own cluster. But I think it's pretty clear that we can't put every single workload in a single cluster.
**CS**: What are some of your favorite things about this SIG?
**JOT**: The complexity of the problems, the people and the newness of the space. We don't have right answers and we have to figure this out. At the beginning, we couldn't even think about multi clusters because there was no way to connect services across clusters. Now there is and we're starting to go tackle those problems, I think that this is a really fun place to be in because I expect that the SIG is going to get a lot busier the next couple of years. It's a very collaborative group and we definitely would like more people to come join us, get involved, raise their problems and bring their ideas.
**CS**: What do you think keeps people in this group? How has the pandemic affected you?
**JOT**: I think it definitely got a little bit quieter during the pandemic. But for the most part; it's a very distributed group so whether you're calling in to our weekly meetings from a conference room or from your home, it doesn't make that huge of a difference. During the pandemic, a lot of people had time to focus on what's next for their scale and growth. I think that's what keeps people in the group - we have real problems that need to be solved which are very new in this space. And it's fun :)
## Wrap up
**CS**: That's all we have for today. Thanks Jeremy for your time.
**JOT**: Thanks Chris. Everybody is welcome at our [bi-weekly meetings](https://github.com/kubernetes/community/tree/master/sig-multicluster#meetings). We love as many people to come as possible and welcome all questions and all ideas. It's a new space and it'd be great to grow the community.
content/en/blog/_posts/2022-02-16-sig-node-ci-subproject-celebrates/index.md
+192
View File
@@ -0,0 +1,192 @@
---
layout: blog
title: 'SIG Node CI Subproject Celebrates Two Years of Test Improvements'
date: 2022-02-16
slug: sig-node-ci-subproject-celebrates
canonicalUrl: https://www.kubernetes.dev/blog/2022/02/16/sig-node-ci-subproject-celebrates-two-years-of-test-improvements/
---
**Authors:** Sergey Kanzhelev (Google), Elana Hashman (Red Hat)
Ensuring the reliability of SIG Node upstream code is a continuous effort
that takes a lot of behind-the-scenes effort from many contributors.
There are frequent releases of Kubernetes, base operating systems,
container runtimes, and test infrastructure that result in a complex matrix that
requires attention and steady investment to "keep the lights on."
In May 2020, the Kubernetes node special interest group ("SIG Node") organized a new
subproject for continuous integration (CI) for node-related code and tests. Since its
inauguration, the SIG Node CI subproject has run a weekly meeting, and even the full hour
is often not enough to complete triage of all bugs, test-related PRs and issues, and discuss all
related ongoing work within the subgroup.
Over the past two years, we've fixed merge-blocking and release-blocking tests, reducing time to merge Kubernetes contributors' pull requests thanks to reduced test flakes. When we started, Node test jobs only passed 42% of the time, and through our efforts, we now ensure a consistent >90% job pass rate. We've closed 144 test failure issues and merged 176 pull requests just in kubernetes/kubernetes. And we've helped subproject participants ascend the Kubernetes contributor ladder, with 3 new org members, 6 new reviewers, and 2 new approvers.
The Node CI subproject is an approachable first stop to help new contributors
get started with SIG Node. There is a low barrier to entry for new contributors
to address high-impact bugs and test fixes, although there is a long
road before contributors can climb the entire contributor ladder:
it took over a year to establish two new approvers for the group.
The complexity of all the different components that power Kubernetes nodes
and its test infrastructure requires a sustained investment over a long period
for developers to deeply understand the entire system,
both at high and low levels of detail.
We have several regular contributors at our meetings, however; our reviewers
and approvers pool is still small. It is our goal to continue to grow
contributors to ensure a sustainable distribution of work
that does not just fall to a few key approvers.
It's not always obvious how subprojects within SIGs are formed, operate,
and work. Each is unique to its sponsoring SIG and tailored to the projects
that the group is intended to support. As a group that has welcomed many
first-time SIG Node contributors, we'd like to share some of the details and
accomplishments over the past two years,
helping to demystify our inner workings and celebrate the hard work
of all our dedicated contributors!
## Timeline
***May 2020.*** SIG Node CI group was formed on May 11, 2020, with more than
[30 volunteers](https://docs.google.com/document/d/1fb-ugvgdSVIkkuJ388_nhp2pBTy_4HEVg5848Xy7n5U/edit#bookmark=id.vsb8pqnf4gib)
signed up, to improve SIG Node CI signal and overall observability.
Victor Pickard focused on getting
[testgrid jobs](https://testgrid.k8s.io/sig-node) passing
when Ning Liao suggested forming a group around this effort and came up with
the [original group charter document](https://docs.google.com/document/d/1yS-XoUl6GjZdjrwxInEZVHhxxLXlTIX2CeWOARmD8tY/edit#heading=h.te6sgum6s8uf).
The SIG Node chairs sponsored group creation with Victor as a subproject lead.
Sergey Kanzhelev joined Victor shortly after as a co-lead.
At the kick-off meeting, we discussed which tests to concentrate on fixing first
and discussed merge-blocking and release-blocking tests, many of which were failing due
to infrastructure issues or buggy test code.
The subproject launched weekly hour-long meetings to discuss ongoing work
discussion and triage.
***June 2020.*** Morgan Bauer, Karan Goel, and Jorge Alarcon Ochoa were
recognized as reviewers for the SIG Node CI group for their contributions,
helping significantly with the early stages of the subproject.
David Porter and Roy Yang also joined the SIG test failures GitHub team.
***August 2020.*** All merge-blocking and release-blocking tests were passing,
with some flakes. However, only 42% of all SIG Node test jobs were green, as there
were many flakes and failing tests.
***October 2020.*** Amim Knabben becomes a Kubernetes org member for his
contributions to the subproject.
***January 2021.*** With healthy presubmit and critical periodic jobs passing,
the subproject discussed its goal for cleaning up the rest of periodic tests
and ensuring they passed without flakes.
Elana Hashman joined the subproject, stepping up to help lead it after
Victor's departure.
***February 2021.*** Artyom Lukianov becomes a Kubernetes org member for his
contributions to the subproject.
***August 2021.*** After SIG Node successfully ran a [bug scrub](https://groups.google.com/g/kubernetes-dev/c/w2ghO4ihje0/m/VeEql1LJBAAJ)
to clean up its bug backlog, the scope of the meeting was extended to
include bug triage to increase overall reliability, anticipating issues
before they affect the CI signal.
Subproject leads Elana Hashman and Sergey Kanzhelev are both recognized as
approvers on all node test code, supported by SIG Node and SIG Testing.
***September 2021.*** After significant deflaking progress with serial tests in
the 1.22 release spearheaded by Francesco Romani, the subproject set a goal
for getting the serial job fully passing by the 1.23 release date.
Mike Miranda becomes a Kubernetes org member for his contributions
to the subproject.
***November 2021.*** Throughout 2021, SIG Node had no merge or
release-blocking test failures. Many flaky tests from past releases are removed
from release-blocking dashboards as they had been fully cleaned up.
Danielle Lancashire was recognized as a reviewer for SIG Node's subgroup, test code.
The final node serial tests were completely fixed. The serial tests consist of
many disruptive and slow tests which tend to be flakey and are hard
to troubleshoot. By the 1.23 release freeze, the last serial tests were
fixed and the job was passing without flakes.
[![Slack announcement that Serial tests are green](serial-tests-green.png)](https://kubernetes.slack.com/archives/C0BP8PW9G/p1638211041322900)
The 1.23 release got a special shout out for the tests quality and CI signal.
The SIG Node CI subproject was proud to have helped contribute to such
a high-quality release, in part due to our efforts in identifying
and fixing flakes in Node and beyond.
[![Slack shoutout that release was mostly green](release-mostly-green.png)](https://kubernetes.slack.com/archives/C92G08FGD/p1637175755023200)
***December 2021.*** An estimated 90% of test jobs were passing at the time of
the 1.23 release (up from 42% in August 2020).
Dockershim code was removed from Kubernetes. This affected nearly half of SIG Node's
test jobs and the SIG Node CI subproject reacted quickly and retargeted all the
tests. SIG Node was the first SIG to complete test migrations off dockershim,
providing examples for other affected SIGs. The vast majority of new jobs passed
at the time of introduction without further fixes required. The [effort of
removing dockershim](https://k8s.io/dockershim)) from Kubernetes is ongoing.
There are still some wrinkles from the dockershim removal as we uncover more
dependencies on dockershim, but we plan to stabilize all test jobs
by the 1.24 release.
## Statistics
Our regular meeting attendees and subproject participants for the past few months:
- Aditi Sharma
- Artyom Lukianov
- Arnaud Meukam
- Danielle Lancashire
- David Porter
- Davanum Srinivas
- Elana Hashman
- Francesco Romani
- Matthias Bertschy
- Mike Miranda
- Paco Xu
- Peter Hunt
- Ruiwen Zhao
- Ryan Phillips
- Sergey Kanzhelev
- Skyler Clark
- Swati Sehgal
- Wenjun Wu
The [kubernetes/test-infra](https://github.com/kubernetes/test-infra/) source code repository contains test definitions. The number of
Node PRs just in that repository:
- 2020 PRs (since May): [183](https://github.com/kubernetes/test-infra/pulls?q=is%3Apr+is%3Aclosed+label%3Asig%2Fnode+created%3A2020-05-01..2020-12-31+-author%3Ak8s-infra-ci-robot+)
- 2021 PRs: [264](https://github.com/kubernetes/test-infra/pulls?q=is%3Apr+is%3Aclosed+label%3Asig%2Fnode+created%3A2021-01-01..2021-12-31+-author%3Ak8s-infra-ci-robot+)
Triaged issues and PRs on CI board (including triaging away from the subgroup scope):
- 2020 (since May): [132](https://github.com/issues?q=project%3Akubernetes%2F43+created%3A2020-05-01..2020-12-31)
- 2021: [532](https://github.com/issues?q=project%3Akubernetes%2F43+created%3A2021-01-01..2021-12-31+)
## Future
Just "keeping the lights on" is a bold task and we are committed to improving this experience.
We are working to simplify the triage and review processes for SIG Node.
Specifically, we are working on better test organization, naming,
and tracking:
- https://github.com/kubernetes/enhancements/pull/3042
- https://github.com/kubernetes/test-infra/issues/24641
- [Kubernetes SIG-Node CI Testgrid Tracker](https://docs.google.com/spreadsheets/d/1IwONkeXSc2SG_EQMYGRSkfiSWNk8yWLpVhPm-LOTbGM/edit#gid=0)
We are also constantly making progress on improved tests debuggability and de-flaking.
If any of this interests you, we'd love for you to join us!
There's plenty to learn in debugging test failures, and it will help you gain
familiarity with the code that SIG Node maintains.
You can always find information about the group on the
[SIG Node](https://github.com/kubernetes/community/tree/master/sig-node) page.
We give group updates at our maintainer track sessions, such as
[KubeCon + CloudNativeCon Europe 2021](https://kccnceu2021.sched.com/event/iE8E/kubernetes-sig-node-intro-and-deep-dive-elana-hashman-red-hat-sergey-kanzhelev-google) and
[KubeCon + CloudNative North America 2021](https://kccncna2021.sched.com/event/lV9D/kubenetes-sig-node-intro-and-deep-dive-elana-hashman-derek-carr-red-hat-sergey-kanzhelev-dawn-chen-google?iframe=no&w=100%&sidebar=yes&bg=no).
Join us in our mission to keep the kubelet and other SIG Node components reliable and ensure smooth and uneventful releases!
content/en/blog/_posts/2022-02-16-sig-node-ci-subproject-celebrates/release-mostly-green.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 99 KiB

content/en/blog/_posts/2022-02-16-sig-node-ci-subproject-celebrates/serial-tests-green.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

content/en/blog/_posts/2022-02-17-updated-dockershim-faq.md
+205
View File
@@ -0,0 +1,205 @@
---
layout: blog
title: "Updated: Dockershim Removal FAQ"
date: 2022-02-17
slug: dockershim-faq
aliases: [ '/dockershim' ]
---
**This is an update to the original [Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/) article,
published in late 2020.**
This document goes over some frequently asked questions regarding the
deprecation and removal of _dockershim_, that was
[announced](/blog/2020/12/08/kubernetes-1-20-release-announcement/)
as a part of the Kubernetes v1.20 release. For more detail
on what that means, check out the blog post
[Don't Panic: Kubernetes and Docker](/blog/2020/12/02/dont-panic-kubernetes-and-docker/).
Also, you can read [check whether dockershim removal affects you](/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you/)
to determine how much impact the removal of dockershim would have for you
or for your organization.
As the Kubernetes 1.24 release has become imminent, we've been working hard to try to make this a smooth transition.
- We've written a blog post detailing our [commitment and next steps](/blog/2022/01/07/kubernetes-is-moving-on-from-dockershim/).
- We believe there are no major blockers to migration to [other container runtimes](/docs/setup/production-environment/container-runtimes/#container-runtimes).
- There is also a [Migrating from dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/) guide available.
- We've also created a page to list
[articles on dockershim removal and on using CRI-compatible runtimes](/docs/reference/node/topics-on-dockershim-and-cri-compatible-runtimes/).
That list includes some of the already mentioned docs, and also covers selected external sources
(including vendor guides).
### Why is the dockershim being removed from Kubernetes?
Early versions of Kubernetes only worked with a specific container runtime:
Docker Engine. Later, Kubernetes added support for working with other container runtimes.
The CRI standard was [created](/blog/2016/12/container-runtime-interface-cri-in-kubernetes/) to
enable interoperability between orchestrators (like Kubernetes) and many different container
runtimes.
Docker Engine doesn't implement that interface (CRI), so the Kubernetes project created
special code to help with the transition, and made that _dockershim_ code part of Kubernetes
itself.
The dockershim code was always intended to be a temporary solution (hence the name: shim).
You can read more about the community discussion and planning in the
[Dockershim Removal Kubernetes Enhancement Proposal][drkep].
In fact, maintaining dockershim had become a heavy burden on the Kubernetes maintainers.
Additionally, features that were largely incompatible with the dockershim, such
as cgroups v2 and user namespaces are being implemented in these newer CRI
runtimes. Removing support for the dockershim will allow further development in
those areas.
[drkep]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2221-remove-dockershim
### Can I still use Docker Engine in Kubernetes 1.23?
Yes, the only thing changed in 1.20 is a single warning log printed at [kubelet]
startup if using Docker Engine as the runtime. You'll see this warning in all versions up to 1.23. The dockershim removal occurs in Kubernetes 1.24.
[kubelet]: /docs/reference/command-line-tools-reference/kubelet/
### When will dockershim be removed?
Given the impact of this change, we are using an extended deprecation timeline.
Removal of dockershim is scheduled for Kubernetes v1.24, see [Dockershim Removal Kubernetes Enhancement Proposal][drkep].
The Kubernetes project will be working closely with vendors and other ecosystem groups to ensure
a smooth transition and will evaluate things as the situation evolves.
### Can I still use Docker Engine as my container runtime?
First off, if you use Docker on your own PC to develop or test containers: nothing changes.
You can still use Docker locally no matter what container runtime(s) you use for your
Kubernetes clusters. Containers make this kind of interoperability possible.
Mirantis and Docker have [committed][mirantis] to maintaining a replacement adapter for
Docker Engine, and to maintain that adapter even after the in-tree dockershim is removed
from Kubernetes. The replacement adapter is named [`cri-dockerd`](https://github.com/Mirantis/cri-dockerd).
[mirantis]: https://www.mirantis.com/blog/mirantis-to-take-over-support-of-kubernetes-dockershim-2/
### Will my existing container images still work?
Yes, the images produced from `docker build` will work with all CRI implementations.
All your existing images will still work exactly the same.
#### What about private images?
Yes. All CRI runtimes support the same pull secrets configuration used in
Kubernetes, either via the PodSpec or ServiceAccount.
### Are Docker and containers the same thing?
Docker popularized the Linux containers pattern and has been instrumental in
developing the underlying technology, however containers in Linux have existed
for a long time. The container ecosystem has grown to be much broader than just
Docker. Standards like OCI and CRI have helped many tools grow and thrive in our
ecosystem, some replacing aspects of Docker while others enhance existing
functionality.
### Are there examples of folks using other runtimes in production today?
All Kubernetes project produced artifacts (Kubernetes binaries) are validated
with each release.
Additionally, the [kind] project has been using containerd for some time and has
seen an improvement in stability for its use case. Kind and containerd are leveraged
multiple times every day to validate any changes to the Kubernetes codebase. Other
related projects follow a similar pattern as well, demonstrating the stability and
usability of other container runtimes. As an example, OpenShift 4.x has been
using the [CRI-O] runtime in production since June 2019.
For other examples and references you can look at the adopters of containerd and
CRI-O, two container runtimes under the Cloud Native Computing Foundation ([CNCF]).
- [containerd](https://github.com/containerd/containerd/blob/master/ADOPTERS.md)
- [CRI-O](https://github.com/cri-o/cri-o/blob/master/ADOPTERS.md)
[CRI-O]: https://cri-o.io/
[kind]: https://kind.sigs.k8s.io/
[CNCF]: https://cncf.io
### People keep referencing OCI, what is that?
OCI stands for the [Open Container Initiative], which standardized many of the
interfaces between container tools and technologies. They maintain a standard
specification for packaging container images (OCI image-spec) and running containers
(OCI runtime-spec). They also maintain an actual implementation of the runtime-spec
in the form of [runc], which is the underlying default runtime for both
[containerd] and [CRI-O]. The CRI builds on these low-level specifications to
provide an end-to-end standard for managing containers.
[Open Container Initiative]: https://opencontainers.org/about/overview/
[runc]: https://github.com/opencontainers/runc
[containerd]: https://containerd.io/
### Which CRI implementation should I use?
That’s a complex question and it depends on a lot of factors. If Docker is
working for you, moving to containerd should be a relatively easy swap and
will have strictly better performance and less overhead. However, we encourage you
to explore all the options from the [CNCF landscape] in case another would be an
even better fit for your environment.
[CNCF landscape]: https://landscape.cncf.io/card-mode?category=container-runtime&grouping=category
### What should I look out for when changing CRI implementations?
While the underlying containerization code is the same between Docker and most
CRIs (including containerd), there are a few differences around the edges. Some
common things to consider when migrating are:
- Logging configuration
- Runtime resource limitations
- Node provisioning scripts that call docker or use docker via it's control socket
- Kubectl plugins that require docker CLI or the control socket
- Tools from the Kubernetes project that require direct access to Docker Engine
(for example: the deprecated `kube-imagepuller` tool)
- Configuration of functionality like `registry-mirrors` and insecure registries
- Other support scripts or daemons that expect Docker Engine to be available and are run
outside of Kubernetes (for example, monitoring or security agents)
- GPUs or special hardware and how they integrate with your runtime and Kubernetes
If you use Kubernetes resource requests/limits or file-based log collection
DaemonSets then they will continue to work the same, but if you’ve customized
your `dockerd` configuration, you’ll need to adapt that for your new container
runtime where possible.
Another thing to look out for is anything expecting to run for system maintenance
or nested inside a container when building images will no longer work. For the
former, you can use the [`crictl`][cr] tool as a drop-in replacement (see [mapping from docker cli to crictl](https://kubernetes.io/docs/tasks/debug-application-cluster/crictl/#mapping-from-docker-cli-to-crictl)) and for the
latter you can use newer container build options like [img], [buildah],
[kaniko], or [buildkit-cli-for-kubectl] that don’t require Docker.
[cr]: https://github.com/kubernetes-sigs/cri-tools
[img]: https://github.com/genuinetools/img
[buildah]: https://github.com/containers/buildah
[kaniko]: https://github.com/GoogleContainerTools/kaniko
[buildkit-cli-for-kubectl]: https://github.com/vmware-tanzu/buildkit-cli-for-kubectl
For containerd, you can start with their [documentation] to see what configuration
options are available as you migrate things over.
[documentation]: https://github.com/containerd/cri/blob/master/docs/registry.md
For instructions on how to use containerd and CRI-O with Kubernetes, see the
Kubernetes documentation on [Container Runtimes]
[Container Runtimes]: /docs/setup/production-environment/container-runtimes/
### What if I have more questions?
If you use a vendor-supported Kubernetes distribution, you can ask them about
upgrade plans for their products. For end-user questions, please post them
to our end user community forum: https://discuss.kubernetes.io/.
You can also check out the excellent blog post
[Wait, Docker is deprecated in Kubernetes now?][dep] a more in-depth technical
discussion of the changes.
[dep]: https://dev.to/inductor/wait-docker-is-deprecated-in-kubernetes-now-what-do-i-do-e4m
### Can I have a hug?
Yes, we're still giving hugs as requested. 🤗🤗🤗
content/en/docs/concepts/architecture/nodes.md
+2 -2
View File
@@ -93,7 +93,7 @@ For self-registration, the kubelet is started with the following options:
No-op if `register-node` is false.
- `--node-ip` - IP address of the node.
- `--node-labels` - {{< glossary_tooltip text="Labels" term_id="label" >}} to add when registering the node in the cluster (see label restrictions enforced by the [NodeRestriction admission plugin](/docs/reference/access-authn-authz/admission-controllers/#noderestriction)).
- `--node-status-update-frequency` - Specifies how often kubelet posts node status to master.
- `--node-status-update-frequency` - Specifies how often kubelet posts its node status to the API server.
When the [Node authorization mode](/docs/reference/access-authn-authz/node/) and
[NodeRestriction admission plugin](/docs/reference/access-authn-authz/admission-controllers/#noderestriction) are enabled,
@@ -335,7 +335,7 @@ the same time:
(default 0.01) per second.
The reason these policies are implemented per availability zone is because one
availability zone might become partitioned from the master while the others remain
availability zone might become partitioned from the control plane while the others remain
connected. If your cluster does not span multiple cloud provider availability zones,
then the eviction mechanism does not take per-zone unavailability into account.
content/en/docs/concepts/cluster-administration/addons.md
-1
View File
@@ -21,7 +21,6 @@ This page lists some of the available add-ons and links to their respective inst
* [Canal](https://github.com/tigera/canal/tree/master/k8s-install) unites Flannel and Calico, providing networking and network policy.
* [Cilium](https://github.com/cilium/cilium) is a L3 network and network policy plugin that can enforce HTTP/API/L7 policies transparently. Both routing and overlay/encapsulation mode are supported, and it can work on top of other CNI plugins.
* [CNI-Genie](https://github.com/Huawei-PaaS/CNI-Genie) enables Kubernetes to seamlessly connect to a choice of CNI plugins, such as Calico, Canal, Flannel, Romana, or Weave.
* [Contiv](https://contiv.github.io) provides configurable networking (native L3 using BGP, overlay using vxlan, classic L2, and Cisco-SDN/ACI) for various use cases and a rich policy framework. Contiv project is fully [open sourced](https://github.com/contiv). The [installer](https://github.com/contiv/install) provides both kubeadm and non-kubeadm based installation options.
* [Contrail](https://www.juniper.net/us/en/products-services/sdn/contrail/contrail-networking/), based on [Tungsten Fabric](https://tungsten.io), is an open source, multi-cloud network virtualization and policy management platform. Contrail and Tungsten Fabric are integrated with orchestration systems such as Kubernetes, OpenShift, OpenStack and Mesos, and provide isolation modes for virtual machines, containers/pods and bare metal workloads.
* [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually) is an overlay network provider that can be used with Kubernetes.
* [Knitter](https://github.com/ZTE/Knitter/) is a plugin to support multiple network interfaces in a Kubernetes pod.
content/en/docs/concepts/cluster-administration/flow-control.md
+155 -81
View File
@@ -42,21 +42,21 @@ Fairness feature enabled.
## Enabling/Disabling API Priority and Fairness
The API Priority and Fairness feature is controlled by a feature gate
and is enabled by default. See
[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/)
and is enabled by default. See [Feature
Gates](/docs/reference/command-line-tools-reference/feature-gates/)
for a general explanation of feature gates and how to enable and
disable them. The name of the feature gate for APF is
"APIPriorityAndFairness". This feature also involves an {{<
glossary_tooltip term_id="api-group" text="API Group" >}} with: (a) a
`v1alpha1` version, disabled by default, and (b) a `v1beta1`
version, enabled by default. You can disable the feature
gate and API group v1beta1 version by adding the following
`v1alpha1` version, disabled by default, and (b) `v1beta1` and
`v1beta2` versions, enabled by default. You can disable the feature
gate and API group beta versions by adding the following
command-line flags to your `kube-apiserver` invocation:
```shell
kube-apiserver \
--feature-gates=APIPriorityAndFairness=false \
--runtime-config=flowcontrol.apiserver.k8s.io/v1beta1=false \
--runtime-config=flowcontrol.apiserver.k8s.io/v1beta1=false,flowcontrol.apiserver.k8s.io/v1beta2=false \
# …and other flags as usual
```
@@ -127,86 +127,13 @@ any of the limitations imposed by this feature. These exemptions prevent an
improperly-configured flow control configuration from totally disabling an API
server.
## Defaults
The Priority and Fairness feature ships with a suggested configuration that
should suffice for experimentation; if your cluster is likely to
experience heavy load then you should consider what configuration will work
best. The suggested configuration groups requests into five priority
classes:
* The `system` priority level is for requests from the `system:nodes` group,
i.e. Kubelets, which must be able to contact the API server in order for
workloads to be able to schedule on them.
* The `leader-election` priority level is for leader election requests from
built-in controllers (in particular, requests for `endpoints`, `configmaps`,
or `leases` coming from the `system:kube-controller-manager` or
`system:kube-scheduler` users and service accounts in the `kube-system`
namespace). These are important to isolate from other traffic because failures
in leader election cause their controllers to fail and restart, which in turn
causes more expensive traffic as the new controllers sync their informers.
* The `workload-high` priority level is for other requests from built-in
controllers.
* The `workload-low` priority level is for requests from any other service
account, which will typically include all requests from controllers running in
Pods.
* The `global-default` priority level handles all other traffic, e.g.
interactive `kubectl` commands run by nonprivileged users.
Additionally, there are two PriorityLevelConfigurations and two FlowSchemas that
are built in and may not be overwritten:
* The special `exempt` priority level is used for requests that are not subject
to flow control at all: they will always be dispatched immediately. The
special `exempt` FlowSchema classifies all requests from the `system:masters`
group into this priority level. You may define other FlowSchemas that direct
other requests to this priority level, if appropriate.
* The special `catch-all` priority level is used in combination with the special
`catch-all` FlowSchema to make sure that every request gets some kind of
classification. Typically you should not rely on this catch-all configuration,
and should create your own catch-all FlowSchema and PriorityLevelConfiguration
(or use the `global-default` configuration that is installed by default) as
appropriate. To help catch configuration errors that miss classifying some
requests, the mandatory `catch-all` priority level only allows one concurrency
share and does not queue requests, making it relatively likely that traffic
that only matches the `catch-all` FlowSchema will be rejected with an HTTP 429
error.
## Health check concurrency exemption
The suggested configuration gives no special treatment to the health
check requests on kube-apiservers from their local kubelets --- which
tend to use the secured port but supply no credentials. With the
suggested config, these requests get assigned to the `global-default`
FlowSchema and the corresponding `global-default` priority level,
where other traffic can crowd them out.
If you add the following additional FlowSchema, this exempts those
requests from rate limiting.
{{< caution >}}
Making this change also allows any hostile party to then send
health-check requests that match this FlowSchema, at any volume they
like. If you have a web traffic filter or similar external security
mechanism to protect your cluster's API server from general internet
traffic, you can configure rules to block any health check requests
that originate from outside your cluster.
{{< /caution >}}
{{< codenew file="priority-and-fairness/health-for-strangers.yaml" >}}
## Resources
The flow control API involves two kinds of resources.
[PriorityLevelConfigurations](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#prioritylevelconfiguration-v1beta1-flowcontrol-apiserver-k8s-io)
[PriorityLevelConfigurations](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#prioritylevelconfiguration-v1beta2-flowcontrol-apiserver-k8s-io)
define the available isolation classes, the share of the available concurrency
budget that each can handle, and allow for fine-tuning queuing behavior.
[FlowSchemas](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#flowschema-v1beta1-flowcontrol-apiserver-k8s-io)
[FlowSchemas](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#flowschema-v1beta2-flowcontrol-apiserver-k8s-io)
are used to classify individual inbound requests, matching each to a
single PriorityLevelConfiguration. There is also a `v1alpha1` version
of the same API group, and it has the same Kinds with the same syntax and
@@ -329,6 +256,153 @@ omitted entirely), in which case all requests matched by this FlowSchema will be
considered part of a single flow. The correct choice for a given FlowSchema
depends on the resource and your particular environment.
## Defaults
Each kube-apiserver maintains two sorts of APF configuration objects:
mandatory and suggested.
### Mandatory Configuration Objects
The four mandatory configuration objects reflect fixed built-in
guardrail behavior. This is behavior that the servers have before
those objects exist, and when those objects exist their specs reflect
this behavior. The four mandatory objects are as follows.
* The mandatory `exempt` priority level is used for requests that are
not subject to flow control at all: they will always be dispatched
immediately. The mandatory `exempt` FlowSchema classifies all
requests from the `system:masters` group into this priority
level. You may define other FlowSchemas that direct other requests
to this priority level, if appropriate.
* The mandatory `catch-all` priority level is used in combination with
the mandatory `catch-all` FlowSchema to make sure that every request
gets some kind of classification. Typically you should not rely on
this catch-all configuration, and should create your own catch-all
FlowSchema and PriorityLevelConfiguration (or use the suggested
`global-default` priority level that is installed by default) as
appropriate. Because it is not expected to be used normally, the
mandatory `catch-all` priority level has a very small concurrency
share and does not queue requests.
### Suggested Configuration Objects
The suggested FlowSchemas and PriorityLevelConfigurations constitute a
reasonable default configuration. You can modify these and/or create
additional configuration objects if you want. If your cluster is
likely to experience heavy load then you should consider what
configuration will work best.
The suggested configuration groups requests into six priority levels:
* The `node-high` priority level is for health updates from nodes.
* The `system` priority level is for non-health requests from the
`system:nodes` group, i.e. Kubelets, which must be able to contact
the API server in order for workloads to be able to schedule on
them.
* The `leader-election` priority level is for leader election requests from
built-in controllers (in particular, requests for `endpoints`, `configmaps`,
or `leases` coming from the `system:kube-controller-manager` or
`system:kube-scheduler` users and service accounts in the `kube-system`
namespace). These are important to isolate from other traffic because failures
in leader election cause their controllers to fail and restart, which in turn
causes more expensive traffic as the new controllers sync their informers.
* The `workload-high` priority level is for other requests from built-in
controllers.
* The `workload-low` priority level is for requests from any other service
account, which will typically include all requests from controllers running in
Pods.
* The `global-default` priority level handles all other traffic, e.g.
interactive `kubectl` commands run by nonprivileged users.
The suggested FlowSchemas serve to steer requests into the above
priority levels, and are not enumerated here.
### Maintenance of the Mandatory and Suggested Configuration Objects
Each `kube-apiserver` independently maintains the mandatory and
suggested configuration objects, using initial and periodic behavior.
Thus, in a situation with a mixture of servers of different versions
there may be thrashing as long as different servers have different
opinions of the proper content of these objects.
Each `kube-apiserver` makes an inital maintenance pass over the
mandatory and suggested configuration objects, and after that does
periodic maintenance (once per minute) of those objects.
For the mandatory configuration objects, maintenance consists of
ensuring that the object exists and, if it does, has the proper spec.
The server refuses to allow a creation or update with a spec that is
inconsistent with the server's guardrail behavior.
Maintenance of suggested configuration objects is designed to allow
their specs to be overridden. Deletion, on the other hand, is not
respected: maintenance will restore the object. If you do not want a
suggested configuration object then you need to keep it around but set
its spec to have minimal consequences. Maintenance of suggested
objects is also designed to support automatic migration when a new
version of the `kube-apiserver` is rolled out, albeit potentially with
thrashing while there is a mixed population of servers.
Maintenance of a suggested configuration object consists of creating
it --- with the server's suggested spec --- if the object does not
exist. OTOH, if the object already exists, maintenance behavior
depends on whether the `kube-apiservers` or the users control the
object. In the former case, the server ensures that the object's spec
is what the server suggests; in the latter case, the spec is left
alone.
The question of who controls the object is answered by first looking
for an annotation with key `apf.kubernetes.io/autoupdate-spec`. If
there is such an annotation and its value is `true` then the
kube-apiservers control the object. If there is such an annotation
and its value is `false` then the users control the object. If
neither of those condtions holds then the `metadata.generation` of the
object is consulted. If that is 1 then the kube-apiservers control
the object. Otherwise the users control the object. These rules were
introduced in release 1.22 and their consideration of
`metadata.generation` is for the sake of migration from the simpler
earlier behavior. Users who wish to control a suggested configuration
object should set its `apf.kubernetes.io/autoupdate-spec` annotation
to `false`.
Maintenance of a mandatory or suggested configuration object also
includes ensuring that it has an `apf.kubernetes.io/autoupdate-spec`
annotation that accurately reflects whether the kube-apiservers
control the object.
Maintenance also includes deleting objects that are neither mandatory
nor suggested but are annotated
`apf.kubernetes.io/autoupdate-spec=true`.
## Health check concurrency exemption
The suggested configuration gives no special treatment to the health
check requests on kube-apiservers from their local kubelets --- which
tend to use the secured port but supply no credentials. With the
suggested config, these requests get assigned to the `global-default`
FlowSchema and the corresponding `global-default` priority level,
where other traffic can crowd them out.
If you add the following additional FlowSchema, this exempts those
requests from rate limiting.
{{< caution >}}
Making this change also allows any hostile party to then send
health-check requests that match this FlowSchema, at any volume they
like. If you have a web traffic filter or similar external security
mechanism to protect your cluster's API server from general internet
traffic, you can configure rules to block any health check requests
that originate from outside your cluster.
{{< /caution >}}
{{< codenew file="priority-and-fairness/health-for-strangers.yaml" >}}
## Diagnostics
Every HTTP response from an API server with the priority and fairness feature
content/en/docs/concepts/cluster-administration/logging.md
+12 -2
View File
@@ -12,7 +12,9 @@ weight: 60
Application logs can help you understand what is happening inside your application. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism. Likewise, container engines are designed to support logging. The easiest and most adopted logging method for containerized applications is writing to standard output and standard error streams.
However, the native functionality provided by a container engine or runtime is usually not enough for a complete logging solution.
For example, you may want to access your application's logs if a container crashes, a pod gets evicted, or a node dies.
In a cluster, logs should have a separate storage and lifecycle independent of nodes, pods, or containers. This concept is called _cluster-level logging_.
<!-- body -->
@@ -55,7 +57,15 @@ The output is:
...
```
You can use `kubectl logs --previous` to retrieve logs from a previous instantiation of a container. If your pod has multiple containers, specify which container's logs you want to access by appending a container name to the command. See the [`kubectl logs` documentation](/docs/reference/generated/kubectl/kubectl-commands#logs) for more details.
You can use `kubectl logs --previous` to retrieve logs from a previous instantiation of a container.
If your pod has multiple containers, specify which container's logs you want to access by
appending a container name to the command, with a `-c` flag, like so:
```console
kubectl logs counter -c count
```
See the [`kubectl logs` documentation](/docs/reference/generated/kubectl/kubectl-commands#logs) for more details.
## Logging at the node level
@@ -141,7 +151,7 @@ as a `DaemonSet`.
Node-level logging creates only one agent per node and doesn't require any changes to the applications running on the node.
Containers write stdout and stderr, but with no agreed format. A node-level agent collects these logs and forwards them for aggregation.
Containers write to stdout and stderr, but with no agreed format. A node-level agent collects these logs and forwards them for aggregation.
### Using a sidecar container with the logging agent {#sidecar-container-with-logging-agent}
content/en/docs/concepts/cluster-administration/networking.md
+1 -1
View File
@@ -79,7 +79,7 @@ addressing, and it can be used in combination with other CNI plugins.
### CNI-Genie from Huawei
[CNI-Genie](https://github.com/cni-genie/CNI-Genie) is a CNI plugin that enables Kubernetes to [simultaneously have access to different implementations](https://github.com/cni-genie/CNI-Genie/blob/master/docs/multiple-cni-plugins/README.md#what-cni-genie-feature-1-multiple-cni-plugins-enables) of the [Kubernetes network model](/docs/concepts/cluster-administration/networking/#the-kubernetes-network-model) in runtime. This includes any implementation that runs as a [CNI plugin](https://github.com/containernetworking/cni#3rd-party-plugins), such as [Flannel](https://github.com/flannel-io/flannel#flannel), [Calico](https://projectcalico.docs.tigera.io/about/about-calico/), [Weave-net](https://www.weave.works/oss/net/).
[CNI-Genie](https://github.com/cni-genie/CNI-Genie) is a CNI plugin that enables Kubernetes to [simultaneously have access to different implementations](https://github.com/cni-genie/CNI-Genie/blob/master/docs/multiple-cni-plugins/README.md#what-cni-genie-feature-1-multiple-cni-plugins-enables) of the [Kubernetes network model](/docs/concepts/cluster-administration/networking/#how-to-implement-the-kubernetes-networking-model) in runtime. This includes any implementation that runs as a [CNI plugin](https://github.com/containernetworking/cni#3rd-party-plugins), such as [Flannel](https://github.com/flannel-io/flannel#flannel), [Calico](https://projectcalico.docs.tigera.io/about/about-calico/), [Weave-net](https://www.weave.works/oss/net/).
CNI-Genie also supports [assigning multiple IP addresses to a pod](https://github.com/cni-genie/CNI-Genie/blob/master/docs/multiple-ips/README.md#feature-2-extension-cni-genie-multiple-ip-addresses-per-pod), each from a different CNI plugin.
content/en/docs/concepts/cluster-administration/system-traces.md
+2 -2
View File
@@ -66,7 +66,7 @@ with `--tracing-config-file=<path-to-config>`. This is an example config that re
spans for 1 in 10000 requests, and uses the default OpenTelemetry endpoint:
```yaml
apiVersion: apiserver.config.k8s.io/v1beta1
apiVersion: apiserver.config.k8s.io/v1alpha1
kind: TracingConfiguration
# default value
#endpoint: localhost:4317
@@ -74,7 +74,7 @@ samplingRatePerMillion: 100
```
For more information about the `TracingConfiguration` struct, see
[API server config API (v1beta1)](/docs/reference/config-api/apiserver-config.v1beta1/#apiserver-k8s-io-v1beta1-TracingConfiguration).
[API server config API (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/#apiserver-k8s-io-v1alpha1-TracingConfiguration).
## Stability
content/en/docs/concepts/configuration/manage-resources-containers.md
+2 -2
View File
@@ -231,7 +231,7 @@ The kubelet reports the resource usage of a Pod as part of the Pod
If optional [tools for monitoring](/docs/tasks/debug-application-cluster/resource-usage-monitoring/)
are available in your cluster, then Pod resource usage can be retrieved either
from the [Metrics API](/docs/tasks/debug-application-cluster/resource-metrics-pipeline/#the-metrics-api)
from the [Metrics API](/docs/tasks/debug-application-cluster/resource-metrics-pipeline/#metrics-api)
directly or from your monitoring tools.
## Local ephemeral storage
@@ -801,6 +801,6 @@ memory limit (and possibly request) for that container.
* Get hands-on experience [assigning CPU resources to containers and Pods](/docs/tasks/configure-pod-container/assign-cpu-resource/).
* Read how the API reference defines a [container](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container)
and its [resource requirements](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources)
* Read about [project quotas](https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-quotas.html) in XFS
* Read about [project quotas](https://xfs.org/index.php/XFS_FAQ#Q:_Quota:_Do_quotas_work_on_XFS.3F) in XFS
* Read more about the [kube-scheduler configuration reference (v1beta3)](/docs/reference/config-api/kube-scheduler-config.v1beta3/)
content/en/docs/concepts/configuration/secret.md
+14 -8
View File
@@ -146,14 +146,6 @@ data:
extra: YmFyCg==
```
When creating a `Pod`, Kubernetes automatically creates a service account Secret
and automatically modifies your Pod to use this Secret. The service account token
Secret contains credentials for accessing the API.
The automatic creation and use of API credentials can be disabled or
overridden if desired. However, if all you need to do is securely access the
API server, this is the recommended workflow.
See the [ServiceAccount](/docs/tasks/configure-pod-container/configure-service-account/)
documentation for more information on how service accounts work.
You can also check the `automountServiceAccountToken` field and the
@@ -161,6 +153,20 @@ You can also check the `automountServiceAccountToken` field and the
[`Pod`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#pod-v1-core)
for information on referencing service account from Pods.
{{< note >}}
Automatic creation of API credentials in secrets to mount into running pods
is no longer used in v1.22 and newer versions. Instead, API credentials are
obtained directly by using the [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) API,
and are mounted into Pods using a [projected volume](/docs/reference/access-authn-authz/service-accounts-admin/#bound-service-account-token-volume).
The tokens obtained using this method have bounded lifetimes, and are automatically
invalidated when the Pod they are mounted into is deleted.
Service account token secrets can still be [created manually](/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-service-account-api-token)
if you need a token that never expires.
However, using the [TokenRequest](/docs/reference/kubernetes-api/authentication-resources/token-request-v1/)
subresource to obtain a token to access the API is recommended instead.
{{< /note >}}
### Docker config Secrets
You can use one of the following `type` values to create a Secret to
content/en/docs/concepts/containers/container-lifecycle-hooks.md
+13 -13
View File
@@ -105,22 +105,22 @@ The logs for a Hook handler are not exposed in Pod events.
If a handler fails for some reason, it broadcasts an event.
For `PostStart`, this is the `FailedPostStartHook` event,
and for `PreStop`, this is the `FailedPreStopHook` event.
You can see these events by running `kubectl describe pod <pod_name>`.
Here is some example output of events from running this command:
To generate a failed `FailedPreStopHook` event yourself, modify the [lifecycle-events.yaml](https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/pods/lifecycle-events.yaml) file to change the postStart command to "badcommand" and apply it.
Here is some example output of the resulting events you see from running `kubectl describe pod lifecycle-demo`:
```
Events:
FirstSeen LastSeen Count From SubObjectPath Type Reason Message
--------- -------- ----- ---- ------------- -------- ------ -------
1m 1m 1 {default-scheduler } Normal Scheduled Successfully assigned test-1730497541-cq1d2 to gke-test-cluster-default-pool-a07e5d30-siqd
1m 1m 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Pulling pulling image "test:1.0"
1m 1m 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Created Created container with docker id 5c6a256a2567; Security:[seccomp=unconfined]
1m 1m 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Pulled Successfully pulled image "test:1.0"
1m 1m 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Started Started container with docker id 5c6a256a2567
38s 38s 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Killing Killing container with docker id 5c6a256a2567: PostStart handler: Error executing in Docker Container: 1
37s 37s 1 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Normal Killing Killing container with docker id 8df9fdfd7054: PostStart handler: Error executing in Docker Container: 1
38s 37s 2 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} Warning FailedSync Error syncing pod, skipping: failed to "StartContainer" for "main" with RunContainerError: "PostStart handler: Error executing in Docker Container: 1"
1m 22s 2 {kubelet gke-test-cluster-default-pool-a07e5d30-siqd} spec.containers{main} Warning FailedPostStartHook
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 7s default-scheduler Successfully assigned default/lifecycle-demo to ip-XXX-XXX-XX-XX.us-east-2...
Normal Pulled 6s kubelet Successfully pulled image "nginx" in 229.604315ms
Normal Pulling 4s (x2 over 6s) kubelet Pulling image "nginx"
Normal Created 4s (x2 over 5s) kubelet Created container lifecycle-demo-container
Normal Started 4s (x2 over 5s) kubelet Started container lifecycle-demo-container
Warning FailedPostStartHook 4s (x2 over 5s) kubelet Exec lifecycle hook ([badcommand]) for Container "lifecycle-demo-container" in Pod "lifecycle-demo_default(30229739-9651-4e5a-9a32-a8f1688862db)" failed - error: command 'badcommand' exited with 126: , message: "OCI runtime exec failed: exec failed: container_linux.go:380: starting container process caused: exec: \"badcommand\": executable file not found in $PATH: unknown\r\n"
Normal Killing 4s (x2 over 5s) kubelet FailedPostStartHook
Normal Pulled 4s kubelet Successfully pulled image "nginx" in 215.66395ms
Warning BackOff 2s (x2 over 3s) kubelet Back-off restarting failed container
```
content/en/docs/concepts/extend-kubernetes/_index.md
+1
View File
@@ -39,6 +39,7 @@ Customization approaches can be broadly divided into *configuration*, which only
*Configuration files* and *flags* are documented in the Reference section of the online documentation, under each binary:
* [kubelet](/docs/reference/command-line-tools-reference/kubelet/)
* [kube-proxy](/docs/reference/command-line-tools-reference/kube-proxy/)
* [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
* [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/)
* [kube-scheduler](/docs/reference/command-line-tools-reference/kube-scheduler/).
content/en/docs/concepts/extend-kubernetes/operator.md
+1
View File
@@ -111,6 +111,7 @@ Operator.
{{% thirdparty-content %}}
* [Charmed Operator Framework](https://juju.is/)
* [Kopf](https://github.com/nolar/kopf) (Kubernetes Operator Pythonic Framework)
* [kubebuilder](https://book.kubebuilder.io/)
* [KubeOps](https://buehler.github.io/dotnet-operator-sdk/) (.NET operator SDK)
* [KUDO](https://kudo.dev/) (Kubernetes Universal Declarative Operator)
content/en/docs/concepts/extend-kubernetes/service-catalog.md
-1
View File
@@ -230,7 +230,6 @@ The following example describes how to map secret values into application enviro
* If you are familiar with {{< glossary_tooltip text="Helm Charts" term_id="helm-chart" >}}, [install Service Catalog using Helm](/docs/tasks/service-catalog/install-service-catalog-using-helm/) into your Kubernetes cluster. Alternatively, you can [install Service Catalog using the SC tool](/docs/tasks/service-catalog/install-service-catalog-using-sc/).
* View [sample service brokers](https://github.com/openservicebrokerapi/servicebroker/blob/master/gettingStarted.md#sample-service-brokers).
* Explore the [kubernetes-sigs/service-catalog](https://github.com/kubernetes-sigs/service-catalog) project.
* View [svc-cat.io](https://svc-cat.io/docs/).
content/en/docs/concepts/overview/components.md
+1 -1
View File
@@ -30,7 +30,7 @@ Control plane components can be run on any machine in the cluster. However,
for simplicity, set up scripts typically start all control plane components on
the same machine, and do not run user containers on this machine. See
[Creating Highly Available clusters with kubeadm](/docs/setup/production-environment/tools/kubeadm/high-availability/)
for an example control plane setup that runs across multiple VMs.
for an example control plane setup that runs across multiple machines.
### kube-apiserver
content/en/docs/concepts/overview/working-with-objects/finalizers.md
+13 -8
View File
@@ -21,18 +21,21 @@ your own.
When you create a resource using a manifest file, you can specify finalizers in
the `metadata.finalizers` field. When you attempt to delete the resource, the
controller that manages it notices the values in the `finalizers` field and does
the following:
API server handling the delete request notices the values in the `finalizers` field
and does the following:
* Modifies the object to add a `metadata.deletionTimestamp` field with the
time you started the deletion.
* Marks the object as read-only until its `metadata.finalizers` field is empty.
* Prevents the object from being removed until its `metadata.finalizers` field is empty.
* Returns a `202` status code (HTTP "Accepted")
The controller managing that finalizer notices the update to the object setting the
`metadata.deletionTimestamp`, indicating deletion of the object has been requested.
The controller then attempts to satisfy the requirements of the finalizers
specified for that resource. Each time a finalizer condition is satisfied, the
controller removes that key from the resource's `finalizers` field. When the
field is empty, garbage collection continues. You can also use finalizers to
prevent deletion of unmanaged resources.
`finalizers` field is emptied, an object with a `deletionTimestamp` field set
is automatically deleted. You can also use finalizers to prevent deletion of unmanaged resources.
A common example of a finalizer is `kubernetes.io/pv-protection`, which prevents
accidental deletion of `PersistentVolume` objects. When a `PersistentVolume`
@@ -63,16 +66,18 @@ Kubernetes also processes finalizers when it identifies owner references on a
resource targeted for deletion.
In some situations, finalizers can block the deletion of dependent objects,
which can cause the targeted owner object to remain in a read-only state for
which can cause the targeted owner object to remain for
longer than expected without being fully deleted. In these situations, you
should check finalizers and owner references on the target owner and dependent
objects to troubleshoot the cause.
{{<note>}}
In cases where objects are stuck in a deleting state, try to avoid manually
In cases where objects are stuck in a deleting state, avoid manually
removing finalizers to allow deletion to continue. Finalizers are usually added
to resources for a reason, so forcefully removing them can lead to issues in
your cluster.
your cluster. This should only be done when the purpose of the finalizer is
understood and is accomplished in another way (for example, manually cleaning
up some dependent object).
{{</note>}}
## {{% heading "whatsnext" %}}
content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md
+14 -5
View File
@@ -63,7 +63,7 @@ One way to create a Deployment using a `.yaml` file like the one above is to use
in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example:
```shell
kubectl apply -f https://k8s.io/examples/application/deployment.yaml --record
kubectl apply -f https://k8s.io/examples/application/deployment.yaml
```
The output is similar to this:
@@ -83,10 +83,19 @@ In the `.yaml` file for the Kubernetes object you want to create, you'll need to
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](https://kubernetes.io/docs/reference/kubernetes-api/) can help you find the spec format for all of the objects you can create using Kubernetes.
For example, the reference for Pod details the [`spec` field](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
for a Pod in the API, and the reference for Deployment details the [`spec` field](/docs/reference/kubernetes-api/workload-resources/deployment-v1/#DeploymentSpec) for Deployments.
In those API reference pages you'll see mention of PodSpec and DeploymentSpec. These names are implementation details of the Golang code that Kubernetes uses to implement its API.
For example, see the [`spec` field](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
for the Pod API reference.
For each Pod, the `.spec` field specifies the pod and its desired state (such as the container image name for
each container within that pod).
Another example of an object specification is the
[`spec` field](/docs/reference/kubernetes-api/workload-resources/stateful-set-v1/#StatefulSetSpec)
for the StatefulSet API. For StatefulSet, the `.spec` field specifies the StatefulSet and
its desired state.
Within the `.spec` of a StatefulSet is a [template](/docs/concepts/workloads/pods/#pod-templates)
for Pod objects. That template describes Pods that the StatefulSet controller will create in order to
satisfy the StatefulSet specification.
Different kinds of object can also have different `.status`; again, the API reference pages
detail the structure of that `.status` field, and its content for each different type of object.
## {{% heading "whatsnext" %}}
content/en/docs/concepts/policy/pod-security-policy.md
+6 -2
View File
@@ -11,9 +11,13 @@ weight: 30
{{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25. It has been replaced by
[Pod Security Admission](/docs/concepts/security/pod-security-admission/). For more information on the deprecation,
{{< caution >}}
PodSecurityPolicy is deprecated as of Kubernetes v1.21, and **will be removed in v1.25**. We recommend migrating to
[Pod Security Admission](/docs/concepts/security/pod-security-admission/), or a 3rd party admission plugin.
For a migration guide, see [Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](/docs/tasks/configure-pod-container/migrate-from-psp/).
For more information on the deprecation,
see [PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).
{{< /caution >}}
Pod Security Policies enable fine-grained authorization of pod creation and
updates.
content/en/docs/concepts/scheduling-eviction/api-eviction.md
+108 -5
View File
@@ -6,14 +6,117 @@ weight: 70
{{< glossary_definition term_id="api-eviction" length="short" >}} </br>
You can request eviction by directly calling the Eviction API
using a client of the kube-apiserver, like the `kubectl drain` command.
This creates an `Eviction` object, which causes the API server to terminate the Pod.
You can request eviction by calling the Eviction API directly, or programmatically
using a client of the {{<glossary_tooltip term_id="kube-apiserver" text="API server">}}, like the `kubectl drain` command. This
creates an `Eviction` object, which causes the API server to terminate the Pod.
API-initiated evictions respect your configured [`PodDisruptionBudgets`](/docs/tasks/run-application/configure-pdb/)
and [`terminationGracePeriodSeconds`](/docs/concepts/workloads/pods/pod-lifecycle#pod-termination).
Using the API to create an Eviction object for a Pod is like performing a
policy-controlled [`DELETE` operation](/docs/reference/kubernetes-api/workload-resources/pod-v1/#delete-delete-a-pod)
on the Pod.
## Calling the Eviction API
You can use a [Kubernetes language client](/docs/tasks/administer-cluster/access-cluster-api/#programmatic-access-to-the-api)
to access the Kubernetes API and create an `Eviction` object. To do this, you
POST the attempted operation, similar to the following example:
{{< tabs name="Eviction_example" >}}
{{% tab name="policy/v1" %}}
{{< note >}}
`policy/v1` Eviction is available in v1.22+. Use `policy/v1beta1` with prior releases.
{{< /note >}}
```json
{
"apiVersion": "policy/v1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
{{% /tab %}}
{{% tab name="policy/v1beta1" %}}
{{< note >}}
Deprecated in v1.22 in favor of `policy/v1`
{{< /note >}}
```json
{
"apiVersion": "policy/v1beta1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
{{% /tab %}}
{{< /tabs >}}
Alternatively, you can attempt an eviction operation by accessing the API using
`curl` or `wget`, similar to the following example:
```bash
curl -v -H 'Content-type: application/json' https://your-cluster-api-endpoint.example/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json
```
## How API-initiated eviction works
When you request an eviction using the API, the API server performs admission
checks and responds in one of the following ways:
* `200 OK`: the eviction is allowed, the `Eviction` subresource is created, and
the Pod is deleted, similar to sending a `DELETE` request to the Pod URL.
* `429 Too Many Requests`: the eviction is not currently allowed because of the
configured {{<glossary_tooltip term_id="pod-disruption-budget" text="PodDisruptionBudget">}}.
You may be able to attempt the eviction again later. You might also see this
response because of API rate limiting.
* `500 Internal Server Error`: the eviction is not allowed because there is a
misconfiguration, like if multiple PodDisruptionBudgets reference the same Pod.
If the Pod you want to evict isn't part of a workload that has a
PodDisruptionBudget, the API server always returns `200 OK` and allows the
eviction.
If the API server allows the eviction, the Pod is deleted as follows:
1. The `Pod` resource in the API server is updated with a deletion timestamp,
after which the API server considers the `Pod` resource to be terminated. The
`Pod` resource is also marked with the configured grace period.
1. The {{<glossary_tooltip term_id="kubelet" text="kubelet">}} on the node where the local Pod is running notices that the `Pod`
resource is marked for termination and starts to gracefully shut down the
local Pod.
1. While the kubelet is shutting the Pod down, the control plane removes the Pod
from {{<glossary_tooltip term_id="endpoint" text="Endpoint">}} and
{{<glossary_tooltip term_id="endpoint-slice" text="EndpointSlice">}}
objects. As a result, controllers no longer consider the Pod as a valid object.
1. After the grace period for the Pod expires, the kubelet forcefully terminates
the local Pod.
1. The kubelet tells the API server to remove the `Pod` resource.
1. The API server deletes the `Pod` resource.
## Troubleshooting stuck evictions
In some cases, your applications may enter a broken state, where the Eviction
API will only return `429` or `500` responses until you intervene. This can
happen if, for example, a ReplicaSet creates pods for your application but new
pods do not enter a `Ready` state. You may also notice this behavior in cases
where the last evicted Pod had a long termination grace period.
If you notice stuck evictions, try one of the following solutions:
* Abort or pause the automated operation causing the issue. Investigate the stuck
application before you restart the operation.
* Wait a while, then directly delete the Pod from your cluster control plane
instead of using the Eviction API.
## {{% heading "whatsnext" %}}
* Learn about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/)
* Learn about [Pod Priority and Preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/)
* Learn how to protect your applications with a [Pod Disruption Budget](/docs/tasks/run-application/configure-pdb/).
* Learn about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/).
* Learn about [Pod Priority and Preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/).
content/en/docs/concepts/security/overview.md
+1 -1
View File
@@ -123,7 +123,7 @@ Area of Concern for Containers | Recommendation |
Container Vulnerability Scanning and OS Dependency Security | As part of an image build step, you should scan your containers for known vulnerabilities.
Image Signing and Enforcement | Sign container images to maintain a system of trust for the content of your containers.
Disallow privileged users | When constructing containers, consult your documentation for how to create users inside of the containers that have the least level of operating system privilege necessary in order to carry out the goal of the container.
Use container runtime with stronger isolation | Select [container runtime classes](/docs/concepts/containers/runtime-class/) that provider stronger isolation
Use container runtime with stronger isolation | Select [container runtime classes](/docs/concepts/containers/runtime-class/) that provide stronger isolation
## Code
content/en/docs/concepts/security/pod-security-admission.md
+2 -2
View File
@@ -19,7 +19,7 @@ The Kubernetes [Pod Security Standards](/docs/concepts/security/pod-security-sta
different isolation levels for Pods. These standards let you define how you want to restrict the
behavior of pods in a clear, consistent fashion.
As an Beta feature, Kubernetes offers a built-in _Pod Security_ {{< glossary_tooltip
As a Beta feature, Kubernetes offers a built-in _Pod Security_ {{< glossary_tooltip
text="admission controller" term_id="admission-controller" >}}, the successor
to [PodSecurityPolicies](/docs/concepts/policy/pod-security-policy/). Pod security restrictions
are applied at the {{< glossary_tooltip text="namespace" term_id="namespace" >}} level when pods
@@ -125,7 +125,7 @@ applied to workload resources, only to the resulting pod objects.
## Exemptions
You can define _exemptions_ from pod security enforcement in order allow the creation of pods that
You can define _exemptions_ from pod security enforcement in order to allow the creation of pods that
would have otherwise been prohibited due to the policy associated with a given namespace.
Exemptions can be statically configured in the
[Admission Controller configuration](/docs/tasks/configure-pod-container/enforce-standards-admission-controller/#configure-the-admission-controller).
content/en/docs/concepts/security/pod-security-standards.md
+2 -2
View File
@@ -52,8 +52,8 @@ fail validation.
<caption style="display:none">Baseline policy specification</caption>
<tbody>
<tr>
<td><strong>Control</strong></td>
<td><strong>Policy</strong></td>
<th>Control</th>
<th>Policy</th>
</tr>
<tr>
<td style="white-space: nowrap">HostProcess</td>
content/en/docs/concepts/services-networking/endpoint-slices.md
+3 -3
View File
@@ -147,9 +147,9 @@ In the v1 API, the per endpoint `topology` was effectively removed in favor of
the dedicated fields `nodeName` and `zone`.
Setting arbitrary topology fields on the `endpoint` field of an `EndpointSlice`
resource has been deprecated and is not be supported in the v1 API. Instead,
the v1 API supports setting individual `nodeName` and `zone` fields. These
fields are automatically translated between API versions. For example, the
resource has been deprecated and is not supported in the v1 API.
Instead, the v1 API supports setting individual `nodeName` and `zone` fields.
These fields are automatically translated between API versions. For example, the
value of the `"topology.kubernetes.io/zone"` key in the `topology` field in
the v1beta1 API is accessible as the `zone` field in the v1 API.
{{< /note >}}
content/en/docs/concepts/services-networking/ingress-controllers.md
+1
View File
@@ -48,6 +48,7 @@ Kubernetes as a project supports and maintains [AWS](https://github.com/kubernet
is an ingress controller driving [Kong Gateway](https://konghq.com/kong/).
* 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.
* [Skipper](https://opensource.zalando.com/skipper/kubernetes/ingress-controller/) HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress, designed as a library to build your custom proxy.
* The [Traefik Kubernetes Ingress provider](https://doc.traefik.io/traefik/providers/kubernetes-ingress/) is an
ingress controller for the [Traefik](https://traefik.io/traefik/) proxy.
content/en/docs/concepts/services-networking/topology-aware-hints.md
+1 -1
View File
@@ -30,7 +30,7 @@ Routing". When calculating the endpoints for a {{< glossary_tooltip term_id="Ser
the EndpointSlice controller considers the topology (region and zone) of each endpoint
and populates the hints field to allocate it to a zone.
Cluster components such as the {{< glossary_tooltip term_id="kube-proxy" text="kube-proxy" >}}
can then consume those hints, and use them to influence how traffic to is routed
can then consume those hints, and use them to influence how the traffic is routed
(favoring topologically closer endpoints).
## Using Topology Aware Hints
content/en/docs/concepts/storage/persistent-volumes.md
+1 -1
View File
@@ -339,7 +339,7 @@ If that has happened, or you suspect that it might have, you can retry expansion
size that is within the capacity limits of underlying storage provider. You can monitor status of resize operation by watching `.status.resizeStatus` and events on the PVC.
Note that,
although you can a specify a lower amount of storage than what was requested previously,
although you can specify a lower amount of storage than what was requested previously,
the new value must still be higher than `.status.capacity`.
Kubernetes does not support shrinking a PVC to less than its current size.
{{% /tab %}}
content/en/docs/concepts/storage/storage-classes.md
+3 -3
View File
@@ -49,7 +49,7 @@ metadata:
name: standard
provisioner: kubernetes.io/aws-ebs
parameters:
type: gp2
type: gp3
reclaimPolicy: Retain
allowVolumeExpansion: true
mountOptions:
@@ -271,9 +271,9 @@ parameters:
fsType: ext4
```
* `type`: `io1`, `gp2`, `sc1`, `st1`. See
* `type`: `io1`, `gp2`, `gp3`, `sc1`, `st1`. See
[AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html)
for details. Default: `gp2`.
for details. Default: `gp3`.
* `zone` (Deprecated): AWS zone. If neither `zone` nor `zones` is specified, volumes are
generally round-robin-ed across all active zones where Kubernetes cluster
has a node. `zone` and `zones` parameters must not be used at the same time.
content/en/docs/concepts/workloads/controllers/job.md
+1 -1
View File
@@ -308,7 +308,7 @@ cleaned up by CronJobs based on the specified capacity-based cleanup policy.
### TTL mechanism for finished Jobs
{{< feature-state for_k8s_version="v1.21" state="beta" >}}
{{< feature-state for_k8s_version="v1.23" state="stable" >}}
Another way to clean up finished Jobs (either `Complete` or `Failed`)
automatically is to use a TTL mechanism provided by a
content/en/docs/contribute/advanced.md
+1
View File
@@ -86,6 +86,7 @@ Responsibilities for New Contributor Ambassadors include:
- Mentoring new contributors through their first few PRs to the docs repo.
- Helping new contributors create the more complex PRs they need to become Kubernetes members.
- [Sponsoring contributors](/docs/contribute/advanced/#sponsor-a-new-contributor) on their path to becoming Kubernetes members.
- Hosting a monthly meeting to help and mentor new contributors.
Current New Contributor Ambassadors are announced at each SIG-Docs meeting and in the [Kubernetes #sig-docs channel](https://kubernetes.slack.com).
content/en/docs/contribute/new-content/blogs-case-studies.md
+9
View File
@@ -83,6 +83,15 @@ To submit a blog post follow these directions:
- _initial commit_
- _draft post_
- The blog team will then review your PR and give you comments on things you might need to fix. After that the bot will merge your PR and your blog post will be published.
- If the content of the blog post contains only content that is not expected to require updates to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic warning about outdated content added to blog posts older than one year.
- To mark a blog post as evergreen, add this to the front matter:
```yaml
evergreen: true
```
- Examples of content that should not be marked evergreen:
- **Tutorials** that only apply to specific releases or versions and not all future versions
- References to pre-GA APIs or features
## Submit a case study
content/en/docs/contribute/review/reviewing-prs.md
+2 -2
View File
@@ -36,7 +36,7 @@ Before you start a review:
## Review process
In general, review pull requests for content and style in English. The figure below outlines the steps for the review process. The details for each step follow.
In general, review pull requests for content and style in English. Figure 1 outlines the steps for the review process. The details for each step follow.
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
@@ -67,7 +67,7 @@ class S,T spacewhite
class third,fourth white
{{</ mermaid >}}
***Figure - Review process steps***
Figure 1. Review process steps.
1. Go to
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
content/en/docs/contribute/style/diagram-guide.md
+184 -76
View File
@@ -7,9 +7,13 @@ weight: 15
<!--Overview-->
This guide shows you how to create, edit and share diagrams using the Mermaid Javascript library. Mermaid.js allows you to generate diagrams using a simple markdown-like syntax inside Markdown files. You can also use Mermaid to generate `.svg` or `.png` image files that you can add to your documentation.
This guide shows you how to create, edit and share diagrams using the Mermaid
Javascript library. Mermaid.js allows you to generate diagrams using a simple
markdown-like syntax inside Markdown files. You can also use Mermaid to
generate `.svg` or `.png` image files that you can add to your documentation.
The target audience for this guide is anybody wishing to learn about Mermaid and/or how to create and add diagrams to Kubernetes documentation.
The target audience for this guide is anybody wishing to learn about Mermaid
and/or how to create and add diagrams to Kubernetes documentation.
Figure 1 outlines the topics covered in this section.
@@ -54,11 +58,12 @@ All you need to begin working with Mermaid is the following:
* Using the Mermaid live editor.
* Using [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/).
* Using the [Hugo {{</* figure */>}} shortcode](https://gohugo.io/content-management/shortcodes/#figure).
* Performing [Hugo local previews](https://kubernetes.io/docs/contribute/new-content/open-a-pr/#preview-locally).
* Performing [Hugo local previews](/docs/contribute/new-content/open-a-pr/#preview-locally).
* Familiar with the [Contributing new content](/docs/contribute/new-content/) process.
{{< note >}}
You can click on each diagram in this section to view the code and rendered diagram in the Mermaid live editor.
You can click on each diagram in this section to view the code and rendered
diagram in the Mermaid live editor.
{{< /note >}}
<!--body-->
@@ -69,21 +74,32 @@ Diagrams improve documentation clarity and comprehension. There are advantages f
The user benefits include:
* __Friendly landing spot__. A detailed text-only greeting page could intimidate users, in particular, first-time Kubernetes users.
* __Faster grasp of concepts__. A diagram can help users understand the key points of a complex topic. Your diagram can serve as a visual learning guide to dive into the topic details.
* __Friendly landing spot__. A detailed text-only greeting page could
intimidate users, in particular, first-time Kubernetes users.
* __Faster grasp of concepts__. A diagram can help users understand the key
points of a complex topic. Your diagram can serve as a visual learning guide
to dive into the topic details.
* __Better retention__. For some, it is easier to recall pictures rather than text.
The contributor benefits include:
* __Assist in developing the structure and content__ of your contribution. For example, you can start with a simple diagram covering the high-level points and then dive into details.
* __Expand and grow the user community__. Easily consumed documentation augmented with diagrams attracts new users who might previously have been reluctant to engage due to perceived complexities.
You should consider your target audience. In addition to experienced K8s users, you will have many who are new to Kubernetes. Even a simple diagram can assist new users in absorbing Kubernetes concepts. They become emboldened and more confident to further explore Kubernetes and the documentation.
* __Assist in developing the structure and content__ of your contribution. For
example, you can start with a simple diagram covering the high-level points
and then dive into details.
* __Expand and grow the user community__. Easily consumed documentation
augmented with diagrams attracts new users who might previously have been
reluctant to engage due to perceived complexities.
You should consider your target audience. In addition to experienced K8s
users, you will have many who are new to Kubernetes. Even a simple diagram can
assist new users in absorbing Kubernetes concepts. They become emboldened and
more confident to further explore Kubernetes and the documentation.
## Mermaid
[Mermaid](https://mermaid-js.github.io/mermaid/#/) is an open source JavaScript library that allows you to create, edit and easily share diagrams using a simple, markdown-like syntax configured inline in Markdown files.
[Mermaid](https://mermaid-js.github.io/mermaid/#/) is an open source
JavaScript library that allows you to create, edit and easily share diagrams
using a simple, markdown-like syntax configured inline in Markdown files.
The following lists features of Mermaid:
@@ -93,35 +109,40 @@ The following lists features of Mermaid:
* Easy collaboration with colleagues by sharing a per-diagram URL.
* Broad selection of shapes, lines, themes and styling.
The following lists advantages of using Mermaid:
* No need for separate, non-Mermaid diagram tools.
* Adheres to existing PR workflow. You can think of Mermaid code as just Markdown text included in your PR.
* Simple tool builds simple diagrams. You don't want to get bogged down (re)crafting an overly complex and detailed picture. Keep it simple!
* Adheres to existing PR workflow. You can think of Mermaid code as just
Markdown text included in your PR.
* Simple tool builds simple diagrams. You don't want to get bogged down
(re)crafting an overly complex and detailed picture. Keep it simple!
Mermaid provides a simple, open and transparent method for the SIG communities to add, edit and collaborate on diagrams for new or existing documentation.
Mermaid provides a simple, open and transparent method for the SIG communities
to add, edit and collaborate on diagrams for new or existing documentation.
{{< note >}}
You can still use Mermaid to create/edit diagrams even if it's not supported in your environment. This method is called __Mermaid+SVG__ and is explained below.
You can still use Mermaid to create/edit diagrams even if it's not supported
in your environment. This method is called __Mermaid+SVG__ and is explained
below.
{{< /note >}}
### Live editor
The [Mermaid live editor](https://mermaid-js.github.io/mermaid-live-editor) is a web-based tool that enables you to create, edit and review diagrams.
The [Mermaid live editor](https://mermaid-js.github.io/mermaid-live-editor) is
a web-based tool that enables you to create, edit and review diagrams.
The following lists live editor functions:
* Displays Mermaid code and rendered diagram.
* Generates a URL for each saved diagram. The URL is displayed in the URL field of your browser. You can share the URL with colleagues who can access and modify the diagram.
* Generates a URL for each saved diagram. The URL is displayed in the URL
field of your browser. You can share the URL with colleagues who can access
and modify the diagram.
* Option to download `.svg` or `.png` files.
{{< note >}}
The live editor is the easiest and fastest way to create and edit Mermaid diagrams.
{{< /note >}}
## Methods for creating diagrams
Figure 2 outlines the three methods to generate and add diagrams.
@@ -157,7 +178,8 @@ Figure 2. Methods to create diagrams.
### Inline
Figure 3 outlines the steps to follow for adding a diagram using the Inline method.
Figure 3 outlines the steps to follow for adding a diagram using the Inline
method.
{{< mermaid >}}
graph LR
@@ -182,7 +204,6 @@ click D "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3Jh
{{< /mermaid >}}
Figure 3. Inline Method steps.
@@ -196,8 +217,11 @@ The following lists the steps you should follow for adding a diagram using the I
4. Add a caption below the diagram using Markdown text.
A Hugo build runs the Mermaid code and turns it into a diagram.
{{< note >}}
You may find keeping track of diagram URLs is cumbersome. If so, make a note in the `.md` file that the Mermaid code is self-documenting. Contributors can copy the Mermaid code to and from the live editor for diagram edits.
You may find keeping track of diagram URLs is cumbersome. If so, make a note
in the `.md` file that the Mermaid code is self-documenting. Contributors can
copy the Mermaid code to and from the live editor for diagram edits.
{{< /note >}}
Here is a sample code snippet contained in an `.md` file:
@@ -218,7 +242,9 @@ Figure 17. A to B
more text
```
{{< note >}}
You must include the `{{</* mermaid */>}}`, `{{</* /mermaid */>}}` shortcode tags at the start and end of the Mermaid code block. You should add a diagram caption below the diagram.
You must include the `{{</* mermaid */>}}`, `{{</* /mermaid */>}}` shortcode
tags at the start and end of the Mermaid code block. You should add a diagram
caption below the diagram.
{{< /note >}}
For more details on diagram captions, see [How to use captions](#how-to-use-captions).
@@ -230,10 +256,13 @@ The following lists advantages of the Inline method:
* No need for separate `.svg` image file handling.
* Content text, diagram code and diagram caption contained in the same `.md` file.
You should use the [local](https://kubernetes.io/docs/contribute/new-content/open-a-pr/#preview-locally) and Netlify previews to verify the diagram is properly rendered.
You should use the [local](/docs/contribute/new-content/open-a-pr/#preview-locally)
and Netlify previews to verify the diagram is properly rendered.
{{< caution >}}
The Mermaid live editor feature set may not support the K8s/website Mermaid feature set. You might see a syntax error or a blank screen after the Hugo build. If that is the case, consider using the Mermaid+SVG method.
The Mermaid live editor feature set may not support the K8s/website Mermaid feature set.
You might see a syntax error or a blank screen after the Hugo build.
If that is the case, consider using the Mermaid+SVG method.
{{< /caution >}}
### Mermaid+SVG
@@ -281,9 +310,13 @@ The following lists the steps you should follow for adding a diagram using the M
4. Use the `{{</* figure */>}}` shortcode to reference the diagram in the `.md` file.
5. Add a caption using the `{{</* figure */>}}` shortcode's `caption` parameter.
For example, use the live editor to create a diagram called `boxnet`. Store the diagram URL somewhere for later access. Generate and download a `boxnet.svg` file to the appropriate `../images/` folder.
For example, use the live editor to create a diagram called `boxnet`.
Store the diagram URL somewhere for later access. Generate and download a
`boxnet.svg` file to the appropriate `../images/` folder.
Use the `{{</* figure */>}}` shortcode in your PR's `.md` file to reference
the `.svg` image file and add a caption.
Use the `{{</* figure */>}}` shortcode in your PR's `.md` file to reference the `.svg` image file and add a caption.
```json
{{</* figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" */>}}
```
@@ -291,10 +324,14 @@ Use the `{{</* figure */>}}` shortcode in your PR's `.md` file to reference the
For more details on diagram captions, see [How to use captions](#how-to-use-captions).
{{< note >}}
The `{{</* figure */>}}` shortcode is the preferred method for adding `.svg` image files to your documentation. You can also use the standard markdown image syntax like so: `![my boxnet diagram](static/images/boxnet.svg)`. And you will need to add a caption below the diagram.
The `{{</* figure */>}}` shortcode is the preferred method for adding `.svg` image files
to your documentation. You can also use the standard markdown image syntax like so:
`![my boxnet diagram](static/images/boxnet.svg)`.
And you will need to add a caption below the diagram.
{{< /note >}}
You should add the live editor URL as a comment block in the `.svg` image file using a text editor. For example, you would include the following at the beginning of the `.svg` image file:
You should add the live editor URL as a comment block in the `.svg` image file using a text editor.
For example, you would include the following at the beginning of the `.svg` image file:
```
<!-- To view or edit the mermaid code, use the following URL: -->
@@ -308,13 +345,17 @@ The following lists advantages of the Mermaid+SVG method:
* Employ existing K8s/website methods for handling `.svg` image files.
* Environment doesn't require Mermaid support.
Be sure to check that your diagram renders properly using the [local](https://kubernetes.io/docs/contribute/new-content/open-a-pr/#preview-locally) and Netlify previews.
Be sure to check that your diagram renders properly using the
[local](/docs/contribute/new-content/open-a-pr/#preview-locally)
and Netlify previews.
### External tool
Figure 5 outlines the steps to follow for adding a diagram using the External Tool method.
First, use your external tool to create the diagram and save it as an `.svg` or `.png` image file. After that, use the same steps as the __Mermaid+SVG__ method for adding `.svg` image files.
First, use your external tool to create the diagram and save it as an `.svg`
or `.png` image file. After that, use the same steps as the __Mermaid+SVG__
method for adding `.svg` image files.
{{< mermaid >}}
flowchart LR
@@ -350,8 +391,11 @@ Figure 5. External Tool method steps
The following lists the steps you should follow for adding a diagram using the External Tool method:
1. Use your external tool to create a diagram.
2. Save the diagram coordinates for contributor access. For example, your tool may offer a link to the diagram image, or you could place the source code file, such as an `.xml` file, in a public repository for later contributor access.
3. Generate and save the diagram as an `.svg` or `.png` image file. Download this file to the appropriate `../images/` folder.
2. Save the diagram coordinates for contributor access. For example, your tool
may offer a link to the diagram image, or you could place the source code
file, such as an `.xml` file, in a public repository for later contributor access.
3. Generate and save the diagram as an `.svg` or `.png` image file.
Download this file to the appropriate `../images/` folder.
4. Use the `{{</* figure */>}}` shortcode to reference the diagram in the `.md` file.
5. Add a caption using the `{{</* figure */>}}` shortcode's `caption` parameter.
@@ -362,30 +406,40 @@ Here is the `{{</* figure */>}}` shortcode for the `images/apple.svg` diagram:
If your external drawing tool permits:
* You can incorporate multiple `.svg` or `.png` logos, icons and images into your diagram. However, make sure you observe copyright and follow the Kubernetes documentation
* You can incorporate multiple `.svg` or `.png` logos, icons and images into your diagram.
However, make sure you observe copyright and follow the Kubernetes documentation
[guidelines](/docs/contribute/style/content-guide/) on the use of third party content.
* You should save the diagram source coordinates for later contributor access. For example, your tool may offer a link to the diagram image, or you could place the source code file, such as an `.xml` file, somewhere for contributor access.
* You should save the diagram source coordinates for later contributor access.
For example, your tool may offer a link to the diagram image, or you could
place the source code file, such as an `.xml` file, somewhere for contributor access.
For more information on K8s and CNCF logos and images, check out [CNCF Artwork](https://github.com/cncf/artwork).
For more information on K8s and CNCF logos and images, check out
[CNCF Artwork](https://github.com/cncf/artwork).
The following lists advantages of the External Tool method:
* Contributor familiarity with external tool.
* Diagrams require more detail than what Mermaid can offer.
Don't forget to check that your diagram renders correctly using the [local](https://kubernetes.io/docs/contribute/new-content/open-a-pr/#preview-locally) and Netlify previews.
Don't forget to check that your diagram renders correctly using the
[local](/docs/contribute/new-content/open-a-pr/#preview-locally) and Netlify previews.
## Examples
This section shows several examples of Mermaid diagrams.
{{< note >}}
The code block examples omit the Hugo `{{</* mermaid */>}}`, `{{</* /mermaid */>}}` shortcode tags. This allows you to copy the code block into the live editor to experiment on your own. Note that the live editor doesn't recognize Hugo shortcodes.
The code block examples omit the Hugo `{{</* mermaid */>}}`, `{{</* /mermaid */>}}`
shortcode tags. This allows you to copy the code block into the live editor
to experiment on your own.
Note that the live editor doesn't recognize Hugo shortcodes.
{{< /note >}}
### Example 1 - Pod topology spread constraints
Figure 6 shows the diagram appearing in the [Pod Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/#node-labels) page.
Figure 6 shows the diagram appearing in the
[Pod topology pread constraints](/docs/concepts/workloads/pods/pod-topology-spread-constraints/#node-labels)
page.
{{< mermaid >}}
graph TB
@@ -417,6 +471,7 @@ click n2 "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3J
Figure 6. Pod Topology Spread Constraints.
Code block:
```
graph TB
subgraph "zoneB"
@@ -437,7 +492,7 @@ graph TB
### Example 2 - Ingress
Figure 7 shows the diagram appearing in the [What is Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress) page.
Figure 7 shows the diagram appearing in the [What is Ingress](/docs/concepts/services-networking/ingress/#what-is-ingress) page.
{{< mermaid >}}
graph LR;
@@ -491,13 +546,15 @@ graph LR;
### Example 3 - K8s system flow
Figure 8 depicts a Mermaid sequence diagram showing the system flow between K8s components to start a container.
Figure 8 depicts a Mermaid sequence diagram showing the system flow between
K8s components to start a container.
{{< figure src="/docs/images/diagram-guide-example-3.svg" alt="K8s system flow diagram" class="diagram-large" caption="Figure 8. K8s system flow diagram" link="https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiJSV7aW5pdDp7XCJ0aGVtZVwiOlwibmV1dHJhbFwifX0lJVxuc2VxdWVuY2VEaWFncmFtXG4gICAgYWN0b3IgbWVcbiAgICBwYXJ0aWNpcGFudCBhcGlTcnYgYXMgY29udHJvbCBwbGFuZTxicj48YnI-YXBpLXNlcnZlclxuICAgIHBhcnRpY2lwYW50IGV0Y2QgYXMgY29udHJvbCBwbGFuZTxicj48YnI-ZXRjZCBkYXRhc3RvcmVcbiAgICBwYXJ0aWNpcGFudCBjbnRybE1nciBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5jb250cm9sbGVyPGJyPm1hbmFnZXJcbiAgICBwYXJ0aWNpcGFudCBzY2hlZCBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5zY2hlZHVsZXJcbiAgICBwYXJ0aWNpcGFudCBrdWJlbGV0IGFzIG5vZGU8YnI-PGJyPmt1YmVsZXRcbiAgICBwYXJ0aWNpcGFudCBjb250YWluZXIgYXMgbm9kZTxicj48YnI-Y29udGFpbmVyPGJyPnJ1bnRpbWVcbiAgICBtZS0-PmFwaVNydjogMS4ga3ViZWN0bCBjcmVhdGUgLWYgcG9kLnlhbWxcbiAgICBhcGlTcnYtLT4-ZXRjZDogMi4gc2F2ZSBuZXcgc3RhdGVcbiAgICBjbnRybE1nci0-PmFwaVNydjogMy4gY2hlY2sgZm9yIGNoYW5nZXNcbiAgICBzY2hlZC0-PmFwaVNydjogNC4gd2F0Y2ggZm9yIHVuYXNzaWduZWQgcG9kcyhzKVxuICAgIGFwaVNydi0-PnNjaGVkOiA1LiBub3RpZnkgYWJvdXQgcG9kIHcgbm9kZW5hbWU9XCIgXCJcbiAgICBzY2hlZC0-PmFwaVNydjogNi4gYXNzaWduIHBvZCB0byBub2RlXG4gICAgYXBpU3J2LS0-PmV0Y2Q6IDcuIHNhdmUgbmV3IHN0YXRlXG4gICAga3ViZWxldC0-PmFwaVNydjogOC4gbG9vayBmb3IgbmV3bHkgYXNzaWduZWQgcG9kKHMpXG4gICAgYXBpU3J2LT4-a3ViZWxldDogOS4gYmluZCBwb2QgdG8gbm9kZVxuICAgIGt1YmVsZXQtPj5jb250YWluZXI6IDEwLiBzdGFydCBjb250YWluZXJcbiAgICBrdWJlbGV0LT4-YXBpU3J2OiAxMS4gdXBkYXRlIHBvZCBzdGF0dXNcbiAgICBhcGlTcnYtLT4-ZXRjZDogMTIuIHNhdmUgbmV3IHN0YXRlIiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjp0cnVlfQ" >}}
Code block:
```
%%{init:{"theme":"neutral"}}%%
sequenceDiagram
@@ -524,29 +581,43 @@ sequenceDiagram
## How to style diagrams
You can style one or more diagram elements using well-known CSS nomenclature. You accomplish this using two types of statements in the Mermaid code.
You can style one or more diagram elements using well-known CSS nomenclature.
You accomplish this using two types of statements in the Mermaid code.
* `classDef` defines a class of style attributes.
* `class` defines one or more elements to apply the class to.
In the code for [figure 7](https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0), you can see examples of both.
In the code for
[figure 7](https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZ3JhcGggIExSXG4gIGNsaWVudChbY2xpZW50XSktLiBJbmdyZXNzLW1hbmFnZWQgPGJyPiBsb2FkIGJhbGFuY2VyIC4tPmluZ3Jlc3NbSW5ncmVzc107XG4gIGluZ3Jlc3MtLT58cm91dGluZyBydWxlfHNlcnZpY2VbU2VydmljZV07XG4gIHN1YmdyYXBoIGNsdXN0ZXJcbiAgaW5ncmVzcztcbiAgc2VydmljZS0tPnBvZDFbUG9kXTtcbiAgc2VydmljZS0tPnBvZDJbUG9kXTtcbiAgZW5kXG4gIGNsYXNzRGVmIHBsYWluIGZpbGw6I2RkZCxzdHJva2U6I2ZmZixzdHJva2Utd2lkdGg6NHB4LGNvbG9yOiMwMDA7XG4gIGNsYXNzRGVmIGs4cyBmaWxsOiMzMjZjZTUsc3Ryb2tlOiNmZmYsc3Ryb2tlLXdpZHRoOjRweCxjb2xvcjojZmZmO1xuICBjbGFzc0RlZiBjbHVzdGVyIGZpbGw6I2ZmZixzdHJva2U6I2JiYixzdHJva2Utd2lkdGg6MnB4LGNvbG9yOiMzMjZjZTU7XG4gIGNsYXNzIGluZ3Jlc3Msc2VydmljZSxwb2QxLHBvZDIgazhzO1xuICBjbGFzcyBjbGllbnQgcGxhaW47XG4gIGNsYXNzIGNsdXN0ZXIgY2x1c3RlcjtcbiIsIm1lcm1haWQiOiJ7XG4gIFwidGhlbWVcIjogXCJkZWZhdWx0XCJcbn0iLCJ1cGRhdGVFZGl0b3IiOmZhbHNlLCJhdXRvU3luYyI6dHJ1ZSwidXBkYXRlRGlhZ3JhbSI6dHJ1ZX0),
you can see examples of both.
```
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // defines style for the k8s class
class ingress,service,pod1,pod2 k8s; // k8s class is applied to elements ingress, service, pod1 and pod2.
```
You can include one or multiple `classDef` and `class` statements in your diagram. You can also use the official K8s `#326ce5` hex color code for K8s components in your diagram.
For more information on styling and classes, see [Mermaid Styling and classes docs](https://mermaid-js.github.io/mermaid/#/flowchart?id=styling-and-classes).
You can include one or multiple `classDef` and `class` statements in your diagram.
You can also use the official K8s `#326ce5` hex color code for K8s components in your diagram.
For more information on styling and classes, see
[Mermaid Styling and classes docs](https://mermaid-js.github.io/mermaid/#/flowchart?id=styling-and-classes).
## How to use captions
A caption is a brief description of a diagram. A title or a short description of the diagram are examples of captions. Captions aren't meant to replace explanatory text you have in your documentation. Rather, they serve as a "context link" between that text and your diagram.
A caption is a brief description of a diagram. A title or a short description
of the diagram are examples of captions. Captions aren't meant to replace
explanatory text you have in your documentation. Rather, they serve as a
"context link" between that text and your diagram.
The combination of some text and a diagram tied together with a caption help provide a concise representation of the information you wish to convey to the user.
The combination of some text and a diagram tied together with a caption help
provide a concise representation of the information you wish to convey to the
user.
Without captions, you are asking the user to scan the text above or below the diagram to figure out a meaning. This can be frustrating for the user.
Without captions, you are asking the user to scan the text above or below the
diagram to figure out a meaning. This can be frustrating for the user.
Figure 9 lays out the three components for proper captioning: diagram, diagram caption and the diagram referral.
Figure 9 lays out the three components for proper captioning: diagram, diagram
caption and the diagram referral.
{{< mermaid >}}
flowchart
@@ -574,94 +645,131 @@ You should always add a caption to each diagram in your documentation.
The `Mermaid+SVG` and `External Tool` methods generate `.svg` image files.
Here is the `{{</* figure */>}}` shortcode for the diagram defined in an `.svg` image file saved to `/images/docs/components-of-kubernetes.svg`:
```text
Here is the `{{</* figure */>}}` shortcode for the diagram defined in an
`.svg` image file saved to `/images/docs/components-of-kubernetes.svg`:
```none
{{</* figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 4. Kubernetes Architecture Components */>}}
```
You should pass the `src`, `alt`, `class` and `caption` values into the `{{</* figure */>}}` shortcode. You can adjust the size of the diagram using `diagram-large`, `diagram-medium` and `diagram-small` classes.
You should pass the `src`, `alt`, `class` and `caption` values into the
`{{</* figure */>}}` shortcode. You can adjust the size of the diagram using
`diagram-large`, `diagram-medium` and `diagram-small` classes.
{{< note >}}
Diagrams created using the `Inline` method don't use the `{{</* figure */>}}` shortcode. The Mermaid code defines how the diagram will render on your page.
Diagrams created using the `Inline` method don't use the `{{</* figure */>}}`
shortcode. The Mermaid code defines how the diagram will render on your page.
{{< /note >}}
See [Methods for creating diagrams](#methods-for-creating-diagrams) for more information on the different methods for creating diagrams.
See [Methods for creating diagrams](#methods-for-creating-diagrams)
for more information on the different methods for creating diagrams.
**Diagram Caption**
Next, add a diagram caption.
If you define your diagram in an `.svg` image file, then you should use the `{{</* figure */>}}` shortcode's `caption` parameter.
If you define your diagram in an `.svg` image file, then you should use the
`{{</* figure */>}}` shortcode's `caption` parameter.
```text
```none
{{</* figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 4. Kubernetes Architecture Components" */>}}
```
If you define your diagram using inline Mermaid code, then you should use Markdown text.
```text
```none
Figure 4. Kubernetes Architecture Components
```
The following lists several items to consider when adding diagram captions:
* Use the `{{</* figure */>}}` shortcode to add a diagram caption for `Mermaid+SVG` and `External Tool` diagrams.
* Use the `{{</* figure */>}}` shortcode to add a diagram caption for `Mermaid+SVG`
and `External Tool` diagrams.
* Use simple Markdown text to add a diagram caption for the `Inline` method.
* Prepend your diagram caption with `Figure NUMBER.`. You must use `Figure` and the number must be unique for each diagram in your documentation page. Add a period after the number.
* Add your diagram caption text after the `Figure NUMBER.` on the same line. You must puncuate the caption with a period. Keep the caption text short.
* Prepend your diagram caption with `Figure NUMBER.`. You must use `Figure`
and the number must be unique for each diagram in your documentation page.
Add a period after the number.
* Add your diagram caption text after the `Figure NUMBER.` on the same line.
You must puncuate the caption with a period. Keep the caption text short.
* Position your diagram caption __BELOW__ your diagram.
**Diagram Referral**
Finally, you can add a diagram referral. This is used inside your text and should precede the diagram itself. It allows a user to connect your text with the associated diagram. The `Figure NUMBER` in your referral and caption must match.
Finally, you can add a diagram referral. This is used inside your text and
should precede the diagram itself. It allows a user to connect your text with
the associated diagram. The `Figure NUMBER` in your referral and caption must
match.
You should avoid using spatial references such as `..the image below..` or `..the following figure ..`
You should avoid using spatial references such as `..the image below..` or
`..the following figure ..`
Here is an example of a diagram referral:
```text
Figure 10 depicts the components of the Kubernetes architecture. The control plane ...
Figure 10 depicts the components of the Kubernetes architecture.
The control plane ...
```
Diagram referrals are optional and there are cases where they might not be suitable. If you are not sure, add a diagram referral to your text to see if it looks and sounds okay. When in doubt, use a diagram referral.
Diagram referrals are optional and there are cases where they might not be
suitable. If you are not sure, add a diagram referral to your text to see if
it looks and sounds okay. When in doubt, use a diagram referral.
**Complete picture**
Figure 10 shows the Kubernetes Architecture diagram that includes the diagram, diagram caption and diagram referral. The `{{</* figure */>}}` shortcode renders the diagram, adds the caption and includes the optional `link` parameter so you can hyperlink the diagram. The diagram referral is contained in this paragraph.
Figure 10 shows the Kubernetes Architecture diagram that includes the diagram,
diagram caption and diagram referral. The `{{</* figure */>}}` shortcode
renders the diagram, adds the caption and includes the optional `link`
parameter so you can hyperlink the diagram. The diagram referral is contained
in this paragraph.
Here is the `{{</* figure */>}}` shortcode for this diagram:
```
{{</* figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 10. Kubernetes Architecture." link="https://kubernetes.io/docs/concepts/overview/components/" */>}}
```
{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Figure 10. Kubernetes Architecture." link="https://kubernetes.io/docs/concepts/overview/components/" >}}
## Tips
* Always use the live editor to create/edit your diagram.
* Always use Hugo local and Netlify previews to check out how the diagram appears in the documentation.
* Always use Hugo local and Netlify previews to check out how the diagram
appears in the documentation.
* Include diagram source pointers such as a URL, source code location, or indicate the code is self-documenting.
* Include diagram source pointers such as a URL, source code location, or
indicate the code is self-documenting.
* Always use diagram captions.
* Very helpful to include the diagram `.svg` or `.png` image and/or Mermaid source code in issues and PRs.
* Very helpful to include the diagram `.svg` or `.png` image and/or Mermaid
source code in issues and PRs.
* With the `Mermaid+SVG` and `External Tool` methods, use `.svg` image files because they stay sharp when you zoom in on the diagram.
* With the `Mermaid+SVG` and `External Tool` methods, use `.svg` image files
because they stay sharp when you zoom in on the diagram.
* Best practice for `.svg` files is to load it into an SVG editing tool and use the
“Convert text to paths” function. This ensures that the diagram renders the same on all systems, regardless of font availability and font rendering support.
"Convert text to paths" function.
This ensures that the diagram renders the same on all systems, regardless of font
availability and font rendering support.
* No Mermaid support for additional icons or artwork.
* Hugo Mermaid shortcodes don't work in the live editor.
* Any time you modify a diagram in the live editor, you __must save__ it to generate a new URL for the diagram.
* Any time you modify a diagram in the live editor, you __must__ save it
to generate a new URL for the diagram.
* Click on the diagrams in this section to view the code and diagram rendering in the live editor.
* Click on the diagrams in this section to view the code and diagram rendering
in the live editor.
* Look over the source code of this page, `diagram-guide.md`, for more examples.
* Check out the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/) for explanations and examples.
* Check out the [Mermaid docs](https://mermaid-js.github.io/mermaid/#/)
for explanations and examples.
Most important, __Keep Diagrams Simple__. This will save time for you and fellow contributors, and allow for easier reading by new and experienced users.
Most important, __Keep Diagrams Simple__.
This will save time for you and fellow contributors, and allow for easier reading
by new and experienced users.
content/en/docs/contribute/style/hugo-shortcodes/index.md
+59 -24
View File
@@ -12,11 +12,13 @@ Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content
## Feature state
In a Markdown page (`.md` file) on this site, you can add a shortcode to display version and state of the documented feature.
In a Markdown page (`.md` file) on this site, you can add a shortcode to
display version and state of the documented feature.
### Feature state demo
Below is a demo of the feature state snippet, which displays the feature as stable in the latest Kubernetes version.
Below is a demo of the feature state snippet, which displays the feature as
stable in the latest Kubernetes version.
```
{{</* feature-state state="stable" */>}}
@@ -50,16 +52,22 @@ Renders to:
There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`.
You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). When the glossary term is moused-over, the glossary entry displays a tooltip. The glossary term also displays as a link.
You can reference glossary terms with an inclusion that automatically updates
and replaces content with the relevant links from [our glossary](/docs/reference/glossary/).
When the glossary term is moused-over, the glossary entry displays a tooltip.
The glossary term also displays as a link.
As well as inclusions with tooltips, you can reuse the definitions from the glossary in
page content.
The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), with a content file for each glossary term.
The raw data for glossary terms is stored at
[the glossary directory](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary),
with a content file for each glossary term.
### Glossary demo
For example, the following include within the Markdown renders to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
For example, the following include within the Markdown renders to
{{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
```
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
@@ -85,7 +93,9 @@ which renders as:
## Links to API Reference
You can link to a page of the Kubernetes API reference using the `api-reference` shortcode, for example to the {{< api-reference page="workload-resources/pod-v1" >}} reference:
You can link to a page of the Kubernetes API reference using the
`api-reference` shortcode, for example to the
{{< api-reference page="workload-resources/pod-v1" >}} reference:
```
{{</* api-reference page="workload-resources/pod-v1" */>}}
@@ -94,7 +104,10 @@ You can link to a page of the Kubernetes API reference using the `api-reference`
The content of the `page` parameter is the suffix of the URL of the API reference page.
You can link to a specific place into a page by specifying an `anchor` parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}} section of the page:
You can link to a specific place into a page by specifying an `anchor`
parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
section of the page:
```
{{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}}
@@ -102,17 +115,20 @@ You can link to a specific place into a page by specifying an `anchor` parameter
```
You can change the text of the link by specifying a `text` parameter, for example by linking to the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}} section of the page:
You can change the text of the link by specifying a `text` parameter, for
example by linking to the
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}}
section of the page:
```
{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" */>}}
```
## Table captions
You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
You can make tables more accessible to screen readers by adding a table caption. To add a
[caption](https://www.w3schools.com/tags/tag_caption.asp) to a table,
enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
{{< note >}}
Table captions are visible to screen readers but invisible when viewed in standard HTML.
@@ -138,7 +154,8 @@ Parameter | Description | Default
`logLevel` | The log level for log output | `INFO`
{{< /table >}}
If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element:
If you inspect the HTML for the table, you should see this element immediately
after the opening `<table>` element:
```html
<caption style="display: none;">Configuration parameters</caption>
@@ -146,14 +163,25 @@ If you inspect the HTML for the table, you should see this element immediately a
## Tabs
In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution.
In a markdown page (`.md` file) on this site, you can add a tab set to display
multiple flavors of a given solution.
The `tabs` shortcode takes these parameters:
* `name`: The name as shown on the tab.
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the `include`, you do not have any shortcode inner content and must use the self-closing syntax. For example, <code>{{</* tab name="Content File #1" include="example1" /*/>}}</code>. The language needs to be specified under `codelang` or the language is taken based on the file name. Non-content files are code-highlighted by default.
* If your inner content is markdown, you must use the `%`-delimiter to surround the tab. For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo
what code language to use for highlighting.
* `include`: The file to include in the tab. If the tab lives in a Hugo
[leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles),
the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself.
If not, the content page that needs to be included is looked up relative to the current page.
Note that with the `include`, you do not have any shortcode inner content and must use the
self-closing syntax. For example,
`{{</* tab name="Content File #1" include="example1" /*/>}}`. The language needs to be specified
under `codelang` or the language is taken based on the file name.
Non-content files are code-highlighted by default.
* If your inner content is markdown, you must use the `%`-delimiter to surround the tab.
For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
* You can combine the variations mentioned above inside a tab set.
Below is a demo of the tabs shortcode.
@@ -288,13 +316,17 @@ The two most commonly used version parameters are `latest` and `version`.
### `{{</* param "version" */>}}`
The `{{</* param "version" */>}}` shortcode generates the value of the current version of
the Kubernetes documentation from the `version` site parameter. The `param` shortcode accepts the name of one site parameter, in this case: `version`.
The `{{</* param "version" */>}}` shortcode generates the value of the current
version of the Kubernetes documentation from the `version` site parameter. The
`param` shortcode accepts the name of one site parameter, in this case:
`version`.
{{< note >}}
In previously released documentation, `latest` and `version` parameter values are not equivalent.
After a new version is released, `latest` is incremented and the value of `version` for the documentation set remains unchanged. For example, a previously released version of the documentation displays `version` as
`v1.19` and `latest` as `v1.20`.
In previously released documentation, `latest` and `version` parameter values
are not equivalent. After a new version is released, `latest` is incremented
and the value of `version` for the documentation set remains unchanged. For
example, a previously released version of the documentation displays `version`
as `v1.19` and `latest` as `v1.20`.
{{< /note >}}
Renders to:
@@ -313,7 +345,8 @@ Renders to:
### `{{</* latest-semver */>}}`
The `{{</* latest-semver */>}}` shortcode generates the value of `latest` without the "v" prefix.
The `{{</* latest-semver */>}}` shortcode generates the value of `latest`
without the "v" prefix.
Renders to:
@@ -330,8 +363,9 @@ Renders to:
### `{{</* latest-release-notes */>}}`
The `{{</* latest-release-notes */>}}` shortcode generates a version string from `latest` and removes
the "v" prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified version string.
The `{{</* latest-release-notes */>}}` shortcode generates a version string
from `latest` and removes the "v" prefix. The shortcode prints a new URL for
the release note CHANGELOG page with the modified version string.
Renders to:
@@ -344,3 +378,4 @@ Renders to:
* Learn about [page content types](/docs/contribute/style/page-content-types/).
* Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/).
* Learn about [advanced contributing](/docs/contribute/advanced/).
content/en/docs/home/_index.md
+1 -1
View File
@@ -60,7 +60,7 @@ cards:
title: K8s Release Notes
description: If you are installing Kubernetes or upgrading to the newest version, refer to the current release notes.
button: "Download Kubernetes"
button_path: "/docs/setup/release/notes"
button_path: "/releases/download"
- name: about
title: About the documentation
description: This website contains documentation for the current and previous 4 versions of Kubernetes.
content/en/docs/reference/_index.md
+4 -1
View File
@@ -66,6 +66,7 @@ client libraries:
* List of [ports and protocols](/docs/reference/ports-and-protocols/) that
should be open on control plane and worker nodes
## Config APIs
This section hosts the documentation for "unpublished" APIs which are used to
@@ -73,10 +74,12 @@ configure kubernetes components or tools. Most of these APIs are not exposed
by the API server in a RESTful way though they are essential for a user or an
operator to use or manage a cluster.
* [kube-apiserver configuration (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/)
* [kube-apiserver configuration (v1)](/docs/reference/config-api/apiserver-config.v1/)
* [kube-apiserver encryption (v1)](/docs/reference/config-api/apiserver-encryption.v1/)
* [kubelet configuration (v1alpha1)](/docs/reference/config-api/kubelet-config.v1alpha1/) and
[kubelet configuration (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/)
* [kubelet credential providers (v1alpha1)](/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/)
* [kube-scheduler configuration (v1beta2)](/docs/reference/config-api/kube-scheduler-config.v1beta2/) and
[kube-scheduler configuration (v1beta3)](/docs/reference/config-api/kube-scheduler-config.v1beta3/)
* [kube-proxy configuration (v1alpha1)](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
content/en/docs/reference/access-authn-authz/authentication.md
+3 -1
View File
@@ -1144,7 +1144,9 @@ If specified, `clientKeyData` and `clientCertificateData` must both must be pres
{{< /tabs >}}
Optionally, the response can include the expiry of the credential formatted as a
RFC3339 timestamp. Presence or absence of an expiry has the following impact:
[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp.
Presence or absence of an expiry has the following impact:
- If an expiry is included, the bearer token and TLS credentials are cached until
the expiry time is reached, or if the server responds with a 401 HTTP status code,
content/en/docs/reference/access-authn-authz/node.md
+2 -2
View File
@@ -34,8 +34,8 @@ Write operations:
Auth-related operations:
* read/write access to the certificationsigningrequests API for TLS bootstrapping
* the ability to create tokenreviews and subjectaccessreviews for delegated authentication/authorization checks
* read/write access to the [CertificateSigningRequests API](/docs/reference/access-authn-authz/certificate-signing-requests/) for TLS bootstrapping
* the ability to create TokenReviews and SubjectAccessReviews for delegated authentication/authorization checks
In future releases, the node authorizer may add or remove permissions to ensure kubelets
have the minimal set of permissions required to operate correctly.
content/en/docs/reference/access-authn-authz/psp-to-pod-security-standards.md
+275
View File
@@ -0,0 +1,275 @@
---
reviewers:
- tallclair
- liggitt
title: Mapping PodSecurityPolicies to Pod Security Standards
content_type: concept
weight: 95
---
<!-- overview -->
The tables below enumerate the configuration parameters on
[PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) objects, whether the field mutates
and/or validates pods, and how the configuration values map to the
[Pod Security Standards](/docs/concepts/security/pod-security-standards/).
For each applicable parameter, the allowed values for the
[Baseline](/docs/concepts/security/pod-security-standards/#baseline) and
[Restricted](/docs/concepts/security/pod-security-standards/#restricted) profiles are listed.
Anything outside the allowed values for those profiles would fall under the
[Privileged](/docs/concepts/security/pod-security-standards/#priveleged) profile. "No opinion"
means all values are allowed under all Pod Security Standards.
For a step-by-step migration guide, see
[Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](/docs/tasks/configure-pod-container/migrate-from-psp/).
<!-- body -->
## PodSecurityPolicy Spec
The fields enumerated in this table are part of the `PodSecurityPolicySpec`, which is specified
under the `.spec` field path.
<table class="no-word-break">
<caption style="display:none">Mapping PodSecurityPolicySpec fields to Pod Security Standards</caption>
<tbody>
<tr>
<th><code>PodSecurityPolicySpec</code></th>
<th>Type</th>
<th>Pod Security Standards Equivalent</th>
</tr>
<tr>
<td><code>privileged</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: <code>false</code> / undefined / nil</td>
</tr>
<tr>
<td><code>defaultAddCapabilities</code></td>
<td>Mutating & Validating</td>
<td>Requirements match <code>allowedCapabilities</code> below.</td>
</tr>
<tr>
<td><code>allowedCapabilities</code></td>
<td>Validating</td>
<td>
<p><b>Baseline</b>: subset of</p>
<ul>
<li><code>AUDIT_WRITE</code></li>
<li><code>CHOWN</code></li>
<li><code>DAC_OVERRIDE</code></li>
<li><code>FOWNER</code></li>
<li><code>FSETID</code></li>
<li><code>KILL</code></li>
<li><code>MKNOD</code></li>
<li><code>NET_BIND_SERVICE</code></li>
<li><code>SETFCAP</code></li>
<li><code>SETGID</code></li>
<li><code>SETPCAP</code></li>
<li><code>SETUID</code></li>
<li><code>SYS_CHROOT</code></li>
</ul>
<p><b>Restricted</b>: empty / undefined / nil OR a list containing <i>only</i> <code>NET_BIND_SERVICE</code>
</td>
</tr>
<tr>
<td><code>requiredDropCapabilities</code></td>
<td>Mutating & Validating</td>
<td>
<p><b>Baseline</b>: no opinion</p>
<p><b>Restricted</b>: must include <code>ALL</code></p>
</td>
</tr>
<tr>
<td><code>volumes</code></td>
<td>Validating</td>
<td>
<p><b>Baseline</b>: anything except</p>
<ul>
<li><code>hostPath</code></li>
<li><code>*</code></li>
</ul>
<p><b>Restricted</b>: subset of</p>
<ul>
<li><code>configMap</code></li>
<li><code>csi</code></li>
<li><code>downwardAPI</code></li>
<li><code>emptyDir</code></li>
<li><code>ephemeral</code></li>
<li><code>persistentVolumeClaim</code></li>
<li><code>projected</code></li>
<li><code>secret</code></li>
</ul>
</td>
</tr>
<tr>
<td><code>hostNetwork</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: <code>false</code> / undefined / nil</td>
</tr>
<tr>
<td><code>hostPorts</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: undefined / nil / empty</td>
</tr>
<tr>
<td><code>hostPID</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: <code>false</code> / undefined / nil</td>
</tr>
<tr>
<td><code>hostIPC</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: <code>false</code> / undefined / nil</td>
</tr>
<tr>
<td><code>seLinux</code></td>
<td>Mutating & Validating</td>
<td>
<p><b>Baseline & Restricted</b>:
<code>seLinux.rule</code> is <code>MustRunAs</code>, with the following <code>options</code></p>
<ul>
<li><code>user</code> is unset (<code>""</code> / undefined / nil)</li>
<li><code>role</code> is unset (<code>""</code> / undefined / nil)</li>
<li><code>type</code> is unset or one of: <code>container_t, container_init_t, container_kvm_t</code></li>
<li><code>level</code> is anything</li>
</ul>
</td>
</tr>
<tr>
<td><code>runAsUser</code></td>
<td>Mutating & Validating</td>
<td>
<p><b>Baseline</b>: Anything</p>
<p><b>Restricted</b>: <code>rule</code> is <code>MustRunAsNonRoot</code></p>
</td>
</tr>
<tr>
<td><code>runAsGroup</code></td>
<td>Mutating (MustRunAs) & Validating</td>
<td>
<i>No opinion</i>
</td>
</tr>
<tr>
<td><code>supplementalGroups</code></td>
<td>Mutating & Validating</td>
<td>
<i>No opinion</i>
</td>
</tr>
<tr>
<td><code>fsGroup</code></td>
<td>Mutating & Validating</td>
<td>
<i>No opinion</i>
</td>
</tr>
<tr>
<td><code>readOnlyRootFilesystem</code></td>
<td>Mutating & Validating</td>
<td>
<i>No opinion</i>
</td>
</tr>
<tr>
<td><code>defaultAllowPrivilegeEscalation</code></td>
<td>Mutating</td>
<td>
<i>No opinion (non-validating)</i>
</td>
</tr>
<tr>
<td><code>allowPrivilegeEscalation</code></td>
<td>Mutating & Validating</td>
<td>
<p><i>Only mutating if set to <code>false</code></i></p>
<p><b>Baseline</b>: No opinion</p>
<p><b>Restricted</b>: <code>false</code></p>
</td>
</tr>
<tr>
<td><code>allowedHostPaths</code></td>
<td>Validating</td>
<td><i>No opinion (volumes takes precedence)</i></td>
</tr>
<tr>
<td><code>allowedFlexVolumes</code></td>
<td>Validating</td>
<td><i>No opinion (volumes takes precedence)</i></td>
</tr>
<tr>
<td><code>allowedCSIDrivers</code></td>
<td>Validating</td>
<td><i>No opinion (volumes takes precedence)</i></td>
</tr>
<tr>
<td><code>allowedUnsafeSysctls</code></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: undefined / nil / empty</td>
</tr>
<tr>
<td><code>forbiddenSysctls</code></td>
<td>Validating</td>
<td><i>No opinion</i></td>
</tr>
<tr>
<td><code>allowedProcMountTypes</code><br><i>(alpha feature)</i></td>
<td>Validating</td>
<td><b>Baseline & Restricted</b>: <code>["Default"]</code> OR undefined / nil / empty</td>
</tr>
<tr>
<td><code>runtimeClass</code><br><code>&nbsp;.defaultRuntimeClassName</code></td>
<td>Mutating</td>
<td><i>No opinion</i></td>
</tr>
<tr>
<td><code>runtimeClass</code><br><code>&nbsp;.allowedRuntimeClassNames</code></td>
<td>Validating</td>
<td><i>No opinion</i></td>
</tr>
</tbody>
</table>
## PodSecurityPolicy annotations
The [annotations](/docs/concepts/overview/working-with-objects/annotations/) enumerated in this
table can be specified under `.metadata.annotations` on the PodSecurityPolicy object.
<table class="no-word-break">
<caption style="display:none">Mapping PodSecurityPolicy annotations to Pod Security Standards</caption>
<tbody>
<tr>
<th><code>PSP Annotation</code></th>
<th>Type</th>
<th>Pod Security Standards Equivalent</th>
</tr>
<tr>
<td><code>seccomp.security.alpha.kubernetes.io</code><br><code>/defaultProfileName</code></td>
<td>Mutating</td>
<td><i>No opinion</i></td>
</tr>
<tr>
<td><code>seccomp.security.alpha.kubernetes.io</code><br><code>/allowedProfileNames</code></td>
<td>Validating</td>
<td>
<p><b>Baseline</b>: <code>"runtime/default,"</code> <i>(Trailing comma to allow unset)</i></p>
<p><b>Restricted</b>: <code>"runtime/default"</code> <i>(No trailing comma)</i></p>
<p><i><code>localhost/*</code> values are also permitted for both Baseline & Restricted.</i></p>
</td>
</tr>
<tr>
<td><code>apparmor.security.beta.kubernetes.io</code><br><code>/defaultProfileName</code></td>
<td>Mutating</td>
<td><i>No opinion</i></td>
</tr>
<tr>
<td><code>apparmor.security.beta.kubernetes.io</code><br><code>/allowedProfileNames</code></td>
<td>Validating</td>
<td>
<p><b>Baseline</b>: <code>"runtime/default,"</code> <i>(Trailing comma to allow unset)</i></p>
<p><b>Restricted</b>: <code>"runtime/default"</code> <i>(No trailing comma)</i></p>
<p><i><code>localhost/*</code> values are also permitted for both Baseline & Restricted.</i></p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/command-line-tools-reference/feature-gates.md
+8 -7
View File
@@ -25,7 +25,8 @@ on each Kubernetes component.
Each Kubernetes component lets you enable or disable a set of feature gates that
are relevant to that component.
Use `-h` flag to see a full set of feature gates for all components.
To set feature gates for a component, such as kubelet, use the `--feature-gates` flag assigned to a list of feature pairs:
To set feature gates for a component, such as kubelet, use the `--feature-gates`
flag assigned to a list of feature pairs:
```shell
--feature-gates="...,GracefulNodeShutdown=true"
@@ -399,7 +400,7 @@ different Kubernetes components.
| `PodShareProcessNamespace` | `true` | Beta | 1.12 | 1.16 |
| `PodShareProcessNamespace` | `true` | GA | 1.17 | - |
| `RequestManagement` | `false` | Alpha | 1.15 | 1.16 |
| `RequestManagement` | - | Derecated | 1.17 | - |
| `RequestManagement` | - | Deprecated | 1.17 | - |
| `ResourceLimitsPriorityFunction` | `false` | Alpha | 1.9 | 1.18 |
| `ResourceLimitsPriorityFunction` | - | Deprecated | 1.19 | - |
| `ResourceQuotaScopeSelectors` | `false` | Alpha | 1.11 | 1.11 |
@@ -575,7 +576,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
- `AnyVolumeDataSource`: Enable use of any custom resource as the `DataSource` of a
{{< glossary_tooltip text="PVC" term_id="persistent-volume-claim" >}}.
- `AppArmor`: Enable use of AppArmor mandatory access control for Pods running on Linux nodes.
See [AppArmor Tutorial](/docs/tutorials/clusters/apparmor/) for more details.
See [AppArmor Tutorial](/docs/tutorials/security/apparmor/) for more details.
- `AttachVolumeLimit`: Enable volume plugins to report limits on number of volumes
that can be attached to a node.
See [dynamic volume limits](/docs/concepts/storage/storage-limits/#dynamic-volume-limits) for more details.
@@ -769,12 +770,12 @@ Each feature gate is designed for enabling/disabling a specific feature:
- `EnableEquivalenceClassCache`: Enable the scheduler to cache equivalence of
nodes when scheduling Pods.
- `EndpointSlice`: Enables EndpointSlices for more scalable and extensible
network endpoints. See [Enabling EndpointSlices](/docs/tasks/administer-cluster/enabling-endpointslices/).
network endpoints. See [Enabling EndpointSlices](/docs/concepts/services-networking/endpoint-slices/).
- `EndpointSliceNodeName`: Enables EndpointSlice `nodeName` field.
- `EndpointSliceProxying`: When enabled, kube-proxy running
on Linux will use EndpointSlices as the primary data source instead of
Endpoints, enabling scalability and performance improvements. See
[Enabling Endpoint Slices](/docs/tasks/administer-cluster/enabling-endpointslices/).
[Enabling Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/).
- `EndpointSliceTerminatingCondition`: Enables EndpointSlice `terminating` and `serving`
condition fields.
- `EphemeralContainers`: Enable the ability to add
@@ -814,7 +815,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
and gracefully terminate pods running on the node. See
[Graceful Node Shutdown](/docs/concepts/architecture/nodes/#graceful-node-shutdown)
for more details.
= `GracefulNodeShutdownBasedOnPodPriority`: Enables the kubelet to check Pod priorities
- `GracefulNodeShutdownBasedOnPodPriority`: Enables the kubelet to check Pod priorities
when shutting down a node gracefully.
- `GRPCContainerProbe`: Enables the gRPC probe method for {Liveness,Readiness,Startup}Probe. See [Configure Liveness, Readiness and Startup Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-grpc-liveness-probe).
- `HonorPVReclaimPolicy`: Honor persistent volume reclaim policy when it is `Delete` irrespective of PV-PVC deletion ordering.
@@ -1089,7 +1090,7 @@ Each feature gate is designed for enabling/disabling a specific feature:
- `WindowsEndpointSliceProxying`: When enabled, kube-proxy running on Windows
will use EndpointSlices as the primary data source instead of Endpoints,
enabling scalability and performance improvements. See
[Enabling Endpoint Slices](/docs/tasks/administer-cluster/enabling-endpointslices/).
[Enabling Endpoint Slices](/docs/concepts/services-networking/endpoint-slices/).
- `WindowsGMSA`: Enables passing of GMSA credential specs from pods to container runtimes.
- `WindowsHostProcessContainers`: Enables support for Windows HostProcess containers.
- `WindowsRunAsUserName` : Enable support for running applications in Windows containers
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
+1 -1
View File
@@ -946,7 +946,7 @@ kube-apiserver [flags]
<td colspan="2">--service-account-key-file strings</td>
</tr>
<tr>
<td></td><td style="line-height: 130%; word-wrap: break-word;"><p>File containing PEM-encoded x509 RSA or ECDSA private or public keys, used to verify ServiceAccount tokens. The specified file can contain multiple keys, and the flag can be specified multiple times with different files. If unspecified, --tls-private-key-file is used. Must be specified when --service-account-signing-key is provided</p></td>
<td></td><td style="line-height: 130%; word-wrap: break-word;"><p>File containing PEM-encoded x509 RSA or ECDSA private or public keys, used to verify ServiceAccount tokens. The specified file can contain multiple keys, and the flag can be specified multiple times with different files. If unspecified, --tls-private-key-file is used. Must be specified when --service-account-signing-key-file is provided</p></td>
</tr>
<tr>
content/en/docs/reference/config-api/apiserver-audit.v1.md
+145 -218
View File
@@ -19,13 +19,13 @@ auto_generated: true
## `Event` {#audit-k8s-io-v1-Event}
**Appears in:**
- [EventList](#audit-k8s-io-v1-EventList)
Event captures all the information that can be included in an API audit log.
<p>Event captures all the information that can be included in an API audit log.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -35,151 +35,133 @@ Event captures all the information that can be included in an API audit log.
<tr><td><code>kind</code><br/>string</td><td><code>Event</code></td></tr>
<tr><td><code>level</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-Level"><code>Level</code></a>
</td>
<td>
AuditLevel at which event was generated</td>
<p>AuditLevel at which event was generated</p>
</td>
</tr>
<tr><td><code>auditID</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
</td>
<td>
Unique audit ID, generated for each request.</td>
<p>Unique audit ID, generated for each request.</p>
</td>
</tr>
<tr><td><code>stage</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-Stage"><code>Stage</code></a>
</td>
<td>
Stage of the request handling when this event instance was generated.</td>
<p>Stage of the request handling when this event instance was generated.</p>
</td>
</tr>
<tr><td><code>requestURI</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
RequestURI is the request URI as sent by the client to a server.</td>
<p>RequestURI is the request URI as sent by the client to a server.</p>
</td>
</tr>
<tr><td><code>verb</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Verb is the kubernetes verb associated with the request.
For non-resource requests, this is the lower-cased HTTP method.</td>
<p>Verb is the kubernetes verb associated with the request.
For non-resource requests, this is the lower-cased HTTP method.</p>
</td>
</tr>
<tr><td><code>user</code> <B>[Required]</B><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#userinfo-v1-authentication"><code>authentication/v1.UserInfo</code></a>
</td>
<td>
Authenticated user information.</td>
<p>Authenticated user information.</p>
</td>
</tr>
<tr><td><code>impersonatedUser</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#userinfo-v1-authentication"><code>authentication/v1.UserInfo</code></a>
</td>
<td>
Impersonated user information.</td>
<p>Impersonated user information.</p>
</td>
</tr>
<tr><td><code>sourceIPs</code><br/>
<code>[]string</code>
</td>
<td>
Source IPs, from where the request originated and intermediate proxies.</td>
<p>Source IPs, from where the request originated and intermediate proxies.</p>
</td>
</tr>
<tr><td><code>userAgent</code><br/>
<code>string</code>
</td>
<td>
UserAgent records the user agent string reported by the client.
Note that the UserAgent is provided by the client, and must not be trusted.</td>
<p>UserAgent records the user agent string reported by the client.
Note that the UserAgent is provided by the client, and must not be trusted.</p>
</td>
</tr>
<tr><td><code>objectRef</code><br/>
<a href="#audit-k8s-io-v1-ObjectReference"><code>ObjectReference</code></a>
</td>
<td>
Object reference this request is targeted at.
Does not apply for List-type requests, or non-resource requests.</td>
<p>Object reference this request is targeted at.
Does not apply for List-type requests, or non-resource requests.</p>
</td>
</tr>
<tr><td><code>responseStatus</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#status-v1-meta"><code>meta/v1.Status</code></a>
</td>
<td>
The response status, populated even when the ResponseObject is not a Status type.
<p>The response status, populated even when the ResponseObject is not a Status type.
For successful responses, this will only include the Code and StatusSuccess.
For non-status type error responses, this will be auto-populated with the error Message.</td>
For non-status type error responses, this will be auto-populated with the error Message.</p>
</td>
</tr>
<tr><td><code>requestObject</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
</td>
<td>
API object from the request, in JSON format. The RequestObject is recorded as-is in the request
<p>API object from the request, in JSON format. The RequestObject is recorded as-is in the request
(possibly re-encoded as JSON), prior to version conversion, defaulting, admission or
merging. It is an external versioned object type, and may not be a valid object on its own.
Omitted for non-resource requests. Only logged at Request Level and higher.</td>
Omitted for non-resource requests. Only logged at Request Level and higher.</p>
</td>
</tr>
<tr><td><code>responseObject</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
</td>
<td>
API object returned in the response, in JSON. The ResponseObject is recorded after conversion
<p>API object returned in the response, in JSON. The ResponseObject is recorded after conversion
to the external type, and serialized as JSON. Omitted for non-resource requests. Only logged
at Response Level.</td>
at Response Level.</p>
</td>
</tr>
<tr><td><code>requestReceivedTimestamp</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#microtime-v1-meta"><code>meta/v1.MicroTime</code></a>
</td>
<td>
Time the request reached the apiserver.</td>
<p>Time the request reached the apiserver.</p>
</td>
</tr>
<tr><td><code>stageTimestamp</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#microtime-v1-meta"><code>meta/v1.MicroTime</code></a>
</td>
<td>
Time the request reached current audit stage.</td>
<p>Time the request reached current audit stage.</p>
</td>
</tr>
<tr><td><code>annotations</code><br/>
<code>map[string]string</code>
</td>
<td>
Annotations is an unstructured key value map stored with an audit event that may be set by
<p>Annotations is an unstructured key value map stored with an audit event that may be set by
plugins invoked in the request serving chain, including authentication, authorization and
admission plugins. Note that these annotations are for the audit event, and do not correspond
to the metadata.annotations of the submitted object. Keys should uniquely identify the informing
component to avoid name collisions (e.g. podsecuritypolicy.admission.k8s.io/policy). Values
should be short. Annotations are included in the Metadata level.</td>
should be short. Annotations are included in the Metadata level.</p>
</td>
</tr>
</tbody>
</table>
@@ -187,10 +169,9 @@ should be short. Annotations are included in the Metadata level.</td>
<p>EventList is a list of audit Events.</p>
EventList is a list of audit Events.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
@@ -199,40 +180,32 @@ EventList is a list of audit Events.
<tr><td><code>kind</code><br/>string</td><td><code>EventList</code></td></tr>
<tr><td><code>metadata</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#listmeta-v1-meta"><code>meta/v1.ListMeta</code></a>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>items</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-Event"><code>[]Event</code></a>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
</tbody>
</table>
## `Policy` {#audit-k8s-io-v1-Policy}
**Appears in:**
- [PolicyList](#audit-k8s-io-v1-PolicyList)
Policy defines the configuration of audit logging, and the rules for how different request
categories are logged.
<p>Policy defines the configuration of audit logging, and the rules for how different request
categories are logged.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -242,49 +215,43 @@ categories are logged.
<tr><td><code>kind</code><br/>string</td><td><code>Policy</code></td></tr>
<tr><td><code>metadata</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#objectmeta-v1-meta"><code>meta/v1.ObjectMeta</code></a>
</td>
<td>
ObjectMeta is included for interoperability with API infrastructure.Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.</td>
<p>ObjectMeta is included for interoperability with API infrastructure.</p>
Refer to the Kubernetes API documentation for the fields of the <code>metadata</code> field.</td>
</tr>
<tr><td><code>rules</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-PolicyRule"><code>[]PolicyRule</code></a>
</td>
<td>
Rules specify the audit Level a request should be recorded at.
<p>Rules specify the audit Level a request should be recorded at.
A request may match multiple rules, in which case the FIRST matching rule is used.
The default audit level is None, but can be overridden by a catch-all rule at the end of the list.
PolicyRules are strictly ordered.</td>
PolicyRules are strictly ordered.</p>
</td>
</tr>
<tr><td><code>omitStages</code><br/>
<a href="#audit-k8s-io-v1-Stage"><code>[]Stage</code></a>
</td>
<td>
OmitStages is a list of stages for which no events are created. Note that this can also
be specified per rule in which case the union of both are omitted.</td>
<p>OmitStages is a list of stages for which no events are created. Note that this can also
be specified per rule in which case the union of both are omitted.</p>
</td>
</tr>
<tr><td><code>omitManagedFields</code><br/>
<code>bool</code>
</td>
<td>
OmitManagedFields indicates whether to omit the managed fields of the request
<p>OmitManagedFields indicates whether to omit the managed fields of the request
and response bodies from being written to the API audit log.
This is used as a global default - a value of 'true' will omit the managed fileds,
otherwise the managed fields will be included in the API audit log.
Note that this can also be specified per rule in which case the value specified
in a rule will override the global default.</td>
in a rule will override the global default.</p>
</td>
</tr>
</tbody>
</table>
@@ -292,10 +259,9 @@ in a rule will override the global default.</td>
<p>PolicyList is a list of audit Policies.</p>
PolicyList is a list of audit Policies.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
@@ -304,85 +270,70 @@ PolicyList is a list of audit Policies.
<tr><td><code>kind</code><br/>string</td><td><code>PolicyList</code></td></tr>
<tr><td><code>metadata</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#listmeta-v1-meta"><code>meta/v1.ListMeta</code></a>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>items</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-Policy"><code>[]Policy</code></a>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
</tbody>
</table>
## `GroupResources` {#audit-k8s-io-v1-GroupResources}
**Appears in:**
- [PolicyRule](#audit-k8s-io-v1-PolicyRule)
GroupResources represents resource kinds in an API group.
<p>GroupResources represents resource kinds in an API group.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>group</code><br/>
<code>string</code>
</td>
<td>
Group is the name of the API group that contains the resources.
The empty string represents the core API group.</td>
<p>Group is the name of the API group that contains the resources.
The empty string represents the core API group.</p>
</td>
</tr>
<tr><td><code>resources</code><br/>
<code>[]string</code>
</td>
<td>
Resources is a list of resources this rule applies to.
For example:
<p>Resources is a list of resources this rule applies to.</p>
<p>For example:
'pods' matches pods.
'pods/log' matches the log subresource of pods.
'&lowast;' matches all resources and their subresources.
'pods/&lowast;' matches all subresources of pods.
'&lowast;/scale' matches all scale subresources.
If wildcard is present, the validation rule will ensure resources do not
overlap with each other.
An empty list implies all resources and subresources in this API groups apply.</td>
'<em>' matches all resources and their subresources.
'pods/</em>' matches all subresources of pods.
'*/scale' matches all scale subresources.</p>
<p>If wildcard is present, the validation rule will ensure resources do not
overlap with each other.</p>
<p>An empty list implies all resources and subresources in this API groups apply.</p>
</td>
</tr>
<tr><td><code>resourceNames</code><br/>
<code>[]string</code>
</td>
<td>
ResourceNames is a list of resource instance names that the policy matches.
<p>ResourceNames is a list of resource instance names that the policy matches.
Using this field requires Resources to be specified.
An empty list implies that every instance of the resource is matched.</td>
An empty list implies that every instance of the resource is matched.</p>
</td>
</tr>
</tbody>
</table>
@@ -390,216 +341,189 @@ An empty list implies that every instance of the resource is matched.</td>
(Alias of `string`)
**Appears in:**
- [Event](#audit-k8s-io-v1-Event)
- [PolicyRule](#audit-k8s-io-v1-PolicyRule)
Level defines the amount of information logged during auditing
<p>Level defines the amount of information logged during auditing</p>
## `ObjectReference` {#audit-k8s-io-v1-ObjectReference}
**Appears in:**
- [Event](#audit-k8s-io-v1-Event)
ObjectReference contains enough information to let you inspect or modify the referred object.
<p>ObjectReference contains enough information to let you inspect or modify the referred object.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>resource</code><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>namespace</code><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>name</code><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>uid</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/types#UID"><code>k8s.io/apimachinery/pkg/types.UID</code></a>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>apiGroup</code><br/>
<code>string</code>
</td>
<td>
APIGroup is the name of the API group that contains the referred object.
The empty string represents the core API group.</td>
<p>APIGroup is the name of the API group that contains the referred object.
The empty string represents the core API group.</p>
</td>
</tr>
<tr><td><code>apiVersion</code><br/>
<code>string</code>
</td>
<td>
APIVersion is the version of the API group that contains the referred object.</td>
<p>APIVersion is the version of the API group that contains the referred object.</p>
</td>
</tr>
<tr><td><code>resourceVersion</code><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>subresource</code><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
</tbody>
</table>
## `PolicyRule` {#audit-k8s-io-v1-PolicyRule}
**Appears in:**
- [Policy](#audit-k8s-io-v1-Policy)
PolicyRule maps requests based off metadata to an audit Level.
Requests must match the rules of every field (an intersection of rules).
<p>PolicyRule maps requests based off metadata to an audit Level.
Requests must match the rules of every field (an intersection of rules).</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>level</code> <B>[Required]</B><br/>
<a href="#audit-k8s-io-v1-Level"><code>Level</code></a>
</td>
<td>
The Level that requests matching this rule are recorded at.</td>
<p>The Level that requests matching this rule are recorded at.</p>
</td>
</tr>
<tr><td><code>users</code><br/>
<code>[]string</code>
</td>
<td>
The users (by authenticated user name) this rule applies to.
An empty list implies every user.</td>
<p>The users (by authenticated user name) this rule applies to.
An empty list implies every user.</p>
</td>
</tr>
<tr><td><code>userGroups</code><br/>
<code>[]string</code>
</td>
<td>
The user groups this rule applies to. A user is considered matching
<p>The user groups this rule applies to. A user is considered matching
if it is a member of any of the UserGroups.
An empty list implies every user group.</td>
An empty list implies every user group.</p>
</td>
</tr>
<tr><td><code>verbs</code><br/>
<code>[]string</code>
</td>
<td>
The verbs that match this rule.
An empty list implies every verb.</td>
<p>The verbs that match this rule.
An empty list implies every verb.</p>
</td>
</tr>
<tr><td><code>resources</code><br/>
<a href="#audit-k8s-io-v1-GroupResources"><code>[]GroupResources</code></a>
</td>
<td>
Resources that this rule matches. An empty list implies all kinds in all API groups.</td>
<p>Resources that this rule matches. An empty list implies all kinds in all API groups.</p>
</td>
</tr>
<tr><td><code>namespaces</code><br/>
<code>[]string</code>
</td>
<td>
Namespaces that this rule matches.
The empty string "" matches non-namespaced resources.
An empty list implies every namespace.</td>
<p>Namespaces that this rule matches.
The empty string &quot;&quot; matches non-namespaced resources.
An empty list implies every namespace.</p>
</td>
</tr>
<tr><td><code>nonResourceURLs</code><br/>
<code>[]string</code>
</td>
<td>
NonResourceURLs is a set of URL paths that should be audited.
&lowast;s are allowed, but only as the full, final step in the path.
<p>NonResourceURLs is a set of URL paths that should be audited.
<em>s are allowed, but only as the full, final step in the path.
Examples:
"/metrics" - Log requests for apiserver metrics
"/healthz&lowast;" - Log all health checks</td>
&quot;/metrics&quot; - Log requests for apiserver metrics
&quot;/healthz</em>&quot; - Log all health checks</p>
</td>
</tr>
<tr><td><code>omitStages</code><br/>
<a href="#audit-k8s-io-v1-Stage"><code>[]Stage</code></a>
</td>
<td>
OmitStages is a list of stages for which no events are created. Note that this can also
<p>OmitStages is a list of stages for which no events are created. Note that this can also
be specified policy wide in which case the union of both are omitted.
An empty list means no restrictions will apply.</td>
An empty list means no restrictions will apply.</p>
</td>
</tr>
<tr><td><code>omitManagedFields</code><br/>
<code>bool</code>
</td>
<td>
OmitManagedFields indicates whether to omit the managed fields of the request
and response bodies from being written to the API audit log.
- a value of 'true' will drop the managed fields from the API audit log
- a value of 'false' indicates that the managed fileds should be included
<p>OmitManagedFields indicates whether to omit the managed fields of the request
and response bodies from being written to the API audit log.</p>
<ul>
<li>a value of 'true' will drop the managed fields from the API audit log</li>
<li>a value of 'false' indicates that the managed fileds should be included
in the API audit log
Note that the value, if specified, in this rule will override the global default
If a value is not specified then the global default specified in
Policy.OmitManagedFields will stand.</td>
Policy.OmitManagedFields will stand.</li>
</ul>
</td>
</tr>
</tbody>
</table>
@@ -607,14 +531,17 @@ Policy.OmitManagedFields will stand.</td>
(Alias of `string`)
**Appears in:**
- [Event](#audit-k8s-io-v1-Event)
- [Policy](#audit-k8s-io-v1-Policy)
- [PolicyRule](#audit-k8s-io-v1-PolicyRule)
Stage defines the stages in request handling that audit events may be generated.
<p>Stage defines the stages in request handling that audit events may be generated.</p>
content/en/docs/reference/config-api/apiserver-config.v1.md
+18 -25
View File
@@ -4,7 +4,8 @@ content_type: tool-reference
package: apiserver.config.k8s.io/v1
auto_generated: true
---
Package v1 is the v1 version of the API.
<p>Package v1 is the v1 version of the API.</p>
## Resource Types
@@ -17,10 +18,9 @@ Package v1 is the v1 version of the API.
<p>AdmissionConfiguration provides versioned configuration for admission controllers.</p>
AdmissionConfiguration provides versioned configuration for admission controllers.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
@@ -29,63 +29,56 @@ AdmissionConfiguration provides versioned configuration for admission controller
<tr><td><code>kind</code><br/>string</td><td><code>AdmissionConfiguration</code></td></tr>
<tr><td><code>plugins</code><br/>
<a href="#apiserver-config-k8s-io-v1-AdmissionPluginConfiguration"><code>[]AdmissionPluginConfiguration</code></a>
</td>
<td>
Plugins allows specifying a configuration per admission control plugin.</td>
<p>Plugins allows specifying a configuration per admission control plugin.</p>
</td>
</tr>
</tbody>
</table>
## `AdmissionPluginConfiguration` {#apiserver-config-k8s-io-v1-AdmissionPluginConfiguration}
**Appears in:**
- [AdmissionConfiguration](#apiserver-config-k8s-io-v1-AdmissionConfiguration)
AdmissionPluginConfiguration provides the configuration for a single plug-in.
<p>AdmissionPluginConfiguration provides the configuration for a single plug-in.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Name is the name of the admission controller.
It must match the registered admission plugin name.</td>
<p>Name is the name of the admission controller.
It must match the registered admission plugin name.</p>
</td>
</tr>
<tr><td><code>path</code><br/>
<code>string</code>
</td>
<td>
Path is the path to a configuration file that contains the plugin's
configuration</td>
<p>Path is the path to a configuration file that contains the plugin's
configuration</p>
</td>
</tr>
<tr><td><code>configuration</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
</td>
<td>
Configuration is an embedded configuration object to be used as the plugin's
configuration. If present, it will be used instead of the path to the configuration file.</td>
<p>Configuration is an embedded configuration object to be used as the plugin's
configuration. If present, it will be used instead of the path to the configuration file.</p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/config-api/apiserver-config.v1alpha1.md
+375
View File
@@ -0,0 +1,375 @@
---
title: kube-apiserver Configuration (v1alpha1)
content_type: tool-reference
package: apiserver.k8s.io/v1alpha1
auto_generated: true
---
<p>Package v1alpha1 is the v1alpha1 version of the API.</p>
## Resource Types
- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration)
- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration)
- [TracingConfiguration](#apiserver-k8s-io-v1alpha1-TracingConfiguration)
## `AdmissionConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionConfiguration}
<p>AdmissionConfiguration provides versioned configuration for admission controllers.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>apiserver.k8s.io/v1alpha1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>AdmissionConfiguration</code></td></tr>
<tr><td><code>plugins</code><br/>
<a href="#apiserver-k8s-io-v1alpha1-AdmissionPluginConfiguration"><code>[]AdmissionPluginConfiguration</code></a>
</td>
<td>
<p>Plugins allows specifying a configuration per admission control plugin.</p>
</td>
</tr>
</tbody>
</table>
## `EgressSelectorConfiguration` {#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration}
<p>EgressSelectorConfiguration provides versioned configuration for egress selector clients.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>apiserver.k8s.io/v1alpha1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>EgressSelectorConfiguration</code></td></tr>
<tr><td><code>egressSelections</code> <B>[Required]</B><br/>
<a href="#apiserver-k8s-io-v1alpha1-EgressSelection"><code>[]EgressSelection</code></a>
</td>
<td>
<p>connectionServices contains a list of egress selection client configurations</p>
</td>
</tr>
</tbody>
</table>
## `TracingConfiguration` {#apiserver-k8s-io-v1alpha1-TracingConfiguration}
<p>TracingConfiguration provides versioned configuration for tracing clients.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>apiserver.k8s.io/v1alpha1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>TracingConfiguration</code></td></tr>
<tr><td><code>endpoint</code><br/>
<code>string</code>
</td>
<td>
<p>Endpoint of the collector that's running on the control-plane node.
The APIServer uses the egressType ControlPlane when sending data to the collector.
The syntax is defined in https://github.com/grpc/grpc/blob/master/doc/naming.md.
Defaults to the otlpgrpc default, localhost:4317
The connection is insecure, and does not support TLS.</p>
</td>
</tr>
<tr><td><code>samplingRatePerMillion</code><br/>
<code>int32</code>
</td>
<td>
<p>SamplingRatePerMillion is the number of samples to collect per million spans.
Defaults to 0.</p>
</td>
</tr>
</tbody>
</table>
## `AdmissionPluginConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionPluginConfiguration}
**Appears in:**
- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration)
<p>AdmissionPluginConfiguration provides the configuration for a single plug-in.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>Name is the name of the admission controller.
It must match the registered admission plugin name.</p>
</td>
</tr>
<tr><td><code>path</code><br/>
<code>string</code>
</td>
<td>
<p>Path is the path to a configuration file that contains the plugin's
configuration</p>
</td>
</tr>
<tr><td><code>configuration</code><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime#Unknown"><code>k8s.io/apimachinery/pkg/runtime.Unknown</code></a>
</td>
<td>
<p>Configuration is an embedded configuration object to be used as the plugin's
configuration. If present, it will be used instead of the path to the configuration file.</p>
</td>
</tr>
</tbody>
</table>
## `Connection` {#apiserver-k8s-io-v1alpha1-Connection}
**Appears in:**
- [EgressSelection](#apiserver-k8s-io-v1alpha1-EgressSelection)
<p>Connection provides the configuration for a single egress selection client.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>proxyProtocol</code> <B>[Required]</B><br/>
<a href="#apiserver-k8s-io-v1alpha1-ProtocolType"><code>ProtocolType</code></a>
</td>
<td>
<p>Protocol is the protocol used to connect from client to the konnectivity server.</p>
</td>
</tr>
<tr><td><code>transport</code><br/>
<a href="#apiserver-k8s-io-v1alpha1-Transport"><code>Transport</code></a>
</td>
<td>
<p>Transport defines the transport configurations we use to dial to the konnectivity server.
This is required if ProxyProtocol is HTTPConnect or GRPC.</p>
</td>
</tr>
</tbody>
</table>
## `EgressSelection` {#apiserver-k8s-io-v1alpha1-EgressSelection}
**Appears in:**
- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration)
<p>EgressSelection provides the configuration for a single egress selection client.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>name is the name of the egress selection.
Currently supported values are &quot;controlplane&quot;, &quot;master&quot;, &quot;etcd&quot; and &quot;cluster&quot;
The &quot;master&quot; egress selector is deprecated in favor of &quot;controlplane&quot;</p>
</td>
</tr>
<tr><td><code>connection</code> <B>[Required]</B><br/>
<a href="#apiserver-k8s-io-v1alpha1-Connection"><code>Connection</code></a>
</td>
<td>
<p>connection is the exact information used to configure the egress selection</p>
</td>
</tr>
</tbody>
</table>
## `ProtocolType` {#apiserver-k8s-io-v1alpha1-ProtocolType}
(Alias of `string`)
**Appears in:**
- [Connection](#apiserver-k8s-io-v1alpha1-Connection)
<p>ProtocolType is a set of valid values for Connection.ProtocolType</p>
## `TCPTransport` {#apiserver-k8s-io-v1alpha1-TCPTransport}
**Appears in:**
- [Transport](#apiserver-k8s-io-v1alpha1-Transport)
<p>TCPTransport provides the information to connect to konnectivity server via TCP</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>url</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>URL is the location of the konnectivity server to connect to.
As an example it might be &quot;https://127.0.0.1:8131&quot;</p>
</td>
</tr>
<tr><td><code>tlsConfig</code><br/>
<a href="#apiserver-k8s-io-v1alpha1-TLSConfig"><code>TLSConfig</code></a>
</td>
<td>
<p>TLSConfig is the config needed to use TLS when connecting to konnectivity server</p>
</td>
</tr>
</tbody>
</table>
## `TLSConfig` {#apiserver-k8s-io-v1alpha1-TLSConfig}
**Appears in:**
- [TCPTransport](#apiserver-k8s-io-v1alpha1-TCPTransport)
<p>TLSConfig provides the authentication information to connect to konnectivity server
Only used with TCPTransport</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>caBundle</code><br/>
<code>string</code>
</td>
<td>
<p>caBundle is the file location of the CA to be used to determine trust with the konnectivity server.
Must be absent/empty if TCPTransport.URL is prefixed with http://
If absent while TCPTransport.URL is prefixed with https://, default to system trust roots.</p>
</td>
</tr>
<tr><td><code>clientKey</code><br/>
<code>string</code>
</td>
<td>
<p>clientKey is the file location of the client key to be used in mtls handshakes with the konnectivity server.
Must be absent/empty if TCPTransport.URL is prefixed with http://
Must be configured if TCPTransport.URL is prefixed with https://</p>
</td>
</tr>
<tr><td><code>clientCert</code><br/>
<code>string</code>
</td>
<td>
<p>clientCert is the file location of the client certificate to be used in mtls handshakes with the konnectivity server.
Must be absent/empty if TCPTransport.URL is prefixed with http://
Must be configured if TCPTransport.URL is prefixed with https://</p>
</td>
</tr>
</tbody>
</table>
## `Transport` {#apiserver-k8s-io-v1alpha1-Transport}
**Appears in:**
- [Connection](#apiserver-k8s-io-v1alpha1-Connection)
<p>Transport defines the transport configurations we use to dial to the konnectivity server</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>tcp</code><br/>
<a href="#apiserver-k8s-io-v1alpha1-TCPTransport"><code>TCPTransport</code></a>
</td>
<td>
<p>TCP is the TCP configuration for communicating with the konnectivity server via TCP
ProxyProtocol of GRPC is not supported with TCP transport at the moment
Requires at least one of TCP or UDS to be set</p>
</td>
</tr>
<tr><td><code>uds</code><br/>
<a href="#apiserver-k8s-io-v1alpha1-UDSTransport"><code>UDSTransport</code></a>
</td>
<td>
<p>UDS is the UDS configuration for communicating with the konnectivity server via UDS
Requires at least one of TCP or UDS to be set</p>
</td>
</tr>
</tbody>
</table>
## `UDSTransport` {#apiserver-k8s-io-v1alpha1-UDSTransport}
**Appears in:**
- [Transport](#apiserver-k8s-io-v1alpha1-Transport)
<p>UDSTransport provides the information to connect to konnectivity server via UDS</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>udsName</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>UDSName is the name of the unix domain socket to connect to konnectivity server
This does not use a unix:// prefix. (Eg: /etc/srv/kubernetes/konnectivity-server/konnectivity-server.socket)</p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/config-api/apiserver-encryption.v1.md
+279
View File
@@ -0,0 +1,279 @@
---
title: kube-apiserver Encryption Configuration (v1)
content_type: tool-reference
package: apiserver.config.k8s.io/v1
auto_generated: true
---
<p>Package v1 is the v1 version of the API.</p>
## Resource Types
- [EncryptionConfiguration](#apiserver-config-k8s-io-v1-EncryptionConfiguration)
## `EncryptionConfiguration` {#apiserver-config-k8s-io-v1-EncryptionConfiguration}
<p>EncryptionConfiguration stores the complete configuration for encryption providers.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>apiserver.config.k8s.io/v1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>EncryptionConfiguration</code></td></tr>
<tr><td><code>resources</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-ResourceConfiguration"><code>[]ResourceConfiguration</code></a>
</td>
<td>
<p>resources is a list containing resources, and their corresponding encryption providers.</p>
</td>
</tr>
</tbody>
</table>
## `AESConfiguration` {#apiserver-config-k8s-io-v1-AESConfiguration}
**Appears in:**
- [ProviderConfiguration](#apiserver-config-k8s-io-v1-ProviderConfiguration)
<p>AESConfiguration contains the API configuration for an AES transformer.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>keys</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-Key"><code>[]Key</code></a>
</td>
<td>
<p>keys is a list of keys to be used for creating the AES transformer.
Each key has to be 32 bytes long for AES-CBC and 16, 24 or 32 bytes for AES-GCM.</p>
</td>
</tr>
</tbody>
</table>
## `IdentityConfiguration` {#apiserver-config-k8s-io-v1-IdentityConfiguration}
**Appears in:**
- [ProviderConfiguration](#apiserver-config-k8s-io-v1-ProviderConfiguration)
<p>IdentityConfiguration is an empty struct to allow identity transformer in provider configuration.</p>
## `KMSConfiguration` {#apiserver-config-k8s-io-v1-KMSConfiguration}
**Appears in:**
- [ProviderConfiguration](#apiserver-config-k8s-io-v1-ProviderConfiguration)
<p>KMSConfiguration contains the name, cache size and path to configuration file for a KMS based envelope transformer.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>name is the name of the KMS plugin to be used.</p>
</td>
</tr>
<tr><td><code>cachesize</code><br/>
<code>int32</code>
</td>
<td>
<p>cachesize is the maximum number of secrets which are cached in memory. The default value is 1000.
Set to a negative value to disable caching.</p>
</td>
</tr>
<tr><td><code>endpoint</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>endpoint is the gRPC server listening address, for example &quot;unix:///var/run/kms-provider.sock&quot;.</p>
</td>
</tr>
<tr><td><code>timeout</code><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
<p>timeout for gRPC calls to kms-plugin (ex. 5s). The default is 3 seconds.</p>
</td>
</tr>
</tbody>
</table>
## `Key` {#apiserver-config-k8s-io-v1-Key}
**Appears in:**
- [AESConfiguration](#apiserver-config-k8s-io-v1-AESConfiguration)
- [SecretboxConfiguration](#apiserver-config-k8s-io-v1-SecretboxConfiguration)
<p>Key contains name and secret of the provided key for a transformer.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>name is the name of the key to be used while storing data to disk.</p>
</td>
</tr>
<tr><td><code>secret</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>secret is the actual key, encoded in base64.</p>
</td>
</tr>
</tbody>
</table>
## `ProviderConfiguration` {#apiserver-config-k8s-io-v1-ProviderConfiguration}
**Appears in:**
- [ResourceConfiguration](#apiserver-config-k8s-io-v1-ResourceConfiguration)
<p>ProviderConfiguration stores the provided configuration for an encryption provider.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>aesgcm</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-AESConfiguration"><code>AESConfiguration</code></a>
</td>
<td>
<p>aesgcm is the configuration for the AES-GCM transformer.</p>
</td>
</tr>
<tr><td><code>aescbc</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-AESConfiguration"><code>AESConfiguration</code></a>
</td>
<td>
<p>aescbc is the configuration for the AES-CBC transformer.</p>
</td>
</tr>
<tr><td><code>secretbox</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-SecretboxConfiguration"><code>SecretboxConfiguration</code></a>
</td>
<td>
<p>secretbox is the configuration for the Secretbox based transformer.</p>
</td>
</tr>
<tr><td><code>identity</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-IdentityConfiguration"><code>IdentityConfiguration</code></a>
</td>
<td>
<p>identity is the (empty) configuration for the identity transformer.</p>
</td>
</tr>
<tr><td><code>kms</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-KMSConfiguration"><code>KMSConfiguration</code></a>
</td>
<td>
<p>kms contains the name, cache size and path to configuration file for a KMS based envelope transformer.</p>
</td>
</tr>
</tbody>
</table>
## `ResourceConfiguration` {#apiserver-config-k8s-io-v1-ResourceConfiguration}
**Appears in:**
- [EncryptionConfiguration](#apiserver-config-k8s-io-v1-EncryptionConfiguration)
<p>ResourceConfiguration stores per resource configuration.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>resources</code> <B>[Required]</B><br/>
<code>[]string</code>
</td>
<td>
<p>resources is a list of kubernetes resources which have to be encrypted.</p>
</td>
</tr>
<tr><td><code>providers</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-ProviderConfiguration"><code>[]ProviderConfiguration</code></a>
</td>
<td>
<p>providers is a list of transformers to be used for reading and writing the resources to disk.
eg: aesgcm, aescbc, secretbox, identity.</p>
</td>
</tr>
</tbody>
</table>
## `SecretboxConfiguration` {#apiserver-config-k8s-io-v1-SecretboxConfiguration}
**Appears in:**
- [ProviderConfiguration](#apiserver-config-k8s-io-v1-ProviderConfiguration)
<p>SecretboxConfiguration contains the API configuration for an Secretbox transformer.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>keys</code> <B>[Required]</B><br/>
<a href="#apiserver-config-k8s-io-v1-Key"><code>[]Key</code></a>
</td>
<td>
<p>keys is a list of keys to be used for creating the Secretbox transformer.
Each key has to be 32 bytes long.</p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/config-api/apiserver-webhookadmission.v1.md
+5 -8
View File
@@ -4,7 +4,8 @@ content_type: tool-reference
package: apiserver.config.k8s.io/v1
auto_generated: true
---
Package v1 is the v1 version of the API.
<p>Package v1 is the v1 version of the API.</p>
## Resource Types
@@ -17,10 +18,9 @@ Package v1 is the v1 version of the API.
<p>WebhookAdmission provides configuration for the webhook admission controller.</p>
WebhookAdmission provides configuration for the webhook admission controller.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
@@ -29,16 +29,13 @@ WebhookAdmission provides configuration for the webhook admission controller.
<tr><td><code>kind</code><br/>string</td><td><code>WebhookAdmission</code></td></tr>
<tr><td><code>kubeConfigFile</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
KubeConfigFile is the path to the kubeconfig file.</td>
<p>KubeConfigFile is the path to the kubeconfig file.</p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/config-api/client-authentication.v1.md
+67 -87
View File
@@ -17,11 +17,10 @@ auto_generated: true
<p>ExecCredential is used by exec-based plugins to communicate credentials to
HTTP transports.</p>
ExecCredential is used by exec-based plugins to communicate credentials to
HTTP transports.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
@@ -30,220 +29,201 @@ HTTP transports.
<tr><td><code>kind</code><br/>string</td><td><code>ExecCredential</code></td></tr>
<tr><td><code>spec</code> <B>[Required]</B><br/>
<a href="#client-authentication-k8s-io-v1-ExecCredentialSpec"><code>ExecCredentialSpec</code></a>
</td>
<td>
Spec holds information passed to the plugin by the transport.</td>
<p>Spec holds information passed to the plugin by the transport.</p>
</td>
</tr>
<tr><td><code>status</code><br/>
<a href="#client-authentication-k8s-io-v1-ExecCredentialStatus"><code>ExecCredentialStatus</code></a>
</td>
<td>
Status is filled in by the plugin and holds the credentials that the transport
should use to contact the API.</td>
<p>Status is filled in by the plugin and holds the credentials that the transport
should use to contact the API.</p>
</td>
</tr>
</tbody>
</table>
## `Cluster` {#client-authentication-k8s-io-v1-Cluster}
**Appears in:**
- [ExecCredentialSpec](#client-authentication-k8s-io-v1-ExecCredentialSpec)
Cluster contains information to allow an exec plugin to communicate
with the kubernetes cluster being authenticated to.
To ensure that this struct contains everything someone would need to communicate
<p>Cluster contains information to allow an exec plugin to communicate
with the kubernetes cluster being authenticated to.</p>
<p>To ensure that this struct contains everything someone would need to communicate
with a kubernetes cluster (just like they would via a kubeconfig), the fields
should shadow "k8s.io/client-go/tools/clientcmd/api/v1".Cluster, with the exception
of CertificateAuthority, since CA data will always be passed to the plugin as bytes.
should shadow &quot;k8s.io/client-go/tools/clientcmd/api/v1&quot;.Cluster, with the exception
of CertificateAuthority, since CA data will always be passed to the plugin as bytes.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>server</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Server is the address of the kubernetes cluster (https://hostname:port).</td>
<p>Server is the address of the kubernetes cluster (https://hostname:port).</p>
</td>
</tr>
<tr><td><code>tls-server-name</code><br/>
<code>string</code>
</td>
<td>
TLSServerName is passed to the server for SNI and is used in the client to
<p>TLSServerName is passed to the server for SNI and is used in the client to
check server certificates against. If ServerName is empty, the hostname
used to contact the server is used.</td>
used to contact the server is used.</p>
</td>
</tr>
<tr><td><code>insecure-skip-tls-verify</code><br/>
<code>bool</code>
</td>
<td>
InsecureSkipTLSVerify skips the validity check for the server's certificate.
This will make your HTTPS connections insecure.</td>
<p>InsecureSkipTLSVerify skips the validity check for the server's certificate.
This will make your HTTPS connections insecure.</p>
</td>
</tr>
<tr><td><code>certificate-authority-data</code><br/>
<code>[]byte</code>
</td>
<td>
CAData contains PEM-encoded certificate authority certificates.
If empty, system roots should be used.</td>
<p>CAData contains PEM-encoded certificate authority certificates.
If empty, system roots should be used.</p>
</td>
</tr>
<tr><td><code>proxy-url</code><br/>
<code>string</code>
</td>
<td>
ProxyURL is the URL to the proxy to be used for all requests to this
cluster.</td>
<p>ProxyURL is the URL to the proxy to be used for all requests to this
cluster.</p>
</td>
</tr>
<tr><td><code>config</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
</td>
<td>
Config holds additional config data that is specific to the exec
plugin with regards to the cluster being authenticated to.
This data is sourced from the clientcmd Cluster object's
extensions[client.authentication.k8s.io/exec] field:
clusters:
- name: my-cluster
<p>Config holds additional config data that is specific to the exec
plugin with regards to the cluster being authenticated to.</p>
<p>This data is sourced from the clientcmd Cluster object's
extensions[client.authentication.k8s.io/exec] field:</p>
<p>clusters:</p>
<ul>
<li>name: my-cluster
cluster:
...
extensions:
- name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
<ul>
<li>name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
extension:
audience: 06e3fbd18de8 # arbitrary config
In some environments, the user config may be exactly the same across many clusters
audience: 06e3fbd18de8 # arbitrary config</li>
</ul>
</li>
</ul>
<p>In some environments, the user config may be exactly the same across many clusters
(i.e. call this exec plugin) minus some details that are specific to each cluster
such as the audience. This field allows the per cluster config to be directly
specified with the cluster info. Using this field to store secret data is not
recommended as one of the prime benefits of exec plugins is that no secrets need
to be stored directly in the kubeconfig.</td>
to be stored directly in the kubeconfig.</p>
</td>
</tr>
</tbody>
</table>
## `ExecCredentialSpec` {#client-authentication-k8s-io-v1-ExecCredentialSpec}
**Appears in:**
- [ExecCredential](#client-authentication-k8s-io-v1-ExecCredential)
ExecCredentialSpec holds request and runtime specific information provided by
the transport.
<p>ExecCredentialSpec holds request and runtime specific information provided by
the transport.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>cluster</code><br/>
<a href="#client-authentication-k8s-io-v1-Cluster"><code>Cluster</code></a>
</td>
<td>
Cluster contains information to allow an exec plugin to communicate with the
<p>Cluster contains information to allow an exec plugin to communicate with the
kubernetes cluster being authenticated to. Note that Cluster is non-nil only
when provideClusterInfo is set to true in the exec provider config (i.e.,
ExecConfig.ProvideClusterInfo).</td>
ExecConfig.ProvideClusterInfo).</p>
</td>
</tr>
<tr><td><code>interactive</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
Interactive declares whether stdin has been passed to this exec plugin.</td>
<p>Interactive declares whether stdin has been passed to this exec plugin.</p>
</td>
</tr>
</tbody>
</table>
## `ExecCredentialStatus` {#client-authentication-k8s-io-v1-ExecCredentialStatus}
**Appears in:**
- [ExecCredential](#client-authentication-k8s-io-v1-ExecCredential)
ExecCredentialStatus holds credentials for the transport to use.
Token and ClientKeyData are sensitive fields. This data should only be
<p>ExecCredentialStatus holds credentials for the transport to use.</p>
<p>Token and ClientKeyData are sensitive fields. This data should only be
transmitted in-memory between client and exec plugin process. Exec plugin
itself should at least be protected via file permissions.
itself should at least be protected via file permissions.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>expirationTimestamp</code><br/>
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#time-v1-meta"><code>meta/v1.Time</code></a>
</td>
<td>
ExpirationTimestamp indicates a time when the provided credentials expire.</td>
<p>ExpirationTimestamp indicates a time when the provided credentials expire.</p>
</td>
</tr>
<tr><td><code>token</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Token is a bearer token used by the client for request authentication.</td>
<p>Token is a bearer token used by the client for request authentication.</p>
</td>
</tr>
<tr><td><code>clientCertificateData</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
PEM-encoded client TLS certificates (including intermediates, if any).</td>
<p>PEM-encoded client TLS certificates (including intermediates, if any).</p>
</td>
</tr>
<tr><td><code>clientKeyData</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
PEM-encoded private key for the above certificate.</td>
<p>PEM-encoded private key for the above certificate.</p>
</td>
</tr>
</tbody>
</table>
content/en/docs/reference/config-api/client-authentication.v1beta1.md
+52 -45
View File
@@ -17,8 +17,9 @@ auto_generated: true
ExecCredential is used by exec-based plugins to communicate credentials to
HTTP transports.
<p>ExecCredential is used by exec-based plugins to communicate credentials to
HTTP transports.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -32,15 +33,15 @@ HTTP transports.
<a href="#client-authentication-k8s-io-v1beta1-ExecCredentialSpec"><code>ExecCredentialSpec</code></a>
</td>
<td>
Spec holds information passed to the plugin by the transport.
<p>Spec holds information passed to the plugin by the transport.</p>
</td>
</tr>
<tr><td><code>status</code><br/>
<a href="#client-authentication-k8s-io-v1beta1-ExecCredentialStatus"><code>ExecCredentialStatus</code></a>
</td>
<td>
Status is filled in by the plugin and holds the credentials that the transport
should use to contact the API.
<p>Status is filled in by the plugin and holds the credentials that the transport
should use to contact the API.</p>
</td>
</tr>
</tbody>
@@ -53,13 +54,14 @@ should use to contact the API.
- [ExecCredentialSpec](#client-authentication-k8s-io-v1beta1-ExecCredentialSpec)
Cluster contains information to allow an exec plugin to communicate
with the kubernetes cluster being authenticated to.
To ensure that this struct contains everything someone would need to communicate
<p>Cluster contains information to allow an exec plugin to communicate
with the kubernetes cluster being authenticated to.</p>
<p>To ensure that this struct contains everything someone would need to communicate
with a kubernetes cluster (just like they would via a kubeconfig), the fields
should shadow "k8s.io/client-go/tools/clientcmd/api/v1".Cluster, with the exception
of CertificateAuthority, since CA data will always be passed to the plugin as bytes.
should shadow &quot;k8s.io/client-go/tools/clientcmd/api/v1&quot;.Cluster, with the exception
of CertificateAuthority, since CA data will always be passed to the plugin as bytes.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -70,67 +72,69 @@ of CertificateAuthority, since CA data will always be passed to the plugin as by
<code>string</code>
</td>
<td>
Server is the address of the kubernetes cluster (https://hostname:port).
<p>Server is the address of the kubernetes cluster (https://hostname:port).</p>
</td>
</tr>
<tr><td><code>tls-server-name</code><br/>
<code>string</code>
</td>
<td>
TLSServerName is passed to the server for SNI and is used in the client to
<p>TLSServerName is passed to the server for SNI and is used in the client to
check server certificates against. If ServerName is empty, the hostname
used to contact the server is used.
used to contact the server is used.</p>
</td>
</tr>
<tr><td><code>insecure-skip-tls-verify</code><br/>
<code>bool</code>
</td>
<td>
InsecureSkipTLSVerify skips the validity check for the server's certificate.
This will make your HTTPS connections insecure.
<p>InsecureSkipTLSVerify skips the validity check for the server's certificate.
This will make your HTTPS connections insecure.</p>
</td>
</tr>
<tr><td><code>certificate-authority-data</code><br/>
<code>[]byte</code>
</td>
<td>
CAData contains PEM-encoded certificate authority certificates.
If empty, system roots should be used.
<p>CAData contains PEM-encoded certificate authority certificates.
If empty, system roots should be used.</p>
</td>
</tr>
<tr><td><code>proxy-url</code><br/>
<code>string</code>
</td>
<td>
ProxyURL is the URL to the proxy to be used for all requests to this
cluster.
<p>ProxyURL is the URL to the proxy to be used for all requests to this
cluster.</p>
</td>
</tr>
<tr><td><code>config</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/runtime/#RawExtension"><code>k8s.io/apimachinery/pkg/runtime.RawExtension</code></a>
</td>
<td>
Config holds additional config data that is specific to the exec
plugin with regards to the cluster being authenticated to.
This data is sourced from the clientcmd Cluster object's
extensions[client.authentication.k8s.io/exec] field:
clusters:
- name: my-cluster
<p>Config holds additional config data that is specific to the exec
plugin with regards to the cluster being authenticated to.</p>
<p>This data is sourced from the clientcmd Cluster object's
extensions[client.authentication.k8s.io/exec] field:</p>
<p>clusters:</p>
<ul>
<li>name: my-cluster
cluster:
...
extensions:
- name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
<ul>
<li>name: client.authentication.k8s.io/exec # reserved extension name for per cluster exec config
extension:
audience: 06e3fbd18de8 # arbitrary config
In some environments, the user config may be exactly the same across many clusters
audience: 06e3fbd18de8 # arbitrary config</li>
</ul>
</li>
</ul>
<p>In some environments, the user config may be exactly the same across many clusters
(i.e. call this exec plugin) minus some details that are specific to each cluster
such as the audience. This field allows the per cluster config to be directly
specified with the cluster info. Using this field to store secret data is not
recommended as one of the prime benefits of exec plugins is that no secrets need
to be stored directly in the kubeconfig.
to be stored directly in the kubeconfig.</p>
</td>
</tr>
</tbody>
@@ -143,8 +147,10 @@ to be stored directly in the kubeconfig.
- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential)
ExecCredentialSpec holds request and runtime specific information provided by
the transport.
<p>ExecCredentialSpec holds request and runtime specific information provided by
the transport.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -155,17 +161,17 @@ the transport.
<a href="#client-authentication-k8s-io-v1beta1-Cluster"><code>Cluster</code></a>
</td>
<td>
Cluster contains information to allow an exec plugin to communicate with the
<p>Cluster contains information to allow an exec plugin to communicate with the
kubernetes cluster being authenticated to. Note that Cluster is non-nil only
when provideClusterInfo is set to true in the exec provider config (i.e.,
ExecConfig.ProvideClusterInfo).
ExecConfig.ProvideClusterInfo).</p>
</td>
</tr>
<tr><td><code>interactive</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
Interactive declares whether stdin has been passed to this exec plugin.
<p>Interactive declares whether stdin has been passed to this exec plugin.</p>
</td>
</tr>
</tbody>
@@ -178,11 +184,12 @@ ExecConfig.ProvideClusterInfo).
- [ExecCredential](#client-authentication-k8s-io-v1beta1-ExecCredential)
ExecCredentialStatus holds credentials for the transport to use.
Token and ClientKeyData are sensitive fields. This data should only be
<p>ExecCredentialStatus holds credentials for the transport to use.</p>
<p>Token and ClientKeyData are sensitive fields. This data should only be
transmitted in-memory between client and exec plugin process. Exec plugin
itself should at least be protected via file permissions.
itself should at least be protected via file permissions.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -193,28 +200,28 @@ itself should at least be protected via file permissions.
<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#time-v1-meta"><code>meta/v1.Time</code></a>
</td>
<td>
ExpirationTimestamp indicates a time when the provided credentials expire.
<p>ExpirationTimestamp indicates a time when the provided credentials expire.</p>
</td>
</tr>
<tr><td><code>token</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Token is a bearer token used by the client for request authentication.
<p>Token is a bearer token used by the client for request authentication.</p>
</td>
</tr>
<tr><td><code>clientCertificateData</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
PEM-encoded client TLS certificates (including intermediates, if any).
<p>PEM-encoded client TLS certificates (including intermediates, if any).</p>
</td>
</tr>
<tr><td><code>clientKeyData</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
PEM-encoded private key for the above certificate.
<p>PEM-encoded private key for the above certificate.</p>
</td>
</tr>
</tbody>
content/en/docs/reference/config-api/kube-proxy-config.v1alpha1.md
+341 -118
View File
@@ -17,8 +17,9 @@ auto_generated: true
KubeProxyConfiguration contains everything necessary to configure the
Kubernetes proxy server.
<p>KubeProxyConfiguration contains everything necessary to configure the
Kubernetes proxy server.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -32,164 +33,164 @@ Kubernetes proxy server.
<code>map[string]bool</code>
</td>
<td>
featureGates is a map of feature names to bools that enable or disable alpha/experimental features.
<p>featureGates is a map of feature names to bools that enable or disable alpha/experimental features.</p>
</td>
</tr>
<tr><td><code>bindAddress</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
bindAddress is the IP address for the proxy server to serve on (set to 0.0.0.0
for all interfaces)
<p>bindAddress is the IP address for the proxy server to serve on (set to 0.0.0.0
for all interfaces)</p>
</td>
</tr>
<tr><td><code>healthzBindAddress</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
healthzBindAddress is the IP address and port for the health check server to serve on,
defaulting to 0.0.0.0:10256
<p>healthzBindAddress is the IP address and port for the health check server to serve on,
defaulting to 0.0.0.0:10256</p>
</td>
</tr>
<tr><td><code>metricsBindAddress</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
metricsBindAddress is the IP address and port for the metrics server to serve on,
defaulting to 127.0.0.1:10249 (set to 0.0.0.0 for all interfaces)
<p>metricsBindAddress is the IP address and port for the metrics server to serve on,
defaulting to 127.0.0.1:10249 (set to 0.0.0.0 for all interfaces)</p>
</td>
</tr>
<tr><td><code>bindAddressHardFail</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
bindAddressHardFail, if true, kube-proxy will treat failure to bind to a port as fatal and exit
<p>bindAddressHardFail, if true, kube-proxy will treat failure to bind to a port as fatal and exit</p>
</td>
</tr>
<tr><td><code>enableProfiling</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
enableProfiling enables profiling via web interface on /debug/pprof handler.
Profiling handlers will be handled by metrics server.
<p>enableProfiling enables profiling via web interface on /debug/pprof handler.
Profiling handlers will be handled by metrics server.</p>
</td>
</tr>
<tr><td><code>clusterCIDR</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
clusterCIDR is the CIDR range of the pods in the cluster. It is used to
<p>clusterCIDR is the CIDR range of the pods in the cluster. It is used to
bridge traffic coming from outside of the cluster. If not provided,
no off-cluster bridging will be performed.
no off-cluster bridging will be performed.</p>
</td>
</tr>
<tr><td><code>hostnameOverride</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
hostnameOverride, if non-empty, will be used as the identity instead of the actual hostname.
<p>hostnameOverride, if non-empty, will be used as the identity instead of the actual hostname.</p>
</td>
</tr>
<tr><td><code>clientConnection</code> <B>[Required]</B><br/>
<a href="#ClientConnectionConfiguration"><code>ClientConnectionConfiguration</code></a>
</td>
<td>
clientConnection specifies the kubeconfig file and client connection settings for the proxy
server to use when communicating with the apiserver.
<p>clientConnection specifies the kubeconfig file and client connection settings for the proxy
server to use when communicating with the apiserver.</p>
</td>
</tr>
<tr><td><code>iptables</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-KubeProxyIPTablesConfiguration"><code>KubeProxyIPTablesConfiguration</code></a>
</td>
<td>
iptables contains iptables-related configuration options.
<p>iptables contains iptables-related configuration options.</p>
</td>
</tr>
<tr><td><code>ipvs</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-KubeProxyIPVSConfiguration"><code>KubeProxyIPVSConfiguration</code></a>
</td>
<td>
ipvs contains ipvs-related configuration options.
<p>ipvs contains ipvs-related configuration options.</p>
</td>
</tr>
<tr><td><code>oomScoreAdj</code> <B>[Required]</B><br/>
<code>int32</code>
</td>
<td>
oomScoreAdj is the oom-score-adj value for kube-proxy process. Values must be within
the range [-1000, 1000]
<p>oomScoreAdj is the oom-score-adj value for kube-proxy process. Values must be within
the range [-1000, 1000]</p>
</td>
</tr>
<tr><td><code>mode</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-ProxyMode"><code>ProxyMode</code></a>
</td>
<td>
mode specifies which proxy mode to use.
<p>mode specifies which proxy mode to use.</p>
</td>
</tr>
<tr><td><code>portRange</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
portRange is the range of host ports (beginPort-endPort, inclusive) that may be consumed
in order to proxy service traffic. If unspecified (0-0) then ports will be randomly chosen.
<p>portRange is the range of host ports (beginPort-endPort, inclusive) that may be consumed
in order to proxy service traffic. If unspecified (0-0) then ports will be randomly chosen.</p>
</td>
</tr>
<tr><td><code>udpIdleTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
udpIdleTimeout is how long an idle UDP connection will be kept open (e.g. '250ms', '2s').
Must be greater than 0. Only applicable for proxyMode=userspace.
<p>udpIdleTimeout is how long an idle UDP connection will be kept open (e.g. '250ms', '2s').
Must be greater than 0. Only applicable for proxyMode=userspace.</p>
</td>
</tr>
<tr><td><code>conntrack</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConntrackConfiguration"><code>KubeProxyConntrackConfiguration</code></a>
</td>
<td>
conntrack contains conntrack-related configuration options.
<p>conntrack contains conntrack-related configuration options.</p>
</td>
</tr>
<tr><td><code>configSyncPeriod</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
configSyncPeriod is how often configuration from the apiserver is refreshed. Must be greater
than 0.
<p>configSyncPeriod is how often configuration from the apiserver is refreshed. Must be greater
than 0.</p>
</td>
</tr>
<tr><td><code>nodePortAddresses</code> <B>[Required]</B><br/>
<code>[]string</code>
</td>
<td>
nodePortAddresses is the --nodeport-addresses value for kube-proxy process. Values must be valid
<p>nodePortAddresses is the --nodeport-addresses value for kube-proxy process. Values must be valid
IP blocks. These values are as a parameter to select the interfaces where nodeport works.
In case someone would like to expose a service on localhost for local visit and some other interfaces for
particular purpose, a list of IP blocks would do that.
If set it to "127.0.0.0/8", kube-proxy will only select the loopback interface for NodePort.
If set it to &quot;127.0.0.0/8&quot;, kube-proxy will only select the loopback interface for NodePort.
If set it to a non-zero IP block, kube-proxy will filter that down to just the IPs that applied to the node.
An empty string slice is meant to select all network interfaces.
An empty string slice is meant to select all network interfaces.</p>
</td>
</tr>
<tr><td><code>winkernel</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-KubeProxyWinkernelConfiguration"><code>KubeProxyWinkernelConfiguration</code></a>
</td>
<td>
winkernel contains winkernel-related configuration options.
<p>winkernel contains winkernel-related configuration options.</p>
</td>
</tr>
<tr><td><code>showHiddenMetricsForVersion</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
ShowHiddenMetricsForVersion is the version for which you want to show hidden metrics.
<p>ShowHiddenMetricsForVersion is the version for which you want to show hidden metrics.</p>
</td>
</tr>
<tr><td><code>detectLocalMode</code> <B>[Required]</B><br/>
<a href="#kubeproxy-config-k8s-io-v1alpha1-LocalMode"><code>LocalMode</code></a>
</td>
<td>
DetectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR
<p>DetectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR</p>
</td>
</tr>
</tbody>
@@ -202,8 +203,10 @@ An empty string slice is meant to select all network interfaces.
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
KubeProxyConntrackConfiguration contains conntrack settings for
the Kubernetes proxy server.
<p>KubeProxyConntrackConfiguration contains conntrack settings for
the Kubernetes proxy server.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -214,33 +217,33 @@ the Kubernetes proxy server.
<code>int32</code>
</td>
<td>
maxPerCore is the maximum number of NAT connections to track
per CPU core (0 to leave the limit as-is and ignore min).
<p>maxPerCore is the maximum number of NAT connections to track
per CPU core (0 to leave the limit as-is and ignore min).</p>
</td>
</tr>
<tr><td><code>min</code> <B>[Required]</B><br/>
<code>int32</code>
</td>
<td>
min is the minimum value of connect-tracking records to allocate,
regardless of conntrackMaxPerCore (set maxPerCore=0 to leave the limit as-is).
<p>min is the minimum value of connect-tracking records to allocate,
regardless of conntrackMaxPerCore (set maxPerCore=0 to leave the limit as-is).</p>
</td>
</tr>
<tr><td><code>tcpEstablishedTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
tcpEstablishedTimeout is how long an idle TCP connection will be kept open
(e.g. '2s'). Must be greater than 0 to set.
<p>tcpEstablishedTimeout is how long an idle TCP connection will be kept open
(e.g. '2s'). Must be greater than 0 to set.</p>
</td>
</tr>
<tr><td><code>tcpCloseWaitTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
tcpCloseWaitTimeout is how long an idle conntrack entry
<p>tcpCloseWaitTimeout is how long an idle conntrack entry
in CLOSE_WAIT state will remain in the conntrack
table. (e.g. '60s'). Must be greater than 0 to set.
table. (e.g. '60s'). Must be greater than 0 to set.</p>
</td>
</tr>
</tbody>
@@ -253,8 +256,10 @@ table. (e.g. '60s'). Must be greater than 0 to set.
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
KubeProxyIPTablesConfiguration contains iptables-related configuration
details for the Kubernetes proxy server.
<p>KubeProxyIPTablesConfiguration contains iptables-related configuration
details for the Kubernetes proxy server.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -265,31 +270,31 @@ details for the Kubernetes proxy server.
<code>int32</code>
</td>
<td>
masqueradeBit is the bit of the iptables fwmark space to use for SNAT if using
the pure iptables proxy mode. Values must be within the range [0, 31].
<p>masqueradeBit is the bit of the iptables fwmark space to use for SNAT if using
the pure iptables proxy mode. Values must be within the range [0, 31].</p>
</td>
</tr>
<tr><td><code>masqueradeAll</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
masqueradeAll tells kube-proxy to SNAT everything if using the pure iptables proxy mode.
<p>masqueradeAll tells kube-proxy to SNAT everything if using the pure iptables proxy mode.</p>
</td>
</tr>
<tr><td><code>syncPeriod</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
syncPeriod is the period that iptables rules are refreshed (e.g. '5s', '1m',
'2h22m'). Must be greater than 0.
<p>syncPeriod is the period that iptables rules are refreshed (e.g. '5s', '1m',
'2h22m'). Must be greater than 0.</p>
</td>
</tr>
<tr><td><code>minSyncPeriod</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
minSyncPeriod is the minimum period that iptables rules are refreshed (e.g. '5s', '1m',
'2h22m').
<p>minSyncPeriod is the minimum period that iptables rules are refreshed (e.g. '5s', '1m',
'2h22m').</p>
</td>
</tr>
</tbody>
@@ -302,8 +307,10 @@ the pure iptables proxy mode. Values must be within the range [0, 31].
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
KubeProxyIPVSConfiguration contains ipvs-related configuration
details for the Kubernetes proxy server.
<p>KubeProxyIPVSConfiguration contains ipvs-related configuration
details for the Kubernetes proxy server.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -311,66 +318,66 @@ details for the Kubernetes proxy server.
<tr><td><code>syncPeriod</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
syncPeriod is the period that ipvs rules are refreshed (e.g. '5s', '1m',
'2h22m'). Must be greater than 0.
<p>syncPeriod is the period that ipvs rules are refreshed (e.g. '5s', '1m',
'2h22m'). Must be greater than 0.</p>
</td>
</tr>
<tr><td><code>minSyncPeriod</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
minSyncPeriod is the minimum period that ipvs rules are refreshed (e.g. '5s', '1m',
'2h22m').
<p>minSyncPeriod is the minimum period that ipvs rules are refreshed (e.g. '5s', '1m',
'2h22m').</p>
</td>
</tr>
<tr><td><code>scheduler</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
ipvs scheduler
<p>ipvs scheduler</p>
</td>
</tr>
<tr><td><code>excludeCIDRs</code> <B>[Required]</B><br/>
<code>[]string</code>
</td>
<td>
excludeCIDRs is a list of CIDR's which the ipvs proxier should not touch
when cleaning up ipvs services.
<p>excludeCIDRs is a list of CIDR's which the ipvs proxier should not touch
when cleaning up ipvs services.</p>
</td>
</tr>
<tr><td><code>strictARP</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
strict ARP configure arp_ignore and arp_announce to avoid answering ARP queries
from kube-ipvs0 interface
<p>strict ARP configure arp_ignore and arp_announce to avoid answering ARP queries
from kube-ipvs0 interface</p>
</td>
</tr>
<tr><td><code>tcpTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
tcpTimeout is the timeout value used for idle IPVS TCP sessions.
The default value is 0, which preserves the current timeout value on the system.
<p>tcpTimeout is the timeout value used for idle IPVS TCP sessions.
The default value is 0, which preserves the current timeout value on the system.</p>
</td>
</tr>
<tr><td><code>tcpFinTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
tcpFinTimeout is the timeout value used for IPVS TCP sessions after receiving a FIN.
The default value is 0, which preserves the current timeout value on the system.
<p>tcpFinTimeout is the timeout value used for IPVS TCP sessions after receiving a FIN.
The default value is 0, which preserves the current timeout value on the system.</p>
</td>
</tr>
<tr><td><code>udpTimeout</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
udpTimeout is the timeout value used for IPVS UDP packets.
The default value is 0, which preserves the current timeout value on the system.
<p>udpTimeout is the timeout value used for IPVS UDP packets.
The default value is 0, which preserves the current timeout value on the system.</p>
</td>
</tr>
</tbody>
@@ -383,8 +390,10 @@ The default value is 0, which preserves the current timeout value on the system.
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
KubeProxyWinkernelConfiguration contains Windows/HNS settings for
the Kubernetes proxy server.
<p>KubeProxyWinkernelConfiguration contains Windows/HNS settings for
the Kubernetes proxy server.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -395,24 +404,24 @@ the Kubernetes proxy server.
<code>string</code>
</td>
<td>
networkName is the name of the network kube-proxy will use
to create endpoints and policies
<p>networkName is the name of the network kube-proxy will use
to create endpoints and policies</p>
</td>
</tr>
<tr><td><code>sourceVip</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
sourceVip is the IP address of the source VIP endoint used for
NAT when loadbalancing
<p>sourceVip is the IP address of the source VIP endoint used for
NAT when loadbalancing</p>
</td>
</tr>
<tr><td><code>enableDSR</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
enableDSR tells kube-proxy whether HNS policies should be created
with DSR
<p>enableDSR tells kube-proxy whether HNS policies should be created
with DSR</p>
</td>
</tr>
</tbody>
@@ -421,36 +430,38 @@ with DSR
## `LocalMode` {#kubeproxy-config-k8s-io-v1alpha1-LocalMode}
(Alias of `string`)
**Appears in:**
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
LocalMode represents modes to detect local traffic from the node
<p>LocalMode represents modes to detect local traffic from the node</p>
## `ProxyMode` {#kubeproxy-config-k8s-io-v1alpha1-ProxyMode}
(Alias of `string`)
**Appears in:**
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
ProxyMode represents modes used by the Kubernetes proxy server.
Currently, three modes of proxy are available in Linux platform: 'userspace' (older, going to be EOL), 'iptables'
(newer, faster), 'ipvs'(newest, better in performance and scalability).
Two modes of proxy are available in Windows platform: 'userspace'(older, stable) and 'kernelspace' (newer, faster).
In Linux platform, if proxy mode is blank, use the best-available proxy (currently iptables, but may change in the
<p>ProxyMode represents modes used by the Kubernetes proxy server.</p>
<p>Currently, three modes of proxy are available in Linux platform: 'userspace' (older, going to be EOL), 'iptables'
(newer, faster), 'ipvs'(newest, better in performance and scalability).</p>
<p>Two modes of proxy are available in Windows platform: 'userspace'(older, stable) and 'kernelspace' (newer, faster).</p>
<p>In Linux platform, if proxy mode is blank, use the best-available proxy (currently iptables, but may change in the
future). If the iptables proxy is selected, regardless of how, but the system's kernel or iptables versions are
insufficient, this always falls back to the userspace proxy. IPVS mode will be enabled when proxy mode is set to 'ipvs',
and the fall back path is firstly iptables and then userspace.
In Windows platform, if proxy mode is blank, use the best-available proxy (currently userspace, but may change in the
and the fall back path is firstly iptables and then userspace.</p>
<p>In Windows platform, if proxy mode is blank, use the best-available proxy (currently userspace, but may change in the
future). If winkernel proxy is selected, regardless of how, but the Windows kernel can't support this mode of proxy,
this always falls back to the userspace proxy.
this always falls back to the userspace proxy.</p>
@@ -464,7 +475,15 @@ this always falls back to the userspace proxy.
- [KubeProxyConfiguration](#kubeproxy-config-k8s-io-v1alpha1-KubeProxyConfiguration)
ClientConnectionConfiguration contains details for constructing a client.
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta2-KubeSchedulerConfiguration)
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta3-KubeSchedulerConfiguration)
- [GenericControllerManagerConfiguration](#controllermanager-config-k8s-io-v1alpha1-GenericControllerManagerConfiguration)
<p>ClientConnectionConfiguration contains details for constructing a client.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -475,37 +494,75 @@ ClientConnectionConfiguration contains details for constructing a client.
<code>string</code>
</td>
<td>
kubeconfig is the path to a KubeConfig file.
<p>kubeconfig is the path to a KubeConfig file.</p>
</td>
</tr>
<tr><td><code>acceptContentTypes</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
acceptContentTypes defines the Accept header sent by clients when connecting to a server, overriding the
<p>acceptContentTypes defines the Accept header sent by clients when connecting to a server, overriding the
default value of 'application/json'. This field will control all connections to the server used by a particular
client.
client.</p>
</td>
</tr>
<tr><td><code>contentType</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
contentType is the content type used when sending data to the server from this client.
<p>contentType is the content type used when sending data to the server from this client.</p>
</td>
</tr>
<tr><td><code>qps</code> <B>[Required]</B><br/>
<code>float32</code>
</td>
<td>
qps controls the number of queries per second allowed for this connection.
<p>qps controls the number of queries per second allowed for this connection.</p>
</td>
</tr>
<tr><td><code>burst</code> <B>[Required]</B><br/>
<code>int32</code>
</td>
<td>
burst allows extra queries to accumulate when a client is exceeding its rate.
<p>burst allows extra queries to accumulate when a client is exceeding its rate.</p>
</td>
</tr>
</tbody>
</table>
## `DebuggingConfiguration` {#DebuggingConfiguration}
**Appears in:**
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta2-KubeSchedulerConfiguration)
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta3-KubeSchedulerConfiguration)
- [GenericControllerManagerConfiguration](#controllermanager-config-k8s-io-v1alpha1-GenericControllerManagerConfiguration)
<p>DebuggingConfiguration holds configuration for Debugging related features.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>enableProfiling</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
<p>enableProfiling enables profiling via web interface host:port/debug/pprof/</p>
</td>
</tr>
<tr><td><code>enableContentionProfiling</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
<p>enableContentionProfiling enables lock contention profiling, if
enableProfiling is true.</p>
</td>
</tr>
</tbody>
@@ -516,9 +573,11 @@ client.
**Appears in:**
- [LoggingConfiguration](#LoggingConfiguration)
FormatOptions contains options for the different logging formats.
<p>FormatOptions contains options for the different logging formats.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -529,7 +588,7 @@ FormatOptions contains options for the different logging formats.
<a href="#JSONOptions"><code>JSONOptions</code></a>
</td>
<td>
[Experimental] JSON contains options for logging format "json".
<p>[Experimental] JSON contains options for logging format &quot;json&quot;.</p>
</td>
</tr>
</tbody>
@@ -542,7 +601,9 @@ FormatOptions contains options for the different logging formats.
- [FormatOptions](#FormatOptions)
JSONOptions contains options for logging format "json".
<p>JSONOptions contains options for logging format &quot;json&quot;.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -553,17 +614,176 @@ JSONOptions contains options for logging format "json".
<code>bool</code>
</td>
<td>
[Experimental] SplitStream redirects error messages to stderr while
<p>[Experimental] SplitStream redirects error messages to stderr while
info messages go to stdout, with buffering. The default is to write
both to stdout, without buffering.
both to stdout, without buffering.</p>
</td>
</tr>
<tr><td><code>infoBufferSize</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue"><code>k8s.io/apimachinery/pkg/api/resource.QuantityValue</code></a>
</td>
<td>
[Experimental] InfoBufferSize sets the size of the info stream when
using split streams. The default is zero, which disables buffering.
<p>[Experimental] InfoBufferSize sets the size of the info stream when
using split streams. The default is zero, which disables buffering.</p>
</td>
</tr>
</tbody>
</table>
## `LeaderElectionConfiguration` {#LeaderElectionConfiguration}
**Appears in:**
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta2-KubeSchedulerConfiguration)
- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta3-KubeSchedulerConfiguration)
- [GenericControllerManagerConfiguration](#controllermanager-config-k8s-io-v1alpha1-GenericControllerManagerConfiguration)
<p>LeaderElectionConfiguration defines the configuration of leader election
clients for components that can run with leader election enabled.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>leaderElect</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
<p>leaderElect enables a leader election client to gain leadership
before executing the main loop. Enable this when running replicated
components for high availability.</p>
</td>
</tr>
<tr><td><code>leaseDuration</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
<p>leaseDuration is the duration that non-leader candidates will wait
after observing a leadership renewal until attempting to acquire
leadership of a led but unrenewed leader slot. This is effectively the
maximum duration that a leader can be stopped before it is replaced
by another candidate. This is only applicable if leader election is
enabled.</p>
</td>
</tr>
<tr><td><code>renewDeadline</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
<p>renewDeadline is the interval between attempts by the acting master to
renew a leadership slot before it stops leading. This must be less
than or equal to the lease duration. This is only applicable if leader
election is enabled.</p>
</td>
</tr>
<tr><td><code>retryPeriod</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
<p>retryPeriod is the duration the clients should wait between attempting
acquisition and renewal of a leadership. This is only applicable if
leader election is enabled.</p>
</td>
</tr>
<tr><td><code>resourceLock</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>resourceLock indicates the resource object type that will be used to lock
during leader election cycles.</p>
</td>
</tr>
<tr><td><code>resourceName</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>resourceName indicates the name of resource object that will be used to lock
during leader election cycles.</p>
</td>
</tr>
<tr><td><code>resourceNamespace</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>resourceName indicates the namespace of resource object that will be used to lock
during leader election cycles.</p>
</td>
</tr>
</tbody>
</table>
## `LoggingConfiguration` {#LoggingConfiguration}
**Appears in:**
- [KubeletConfiguration](#kubelet-config-k8s-io-v1beta1-KubeletConfiguration)
<p>LoggingConfiguration contains logging options
Refer <a href="https://github.com/kubernetes/component-base/blob/master/logs/options.go">Logs Options</a> for more information.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>format</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<p>Format Flag specifies the structure of log messages.
default value of format is <code>text</code></p>
</td>
</tr>
<tr><td><code>flushFrequency</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/time#Duration"><code>time.Duration</code></a>
</td>
<td>
<p>Maximum number of seconds between log flushes. Ignored if the
selected logging backend writes log messages without buffering.</p>
</td>
</tr>
<tr><td><code>verbosity</code> <B>[Required]</B><br/>
<code>uint32</code>
</td>
<td>
<p>Verbosity is the threshold that determines which log messages are
logged. Default is zero which logs only the most important
messages. Higher values enable additional messages. Error messages
are always logged.</p>
</td>
</tr>
<tr><td><code>vmodule</code> <B>[Required]</B><br/>
<a href="#VModuleConfiguration"><code>VModuleConfiguration</code></a>
</td>
<td>
<p>VModule overrides the verbosity threshold for individual files.
Only supported for &quot;text&quot; log format.</p>
</td>
</tr>
<tr><td><code>sanitization</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
<p>[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.`)</p>
</td>
</tr>
<tr><td><code>options</code> <B>[Required]</B><br/>
<a href="#FormatOptions"><code>FormatOptions</code></a>
</td>
<td>
<p>[Experimental] Options holds additional parameters that are specific
to the different logging formats. Only the options for the selected
format get used, but all of them get validated.</p>
</td>
</tr>
</tbody>
@@ -572,11 +792,14 @@ using split streams. The default is zero, which disables buffering.
## `VModuleConfiguration` {#VModuleConfiguration}
(Alias of `[]k8s.io/component-base/config/v1alpha1.VModuleItem`)
**Appears in:**
- [LoggingConfiguration](#LoggingConfiguration)
VModuleConfiguration is a collection of individual file names or patterns
and the corresponding verbosity threshold.
<p>VModuleConfiguration is a collection of individual file names or patterns
and the corresponding verbosity threshold.</p>
content/en/docs/reference/config-api/kube-scheduler-config.v1beta2.md
+598 -728
View File
File diff suppressed because it is too large Load Diff
content/en/docs/reference/config-api/kube-scheduler-config.v1beta3.md
+375 -499
View File
File diff suppressed because it is too large Load Diff
content/en/docs/reference/config-api/kubeadm-config.v1beta2.md
+520 -661
View File
File diff suppressed because it is too large Load Diff
content/en/docs/reference/config-api/kubeadm-config.v1beta3.md
+607 -655
View File
File diff suppressed because it is too large Load Diff
content/en/docs/reference/config-api/kubelet-config.v1alpha1.md
+129 -161
View File
@@ -13,102 +13,14 @@ auto_generated: true
## `FormatOptions` {#FormatOptions}
**Appears in:**
- [LoggingConfiguration](#LoggingConfiguration)
FormatOptions contains options for the different logging formats.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>json</code> <B>[Required]</B><br/>
<a href="#JSONOptions"><code>JSONOptions</code></a>
</td>
<td>
[Experimental] JSON contains options for logging format "json".</td>
</tr>
</tbody>
</table>
## `JSONOptions` {#JSONOptions}
**Appears in:**
- [FormatOptions](#FormatOptions)
JSONOptions contains options for logging format "json".
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>splitStream</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
[Experimental] SplitStream redirects error messages to stderr while
info messages go to stdout, with buffering. The default is to write
both to stdout, without buffering.</td>
</tr>
<tr><td><code>infoBufferSize</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue"><code>k8s.io/apimachinery/pkg/api/resource.QuantityValue</code></a>
</td>
<td>
[Experimental] InfoBufferSize sets the size of the info stream when
using split streams. The default is zero, which disables buffering.</td>
</tr>
</tbody>
</table>
## `VModuleConfiguration` {#VModuleConfiguration}
(Alias of `[]k8s.io/component-base/config/v1alpha1.VModuleItem`)
**Appears in:**
- [LoggingConfiguration](#LoggingConfiguration)
VModuleConfiguration is a collection of individual file names or patterns
and the corresponding verbosity threshold.
## `CredentialProviderConfig` {#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig}
CredentialProviderConfig is the configuration containing information about
<p>CredentialProviderConfig is the configuration containing information about
each exec credential provider. Kubelet reads this configuration from disk and enables
each provider as specified by the CredentialProvider type.
each provider as specified by the CredentialProvider type.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
@@ -118,164 +30,220 @@ each provider as specified by the CredentialProvider type.
<tr><td><code>kind</code><br/>string</td><td><code>CredentialProviderConfig</code></td></tr>
<tr><td><code>providers</code> <B>[Required]</B><br/>
<a href="#kubelet-config-k8s-io-v1alpha1-CredentialProvider"><code>[]CredentialProvider</code></a>
</td>
<td>
providers is a list of credential provider plugins that will be enabled by the kubelet.
<p>providers is a list of credential provider plugins that will be enabled by the kubelet.
Multiple providers may match against a single image, in which case credentials
from all providers will be returned to the kubelet. If multiple providers are called
for a single image, the results are combined. If providers return overlapping
auth keys, the value from the provider earlier in this list is used.</td>
auth keys, the value from the provider earlier in this list is used.</p>
</td>
</tr>
</tbody>
</table>
## `CredentialProvider` {#kubelet-config-k8s-io-v1alpha1-CredentialProvider}
**Appears in:**
- [CredentialProviderConfig](#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig)
CredentialProvider represents an exec plugin to be invoked by the kubelet. The plugin is only
invoked when an image being pulled matches the images handled by the plugin (see matchImages).
<p>CredentialProvider represents an exec plugin to be invoked by the kubelet. The plugin is only
invoked when an image being pulled matches the images handled by the plugin (see matchImages).</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
name is the required name of the credential provider. It must match the name of the
<p>name is the required name of the credential provider. It must match the name of the
provider executable as seen by the kubelet. The executable must be in the kubelet's
bin directory (set by the --image-credential-provider-bin-dir flag).</td>
bin directory (set by the --image-credential-provider-bin-dir flag).</p>
</td>
</tr>
<tr><td><code>matchImages</code> <B>[Required]</B><br/>
<code>[]string</code>
</td>
<td>
matchImages is a required list of strings used to match against images in order to
<p>matchImages is a required list of strings used to match against images in order to
determine if this provider should be invoked. If one of the strings matches the
requested image from the kubelet, the plugin will be invoked and given a chance
to provide credentials. Images are expected to contain the registry domain
and URL path.
Each entry in matchImages is a pattern which can optionally contain a port and a path.
and URL path.</p>
<p>Each entry in matchImages is a pattern which can optionally contain a port and a path.
Globs can be used in the domain, but not in the port or the path. Globs are supported
as subdomains like '&lowast;.k8s.io' or 'k8s.&lowast;.io', and top-level-domains such as 'k8s.&lowast;'.
Matching partial subdomains like 'app&lowast;.k8s.io' is also supported. Each glob can only match
a single subdomain segment, so &lowast;.io does not match &lowast;.k8s.io.
A match exists between an image and a matchImage when all of the below are true:
- Both contain the same number of domain parts and each part matches.
- The URL path of an imageMatch must be a prefix of the target image URL path.
- If the imageMatch contains a port, then the port must match in the image as well.
Example values of matchImages:
- 123456789.dkr.ecr.us-east-1.amazonaws.com
- &lowast;.azurecr.io
- gcr.io
- &lowast;.&lowast;.registry.io
- registry.io:8080/path</td>
as subdomains like '<em>.k8s.io' or 'k8s.</em>.io', and top-level-domains such as 'k8s.<em>'.
Matching partial subdomains like 'app</em>.k8s.io' is also supported. Each glob can only match
a single subdomain segment, so *.io does not match *.k8s.io.</p>
<p>A match exists between an image and a matchImage when all of the below are true:</p>
<ul>
<li>Both contain the same number of domain parts and each part matches.</li>
<li>The URL path of an imageMatch must be a prefix of the target image URL path.</li>
<li>If the imageMatch contains a port, then the port must match in the image as well.</li>
</ul>
<p>Example values of matchImages:</p>
<ul>
<li>123456789.dkr.ecr.us-east-1.amazonaws.com</li>
<li>*.azurecr.io</li>
<li>gcr.io</li>
<li><em>.</em>.registry.io</li>
<li>registry.io:8080/path</li>
</ul>
</td>
</tr>
<tr><td><code>defaultCacheDuration</code> <B>[Required]</B><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
defaultCacheDuration is the default duration the plugin will cache credentials in-memory
if a cache duration is not provided in the plugin response. This field is required.</td>
<p>defaultCacheDuration is the default duration the plugin will cache credentials in-memory
if a cache duration is not provided in the plugin response. This field is required.</p>
</td>
</tr>
<tr><td><code>apiVersion</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
Required input version of the exec CredentialProviderRequest. The returned CredentialProviderResponse
MUST use the same encoding version as the input. Current supported values are:
- credentialprovider.kubelet.k8s.io/v1alpha1</td>
<p>Required input version of the exec CredentialProviderRequest. The returned CredentialProviderResponse
MUST use the same encoding version as the input. Current supported values are:</p>
<ul>
<li>credentialprovider.kubelet.k8s.io/v1alpha1</li>
</ul>
</td>
</tr>
<tr><td><code>args</code><br/>
<code>[]string</code>
</td>
<td>
Arguments to pass to the command when executing it.</td>
<p>Arguments to pass to the command when executing it.</p>
</td>
</tr>
<tr><td><code>env</code><br/>
<a href="#kubelet-config-k8s-io-v1alpha1-ExecEnvVar"><code>[]ExecEnvVar</code></a>
</td>
<td>
Env defines additional environment variables to expose to the process. These
<p>Env defines additional environment variables to expose to the process. These
are unioned with the host's environment, as well as variables client-go uses
to pass argument to the plugin.</td>
to pass argument to the plugin.</p>
</td>
</tr>
</tbody>
</table>
## `ExecEnvVar` {#kubelet-config-k8s-io-v1alpha1-ExecEnvVar}
**Appears in:**
- [CredentialProvider](#kubelet-config-k8s-io-v1alpha1-CredentialProvider)
ExecEnvVar is used for setting environment variables when executing an exec-based
credential plugin.
<p>ExecEnvVar is used for setting environment variables when executing an exec-based
credential plugin.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>name</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
<tr><td><code>value</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
<span class="text-muted">No description provided.</span>
</td>
<span class="text-muted">No description provided.</span></td>
</tr>
</tbody>
</table>
## `FormatOptions` {#FormatOptions}
**Appears in:**
<p>FormatOptions contains options for the different logging formats.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>json</code> <B>[Required]</B><br/>
<a href="#JSONOptions"><code>JSONOptions</code></a>
</td>
<td>
<p>[Experimental] JSON contains options for logging format &quot;json&quot;.</p>
</td>
</tr>
</tbody>
</table>
## `JSONOptions` {#JSONOptions}
**Appears in:**
- [FormatOptions](#FormatOptions)
<p>JSONOptions contains options for logging format &quot;json&quot;.</p>
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>splitStream</code> <B>[Required]</B><br/>
<code>bool</code>
</td>
<td>
<p>[Experimental] SplitStream redirects error messages to stderr while
info messages go to stdout, with buffering. The default is to write
both to stdout, without buffering.</p>
</td>
</tr>
<tr><td><code>infoBufferSize</code> <B>[Required]</B><br/>
<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#QuantityValue"><code>k8s.io/apimachinery/pkg/api/resource.QuantityValue</code></a>
</td>
<td>
<p>[Experimental] InfoBufferSize sets the size of the info stream when
using split streams. The default is zero, which disables buffering.</p>
</td>
</tr>
</tbody>
</table>
## `VModuleConfiguration` {#VModuleConfiguration}
(Alias of `[]k8s.io/component-base/config/v1alpha1.VModuleItem`)
**Appears in:**
<p>VModuleConfiguration is a collection of individual file names or patterns
and the corresponding verbosity threshold.</p>
content/en/docs/reference/config-api/kubelet-config.v1beta1.md
+629 -795
View File
File diff suppressed because it is too large Load Diff
content/en/docs/reference/config-api/kubelet-credentialprovider.v1alpha1.md
+192
View File
@@ -0,0 +1,192 @@
---
title: Kubelet CredentialProvider (v1alpha1)
content_type: tool-reference
package: credentialprovider.kubelet.k8s.io/v1alpha1
auto_generated: true
---
## Resource Types
- [CredentialProviderRequest](#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderRequest)
- [CredentialProviderResponse](#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderResponse)
## `CredentialProviderRequest` {#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderRequest}
CredentialProviderRequest includes the image that the kubelet requires authentication for.
Kubelet will pass this request object to the plugin via stdin. In general, plugins should
prefer responding with the same apiVersion they were sent.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>credentialprovider.kubelet.k8s.io/v1alpha1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>CredentialProviderRequest</code></td></tr>
<tr><td><code>image</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
image is the container image that is being pulled as part of the
credential provider plugin request. Plugins may optionally parse the image
to extract any information required to fetch credentials.</td>
</tr>
</tbody>
</table>
## `CredentialProviderResponse` {#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderResponse}
CredentialProviderResponse holds credentials that the kubelet should use for the specified
image provided in the original request. Kubelet will read the response from the plugin via stdout.
This response should be set to the same apiVersion as CredentialProviderRequest.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>apiVersion</code><br/>string</td><td><code>credentialprovider.kubelet.k8s.io/v1alpha1</code></td></tr>
<tr><td><code>kind</code><br/>string</td><td><code>CredentialProviderResponse</code></td></tr>
<tr><td><code>cacheKeyType</code> <B>[Required]</B><br/>
<a href="#credentialprovider-kubelet-k8s-io-v1alpha1-PluginCacheKeyType"><code>PluginCacheKeyType</code></a>
</td>
<td>
cacheKeyType indiciates the type of caching key to use based on the image provided
in the request. There are three valid values for the cache key type: Image, Registry, and
Global. If an invalid value is specified, the response will NOT be used by the kubelet.</td>
</tr>
<tr><td><code>cacheDuration</code><br/>
<a href="https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"><code>meta/v1.Duration</code></a>
</td>
<td>
cacheDuration indicates the duration the provided credentials should be cached for.
The kubelet will use this field to set the in-memory cache duration for credentials
in the AuthConfig. If null, the kubelet will use defaultCacheDuration provided in
CredentialProviderConfig. If set to 0, the kubelet will not cache the provided AuthConfig.</td>
</tr>
<tr><td><code>auth</code><br/>
<a href="#credentialprovider-kubelet-k8s-io-v1alpha1-AuthConfig"><code>map[string]k8s.io/kubelet/pkg/apis/credentialprovider/v1alpha1.AuthConfig</code></a>
</td>
<td>
auth is a map containing authentication information passed into the kubelet.
Each key is a match image string (more on this below). The corresponding authConfig value
should be valid for all images that match against this key. A plugin should set
this field to null if no valid credentials can be returned for the requested image.
Each key in the map is a pattern which can optionally contain a port and a path.
Globs can be used in the domain, but not in the port or the path. Globs are supported
as subdomains like '&lowast;.k8s.io' or 'k8s.&lowast;.io', and top-level-domains such as 'k8s.&lowast;'.
Matching partial subdomains like 'app&lowast;.k8s.io' is also supported. Each glob can only match
a single subdomain segment, so &lowast;.io does not match &lowast;.k8s.io.
The kubelet will match images against the key when all of the below are true:
- Both contain the same number of domain parts and each part matches.
- The URL path of an imageMatch must be a prefix of the target image URL path.
- If the imageMatch contains a port, then the port must match in the image as well.
When multiple keys are returned, the kubelet will traverse all keys in reverse order so that:
- longer keys come before shorter keys with the same prefix
- non-wildcard keys come before wildcard keys with the same prefix.
For any given match, the kubelet will attempt an image pull with the provided credentials,
stopping after the first successfully authenticated pull.
Example keys:
- 123456789.dkr.ecr.us-east-1.amazonaws.com
- &lowast;.azurecr.io
- gcr.io
- &lowast;.&lowast;.registry.io
- registry.io:8080/path</td>
</tr>
</tbody>
</table>
## `AuthConfig` {#credentialprovider-kubelet-k8s-io-v1alpha1-AuthConfig}
**Appears in:**
- [CredentialProviderResponse](#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderResponse)
AuthConfig contains authentication information for a container registry.
Only username/password based authentication is supported today, but more authentication
mechanisms may be added in the future.
<table class="table">
<thead><tr><th width="30%">Field</th><th>Description</th></tr></thead>
<tbody>
<tr><td><code>username</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
username is the username used for authenticating to the container registry
An empty username is valid.</td>
</tr>
<tr><td><code>password</code> <B>[Required]</B><br/>
<code>string</code>
</td>
<td>
password is the password used for authenticating to the container registry
An empty password is valid.</td>
</tr>
</tbody>
</table>
## `PluginCacheKeyType` {#credentialprovider-kubelet-k8s-io-v1alpha1-PluginCacheKeyType}
(Alias of `string`)
**Appears in:**
- [CredentialProviderResponse](#credentialprovider-kubelet-k8s-io-v1alpha1-CredentialProviderResponse)
content/en/docs/reference/glossary/finalizer.md
+3 -3
View File
@@ -19,12 +19,12 @@ to clean up resources the deleted object owned.
<!--more-->
When you tell Kubernetes to delete an object that has finalizers specified for
it, the Kubernetes API marks the object for deletion, putting it into a
read-only state. The target object remains in a terminating state while the
it, the Kubernetes API marks the object for deletion by populating `.metadata.deletionTimestamp`,
and returns a `202` status code (HTTP "Accepted"). The target object remains in a terminating state while the
control plane, or other components, take the actions defined by the finalizers.
After these actions are complete, the controller removes the relevant finalizers
from the target object. When the `metadata.finalizers` field is empty,
Kubernetes considers the deletion complete.
Kubernetes considers the deletion complete and deletes the object.
You can use finalizers to control {{<glossary_tooltip text="garbage collection" term_id="garbage-collection">}}
of resources. For example, you can define a finalizer to clean up related resources or
content/en/docs/reference/issues-security/security.md
-2
View File
@@ -19,8 +19,6 @@ This page describes Kubernetes security and disclosure information.
Join the [kubernetes-security-announce](https://groups.google.com/forum/#!forum/kubernetes-security-announce) group for emails about security and major API announcements.
You can also subscribe to an RSS feed of the above using [this link](https://groups.google.com/forum/feed/kubernetes-security-announce/msgs/rss_v2_0.xml?num=50).
## Report a Vulnerability
We're extremely grateful for security researchers and users that report vulnerabilities to the Kubernetes Open Source Community. All reports are thoroughly investigated by a set of community volunteers.
content/en/docs/reference/kubectl/cheatsheet.md
+6 -2
View File
@@ -73,6 +73,10 @@ kubectl config set-context gce --user=cluster-admin --namespace=foo \
&& kubectl config use-context gce
kubectl config unset users.foo # delete user foo
# short alias to set/show context/namespace (only works for bash and bash-compatible shells, current context to be set before using kn to set namespace)
alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'
```
## Kubectl apply
@@ -212,10 +216,10 @@ kubectl diff -f ./my-manifest.yaml
# Produce a period-delimited tree of all keys returned for nodes
# Helpful when locating a key within a complex nested JSON structure
kubectl get nodes -o json | jq -c 'path(..)|[.[]|tostring]|join(".")'
kubectl get nodes -o json | jq -c 'paths|join(".")'
# Produce a period-delimited tree of all keys returned for pods, etc
kubectl get pods -o json | jq -c 'path(..)|[.[]|tostring]|join(".")'
kubectl get pods -o json | jq -c 'paths|join(".")'
# Produce ENV for all pods, assuming you have a default container for the pods, default namespace and the `env` command is supported.
# Helpful when running any supported command across all pods, not just `env`
content/en/docs/reference/labels-annotations-taints.md
+16
View File
@@ -72,6 +72,22 @@ This annotation is a best guess at why something was changed.
It is populated when adding `--record` to a `kubectl` command that may change an object.
## kubernetes.io/description {#description}
Example: `kubernetes.io/description: "Description of K8s object."`
Used on: All Objects
This annotation is used for describing specific behaviour of given object.
## kubernetes.io/enforce-mountable-secrets {#enforce-mountable-secrets}
Example: `kubernetes.io/enforce-mountable-secrets: "true"`
Used on: ServiceAccount
The value for this annotation must be **true** to take effect. This annotation indicates that pods running as this service account may only reference Secret API objects specified in the service account's `secrets` field.
## controller.kubernetes.io/pod-deletion-cost {#pod-deletion-cost}
Example: `controller.kubernetes.io/pod-deletion-cost=10`
content/en/docs/reference/node/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: Node Reference Information
weight: 40
---
content/en/docs/reference/node/topics-on-dockershim-and-cri-compatible-runtimes.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Articles on dockershim Removal and on Using CRI-compatible Runtimes
content_type: reference
---
<!-- overview -->
This is a list of articles and other pages that are either
about the Kubernetes' deprecation and removal of _dockershim_,
or about using CRI-compatible container runtimes, in connection
with that removal.
<!-- body -->
## Kubernetes project
* Kubernetes blog: [Dockershim Removal FAQ](/blog/2022/02/17/dockershim-faq/) (originally published 2022/02/17)
* Kubernetes blog: [Kubernetes is Moving on From Dockershim: Commitments and Next Steps](/blog/2022/01/07/kubernetes-is-moving-on-from-dockershim/) (published 2022/01/07)
* Kubernetes blog: [Dockershim removal is coming. Are you ready?](/blog/2021/11/12/are-you-ready-for-dockershim-removal/) (published 2021/11/12)
* Kubernetes documentation: [Migrating from dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/)
* Kubernetes documentation: [Container runtimes](/docs/setup/production-environment/container-runtimes/)
* Kubernetes enhancement proposal: [KEP-2221: Removing dockershim from kubelet](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2221-remove-dockershim/README.md)
* Kubernetes enhancement proposal issue: [Removing dockershim from kubelet](https://github.com/kubernetes/enhancements/issues/2221) (_k/enhancements#2221_)
You can provide feedback via the GitHub issue [**Dockershim removal feedback & issues**](https://github.com/kubernetes/kubernetes/issues/106917).
## External sources {#third-party}
<!-- sort these alphabetically -->
* Amazon Web Services EKS documentation: [Dockershim deprecation](https://docs.aws.amazon.com/eks/latest/userguide/dockershim-deprecation.html)
* CNCF conference video: [Lessons Learned Migrating Kubernetes from Docker to containerd Runtime](https://www.youtube.com/watch?v=uDOu6rK4yOk) (Ana Caylin, at KubeCon Europe 2019)
* Docker.com blog: [What developers need to know about Docker, Docker Engine, and Kubernetes v1.20](https://www.docker.com/blog/what-developers-need-to-know-about-docker-docker-engine-and-kubernetes-v1-20/) (published 2020/12/04)
* "_Google Open Source_" channel on YouTube: [Learn Kubernetes with Google - Migrating from Dockershim to Containerd](https://youtu.be/fl7_4hjT52g)
* Microsoft Apps on Azure blog: [Dockershim deprecation and AKS](https://techcommunity.microsoft.com/t5/apps-on-azure-blog/dockershim-deprecation-and-aks/ba-p/3055902) (published 2022/01/21)
* Mirantis blog: [The Future of Dockershim is cri-dockerd](https://www.mirantis.com/blog/the-future-of-dockershim-is-cri-dockerd/) (published 2021/04/21)
* Mirantis: [Mirantis/cri-dockerd](https://github.com/Mirantis/cri-dockerd) Git repository (on GitHub)
* Tripwire: [How Dockershim’s Forthcoming Deprecation Affects Your Kubernetes](https://www.tripwire.com/state-of-security/security-data-protection/cloud/how-dockershim-forthcoming-deprecation-affects-your-kubernetes/)
content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md
+3
View File
@@ -6,6 +6,9 @@ weight: 90
`kubeadm kubeconfig` provides utilities for managing kubeconfig files.
For examples on how to use `kubeadm kubeconfig user` see
[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
## kubeadm kubeconfig {#cmd-kubeconfig}
{{< tabs name="tab-kubeconfig" >}}
content/en/docs/reference/using-api/api-concepts.md
+1 -1
View File
@@ -183,7 +183,7 @@ and starting the **watch** from the `resourceVersion` that was returned.
For subscribing to collections, Kubernetes client libraries typically offer some form
of standard tool for this **list**-then-**watch** logic. (In the Go client library,
this is called a `Reflector` and is located in the `k8s.io/client-go/cache` package.)
this is called a `Reflector` and is located in the `k8s.io/client-go/tools/cache` package.)
### Watch bookmarks
content/en/docs/setup/best-practices/enforcing-pod-security-standards.md
+2
View File
@@ -70,6 +70,8 @@ few different ways:
Other alternatives for enforcing security profiles are being developed in the Kubernetes
ecosystem:
- [Kubewarden](https://github.com/kubewarden).
- [Kyverno](https://kyverno.io/policies/).
- [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper).
The decision to go with a _built-in_ solution (e.g. PodSecurity admission controller) versus a
content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md
+11 -1
View File
@@ -210,7 +210,8 @@ export KUBECONFIG=/etc/kubernetes/admin.conf
Kubeadm signs the certificate in the `admin.conf` to have `Subject: O = system:masters, CN = kubernetes-admin`.
`system:masters` is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC).
Do not share the `admin.conf` file with anyone and instead grant users custom permissions by generating
them a kubeconfig file using the `kubeadm kubeconfig user` command.
them a kubeconfig file using the `kubeadm kubeconfig user` command. For more details see
[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
{{< /warning >}}
Make a record of the `kubeadm join` command that `kubeadm init` outputs. You
@@ -283,6 +284,15 @@ If your network is not working or CoreDNS is not in the `Running` state, check o
[troubleshooting guide](/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm/)
for `kubeadm`.
### Managed node labels
By default, kubeadm enables the [NodeRestriction](/docs/reference/access-authn-authz/admission-controllers/#noderestriction)
admission controller that restricts what labels can be self-applied by kubelets on node registration.
The admission controller documentation covers what labels are permitted to be used with the kubelet `--node-labels` option.
The `node-role.kubernetes.io/control-plane` label is such a restricted label and kubeadm manually applies it using
a privileged client after a node has been created. To do that manually you can do the same by using `kubectl label`
and ensure it is using a privileged kubeconfig such as the kubeadm managed `/etc/kubernetes/admin.conf`.
### Control plane node isolation
By default, your cluster will not schedule Pods on the control-plane node for security
content/en/docs/setup/production-environment/tools/kubeadm/install-kubeadm.md
+4
View File
@@ -217,6 +217,10 @@ sudo systemctl enable --now kubelet
- You can leave SELinux enabled if you know how to configure it but it may require settings that are not supported by kubeadm.
- If the `baseurl` fails because your Red Hat-based distribution cannot interpret `basearch`, replace `\$basearch` with your computer's architecture.
Type `uname -m` to see that value.
For example, the `baseurl` URL for `x86_64` could be: `https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64`.
{{% /tab %}}
{{% tab name="Without a package manager" %}}
Install CNI plugins (required for most pod network):
content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md
+13 -2
View File
@@ -265,9 +265,9 @@ with recommendations on when to use each CNI:
| -------------- | ----------- | ------------------------------ | --------------- | ------------------------------ |
| L2bridge | Containers are attached to an external vSwitch. Containers are attached to the underlay network, although the physical network doesn't need to learn the container MACs because they are rewritten on ingress/egress. | MAC is rewritten to host MAC, IP may be rewritten to host IP using HNS OutboundNAT policy. | [win-bridge](https://github.com/containernetworking/plugins/tree/master/plugins/main/windows/win-bridge), [Azure-CNI](https://github.com/Azure/azure-container-networking/blob/master/docs/cni.md), Flannel host-gateway uses win-bridge | win-bridge uses L2bridge network mode, connects containers to the underlay of hosts, offering best performance. Requires user-defined routes (UDR) for inter-node connectivity. |
| L2Tunnel | This is a special case of l2bridge, but only used on Azure. All packets are sent to the virtualization host where SDN policy is applied. | MAC rewritten, IP visible on the underlay network | [Azure-CNI](https://github.com/Azure/azure-container-networking/blob/master/docs/cni.md) | Azure-CNI allows integration of containers with Azure vNET, and allows them to leverage the set of capabilities that [Azure Virtual Network provides](https://azure.microsoft.com/en-us/services/virtual-network/). For example, securely connect to Azure services or use Azure NSGs. See [azure-cni for some examples](https://docs.microsoft.com/en-us/azure/aks/concepts-network#azure-cni-advanced-networking) |
| Overlay (Overlay networking for Windows in Kubernetes is in *alpha* stage) | Containers are given a vNIC connected to an external vSwitch. Each overlay network gets its own IP subnet, defined by a custom IP prefix.The overlay network driver uses VXLAN encapsulation. | Encapsulated with an outer header. | [Win-overlay](https://github.com/containernetworking/plugins/tree/master/plugins/main/windows/win-overlay), Flannel VXLAN (uses win-overlay) | win-overlay should be used when virtual container networks are desired to be isolated from underlay of hosts (e.g. for security reasons). Allows for IPs to be re-used for different overlay networks (which have different VNID tags) if you are restricted on IPs in your datacenter. This option requires [KB4489899](https://support.microsoft.com/help/4489899) on Windows Server 2019. |
| Overlay (Overlay networking for Windows in Kubernetes is in *alpha* stage) | Containers are given a vNIC connected to an external vSwitch. Each overlay network gets its own IP subnet, defined by a custom IP prefix.The overlay network driver uses VXLAN encapsulation. | Encapsulated with an outer header. | [win-overlay](https://github.com/containernetworking/plugins/tree/master/plugins/main/windows/win-overlay), Flannel VXLAN (uses win-overlay) | win-overlay should be used when virtual container networks are desired to be isolated from underlay of hosts (e.g. for security reasons). Allows for IPs to be re-used for different overlay networks (which have different VNID tags) if you are restricted on IPs in your datacenter. This option requires [KB4489899](https://support.microsoft.com/help/4489899) on Windows Server 2019. |
| Transparent (special use case for [ovn-kubernetes](https://github.com/openvswitch/ovn-kubernetes)) | Requires an external vSwitch. Containers are attached to an external vSwitch which enables intra-pod communication via logical networks (logical switches and routers). | Packet is encapsulated either via [GENEVE](https://datatracker.ietf.org/doc/draft-gross-geneve/) or [STT](https://datatracker.ietf.org/doc/draft-davie-stt/) tunneling to reach pods which are not on the same host. <br/> Packets are forwarded or dropped via the tunnel metadata information supplied by the ovn network controller. <br/> NAT is done for north-south communication. | [ovn-kubernetes](https://github.com/openvswitch/ovn-kubernetes) | [Deploy via ansible](https://github.com/openvswitch/ovn-kubernetes/tree/master/contrib). Distributed ACLs can be applied via Kubernetes policies. IPAM support. Load-balancing can be achieved without kube-proxy. NATing is done without using iptables/netsh. |
| NAT (*not used in Kubernetes*) | Containers are given a vNIC connected to an internal vSwitch. DNS/DHCP is provided using an internal component called [WinNAT](https://blogs.technet.microsoft.com/virtualization/2016/05/25/windows-nat-winnat-capabilities-and-limitations/) | MAC and IP is rewritten to host MAC/IP. | [nat](https://github.com/Microsoft/windows-container-networking/tree/master/plugins/nat) | Included here for completeness |
| NAT (*not used in Kubernetes*) | Containers are given a vNIC connected to an internal vSwitch. DNS/DHCP is provided using an internal component called [WinNAT](https://techcommunity.microsoft.com/t5/virtualization/windows-nat-winnat-capabilities-and-limitations/ba-p/382303) | MAC and IP is rewritten to host MAC/IP. | [nat](https://github.com/Microsoft/windows-container-networking/tree/master/plugins/nat) | Included here for completeness |
As outlined above, the [Flannel](https://github.com/coreos/flannel)
CNI [meta plugin](https://github.com/containernetworking/plugins/tree/master/plugins/meta/flannel)
@@ -327,6 +327,17 @@ In a cluster that includes Windows nodes, you can use the following types of Ser
* `LoadBalancer`
* `ExternalName`
{{< warning >}}
There are known issue with NodePort services on overlay networking, if the target destination node is running Windows Server 2022.
To avoid the issue entirely, you can configure the service with `externalTrafficPolicy: Local`.
There are known issues with pod to pod connectivity on l2bridge network on Windows Server 2022 with KB5005619 or higher installed.
To workaround the issue and restore pod-pod connectivity, you can disable the WinDSR feature in kube-proxy.
These issues require OS fixes.
Please follow https://github.com/microsoft/Windows-Containers/issues/204 for updates.
{{< /warning >}}
Windows container networking differs in some important ways from Linux networking.
The [Microsoft documentation for Windows Container Networking](https://docs.microsoft.com/en-us/virtualization/windowscontainers/container-networking/architecture) provides
additional details and background.
content/en/docs/tasks/access-application-cluster/access-cluster.md
+28 -5
View File
@@ -86,12 +86,36 @@ The output is similar to this:
### Without kubectl proxy
Use `kubectl describe secret...` to get the token for the default service account with grep/cut:
Use `kubectl apply` and `kubectl describe secret...` to create a token for the default service account with grep/cut:
First, create the Secret, requesting a token for the default ServiceAccount:
```shell
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: default-token
annotations:
kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF
```
Next, wait for the token controller to populate the Secret with a token:
```shell
while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do
echo "waiting for token..." >&2
sleep 1
done
```
Capture and use the generated token:
```shell
APISERVER=$(kubectl config view --minify | grep server | cut -f 2- -d ":" | tr -d " ")
SECRET_NAME=$(kubectl get secrets | grep ^default | cut -f1 -d ' ')
TOKEN=$(kubectl describe secret $SECRET_NAME | grep -E '^token' | cut -f2 -d':' | tr -d " ")
TOKEN=$(kubectl describe secret default-token | grep -E '^token' | cut -f2 -d':' | tr -d " ")
curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
```
@@ -117,8 +141,7 @@ Using `jsonpath`:
```shell
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
SECRET_NAME=$(kubectl get serviceaccount default -o jsonpath='{.secrets[0].name}')
TOKEN=$(kubectl get secret $SECRET_NAME -o jsonpath='{.data.token}' | base64 --decode)
TOKEN=$(kubectl get secret default-token -o jsonpath='{.data.token}' | base64 --decode)
curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
```
content/en/docs/tasks/access-application-cluster/web-ui-dashboard.md
+4 -2
View File
@@ -1,6 +1,8 @@
---
reviewers:
- bryk
- floreks
- maciaszczykm
- shu-mutou
- mikedanese
title: Deploy and Access the Kubernetes Dashboard
description: >-
@@ -35,7 +37,7 @@ Dashboard also provides information on the state of Kubernetes resources in your
The Dashboard UI is not deployed by default. To deploy it, run the following command:
```
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.4.0/aio/deploy/recommended.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.5.0/aio/deploy/recommended.yaml
```
## Accessing the Dashboard UI
content/en/docs/tasks/administer-cluster/access-cluster-api.md
+19 -22
View File
@@ -95,8 +95,25 @@ export CLUSTER_NAME="some_server_name"
# Point to the API server referring the cluster name
APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
# Gets the token value
TOKEN=$(kubectl get secrets -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='default')].data.token}"|base64 --decode)
# Create a secret to hold a token for the default service account
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: default-token
annotations:
kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF
# Wait for the token controller to populate the secret with a token:
while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do
echo "waiting for token..." >&2
sleep 1
done
# Get the token value
TOKEN=$(kubectl get secret default-token -o jsonpath='{.data.token}' | base64 --decode)
# Explore the API with TOKEN
curl -X GET $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
@@ -119,26 +136,6 @@ The output is similar to this:
}
```
Using `jsonpath` approach:
```shell
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
TOKEN=$(kubectl get secret $(kubectl get serviceaccount default -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.token}' | base64 --decode )
curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
{
"kind": "APIVersions",
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "10.0.1.149:443"
}
]
}
```
The above example uses the `--insecure` flag. This leaves it subject to MITM
attacks. When kubectl accesses the cluster it uses a stored root certificate
and client certificates to access the server. (These are installed in the
content/en/docs/tasks/administer-cluster/configure-upgrade-etcd.md
+9
View File
@@ -361,3 +361,12 @@ We also recommend restarting any components (e.g. `kube-scheduler`,
stale data. Note that in practice, the restore takes a bit of time. During the
restoration, critical components will lose leader lock and restart themselves.
{{< /note >}}
## Upgrading etcd clusters
For more details on etcd upgrade, please refer to the [etcd upgrades](https://etcd.io/docs/latest/upgrades/) documentation.
{{< note >}}
Before you start an upgrade, please back up your etcd cluster first.
{{< /note >}}
content/en/docs/tasks/administer-cluster/cpu-management-policies.md
+23 -1
View File
@@ -46,7 +46,8 @@ management policies to determine some placement preferences on the node.
### Configuration
The CPU Manager policy is set with the `--cpu-manager-policy` kubelet
option. There are two supported policies:
flag or the `cpuManagerPolicy` field in [KubeletConfiguration](/docs/reference/config-api/kubelet-config.v1beta1/).
There are two supported policies:
* [`none`](#none-policy): the default policy.
* [`static`](#static-policy): allows pods with certain resource characteristics to be
@@ -68,6 +69,27 @@ and `CPUManagerPolicyBetaOptions` feature gates. Diverging from the Kubernetes s
feature gates guard groups of options, because it would have been too cumbersome to add a feature
gate for each individual option.
### Changing the CPU Manager Policy
Since the CPU manger policy can only be applied when kubelet spawns new pods, simply changing from
"none" to "static" won't apply to existing pods. So in order to properly change the CPU manager
policy on a node, perform the following steps:
1. [Drain](/docs/tasks/administer-cluster/safely-drain-node) the node.
2. Stop kubelet.
3. Remove the old CPU manager state file. The path to this file is
`/var/lib/kubelet/cpu_manager_state` by default. This clears the state maintained by the
CPUManager so that the cpu-sets set up by the new policy won’t conflict with it.
4. Edit the kubelet configuration to change the CPU manager policy to the desired value.
5. Start kubelet.
Repeat this process for every node that needs its CPU manager policy changed. Skipping this
process will result in kubelet crashlooping with the following error:
```
could not restore state from checkpoint: configured policy "static" differs from state checkpoint policy "none", please drain this node and delete the CPU manager checkpoint file "/var/lib/kubelet/cpu_manager_state" before restarting Kubelet
```
### None policy
The `none` policy explicitly enables the existing default CPU
content/en/docs/tasks/administer-cluster/encrypt-data.md
+75 -53
View File
@@ -1,7 +1,7 @@
---
title: Encrypting Secret Data at Rest
reviewers:
- smarterclayton
title: Encrypting Secret Data at Rest
content_type: task
min-kubernetes-server-version: 1.13
---
@@ -9,27 +9,26 @@ min-kubernetes-server-version: 1.13
<!-- overview -->
This page shows how to enable and configure encryption of secret data at rest.
## {{% heading "prerequisites" %}}
* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
* etcd v3.0 or later is required
<!-- steps -->
## Configuration and determining whether encryption at rest is already enabled
The `kube-apiserver` process accepts an argument `--encryption-provider-config`
that controls how API data is encrypted in etcd. An example configuration
is provided below.
that controls how API data is encrypted in etcd.
The configuration is provided as an API named
[`EncryptionConfiguration`](/docs/reference/config-api/apiserver-encryption.v1/).
An example configuration is provided below.
{{< caution >}}
**IMPORTANT:** For multi-master configurations (with two or more control plane nodes) the encryption configuration file must be the same!
Otherwise, the kube-apiserver can't decrypt data stored inside the key-value store.
**IMPORTANT:** For high-availability configurations (with two or more control plane nodes), the
encryption configuration file must be the same! Otherwise, the `kube-apiserver` component cannot
decrypt data stored in the etcd.
{{< /caution >}}
## Understanding the encryption at rest configuration.
@@ -63,15 +62,20 @@ resources:
Each `resources` array item is a separate config and contains a complete configuration. The
`resources.resources` field is an array of Kubernetes resource names (`resource` or `resource.group`)
that should be encrypted. The `providers` array is an ordered list of the possible encryption
providers. Only one provider type may be specified per entry (`identity` or `aescbc` may be provided, but not both in the same item).
providers.
The first provider in the list is used to encrypt resources going into storage. When reading
resources from storage each provider that matches the stored data attempts to decrypt the data in
order. If no provider can read the stored data due to a mismatch in format or secret key, an error
Only one provider type may be specified per entry (`identity` or `aescbc` may be provided,
but not both in the same item).
The first provider in the list is used to encrypt resources written into the storage. When reading
resources from storage, each provider that matches the stored data attempts in order to decrypt the
data. If no provider can read the stored data due to a mismatch in format or secret key, an error
is returned which prevents clients from accessing that resource.
For more detailed information about the `EncryptionConfiguration` struct, please refer to the
[encryption configuration API](/docs/reference/config-api/apiserver-encryption.v1/).
{{< caution >}}
**IMPORTANT:** If any resource is not readable via the encryption config (because keys were changed),
If any resource is not readable via the encryption config (because keys were changed),
the only recourse is to delete that key from the underlying etcd directly. Calls that attempt to
read that resource will fail until it is deleted or a valid decryption key is provided.
{{< /caution >}}
@@ -90,15 +94,24 @@ Name | Encryption | Strength | Speed | Key Length | Other Considerations
Each provider supports multiple keys - the keys are tried in order for decryption, and if the provider
is the first provider, the first key is used for encryption.
__Storing the raw encryption key in the EncryptionConfig only moderately improves your security posture, compared to no encryption.
Please use `kms` provider for additional security.__ By default, the `identity` provider is used to protect secrets in etcd, which
provides no encryption. `EncryptionConfiguration` was introduced to encrypt secrets locally, with a locally managed key.
Encrypting secrets with a locally managed key protects against an etcd compromise, but it fails to protect against a host compromise.
Since the encryption keys are stored on the host in the EncryptionConfig YAML file, a skilled attacker can access that file and
extract the encryption keys.
{{< caution >}}
Storing the raw encryption key in the EncryptionConfig only moderately improves your security
posture, compared to no encryption. Please use `kms` provider for additional security.
{{< /caution >}}
Envelope encryption creates dependence on a separate key, not stored in Kubernetes. In this case, an attacker would need to compromise etcd, the kubeapi-server, and the third-party KMS provider to retrieve the plaintext values, providing a higher level of security than locally-stored encryption keys.
By default, the `identity` provider is used to protect Secrets in etcd, which provides no
encryption. `EncryptionConfiguration` was introduced to encrypt Secrets locally, with a locally
managed key.
Encrypting Secrets with a locally managed key protects against an etcd compromise, but it fails to
protect against a host compromise. Since the encryption keys are stored on the host in the
EncryptionConfiguration YAML file, a skilled attacker can access that file and extract the encryption
keys.
Envelope encryption creates dependence on a separate key, not stored in Kubernetes. In this case,
an attacker would need to compromise etcd, the `kubeapi-server`, and the third-party KMS provider to
retrieve the plaintext values, providing a higher level of security than locally stored encryption keys.
## Encrypting your data
@@ -118,87 +131,90 @@ resources:
- identity: {}
```
To create a new secret perform the following steps:
To create a new Secret, perform the following steps:
1. Generate a 32 byte random key and base64 encode it. If you're on Linux or macOS, run the following command:
1. Generate a 32-byte random key and base64 encode it. If you're on Linux or macOS, run the following command:
```shell
head -c 32 /dev/urandom | base64
```
2. Place that value in the secret field.
3. Set the `--encryption-provider-config` flag on the `kube-apiserver` to point to the location of the config file.
4. Restart your API server.
1. Place that value in the `secret` field of the `EncryptionConfiguration` struct.
1. Set the `--encryption-provider-config` flag on the `kube-apiserver` to point to
the location of the config file.
1. Restart your API server.
{{< caution >}}
Your config file contains keys that can decrypt content in etcd, so you must properly restrict permissions on your masters so only the user who runs the kube-apiserver can read it.
Your config file contains keys that can decrypt the contents in etcd, so you must properly restrict
permissions on your control-plane nodes so only the user who runs the `kube-apiserver` can read it.
{{< /caution >}}
## Verifying that data is encrypted
Data is encrypted when written to etcd. After restarting your `kube-apiserver`, any newly created or
updated secret should be encrypted when stored. To check, you can use the `etcdctl` command line
program to retrieve the contents of your secret.
updated Secret should be encrypted when stored. To check this, you can use the `etcdctl` command line
program to retrieve the contents of your Secret.
1. Create a new secret called `secret1` in the `default` namespace:
1. Create a new Secret called `secret1` in the `default` namespace:
```shell
kubectl create secret generic secret1 -n default --from-literal=mykey=mydata
```
2. Using the etcdctl commandline, read that secret out of etcd:
1. Using the `etcdctl` command line, read that Secret out of etcd:
`ETCDCTL_API=3 etcdctl get /registry/secrets/default/secret1 [...] | hexdump -C`
where `[...]` must be the additional arguments for connecting to the etcd server.
3. Verify the stored secret is prefixed with `k8s:enc:aescbc:v1:` which indicates the `aescbc` provider has encrypted the resulting data.
1. Verify the stored Secret is prefixed with `k8s:enc:aescbc:v1:` which indicates
the `aescbc` provider has encrypted the resulting data.
4. Verify the secret is correctly decrypted when retrieved via the API:
1. Verify the Secret is correctly decrypted when retrieved via the API:
```shell
kubectl describe secret secret1 -n default
```
should match `mykey: bXlkYXRh`, mydata is encoded, check [decoding a secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret) to
completely decode the secret.
The output should contain `mykey: bXlkYXRh`, with contents of `mydata` encoded, check
[decoding a Secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret)
to completely decode the Secret.
## Ensure all Secrets are encrypted
## Ensure all secrets are encrypted
Since secrets are encrypted on write, performing an update on a secret will encrypt that content.
Since Secrets are encrypted on write, performing an update on a Secret will encrypt that content.
```shell
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
The command above reads all secrets and then updates them to apply server side encryption.
The command above reads all Secrets and then updates them to apply server side encryption.
{{< note >}}
If an error occurs due to a conflicting write, retry the command.
For larger clusters, you may wish to subdivide the secrets by namespace or script an update.
{{< /note >}}
## Rotating a decryption key
Changing the secret without incurring downtime requires a multi step operation, especially in
the presence of a highly available deployment where multiple `kube-apiserver` processes are running.
Changing a Secret without incurring downtime requires a multi-step operation, especially in
the presence of a highly-available deployment where multiple `kube-apiserver` processes are running.
1. Generate a new key and add it as the second key entry for the current provider on all servers
2. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key
3. Make the new key the first entry in the `keys` array so that it is used for encryption in the config
4. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key
5. Run `kubectl get secrets --all-namespaces -o json | kubectl replace -f -` to encrypt all existing secrets with the new key
6. Remove the old decryption key from the config after you back up etcd with the new key in use and update all secrets
With a single `kube-apiserver`, step 2 may be skipped.
1. Restart all `kube-apiserver` processes to ensure each server can decrypt using the new key
1. Make the new key the first entry in the `keys` array so that it is used for encryption in the config
1. Restart all `kube-apiserver` processes to ensure each server now encrypts using the new key
1. Run `kubectl get secrets --all-namespaces -o json | kubectl replace -f -` to encrypt all
existing Secrets with the new key
1. Remove the old decryption key from the config after you have backed up etcd with the new key in use
and updated all Secrets
When running a single `kube-apiserver` instance, step 2 may be skipped.
## Decrypting all data
To disable encryption at rest place the `identity` provider as the first entry in the config:
To disable encryption at rest, place the `identity` provider as the first entry in the config
and restart all `kube-apiserver` processes.
```yaml
apiVersion: apiserver.config.k8s.io/v1
@@ -214,8 +230,14 @@ resources:
secret: <BASE 64 ENCODED SECRET>
```
and restart all `kube-apiserver` processes. Then run:
Then run the following command to force decrypt
all Secrets:
```shell
kubectl get secrets --all-namespaces -o json | kubectl replace -f -
```
to force all secrets to be decrypted.
## {{% heading "whatsnext" %}}
* Learn more about the [EncryptionConfiguration configuration API (v1)](/docs/reference/config-api/apiserver-encryption.v1/).
content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md
+52 -1
View File
@@ -10,7 +10,9 @@ weight: 10
{{< feature-state for_k8s_version="v1.15" state="stable" >}}
Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/) expire after 1 year. This page explains how to manage certificate renewals with kubeadm.
Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/) expire after 1 year.
This page explains how to manage certificate renewals with kubeadm. It also covers other tasks related
to kubeadm certificate management.
## {{% heading "prerequisites" %}}
@@ -289,3 +291,52 @@ Such a controller is not a secure mechanism unless it not only verifies the Comm
in the CSR but also verifies the requested IPs and domain names. This would prevent
a malicious actor that has access to a kubelet client certificate to create
CSRs requesting serving certificates for any IP or domain name.
## Generating kubeconfig files for additional users {#kubeconfig-additional-users}
During cluster creation, kubeadm signs the certificate in the `admin.conf` to have
`Subject: O = system:masters, CN = kubernetes-admin`.
[`system:masters`](/docs/reference/access-authn-authz/rbac/#user-facing-roles)
is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC).
Sharing the `admin.conf` with additional users is **not recommended**!
Instead, you can use the [`kubeadm kubeconfig user`](/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig)
command to generate kubeconfig files for additional users.
The command accepts a mixture of command line flags and
[kubeadm configuration](/docs/reference/config-api/kubeadm-config.v1beta3/) options.
The generated kubeconfig will be written to stdout and can be piped to a file
using `kubeadm kubeconfig user ... > somefile.conf`.
Example configuration file that can be used with `--config`:
```yaml
# example.yaml
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
# Will be used as the target "cluster" in the kubeconfig
clusterName: "kubernetes"
# Will be used as the "server" (IP or DNS name) of this cluster in the kubeconfig
controlPlaneEndpoint: "some-dns-address:6443"
# The cluster CA key and certificate will be loaded from this local directory
certificatesDir: "/etc/kubernetes/pki"
```
Make sure that these settings match the desired target cluster settings.
To see the settings of an existing cluster use:
```shell
kubectl get cm kubeadm-config -n kube-system -o=jsonpath="{.data.ClusterConfiguration}"
```
The following example will generate a kubeconfig file with credentials valid for 24 hours
for a new user `johndoe` that is part of the `appdevs` group:
```shell
kubeadm kubeconfig user --config example.yaml --org appdevs --client-name johndoe --validity-period 24h
```
The following example will generate a kubeconfig file with administrator credentials valid for 1 week:
```shell
kubeadm kubeconfig user --config example.yaml --client-name admin --validity-period 168h
```
content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
+1 -1
View File
@@ -170,7 +170,7 @@ kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-3.ya
```
The output shows that the Pod does not get created, because it defines an unacceptable container.
That container is not acceptable because it specifies a CPU limit that is lower than the
That container is not acceptable because it specifies a CPU request that is lower than the
enforced minimum:
```
content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
+3 -3
View File
@@ -13,10 +13,10 @@ This page shows how to configure default memory requests and limits for a
{{< glossary_tooltip text="namespace" term_id="namespace" >}}.
A Kubernetes cluster can be divided into namespaces. Once you have a namespace that
that has a default memory
has a default memory
[limit](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits),
and you then try to create a Pod with a container that does not specify its own memory
limit its own memory limit, then the
limit, then the
{{< glossary_tooltip text="control plane" term_id="control-plane" >}} assigns the default
memory limit to that container.
@@ -177,7 +177,7 @@ Here are two of the restrictions that a resource quota imposes on a namespace:
* For every Pod that runs in the namespace, the Pod and each of its containers must have a memory limit.
(If you specify a memory limit for every container in a Pod, Kubernetes can infer the Pod-level memory
limit by adding up the limits for its containers).
* CPU limits apply a resource reservation on the node where the Pod in question is scheduled.
* Memory limits apply a resource reservation on the node where the Pod in question is scheduled.
The total amount of memory reserved for all Pods in the namespace must not exceed a specified limit.
* The total amount of memory actually used by all Pods in the namespace must also not exceed a specified limit.
content/en/docs/tasks/administer-cluster/memory-manager.md
+7 -2
View File
@@ -138,7 +138,8 @@ The sum of their values will account for the total amount of reserved memory.
A new `--reserved-memory` flag was added to Memory Manager to allow for this total reserved memory
to be split (by a node administrator) and accordingly reserved across many NUMA nodes.
The flag specifies a comma-separated list of memory reservations per NUMA node.
The flag specifies a comma-separated list of memory reservations of different memory types per NUMA node.
Memory reservations across multiple NUMA nodes can be specified using semicolon as separator.
This parameter is only useful in the context of the Memory Manager feature.
The Memory Manager will not use this reserved memory for the allocation of container workloads.
@@ -180,6 +181,10 @@ or
`--reserved-memory 0:memory=1Gi --reserved-memory 1:memory=2Gi`
or
`--reserved-memory '0:memory=1Gi;1:memory=2Gi'`
When you specify values for `--reserved-memory` flag, you must comply with the setting that
you prior provided via Node Allocatable Feature flags.
That is, the following rule must be obeyed for each memory type:
@@ -215,7 +220,7 @@ Here is an example of a correct configuration:
--kube-reserved=cpu=4,memory=4Gi
--system-reserved=cpu=1,memory=1Gi
--memory-manager-policy=Static
--reserved-memory 0:memory=3Gi --reserved-memory 1:memory=2148Mi
--reserved-memory '0:memory=3Gi;1:memory=2148Mi'
```
Let us validate the configuration above:
content/en/docs/tasks/administer-cluster/migrating-from-dockershim/_index.md
+2 -1
View File
@@ -11,7 +11,8 @@ dockershim to other container runtimes.
Since the announcement of [dockershim deprecation](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)
in Kubernetes 1.20, there were questions on how this will affect various workloads and Kubernetes
installations. You can find this blog post useful to understand the problem better: [Dockershim Deprecation FAQ](/blog/2020/12/02/dockershim-faq/)
installations. Our [Dockershim Removal FAQ](/blog/2022/02/17/dockershim-faq/) is there to help you
to understand the problem better.
It is recommended to migrate from dockershim to alternative container runtimes.
Check out [container runtimes](/docs/setup/production-environment/container-runtimes/)
content/en/docs/tasks/administer-cluster/migrating-from-dockershim/change-runtime-containerd.md
+154
View File
@@ -0,0 +1,154 @@
---
title: "Changing the Container Runtime on a Node from Docker Engine to containerd"
weight: 8
content_type: task
---
This task outlines the steps needed to update your container runtime to containerd from Docker. It is applicable for cluster operators running Kubernetes 1.23 or earlier. Also this covers an example scenario for migrating from dockershim to containerd and alternative container runtimes can be picked from this [page](https://kubernetes.io/docs/setup/production-environment/container-runtimes/).
## {{% heading "prerequisites" %}}
{{% thirdparty-content %}}
Install containerd. For more information see, [containerd's installation documentation](https://containerd.io/docs/getting-started/) and for specific prerequisite follow [this](/docs/setup/production-environment/container-runtimes/#containerd).
## Drain the node
```
# replace <node-to-drain> with the name of your node you are draining
kubectl drain <node-to-drain> --ignore-daemonsets
```
## Stop the Docker daemon
```shell
systemctl stop kubelet
systemctl disable docker.service --now
```
## Install Containerd
This [page](/docs/setup/production-environment/container-runtimes/#containerd) contains detailed steps to install containerd.
{{< tabs name="tab-cri-containerd-installation" >}}
{{% tab name="Linux" %}}
1. Install the `containerd.io` package from the official Docker repositories.
Instructions for setting up the Docker repository for your respective Linux distribution and installing the `containerd.io` package can be found at
[Install Docker Engine](https://docs.docker.com/engine/install/#server).
2. Configure containerd:
```shell
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
```
3. Restart containerd:
```shell
sudo systemctl restart containerd
```
{{% /tab %}}
{{% tab name="Windows (PowerShell)" %}}
Start a Powershell session, set `$Version` to the desired version (ex: `$Version="1.4.3"`), and then run the following commands:
1. Download containerd:
```powershell
curl.exe -L https://github.com/containerd/containerd/releases/download/v$Version/containerd-$Version-windows-amd64.tar.gz -o containerd-windows-amd64.tar.gz
tar.exe xvf .\containerd-windows-amd64.tar.gz
```
2. Extract and configure:
```powershell
Copy-Item -Path ".\bin\" -Destination "$Env:ProgramFiles\containerd" -Recurse -Force
cd $Env:ProgramFiles\containerd\
.\containerd.exe config default | Out-File config.toml -Encoding ascii
# Review the configuration. Depending on setup you may want to adjust:
# - the sandbox_image (Kubernetes pause image)
# - cni bin_dir and conf_dir locations
Get-Content config.toml
# (Optional - but highly recommended) Exclude containerd from Windows Defender Scans
Add-MpPreference -ExclusionProcess "$Env:ProgramFiles\containerd\containerd.exe"
```
3. Start containerd:
```powershell
.\containerd.exe --register-service
Start-Service containerd
```
{{% /tab %}}
{{< /tabs >}}
## Configure the kubelet to use containerd as its container runtime
Edit the file `/var/lib/kubelet/kubeadm-flags.env` and add the containerd runtime to the flags. `--container-runtime=remote` and `--container-runtime-endpoint=unix:///run/containerd/containerd.sock"`
For users using kubeadm should consider the following:
The `kubeadm` tool stores the CRI socket for each host as an annotation in the Node object for that host.
To change it you must do the following:
Execute `kubectl edit no <NODE-NAME>` on a machine that has the kubeadm `/etc/kubernetes/admin.conf` file.
This will start a text editor where you can edit the Node object.
To choose a text editor you can set the `KUBE_EDITOR` environment variable.
- Change the value of `kubeadm.alpha.kubernetes.io/cri-socket` from `/var/run/dockershim.sock`
to the CRI socket path of your choice (for example `unix:///run/containerd/containerd.sock`).
Note that new CRI socket paths must be prefixed with `unix://` ideally.
- Save the changes in the text editor, which will update the Node object.
## Restart the kubelet
```shell
systemctl start kubelet
```
## Verify that the node is healthy
Run `kubectl get nodes -o wide` and containerd appears as the runtime for the node we just changed.
## Remove Docker Engine
{{% thirdparty-content %}}
Finally if everything goes well remove docker
{{< tabs name="tab-remove-docker-enigine" >}}
{{% tab name="CentOS" %}}
```shell
sudo yum remove docker-ce docker-ce-cli
```
{{% /tab %}}
{{% tab name="Debian" %}}
```shell
sudo apt-get purge docker-ce docker-ce-cli
```
{{% /tab %}}
{{% tab name="Fedora" %}}
```shell
sudo dnf remove docker-ce docker-ce-cli
```
{{% /tab %}}
{{% tab name="Ubuntu" %}}
```shell
sudo apt-get purge docker-ce docker-ce-cli
```
{{% /tab %}}
{{< /tabs >}}
content/en/docs/tasks/administer-cluster/safely-drain-node.md
+3 -88
View File
@@ -23,8 +23,6 @@ This task also assumes that you have met the following prerequisites:
and have [configured PodDisruptionBudgets](/docs/tasks/run-application/configure-pdb/) for
applications that need them.
<!-- steps -->
## (Optional) Configure a disruption budget {#configure-poddisruptionbudget}
@@ -100,95 +98,12 @@ replicas to fall below the specified budget are blocked.
If you prefer not to use [kubectl drain](/docs/reference/generated/kubectl/kubectl-commands/#drain) (such as
to avoid calling to an external command, or to get finer control over the pod
eviction process), you can also programmatically cause evictions using the eviction API.
eviction process), you can also programmatically cause evictions using the
eviction API.
You should first be familiar with using [Kubernetes language clients](/docs/tasks/administer-cluster/access-cluster-api/#programmatic-access-to-the-api) to access the API.
The eviction subresource of a
Pod can be thought of as a kind of policy-controlled DELETE operation on the Pod
itself. To attempt an eviction (more precisely: to attempt to
*create* an Eviction), you POST an attempted operation. Here's an example:
{{< tabs name="Eviction_example" >}}
{{% tab name="policy/v1" %}}
{{< note >}}
`policy/v1` Eviction is available in v1.22+. Use `policy/v1beta1` with prior releases.
{{< /note >}}
```json
{
"apiVersion": "policy/v1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
{{% /tab %}}
{{% tab name="policy/v1beta1" %}}
{{< note >}}
Deprecated in v1.22 in favor of `policy/v1`
{{< /note >}}
```json
{
"apiVersion": "policy/v1beta1",
"kind": "Eviction",
"metadata": {
"name": "quux",
"namespace": "default"
}
}
```
{{% /tab %}}
{{< /tabs >}}
You can attempt an eviction using `curl`:
```bash
curl -v -H 'Content-type: application/json' https://your-cluster-api-endpoint.example/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json
```
The API can respond in one of three ways:
- If the eviction is granted, then the Pod is deleted as if you sent
a `DELETE` request to the Pod's URL and received back `200 OK`.
- If the current state of affairs wouldn't allow an eviction by the rules set
forth in the budget, you get back `429 Too Many Requests`. This is
typically used for generic rate limiting of *any* requests, but here we mean
that this request isn't allowed *right now* but it may be allowed later.
- If there is some kind of misconfiguration; for example multiple PodDisruptionBudgets
that refer the same Pod, you get a `500 Internal Server Error` response.
For a given eviction request, there are two cases:
- There is no budget that matches this pod. In this case, the server always
returns `200 OK`.
- There is at least one budget. In this case, any of the three above responses may
apply.
## Stuck evictions
In some cases, an application may reach a broken state, one where unless you intervene the
eviction API will never return anything other than 429 or 500.
For example: this can happen if ReplicaSet is creating Pods for your application but
the replacement Pods do not become `Ready`. You can also see similar symptoms if the
last Pod evicted has a very long termination grace period.
In this case, there are two potential solutions:
- Abort or pause the automated operation. Investigate the reason for the stuck application,
and restart the automation.
- After a suitably long wait, `DELETE` the Pod from your cluster's control plane, instead
of using the eviction API.
Kubernetes does not specify what the behavior should be in this case; it is up to the
application owners and cluster owners to establish an agreement on behavior in these cases.
For more information, see [API-initiated eviction](/docs/concepts/scheduling-eviction/api-eviction/).
## {{% heading "whatsnext" %}}
* Follow steps to protect your application by [configuring a Pod Disruption Budget](/docs/tasks/run-application/configure-pdb/).
content/en/docs/tasks/administer-cluster/sysctl-cluster.md
+1 -1
View File
@@ -70,7 +70,7 @@ The following sysctls are supported in the _safe_ set:
- `kernel.shm_rmid_forced`,
- `net.ipv4.ip_local_port_range`,
- `net.ipv4.tcp_syncookies`,
- `net.ipv4.ping_group_range` (since Kubernetes 1.18).
- `net.ipv4.ping_group_range` (since Kubernetes 1.18),
- `net.ipv4.ip_unprivileged_port_start` (since Kubernetes 1.22).
{{< note >}}
content/en/docs/tasks/administer-cluster/use-cascading-deletion.md
+5 -4
View File
@@ -5,7 +5,8 @@ content_type: task
<!--overview-->
This page shows you how to specify the type of [cascading deletion](/docs/concepts/workloads/controllers/garbage-collection/#cascading-deletion)
This page shows you how to specify the type of
[cascading deletion](/docs/concepts/architecture/garbage-collection/#cascading-deletion)
to use in your cluster during {{<glossary_tooltip text="garbage collection" term_id="garbage-collection">}}.
## {{% heading "prerequisites" %}}
@@ -26,7 +27,7 @@ kubectl get pods -l app=nginx --output=yaml
The output has an `ownerReferences` field similar to this:
```
```yaml
apiVersion: v1
...
ownerReferences:
@@ -41,7 +42,7 @@ apiVersion: v1
## Use foreground cascading deletion {#use-foreground-cascading-deletion}
By default, Kubernetes uses [background cascading deletion](/docs/concepts/workloads/controllers/garbage-collection/#background-deletion)
By default, Kubernetes uses [background cascading deletion](/docs/concepts/architecture/garbage-collection/#background-deletion)
to delete dependents of an object. You can switch to foreground cascading deletion
using either `kubectl` or the Kubernetes API, depending on the Kubernetes
version your cluster runs. {{<version-check>}}
@@ -349,4 +350,4 @@ kubectl get pods -l app=nginx
* Learn about [owners and dependents](/docs/concepts/overview/working-with-objects/owners-dependents/) in Kubernetes.
* Learn about Kubernetes [finalizers](/docs/concepts/overview/working-with-objects/finalizers/).
* Learn about [garbage collection](/docs/concepts/workloads/controllers/garbage-collection/).
* Learn about [garbage collection](/docs/concepts/architecture/garbage-collection/).

Some files were not shown because too many files have changed in this diff Show More