diff --git a/Dockerfile b/Dockerfile index 93c73d218c..9e9a6d65b0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,29 +4,42 @@ # change is that the Hugo version is now an overridable argument rather than a fixed # environment variable. -FROM golang:1.15-alpine +FROM golang:1.16-alpine LABEL maintainer="Luc Perkins " RUN apk add --no-cache \ curl \ - git \ - openssh-client \ - rsync \ + gcc \ + g++ \ + musl-dev \ build-base \ - libc6-compat \ - npm && \ - npm install -D autoprefixer postcss-cli + libc6-compat ARG HUGO_VERSION +RUN mkdir $HOME/src && \ + cd $HOME/src && \ + curl -L https://github.com/gohugoio/hugo/archive/refs/tags/v${HUGO_VERSION}.tar.gz | tar -xz && \ + cd "hugo-${HUGO_VERSION}" && \ + go install --tags extended + +FROM golang:1.16-alpine + +RUN apk add --no-cache \ + git \ + openssh-client \ + rsync \ + npm && \ + npm install -D autoprefixer postcss-cli + RUN mkdir -p /usr/local/src && \ cd /usr/local/src && \ - curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz | tar -xz && \ - mv hugo /usr/local/bin/hugo && \ addgroup -Sg 1000 hugo && \ adduser -Sg hugo -u 1000 -h /src hugo +COPY --from=0 /go/bin/hugo /usr/local/bin/hugo + WORKDIR /src USER hugo:hugo diff --git a/OWNERS_ALIASES b/OWNERS_ALIASES index 72adfa668d..a98ae58b6f 100644 --- a/OWNERS_ALIASES +++ b/OWNERS_ALIASES @@ -24,12 +24,14 @@ aliases: - jimangel - jlbutler - kbhawkey + - natalisucks - onlydole - pi-victor - reylejano - savitharaghunathan - sftim - tengqm + - zacharysarah sig-docs-en-reviews: # PR reviews for English content - bradtopol - celestehorgan @@ -38,11 +40,13 @@ aliases: - jimangel - kbhawkey - mehabhalodiya + - natalisucks - onlydole - rajeshdeshpande02 - sftim - shannonxtreme - tengqm + - zacharysarah sig-docs-es-owners: # Admins for Spanish content - raelga - electrocucaracha diff --git a/README.md b/README.md index 87dd03e7eb..005452ef06 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,14 @@ For more information about contributing to the Kubernetes documentation, see: - [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) - [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/) +### New contributor ambassadors + +If you need help at any point when contributing, the [New Contributor Ambassadors](https://kubernetes.io/docs/contribute/advanced/#serve-as-a-new-contributor-ambassador) are a good point of contact. These are SIG Docs approvers whose responsibilities include mentoring new contributors and helping them through their first few pull requests. The best place to contact the New Contributors Ambassadors would be on the [Kubernetes Slack](https://slack.k8s.io/). Current New Contributors Ambassadors for SIG Docs: + +| Name | Slack | GitHub | +| -------------------------- | -------------------------- | -------------------------- | +| Arsh Sharma | @arsh | @RinkiyaKeDad | + ## Localization `README.md`'s | Language | Language | diff --git a/assets/scss/_custom.scss b/assets/scss/_custom.scss index d46bac0924..1ebe8c81fa 100644 --- a/assets/scss/_custom.scss +++ b/assets/scss/_custom.scss @@ -566,7 +566,8 @@ main.content { } } -/* COMMUNITY */ +/* COMMUNITY legacy styles */ +/* Leave these in place until localizations are caught up */ .newcommunitywrapper { .news { diff --git a/content/en/blog/_posts/2015-04-00-Faster-Than-Speeding-Latte.md b/content/en/blog/_posts/2015-04-00-Faster-Than-Speeding-Latte.md index fd6118b1c5..90a11d2582 100644 --- a/content/en/blog/_posts/2015-04-00-Faster-Than-Speeding-Latte.md +++ b/content/en/blog/_posts/2015-04-00-Faster-Than-Speeding-Latte.md @@ -1,8 +1,11 @@ --- -title: " Faster than a speeding Latte " +title: "Faster than a speeding Latte" date: 2015-04-06 slug: faster-than-speeding-latte url: /blog/2015/04/Faster-Than-Speeding-Latte +evergreen: true --- + Check out Brendan Burns racing Kubernetes. -[![Check out Brendan Burns racing Kubernetes](https://img.youtube.com/vi/7vZ9dRKRMyc/0.jpg)](https://www.youtube.com/watch?v=?7vZ9dRKRMyc) + +{{< youtube id="7vZ9dRKRMyc" title="Latte vs. Kubernetes setup - which is faster?">}} diff --git a/content/en/blog/_posts/2019-02-11-runc-CVE-2019-5736.md b/content/en/blog/_posts/2019-02-11-runc-CVE-2019-5736.md index 84482daf79..027cc2e9bf 100644 --- a/content/en/blog/_posts/2019-02-11-runc-CVE-2019-5736.md +++ b/content/en/blog/_posts/2019-02-11-runc-CVE-2019-5736.md @@ -1,17 +1,20 @@ --- title: Runc and CVE-2019-5736 date: 2019-02-11 +evergreen: false # mentions PodSecurityPolicy --- +Authors: Kubernetes Product Security Committee + This morning [a container escape vulnerability in runc was announced](https://www.openwall.com/lists/oss-security/2019/02/11/2). We wanted to provide some guidance to Kubernetes users to ensure everyone is safe and secure. -## What Is Runc? +## What is runc? Very briefly, runc is the low-level tool which does the heavy lifting of spawning a Linux container. Other tools like Docker, Containerd, and CRI-O sit on top of runc to deal with things like data formatting and serialization, but runc is at the heart of all of these systems. Kubernetes in turn sits on top of those tools, and so while no part of Kubernetes itself is vulnerable, most Kubernetes installations are using runc under the hood. -### What Is The Vulnerability? +### What is the vulnerability? While full details are still embargoed to give people time to patch, the rough version is that when running a process as root (UID 0) inside a container, that process can exploit a bug in runc to gain root privileges on the host running the container. This then allows them unlimited access to the server as well as any other containers on that server. @@ -19,13 +22,14 @@ If the process inside the container is either trusted (something you know is not The most common source of risk is attacker-controller container images, such as unvetted images from public repositories. -### What Should I Do? +### What should i do? As with all security issues, the two main options are to mitigate the vulnerability or upgrade your version of runc to one that includes the fix. As the exploit requires UID 0 within the container, a direct mitigation is to ensure all your containers are running as a non-0 user. This can be set within the container image, or via your pod specification: ```yaml +--- apiVersion: v1 kind: Pod metadata: @@ -39,6 +43,7 @@ spec: This can also be enforced globally using a PodSecurityPolicy: ```yaml +--- apiVersion: policy/v1beta1 kind: PodSecurityPolicy metadata: @@ -89,7 +94,7 @@ We don't have specific confirmation that Docker for Mac and Docker for Windows a If you are unable to upgrade Docker, the Rancher team has provided backports of the fix for many older versions at [github.com/rancher/runc-cve](https://github.com/rancher/runc-cve). -## Getting More Information +## Getting more information If you have any further questions about how this vulnerability impacts Kubernetes, please join us at [discuss.kubernetes.io](https://discuss.kubernetes.io/). diff --git a/content/en/blog/_posts/2021-04-22-gateway-api/index.md b/content/en/blog/_posts/2021-04-22-gateway-api/index.md index d9c798a5b1..c22d45cdbb 100644 --- a/content/en/blog/_posts/2021-04-22-gateway-api/index.md +++ b/content/en/blog/_posts/2021-04-22-gateway-api/index.md @@ -30,15 +30,15 @@ This led to design principles that allow the Gateway API to improve upon Ingress The Gateway API introduces a few new resource types: -- **[GatewayClasses](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.GatewayClass)** are cluster-scoped resources that act as templates to explicitly define behavior for Gateways derived from them. This is similar in concept to StorageClasses, but for networking data-planes. -- **[Gateways](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.Gateway)** are the deployed instances of GatewayClasses. They are the logical representation of the data-plane which performs routing, which may be in-cluster proxies, hardware LBs, or cloud LBs. -- **Routes** are not a single resource, but represent many different protocol-specific Route resources. The [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.HTTPRoute) has matching, filtering, and routing rules that get applied to Gateways that can process HTTP and HTTPS traffic. Similarly, there are [TCPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.TCPRoute), [UDPRoutes](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.UDPRoute), and [TLSRoutes](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha1.TLSRoute) which also have protocol-specific semantics. This model also allows the Gateway API to incrementally expand its protocol support in the future. +- **[GatewayClasses](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.GatewayClass)** are cluster-scoped resources that act as templates to explicitly define behavior for Gateways derived from them. This is similar in concept to StorageClasses, but for networking data-planes. +- **[Gateways](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.Gateway)** are the deployed instances of GatewayClasses. They are the logical representation of the data-plane which performs routing, which may be in-cluster proxies, hardware LBs, or cloud LBs. +- **Routes** are not a single resource, but represent many different protocol-specific Route resources. The [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.HTTPRoute) has matching, filtering, and routing rules that get applied to Gateways that can process HTTP and HTTPS traffic. Similarly, there are [TCPRoutes](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.TCPRoute), [UDPRoutes](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.UDPRoute), and [TLSRoutes](https://gateway-api.sigs.k8s.io/v1alpha1/references/spec/#networking.x-k8s.io/v1alpha1.TLSRoute) which also have protocol-specific semantics. This model also allows the Gateway API to incrementally expand its protocol support in the future. ![The resources of the Gateway API](gateway-api-resources.png) ### Gateway Controller Implementations -The good news is that although Gateway is in [Alpha](https://github.com/kubernetes-sigs/gateway-api/releases), there are already several [Gateway controller implementations](https://gateway-api.sigs.k8s.io/references/implementations/) that you can run. Since it’s a standardized spec, the following example could be run on any of them and should function the exact same way. Check out [getting started](https://gateway-api.sigs.k8s.io/guides/getting-started/) to see how to install and use one of these Gateway controllers. +The good news is that although Gateway is in [Alpha](https://github.com/kubernetes-sigs/gateway-api/releases), there are already several [Gateway controller implementations](https://gateway-api.sigs.k8s.io/implementations/) that you can run. Since it’s a standardized spec, the following example could be run on any of them and should function the exact same way. Check out [getting started](https://gateway-api.sigs.k8s.io/v1alpha1/guides/getting-started/) to see how to install and use one of these Gateway controllers. ## Getting Hands-on with the Gateway API @@ -134,7 +134,7 @@ spec: So we have two HTTPRoutes matching and routing traffic to different Services. You might be wondering, where are these Services accessible? Through which networks or IPs are they exposed? -How Routes are exposed to clients is governed by [Route binding](https://gateway-api.sigs.k8s.io/concepts/api-overview/#route-binding), which describes how Routes and Gateways create a bidirectional relationship between each other. When Routes are bound to a Gateway it means their collective routing rules are configured on the underlying load balancers or proxies and the Routes are accessible through the Gateway. Thus, a Gateway is a logical representation of a networking data plane that can be configured through Routes. +How Routes are exposed to clients is governed by [Route binding](https://gateway-api.sigs.k8s.io/concepts/api-overview/#route-resources), which describes how Routes and Gateways create a bidirectional relationship between each other. When Routes are bound to a Gateway it means their collective routing rules are configured on the underlying load balancers or proxies and the Routes are accessible through the Gateway. Thus, a Gateway is a logical representation of a networking data plane that can be configured through Routes. ![How Routes bind with Gateways](route-binding.png ) @@ -192,6 +192,6 @@ When you put it all together, you have a single load balancing infrastructure th There are many resources to check out to learn more. -* Check out the [user guides](https://gateway-api.sigs.k8s.io/guides/getting-started/) to see what use-cases can be addressed. -* Try out one of the [existing Gateway controllers ](https://gateway-api.sigs.k8s.io/references/implementations/) +* Check out the [user guides](https://gateway-api.sigs.k8s.io/v1alpha1/guides/getting-started/) to see what use-cases can be addressed. +* Try out one of the [existing Gateway controllers ](https://gateway-api.sigs.k8s.io/implementations/) * Or [get involved](https://gateway-api.sigs.k8s.io/contributing/community/) and help design and influence the future of Kubernetes service networking! diff --git a/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md b/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md new file mode 100644 index 0000000000..5a8a4a2989 --- /dev/null +++ b/content/en/blog/_posts/2022-03-15-meet-our-contributors-APAC-AU-NZ-region-01.md @@ -0,0 +1,78 @@ +--- +layout: blog +title: "Meet Our Contributors - APAC (Aus-NZ region)" +date: 2022-03-16T12:00:00+0000 +slug: meet-our-contributors-au-nz-ep-02 +canonicalUrl: https://www.kubernetes.dev/blog/2022/03/14/meet-our-contributors-au-nz-ep-02/ +--- + +**Authors & Interviewers:** [Anubhav Vardhan](https://github.com/anubha-v-ardhan), [Atharva Shinde](https://github.com/Atharva-Shinde), [Avinesh Tripathi](https://github.com/AvineshTripathi), [Brad McCoy](https://github.com/bradmccoydev), [Debabrata Panigrahi](https://github.com/Debanitrkl), [Jayesh Srivastava](https://github.com/jayesh-srivastava), [Kunal Verma](https://github.com/verma-kunal), [Pranshu Srivastava](https://github.com/PranshuSrivastava), [Priyanka Saggu](github.com/Priyankasaggu11929/), [Purneswar Prasad](https://github.com/PurneswarPrasad), [Vedant Kakde](https://github.com/vedant-kakde) + +--- + +Good day, everyone 👋 + +Welcome back to the second episode of the "Meet Our Contributors" blog post series for APAC. + +This post will feature four outstanding contributors from the Australia and New Zealand regions, who have played diverse leadership and community roles in the Upstream Kubernetes project. + +So, without further ado, let's get straight to the blog. + +## [Caleb Woodbine](https://github.com/BobyMCbobs) + +Caleb Woodbine is currently a member of the ii.nz organisation. + +He began contributing to the Kubernetes project in 2018 as a member of the Kubernetes Conformance working group. His experience was positive, and he benefited from early guidance from [Hippie Hacker](https://github.com/hh), a fellow contributor from New Zealand. + +He has made major contributions to Kubernetes project since then through `SIG k8s-infra` and `k8s-conformance` working group. + +Caleb is also a co-organizer of the [CloudNative NZ](https://www.meetup.com/cloudnative-nz/) community events, which aim to expand the reach of Kubernetes project throughout New Zealand in order to encourage technical education and improved employment opportunities. + +> _There need to be more outreach in APAC and the educators and universities must pick up Kubernetes, as they are very slow and about 8+ years out of date. NZ tends to rather pay overseas than educate locals on the latest cloud tech Locally._ + +## [Dylan Graham](https://github.com/DylanGraham) + +Dylan Graham is a cloud engineer from Adeliade, Australia. He has been contributing to the upstream Kubernetes project since 2018. + +He stated that being a part of such a large-scale project was initially overwhelming, but that the community's friendliness and openness assisted him in getting through it. + +He began by contributing to the project documentation and is now mostly focused on the community support for the APAC region. + +He believes that consistent attendance at community/project meetings, taking on project tasks, and seeking community guidance as needed can help new aspiring developers become effective contributors. + +> _The feeling of being a part of a large community is really special. I've met some amazing people, even some before the pandemic in real life :)_ + +## [Hippie Hacker](https://github.com/hh) + +Hippie has worked for the CNCF.io as a Strategic Initiatives contractor from New Zealand for almost 5+ years. He is an active contributor to k8s-infra, API conformance testing, Cloud provider conformance submissions, and apisnoop.cncf.io domains of the upstream Kubernetes & CNCF projects. + +He recounts their early involvement with the Kubernetes project, which began roughly 5 years ago when their firm, ii.nz, demonstrated [network booting from a Raspberry Pi using PXE and running Gitlab in-cluster to install Kubernetes on servers](https://ii.nz/post/bringing-the-cloud-to-your-community/). + +He describes their own contributing experience as someone who, at first, tried to do all of the hard lifting on their own, but eventually saw the benefit of group contributions which reduced burnout and task division which allowed folks to keep moving forward on their own momentum. + +He recommends that new contributors use pair programming. + +> _The cross pollination of approaches and two pairs of eyes on the same work can often yield a much more amplified effect than a PR comment / approval alone can afford._ + +## [Nick Young](https://github.com/youngnick) + +Nick Young works at VMware as a technical lead for Contour, a CNCF ingress controller. He was active with the upstream Kubernetes project from the beginning, and eventually became the chair of the LTS working group, where he advocated user concerns. He is currently the SIG Network Gateway API subproject's maintainer. + +His contribution path was notable in that he began working on major areas of the Kubernetes project early on, skewing his trajectory. + +He asserts the best thing a new contributor can do is to "start contributing". Naturally, if it is relevant to their employment, that is excellent; however, investing non-work time in contributing can pay off in the long run in terms of work. He believes that new contributors, particularly those who are currently Kubernetes users, should be encouraged to participate in higher-level project discussions. + +> _Just being active and contributing will get you a long way. Once you've been active for a while, you'll find that you're able to answer questions, which will mean you're asked questions, and before you know it you are an expert._ + + + + +--- + +If you have any recommendations/suggestions for who we should interview next, please let us know in #sig-contribex. Your suggestions would be much appreciated. We're thrilled to have additional folks assisting us in reaching out to even more wonderful individuals of the community. + + +We'll see you all in the next one. Everyone, till then, have a happy contributing! 👋 + + + diff --git a/content/en/blog/_posts/2022-03-31-ready-for-dockershim-removal.md b/content/en/blog/_posts/2022-03-31-ready-for-dockershim-removal.md new file mode 100644 index 0000000000..63d0cc5be5 --- /dev/null +++ b/content/en/blog/_posts/2022-03-31-ready-for-dockershim-removal.md @@ -0,0 +1,34 @@ +--- +layout: blog +title: "Is Your Cluster Ready for v1.24?" +date: 2022-03-31 +slug: ready-for-dockershim-removal +--- + +**Author:** Kat Cosgrove + + +Way back in December of 2020, Kubernetes announced the [deprecation of Dockershim](/blog/2020/12/02/dont-panic-kubernetes-and-docker/). In Kubernetes, dockershim is a software shim that allows you to use the entire Docker engine as your container runtime within Kubernetes. In the upcoming v1.24 release, we are removing Dockershim - the delay between deprecation and removal in line with the [project’s policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) of supporting features for at least one year after deprecation. If you are a cluster operator, this guide includes the practical realities of what you need to know going into this release. Also, what do you need to do to ensure your cluster doesn’t fall over! + +## First, does this even affect you? + +If you are rolling your own cluster or are otherwise unsure whether or not this removal affects you, stay on the safe side and [check to see if you have any dependencies on Docker Engine](/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you/). Please note that using Docker Desktop to build your application containers is not a Docker dependency for your cluster. Container images created by Docker are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/), a Linux Foundation governance structure that defines industry standards around container formats and runtimes. They will work just fine on any container runtime supported by Kubernetes. + +If you are using a managed Kubernetes service from a cloud provider, and you haven’t explicitly changed the container runtime, there may be nothing else for you to do. Amazon EKS, Azure AKS, and Google GKE all default to containerd now, though you should make sure they do not need updating if you have any node customizations. To check the runtime of your nodes, follow [Find Out What Container Runtime is Used on a Node](​​/docs/tasks/administer-cluster/migrating-from-dockershim/find-out-runtime-you-use/). + +Regardless of whether you are rolling your own cluster or using a managed Kubernetes service from a cloud provider, you may need to [migrate telemetry or security agents that rely on Docker Engine](/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents/). + +## I have a Docker dependency. What now? + +If your Kubernetes cluster depends on Docker Engine and you intend to upgrade to Kubernetes v1.24 (which you should eventually do for security and similar reasons), you will need to change your container runtime from Docker Engine to something else or use [cri-dockerd](https://github.com/Mirantis/cri-dockerd). Since [containerd](https://containerd.io/) is a graduated CNCF project and the runtime within Docker itself, it’s a safe bet as an alternative container runtime. Fortunately, the Kubernetes project has already documented the process of [changing a node’s container runtime](/docs/tasks/administer-cluster/migrating-from-dockershim/change-runtime-containerd/), using containerd as an example. Instructions are similar for switching to one of the other supported runtimes. + +## I want to upgrade Kubernetes, and I need to maintain compatibility with Docker as a runtime. What are my options? + +Fear not, you aren’t being left out in the cold and you don’t have to take the security risk of staying on an old version of Kubernetes. Mirantis and Docker have jointly released, and are maintaining, a replacement for dockershim. That replacement is called [cri-dockerd](https://github.com/Mirantis/cri-dockerd). If you do need to maintain compatibility with Docker as a runtime, install cri-dockerd following the instructions in the project’s documentation. + +## Is that it? + + +Yes. As long as you go into this release aware of the changes being made and the details of your own clusters, and you make sure to communicate clearly with your development teams, it will be minimally dramatic. You may have some changes to make to your cluster, application code, or scripts, but all of these requirements are documented. Switching from using Docker Engine as your runtime to using [one of the other supported container runtimes](/docs/setup/production-environment/container-runtimes/) effectively means removing the middleman, since the purpose of dockershim is to access the container runtime used by Docker itself. From a practical perspective, this removal is better both for you and for Kubernetes maintainers in the long-run. + +If you still have questions, please first check the [Dockershim Removal FAQ](/blog/2022/02/17/dockershim-faq/). diff --git a/content/en/community/_index.html b/content/en/community/_index.html index c08aa25ae0..de7fcee9a4 100644 --- a/content/en/community/_index.html +++ b/content/en/community/_index.html @@ -1,257 +1,183 @@ ---- -title: Community -layout: basic -cid: community ---- - -
-
- Kubernetes Conference Gallery - Kubernetes Conference Gallery -
- -
-
-

The Kubernetes community -- users, contributors, and the culture we've built together -- is one of the biggest reasons for the meteoric rise of this open source project. Our culture and values continue to grow and change as the project itself grows and changes. We all work together toward constant improvement of the project and the ways we work on it. -

We are the people who file issues and pull requests, attend SIG meetings, Kubernetes meetups, and KubeCon, advocate for its adoption and innovation, run kubectl get pods, and contribute in a thousand other vital ways. Read on to learn how you can get involved and become part of this amazing community.

-
-
- -
- -Contributor Community      -Community Values      -Code of conduct       -Videos      -Discussions      -Events and meetups      -News      -Releases - -
-

-
-
-
- Kubernetes Conference Gallery -
- -
- Kubernetes Conference Gallery -
- -
- Kubernetes Conference Gallery -
- Kubernetes Conference Gallery - -
- -
-
-
-

-

-

Community Values

-The Kubernetes Community values are the keystone to the ongoing success of the project.
-These principles guide every aspect of the Kubernetes project. -
- -

- - READ MORE - - -
-
-
- - - -
-
-

-

-

Code of Conduct

-The Kubernetes community values respect and inclusiveness, and enforces a Code of Conduct in all interactions. If you notice a violation of the Code of Conduct at an event or meeting, in Slack, or in another communication mechanism, reach out to the Kubernetes Code of Conduct Committee at conduct@kubernetes.io. All reports are kept confidential. You can read about the committee here. -
- -

- - -READ MORE - - -
-
-
- - - -
-

-

-

Videos

- -
We're on YouTube, a lot. Subscribe for a wide range of topics.
- -
- -
- - - - -
-Watch monthly office hours ▶
- -
- -
- - -
-Watch weekly community meetings ▶ -
- -
- -
- - - - -
-Watch a talk from a community member ▶ -
- - - -
-
-
- - -
-

-

-

Discussions

- -
We talk a lot. Find us and join the conversation on any of these platforms.
- -
- -
-Forum" - -forum ▶ - -
-Topic-based technical discussions that bridge docs, StackOverflow, and so much more -
-
- -
-Twitter - -twitter ▶ - -
Real-time announcements of blog posts, events, news, ideas -
-
- -
-GitHub - -github ▶ - -
-All the project and issue tracking, plus of course code -
-
- -
-Stack Overflow - -stack overflow ▶ - -
- Technical troubleshooting for any use case - -
-
- - - -
-
-
-

-

-
-

Upcoming Events

- {{< upcoming-events >}} -
-
- -
-
-
-

Global Community

-With over 150 meetups in the world and growing, go find your local kube people. If one isn't near, take charge and create your own. -
- -
-FIND A MEETUP -
- - -
-
- - - - -
-

-

-

Recent News

- -
-
- -
- -
-



-
- -
+--- +title: Community +layout: basic +cid: community +community_styles_migrated: true +--- + + +
+

The Kubernetes community — users, contributors, and the culture we've + built together — is one of the biggest reasons for the meteoric rise of + this open source project. Our culture and values continue to grow and change + as the project itself grows and changes. We all work together toward constant + improvement of the project and the ways we work on it.

+

We are the people who file issues and pull requests, attend SIG meetings, + Kubernetes meetups, and KubeCon, advocate for its adoption and innovation, + run kubectl get pods, and contribute in a thousand other vital + ways. Read on to learn how you can get involved and become part of this amazing + community.

+
+ + + + + +
+

Community Values

+

The Kubernetes Community values are the keystone to the ongoing success of the project.
+ These principles guide every aspect of the Kubernetes project.

+ + Read more + +
+ +
+

Code of Conduct

+

The Kubernetes community values respect and inclusiveness, and enforces a Code of Conduct in all interactions.

+

If you notice a violation of the Code of Conduct at an event or meeting, in Slack, or in another communication mechanism, reach out to the Kubernetes Code of Conduct Committee at conduct@kubernetes.io. All reports are kept confidential. You can read about the committee in the Kubernetes community repository on GitHub.

+ + Read more + +
+ +
+

Videos

+ +

Kubernetes is on YouTube, a lot. Subscribe for a wide range of topics.

+ +
+
+ + + Watch monthly office hours ▶ + +
+ +
+ + + Watch weekly community meetings ▶ + +
+ + +
+
+ +
+

Discussions

+ +

We talk a lot. Find us and join the conversation on any of these platforms.

+ +
+
+ + Forum + + Community forums ▶ +

Topic-based technical discussions that bridge docs, + troubleshooting, and so much more.

+
+ +
+ + Twitter + + Twitter ▶ +

#kubernetesio

+

Real-time announcements of blog posts, events, news, ideas.

+
+ +
+ + GitHub + + GitHub ▶ +

All the project and issue tracking, plus of course code.

+
+ +
+ + Server Fault + + Server Fault ▶ +

Kubernetes-related discussion on Server Fault. Ask a question, or answer one.

+
+ +
+ + Slack + + Slack ▶ +

With 170+ channels, you'll find one that fits your needs.

+
Need an invitation? + Visit https://slack.k8s.io/ + for an invitation.
+
+
+
+ +
+
+

Upcoming Events

+ {{< upcoming-events >}} +
+
+ +
+

Global community

+

+ With over 150 meetups in the world and growing, go find your local kube people. If one isn't near, take charge and create your own. +

+ + Find a meetup + +
+ +
+

Recent News

+
+ +
+
diff --git a/content/en/community/code-of-conduct.md b/content/en/community/code-of-conduct.md index 5dd0cb28e8..a66b0572bf 100644 --- a/content/en/community/code-of-conduct.md +++ b/content/en/community/code-of-conduct.md @@ -1,27 +1,29 @@ --- -title: Community +title: Kubernetes Community Code of Conduct layout: basic cid: community -css: /css/community.css +community_styles_migrated: true --- -
-

Kubernetes Community Code of Conduct

- +
+

Kubernetes follows the CNCF Code of Conduct. The text of the CNCF CoC is replicated below, as of commit 214585e. If you notice that this is out of date, please file an issue. +

+

If you notice a violation of the Code of Conduct at an event or meeting, in Slack, or in another communication mechanism, reach out to the Kubernetes Code of Conduct Committee. You can reach us by email at conduct@kubernetes.io. Your anonymity will be protected. +

+
-
+
{{< include "/static/cncf-code-of-conduct.md" >}}
-
diff --git a/content/en/community/static/OWNERS b/content/en/community/static/OWNERS new file mode 100644 index 0000000000..3db354af14 --- /dev/null +++ b/content/en/community/static/OWNERS @@ -0,0 +1,7 @@ +# See the OWNERS docs at https://go.k8s.io/owners + +# Disable inheritance to encourage careful review of any changes here. +options: + no_parent_owners: true +approvers: +- sig-docs-leads diff --git a/content/en/community/static/README.md b/content/en/community/static/README.md index ef8e8d5a3e..bc44990c07 100644 --- a/content/en/community/static/README.md +++ b/content/en/community/static/README.md @@ -1,2 +1,5 @@ The files in this directory have been imported from other sources. Do not -edit them directly, except by replacing them with new versions. \ No newline at end of file +edit them directly, except by replacing them with new versions. + +Localization note: you do not need to create localized versions of any of + the files in this directory. \ No newline at end of file diff --git a/content/en/community/values.md b/content/en/community/values.md index 4ae1fe30b6..675e93c865 100644 --- a/content/en/community/values.md +++ b/content/en/community/values.md @@ -1,13 +1,18 @@ --- -title: Community +title: Kubernetes Community Values layout: basic cid: community -css: /css/community.css +community_styles_migrated: true + +# this page is deprecated +# canonical page is https://www.kubernetes.dev/community/values/ +sitemap: + priority: 0.1 --- - -
- -
+
{{< include "/static/community-values.md" >}}
-
+ + + diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index 6946a6d706..049e7cc190 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -33,9 +33,9 @@ There are two main ways to have Nodes added to the {{< glossary_tooltip text="AP 1. The kubelet on a node self-registers to the control plane 2. You (or another human user) manually add a Node object -After you create a Node {{< glossary_tooltip text="object" term_id="object" >}}, or the kubelet on a node self-registers, the -control plane checks whether the new Node object is valid. For example, if you -try to create a Node from the following JSON manifest: +After you create a Node {{< glossary_tooltip text="object" term_id="object" >}}, +or the kubelet on a node self-registers, the control plane checks whether the new Node object is +valid. For example, if you try to create a Node from the following JSON manifest: ```json { @@ -85,19 +85,23 @@ register itself with the API server. This is the preferred pattern, used by mos For self-registration, the kubelet is started with the following options: - - `--kubeconfig` - Path to credentials to authenticate itself to the API server. - - `--cloud-provider` - How to talk to a {{< glossary_tooltip text="cloud provider" term_id="cloud-provider" >}} to read metadata about itself. - - `--register-node` - Automatically register with the API server. - - `--register-with-taints` - Register the node with the given list of {{< glossary_tooltip text="taints" term_id="taint" >}} (comma separated `=:`). +- `--kubeconfig` - Path to credentials to authenticate itself to the API server. +- `--cloud-provider` - How to talk to a {{< glossary_tooltip text="cloud provider" term_id="cloud-provider" >}} + to read metadata about itself. +- `--register-node` - Automatically register with the API server. +- `--register-with-taints` - Register the node with the given list of + {{< glossary_tooltip text="taints" term_id="taint" >}} (comma separated `=:`). - 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 its node status to the API server. + 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 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, -kubelets are only authorized to create/modify their own Node resource. +[NodeRestriction admission plugin](/docs/reference/access-authn-authz/admission-controllers/#noderestriction) +are enabled, kubelets are only authorized to create/modify their own Node resource. {{< note >}} As mentioned in the [Node name uniqueness](#node-name-uniqueness) section, @@ -168,8 +172,10 @@ Each section of the output is described below. The usage of these fields varies depending on your cloud provider or bare metal configuration. -* HostName: The hostname as reported by the node's kernel. Can be overridden via the kubelet `--hostname-override` parameter. -* ExternalIP: Typically the IP address of the node that is externally routable (available from outside the cluster). +* HostName: The hostname as reported by the node's kernel. Can be overridden via the kubelet + `--hostname-override` parameter. +* ExternalIP: Typically the IP address of the node that is externally routable (available from + outside the cluster). * InternalIP: Typically the IP address of the node that is routable only within the cluster. @@ -289,7 +295,6 @@ and for updating their related Leases. updates to the Node's `.status`. If the Lease update fails, the kubelet retries, using exponential backoff that starts at 200 milliseconds and capped at 7 seconds. - ## Node controller The node {{< glossary_tooltip text="controller" term_id="controller" >}} is a @@ -306,6 +311,7 @@ controller deletes the node from its list of nodes. The third is monitoring the nodes' health. The node controller is responsible for: + - In the case that a node becomes unreachable, updating the NodeReady condition of within the Node's `.status`. In this case the node controller sets the NodeReady condition to `ConditionUnknown`. @@ -327,6 +333,7 @@ The node eviction behavior changes when a node in a given availability zone becomes unhealthy. The node controller checks what percentage of nodes in the zone are unhealthy (NodeReady condition is `ConditionUnknown` or `ConditionFalse`) at the same time: + - If the fraction of unhealthy nodes is at least `--unhealthy-zone-threshold` (default 0.55), then the eviction rate is reduced. - If the cluster is small (i.e. has less than or equal to @@ -391,7 +398,9 @@ for more information. The kubelet attempts to detect node system shutdown and terminates pods running on the node. -Kubelet ensures that pods follow the normal [pod termination process](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) during the node shutdown. +Kubelet ensures that pods follow the normal +[pod termination process](/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) +during the node shutdown. The Graceful node shutdown feature depends on systemd since it takes advantage of [systemd inhibitor locks](https://www.freedesktop.org/wiki/Software/systemd/inhibit/) to @@ -404,18 +413,26 @@ enabled by default in 1.21. Note that by default, both configuration options described below, `shutdownGracePeriod` and `shutdownGracePeriodCriticalPods` are set to zero, thus not activating Graceful node shutdown functionality. -To activate the feature, the two kubelet config settings should be configured appropriately and set to non-zero values. +To activate the feature, the two kubelet config settings should be configured appropriately and +set to non-zero values. During a graceful shutdown, kubelet terminates pods in two phases: 1. Terminate regular pods running on the node. -2. Terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) running on the node. +2. Terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) + running on the node. + +Graceful node shutdown feature is configured with two +[`KubeletConfiguration`](/docs/tasks/administer-cluster/kubelet-config-file/) options: -Graceful node shutdown feature is configured with two [`KubeletConfiguration`](/docs/tasks/administer-cluster/kubelet-config-file/) options: * `shutdownGracePeriod`: - * Specifies the total duration that the node should delay the shutdown by. This is the total grace period for pod termination for both regular and [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical). + * Specifies the total duration that the node should delay the shutdown by. This is the total + grace period for pod termination for both regular and + [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical). * `shutdownGracePeriodCriticalPods`: - * Specifies the duration used to terminate [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) during a node shutdown. This value should be less than `shutdownGracePeriod`. + * Specifies the duration used to terminate + [critical pods](/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#marking-pod-as-critical) + during a node shutdown. This value should be less than `shutdownGracePeriod`. For example, if `shutdownGracePeriod=30s`, and `shutdownGracePeriodCriticalPods=10s`, kubelet will delay the node shutdown by @@ -443,8 +460,8 @@ To provide more flexibility during graceful node shutdown around the ordering of pods during shutdown, graceful node shutdown honors the PriorityClass for Pods, provided that you enabled this feature in your cluster. The feature allows cluster administers to explicitly define the ordering of pods -during graceful node shutdown based on [priority -classes](docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass). +during graceful node shutdown based on +[priority classes](/docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass). The [Graceful Node Shutdown](#graceful-node-shutdown) feature, as described above, shuts down pods in two phases, non-critical pods, followed by critical @@ -457,8 +474,8 @@ graceful node shutdown in multiple phases, each phase shutting down a particular priority class of pods. The kubelet can be configured with the exact phases and shutdown time per phase. -Assuming the following custom pod [priority -classes](docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass) +Assuming the following custom pod +[priority classes](/docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass) in a cluster, |Pod priority class name|Pod priority class value| @@ -492,7 +509,7 @@ shutdownGracePeriodByPodPriority: shutdownGracePeriodSeconds: 60 ``` -The above table implies that any pod with priority value >= 100000 will get +The above table implies that any pod with `priority` value >= 100000 will get just 10 seconds to stop, any pod with value >= 10000 and < 100000 will get 180 seconds to stop, any pod with value >= 1000 and < 10000 will get 120 seconds to stop. Finally, all other pods will get 60 seconds to stop. @@ -507,8 +524,8 @@ example, you could instead use these settings: | 0 |60 seconds | -In the above case, the pods with custom-class-b will go into the same bucket -as custom-class-c for shutdown. +In the above case, the pods with `custom-class-b` will go into the same bucket +as `custom-class-c` for shutdown. If there are no pods in a particular range, then the kubelet does not wait for pods in that priority range. Instead, the kubelet immediately skips to the @@ -577,3 +594,4 @@ see [KEP-2400](https://github.com/kubernetes/enhancements/issues/2400) and its * Read the [Node](https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#the-kubernetes-node) section of the architecture design document. * Read about [taints and tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/). + diff --git a/content/en/docs/concepts/configuration/configmap.md b/content/en/docs/concepts/configuration/configmap.md index 439d6a049d..92935e2482 100644 --- a/content/en/docs/concepts/configuration/configmap.md +++ b/content/en/docs/concepts/configuration/configmap.md @@ -42,7 +42,7 @@ that lets you store configuration for other objects to use. Unlike most Kubernetes objects that have a `spec`, a ConfigMap has `data` and `binaryData` fields. These fields accept key-value pairs as their values. Both the `data` field and the `binaryData` are optional. The `data` field is designed to -contain UTF-8 byte sequences while the `binaryData` field is designed to +contain UTF-8 strings while the `binaryData` field is designed to contain binary data as base64-encoded strings. The name of a ConfigMap must be a valid diff --git a/content/en/docs/concepts/configuration/organize-cluster-access-kubeconfig.md b/content/en/docs/concepts/configuration/organize-cluster-access-kubeconfig.md index b27fcdee61..713592cf98 100644 --- a/content/en/docs/concepts/configuration/organize-cluster-access-kubeconfig.md +++ b/content/en/docs/concepts/configuration/organize-cluster-access-kubeconfig.md @@ -148,7 +148,28 @@ File references on the command line are relative to the current working director In `$HOME/.kube/config`, relative paths are stored relatively, and absolute paths are stored absolutely. +## Proxy +You can configure `kubectl` to use proxy by setting `proxy-url` in the kubeconfig file, like: + +```yaml +apiVersion: v1 +kind: Config + +proxy-url: https://proxy.host:3128 + +clusters: +- cluster: + name: development + +users: +- name: developer + +contexts: +- context: + name: development + +``` ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md index 82e8a5737d..d9611439a4 100644 --- a/content/en/docs/concepts/configuration/secret.md +++ b/content/en/docs/concepts/configuration/secret.md @@ -6,7 +6,8 @@ content_type: concept feature: title: Secret and configuration management description: > - Deploy and update secrets and application configuration without rebuilding your image and without exposing secrets in your stack configuration. + Deploy and update secrets and application configuration without rebuilding your image + and without exposing secrets in your stack configuration. weight: 30 --- @@ -22,8 +23,8 @@ application code. Because Secrets can be created independently of the Pods that use them, there is less risk of the Secret (and its data) being exposed during the workflow of creating, viewing, and editing Pods. Kubernetes, and applications that run in -your cluster, can also take additional precautions with Secrets, such as -avoiding writing confidential data to nonvolatile storage. +your cluster, can also take additional precautions with Secrets, such as avoiding +writing secret data to nonvolatile storage. Secrets are similar to {{< glossary_tooltip text="ConfigMaps" term_id="configmap" >}} but are specifically intended to hold confidential data. @@ -35,19 +36,21 @@ Additionally, anyone who is authorized to create a Pod in a namespace can use th In order to safely use Secrets, take at least the following steps: 1. [Enable Encryption at Rest](/docs/tasks/administer-cluster/encrypt-data/) for Secrets. -2. Enable or configure [RBAC rules](/docs/reference/access-authn-authz/authorization/) that - restrict reading data in Secrets (including via indirect means). -3. Where appropriate, also use mechanisms such as RBAC to limit which principals are allowed to create new Secrets or replace existing ones. +1. [Enable or configure RBAC rules](/docs/reference/access-authn-authz/authorization/) that + restrict reading and writing the Secret. Be aware that secrets can be obtained + implicitly by anyone with the permission to create a Pod. +1. Where appropriate, also use mechanisms such as RBAC to limit which principals are allowed + to create new Secrets or replace existing ones. {{< /caution >}} +See [Information security for Secrets](#information-security-for-secrets) for more details. + -## Overview of Secrets - -To use a Secret, a Pod needs to reference the Secret. -A Secret can be used with a Pod in three ways: +## Uses for Secrets +There are three main ways for a Pod to use a Secret: - As [files](#using-secrets-as-files-from-a-pod) in a {{< glossary_tooltip text="volume" term_id="volume" >}} mounted on one or more of its containers. @@ -58,8 +61,50 @@ The Kubernetes control plane also uses Secrets; for example, [bootstrap token Secrets](#bootstrap-token-secrets) are a mechanism to help automate node registration. +### Alternatives to Secrets + +Rather than using a Secret to protect confidential data, you can pick from alternatives. + +Here are some of your options: + +- if your cloud-native component needs to authenticate to another application that you + know is running within the same Kubernetes cluster, you can use a + [ServiceAccount](/docs/reference/access-authn-authz/authentication/#service-account-tokens) + and its tokens to identify your client. +- there are third-party tools that you can run, either within or outside your cluster, + that provide secrets management. For example, a service that Pods access over HTTPS, + that reveals a secret if the client correctly authenticates (for example, with a ServiceAccount + token). +- for authentication, you can implement a custom signer for X.509 certificates, and use + [CertificateSigningRequests](/docs/reference/access-authn-authz/certificate-signing-requests/) + to let that custom signer issue certificates to Pods that need them. +- you can use a [device plugin](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/) + to expose node-local encryption hardware to a specific Pod. For example, you can schedule + trusted Pods onto nodes that provide a Trusted Platform Module, configured out-of-band. + +You can also combine two or more of those options, including the option to use Secret objects themselves. + +For example: implement (or deploy) an {{< glossary_tooltip text="operator" term_id="operator-pattern" >}} +that fetches short-lived session tokens from an external service, and then creates Secrets based +on those short-lived session tokens. Pods running in your cluster can make use of the session tokens, +and operator ensures they are valid. This separation means that you can run Pods that are unaware of +the exact mechanisms for issuing and refreshing those session tokens. + +## Working with Secrets + +### Creating a Secret + +There are several options to create a Secret: + +- [create Secret using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/) +- [create Secret from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/) +- [create Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/) + +#### Constraints on Secret names and data {#restriction-names-data} + The name of a Secret object must be a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). + You can specify the `data` and/or the `stringData` field when creating a configuration file for a Secret. The `data` and the `stringData` fields are optional. The values for all keys in the `data` field have to be base64-encoded strings. @@ -72,21 +117,732 @@ merged into the `data` field. If a key appears in both the `data` and the `stringData` field, the value specified in the `stringData` field takes precedence. +#### Size limit {#restriction-data-size} + +Individual secrets are limited to 1MiB in size. This is to discourage creation +of very large secrets that could exhaust the API server and kubelet memory. +However, creation of many smaller secrets could also exhaust memory. You can +use a [resource quota](/docs/concepts/policy/resource-quotas/) to limit the +number of Secrets (or other resources) in a namespace. + +### Editing a Secret + +You can edit an existing Secret using kubectl: + +```shell +kubectl edit secrets mysecret +``` + +This opens your default editor and allows you to update the base64 encoded Secret +values in the `data` field; for example: + +```yaml +# Please edit the object below. Lines beginning with a '#' will be ignored, +# and an empty file will abort the edit. If an error occurs while saving this file, it will be +# reopened with the relevant failures. +# +apiVersion: v1 +data: + username: YWRtaW4= + password: MWYyZDFlMmU2N2Rm +kind: Secret +metadata: + annotations: + kubectl.kubernetes.io/last-applied-configuration: { ... } + creationTimestamp: 2020-01-22T18:41:56Z + name: mysecret + namespace: default + resourceVersion: "164619" + uid: cfee02d6-c137-11e5-8d73-42010af00002 +type: Opaque +``` + +That example manifest defines a Secret with two keys in the `data` field: `username` and `password`. +The values are Base64 strings in the manifest; however, when you use the Secret with a Pod +then the kubelet provides the _decoded_ data to the Pod and its containers. + +You can package many keys and values into one Secret, or use many Secrets, whichever is convenient. + +### Using a Secret + +Secrets can be mounted as data volumes or exposed as +{{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}} +to be used by a container in a Pod. Secrets can also be used by other parts of the +system, without being directly exposed to the Pod. For example, Secrets can hold +credentials that other parts of the system should use to interact with external +systems on your behalf. + +Secret volume sources are validated to ensure that the specified object +reference actually points to an object of type Secret. Therefore, a Secret +needs to be created before any Pods that depend on it. + +If the Secret cannot be fetched (perhaps because it does not exist, or +due to a temporary lack of connection to the API server) the kubelet +periodically retries running that Pod. The kubelet also reports an Event +for that Pod, including details of the problem fetching the Secret. + +#### Optional Secrets {#restriction-secret-must-exist} + +When you define a container environment variable based on a Secret, +you can mark it as _optional_. The default is for the Secret to be +required. + +None of a Pod's containers will start until all non-optional Secrets are +available. + +If a Pod references a specific key in a Secret and that Secret does exist, but +is missing the named key, the Pod fails during startup. + +### Using Secrets as files from a Pod {#using-secrets-as-files-from-a-pod} + +If you want to access data from a Secret in a Pod, one way to do that is to +have Kubernetes make the value of that Secret be available as a file inside +the filesystem of one or more of the Pod's containers. + +To configure that, you: + +1. Create a secret or use an existing one. Multiple Pods can reference the same secret. +1. Modify your Pod definition to add a volume under `.spec.volumes[]`. Name the volume anything, and have a `.spec.volumes[].secret.secretName` field equal to the name of the Secret object. +1. Add a `.spec.containers[].volumeMounts[]` to each container that needs the secret. Specify `.spec.containers[].volumeMounts[].readOnly = true` and `.spec.containers[].volumeMounts[].mountPath` to an unused directory name where you would like the secrets to appear. +1. Modify your image or command line so that the program looks for files in that directory. Each key in the secret `data` map becomes the filename under `mountPath`. + +This is an example of a Pod that mounts a Secret named `mysecret` in a volume: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: mypod +spec: + containers: + - name: mypod + image: redis + volumeMounts: + - name: foo + mountPath: "/etc/foo" + readOnly: true + volumes: + - name: foo + secret: + secretName: mysecret + optional: false # default setting; "mysecret" must exist +``` + +Each Secret you want to use needs to be referred to in `.spec.volumes`. + +If there are multiple containers in the Pod, then each container needs its +own `volumeMounts` block, but only one `.spec.volumes` is needed per Secret. + +{{< note >}} +Versions of Kubernetes before v1.22 automatically created credentials for accessing +the Kubernetes API. This older mechanism was based on creating token Secrets that +could then be mounted into running Pods. +In more recent versions, including Kubernetes v{{< skew currentVersion >}}, 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. + +You can still [manually create](/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-service-account-api-token) +a service account token Secret; for example, 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 >}} + +#### Projection of Secret keys to specific paths + +You can also control the paths within the volume where Secret keys are projected. +You can use the `.spec.volumes[].secret.items` field to change the target path of each key: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: mypod +spec: + containers: + - name: mypod + image: redis + volumeMounts: + - name: foo + mountPath: "/etc/foo" + readOnly: true + volumes: + - name: foo + secret: + secretName: mysecret + items: + - key: username + path: my-group/my-username +``` + +What will happen: + +* the `username` key from `mysecret` is available to the container at the path + `/etc/foo/my-group/my-username` instead of at `/etc/foo/username`. +* the `password` key from that Secret object is not projected. + +If `.spec.volumes[].secret.items` is used, only keys specified in `items` are projected. +To consume all keys from the Secret, all of them must be listed in the `items` field. + +If you list keys explicitly, then all listed keys must exist in the corresponding Secret. +Otherwise, the volume is not created. + +#### Secret files permissions + +You can set the POSIX file access permission bits for a single Secret key. +If you don't specify any permissions, `0644` is used by default. +You can also set a default mode for the entire Secret volume and override per key if needed. + +For example, you can specify a default mode like this: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: mypod +spec: + containers: + - name: mypod + image: redis + volumeMounts: + - name: foo + mountPath: "/etc/foo" + volumes: + - name: foo + secret: + secretName: mysecret + defaultMode: 0400 +``` + +The secret is mounted on `/etc/foo`; all the files created by the +secret volume mount have permission `0400`. + + +{{< note >}} +If you're defining a Pod or a Pod template using JSON, beware that the JSON +specification doesn't support octal notation. You can use the decimal value +for the `defaultMode` (for example, 0400 in octal is 256 in decimal) instead. +If you're writing YAML, you can write the `defaultMode` in octal. +{{< /note >}} + +#### Consuming Secret values from volumes + +Inside the container that mounts a secret volume, the secret keys appear as +files. The secret values are base64 decoded and stored inside these files. + +This is the result of commands executed inside the container from the example above: + +```shell +ls /etc/foo/ +``` + +The output is similar to: + +``` +username +password +``` + +```shell +cat /etc/foo/username +``` + +The output is similar to: + +``` +admin +``` + +```shell +cat /etc/foo/password +``` + +The output is similar to: + +``` +1f2d1e2e67df +``` + +The program in a container is responsible for reading the secret data from these +files, as needed. + +#### Mounted Secrets are updated automatically + +When a volume contains data from a Secret, and that Secret is updated, Kubernetes tracks +this and updates the data in the volume, using an eventually-consistent approach. + +{{< note >}} +A container using a Secret as a +[subPath](/docs/concepts/storage/volumes#using-subpath) volume mount does not receive +automated Secret updates. +{{< /note >}} + +The kubelet keeps a cache of the current keys and values for the Secrets that are used in +volumes for pods on that node. +You can configure the way that the kubelet detects changes from the cached values. The `configMapAndSecretChangeDetectionStrategy` field in +the [kubelet configuration](/docs/reference/config-api/kubelet-config.v1beta1/) controls which strategy the kubelet uses. The default strategy is `Watch`. + +Updates to Secrets can be either propagated by an API watch mechanism (the default), based on +a cache with a defined time-to-live, or polled from the cluster API server on each kubelet +synchronisation loop. + +As a result, the total delay from the moment when the Secret is updated to the moment +when new keys are projected to the Pod can be as long as the kubelet sync period + cache +propagation delay, where the cache propagation delay depends on the chosen cache type +(following the same order listed in the previous paragraph, these are: +watch propagation delay, the configured cache TTL, or zero for direct polling). + +### Using Secrets as environment variables + +To use a Secret in an {{< glossary_tooltip text="environment variable" term_id="container-env-variables" >}} +in a Pod: + +1. Create a Secret (or use an existing one). Multiple Pods can reference the same Secret. +1. Modify your Pod definition in each container that you wish to consume the value of a secret + key to add an environment variable for each secret key you wish to consume. The environment + variable that consumes the secret key should populate the secret's name and key in `env[].valueFrom.secretKeyRef`. +1. Modify your image and/or command line so that the program looks for values in the specified + environment variables. + +This is an example of a Pod that uses a Secret via environment variables: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: secret-env-pod +spec: + containers: + - name: mycontainer + image: redis + env: + - name: SECRET_USERNAME + valueFrom: + secretKeyRef: + name: mysecret + key: username + optional: false # same as default; "mysecret" must exist + # and include a key named "username" + - name: SECRET_PASSWORD + valueFrom: + secretKeyRef: + name: mysecret + key: password + optional: false # same as default; "mysecret" must exist + # and include a key named "password" + restartPolicy: Never +``` + + +#### Invalid environment variables {#restriction-env-from-invalid} + +Secrets used to populate environment variables by the `envFrom` field that have keys +that are considered invalid environment variable names will have those keys +skipped. The Pod is allowed to start. + +If you define a Pod with an invalid variable name, the failed Pod startup includes +an event with the reason set to `InvalidVariableNames` and a message that lists the +skipped invalid keys. The following example shows a Pod that refers to a Secret +named `mysecret`, where `mysecret` contains 2 invalid keys: `1badkey` and `2alsobad`. + +```shell +kubectl get events +``` + +The output is similar to: + +``` +LASTSEEN FIRSTSEEN COUNT NAME KIND SUBOBJECT TYPE REASON +0s 0s 1 dapi-test-pod Pod Warning InvalidEnvironmentVariableNames kubelet, 127.0.0.1 Keys [1badkey, 2alsobad] from the EnvFrom secret default/mysecret were skipped since they are considered invalid environment variable names. +``` + + +#### Consuming Secret values from environment variables + +Inside a container that consumes a Secret using environment variables, the secret keys appear +as normal environment variables. The values of those variables are the base64 decoded values +of the secret data. + +This is the result of commands executed inside the container from the example above: + +```shell +echo "$SECRET_USERNAME" +``` + +The output is similar to: + +``` +admin +``` + +```shell +echo "$SECRET_PASSWORD" +``` + +The output is similar to: + +``` +1f2d1e2e67df +``` + +{{< note >}} +If a container already consumes a Secret in an environment variable, +a Secret update will not be seen by the container unless it is +restarted. There are third party solutions for triggering restarts when +secrets change. +{{< /note >}} + +### Container image pull secrets {#using-imagepullsecrets} + +If you want to fetch container images from a private repository, you need a way for +the kubelet on each node to authenticate to that repository. You can configure +_image pull secrets_ to make this possible. These secrets are configured at the Pod +level. + +The `imagePullSecrets` field for a Pod is a list of references to Secrets in the same namespace +as the Pod. +You can use an `imagePullSecrets` to pass image registry access credentials to +the kubelet. The kubelet uses this information to pull a private image on behalf of your Pod. +See `PodSpec` in the [Pod API reference](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec) +for more information about the `imagePullSecrets` field. + +#### Using imagePullSecrets + +The `imagePullSecrets` field is a list of references to secrets in the same namespace. +You can use an `imagePullSecrets` to pass a secret that contains a Docker (or other) image registry +password to the kubelet. The kubelet uses this information to pull a private image on behalf of your Pod. +See the [PodSpec API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) for more information about the `imagePullSecrets` field. + +##### Manually specifying an imagePullSecret + +You can learn how to specify `imagePullSecrets` from the [container images](/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) +documentation. + +##### Arranging for imagePullSecrets to be automatically attached + +You can manually create `imagePullSecrets`, and reference these from +a ServiceAccount. Any Pods created with that ServiceAccount +or created with that ServiceAccount by default, will get their `imagePullSecrets` +field set to that of the service account. +See [Add ImagePullSecrets to a service account](/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) + for a detailed explanation of that process. + +### Using Secrets with static Pods {#restriction-static-pod} + +You cannot use ConfigMaps or Secrets with +{{< glossary_tooltip text="static Pods" term_id="static-pod" >}}. + +## Use cases + +### Use case: As container environment variables + +Create a secret +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: mysecret +type: Opaque +data: + USER_NAME: YWRtaW4= + PASSWORD: MWYyZDFlMmU2N2Rm +``` + +Create the Secret: +```shell +kubectl apply -f mysecret.yaml +``` + +Use `envFrom` to define all of the Secret's data as container environment variables. The key from the Secret becomes the environment variable name in the Pod. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: secret-test-pod +spec: + containers: + - name: test-container + image: k8s.gcr.io/busybox + command: [ "/bin/sh", "-c", "env" ] + envFrom: + - secretRef: + name: mysecret + restartPolicy: Never +``` + +### Use case: Pod with SSH keys + +Create a Secret containing some SSH keys: + +```shell +kubectl create secret generic ssh-key-secret --from-file=ssh-privatekey=/path/to/.ssh/id_rsa --from-file=ssh-publickey=/path/to/.ssh/id_rsa.pub +``` + +The output is similar to: + +``` +secret "ssh-key-secret" created +``` + +You can also create a `kustomization.yaml` with a `secretGenerator` field containing ssh keys. + +{{< caution >}} +Think carefully before sending your own SSH keys: other users of the cluster may have access +to the Secret. + +You could instead create an SSH private key representing a service identity that you want to be +accessible to all the users with whom you share the Kubernetes cluster, and that you can revoke +if the credentials are compromised. +{{< /caution >}} + +Now you can create a Pod which references the secret with the SSH key and +consumes it in a volume: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: secret-test-pod + labels: + name: secret-test +spec: + volumes: + - name: secret-volume + secret: + secretName: ssh-key-secret + containers: + - name: ssh-test-container + image: mySshImage + volumeMounts: + - name: secret-volume + readOnly: true + mountPath: "/etc/secret-volume" +``` + +When the container's command runs, the pieces of the key will be available in: + +``` +/etc/secret-volume/ssh-publickey +/etc/secret-volume/ssh-privatekey +``` + +The container is then free to use the secret data to establish an SSH connection. + +### Use case: Pods with prod / test credentials + +This example illustrates a Pod which consumes a secret containing production +credentials and another Pod which consumes a secret with test environment +credentials. + +You can create a `kustomization.yaml` with a `secretGenerator` field or run +`kubectl create secret`. + +```shell +kubectl create secret generic prod-db-secret --from-literal=username=produser --from-literal=password=Y4nys7f11 +``` + +The output is similar to: + +``` +secret "prod-db-secret" created +``` + +You can also create a secret for test environment credentials. + +```shell +kubectl create secret generic test-db-secret --from-literal=username=testuser --from-literal=password=iluvtests +``` + +The output is similar to: + +``` +secret "test-db-secret" created +``` + +{{< note >}} +Special characters such as `$`, `\`, `*`, `=`, and `!` will be interpreted by your [shell](https://en.wikipedia.org/wiki/Shell_(computing)) and require escaping. + +In most shells, the easiest way to escape the password is to surround it with single quotes (`'`). +For example, if your actual password is `S!B\*d$zDsb=`, you should execute the command this way: + +```shell +kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password='S!B\*d$zDsb=' +``` + +You do not need to escape special characters in passwords from files (`--from-file`). +{{< /note >}} + +Now make the Pods: + +```shell +cat < pod.yaml +apiVersion: v1 +kind: List +items: +- kind: Pod + apiVersion: v1 + metadata: + name: prod-db-client-pod + labels: + name: prod-db-client + spec: + volumes: + - name: secret-volume + secret: + secretName: prod-db-secret + containers: + - name: db-client-container + image: myClientImage + volumeMounts: + - name: secret-volume + readOnly: true + mountPath: "/etc/secret-volume" +- kind: Pod + apiVersion: v1 + metadata: + name: test-db-client-pod + labels: + name: test-db-client + spec: + volumes: + - name: secret-volume + secret: + secretName: test-db-secret + containers: + - name: db-client-container + image: myClientImage + volumeMounts: + - name: secret-volume + readOnly: true + mountPath: "/etc/secret-volume" +EOF +``` + +Add the pods to the same `kustomization.yaml`: + +```shell +cat <> kustomization.yaml +resources: +- pod.yaml +EOF +``` + +Apply all those objects on the API server by running: + +```shell +kubectl apply -k . +``` + +Both containers will have the following files present on their filesystems with the values +for each container's environment: + +``` +/etc/secret-volume/username +/etc/secret-volume/password +``` + +Note how the specs for the two Pods differ only in one field; this facilitates +creating Pods with different capabilities from a common Pod template. + +You could further simplify the base Pod specification by using two service accounts: + +1. `prod-user` with the `prod-db-secret` +1. `test-user` with the `test-db-secret` + +The Pod specification is shortened to: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: prod-db-client-pod + labels: + name: prod-db-client +spec: + serviceAccount: prod-db-client + containers: + - name: db-client-container + image: myClientImage +``` + +### Use case: dotfiles in a secret volume + +You can make your data "hidden" by defining a key that begins with a dot. +This key represents a dotfile or "hidden" file. For example, when the following secret +is mounted into a volume, `secret-volume`: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: dotfile-secret +data: + .secret-file: dmFsdWUtMg0KDQo= +--- +apiVersion: v1 +kind: Pod +metadata: + name: secret-dotfiles-pod +spec: + volumes: + - name: secret-volume + secret: + secretName: dotfile-secret + containers: + - name: dotfile-test-container + image: k8s.gcr.io/busybox + command: + - ls + - "-l" + - "/etc/secret-volume" + volumeMounts: + - name: secret-volume + readOnly: true + mountPath: "/etc/secret-volume" +``` + +The volume will contain a single file, called `.secret-file`, and +the `dotfile-test-container` will have this file present at the path +`/etc/secret-volume/.secret-file`. + +{{< note >}} +Files beginning with dot characters are hidden from the output of `ls -l`; +you must use `ls -la` to see them when listing directory contents. +{{< /note >}} + +### Use case: Secret visible to one container in a Pod + +Consider a program that needs to handle HTTP requests, do some complex business +logic, and then sign some messages with an HMAC. Because it has complex +application logic, there might be an unnoticed remote file reading exploit in +the server, which could expose the private key to an attacker. + +This could be divided into two processes in two containers: a frontend container +which handles user interaction and business logic, but which cannot see the +private key; and a signer container that can see the private key, and responds +to simple signing requests from the frontend (for example, over localhost networking). + +With this partitioned approach, an attacker now has to trick the application +server into doing something rather arbitrary, which may be harder than getting +it to read a file. + ## Types of Secret {#secret-types} When creating a Secret, you can specify its type using the `type` field of -a Secret resource, or certain equivalent `kubectl` command line flags (if available). -The `type` of a Secret is used to facilitate programmatic handling of different -kinds of confidential data. +the [Secret](/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/) +resource, or certain equivalent `kubectl` command line flags (if available). +The Secret type is used to facilitate programmatic handling of the Secret data. -Kubernetes provides several builtin types for some common usage scenarios. +Kubernetes provides several built-in types for some common usage scenarios. These types vary in terms of the validations performed and the constraints Kubernetes imposes on them. -| Builtin Type | Usage | +| Built-in Type | Usage | |--------------|-------| | `Opaque` | arbitrary user-defined data | -| `kubernetes.io/service-account-token` | service account token | +| `kubernetes.io/service-account-token` | ServiceAccount token | | `kubernetes.io/dockercfg` | serialized `~/.dockercfg` file | | `kubernetes.io/dockerconfigjson` | serialized `~/.docker/config.json` file | | `kubernetes.io/basic-auth` | credentials for basic authentication | @@ -95,11 +851,16 @@ Kubernetes imposes on them. | `bootstrap.kubernetes.io/token` | bootstrap token data | You can define and use your own Secret type by assigning a non-empty string as the -`type` value for a Secret object. An empty string is treated as an `Opaque` type. +`type` value for a Secret object (an empty string is treated as an `Opaque` type). + Kubernetes doesn't impose any constraints on the type name. However, if you -are using one of the builtin types, you must meet all the requirements defined +are using one of the built-in types, you must meet all the requirements defined for that type. +If you are defining a type of secret that's for public use, follow the convention +and structure the secret type to have your domain name before the name, separated +by a `/`. For example: `cloud-hosting.example.net/cloud-api-credentials`. + ### Opaque secrets `Opaque` is the default Secret type if omitted from a Secret configuration file. @@ -120,16 +881,20 @@ empty-secret Opaque 0 2m6s ``` The `DATA` column shows the number of data items stored in the Secret. -In this case, `0` means we have created an empty Secret. +In this case, `0` means you have created an empty Secret. -### Service account token Secrets +### Service account token Secrets A `kubernetes.io/service-account-token` type of Secret is used to store a -token that identifies a service account. When using this Secret type, you need -to ensure that the `kubernetes.io/service-account.name` annotation is set to an -existing service account name. A Kubernetes controller fills in some other -fields such as the `kubernetes.io/service-account.uid` annotation and the -`token` key in the `data` field set to actual token content. +token that identifies a +{{< glossary_tooltip text="service account" term_id="service-account" >}}. +When using this Secret type, you need to ensure that the +`kubernetes.io/service-account.name` annotation is set to an existing +service account name. A Kubernetes +{{< glossary_tooltip text="controller" term_id="controller" >}} fills in some +other fields such as the `kubernetes.io/service-account.uid` annotation, and the +`token` key in the `data` field, which is set to contain an authentication +token. The following example configuration declares a service account token Secret: @@ -146,31 +911,25 @@ data: extra: YmFyCg== ``` +When creating a `Pod`, Kubernetes automatically finds or creates a service account +Secret and then automatically modifies your Pod to use this Secret. The service account +token Secret contains credentials for accessing the Kubernetes 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. +documentation for more information on how service accounts work. You can also check the `automountServiceAccountToken` field and the `serviceAccountName` field of 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 -store the credentials for accessing a Docker registry for images. +store the credentials for accessing a container image registry: - `kubernetes.io/dockercfg` - `kubernetes.io/dockerconfigjson` @@ -207,59 +966,64 @@ If you do not want to perform the base64 encoding, you can choose to use the {{< /note >}} When you create these types of Secrets using a manifest, the API -server checks whether the expected key does exists in the `data` field, and +server checks whether the expected key exists in the `data` field, and it verifies if the value provided can be parsed as a valid JSON. The API server doesn't validate if the JSON actually is a Docker config file. When you do not have a Docker config file, or you want to use `kubectl` -to create a Docker registry Secret, you can do: +to create a Secret for accessing a container registry, you can do: ```shell kubectl create secret docker-registry secret-tiger-docker \ + --docker-email=tiger@acme.example \ --docker-username=tiger \ - --docker-password=pass113 \ - --docker-email=tiger@acme.com \ + --docker-password=pass1234 \ --docker-server=my-registry.example:5000 ``` -This command creates a Secret of type `kubernetes.io/dockerconfigjson`. -If you dump the `.dockerconfigjson` content from the `data` field, you will -get the following JSON content which is a valid Docker configuration created -on the fly: +That command creates a Secret of type `kubernetes.io/dockerconfigjson`. +If you dump the `.data.dockercfgjson` field from that new Secret and then +decode it from base64: + +```shell +kubectl get secret secret-tiger-docker -o jsonpath='{.data.*}' | base64 -d +``` + +then the output is equivalent to this JSON document (which is also a valid +Docker configuration file): ```json { - "apiVersion": "v1", - "data": { - ".dockerconfigjson": "eyJhdXRocyI6eyJteS1yZWdpc3RyeTo1MDAwIjp7InVzZXJuYW1lIjoidGlnZXIiLCJwYXNzd29yZCI6InBhc3MxMTMiLCJlbWFpbCI6InRpZ2VyQGFjbWUuY29tIiwiYXV0aCI6ImRHbG5aWEk2Y0dGemN6RXhNdz09In19fQ==" - }, - "kind": "Secret", - "metadata": { - "creationTimestamp": "2021-07-01T07:30:59Z", - "name": "secret-tiger-docker", - "namespace": "default", - "resourceVersion": "566718", - "uid": "e15c1d7b-9071-4100-8681-f3a7a2ce89ca" - }, - "type": "kubernetes.io/dockerconfigjson" + "auths": { + "my-registry.example:5000": { + "username": "tiger", + "password": "pass1234", + "email": "tiger@acme.example", + "auth": "dGlnZXI6cGFzczEyMzQ=" + } + } } - ``` +{{< note >}} +The `auth` value there is base64 encoded; it is obscured but not secret. +Anyone who can read that Secret can learn the registry access bearer token. +{{< /note >}} + ### Basic authentication Secret The `kubernetes.io/basic-auth` type is provided for storing credentials needed for basic authentication. When using this Secret type, the `data` field of the Secret must contain one of the following two keys: -- `username`: the user name for authentication; -- `password`: the password or token for authentication. +- `username`: the user name for authentication +- `password`: the password or token for authentication Both values for the above two keys are base64 encoded strings. You can, of course, provide the clear text content using the `stringData` for Secret creation. -The following YAML is an example config for a basic authentication Secret: +The following manifest is an example of a basic authentication Secret: ```yaml apiVersion: v1 @@ -268,15 +1032,17 @@ metadata: name: secret-basic-auth type: kubernetes.io/basic-auth stringData: - username: admin - password: t0p-Secret + username: admin # required field for kubernetes.io/basic-auth + password: t0p-Secret # required field for kubernetes.io/basic-auth ``` -The basic authentication Secret type is provided only for user's convenience. -You can create an `Opaque` for credentials used for basic authentication. -However, using the builtin Secret type helps unify the formats of your credentials -and the API server does verify if the required keys are provided in a Secret -configuration. +The basic authentication Secret type is provided only for convenience. +You can create an `Opaque` type for credentials used for basic authentication. +However, using the defined and public Secret type (`kubernetes.io/basic-auth`) helps other +people to understand the purpose of your Secret, and sets a convention for what key names +to expect. +The Kubernetes API verifies that the required keys are set for a Secret +of this type. ### SSH authentication secrets @@ -285,7 +1051,8 @@ SSH authentication. When using this Secret type, you will have to specify a `ssh-privatekey` key-value pair in the `data` (or `stringData`) field as the SSH credential to use. -The following YAML is an example config for a SSH authentication Secret: +The following manifest is an example of a Secret used for SSH public/private +key authentication: ```yaml apiVersion: v1 @@ -300,8 +1067,10 @@ data: ``` The SSH authentication Secret type is provided only for user's convenience. -You can create an `Opaque` for credentials used for SSH authentication. -However, using the builtin Secret type helps unify the formats of your credentials +You could instead create an `Opaque` type Secret for credentials used for SSH authentication. +However, using the defined and public Secret type (`kubernetes.io/ssh-auth`) helps other +people to understand the purpose of your Secret, and sets a convention for what key names +to expect. and the API server does verify if the required keys are provided in a Secret configuration. @@ -315,9 +1084,11 @@ ConfigMap. ### TLS secrets Kubernetes provides a builtin Secret type `kubernetes.io/tls` for storing -a certificate and its associated key that are typically used for TLS . This -data is primarily used with TLS termination of the Ingress resource, but may -be used with other resources or directly by a workload. +a certificate and its associated key that are typically used for TLS. + +One common use for TLS secrets is to configure encryption in transit for +an [Ingress](/docs/concepts/services-networking/ingress/), but you can also use it +with other resources or directly in your workload. When using this type of Secret, the `tls.key` and the `tls.crt` key must be provided in the `data` (or `stringData`) field of the Secret configuration, although the API server doesn't actually validate the values for each key. @@ -352,20 +1123,28 @@ kubectl create secret tls my-tls-secret \ --key=path/to/key/file ``` -The public/private key pair must exist beforehand. The public key certificate -for `--cert` must be .PEM encoded (Base64-encoded DER format), and match the -given private key for `--key`. -The private key must be in what is commonly called PEM private key format, -unencrypted. In both cases, the initial and the last lines from PEM (for -example, `--------BEGIN CERTIFICATE-----` and `-------END CERTIFICATE----` for -a certificate) are *not* included. +The public/private key pair must exist before hand. The public key certificate +for `--cert` must be DER format as per +[Section 5.1 of RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468#section-5.1), +and must match the given private key for `--key` (PKCS #8 in DER format; +[Section 11 of RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468#section-11)). + +{{< note >}} +A kubernetes.io/tls Secret stores the Base64-encoded DER data for keys and +certificates. If you're familiar with PEM format for private keys and for certificates, +the base64 data are the same as that format except that you omit +the initial and the last lines that are used in PEM. + +For example, for a certificate, you do **not** include `--------BEGIN CERTIFICATE-----` +and `-------END CERTIFICATE----`. +{{< /note >}} ### Bootstrap token Secrets A bootstrap token Secret can be created by explicitly specifying the Secret `type` to `bootstrap.kubernetes.io/token`. This type of Secret is designed for tokens used during the node bootstrap process. It stores tokens used to sign -well known ConfigMaps. +well-known ConfigMaps. A bootstrap token Secret is usually created in the `kube-system` namespace and named in the form `bootstrap-token-` where `` is a 6 character @@ -427,367 +1206,23 @@ stringData: usage-bootstrap-signing: "true" ``` -## Creating a Secret - -There are several options to create a Secret: - -- [create Secret using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/) -- [create Secret from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/) -- [create Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/) - -## Editing a Secret - -An existing Secret may be edited with the following command: - -```shell -kubectl edit secrets mysecret -``` - -This will open the default configured editor and allow for updating the base64 encoded Secret values in the `data` field: - -```yaml -# Please edit the object below. Lines beginning with a '#' will be ignored, -# and an empty file will abort the edit. If an error occurs while saving this file will be -# reopened with the relevant failures. -# -apiVersion: v1 -data: - username: YWRtaW4= - password: MWYyZDFlMmU2N2Rm -kind: Secret -metadata: - annotations: - kubectl.kubernetes.io/last-applied-configuration: { ... } - creationTimestamp: 2016-01-22T18:41:56Z - name: mysecret - namespace: default - resourceVersion: "164619" - uid: cfee02d6-c137-11e5-8d73-42010af00002 -type: Opaque -``` - -## Using Secrets - -Secrets can be mounted as data volumes or exposed as -{{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}} -to be used by a container in a Pod. Secrets can also be used by other parts of the -system, without being directly exposed to the Pod. For example, Secrets can hold -credentials that other parts of the system should use to interact with external -systems on your behalf. - -### Using Secrets as files from a Pod - -To consume a Secret in a volume in a Pod: - -1. Create a secret or use an existing one. Multiple Pods can reference the same secret. -1. Modify your Pod definition to add a volume under `.spec.volumes[]`. Name the volume anything, and have a `.spec.volumes[].secret.secretName` field equal to the name of the Secret object. -1. Add a `.spec.containers[].volumeMounts[]` to each container that needs the secret. Specify `.spec.containers[].volumeMounts[].readOnly = true` and `.spec.containers[].volumeMounts[].mountPath` to an unused directory name where you would like the secrets to appear. -1. Modify your image or command line so that the program looks for files in that directory. Each key in the secret `data` map becomes the filename under `mountPath`. - -This is an example of a Pod that mounts a Secret in a volume: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: mypod -spec: - containers: - - name: mypod - image: redis - volumeMounts: - - name: foo - mountPath: "/etc/foo" - readOnly: true - volumes: - - name: foo - secret: - secretName: mysecret -``` - -Each Secret you want to use needs to be referred to in `.spec.volumes`. - -If there are multiple containers in the Pod, then each container needs its -own `volumeMounts` block, but only one `.spec.volumes` is needed per Secret. - -You can package many files into one secret, or use many secrets, whichever is convenient. - -#### Projection of Secret keys to specific paths - -You can also control the paths within the volume where Secret keys are projected. -You can use the `.spec.volumes[].secret.items` field to change the target path of each key: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: mypod -spec: - containers: - - name: mypod - image: redis - volumeMounts: - - name: foo - mountPath: "/etc/foo" - readOnly: true - volumes: - - name: foo - secret: - secretName: mysecret - items: - - key: username - path: my-group/my-username -``` - -What will happen: - -* `username` secret is stored under `/etc/foo/my-group/my-username` file instead of `/etc/foo/username`. -* `password` secret is not projected. - -If `.spec.volumes[].secret.items` is used, only keys specified in `items` are projected. -To consume all keys from the secret, all of them must be listed in the `items` field. -All listed keys must exist in the corresponding secret. Otherwise, the volume is not created. - -#### Secret files permissions - -You can set the file access permission bits for a single Secret key. -If you don't specify any permissions, `0644` is used by default. -You can also set a default mode for the entire Secret volume and override per key if needed. - -For example, you can specify a default mode like this: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: mypod -spec: - containers: - - name: mypod - image: redis - volumeMounts: - - name: foo - mountPath: "/etc/foo" - volumes: - - name: foo - secret: - secretName: mysecret - defaultMode: 0400 -``` - -Then, the secret will be mounted on `/etc/foo` and all the files created by the -secret volume mount will have permission `0400`. - -Note that the JSON spec doesn't support octal notation, so use the value 256 for -0400 permissions. If you use YAML instead of JSON for the Pod, you can use octal -notation to specify permissions in a more natural way. - -Note if you `kubectl exec` into the Pod, you need to follow the symlink to find -the expected file mode. For example, - -Check the secrets file mode on the pod. -``` -kubectl exec mypod -it sh - -cd /etc/foo -ls -l -``` - -The output is similar to this: -``` -total 0 -lrwxrwxrwx 1 root root 15 May 18 00:18 password -> ..data/password -lrwxrwxrwx 1 root root 15 May 18 00:18 username -> ..data/username -``` - -Follow the symlink to find the correct file mode. - -``` -cd /etc/foo/..data -ls -l -``` - -The output is similar to this: -``` -total 8 --r-------- 1 root root 12 May 18 00:18 password --r-------- 1 root root 5 May 18 00:18 username -``` - -You can also use mapping, as in the previous example, and specify different -permissions for different files like this: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: mypod -spec: - containers: - - name: mypod - image: redis - volumeMounts: - - name: foo - mountPath: "/etc/foo" - volumes: - - name: foo - secret: - secretName: mysecret - items: - - key: username - path: my-group/my-username - mode: 0777 -``` - -In this case, the file resulting in `/etc/foo/my-group/my-username` will have -permission value of `0777`. If you use JSON, owing to JSON limitations, you -must specify the mode in decimal notation, `511`. - -Note that this permission value might be displayed in decimal notation if you -read it later. - -#### Consuming Secret values from volumes - -Inside the container that mounts a secret volume, the secret keys appear as -files and the secret values are base64 decoded and stored inside these files. -This is the result of commands executed inside the container from the example above: - -```shell -ls /etc/foo/ -``` - -The output is similar to: - -``` -username -password -``` - -```shell -cat /etc/foo/username -``` - -The output is similar to: - -``` -admin -``` - -```shell -cat /etc/foo/password -``` - -The output is similar to: - -``` -1f2d1e2e67df -``` - -The program in a container is responsible for reading the secrets from the -files. - -#### Mounted Secrets are updated automatically - -When a secret currently consumed in a volume is updated, projected keys are eventually updated as well. -The kubelet checks whether the mounted secret is fresh on every periodic sync. -However, the kubelet uses its local cache for getting the current value of the Secret. -The type of the cache is configurable using the `ConfigMapAndSecretChangeDetectionStrategy` field in -the [KubeletConfiguration struct](/docs/reference/config-api/kubelet-config.v1beta1/). -A Secret can be either propagated by watch (default), ttl-based, or by redirecting -all requests directly to the API server. -As a result, the total delay from the moment when the Secret is updated to the moment -when new keys are projected to the Pod can be as long as the kubelet sync period + cache -propagation delay, where the cache propagation delay depends on the chosen cache type -(it equals to watch propagation delay, ttl of cache, or zero correspondingly). - -{{< note >}} -A container using a Secret as a -[subPath](/docs/concepts/storage/volumes#using-subpath) volume mount will not receive -Secret updates. -{{< /note >}} - -### Using Secrets as environment variables - -To use a secret in an {{< glossary_tooltip text="environment variable" term_id="container-env-variables" >}} -in a Pod: - -1. Create a secret or use an existing one. Multiple Pods can reference the same secret. -1. Modify your Pod definition in each container that you wish to consume the value of a secret key to add an environment variable for each secret key you wish to consume. The environment variable that consumes the secret key should populate the secret's name and key in `env[].valueFrom.secretKeyRef`. -1. Modify your image and/or command line so that the program looks for values in the specified environment variables. - -This is an example of a Pod that uses secrets from environment variables: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: secret-env-pod -spec: - containers: - - name: mycontainer - image: redis - env: - - name: SECRET_USERNAME - valueFrom: - secretKeyRef: - name: mysecret - key: username - - name: SECRET_PASSWORD - valueFrom: - secretKeyRef: - name: mysecret - key: password - restartPolicy: Never -``` - -#### Consuming Secret Values from environment variables - -Inside a container that consumes a secret in the environment variables, the secret keys appear as -normal environment variables containing the base64 decoded values of the secret data. -This is the result of commands executed inside the container from the example above: - -```shell -echo $SECRET_USERNAME -``` - -The output is similar to: - -``` -admin -``` - -```shell -echo $SECRET_PASSWORD -``` - -The output is similar to: - -``` -1f2d1e2e67df -``` - -#### Environment variables are not updated after a secret update - -If a container already consumes a Secret in an environment variable, a Secret update will not be seen by the container unless it is restarted. -There are third party solutions for triggering restarts when secrets change. ## Immutable Secrets {#secret-immutable} {{< feature-state for_k8s_version="v1.21" state="stable" >}} -The Kubernetes feature _Immutable Secrets and ConfigMaps_ provides an option to set -individual Secrets and ConfigMaps as immutable. For clusters that extensively use Secrets -(at least tens of thousands of unique Secret to Pod mounts), preventing changes to their -data has the following advantages: +Kubernetes lets you mark specific Secrets (and ConfigMaps) as _immutable_. +Preventing changes to the data of an existing Secret has the following benefits: - protects you from accidental (or unwanted) updates that could cause applications outages -- improves performance of your cluster by significantly reducing load on kube-apiserver, by -closing watches for secrets marked as immutable. +- (for clusters that extensively use Secrets - at least tens of thousands of unique Secret + to Pod mounts), switching to immutable Secrets improves the performance of your cluster + by significantly reducing load on kube-apiserver. The kubelet does not need to maintain + a [watch] on any Secrets that are marked as immutable. -This feature is controlled by the `ImmutableEphemeralVolumes` -[feature gate](/docs/reference/command-line-tools-reference/feature-gates/), -which is enabled by default since v1.19. You can create an immutable -Secret by setting the `immutable` field to `true`. For example, +### Marking a Secret as immutable {#secret-immutable-create} + +You can create an immutable Secret by setting the `immutable` field to `true`. For example, ```yaml apiVersion: v1 kind: Secret @@ -798,6 +1233,8 @@ data: immutable: true ``` +You can also update any existing mutable Secret to make it immutable. + {{< note >}} Once a Secret or ConfigMap is marked as immutable, it is _not_ possible to revert this change nor to mutate the contents of the `data` field. You can only delete and recreate the Secret. @@ -805,388 +1242,10 @@ Existing Pods maintain a mount point to the deleted Secret - it is recommended t these pods. {{< /note >}} -### Using imagePullSecrets +## Information security for Secrets -The `imagePullSecrets` field is a list of references to secrets in the same namespace. -You can use an `imagePullSecrets` to pass a secret that contains a Docker (or other) image registry -password to the kubelet. The kubelet uses this information to pull a private image on behalf of your Pod. -See the [PodSpec API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) for more information about the `imagePullSecrets` field. - -#### Manually specifying an imagePullSecret - -You can learn how to specify `ImagePullSecrets` from the [container images documentation](/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod). - -### Arranging for imagePullSecrets to be automatically attached - -You can manually create `imagePullSecrets`, and reference it from -a ServiceAccount. Any Pods created with that ServiceAccount -or created with that ServiceAccount by default, will get their `imagePullSecrets` -field set to that of the service account. -See [Add ImagePullSecrets to a service account](/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) - for a detailed explanation of that process. - -## Details - -### Restrictions - -Secret volume sources are validated to ensure that the specified object -reference actually points to an object of type Secret. Therefore, a secret -needs to be created before any Pods that depend on it. - -Secret resources reside in a {{< glossary_tooltip text="namespace" term_id="namespace" >}}. -Secrets can only be referenced by Pods in that same namespace. - -Individual secrets are limited to 1MiB in size. This is to discourage creation -of very large secrets which would exhaust the API server and kubelet memory. -However, creation of many smaller secrets could also exhaust memory. More -comprehensive limits on memory usage due to secrets is a planned feature. - -The kubelet only supports the use of secrets for Pods where the secrets -are obtained from the API server. -This includes any Pods created using `kubectl`, or indirectly via a replication -controller. It does not include Pods created as a result of the kubelet -`--manifest-url` flag, its `--config` flag, or its REST API (these are -not common ways to create Pods). -The `spec` of a {{< glossary_tooltip text="static Pod" term_id="static-pod" >}} cannot refer to a Secret -or any other API objects. - - -Secrets must be created before they are consumed in Pods as environment -variables unless they are marked as optional. References to secrets that do -not exist will prevent the Pod from starting. - -References (`secretKeyRef` field) to keys that do not exist in a named Secret -will prevent the Pod from starting. - -Secrets used to populate environment variables by the `envFrom` field that have keys -that are considered invalid environment variable names will have those keys -skipped. The Pod will be allowed to start. There will be an event whose -reason is `InvalidVariableNames` and the message will contain the list of -invalid keys that were skipped. The example shows a pod which refers to the -default/mysecret that contains 2 invalid keys: `1badkey` and `2alsobad`. - -```shell -kubectl get events -``` - -The output is similar to: - -``` -LASTSEEN FIRSTSEEN COUNT NAME KIND SUBOBJECT TYPE REASON -0s 0s 1 dapi-test-pod Pod Warning InvalidEnvironmentVariableNames kubelet, 127.0.0.1 Keys [1badkey, 2alsobad] from the EnvFrom secret default/mysecret were skipped since they are considered invalid environment variable names. -``` - -### Secret and Pod lifetime interaction - -When a Pod is created by calling the Kubernetes API, there is no check if a referenced -secret exists. Once a Pod is scheduled, the kubelet will try to fetch the -secret value. If the secret cannot be fetched because it does not exist or -because of a temporary lack of connection to the API server, the kubelet will -periodically retry. It will report an event about the Pod explaining the -reason it is not started yet. Once the secret is fetched, the kubelet will -create and mount a volume containing it. None of the Pod's containers will -start until all the Pod's volumes are mounted. - -## Use cases - -### Use-Case: As container environment variables - -Create a secret - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -type: Opaque -data: - USER_NAME: YWRtaW4= - PASSWORD: MWYyZDFlMmU2N2Rm -``` - -Create the Secret: - -```shell -kubectl apply -f mysecret.yaml -``` - -Use `envFrom` to define all of the Secret's data as container environment variables. The key from the Secret becomes the environment variable name in the Pod. - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: secret-test-pod -spec: - containers: - - name: test-container - image: k8s.gcr.io/busybox - command: [ "/bin/sh", "-c", "env" ] - envFrom: - - secretRef: - name: mysecret - restartPolicy: Never -``` - -### Use-Case: Pod with ssh keys - -Create a secret containing some ssh keys: - -```shell -kubectl create secret generic ssh-key-secret --from-file=ssh-privatekey=/path/to/.ssh/id_rsa --from-file=ssh-publickey=/path/to/.ssh/id_rsa.pub -``` - -The output is similar to: - -``` -secret "ssh-key-secret" created -``` - -You can also create a `kustomization.yaml` with a `secretGenerator` field containing ssh keys. - -{{< caution >}} -Think carefully before sending your own ssh keys: other users of the cluster may have access to the secret. Use a service account which you want to be accessible to all the users with whom you share the Kubernetes cluster, and can revoke this account if the users are compromised. -{{< /caution >}} - -Now you can create a Pod which references the secret with the ssh key and -consumes it in a volume: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: secret-test-pod - labels: - name: secret-test -spec: - volumes: - - name: secret-volume - secret: - secretName: ssh-key-secret - containers: - - name: ssh-test-container - image: mySshImage - volumeMounts: - - name: secret-volume - readOnly: true - mountPath: "/etc/secret-volume" -``` - -When the container's command runs, the pieces of the key will be available in: - -``` -/etc/secret-volume/ssh-publickey -/etc/secret-volume/ssh-privatekey -``` - -The container is then free to use the secret data to establish an ssh connection. - -### Use-Case: Pods with prod / test credentials - -This example illustrates a Pod which consumes a secret containing production -credentials and another Pod which consumes a secret with test environment -credentials. - -You can create a `kustomization.yaml` with a `secretGenerator` field or run -`kubectl create secret`. - -```shell -kubectl create secret generic prod-db-secret --from-literal=username=produser --from-literal=password=Y4nys7f11 -``` - -The output is similar to: - -``` -secret "prod-db-secret" created -``` - -You can also create a secret for test environment credentials. - -```shell -kubectl create secret generic test-db-secret --from-literal=username=testuser --from-literal=password=iluvtests -``` - -The output is similar to: - -``` -secret "test-db-secret" created -``` - -{{< note >}} -Special characters such as `$`, `\`, `*`, `=`, and `!` will be interpreted by your [shell](https://en.wikipedia.org/wiki/Shell_(computing)) and require escaping. -In most shells, the easiest way to escape the password is to surround it with single quotes (`'`). -For example, if your actual password is `S!B\*d$zDsb=`, you should execute the command this way: - -```shell -kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password='S!B\*d$zDsb=' -``` - -You do not need to escape special characters in passwords from files (`--from-file`). -{{< /note >}} - -Now make the Pods: - -```shell -cat < pod.yaml -apiVersion: v1 -kind: List -items: -- kind: Pod - apiVersion: v1 - metadata: - name: prod-db-client-pod - labels: - name: prod-db-client - spec: - volumes: - - name: secret-volume - secret: - secretName: prod-db-secret - containers: - - name: db-client-container - image: myClientImage - volumeMounts: - - name: secret-volume - readOnly: true - mountPath: "/etc/secret-volume" -- kind: Pod - apiVersion: v1 - metadata: - name: test-db-client-pod - labels: - name: test-db-client - spec: - volumes: - - name: secret-volume - secret: - secretName: test-db-secret - containers: - - name: db-client-container - image: myClientImage - volumeMounts: - - name: secret-volume - readOnly: true - mountPath: "/etc/secret-volume" -EOF -``` - -Add the pods to the same kustomization.yaml: - -```shell -cat <> kustomization.yaml -resources: -- pod.yaml -EOF -``` - -Apply all those objects on the API server by running: - -```shell -kubectl apply -k . -``` - -Both containers will have the following files present on their filesystems with the values for each container's environment: - -``` -/etc/secret-volume/username -/etc/secret-volume/password -``` - -Note how the specs for the two Pods differ only in one field; this facilitates -creating Pods with different capabilities from a common Pod template. - -You could further simplify the base Pod specification by using two service accounts: - -1. `prod-user` with the `prod-db-secret` -1. `test-user` with the `test-db-secret` - -The Pod specification is shortened to: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: prod-db-client-pod - labels: - name: prod-db-client -spec: - serviceAccount: prod-db-client - containers: - - name: db-client-container - image: myClientImage -``` - -### Use-case: dotfiles in a secret volume - -You can make your data "hidden" by defining a key that begins with a dot. -This key represents a dotfile or "hidden" file. For example, when the following secret -is mounted into a volume, `secret-volume`: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: dotfile-secret -data: - .secret-file: dmFsdWUtMg0KDQo= ---- -apiVersion: v1 -kind: Pod -metadata: - name: secret-dotfiles-pod -spec: - volumes: - - name: secret-volume - secret: - secretName: dotfile-secret - containers: - - name: dotfile-test-container - image: k8s.gcr.io/busybox - command: - - ls - - "-l" - - "/etc/secret-volume" - volumeMounts: - - name: secret-volume - readOnly: true - mountPath: "/etc/secret-volume" -``` - -The volume will contain a single file, called `.secret-file`, and -the `dotfile-test-container` will have this file present at the path -`/etc/secret-volume/.secret-file`. - -{{< note >}} -Files beginning with dot characters are hidden from the output of `ls -l`; -you must use `ls -la` to see them when listing directory contents. -{{< /note >}} - -### Use-case: Secret visible to one container in a Pod - -Consider a program that needs to handle HTTP requests, do some complex business -logic, and then sign some messages with an HMAC. Because it has complex -application logic, there might be an unnoticed remote file reading exploit in -the server, which could expose the private key to an attacker. - -This could be divided into two processes in two containers: a frontend container -which handles user interaction and business logic, but which cannot see the -private key; and a signer container that can see the private key, and responds -to simple signing requests from the frontend (for example, over localhost networking). - -With this partitioned approach, an attacker now has to trick the application -server into doing something rather arbitrary, which may be harder than getting -it to read a file. - - - -## Best practices - -### Clients that use the Secret API - -When deploying applications that interact with the Secret API, you should -limit access using [authorization policies]( -/docs/reference/access-authn-authz/authorization/) such as [RBAC]( -/docs/reference/access-authn-authz/rbac/). +Although ConfigMap and Secret work similarly, Kubernetes applies some additional +protection for Secret objects. Secrets often hold values that span a spectrum of importance, many of which can cause escalations within Kubernetes (e.g. service account tokens) and to @@ -1194,78 +1253,78 @@ external systems. Even if an individual app can reason about the power of the Secrets it expects to interact with, other apps within the same namespace can render those assumptions invalid. -For these reasons `watch` and `list` requests for secrets within a namespace are -extremely powerful capabilities and should be avoided, since listing secrets allows -the clients to inspect the values of all secrets that are in that namespace. The ability to -`watch` and `list` all secrets in a cluster should be reserved for only the most -privileged, system-level components. +A Secret is only sent to a node if a Pod on that node requires it. +For mounting secrets into Pods, the kubelet stores a copy of the data into a `tmpfs` +so that the confidential data is not written to durable storage. +Once the Pod that depends on the Secret is deleted, the kubelet deletes its local copy +of the confidential data from the Secret. -Applications that need to access the Secret API should perform `get` requests on -the secrets they need. This lets administrators restrict access to all secrets -while [white-listing access to individual instances](/docs/reference/access-authn-authz/rbac/#referring-to-resources) that -the app needs. +There may be several containers in a Pod. By default, containers you define +only have access to the default ServiceAccount and its related Secret. +You must explicitly define environment variables or map a volume into a +container in order to provide access to any other Secret. -For improved performance over a looping `get`, clients can design resources that -reference a secret then `watch` the resource, re-requesting the secret when the -reference changes. Additionally, a ["bulk watch" API](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/bulk_watch.md) -to let clients `watch` individual resources has also been proposed, and will likely -be available in future releases of Kubernetes. +There may be Secrets for several Pods on the same node. However, only the +Secrets that a Pod requests are potentially visible within its containers. +Therefore, one Pod does not have access to the Secrets of another Pod. -## Security properties +{{< warning >}} +Any privileged containers on a node are liable to have access to all Secrets used +on that node. +{{< /warning >}} -### Protections -Because secrets can be created independently of the Pods that use -them, there is less risk of the secret being exposed during the workflow of -creating, viewing, and editing Pods. The system can also take additional -precautions with Secrets, such as avoiding writing them to disk where -possible. +### Security recommendations for developers -A secret is only sent to a node if a Pod on that node requires it. -The kubelet stores the secret into a `tmpfs` so that the secret is not written -to disk storage. Once the Pod that depends on the secret is deleted, the kubelet -will delete its local copy of the secret data as well. +- Applications still need to protect the value of confidential information after reading it + from an environment variable or volume. For example, your application must avoid logging + the secret data in the clear or transmitting it to an untrusted party. +- If you are defining multiple containers in a Pod, and only one of those + containers needs access to a Secret, define the volume mount or environment + variable configuration so that the other containers do not have access to that + Secret. +- If you configure a Secret through a {{< glossary_tooltip text="manifest" term_id="manifest" >}}, + with the secret data encoded as base64, sharing this file or checking it in to a + source repository means the secret is available to everyone who can read the manifest. + Base64 encoding is _not_ an encryption method, it provides no additional confidentiality + over plain text. +- When deploying applications that interact with the Secret API, you should + limit access using + [authorization policies](/docs/reference/access-authn-authz/authorization/) such as + [RBAC]( /docs/reference/access-authn-authz/rbac/). +- In the Kubernetes API, `watch` and `list` requests for Secrets within a namespace + are extremely powerful capabilities. Avoid granting this access where feasible, since + listing Secrets allows the clients to inspect the values of every Secret in that + namespace. -There may be secrets for several Pods on the same node. However, only the -secrets that a Pod requests are potentially visible within its containers. -Therefore, one Pod does not have access to the secrets of another Pod. +### Security recommendations for cluster administrators -There may be several containers in a Pod. However, each container in a Pod has -to request the secret volume in its `volumeMounts` for it to be visible within -the container. This can be used to construct useful [security partitions at the -Pod level](#use-case-secret-visible-to-one-container-in-a-pod). +{{< caution >}} +A user who can create a Pod that uses a Secret can also see the value of that Secret. Even +if cluster policies do not allow a user to read the Secret directly, the same user could +have access to run a Pod that then exposes the Secret. +{{< /caution >}} -On most Kubernetes distributions, communication between users -and the API server, and from the API server to the kubelets, is protected by SSL/TLS. -Secrets are protected when transmitted over these channels. - -{{< feature-state for_k8s_version="v1.13" state="beta" >}} - -You can enable [encryption at rest](/docs/tasks/administer-cluster/encrypt-data/) -for secret data, so that the secrets are not stored in the clear into {{< glossary_tooltip term_id="etcd" >}}. - -### Risks - - - In the API server, secret data is stored in {{< glossary_tooltip term_id="etcd" >}}; - therefore: - - Administrators should enable encryption at rest for cluster data (requires v1.13 or later). - - Administrators should limit access to etcd to admin users. - - Administrators may want to wipe/shred disks used by etcd when no longer in use. - - If running etcd in a cluster, administrators should make sure to use SSL/TLS - for etcd peer-to-peer communication. - - If you configure the secret through a manifest (JSON or YAML) file which has - the secret data encoded as base64, sharing this file or checking it in to a - source repository means the secret is compromised. Base64 encoding is _not_ an - encryption method and is considered the same as plain text. - - Applications still need to protect the value of secret after reading it from the volume, - such as not accidentally logging it or transmitting it to an untrusted party. - - A user who can create a Pod that uses a secret can also see the value of that secret. Even - if the API server policy does not allow that user to read the Secret, the user could - run a Pod which exposes the secret. +- Reserve the ability to `watch` or `list` all secrets in a cluster (using the Kubernetes + API), so that only the most privileged, system-level components can perform this action. +- When deploying applications that interact with the Secret API, you should + limit access using + [authorization policies](/docs/reference/access-authn-authz/authorization/) such as + [RBAC]( /docs/reference/access-authn-authz/rbac/). +- In the API server, objects (including Secrets) are persisted into + {{< glossary_tooltip term_id="etcd" >}}; therefore: + - only allow cluster admistrators to access etcd (this includes read-only access); + - enable [encryption at rest](/docs/tasks/administer-cluster/encrypt-data/) + for Secret objects, so that the data of these Secrets are not stored in the clear + into {{< glossary_tooltip term_id="etcd" >}}; + - consider wiping / shredding the durable storage used by etcd once it is + no longer in use; + - if there are multiple etcd instances, make sure that etcd is + using SSL/TLS for communication between etcd peers. ## {{% heading "whatsnext" %}} -- Learn how to [manage Secret using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/) -- Learn how to [manage Secret using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/) -- Learn how to [manage Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/) +- Learn how to [manage Secrets using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/) +- Learn how to [manage Secrets using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/) +- Learn how to [manage Secrets using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/) - Read the [API reference](/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/) for `Secret` diff --git a/content/en/docs/concepts/containers/images.md b/content/en/docs/concepts/containers/images.md index 3512ed2098..c07880a458 100644 --- a/content/en/docs/concepts/containers/images.md +++ b/content/en/docs/concepts/containers/images.md @@ -29,8 +29,7 @@ and possibly a port number as well; for example: `fictional.registry.example:104 If you don't specify a registry hostname, Kubernetes assumes that you mean the Docker public registry. -After the image name part you can add a _tag_ (as also using with commands such -as `docker` and `podman`). +After the image name part you can add a _tag_ (in the same way you would when using with commands like `docker` or `podman`). Tags let you identify different versions of the same series of images. Image tags consist of lowercase and uppercase letters, digits, underscores (`_`), @@ -91,7 +90,7 @@ the image's digest; replace `:` with `@` (for example, `image@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`). -When using image tags, if the image registry were to change the code that the tag on that image represents, you might end up with a mix of Pods running the old and new code. An image digest uniquely identifies a specific version of the image, so Kubernetes runs the same code every time it starts a container with that image name and digest specified. Specifying an image fixes the code that you run so that a change at the registry cannot lead to that mix of versions. +When using image tags, if the image registry were to change the code that the tag on that image represents, you might end up with a mix of Pods running the old and new code. An image digest uniquely identifies a specific version of the image, so Kubernetes runs the same code every time it starts a container with that image name and digest specified. Specifying an image by digest fixes the code that you run so that a change at the registry cannot lead to that mix of versions. There are third-party [admission controllers](/docs/reference/access-authn-authz/admission-controllers/) that mutate Pods (and pod templates) when they are created, so that the @@ -175,95 +174,11 @@ These options are explained in more detail below. ### Configuring nodes to authenticate to a private registry -If you run Docker on your nodes, you can configure the Docker container -runtime to authenticate to a private container registry. +Specific instructions for setting credentials depends on the container runtime and registry you chose to use. You should refer to your solution's documentation for the most accurate information. -This approach is suitable if you can control node configuration. - -{{< note >}} -Default Kubernetes only supports the `auths` and `HttpHeaders` section in Docker configuration. -Docker credential helpers (`credHelpers` or `credsStore`) are not supported. -{{< /note >}} - - -Docker stores keys for private registries in the `$HOME/.dockercfg` or `$HOME/.docker/config.json` file. If you put the same file -in the search paths list below, kubelet uses it as the credential provider when pulling images. - -* `{--root-dir:-/var/lib/kubelet}/config.json` -* `{cwd of kubelet}/config.json` -* `${HOME}/.docker/config.json` -* `/.docker/config.json` -* `{--root-dir:-/var/lib/kubelet}/.dockercfg` -* `{cwd of kubelet}/.dockercfg` -* `${HOME}/.dockercfg` -* `/.dockercfg` - -{{< note >}} -You may have to set `HOME=/root` explicitly in the environment of the kubelet process. -{{< /note >}} - -Here are the recommended steps to configuring your nodes to use a private registry. In this -example, run these on your desktop/laptop: - - 1. Run `docker login [server]` for each set of credentials you want to use. This updates `$HOME/.docker/config.json` on your PC. - 1. View `$HOME/.docker/config.json` in an editor to ensure it contains only the credentials you want to use. - 1. Get a list of your nodes; for example: - - if you want the names: `nodes=$( kubectl get nodes -o jsonpath='{range.items[*].metadata}{.name} {end}' )` - - if you want to get the IP addresses: `nodes=$( kubectl get nodes -o jsonpath='{range .items[*].status.addresses[?(@.type=="ExternalIP")]}{.address} {end}' )` - 1. Copy your local `.docker/config.json` to one of the search paths list above. - - for example, to test this out: `for n in $nodes; do scp ~/.docker/config.json root@"$n":/var/lib/kubelet/config.json; done` - -{{< note >}} -For production clusters, use a configuration management tool so that you can apply this -setting to all the nodes where you need it. -{{< /note >}} - -Verify by creating a Pod that uses a private image; for example: - -```shell -kubectl apply -f - <}} @@ -362,6 +278,8 @@ Kubernetes supports specifying container image registry keys on a Pod. #### Creating a Secret with a Docker config +You need to know the username, registry password and client email address for authenticating +to the registry, as well as its hostname. Run the following command, substituting the appropriate uppercase values: ```shell @@ -426,14 +344,13 @@ There are a number of solutions for configuring private registries. Here are so common use cases and suggested solutions. 1. Cluster running only non-proprietary (e.g. open-source) images. No need to hide images. - - Use public images on the Docker hub. + - Use public images from a public registry - No configuration required. - Some cloud providers automatically cache or mirror public images, which improves availability and reduces the time to pull images. 1. Cluster running some proprietary images which should be hidden to those outside the company, but visible to all cluster users. - - Use a hosted private [Docker registry](https://docs.docker.com/registry/). - - It may be hosted on the [Docker Hub](https://hub.docker.com/signup), or elsewhere. - - Manually configure .docker/config.json on each node as described above. + - Use a hosted private registry + - Manual configuration may be required on the nodes that need to access to private registry - Or, run an internal private registry behind your firewall with open read access. - No Kubernetes configuration is required. - Use a hosted container image registry service that controls image access @@ -450,8 +367,6 @@ common use cases and suggested solutions. If you need access to multiple registries, you can create one secret for each registry. -Kubelet will merge any `imagePullSecrets` into a single virtual `.docker/config.json` - ## {{% heading "whatsnext" %}} diff --git a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md index 8b201e70e6..97dfa3860e 100644 --- a/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md +++ b/content/en/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins.md @@ -344,7 +344,7 @@ pluginapi.Device{ID: "25102017", Health: pluginapi.Healthy, Topology:&pluginapi. Here are some examples of device plugin implementations: * The [AMD GPU device plugin](https://github.com/RadeonOpenCompute/k8s-device-plugin) -* The [Intel device plugins](https://github.com/intel/intel-device-plugins-for-kubernetes) for Intel GPU, FPGA and QuickAssist devices +* The [Intel device plugins](https://github.com/intel/intel-device-plugins-for-kubernetes) for Intel GPU, FPGA, QAT, VPU, SGX, DSA, DLB and IAA devices * The [KubeVirt device plugins](https://github.com/kubevirt/kubernetes-device-plugins) for hardware-assisted virtualization * The [NVIDIA GPU device plugin](https://github.com/NVIDIA/k8s-device-plugin) * Requires [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) 2.0, which allows you to run GPU-enabled Docker containers. diff --git a/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md b/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md index 462428800c..c24e8a8c94 100644 --- a/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md +++ b/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md @@ -12,158 +12,181 @@ weight: 20 You can constrain a {{< glossary_tooltip text="Pod" term_id="pod" >}} so that it can only run on particular set of -{{< glossary_tooltip text="Node(s)" term_id="node" >}}. +{{< glossary_tooltip text="node(s)" term_id="node" >}}. There are several ways to do this and the recommended approaches all use [label selectors](/docs/concepts/overview/working-with-objects/labels/) to facilitate the selection. Generally such constraints are unnecessary, as the scheduler will automatically do a reasonable placement -(e.g. spread your pods across nodes so as not place the pod on a node with insufficient free resources, etc.) -but there are some circumstances where you may want to control which node the pod deploys to - for example to ensure -that a pod ends up on a machine with an SSD attached to it, or to co-locate pods from two different +(for example, spreading your Pods across nodes so as not place Pods on a node with insufficient free resources). +However, there are some circumstances where you may want to control which node +the Pod deploys to, for example, to ensure that a Pod ends up on a node with an SSD attached to it, or to co-locate Pods from two different services that communicate a lot into the same availability zone. - +You can use any of the following methods to choose where Kubernetes schedules +specific Pods: + + * [nodeSelector](#nodeselector) field matching against [node labels](#built-in-node-labels) + * [Affinity and anti-affinity](#affinity-and-anti-affinity) + * [nodeName](#nodename) field + +## Node labels {#built-in-node-labels} + +Like many other Kubernetes objects, nodes have +[labels](/docs/concepts/overview/working-with-objects/labels/). You can [attach labels manually](/docs/tasks/confiure-pod-container/assign-pods-nodes/#add-a-label-to-a-node). +Kubernetes also populates a standard set of labels on all nodes in a cluster. See [Well-Known Labels, Annotations and Taints](/docs/reference/labels-annotations-taints/) +for a list of common node labels. + +{{}} +The value of these labels is cloud provider specific and is not guaranteed to be reliable. +For example, the value of `kubernetes.io/hostname` may be the same as the node name in some environments +and a different value in other environments. +{{}} + +### Node isolation/restriction + +Adding labels to nodes allows you to target Pods for scheduling on specific +nodes or groups of nodes. You can use this functionality to ensure that specific +Pods only run on nodes with certain isolation, security, or regulatory +properties. + +If you use labels for node isolation, choose label keys that the {{}} +cannot modify. This prevents a compromised node from setting those labels on +itself so that the scheduler schedules workloads onto the compromised node. + +The [`NodeRestriction` admission plugin](/docs/reference/access-authn-authz/admission-controllers/#noderestriction) +prevents the kubelet from setting or modifying labels with a +`node-restriction.kubernetes.io/` prefix. + +To make use of that label prefix for node isolation: + +1. Ensure you are using the [Node authorizer](/docs/reference/access-authn-authz/node/) and have _enabled_ the `NodeRestriction` admission plugin. +2. Add labels with the `node-restriction.kubernetes.io/` prefix to your nodes, and use those labels in your [node selectors](#nodeselector). + For example, `example.com.node-restriction.kubernetes.io/fips=true` or `example.com.node-restriction.kubernetes.io/pci-dss=true`. + ## nodeSelector `nodeSelector` is the simplest recommended form of node selection constraint. -`nodeSelector` is a field of PodSpec. It specifies a map of key-value pairs. For the pod to be eligible -to run on a node, the node must have each of the indicated key-value pairs as labels (it can have -additional labels as well). The most common usage is one key-value pair. +You can add the `nodeSelector` field to your Pod specification and specify the +[node labels](#built-in-node-labels) you want the target node to have. +Kubernetes only schedules the Pod onto nodes that have each of the labels you +specify. -Let's walk through an example of how to use `nodeSelector`. - -### Step Zero: Prerequisites - -This example assumes that you have a basic understanding of Kubernetes pods and that you have [set up a Kubernetes cluster](/docs/setup/). - -### Step One: Attach label to the node - -Run `kubectl get nodes` to get the names of your cluster's nodes. Pick out the one that you want to add a label to, and then run `kubectl label nodes =` to add a label to the node you've chosen. For example, if my node name is 'kubernetes-foo-node-1.c.a-robinson.internal' and my desired label is 'disktype=ssd', then I can run `kubectl label nodes kubernetes-foo-node-1.c.a-robinson.internal disktype=ssd`. - -You can verify that it worked by re-running `kubectl get nodes --show-labels` and checking that the node now has a label. You can also use `kubectl describe node "nodename"` to see the full list of labels of the given node. - -### Step Two: Add a nodeSelector field to your pod configuration - -Take whatever pod config file you want to run, and add a nodeSelector section to it, like this. For example, if this is my pod config: - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: nginx - labels: - env: test -spec: - containers: - - name: nginx - image: nginx -``` - -Then add a nodeSelector like so: - -{{< codenew file="pods/pod-nginx.yaml" >}} - -When you then run `kubectl apply -f https://k8s.io/examples/pods/pod-nginx.yaml`, -the Pod will get scheduled on the node that you attached the label to. You can -verify that it worked by running `kubectl get pods -o wide` and looking at the -"NODE" that the Pod was assigned to. - -## Interlude: built-in node labels {#built-in-node-labels} - -In addition to labels you [attach](#step-one-attach-label-to-the-node), nodes come pre-populated -with a standard set of labels. See [Well-Known Labels, Annotations and Taints](/docs/reference/labels-annotations-taints/) for a list of these. - -{{< note >}} -The value of these labels is cloud provider specific and is not guaranteed to be reliable. -For example, the value of `kubernetes.io/hostname` may be the same as the Node name in some environments -and a different value in other environments. -{{< /note >}} - -## Node isolation/restriction - -Adding labels to Node objects allows targeting pods to specific nodes or groups of nodes. -This can be used to ensure specific pods only run on nodes with certain isolation, security, or regulatory properties. -When using labels for this purpose, choosing label keys that cannot be modified by the kubelet process on the node is strongly recommended. -This prevents a compromised node from using its kubelet credential to set those labels on its own Node object, -and influencing the scheduler to schedule workloads to the compromised node. - -The `NodeRestriction` admission plugin prevents kubelets from setting or modifying labels with a `node-restriction.kubernetes.io/` prefix. -To make use of that label prefix for node isolation: - -1. Ensure you are using the [Node authorizer](/docs/reference/access-authn-authz/node/) and have _enabled_ the [NodeRestriction admission plugin](/docs/reference/access-authn-authz/admission-controllers/#noderestriction). -2. Add labels under the `node-restriction.kubernetes.io/` prefix to your Node objects, and use those labels in your node selectors. -For example, `example.com.node-restriction.kubernetes.io/fips=true` or `example.com.node-restriction.kubernetes.io/pci-dss=true`. +See [Assign Pods to Nodes](/docs/tasks/configure-pod-container/assign-pods-nodes) for more +information. ## Affinity and anti-affinity -`nodeSelector` provides a very simple way to constrain pods to nodes with particular labels. The affinity/anti-affinity -feature, greatly expands the types of constraints you can express. The key enhancements are +`nodeSelector` is the simplest way to constrain Pods to nodes with specific +labels. Affinity and anti-affinity expands the types of constraints you can +define. Some of the benefits of affinity and anti-affinity include: -1. The affinity/anti-affinity language is more expressive. The language offers more matching rules - besides exact matches created with a logical AND operation; -2. you can indicate that the rule is "soft"/"preference" rather than a hard requirement, so if the scheduler - can't satisfy it, the pod will still be scheduled; -3. you can constrain against labels on other pods running on the node (or other topological domain), - rather than against labels on the node itself, which allows rules about which pods can and cannot be co-located +* The affinity/anti-affinity language is more expressive. `nodeSelector` only + selects nodes with all the specified labels. Affinity/anti-affinity gives you + more control over the selection logic. +* You can indicate that a rule is *soft* or *preferred*, so that the scheduler + still schedules the Pod even if it can't find a matching node. +* You can constrain a Pod using labels on other Pods running on the node (or other topological domain), + instead of just node labels, which allows you to define rules for which Pods + can be co-located on a node. -The affinity feature consists of two types of affinity, "node affinity" and "inter-pod affinity/anti-affinity". -Node affinity is like the existing `nodeSelector` (but with the first two benefits listed above), -while inter-pod affinity/anti-affinity constrains against pod labels rather than node labels, as -described in the third item listed above, in addition to having the first and second properties listed above. +The affinity feature consists of two types of affinity: + +* *Node affinity* functions like the `nodeSelector` field but is more expressive and + allows you to specify soft rules. +* *Inter-pod affinity/anti-affinity* allows you to constrain Pods against labels + on other Pods. ### Node affinity -Node affinity is conceptually similar to `nodeSelector` -- it allows you to constrain which nodes your -pod is eligible to be scheduled on, based on labels on the node. +Node affinity is conceptually similar to `nodeSelector`, allowing you to constrain which nodes your +Pod can be scheduled on based on node labels. There are two types of node +affinity: -There are currently two types of node affinity, called `requiredDuringSchedulingIgnoredDuringExecution` and -`preferredDuringSchedulingIgnoredDuringExecution`. You can think of them as "hard" and "soft" respectively, -in the sense that the former specifies rules that *must* be met for a pod to be scheduled onto a node (similar to -`nodeSelector` but using a more expressive syntax), while the latter specifies *preferences* that the scheduler -will try to enforce but will not guarantee. The "IgnoredDuringExecution" part of the names means that, similar -to how `nodeSelector` works, if labels on a node change at runtime such that the affinity rules on a pod are no longer -met, the pod continues to run on the node. In the future we plan to offer -`requiredDuringSchedulingRequiredDuringExecution` which will be identical to `requiredDuringSchedulingIgnoredDuringExecution` -except that it will evict pods from nodes that cease to satisfy the pods' node affinity requirements. + * `requiredDuringSchedulingIgnoredDuringExecution`: The scheduler can't + schedule the Pod unless the rule is met. This functions like `nodeSelector`, + but with a more expressive syntax. + * `preferredDuringSchedulingIgnoredDuringExecution`: The scheduler tries to + find a node that meets the rule. If a matching node is not available, the + scheduler still schedules the Pod. -Thus an example of `requiredDuringSchedulingIgnoredDuringExecution` would be "only run the pod on nodes with Intel CPUs" -and an example `preferredDuringSchedulingIgnoredDuringExecution` would be "try to run this set of pods in failure -zone XYZ, but if it's not possible, then allow some to run elsewhere". +{{}} +In the preceding types, `IgnoredDuringExecution` means that if the node labels +change after Kubernetes schedules the Pod, the Pod continues to run. +{{}} -Node affinity is specified as field `nodeAffinity` of field `affinity` in the PodSpec. +You can specify node affinities using the `.spec.affinity.nodeAffinity` field in +your Pod spec. -Here's an example of a pod that uses node affinity: +For example, consider the following Pod spec: -{{< codenew file="pods/pod-with-node-affinity.yaml" >}} +{{}} -This node affinity rule says the pod can only be placed on a node with a label whose key is -`kubernetes.io/e2e-az-name` and whose value is either `e2e-az1` or `e2e-az2`. In addition, -among nodes that meet that criteria, nodes with a label whose key is `another-node-label-key` and whose -value is `another-node-label-value` should be preferred. +In this example, the following rules apply: -You can see the operator `In` being used in the example. The new node affinity syntax supports the following operators: `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt`. -You can use `NotIn` and `DoesNotExist` to achieve node anti-affinity behavior, or use -[node taints](/docs/concepts/scheduling-eviction/taint-and-toleration/) to repel pods from specific nodes. + * The node *must* have a label with the key `kubernetes.io/e2e-az-name` and + the value is either `e2e-az1` or `e2e-az2`. + * The node *preferably* has a label with the key `another-node-label-key` and + the value `another-node-label-value`. -If you specify both `nodeSelector` and `nodeAffinity`, *both* must be satisfied for the pod -to be scheduled onto a candidate node. +You can use the `operator` field to specify a logical operator for Kubernetes to use when +interpreting the rules. You can use `In`, `NotIn`, `Exists`, `DoesNotExist`, +`Gt` and `Lt`. -If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` types, then the pod can be scheduled onto a node **if one of the** `nodeSelectorTerms` can be satisfied. +`NotIn` and `DoesNotExist` allow you to define node anti-affinity behavior. +Alternatively, you can use [node taints](/docs/concepts/scheduling-eviction/taint-and-toleration/) +to repel Pods from specific nodes. -If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`, then the pod can be scheduled onto a node **only if all** `matchExpressions` is satisfied. +{{}} +If you specify both `nodeSelector` and `nodeAffinity`, *both* must be satisfied +for the Pod to be scheduled onto a node. -If you remove or change the label of the node where the pod is scheduled, the pod won't be removed. In other words, the affinity selection works only at the time of scheduling the pod. +If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` +types, then the Pod can be scheduled onto a node if one of the specified `nodeSelectorTerms` can be +satisfied. -The `weight` field in `preferredDuringSchedulingIgnoredDuringExecution` is in the range 1-100. For each node that meets all of the scheduling requirements (resource request, RequiredDuringScheduling affinity expressions, etc.), the scheduler will compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding MatchExpressions. This score is then combined with the scores of other priority functions for the node. The node(s) with the highest total score are the most preferred. +If you specify multiple `matchExpressions` associated with a single `nodeSelectorTerms`, +then the Pod can be scheduled onto a node only if all the `matchExpressions` are +satisfied. +{{}} + +See [Assign Pods to Nodes using Node Affinity](/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) +for more information. + +#### Node affinity weight + +You can specify a `weight` between 1 and 100 for each instance of the +`preferredDuringSchedulingIgnoredDuringExecution` affinity type. When the +scheduler finds nodes that meet all the other scheduling requirements of the Pod, the +scheduler iterates through every preferred rule that the node satisfies and adds the +value of the `weight` for that expression to a sum. + +The final sum is added to the score of other priority functions for the node. +Nodes with the highest total score are prioritized when the scheduler makes a +scheduling decision for the Pod. + +For example, consider the following Pod spec: + +{{}} + +If there are two possible nodes that match the +`requiredDuringSchedulingIgnoredDuringExecution` rule, one with the +`label-1:key-1` label and another with the `label-2:key-2` label, the scheduler +considers the `weight` of each node and adds the weight to the other scores for +that node, and schedules the Pod onto the node with the highest final score. + +{{}} +If you want Kubernetes to successfully schedule the Pods in this example, you +must have existing nodes with the `kubernetes.io/os=linux` label. +{{}} #### Node affinity per scheduling profile {{< feature-state for_k8s_version="v1.20" state="beta" >}} When configuring multiple [scheduling profiles](/docs/reference/scheduling/config/#multiple-profiles), you can associate -a profile with a Node affinity, which is useful if a profile only applies to a specific set of Nodes. -To do so, add an `addedAffinity` to the args of the [`NodeAffinity` plugin](/docs/reference/scheduling/config/#scheduling-plugins) +a profile with a node affinity, which is useful if a profile only applies to a specific set of nodes. +To do so, add an `addedAffinity` to the `args` field of the [`NodeAffinity` plugin](/docs/reference/scheduling/config/#scheduling-plugins) in the [scheduler configuration](/docs/reference/scheduling/config/). For example: ```yaml @@ -188,29 +211,41 @@ profiles: The `addedAffinity` is applied to all Pods that set `.spec.schedulerName` to `foo-scheduler`, in addition to the NodeAffinity specified in the PodSpec. -That is, in order to match the Pod, Nodes need to satisfy `addedAffinity` and the Pod's `.spec.NodeAffinity`. +That is, in order to match the Pod, nodes need to satisfy `addedAffinity` and +the Pod's `.spec.NodeAffinity`. -Since the `addedAffinity` is not visible to end users, its behavior might be unexpected to them. We -recommend to use node labels that have clear correlation with the profile's scheduler name. +Since the `addedAffinity` is not visible to end users, its behavior might be +unexpected to them. Use node labels that have a clear correlation to the +scheduler profile name. {{< note >}} -The DaemonSet controller, which [creates Pods for DaemonSets](/docs/concepts/workloads/controllers/daemonset/#scheduled-by-default-scheduler) -is not aware of scheduling profiles. For this reason, it is recommended that you keep a scheduler profile, such as the -`default-scheduler`, without any `addedAffinity`. Then, the Daemonset's Pod template should use this scheduler name. -Otherwise, some Pods created by the Daemonset controller might remain unschedulable. +The DaemonSet controller, which [creates Pods for DaemonSets](/docs/concepts/workloads/controllers/daemonset/#scheduled-by-default-scheduler), +does not support scheduling profiles. When the DaemonSet controller creates +Pods, the default Kubernetes scheduler places those Pods and honors any +`nodeAffinity` rules in the DaemonSet controller. {{< /note >}} ### Inter-pod affinity and anti-affinity -Inter-pod affinity and anti-affinity allow you to constrain which nodes your pod is eligible to be scheduled *based on -labels on pods that are already running on the node* rather than based on labels on nodes. The rules are of the form -"this pod should (or, in the case of anti-affinity, should not) run in an X if that X is already running one or more pods that meet rule Y". -Y is expressed as a LabelSelector with an optional associated list of namespaces; unlike nodes, because pods are namespaced -(and therefore the labels on pods are implicitly namespaced), -a label selector over pod labels must specify which namespaces the selector should apply to. Conceptually X is a topology domain -like node, rack, cloud provider zone, cloud provider region, etc. You express it using a `topologyKey` which is the -key for the node label that the system uses to denote such a topology domain; for example, see the label keys listed above -in the section [Interlude: built-in node labels](#built-in-node-labels). +Inter-pod affinity and anti-affinity allow you to constrain which nodes your +Pods can be scheduled on based on the labels of **Pods** already running on that +node, instead of the node labels. + +Inter-pod affinity and anti-affinity rules take the form "this +Pod should (or, in the case of anti-affinity, should not) run in an X if that X +is already running one or more Pods that meet rule Y", where X is a topology +domain like node, rack, cloud provider zone or region, or similar and Y is the +rule Kubernetes tries to satisfy. + +You express these rules (Y) as [label selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors) +with an optional associated list of namespaces. Pods are namespaced objects in +Kubernetes, so Pod labels also implicitly have namespaces. Any label selectors +for Pod labels should specify the namespaces in which Kubernetes should look for those +labels. + +You express the topology domain (X) using a `topologyKey`, which is the key for +the node label that the system uses to denote the domain. For examples, see +[Well-Known Labels, Annotations and Taints](/docs/reference/labels-annotations-taints/). {{< note >}} Inter-pod affinity and anti-affinity require substantial amount of @@ -219,80 +254,106 @@ not recommend using them in clusters larger than several hundred nodes. {{< /note >}} {{< note >}} -Pod anti-affinity requires nodes to be consistently labelled, in other words every node in the cluster must have an appropriate label matching `topologyKey`. If some or all nodes are missing the specified `topologyKey` label, it can lead to unintended behavior. +Pod anti-affinity requires nodes to be consistently labelled, in other words, +every node in the cluster must have an appropriate label matching `topologyKey`. +If some or all nodes are missing the specified `topologyKey` label, it can lead +to unintended behavior. {{< /note >}} -As with node affinity, there are currently two types of pod affinity and anti-affinity, called `requiredDuringSchedulingIgnoredDuringExecution` and -`preferredDuringSchedulingIgnoredDuringExecution` which denote "hard" vs. "soft" requirements. -See the description in the node affinity section earlier. -An example of `requiredDuringSchedulingIgnoredDuringExecution` affinity would be "co-locate the pods of service A and service B -in the same zone, since they communicate a lot with each other" -and an example `preferredDuringSchedulingIgnoredDuringExecution` anti-affinity would be "spread the pods from this service across zones" -(a hard requirement wouldn't make sense, since you probably have more pods than zones). +#### Types of inter-pod affinity and anti-affinity -Inter-pod affinity is specified as field `podAffinity` of field `affinity` in the PodSpec. -And inter-pod anti-affinity is specified as field `podAntiAffinity` of field `affinity` in the PodSpec. +Similar to [node affinity](#node-affinity) are two types of Pod affinity and +anti-affinity as follows: -#### An example of a pod that uses pod affinity: + * `requiredDuringSchedulingIgnoredDuringExecution` + * `preferredDuringSchedulingIgnoredDuringExecution` + +For example, you could use +`requiredDuringSchedulingIgnoredDuringExecution` affinity to tell the scheduler to +co-locate Pods of two services in the same cloud provider zone because they +communicate with each other a lot. Similarly, you could use +`preferredDuringSchedulingIgnoredDuringExecution` anti-affinity to spread Pods +from a service across multiple cloud provider zones. + +To use inter-pod affinity, use the `affinity.podAffinity` field in the Pod spec. +For inter-pod anti-affinity, use the `affinity.podAntiAffinity` field in the Pod +spec. + +#### Pod affinity example {#an-example-of-a-pod-that-uses-pod-affinity} + +Consider the following Pod spec: {{< codenew file="pods/pod-with-pod-affinity.yaml" >}} -The affinity on this pod defines one pod affinity rule and one pod anti-affinity rule. In this example, the -`podAffinity` is `requiredDuringSchedulingIgnoredDuringExecution` -while the `podAntiAffinity` is `preferredDuringSchedulingIgnoredDuringExecution`. The -pod affinity rule says that the pod can be scheduled onto a node only if that node is in the same zone -as at least one already-running pod that has a label with key "security" and value "S1". (More precisely, the pod is eligible to run -on node N if node N has a label with key `topology.kubernetes.io/zone` and some value V -such that there is at least one node in the cluster with key `topology.kubernetes.io/zone` and -value V that is running a pod that has a label with key "security" and value "S1".) The pod anti-affinity -rule says that the pod should not be scheduled onto a node if that node is in the same zone as a pod with -label having key "security" and value "S2". See the +This example defines one Pod affinity rule and one Pod anti-affinity rule. The +Pod affinity rule uses the "hard" +`requiredDuringSchedulingIgnoredDuringExecution`, while the anti-affinity rule +uses the "soft" `preferredDuringSchedulingIgnoredDuringExecution`. + +The affinity rule says that the scheduler can only schedule a Pod onto a node if +the node is in the same zone as one or more existing Pods with the label +`security=S1`. More precisely, the scheduler must place the Pod on a node that has the +`topology.kubernetes.io/zone=V` label, as long as there is at least one node in +that zone that currently has one or more Pods with the Pod label `security=S1`. + +The anti-affinity rule says that the scheduler should try to avoid scheduling +the Pod onto a node that is in the same zone as one or more Pods with the label +`security=S2`. More precisely, the scheduler should try to avoid placing the Pod on a node that has the +`topology.kubernetes.io/zone=R` label if there are other nodes in the +same zone currently running Pods with the `Security=S2` Pod label. + +See the [design doc](https://git.k8s.io/community/contributors/design-proposals/scheduling/podaffinity.md) -for many more examples of pod affinity and anti-affinity, both the `requiredDuringSchedulingIgnoredDuringExecution` -flavor and the `preferredDuringSchedulingIgnoredDuringExecution` flavor. +for many more examples of Pod affinity and anti-affinity. -The legal operators for pod affinity and anti-affinity are `In`, `NotIn`, `Exists`, `DoesNotExist`. +You can use the `In`, `NotIn`, `Exists` and `DoesNotExist` values in the +`operator` field for Pod affinity and anti-affinity. -In principle, the `topologyKey` can be any legal label-key. However, -for performance and security reasons, there are some constraints on topologyKey: +In principle, the `topologyKey` can be any allowed label key with the following +exceptions for performance and security reasons: -1. For pod affinity, empty `topologyKey` is not allowed in both `requiredDuringSchedulingIgnoredDuringExecution` -and `preferredDuringSchedulingIgnoredDuringExecution`. -2. For pod anti-affinity, empty `topologyKey` is also not allowed in both `requiredDuringSchedulingIgnoredDuringExecution` -and `preferredDuringSchedulingIgnoredDuringExecution`. -3. For `requiredDuringSchedulingIgnoredDuringExecution` pod anti-affinity, the admission controller `LimitPodHardAntiAffinityTopology` was introduced to limit `topologyKey` to `kubernetes.io/hostname`. If you want to make it available for custom topologies, you may modify the admission controller, or disable it. -4. Except for the above cases, the `topologyKey` can be any legal label-key. +* For Pod affinity and anti-affinity, an empty `topologyKey` field is not allowed in both `requiredDuringSchedulingIgnoredDuringExecution` + and `preferredDuringSchedulingIgnoredDuringExecution`. +* For `requiredDuringSchedulingIgnoredDuringExecution` Pod anti-affinity rules, + the admission controller `LimitPodHardAntiAffinityTopology` limits + `topologyKey` to `kubernetes.io/hostname`. You can modify or disable the + admission controller if you want to allow custom topologies. -In addition to `labelSelector` and `topologyKey`, you can optionally specify a list `namespaces` -of namespaces which the `labelSelector` should match against (this goes at the same level of the definition as `labelSelector` and `topologyKey`). -If omitted or empty, it defaults to the namespace of the pod where the affinity/anti-affinity definition appears. - -All `matchExpressions` associated with `requiredDuringSchedulingIgnoredDuringExecution` affinity and anti-affinity -must be satisfied for the pod to be scheduled onto a node. +In addition to `labelSelector` and `topologyKey`, you can optionally specify a list +of namespaces which the `labelSelector` should match against using the +`namespaces` field at the same level as `labelSelector` and `topologyKey`. +If omitted or empty, `namespaces` defaults to the namespace of the Pod where the +affinity/anti-affinity definition appears. #### Namespace selector {{< feature-state for_k8s_version="v1.22" state="beta" >}} -Users can also select matching namespaces using `namespaceSelector`, which is a label query over the set of namespaces. -The affinity term is applied to the union of the namespaces selected by `namespaceSelector` and the ones listed in the `namespaces` field. +You can also select matching namespaces using `namespaceSelector`, which is a label query over the set of namespaces. +The affinity term is applied to namespaces selected by both `namespaceSelector` and the `namespaces` field. Note that an empty `namespaceSelector` ({}) matches all namespaces, while a null or empty `namespaces` list and -null `namespaceSelector` means "this pod's namespace". +null `namespaceSelector` matches the namespace of the Pod where the rule is defined. +{{}} This feature is beta and enabled by default. You can disable it via the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) `PodAffinityNamespaceSelector` in both kube-apiserver and kube-scheduler. +{{}} -#### More Practical Use-cases +#### More practical use-cases -Interpod Affinity and AntiAffinity can be even more useful when they are used with higher -level collections such as ReplicaSets, StatefulSets, Deployments, etc. One can easily configure that a set of workloads should +Inter-pod affinity and anti-affinity can be even more useful when they are used with higher +level collections such as ReplicaSets, StatefulSets, Deployments, etc. These +rules allow you to configure that a set of workloads should be co-located in the same defined topology, eg., the same node. -##### Always co-located in the same node +Take, for example, a three-node cluster running a web application with an +in-memory cache like redis. You could use inter-pod affinity and anti-affinity +to co-locate the web servers with the cache as much as possible. -In a three node cluster, a web application has in-memory cache such as redis. We want the web-servers to be co-located with the cache as much as possible. - -Here is the yaml snippet of a simple redis deployment with three replicas and selector label `app=store`. The deployment has `PodAntiAffinity` configured to ensure the scheduler does not co-locate replicas on a single node. +In the following example Deployment for the redis cache, the replicas get the label `app=store`. The +`podAntiAffinity` rule tells the scheduler to avoid placing multiple replicas +with the `app=store` label on a single node. This creates each cache in a +separate node. ```yaml apiVersion: apps/v1 @@ -324,7 +385,10 @@ spec: image: redis:3.2-alpine ``` -The below yaml snippet of the webserver deployment has `podAntiAffinity` and `podAffinity` configured. This informs the scheduler that all its replicas are to be co-located with pods that have selector label `app=store`. This will also ensure that each web-server replica does not co-locate on a single node. +The following Deployment for the web servers creates replicas with the label `app=web-store`. The +Pod affinity rule tells the scheduler to place each replica on a node that has a +Pod with the label `app=store`. The Pod anti-affinity rule tells the scheduler +to avoid placing multiple `app=web-store` servers on a single node. ```yaml apiVersion: apps/v1 @@ -365,56 +429,37 @@ spec: image: nginx:1.16-alpine ``` -If we create the above two deployments, our three node cluster should look like below. +Creating the two preceding Deployments results in the following cluster layout, +where each web server is co-located with a cache, on three separate nodes. | node-1 | node-2 | node-3 | |:--------------------:|:-------------------:|:------------------:| | *webserver-1* | *webserver-2* | *webserver-3* | | *cache-1* | *cache-2* | *cache-3* | -As you can see, all the 3 replicas of the `web-server` are automatically co-located with the cache as expected. - -``` -kubectl get pods -o wide -``` -The output is similar to this: -``` -NAME READY STATUS RESTARTS AGE IP NODE -redis-cache-1450370735-6dzlj 1/1 Running 0 8m 10.192.4.2 kube-node-3 -redis-cache-1450370735-j2j96 1/1 Running 0 8m 10.192.2.2 kube-node-1 -redis-cache-1450370735-z73mh 1/1 Running 0 8m 10.192.3.1 kube-node-2 -web-server-1287567482-5d4dz 1/1 Running 0 7m 10.192.2.3 kube-node-1 -web-server-1287567482-6f7v5 1/1 Running 0 7m 10.192.4.3 kube-node-3 -web-server-1287567482-s330j 1/1 Running 0 7m 10.192.3.2 kube-node-2 -``` - -##### Never co-located in the same node - -The above example uses `PodAntiAffinity` rule with `topologyKey: "kubernetes.io/hostname"` to deploy the redis cluster so that -no two instances are located on the same host. -See [ZooKeeper tutorial](/docs/tutorials/stateful-application/zookeeper/#tolerating-node-failure) -for an example of a StatefulSet configured with anti-affinity for high availability, using the same technique. +See the [ZooKeeper tutorial](/docs/tutorials/stateful-application/zookeeper/#tolerating-node-failure) +for an example of a StatefulSet configured with anti-affinity for high +availability, using the same technique as this example. ## nodeName -`nodeName` is the simplest form of node selection constraint, but due -to its limitations it is typically not used. `nodeName` is a field of -PodSpec. If it is non-empty, the scheduler ignores the pod and the -kubelet running on the named node tries to run the pod. Thus, if -`nodeName` is provided in the PodSpec, it takes precedence over the -above methods for node selection. +`nodeName` is a more direct form of node selection than affinity or +`nodeSelector`. `nodeName` is a field in the Pod spec. If the `nodeName` field +is not empty, the scheduler ignores the Pod and the kubelet on the named node +tries to place the Pod on that node. Using `nodeName` overrules using +`nodeSelector` or affinity and anti-affinity rules. Some of the limitations of using `nodeName` to select nodes are: -- If the named node does not exist, the pod will not be run, and in +- If the named node does not exist, the Pod will not run, and in some cases may be automatically deleted. - If the named node does not have the resources to accommodate the - pod, the pod will fail and its reason will indicate why, + Pod, the Pod will fail and its reason will indicate why, for example OutOfmemory or OutOfcpu. - Node names in cloud environments are not always predictable or stable. -Here is an example of a pod config file using the `nodeName` field: +Here is an example of a Pod spec using the `nodeName` field: ```yaml apiVersion: v1 @@ -428,21 +473,16 @@ spec: nodeName: kube-01 ``` -The above pod will run on the node kube-01. - - +The above Pod will only run on the node `kube-01`. ## {{% heading "whatsnext" %}} - -[Taints](/docs/concepts/scheduling-eviction/taint-and-toleration/) allow a Node to *repel* a set of Pods. - -The design documents for -[node affinity](https://git.k8s.io/community/contributors/design-proposals/scheduling/nodeaffinity.md) -and for [inter-pod affinity/anti-affinity](https://git.k8s.io/community/contributors/design-proposals/scheduling/podaffinity.md) contain extra background information about these features. - -Once a Pod is assigned to a Node, the kubelet runs the Pod and allocates node-local resources. -The [topology manager](/docs/tasks/administer-cluster/topology-manager/) can take part in node-level -resource allocation decisions. +* Read more about [taints and tolerations](/docs/concepts/scheduling-eviction/taint-and-toleration/) . +* Read the design docs for [node affinity](https://git.k8s.io/community/contributors/design-proposals/scheduling/nodeaffinity.md) + and for [inter-pod affinity/anti-affinity](https://git.k8s.io/community/contributors/design-proposals/scheduling/podaffinity.md). +* Learn about how the [topology manager](/docs/tasks/administer-cluster/topology-manager/) takes part in node-level + resource allocation decisions. +* Learn how to use [nodeSelector](/docs/tasks/configure-pod-container/assign-pods-nodes/). +* Learn how to use [affinity and anti-affinity](/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/). diff --git a/content/en/docs/concepts/services-networking/ingress-controllers.md b/content/en/docs/concepts/services-networking/ingress-controllers.md index 08b715ac7b..5516306ffa 100644 --- a/content/en/docs/concepts/services-networking/ingress-controllers.md +++ b/content/en/docs/concepts/services-networking/ingress-controllers.md @@ -23,7 +23,7 @@ Kubernetes as a project supports and maintains [AWS](https://github.com/kubernet {{% thirdparty-content %}} -* [AKS Application Gateway Ingress Controller](https://azure.github.io/application-gateway-kubernetes-ingress/) is an ingress controller that configures the [Azure Application Gateway](https://docs.microsoft.com/azure/application-gateway/overview). +* [AKS Application Gateway Ingress Controller](https://docs.microsoft.com/azure/application-gateway/tutorial-ingress-controller-add-on-existing?toc=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fazure%2Faks%2Ftoc.json&bc=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fazure%2Fbread%2Ftoc.json) is an ingress controller that configures the [Azure Application Gateway](https://docs.microsoft.com/azure/application-gateway/overview). * [Ambassador](https://www.getambassador.io/) API Gateway is an [Envoy](https://www.envoyproxy.io)-based ingress controller. * [Apache APISIX ingress controller](https://github.com/apache/apisix-ingress-controller) is an [Apache APISIX](https://github.com/apache/apisix)-based ingress controller. diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md index fa07048b52..e1ca55ab80 100644 --- a/content/en/docs/concepts/services-networking/ingress.md +++ b/content/en/docs/concepts/services-networking/ingress.md @@ -88,13 +88,13 @@ has all the information needed to configure a load balancer or proxy server. Mos contains a list of rules matched against all incoming requests. Ingress resource only supports rules for directing HTTP(S) traffic. -If the `ingressClassName` is omitted, a [default Ingress class](#default-ingress-class) +If the `ingressClassName` is omitted, a [default Ingress class](#default-ingress-class) should be defined. -There are some ingress controllers, that work without the definition of a -default `IngressClass`. For example, the Ingress-NGINX controller can be -configured with a [flag](https://kubernetes.github.io/ingress-nginx/#what-is-the-flag-watch-ingress-without-class) -`--watch-ingress-without-class`. It is [recommended](https://kubernetes.github.io/ingress-nginx/#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do) though, to specify the +There are some ingress controllers, that work without the definition of a +default `IngressClass`. For example, the Ingress-NGINX controller can be +configured with a [flag](https://kubernetes.github.io/ingress-nginx/#what-is-the-flag-watch-ingress-without-class) +`--watch-ingress-without-class`. It is [recommended](https://kubernetes.github.io/ingress-nginx/#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do) though, to specify the default `IngressClass` as shown [below](#default-ingress-class). ### Ingress rules @@ -118,8 +118,14 @@ match a path in the spec. ### DefaultBackend {#default-backend} -An Ingress with no rules sends all traffic to a single default backend. The `defaultBackend` is conventionally a configuration option -of the [Ingress controller](/docs/concepts/services-networking/ingress-controllers) and is not specified in your Ingress resources. +An Ingress with no rules sends all traffic to a single default backend and `.spec.defaultBackend` +is the backend that should handle requests in that case. +The `defaultBackend` is conventionally a configuration option of the +[Ingress controller](/docs/concepts/services-networking/ingress-controllers) and +is not specified in your Ingress resources. +If no `.spec.rules` are specified, `.spec.defaultBackend` must be specified. +If `defaultBackend` is not set, the handling of requests that do not match any of the rules will be up to the +ingress controller (consult the documentation for your ingress controller to find out how it handles this case). If none of the hosts or paths match the HTTP request in the Ingress objects, the traffic is routed to your default backend. @@ -310,7 +316,7 @@ spec: parameters: # The parameters for this IngressClass are specified in an # IngressParameter (API group k8s.example.com) named "external-config", - # that's in the "external-configuration" configuration namespace. + # that's in the "external-configuration" namespace. scope: Namespace apiGroup: k8s.example.com kind: IngressParameter diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index 0298854137..cc23725a3c 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -109,12 +109,45 @@ field. {{< /note >}} Port definitions in Pods have names, and you can reference these names in the -`targetPort` attribute of a Service. This works even if there is a mixture -of Pods in the Service using a single configured name, with the same network -protocol available via different port numbers. -This offers a lot of flexibility for deploying and evolving your Services. -For example, you can change the port numbers that Pods expose in the next -version of your backend software, without breaking clients. +`targetPort` attribute of a Service. For example, we can bind the `targetPort` +of the Service to the Pod port in the following way: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: nginx + labels: + app.kubernetes.io/name: proxy +spec: + containers: + - name: nginx + image: nginx:11.14.2 + ports: + - containerPort: 80 + name: http-web-service + +--- +apiVersion: v1 +kind: Service +metadata: + name: nginx-service +spec: + selector: + app.kubernetes.io/name: proxy + ports: + - name: name-of-service-port + protocol: TCP + port: 80 + targetPort: http-web-service +``` + + +This works even if there is a mixture of Pods in the Service using a single +configured name, with the same network protocol available via different +port numbers. This offers a lot of flexibility for deploying and evolving +your Services. For example, you can change the port numbers that Pods expose +in the next version of your backend software, without breaking clients. The default protocol for Services is TCP; you can also use any other [supported protocol](#protocol-support). diff --git a/content/en/docs/concepts/services-networking/topology-aware-hints.md b/content/en/docs/concepts/services-networking/topology-aware-hints.md index 4cc4f4aa5e..cd02b4015c 100644 --- a/content/en/docs/concepts/services-networking/topology-aware-hints.md +++ b/content/en/docs/concepts/services-networking/topology-aware-hints.md @@ -19,6 +19,12 @@ those network endpoints can be routed closer to where it originated. For example, you can route traffic within a locality to reduce costs, or to improve network performance. +{{< note >}} +The "topology-aware hints" feature is at Beta stage and it is **NOT** enabled +by default. To try out this feature, you have to enable the `TopologyAwareHints` +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/). +{{< /note >}} + ## Motivation diff --git a/content/en/docs/concepts/storage/storage-classes.md b/content/en/docs/concepts/storage/storage-classes.md index 421a293737..788f592abe 100644 --- a/content/en/docs/concepts/storage/storage-classes.md +++ b/content/en/docs/concepts/storage/storage-classes.md @@ -87,7 +87,7 @@ for provisioning PVs. This field must be specified. You are not restricted to specifying the "internal" provisioners listed here (whose names are prefixed with "kubernetes.io" and shipped alongside Kubernetes). You can also run and specify external provisioners, -which are independent programs that follow a [specification](https://git.k8s.io/community/contributors/design-proposals/storage/volume-provisioning.md) +which are independent programs that follow a [specification](https://github.com/kubernetes/design-proposals-archive/blob/main/storage/volume-provisioning.md) defined by Kubernetes. Authors of external provisioners have full discretion over where their code lives, how the provisioner is shipped, how it needs to be run, what volume plugin it uses (including Flex), etc. The repository @@ -241,8 +241,8 @@ allowedTopologies: - matchLabelExpressions: - key: failure-domain.beta.kubernetes.io/zone values: - - us-central1-a - - us-central1-b + - us-central-1a + - us-central-1b ``` ## Parameters diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md index 62cac0f001..cafe51102b 100644 --- a/content/en/docs/concepts/workloads/controllers/cron-jobs.md +++ b/content/en/docs/concepts/workloads/controllers/cron-jobs.md @@ -69,7 +69,7 @@ takes you through this example in more detail). # │ │ │ ┌───────────── month (1 - 12) # │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday; # │ │ │ │ │ 7 is also Sunday on some systems) -# │ │ │ │ │ +# │ │ │ │ │ OR sun, mon, tue, wed, thu, fri, sat # │ │ │ │ │ # * * * * * ``` diff --git a/content/en/docs/concepts/workloads/controllers/daemonset.md b/content/en/docs/concepts/workloads/controllers/daemonset.md index 7eec771d7d..ffb1fbd614 100644 --- a/content/en/docs/concepts/workloads/controllers/daemonset.md +++ b/content/en/docs/concepts/workloads/controllers/daemonset.md @@ -107,7 +107,7 @@ If you do not specify either, then the DaemonSet controller will create Pods on ### Scheduled by default scheduler -{{< feature-state state="stable" for-kubernetes-version="1.17" >}} +{{< feature-state for_kubernetes_version="1.17" state="stable" >}} A DaemonSet ensures that all eligible nodes run a copy of a Pod. Normally, the node that a Pod runs on is selected by the Kubernetes scheduler. However, diff --git a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md index 07cf3c77a6..596d835d73 100644 --- a/content/en/docs/concepts/workloads/pods/pod-lifecycle.md +++ b/content/en/docs/concepts/workloads/pods/pod-lifecycle.md @@ -136,7 +136,7 @@ completion or failed for some reason. When you use `kubectl` to query a Pod with a container that is `Terminated`, you see a reason, an exit code, and the start and finish time for that container's period of execution. -If a container has a `preStop` hook configured, that runs before the container enters +If a container has a `preStop` hook configured, this hook runs before the container enters the `Terminated` state. ## Container restart policy {#restart-policy} diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index 30e1725859..68e8b89869 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -733,7 +733,7 @@ The following HTTP headers can be used to performing an impersonation request: * `Impersonate-User`: The username to act as. * `Impersonate-Group`: A group name to act as. Can be provided multiple times to set multiple groups. Optional. Requires "Impersonate-User". -* `Impersonate-Extra-( extra name )`: A dynamic header used to associate extra fields with the user. Optional. Requires "Impersonate-User". In order to be preserved consistently, `( extra name )` should be lower-case, and any characters which aren't [legal in HTTP header labels](https://tools.ietf.org/html/rfc7230#section-3.2.6) MUST be utf8 and [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1). +* `Impersonate-Extra-( extra name )`: A dynamic header used to associate extra fields with the user. Optional. Requires "Impersonate-User". In order to be preserved consistently, `( extra name )` must be lower-case, and any characters which aren't [legal in HTTP header labels](https://tools.ietf.org/html/rfc7230#section-3.2.6) MUST be utf8 and [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1). * `Impersonate-Uid`: A unique identifier that represents the user being impersonated. Optional. Requires "Impersonate-User". Kubernetes does not impose any format requirements on this string. {{< note >}} diff --git a/content/en/docs/reference/command-line-tools-reference/kubelet.md b/content/en/docs/reference/command-line-tools-reference/kubelet.md index dc23747c22..555414a6eb 100644 --- a/content/en/docs/reference/command-line-tools-reference/kubelet.md +++ b/content/en/docs/reference/command-line-tools-reference/kubelet.md @@ -163,14 +163,14 @@ kubelet [flags] --cloud-config string -The path to the cloud provider configuration file. Empty string for no configuration file. (DEPRECATED: will be removed in 1.23, in favor of removing cloud providers code from Kubelet.) +The path to the cloud provider configuration file. Empty string for no configuration file. (DEPRECATED: will be removed in 1.24 or later, in favor of removing cloud providers code from kubelet.) --cloud-provider string -The provider for cloud services. Set to empty string for running with no cloud provider. If set, the cloud provider determines the name of the node (consult cloud provider documentation to determine if and how the hostname is used). (DEPRECATED: will be removed in 1.23, in favor of removing cloud provider code from Kubelet.) +The provider for cloud services. Set to empty string for running with no cloud provider. If set, the cloud provider determines the name of the node (consult cloud provider documentation to determine if and how the hostname is used). (DEPRECATED: will be removed in 1.24 or later, in favor of removing cloud provider code from Kubelet.) @@ -297,7 +297,7 @@ kubelet [flags] --dynamic-config-dir string -The Kubelet will use this directory for checkpointing downloaded configurations and tracking configuration health. The Kubelet will create this directory if it does not already exist. The path may be absolute or relative; relative paths start at the Kubelet's current working directory. Providing this flag enables dynamic Kubelet configuration. The DynamicKubeletConfig feature gate must be enabled to pass this flag. (DEPRECATED: Feature DynamicKubeletConfig is deprecated in 1.22 and will not move to GA. It is planned to be removed from Kubernetes in the version 1.23. Please use alternative ways to update kubelet configuration.) +The Kubelet will use this directory for checkpointing downloaded configurations and tracking configuration health. The Kubelet will create this directory if it does not already exist. The path may be absolute or relative; relative paths start at the Kubelet's current working directory. Providing this flag enables dynamic Kubelet configuration. The DynamicKubeletConfig feature gate must be enabled to pass this flag. (DEPRECATED: Feature DynamicKubeletConfig is deprecated in 1.22 and will not move to GA. It is planned to be removed from Kubernetes in the version 1.24 or later. Please use alternative ways to update kubelet configuration.) @@ -395,21 +395,21 @@ kubelet [flags] --experimental-allocatable-ignore-eviction     Default: false -When set to true, hard eviction thresholds will be ignored while calculating node allocatable. See https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/ for more details. (DEPRECATED: will be removed in 1.23) +When set to true, hard eviction thresholds will be ignored while calculating node allocatable. See https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/ for more details. (DEPRECATED: will be removed in 1.24 or later) --experimental-check-node-capabilities-before-mount -[Experimental] if set to true, the kubelet will check the underlying node for required components (binaries, etc.) before performing the mount (DEPRECATED: will be removed in 1.23, in favor of using CSI.) +[Experimental] if set to true, the kubelet will check the underlying node for required components (binaries, etc.) before performing the mount (DEPRECATED: will be removed in 1.24 or later, in favor of using CSI.) --experimental-kernel-memcg-notification -Use kernelMemcgNotification configuration, this flag will be removed in 1.23. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) +Use kernelMemcgNotification configuration, this flag will be removed in 1.24 or later. (DEPRECATED: This parameter should be set via the config file specified by the Kubelet's --config flag. See https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/ for more information.) @@ -423,7 +423,7 @@ kubelet [flags] --experimental-mounter-path string     Default: mount -[Experimental] Path of mounter binary. Leave empty to use the default mount. (DEPRECATED: will be removed in 1.23, in favor of using CSI.) +[Experimental] Path of mounter binary. Leave empty to use the default mount. (DEPRECATED: will be removed in 1.24 or later, in favor of using CSI.) diff --git a/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md b/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md index 10c1ff80dd..730973fd82 100644 --- a/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md +++ b/content/en/docs/reference/config-api/kubeadm-config.v1beta3.md @@ -156,15 +156,15 @@ configuration types to be used during a kubeadm init run.

effect: "NoSchedule" kubeletExtraArgs: v: 4 -ignorePreflightErrors: -- IsPrivilegedUser - imagePullPolicy: "IfNotPresent" + ignorePreflightErrors: + - IsPrivilegedUser + imagePullPolicy: "IfNotPresent" localAPIEndpoint: advertiseAddress: "10.100.0.1" bindPort: 6443 certificateKey: "e6a2eb8581237ab72a4f494f30285ec12a9694d750b9785706a83bfcbbbd2204" - skipPhases: - - addon/kube-proxy +skipPhases: + - addon/kube-proxy --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration @@ -264,6 +264,109 @@ node only (e.g. the node ip).

+## `BootstrapToken` {#BootstrapToken} + + +**Appears in:** + +- [InitConfiguration](#kubeadm-k8s-io-v1beta3-InitConfiguration) + + +

BootstrapToken describes one bootstrap token, stored as a Secret in the cluster

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
token [Required]
+BootstrapTokenString +		 +

token is used for establishing bidirectional trust between nodes and control-planes. +Used for joining nodes in the cluster.

+
description
+string +		 +

description sets a human-friendly message why this token exists and what it's used +for, so other administrators can know its purpose.

+
ttl
+meta/v1.Duration +		 +

ttl defines the time to live for this token. Defaults to 24h. +expires and ttl are mutually exclusive.

+
expires
+meta/v1.Time +		 +

expires specifies the timestamp when this token expires. Defaults to being set +dynamically at runtime based on the ttl. expires and ttl are mutually exclusive.

+
usages
+[]string +		 +

usages describes the ways in which this token can be used. Can by default be used +for establishing bidirectional trust, but that can be changed here.

+
groups
+[]string +		 +

groups specifies the extra groups that this token will authenticate as when/if +used for authentication

+
+ +## `BootstrapTokenString` {#BootstrapTokenString} + + +**Appears in:** + +- [BootstrapToken](#BootstrapToken) + + +

BootstrapTokenString is a token of the format abcdef.abcdef0123456789 that is used +for both validation of the practically of the API server from a joining node's point +of view and as an authentication method for the node in the bootstrap phase of +"kubeadm join". This token is and should be short-lived.

+ + + + + + + + + + + + + + +
FieldDescription
- [Required]
+string +		 + No description provided.
- [Required]
+string +		 + No description provided.
+ + + ## `ClusterConfiguration` {#kubeadm-k8s-io-v1beta3-ClusterConfiguration} @@ -1237,106 +1340,3 @@ first alpha-numerically.

- - - -## `BootstrapToken` {#BootstrapToken} - - -**Appears in:** - -- [InitConfiguration](#kubeadm-k8s-io-v1beta3-InitConfiguration) - - -

BootstrapToken describes one bootstrap token, stored as a Secret in the cluster

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
token [Required]
-BootstrapTokenString -		 -

token is used for establishing bidirectional trust between nodes and control-planes. -Used for joining nodes in the cluster.

-
description
-string -		 -

description sets a human-friendly message why this token exists and what it's used -for, so other administrators can know its purpose.

-
ttl
-meta/v1.Duration -		 -

ttl defines the time to live for this token. Defaults to 24h. -expires and ttl are mutually exclusive.

-
expires
-meta/v1.Time -		 -

expires specifies the timestamp when this token expires. Defaults to being set -dynamically at runtime based on the ttl. expires and ttl are mutually exclusive.

-
usages
-[]string -		 -

usages describes the ways in which this token can be used. Can by default be used -for establishing bidirectional trust, but that can be changed here.

-
groups
-[]string -		 -

groups specifies the extra groups that this token will authenticate as when/if -used for authentication

-
- -## `BootstrapTokenString` {#BootstrapTokenString} - - -**Appears in:** - -- [BootstrapToken](#BootstrapToken) - - -

BootstrapTokenString is a token of the format abcdef.abcdef0123456789 that is used -for both validation of the practically of the API server from a joining node's point -of view and as an authentication method for the node in the bootstrap phase of -"kubeadm join". This token is and should be short-lived.

- - - - - - - - - - - - - - -
FieldDescription
- [Required]
-string -		 - No description provided.
- [Required]
-string -		 - No description provided.
diff --git a/content/en/docs/reference/glossary/namespace.md b/content/en/docs/reference/glossary/namespace.md index 33a97d90a1..02381c4ee6 100644 --- a/content/en/docs/reference/glossary/namespace.md +++ b/content/en/docs/reference/glossary/namespace.md @@ -4,7 +4,7 @@ id: namespace date: 2018-04-12 full_link: /docs/concepts/overview/working-with-objects/namespaces short_description: > - An abstraction used by Kubernetes to support multiple virtual clusters on the same physical cluster. + An abstraction used by Kubernetes to support isolation of groups of resources within a single cluster. aka: tags: diff --git a/content/en/docs/reference/kubectl/cheatsheet.md b/content/en/docs/reference/kubectl/cheatsheet.md index 8d995efb49..3eaeb17ca9 100644 --- a/content/en/docs/reference/kubectl/cheatsheet.md +++ b/content/en/docs/reference/kubectl/cheatsheet.md @@ -238,7 +238,7 @@ kubectl rollout status -w deployment/frontend # Watch rolling kubectl rollout restart deployment/frontend # Rolling restart of the "frontend" deployment -cat pod.json | kubectl replace -f - # Replace a pod based on the JSON passed into std +cat pod.json | kubectl replace -f - # Replace a pod based on the JSON passed into stdin # Force replace, delete and then re-create the resource. Will cause a service outage. kubectl replace --force -f ./pod.json diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md index 9d4b342ed6..b1eefe7df5 100644 --- a/content/en/docs/reference/labels-annotations-taints/_index.md +++ b/content/en/docs/reference/labels-annotations-taints/_index.md @@ -37,9 +37,9 @@ Example: `kubernetes.io/metadata.name=mynamespace` Used on: Namespaces -The Kubernetes API server (part of the {{< glossary_tooltip text="control plane" term_id="control-plane" >}}) +The Kubernetes API server (part of the {{< glossary_tooltip text="control plane" term_id="control-plane" >}}) sets this label on all namespaces. The label value is set -to the name of the namespace. You can't change this label's value. +to the name of the namespace. You can't change this label's value. This is useful if you want to target a specific namespace with a label {{< glossary_tooltip text="selector" term_id="selector" >}}. @@ -69,7 +69,7 @@ Example: `kubernetes.io/change-cause=kubectl edit --record deployment foo` Used on: All Objects -This annotation is a best guess at why something was changed. +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. @@ -184,6 +184,16 @@ Used on: PersistentVolumeClaim This annotation has been deprecated. +### volume.beta.kubernetes.io/mount-options (deprecated) {#mount-options} + +Example : `volume.beta.kubernetes.io/mount-options: "ro,soft"` + +Used on: PersistentVolume + +A Kubernetes administrator can specify additional [mount options](/docs/concepts/storage/persistent-volumes/#mount-options) for when a PersistentVolume is mounted on a node. + +This annotation has been deprecated. + ### volume.kubernetes.io/storage-provisioner Used on: PersistentVolumeClaim @@ -404,7 +414,7 @@ Example: `pod-security.kubernetes.io/enforce-version: {{< skew latestVersion >}} Used on: Namespace Value **must** be `latest` or a valid Kubernetes version in the format `v.`. -This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) +This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) policies to apply when validating a submitted Pod. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) @@ -431,7 +441,7 @@ Example: `pod-security.kubernetes.io/audit-version: {{< skew latestVersion >}}` Used on: Namespace Value **must** be `latest` or a valid Kubernetes version in the format `v.`. -This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) +This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards) policies to apply when validating a submitted Pod. See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission) @@ -445,7 +455,7 @@ Used on: Namespace Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to [Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically, -the `warn` label does not prevent the creation of a Pod in the labeled Namespace which does not meet the +the `warn` label does not prevent the creation of a Pod in the labeled Namespace which does not meet the requirements outlined in the indicated level, but returns a warning to the user after doing so. Note that warnings are also displayed when creating or updating objects that contain Pod templates, such as Deployments, Jobs, StatefulSets, etc. @@ -475,10 +485,10 @@ The [`securityContext`](/docs/reference/kubernetes-api/workload-resources/pod-v1 When you [specify the security context for a Pod](/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod), the settings you specify apply to all containers in that Pod. -### container.seccomp.security.alpha.kubernetes.io/[NAME] {#container-seccomp-security-alpha-kubernetes-io} +### container.seccomp.security.alpha.kubernetes.io/[NAME] (deprecated) {#container-seccomp-security-alpha-kubernetes-io} This annotation has been deprecated since Kubernetes v1.19 and will become non-functional in v1.25. -The tutorial [Restrict a Container's Syscalls with seccomp](/docs/tutorials/clusters/seccomp/) takes +The tutorial [Restrict a Container's Syscalls with seccomp](/docs/tutorials/security/seccomp/) takes you through the steps you follow to apply a seccomp profile to a Pod or to one of its containers. That tutorial covers the supported mechanism for configuring seccomp in Kubernetes, based on setting `securityContext` within the Pod's `.spec`. @@ -489,4 +499,4 @@ based on setting `securityContext` within the Pod's `.spec`. - [`pod-security.kubernetes.io/enforce-policy`](/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-enforce-policy) - [`pod-security.kubernetes.io/audit-violations`](/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-audit-violations) -See more details on the [Audit Annotations](/docs/reference/labels-annotations-taints/audit-annotations/) page. \ No newline at end of file +See more details on the [Audit Annotations](/docs/reference/labels-annotations-taints/audit-annotations/) page. diff --git a/content/en/docs/setup/best-practices/certificates.md b/content/en/docs/setup/best-practices/certificates.md index 56ecb7f544..52696ade4b 100644 --- a/content/en/docs/setup/best-practices/certificates.md +++ b/content/en/docs/setup/best-practices/certificates.md @@ -22,6 +22,8 @@ This page explains the certificates that your cluster requires. Kubernetes requires PKI for the following operations: * Client certificates for the kubelet to authenticate to the API server +* Kubelet [server certificates](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#client-and-serving-certificates) + for the the API server to talk to the kubelets * Server certificate for the API server endpoint * Client certificates for administrators of the cluster to authenticate to the API server * Client certificates for the API server to talk to the kubelets diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md b/content/en/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md index 59477d944f..4625299919 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md +++ b/content/en/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md @@ -208,6 +208,7 @@ The DEB and RPM packages shipped with the Kubernetes releases are: | Package name | Description | |--------------|-------------| | `kubeadm` | Installs the `/usr/bin/kubeadm` CLI tool and the [kubelet drop-in file](#the-kubelet-drop-in-file-for-systemd) for the kubelet. | -| `kubelet` | Installs the kubelet binary in `/usr/bin` and CNI binaries in `/opt/cni/bin`. | +| `kubelet` | Installs the `/usr/bin/kubelet` binary. | | `kubectl` | Installs the `/usr/bin/kubectl` binary. | | `cri-tools` | Installs the `/usr/bin/crictl` binary from the [cri-tools git repository](https://github.com/kubernetes-sigs/cri-tools). | +| `kubernetes-cni` | Installs the `/opt/cni/bin` binaries from the [plugins git repository](https://github.com/containernetworking/plugins). | diff --git a/content/en/docs/tasks/administer-cluster/access-cluster-services.md b/content/en/docs/tasks/access-application-cluster/access-cluster-services.md similarity index 100% rename from content/en/docs/tasks/administer-cluster/access-cluster-services.md rename to content/en/docs/tasks/access-application-cluster/access-cluster-services.md diff --git a/content/en/docs/tasks/access-application-cluster/access-cluster.md b/content/en/docs/tasks/access-application-cluster/access-cluster.md index 3bd994f80b..8e89e12a59 100644 --- a/content/en/docs/tasks/access-application-cluster/access-cluster.md +++ b/content/en/docs/tasks/access-application-cluster/access-cluster.md @@ -237,7 +237,9 @@ In each case, the credentials of the pod are used to communicate securely with t ## Accessing services running on the cluster -The previous section describes how to connect to the Kubernetes API server. For information about connecting to other services running on a Kubernetes cluster, see [Access Cluster Services.](/docs/tasks/administer-cluster/access-cluster-services/) +The previous section describes how to connect to the Kubernetes API server. +For information about connecting to other services running on a Kubernetes cluster, see +[Access Cluster Services](/docs/tasks/access-application-cluster/access-cluster-services/). ## Requesting redirects diff --git a/content/en/docs/tasks/access-application-cluster/ingress-minikube.md b/content/en/docs/tasks/access-application-cluster/ingress-minikube.md index ca723f73cf..251bebbaef 100644 --- a/content/en/docs/tasks/access-application-cluster/ingress-minikube.md +++ b/content/en/docs/tasks/access-application-cluster/ingress-minikube.md @@ -240,13 +240,13 @@ The following manifest defines an Ingress that sends traffic to your Service via following lines at the end: ```yaml - - path: /v2 - pathType: Prefix - backend: - service: - name: web2 - port: - number: 8080 + - path: /v2 + pathType: Prefix + backend: + service: + name: web2 + port: + number: 8080 ``` 1. Apply the changes: diff --git a/content/en/docs/tasks/administer-cluster/change-pv-reclaim-policy.md b/content/en/docs/tasks/administer-cluster/change-pv-reclaim-policy.md index 408438e1de..457fbd6332 100644 --- a/content/en/docs/tasks/administer-cluster/change-pv-reclaim-policy.md +++ b/content/en/docs/tasks/administer-cluster/change-pv-reclaim-policy.md @@ -7,14 +7,10 @@ content_type: task This page shows how to change the reclaim policy of a Kubernetes PersistentVolume. - ## {{% heading "prerequisites" %}} - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - ## Why change reclaim policy of a PersistentVolume @@ -33,55 +29,58 @@ Released phase, where all of its data can be manually recovered. 1. List the PersistentVolumes in your cluster: - ```shell - kubectl get pv - ``` + ```shell + kubectl get pv + ``` - The output is similar to this: + The output is similar to this: - NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE - pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 10s - pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 6s - pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim3 manual 3s + ```none + NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE + pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 10s + pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 6s + pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim3 manual 3s + ``` - This list also includes the name of the claims that are bound to each volume + This list also includes the name of the claims that are bound to each volume for easier identification of dynamically provisioned volumes. 1. Choose one of your PersistentVolumes and change its reclaim policy: - ```shell - kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' - ``` + ```shell + kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' + ``` - where `` is the name of your chosen PersistentVolume. + where `` is the name of your chosen PersistentVolume. - {{< note >}} - On Windows, you must _double_ quote any JSONPath template that contains spaces (not single quote as shown above for bash). This in turn means that you must use a single quote or escaped double quote around any literals in the template. For example: + {{< note >}} + On Windows, you must _double_ quote any JSONPath template that contains spaces (not single + quote as shown above for bash). This in turn means that you must use a single quote or escaped + double quote around any literals in the template. For example: -```cmd -kubectl patch pv -p "{\"spec\":{\"persistentVolumeReclaimPolicy\":\"Retain\"}}" -``` - - {{< /note >}} + ```cmd + kubectl patch pv -p "{\"spec\":{\"persistentVolumeReclaimPolicy\":\"Retain\"}}" + ``` + {{< /note >}} 1. Verify that your chosen PersistentVolume has the right policy: - ```shell - kubectl get pv - ``` + ```shell + kubectl get pv + ``` - The output is similar to this: - - NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE - pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 40s - pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 36s - pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Retain Bound default/claim3 manual 33s - - In the preceding output, you can see that the volume bound to claim - `default/claim3` has reclaim policy `Retain`. It will not be automatically - deleted when a user deletes claim `default/claim3`. + The output is similar to this: + ```none + NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE + pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 40s + pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 36s + pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Retain Bound default/claim3 manual 33s + ``` + In the preceding output, you can see that the volume bound to claim + `default/claim3` has reclaim policy `Retain`. It will not be automatically + deleted when a user deletes claim `default/claim3`. ## {{% heading "whatsnext" %}} @@ -91,8 +90,8 @@ kubectl patch pv -p "{\"spec\":{\"persistentVolumeReclaimPolicy\" ### References {#reference} * {{< api-reference page="config-and-storage-resources/persistent-volume-v1" >}} - * Pay attention to the `.spec.persistentVolumeReclaimPolicy` [field](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1/#PersistentVolumeSpec) of PersistentVolume. + * Pay attention to the `.spec.persistentVolumeReclaimPolicy` + [field](/docs/reference/kubernetes-api/config-and-storage-resources/persistent-volume-v1/#PersistentVolumeSpec) + of PersistentVolume. * {{< api-reference page="config-and-storage-resources/persistent-volume-claim-v1" >}} - - diff --git a/content/en/docs/tasks/administer-cluster/coredns.md b/content/en/docs/tasks/administer-cluster/coredns.md index 54163058c8..43a75275b8 100644 --- a/content/en/docs/tasks/administer-cluster/coredns.md +++ b/content/en/docs/tasks/administer-cluster/coredns.md @@ -19,11 +19,14 @@ This page describes the CoreDNS upgrade process and how to install CoreDNS inste ## About CoreDNS -[CoreDNS](https://coredns.io) is a flexible, extensible DNS server that can serve as the Kubernetes cluster DNS. -Like Kubernetes, the CoreDNS project is hosted by the {{< glossary_tooltip text="CNCF" term_id="cncf" >}}. +[CoreDNS](https://coredns.io) is a flexible, extensible DNS server +that can serve as the Kubernetes cluster DNS. +Like Kubernetes, the CoreDNS project is hosted by the +{{< glossary_tooltip text="CNCF" term_id="cncf" >}}. -You can use CoreDNS instead of kube-dns in your cluster by replacing kube-dns in an existing -deployment, or by using tools like kubeadm that will deploy and upgrade the cluster for you. +You can use CoreDNS instead of kube-dns in your cluster by replacing +kube-dns in an existing deployment, or by using tools like kubeadm +that will deploy and upgrade the cluster for you. ## Installing CoreDNS @@ -34,51 +37,44 @@ For manual deployment or replacement of kube-dns, see the documentation at the ### Upgrading an existing cluster with kubeadm -In Kubernetes version 1.10 and later, you can also move to CoreDNS when you use `kubeadm` to upgrade -a cluster that is using `kube-dns`. In this case, `kubeadm` will generate the CoreDNS configuration +In Kubernetes version 1.21, kubeadm removed its support for `kube-dns` as a DNS application. +For `kubeadm` v{{< skew currentVersion >}}, the only supported cluster DNS application +is CoreDNS. + +You can move to CoreDNS when you use `kubeadm` to upgrade a cluster that is +using `kube-dns`. In this case, `kubeadm` generates the CoreDNS configuration ("Corefile") based upon the `kube-dns` ConfigMap, preserving configurations for stub domains, and upstream name server. -If you are moving from kube-dns to CoreDNS, make sure to set the `CoreDNS` feature gate to `true` -during an upgrade. For example, here is what a `v1.11.0` upgrade would look like: -``` -kubeadm upgrade apply v1.11.0 --feature-gates=CoreDNS=true -``` - -In Kubernetes version 1.13 and later the `CoreDNS` feature gate is removed and CoreDNS -is used by default. - -In versions prior to 1.11 the Corefile will be **overwritten** by the one created during upgrade. -**You should save your existing ConfigMap if you have customized it.** You may re-apply your -customizations after the new ConfigMap is up and running. - -If you are running CoreDNS in Kubernetes version 1.11 and later, during upgrade, -your existing Corefile will be retained. - -In Kubernetes version 1.21, support for `kube-dns` is removed from kubeadm. - ## Upgrading CoreDNS -CoreDNS is available in Kubernetes since v1.9. -You can check the version of CoreDNS shipped with Kubernetes and the changes made to CoreDNS [here](https://github.com/coredns/deployment/blob/master/kubernetes/CoreDNS-k8s_version.md). +You can check the version of CoreDNS that kubeadm installs for each version of +Kubernetes in the page +[CoreDNS version in Kubernetes](https://github.com/coredns/deployment/blob/master/kubernetes/CoreDNS-k8s_version.md). + +CoreDNS can be upgraded manually in case you want to only upgrade CoreDNS +or use your own custom image. +There is a helpful [guideline and walkthrough](https://github.com/coredns/deployment/blob/master/kubernetes/Upgrading_CoreDNS.md) +available to ensure a smooth upgrade. +Make sure the existing CoreDNS configuration ("Corefile") is retained when +upgrading your cluster. + +If you are upgrading your cluster using the `kubeadm` tool, `kubeadm` +can take care of retaining the existing CoreDNS configuration automatically. -CoreDNS can be upgraded manually in case you want to only upgrade CoreDNS or use your own custom image. -There is a helpful [guideline and walkthrough](https://github.com/coredns/deployment/blob/master/kubernetes/Upgrading_CoreDNS.md) available to ensure a smooth upgrade. ## Tuning CoreDNS -When resource utilisation is a concern, it may be useful to tune the configuration of CoreDNS. For more details, check out the +When resource utilisation is a concern, it may be useful to tune the +configuration of CoreDNS. For more details, check out the [documentation on scaling CoreDNS](https://github.com/coredns/deployment/blob/master/kubernetes/Scaling_CoreDNS.md). - - ## {{% heading "whatsnext" %}} - You can configure [CoreDNS](https://coredns.io) to support many more use cases than -kube-dns by modifying the `Corefile`. For more information, see the -[CoreDNS site](https://coredns.io/2017/05/08/custom-dns-entries-for-kubernetes/). - - - +kube-dns does by modifying the CoreDNS configuration ("Corefile"). +For more information, see the [documentation](https://coredns.io/plugins/kubernetes/) +for the `kubernetes` CoreDNS plugin, or read the +[Custom DNS Entries for Kubernetes](https://coredns.io/2017/05/08/custom-dns-entries-for-kubernetes/). +in the CoreDNS blog. diff --git a/content/en/docs/tasks/configure-pod-container/assign-memory-resource.md b/content/en/docs/tasks/configure-pod-container/assign-memory-resource.md index 94c20297cf..137571d8e8 100644 --- a/content/en/docs/tasks/configure-pod-container/assign-memory-resource.md +++ b/content/en/docs/tasks/configure-pod-container/assign-memory-resource.md @@ -99,10 +99,10 @@ and a memory limit of 200 MiB. ```yaml ... resources: - limits: - memory: 200Mi requests: memory: 100Mi + limits: + memory: 200Mi ... ``` diff --git a/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md b/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md index ded295635b..9f46360a5c 100644 --- a/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md +++ b/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md @@ -50,7 +50,7 @@ plugins: # Array of authenticated usernames to exempt. usernames: [] # Array of runtime class names to exempt. - runtimeClassNames: [] + runtimeClasses: [] # Array of namespaces to exempt. namespaces: [] ``` diff --git a/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md b/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md index 205628b525..a463982422 100644 --- a/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md +++ b/content/en/docs/tasks/configure-pod-container/translate-compose-kubernetes.md @@ -208,7 +208,6 @@ you need is an existing `docker-compose.yml` file. - CLI - [`kompose convert`](#kompose-convert) - Documentation - - [Build and Push Docker Images](#build-and-push-docker-images) - [Alternative Conversions](#alternative-conversions) - [Labels](#labels) - [Restart](#restart) @@ -326,55 +325,6 @@ INFO OpenShift file "foo-buildconfig.yaml" created If you are manually pushing the OpenShift artifacts using ``oc create -f``, you need to ensure that you push the imagestream artifact before the buildconfig artifact, to workaround this OpenShift issue: https://github.com/openshift/origin/issues/4518 . {{< /note >}} - - -## Build and Push Docker Images - -Kompose supports both building and pushing Docker images. When using the `build` key within your Docker Compose file, your image will: - -- Automatically be built with Docker using the `image` key specified within your file -- Be pushed to the correct Docker repository using local credentials (located at `.docker/config`) - -Using an [example Docker Compose file](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/buildconfig/docker-compose.yml): - -```yaml -version: "2" - -services: - foo: - build: "./build" - image: docker.io/foo/bar -``` - -Using `kompose up` with a `build` key: - -```none -kompose up -INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar' -INFO Building image 'docker.io/foo/bar' from directory 'build' -INFO Image 'docker.io/foo/bar' from directory 'build' built successfully -INFO Pushing image 'foo/bar:latest' to registry 'docker.io' -INFO Attempting authentication credentials 'https://index.docker.io/v1/ -INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io' -INFO We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead. - -INFO Deploying application in "default" namespace -INFO Successfully created Service: foo -INFO Successfully created Deployment: foo - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. -``` - -In order to disable the functionality, or choose to use BuildConfig generation (with OpenShift) `--build (local|build-config|none)` can be passed. - -```sh -# Disable building/pushing Docker images -kompose up --build none - -# Generate Build Config artifacts for OpenShift -kompose up --provider openshift --build build-config -``` - ## Alternative Conversions The default `kompose` transformation will generate Kubernetes [Deployments](/docs/concepts/workloads/controllers/deployment/) and [Services](/docs/concepts/services-networking/service/), in yaml format. You have alternative option to generate json with `-j`. Also, you can alternatively generate [Replication Controllers](/docs/concepts/workloads/controllers/replicationcontroller/) objects, [Daemon Sets](/docs/concepts/workloads/controllers/daemonset/), or [Helm](https://github.com/helm/helm) charts. diff --git a/content/en/docs/tasks/debug-application-cluster/resource-metrics-pipeline.md b/content/en/docs/tasks/debug-application-cluster/resource-metrics-pipeline.md index 14afc52c24..c2818940e2 100644 --- a/content/en/docs/tasks/debug-application-cluster/resource-metrics-pipeline.md +++ b/content/en/docs/tasks/debug-application-cluster/resource-metrics-pipeline.md @@ -8,14 +8,19 @@ content_type: concept -For Kubernetes, the _Metrics API_ offers a basic set of metrics to support automatic scaling and similar use cases. -This API makes information available about resource usage for node and pod, including metrics for CPU and memory. -If you deploy the Metrics API into your cluster, clients of the Kubernetes API can then query for this information, and -you can use Kubernetes' access control mechanisms to manage permissions to do so. +For Kubernetes, the _Metrics API_ offers a basic set of metrics to support automatic scaling and +similar use cases. This API makes information available about resource usage for node and pod, +including metrics for CPU and memory. If you deploy the Metrics API into your cluster, clients of +the Kubernetes API can then query for this information, and you can use Kubernetes' access control +mechanisms to manage permissions to do so. -The [HorizontalPodAutoscaler](/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) and [VerticalPodAutoscaler](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler#readme) (VPA) use data from the metrics API to adjust workload replicas and resources to meet customer demand. +The [HorizontalPodAutoscaler](/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) and +[VerticalPodAutoscaler](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler#readme) (VPA) +use data from the metrics API to adjust workload replicas and resources to meet customer demand. -You can also view the resource metrics using the [`kubectl top`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#top) command. +You can also view the resource metrics using the +[`kubectl top`](/docs/reference/generated/kubectl/kubectl-commands#top) +command. {{< note >}} The Metrics API, and the metrics pipeline that it enables, only offers the minimum @@ -59,34 +64,51 @@ Figure 1. Resource Metrics Pipeline The architecture components, from right to left in the figure, consist of the following: -* [cAdvisor](https://github.com/google/cadvisor): Daemon for collecting, aggregating and exposing container metrics included in Kubelet. -* [kubelet](/docs/concepts/overview/components/#kubelet): Node agent for managing container resources. Resource metrics are accessible using the `/metrics/resource` and `/stats` kubelet API endpoints. -* [Summary API](#summary-api-source): API provided by the kubelet for discovering and retrieving per-node summarized stats available through the `/stats` endpoint. -* [metrics-server](#metrics-server): Cluster addon component that collects and aggregates resource metrics pulled from each kubelet. The API server serves Metrics API for use by HPA, VPA, and by the `kubectl top` command. Metrics Server is a reference implementation of the Metrics API. -* [Metrics API](#metrics-api): Kubernetes API supporting access to CPU and memory used for workload autoscaling. To make this work in your cluster, you need an API extension server that provides the Metrics API. +* [cAdvisor](https://github.com/google/cadvisor): Daemon for collecting, aggregating and exposing + container metrics included in Kubelet. +* [kubelet](/docs/concepts/overview/components/#kubelet): Node agent for managing container + resources. Resource metrics are accessible using the `/metrics/resource` and `/stats` kubelet + API endpoints. +* [Summary API](#summary-api-source): API provided by the kubelet for discovering and retrieving + per-node summarized stats available through the `/stats` endpoint. +* [metrics-server](#metrics-server): Cluster addon component that collects and aggregates resource + metrics pulled from each kubelet. The API server serves Metrics API for use by HPA, VPA, and by + the `kubectl top` command. Metrics Server is a reference implementation of the Metrics API. +* [Metrics API](#metrics-api): Kubernetes API supporting access to CPU and memory used for + workload autoscaling. To make this work in your cluster, you need an API extension server that + provides the Metrics API. {{< note >}} cAdvisor supports reading metrics from cgroups, which works with typical container runtimes on Linux. - If you use a container runtime that uses another resource isolation mechanism, for example virtualization, then that container runtime must support [CRI Container Metrics](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/cri-container-stats.md) in order for metrics to be available to the kubelet. + If you use a container runtime that uses another resource isolation mechanism, for example + virtualization, then that container runtime must support + [CRI Container Metrics](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/cri-container-stats.md) + in order for metrics to be available to the kubelet. {{< /note >}} - ## Metrics API -The metrics-server implements the Metrics API. This API allows you to access CPU and memory usage for the nodes and pods in your cluster. Its primary role is to feed resource usage metrics to K8s autoscaler components. +The metrics-server implements the Metrics API. This API allows you to access CPU and memory usage +for the nodes and pods in your cluster. Its primary role is to feed resource usage metrics to K8s +autoscaler components. + +Here is an example of the Metrics API request for a `minikube` node piped through `jq` for easier +reading: -Here is an example of the Metrics API request for a `minikube` node piped through `jq` for easier reading: ```shell kubectl get --raw "/apis/metrics.k8s.io/v1beta1/nodes/minikube" | jq '.' ``` Here is the same API call using `curl`: + ```shell curl http://localhost:8080/apis/metrics.k8s.io/v1beta1/nodes/minikube ``` -Sample reply: + +Sample response: + ```json { "kind": "NodeMetrics", @@ -104,16 +126,22 @@ Sample reply: } } ``` -Here is an example of the Metrics API request for a `kube-scheduler-minikube` pod contained in the `kube-system` namespace and piped through `jq` for easier reading: + +Here is an example of the Metrics API request for a `kube-scheduler-minikube` pod contained in the +`kube-system` namespace and piped through `jq` for easier reading: ```shell kubectl get --raw "/apis/metrics.k8s.io/v1beta1/namespaces/kube-system/pods/kube-scheduler-minikube" | jq '.' ``` + Here is the same API call using `curl`: + ```shell curl http://localhost:8080/apis/metrics.k8s.io/v1beta1/namespaces/kube-system/pods/kube-scheduler-minikube ``` -Sample reply: + +Sample response: + ```json { "kind": "PodMetrics", @@ -138,47 +166,72 @@ Sample reply: } ``` -The Metrics API is defined in the [k8s.io/metrics](https://github.com/kubernetes/metrics) repository. You must enable the [API aggregation layer](/docs/tasks/extend-kubernetes/configure-aggregation-layer/) and register an [APIService](/docs/reference/kubernetes-api/cluster-resources/api-service-v1/) for the `metrics.k8s.io` API. +The Metrics API is defined in the [k8s.io/metrics](https://github.com/kubernetes/metrics) +repository. You must enable the [API aggregation layer](/docs/tasks/extend-kubernetes/configure-aggregation-layer/) +and register an [APIService](/docs/reference/kubernetes-api/cluster-resources/api-service-v1/) +for the `metrics.k8s.io` API. -To learn more about the Metrics API, see [resource metrics API design](https://github.com/kubernetes/design-proposals-archive/blob/main/instrumentation/resource-metrics-api.md), the [metrics-server repository](https://github.com/kubernetes-sigs/metrics-server) and the [resource metrics API](https://github.com/kubernetes/metrics#resource-metrics-api). +To learn more about the Metrics API, see [resource metrics API design](https://github.com/kubernetes/design-proposals-archive/blob/main/instrumentation/resource-metrics-api.md), +the [metrics-server repository](https://github.com/kubernetes-sigs/metrics-server) and the +[resource metrics API](https://github.com/kubernetes/metrics#resource-metrics-api). -{{< note >}} You must deploy the metrics-server or alternative adapter that serves the Metrics API to be able to access it. {{< /note >}} +{{< note >}} +You must deploy the metrics-server or alternative adapter that serves the Metrics API to be able +to access it. +{{< /note >}} ## Measuring resource usage ### CPU -CPU is reported as the average core usage measured in cpu units. One cpu, in Kubernetes, is equivalent to 1 vCPU/Core for cloud providers, and 1 hyper-thread on bare-metal Intel processors. +CPU is reported as the average core usage measured in cpu units. One cpu, in Kubernetes, is +equivalent to 1 vCPU/Core for cloud providers, and 1 hyper-thread on bare-metal Intel processors. -This value is derived by taking a rate over a cumulative CPU counter provided by the kernel (in both Linux and Windows kernels). The time window used to calculate CPU is shown under window field in Metrics API. +This value is derived by taking a rate over a cumulative CPU counter provided by the kernel (in +both Linux and Windows kernels). The time window used to calculate CPU is shown under window field +in Metrics API. -To learn more about how Kubernetes allocates and measures CPU resources, see [meaning of CPU](/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu). +To learn more about how Kubernetes allocates and measures CPU resources, see +[meaning of CPU](/docs/concepts/configuration/manage-resources-container/#meaning-of-cpu). ### Memory Memory is reported as the working set, measured in bytes, at the instant the metric was collected. -In an ideal world, the "working set" is the amount of memory in-use that cannot be freed under memory pressure. However, calculation of the working set varies by host OS, and generally makes heavy use of heuristics to produce an estimate. +In an ideal world, the "working set" is the amount of memory in-use that cannot be freed under +memory pressure. However, calculation of the working set varies by host OS, and generally makes +heavy use of heuristics to produce an estimate. -The Kubernetes model for a container's working set expects that the container runtime counts anonymous memory associated with the container in question. The working set metric typically also includes some cached (file-backed) memory, because the host OS cannot always reclaim pages. +The Kubernetes model for a container's working set expects that the container runtime counts +anonymous memory associated with the container in question. The working set metric typically also +includes some cached (file-backed) memory, because the host OS cannot always reclaim pages. -To learn more about how Kubernetes allocates and measures memory resources, see [meaning of memory](/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory). +To learn more about how Kubernetes allocates and measures memory resources, see +[meaning of memory](/docs/concepts/configuration/manage-resources-container/#meaning-of-memory). ## Metrics Server -The metrics-server fetches resource metrics from the kubelets and exposes them in the Kubernetes API server through the Metrics API for use by the HPA and VPA. You can also view these metrics using the `kubectl top` command. +The metrics-server fetches resource metrics from the kubelets and exposes them in the Kubernetes +API server through the Metrics API for use by the HPA and VPA. You can also view these metrics +using the `kubectl top` command. -The metrics-server uses the Kubernetes API to track nodes and pods in your cluster. The metrics-server queries each node over HTTP to fetch metrics. The metrics-server also builds an internal view of pod metadata, and keeps a cache of pod health. That cached pod health information is available via the extension API that the metrics-server makes available. +The metrics-server uses the Kubernetes API to track nodes and pods in your cluster. The +metrics-server queries each node over HTTP to fetch metrics. The metrics-server also builds an +internal view of pod metadata, and keeps a cache of pod health. That cached pod health information +is available via the extension API that the metrics-server makes available. -For example with an HPA query, the metrics-server needs to identify which pods fulfill the label selectors in the deployment. +For example with an HPA query, the metrics-server needs to identify which pods fulfill the label +selectors in the deployment. + +The metrics-server calls the [kubelet](/docs/reference/command-line-tools-reference/kubelet/) API +to collect metrics from each node. Depending on the metrics-server version it uses: -The metrics-server calls the [kubelet](/docs/reference/command-line-tools-reference/kubelet/) API to collect metrics from each node. Depending on the metrics-server version it uses: * Metrics resource endpoint `/metrics/resource` in version v0.6.0+ or * Summary API endpoint `/stats/summary` in older versions - -To learn more about the metrics-server, see the [metrics-server repository](https://github.com/kubernetes-sigs/metrics-server). +To learn more about the metrics-server, see the +[metrics-server repository](https://github.com/kubernetes-sigs/metrics-server). You can also check out the following: @@ -190,20 +243,25 @@ You can also check out the following: ### Summary API source -The [kubelet](/docs/reference/command-line-tools-reference/kubelet/) gathers stats at the node, volume, pod and container level, and emits this information in +The [kubelet](/docs/reference/command-line-tools-reference/kubelet/) gathers stats at the node, +volume, pod and container level, and emits this information in the [Summary API](https://github.com/kubernetes/kubernetes/blob/7d309e0104fedb57280b261e5677d919cb2a0e2d/staging/src/k8s.io/kubelet/pkg/apis/stats/v1alpha1/types.go) for consumers to read. Here is an example of a Summary API request for a `minikube` node: - ```shell kubectl get --raw "/api/v1/nodes/minikube/proxy/stats/summary" ``` + Here is the same API call using `curl`: + ```shell curl http://localhost:8080/api/v1/nodes/minikube/proxy/stats/summary ``` + {{< note >}} -The summary API `/stats/summary` endpoint will be replaced by the `/metrics/resource` endpoint beginning with metrics-server 0.6.x. -{{< /note >}} \ No newline at end of file +The summary API `/stats/summary` endpoint will be replaced by the `/metrics/resource` endpoint +beginning with metrics-server 0.6.x. +{{< /note >}} + diff --git a/content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md b/content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md index 579adcb736..d50b3e91a5 100644 --- a/content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md +++ b/content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md @@ -6,20 +6,15 @@ weight: 40 -This page shows how a Pod can use a DownwardAPIVolumeFile to expose information -about itself to Containers running in the Pod. A DownwardAPIVolumeFile can expose -Pod fields and Container fields. - - - +This page shows how a Pod can use a +[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core) +to expose information about itself to Containers running in the Pod. +A `DownwardAPIVolumeFile` can expose Pod fields and Container fields. ## {{% heading "prerequisites" %}} - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - - ## The Downward API @@ -27,10 +22,10 @@ Pod fields and Container fields. There are two ways to expose Pod and Container fields to a running Container: * [Environment variables](/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#the-downward-api) -* Volume Files +* Volume files Together, these two ways of exposing Pod and Container fields are called the -*Downward API*. +"Downward API". ## Store Pod fields @@ -60,13 +55,13 @@ Create the Pod: kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume.yaml ``` -Verify that the Container in the Pod is running: +Verify that the container in the Pod is running: ```shell kubectl get pods ``` -View the Container's logs: +View the container's logs: ```shell kubectl logs kubernetes-downwardapi-volume-example @@ -83,7 +78,7 @@ build="two" builder="john-doe" ``` -Get a shell into the Container that is running in your Pod: +Get a shell into the container that is running in your Pod: ```shell kubectl exec -it kubernetes-downwardapi-volume-example -- sh @@ -136,8 +131,7 @@ total 8 Using symbolic links enables dynamic atomic refresh of the metadata; updates are written to a new temporary directory, and the `..data` symlink is updated -atomically using -[rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html). +atomically using [rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html). {{< note >}} A container using Downward API as a @@ -153,17 +147,19 @@ Exit the shell: ## Store Container fields -The preceding exercise, you stored Pod fields in a DownwardAPIVolumeFile. +The preceding exercise, you stored Pod fields in a +[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core).. In this next exercise, you store Container fields. Here is the configuration file for a Pod that has one Container: {{< codenew file="pods/inject/dapi-volume-resources.yaml" >}} -In the configuration file, you can see that the Pod has a `downwardAPI` Volume, -and the Container mounts the Volume at `/etc/podinfo`. +In the configuration file, you can see that the Pod has a +[`downwardAPI` volume](/concepts/storage/volumes/#downwardapi), +and the Container mounts the volume at `/etc/podinfo`. Look at the `items` array under `downwardAPI`. Each element of the array is a -DownwardAPIVolumeFile. +[`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core). The first element specifies that in the Container named `client-container`, the value of the `limits.cpu` field in the format specified by `1m` should be @@ -176,7 +172,7 @@ Create the Pod: kubectl apply -f https://k8s.io/examples/pods/inject/dapi-volume-resources.yaml ``` -Get a shell into the Container that is running in your Pod: +Get a shell into the container that is running in your Pod: ```shell kubectl exec -it kubernetes-downwardapi-volume-example-2 -- sh @@ -187,46 +183,56 @@ In your shell, view the `cpu_limit` file: ```shell /# cat /etc/podinfo/cpu_limit ``` + You can use similar commands to view the `cpu_request`, `mem_limit` and `mem_request` files. - - + ## Capabilities of the Downward API The following information is available to containers through environment variables and `downwardAPI` volumes: * Information available via `fieldRef`: + * `metadata.name` - the pod's name * `metadata.namespace` - the pod's namespace * `metadata.uid` - the pod's UID - * `metadata.labels['']` - the value of the pod's label `` (for example, `metadata.labels['mylabel']`) - * `metadata.annotations['']` - the value of the pod's annotation `` (for example, `metadata.annotations['myannotation']`) + * `metadata.labels['']` - the value of the pod's label `` + (for example, `metadata.labels['mylabel']`) + * `metadata.annotations['']` - the value of the pod's annotation `` + (for example, `metadata.annotations['myannotation']`) + * Information available via `resourceFieldRef`: + * A Container's CPU limit * A Container's CPU request * A Container's memory limit * A Container's memory request - * A Container's hugepages limit (providing that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) - * A Container's hugepages request (providing that the `DownwardAPIHugePages` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) + * A Container's hugepages limit (provided that the `DownwardAPIHugePages` + [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) + * A Container's hugepages request (provided that the `DownwardAPIHugePages` + [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled) * A Container's ephemeral-storage limit * A Container's ephemeral-storage request In addition, the following information is available through `downwardAPI` volume `fieldRef`: -* `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"` with one label per line -* `metadata.annotations` - all of the pod's annotations, formatted as `annotation-key="escaped-annotation-value"` with one annotation per line +* `metadata.labels` - all of the pod's labels, formatted as `label-key="escaped-label-value"` + with one label per line +* `metadata.annotations` - all of the pod's annotations, formatted as + `annotation-key="escaped-annotation-value"` with one annotation per line The following information is available through environment variables: * `status.podIP` - the pod's IP address -* `spec.serviceAccountName` - the pod's service account name, available since v1.4.0-alpha.3 -* `spec.nodeName` - the node's name, available since v1.4.0-alpha.3 -* `status.hostIP` - the node's IP, available since v1.7.0-alpha.1 +* `spec.serviceAccountName` - the pod's service account name +* `spec.nodeName` - the name of the node to which the scheduler always attempts to + schedule the pod +* `status.hostIP` - the IP of the node to which the Pod is assigned {{< note >}} If CPU and memory limits are not specified for a Container, the @@ -241,7 +247,7 @@ basis. For more information, see ## Motivation for the Downward API -It is sometimes useful for a Container to have information about itself, without +It is sometimes useful for a container to have information about itself, without being overly coupled to Kubernetes. The Downward API allows containers to consume information about themselves or the cluster without using the Kubernetes client or API server. @@ -252,19 +258,17 @@ application, but that is tedious and error prone, and it violates the goal of lo coupling. A better option would be to use the Pod's name as an identifier, and inject the Pod's name into the well-known environment variable. - - - ## {{% heading "whatsnext" %}} - -* [PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) -* [Volume](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core) -* [DownwardAPIVolumeSource](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core) -* [DownwardAPIVolumeFile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core) -* [ResourceFieldSelector](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core) - - - - +* Check the [`PodSpec`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) + API definition which defines the desired state of a Pod. +* Check the [`Volume`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#volume-v1-core) + API definition which defines a generic volume in a Pod for containers to access. +* Check the [`DownwardAPIVolumeSource`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumesource-v1-core) + API definition which defines a volume that contains Downward API information. +* Check the [`DownwardAPIVolumeFile`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#downwardapivolumefile-v1-core) + API definition which contains references to object or resource fields for + populating a file in the Downward API volume. +* Check the [`ResourceFieldSelector`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcefieldselector-v1-core) + API definition which specifies the container resources and their output format. diff --git a/content/en/docs/tasks/manage-daemon/update-daemon-set.md b/content/en/docs/tasks/manage-daemon/update-daemon-set.md index d36f487794..e435f392fe 100644 --- a/content/en/docs/tasks/manage-daemon/update-daemon-set.md +++ b/content/en/docs/tasks/manage-daemon/update-daemon-set.md @@ -34,11 +34,11 @@ DaemonSet has two update strategy types: To enable the rolling update feature of a DaemonSet, you must set its `.spec.updateStrategy.type` to `RollingUpdate`. -You may want to set -[`.spec.updateStrategy.rollingUpdate.maxUnavailable`](/docs/concepts/workloads/controllers/deployment/#max-unavailable) +You may want to set +[`.spec.updateStrategy.rollingUpdate.maxUnavailable`](/docs/reference/kubernetes-api/workload-resources/daemon-set-v1/#DaemonSetSpec) (default to 1), -[`.spec.minReadySeconds`](/docs/concepts/workloads/controllers/deployment/#min-ready-seconds) -(default to 0) and +[`.spec.minReadySeconds`](/docs/reference/kubernetes-api/workload-resources/daemon-set-v1/#DaemonSetSpec) +(default to 0) and [`.spec.updateStrategy.rollingUpdate.maxSurge`](/docs/reference/kubernetes-api/workload-resources/daemon-set-v1/#DaemonSetSpec) (a beta feature and defaults to 0) as well. diff --git a/content/en/docs/tasks/manage-kubernetes-objects/kustomization.md b/content/en/docs/tasks/manage-kubernetes-objects/kustomization.md index f391b37e09..cca985705b 100644 --- a/content/en/docs/tasks/manage-kubernetes-objects/kustomization.md +++ b/content/en/docs/tasks/manage-kubernetes-objects/kustomization.md @@ -308,7 +308,7 @@ metadata: type: Opaque ``` -Like ConfigMaps, generated Secrets can be used in Deployments by refering to the name of the secretGenerator: +Like ConfigMaps, generated Secrets can be used in Deployments by referring to the name of the secretGenerator: ```shell # Create a password.txt file diff --git a/content/en/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch.md b/content/en/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch.md index e6e33efe75..7b38703c74 100644 --- a/content/en/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch.md +++ b/content/en/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch.md @@ -189,11 +189,11 @@ kubectl get deployment patch-demo --output yaml The output shows that the PodSpec in the Deployment has only one Toleration: -```shell +```yaml tolerations: - - effect: NoSchedule - key: disktype - value: ssd +- effect: NoSchedule + key: disktype + value: ssd ``` Notice that the `tolerations` list in the PodSpec was replaced, not merged. This is because diff --git a/content/en/docs/tasks/tools/included/optional-kubectl-configs-zsh.md b/content/en/docs/tasks/tools/included/optional-kubectl-configs-zsh.md index b7d9044605..176bdeeeb1 100644 --- a/content/en/docs/tasks/tools/included/optional-kubectl-configs-zsh.md +++ b/content/en/docs/tasks/tools/included/optional-kubectl-configs-zsh.md @@ -12,16 +12,11 @@ To do so in all your shell sessions, add the following to your `~/.zshrc` file: source <(kubectl completion zsh) ``` -If you have an alias for kubectl, you can extend shell completion to work with that alias: - -```zsh -echo 'alias k=kubectl' >>~/.zshrc -echo 'compdef __start_kubectl k' >>~/.zshrc -``` +If you have an alias for kubectl, kubectl autocompletion will automatically work with it. After reloading your shell, kubectl autocompletion should be working. -If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file: +If you get an error like `2: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file: ```zsh autoload -Uz compinit diff --git a/content/en/docs/tasks/tools/install-kubectl-linux.md b/content/en/docs/tasks/tools/install-kubectl-linux.md index 2788e50e19..987f3a4116 100644 --- a/content/en/docs/tasks/tools/install-kubectl-linux.md +++ b/content/en/docs/tasks/tools/install-kubectl-linux.md @@ -83,7 +83,7 @@ For example, to download version {{< param "fullversion" >}} on Linux, type: ```bash chmod +x kubectl - mkdir -p ~/.local/bin/kubectl + mkdir -p ~/.local/bin mv ./kubectl ~/.local/bin/kubectl # and then append (or prepend) ~/.local/bin to $PATH ``` diff --git a/content/en/docs/tasks/tools/install-kubectl-macos.md b/content/en/docs/tasks/tools/install-kubectl-macos.md index fb5ec2a306..9861aca156 100644 --- a/content/en/docs/tasks/tools/install-kubectl-macos.md +++ b/content/en/docs/tasks/tools/install-kubectl-macos.md @@ -114,7 +114,7 @@ The following methods exist for installing kubectl on macOS: Or use this for detailed view of version: ```cmd - kubectl version --client --output=yaml + kubectl version --client --output=yaml ``` ### Install with Homebrew on macOS @@ -124,7 +124,7 @@ If you are on macOS and using [Homebrew](https://brew.sh/) package manager, you 1. Run the installation command: ```bash - brew install kubectl + brew install kubectl ``` or diff --git a/content/en/docs/tasks/tools/install-kubectl-windows.md b/content/en/docs/tasks/tools/install-kubectl-windows.md index f5248ecfe4..3fde98c309 100644 --- a/content/en/docs/tasks/tools/install-kubectl-windows.md +++ b/content/en/docs/tasks/tools/install-kubectl-windows.md @@ -38,13 +38,13 @@ The following methods exist for installing kubectl on Windows: 1. Validate the binary (optional) - Download the kubectl checksum file: + Download the `kubectl` checksum file: ```powershell curl -LO "https://dl.k8s.io/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe.sha256" ``` - Validate the kubectl binary against the checksum file: + Validate the `kubectl` binary against the checksum file: - Using Command Prompt to manually compare `CertUtil`'s output to the checksum file downloaded: @@ -59,7 +59,7 @@ The following methods exist for installing kubectl on Windows: $($(CertUtil -hashfile .\kubectl.exe SHA256)[1] -replace " ", "") -eq $(type .\kubectl.exe.sha256) ``` -1. Append or prepend the kubectl binary folder to your `PATH` environment variable. +1. Append or prepend the `kubectl` binary folder to your `PATH` environment variable. 1. Test to ensure the version of `kubectl` is the same as downloaded: @@ -156,13 +156,13 @@ Below are the procedures to set up autocompletion for PowerShell. 1. Validate the binary (optional) - Download the kubectl-convert checksum file: + Download the `kubectl-convert` checksum file: ```powershell curl -LO "https://dl.k8s.io/{{< param "fullversion" >}}/bin/windows/amd64/kubectl-convert.exe.sha256" ``` - Validate the kubectl-convert binary against the checksum file: + Validate the `kubectl-convert` binary against the checksum file: - Using Command Prompt to manually compare `CertUtil`'s output to the checksum file downloaded: @@ -177,7 +177,7 @@ Below are the procedures to set up autocompletion for PowerShell. $($(CertUtil -hashfile .\kubectl-convert.exe SHA256)[1] -replace " ", "") -eq $(type .\kubectl-convert.exe.sha256) ``` -1. Append or prepend the kubectl binary folder to your `PATH` environment variable. +1. Append or prepend the `kubectl-convert` binary folder to your `PATH` environment variable. 1. Verify plugin is successfully installed diff --git a/content/en/docs/tutorials/security/apparmor.md b/content/en/docs/tutorials/security/apparmor.md index 992841e356..727b267608 100644 --- a/content/en/docs/tutorials/security/apparmor.md +++ b/content/en/docs/tutorials/security/apparmor.md @@ -382,27 +382,13 @@ If you do not want AppArmor to be available on your cluster, it can be disabled ``` When disabled, any Pod that includes an AppArmor profile will fail validation with a "Forbidden" -error. Note that by default docker always enables the "docker-default" profile on non-privileged -pods (if the AppArmor kernel module is enabled), and will continue to do so even if the feature-gate -is disabled. The option to disable AppArmor will be removed when AppArmor graduates to general +error. + +{{}} +Even if the Kubernetes feature is disabled, runtimes may still enforce the default profile. The +option to disable the AppArmor feature will be removed when AppArmor graduates to general availability (GA). - -### Upgrading to Kubernetes v1.4 with AppArmor - -No action is required with respect to AppArmor to upgrade your cluster to v1.4. However, if any -existing pods had an AppArmor annotation, they will not go through validation (or PodSecurityPolicy -admission). If permissive profiles are loaded on the nodes, a malicious user could pre-apply a -permissive profile to escalate the pod privileges above the docker-default. If this is a concern, it -is recommended to scrub the cluster of any pods containing an annotation with -`apparmor.security.beta.kubernetes.io`. - -### Upgrade path to General Availability - -When AppArmor is ready to be graduated to general availability (GA), the options currently specified -through annotations will be converted to fields. Supporting all the upgrade and downgrade paths -through the transition is very nuanced, and will be explained in detail when the transition -occurs. We will commit to supporting both fields and annotations for at least 2 releases, and will -explicitly reject the annotations for at least 2 releases after that. +{{}} ## Authoring Profiles @@ -415,10 +401,6 @@ tools to help with that: * [bane](https://github.com/jfrazelle/bane) is an AppArmor profile generator for Docker that uses a simplified profile language. -It is recommended to run your application through Docker on a development workstation to generate -the profiles, but there is nothing preventing running the tools on the Kubernetes node where your -Pod is running. - To debug problems with AppArmor, you can check the system logs to see what, specifically, was denied. AppArmor logs verbose messages to `dmesg`, and errors can usually be found in the system logs or through `journalctl`. More information is provided in @@ -441,9 +423,8 @@ Specifying the profile a container will run with: - `runtime/default`: Refers to the default runtime profile. - Equivalent to not specifying a profile (without a PodSecurityPolicy default), except it still requires AppArmor to be enabled. - - For Docker, this resolves to the - [`docker-default`](https://docs.docker.com/engine/security/apparmor/) profile for non-privileged - containers, and unconfined (no profile) for privileged containers. + - In practice, many container runtimes use the same OCI default profile, defined here: + https://github.com/containers/common/blob/main/pkg/apparmor/apparmor_linux_template.go - `localhost/`: Refers to a profile loaded on the node (localhost) by name. - The possible profile names are detailed in the [core policy reference](https://gitlab.com/apparmor/apparmor/wikis/AppArmor_Core_Policy_Reference#profile-names-and-attachment-specifications). @@ -474,5 +455,3 @@ Additional resources: * [Quick guide to the AppArmor profile language](https://gitlab.com/apparmor/apparmor/wikis/QuickProfileLanguage) * [AppArmor core policy reference](https://gitlab.com/apparmor/apparmor/wikis/Policy_Layout) - - diff --git a/content/en/docs/tutorials/security/cluster-level-pss.md b/content/en/docs/tutorials/security/cluster-level-pss.md index fb610f99a9..4da0502aca 100644 --- a/content/en/docs/tutorials/security/cluster-level-pss.md +++ b/content/en/docs/tutorials/security/cluster-level-pss.md @@ -12,7 +12,7 @@ Pod Security admission (PSA) is enabled by default in v1.23 and later, as it has [graduated to beta](/blog/2021/12/09/pod-security-admission-beta/). Pod Security is an admission controller that carries out checks against the Kubernetes -[Pod Security Standards](docs/concepts/security/pod-security-standards/) when new pods are +[Pod Security Standards](/docs/concepts/security/pod-security-standards/) when new pods are created. This tutorial shows you how to enforce the `baseline` Pod Security Standard at the cluster level which applies a standard configuration to all namespaces in a cluster. diff --git a/content/en/docs/tutorials/stateless-application/guestbook.md b/content/en/docs/tutorials/stateless-application/guestbook.md index c31bcbc49e..78e19ad34a 100644 --- a/content/en/docs/tutorials/stateless-application/guestbook.md +++ b/content/en/docs/tutorials/stateless-application/guestbook.md @@ -243,7 +243,7 @@ pointing to. This IP address is accessible only within the cluster. If you want guests to be able to access your guestbook, you must configure the frontend Service to be externally visible, so a client can request the Service -from outside the Kubernetes cluster. However a Kubernetes user you can use +from outside the Kubernetes cluster. However a Kubernetes user can use `kubectl port-forward` to access the service even though it uses a `ClusterIP`. diff --git a/content/en/examples/examples_test.go b/content/en/examples/examples_test.go index ac50cdfe4c..eaf6e5808e 100644 --- a/content/en/examples/examples_test.go +++ b/content/en/examples/examples_test.go @@ -556,6 +556,7 @@ func TestExampleObjectSchemas(t *testing.T) { "pod-projected-svc-token": {&api.Pod{}}, "pod-rs": {&api.Pod{}, &api.Pod{}}, "pod-single-configmap-env-variable": {&api.Pod{}}, + "pod-with-affinity-anti-affinity": {&api.Pod{}}, "pod-with-node-affinity": {&api.Pod{}}, "pod-with-pod-affinity": {&api.Pod{}}, "pod-with-toleration": {&api.Pod{}}, diff --git a/content/en/examples/pods/pod-with-affinity-anti-affinity.yaml b/content/en/examples/pods/pod-with-affinity-anti-affinity.yaml new file mode 100644 index 0000000000..a7d14b2d6f --- /dev/null +++ b/content/en/examples/pods/pod-with-affinity-anti-affinity.yaml @@ -0,0 +1,32 @@ +apiVersion: v1 +kind: Pod +metadata: + name: with-affinity-anti-affinity +spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - linux + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 1 + preference: + matchExpressions: + - key: label-1 + operator: In + values: + - key-1 + - weight: 50 + preference: + matchExpressions: + - key: label-2 + operator: In + values: + - key-2 + containers: + - name: with-node-affinity + image: k8s.gcr.io/pause:2.0 \ No newline at end of file diff --git a/content/en/examples/pods/pod-with-node-affinity.yaml b/content/en/examples/pods/pod-with-node-affinity.yaml index 253d2b21ea..e077f79883 100644 --- a/content/en/examples/pods/pod-with-node-affinity.yaml +++ b/content/en/examples/pods/pod-with-node-affinity.yaml @@ -8,11 +8,10 @@ spec: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - - key: kubernetes.io/e2e-az-name + - key: kubernetes.io/os operator: In values: - - e2e-az1 - - e2e-az2 + - linux preferredDuringSchedulingIgnoredDuringExecution: - weight: 1 preference: diff --git a/content/en/examples/pods/resource/memory-request-limit-3.yaml b/content/en/examples/pods/resource/memory-request-limit-3.yaml index 9f089c4a7a..d816393986 100644 --- a/content/en/examples/pods/resource/memory-request-limit-3.yaml +++ b/content/en/examples/pods/resource/memory-request-limit-3.yaml @@ -8,9 +8,9 @@ spec: - name: memory-demo-3-ctr image: polinux/stress resources: - limits: - memory: "1000Gi" requests: memory: "1000Gi" + limits: + memory: "1000Gi" command: ["stress"] args: ["--vm", "1", "--vm-bytes", "150M", "--vm-hang", "1"] diff --git a/content/en/examples/pods/resource/memory-request-limit.yaml b/content/en/examples/pods/resource/memory-request-limit.yaml index 985b1308d9..07ce3e7d3c 100644 --- a/content/en/examples/pods/resource/memory-request-limit.yaml +++ b/content/en/examples/pods/resource/memory-request-limit.yaml @@ -8,9 +8,9 @@ spec: - name: memory-demo-ctr image: polinux/stress resources: - limits: - memory: "200Mi" requests: memory: "100Mi" + limits: + memory: "200Mi" command: ["stress"] args: ["--vm", "1", "--vm-bytes", "150M", "--vm-hang", "1"] diff --git a/content/en/releases/patch-releases.md b/content/en/releases/patch-releases.md index e956012593..3358da7171 100644 --- a/content/en/releases/patch-releases.md +++ b/content/en/releases/patch-releases.md @@ -78,10 +78,10 @@ releases may also occur in between these. | Monthly Patch Release | Cherry Pick Deadline | Target date | | --------------------- | -------------------- | ----------- | -| March 2022 | 2022-03-11 | 2022-03-16 | | April 2022 | 2022-04-08 | 2022-04-13 | | May 2022 | 2022-05-13 | 2022-05-18 | | June 2022 | 2022-06-10 | 2022-06-15 | +| July 2022 | 2022-07-08 | 2022-07-13 | ## Detailed Release History for Active Branches @@ -93,6 +93,7 @@ End of Life for **1.23** is **2023-02-28**. | Patch Release | Cherry Pick Deadline | Target Date | Note | |---------------|----------------------|-------------|------| +| 1.23.6 | 2022-04-08 | 2022-04-13 | | | 1.23.5 | 2022-03-11 | 2022-03-16 | | | 1.23.4 | 2022-02-11 | 2022-02-16 | | | 1.23.3 | 2022-01-24 | 2022-01-25 | [Out-of-Band Release](https://groups.google.com/u/2/a/kubernetes.io/g/dev/c/Xl1sm-CItaY) | @@ -107,6 +108,7 @@ End of Life for **1.22** is **2022-10-28** | Patch Release | Cherry Pick Deadline | Target Date | Note | |---------------|----------------------|-------------|------| +| 1.22.9 | 2022-04-08 | 2022-04-13 | | | 1.22.8 | 2022-03-11 | 2022-03-16 | | | 1.22.7 | 2022-02-11 | 2022-02-16 | | | 1.22.6 | 2022-01-14 | 2022-01-19 | | @@ -124,6 +126,7 @@ End of Life for **1.21** is **2022-06-28** | Patch Release | Cherry Pick Deadline | Target Date | Note | | ------------- | -------------------- | ----------- | ---------------------------------------------------------------------- | +| 1.21.12 | 2022-04-08 | 2022-04-13 | | | 1.21.11 | 2022-03-11 | 2022-03-16 | | | 1.21.10 | 2022-02-11 | 2022-02-16 | | | 1.21.9 | 2022-01-14 | 2022-01-19 | | diff --git a/content/fr/docs/tasks/configure-pod-container/translate-compose-kubernetes.md b/content/fr/docs/tasks/configure-pod-container/translate-compose-kubernetes.md index f856847e85..0ade44801b 100644 --- a/content/fr/docs/tasks/configure-pod-container/translate-compose-kubernetes.md +++ b/content/fr/docs/tasks/configure-pod-container/translate-compose-kubernetes.md @@ -121,22 +121,7 @@ En quelques étapes, nous vous emmenons de Docker Compose à Kubernetes. Tous do kompose.service.type: LoadBalancer ``` -2. Lancez la commande `kompose up` pour déployer directement sur Kubernetes, ou passez plutôt à l'étape suivante pour générer un fichier à utiliser avec `kubectl`. - - ```bash - $ kompose up - We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. - If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead. - - INFO Successfully created Service: redis - INFO Successfully created Service: web - INFO Successfully created Deployment: redis - INFO Successfully created Deployment: web - - Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. - ``` - -3. Pour convertir le fichier `docker-compose.yml` en fichiers que vous pouvez utiliser avec `kubectl`, lancez `kompose convert` et ensuite `kubectl apply -f `. +2. Pour convertir le fichier `docker-compose.yml` en fichiers que vous pouvez utiliser avec `kubectl`, lancez `kompose convert` et ensuite `kubectl apply -f `. ```bash $ kompose convert @@ -160,7 +145,7 @@ En quelques étapes, nous vous emmenons de Docker Compose à Kubernetes. Tous do Vos déploiements fonctionnent sur Kubernetes. -4. Accédez à votre application. +3. Accédez à votre application. Si vous utilisez déjà `minikube` pour votre processus de développement : @@ -201,10 +186,7 @@ En quelques étapes, nous vous emmenons de Docker Compose à Kubernetes. Tous do - CLI - [`kompose convert`](#kompose-convert) - - [`kompose up`](#kompose-up) - - [`kompose down`](#kompose-down) - Documentation - - [Construire et pousser des images de docker](#build-and-push-docker-images) - [Conversions alternatives](#alternative-conversions) - [Etiquettes](#labels) - [Redémarrage](#restart) @@ -301,152 +283,6 @@ INFO OpenShift file "foo-buildconfig.yaml" created Si vous poussez manuellement les artefacts OpenShift en utilisant ``oc create -f``, vous devez vous assurer que vous poussez l'artefact imagestream avant l'artefact buildconfig, pour contourner ce problème OpenShift : https://github.com/openshift/origin/issues/4518 . {{< /note >}} -## `kompose up` - -Kompose propose un moyen simple de déployer votre application "composée" sur Kubernetes ou OpenShift via `kompose up`. - - -### Kubernetes -```sh -$ kompose --file ./examples/docker-guestbook.yml up -We are going to create Kubernetes deployments and services for your Dockerized application. -If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead. - -INFO Successfully created service: redis-master -INFO Successfully created service: redis-slave -INFO Successfully created service: frontend -INFO Successfully created deployment: redis-master -INFO Successfully created deployment: redis-slave -INFO Successfully created deployment: frontend - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details. - -$ kubectl get deployment,svc,pods -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -deployment.extensions/frontend 1 1 1 1 4m -deployment.extensions/redis-master 1 1 1 1 4m -deployment.extensions/redis-slave 1 1 1 1 4m - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -service/frontend ClusterIP 10.0.174.12 80/TCP 4m -service/kubernetes ClusterIP 10.0.0.1 443/TCP 13d -service/redis-master ClusterIP 10.0.202.43 6379/TCP 4m -service/redis-slave ClusterIP 10.0.1.85 6379/TCP 4m - -NAME READY STATUS RESTARTS AGE -pod/frontend-2768218532-cs5t5 1/1 Running 0 4m -pod/redis-master-1432129712-63jn8 1/1 Running 0 4m -pod/redis-slave-2504961300-nve7b 1/1 Running 0 4m -``` - -**Note**: - -- Vous devez avoir un cluster Kubernetes en cours d'exécution avec kubectl pré-configuré. -- Seuls les déploiements et les services sont générés et déployés dans Kubernetes. Si vous avez besoin d'autres types de ressources, utilisez les commandes `kompose convert` et `kubectl apply -f` à la place. - -### OpenShift -```sh -$ kompose --file ./examples/docker-guestbook.yml --provider openshift up -We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application. -If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. - -INFO Successfully created service: redis-slave -INFO Successfully created service: frontend -INFO Successfully created service: redis-master -INFO Successfully created deployment: redis-slave -INFO Successfully created ImageStream: redis-slave -INFO Successfully created deployment: frontend -INFO Successfully created ImageStream: frontend -INFO Successfully created deployment: redis-master -INFO Successfully created ImageStream: redis-master - -Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details. - -$ oc get dc,svc,is -NAME REVISION DESIRED CURRENT TRIGGERED BY -dc/frontend 0 1 0 config,image(frontend:v4) -dc/redis-master 0 1 0 config,image(redis-master:e2e) -dc/redis-slave 0 1 0 config,image(redis-slave:v1) -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -svc/frontend 172.30.46.64 80/TCP 8s -svc/redis-master 172.30.144.56 6379/TCP 8s -svc/redis-slave 172.30.75.245 6379/TCP 8s -NAME DOCKER REPO TAGS UPDATED -is/frontend 172.30.12.200:5000/fff/frontend -is/redis-master 172.30.12.200:5000/fff/redis-master -is/redis-slave 172.30.12.200:5000/fff/redis-slave v1 -``` - -**Note**: - -- Vous devez avoir un cluster OpenShift en cours d'exécution avec `oc` pré-configuré (`oc login`) - -## `kompose down` - -Une fois que vous avez déployé l'application "composée" sur Kubernetes, `$ kompose down` vous -facilitera la suppression de l'application en supprimant ses déploiements et services. Si vous avez besoin de supprimer d'autres ressources, utilisez la commande 'kubectl'. - -```sh -$ kompose --file docker-guestbook.yml down -INFO Successfully deleted service: redis-master -INFO Successfully deleted deployment: redis-master -INFO Successfully deleted service: redis-slave -INFO Successfully deleted deployment: redis-slave -INFO Successfully deleted service: frontend -INFO Successfully deleted deployment: frontend -``` - -**Note**: - -- Vous devez avoir un cluster Kubernetes en cours d'exécution avec kubectl pré-configuré. - -## Construire et pousser des images de docker - -Kompose permet de construire et de pousser des images Docker. Lorsque vous utilisez la clé `build` dans votre fichier Docker Compose, votre image sera : - - - Automatiquement construite avec le Docker en utilisant la clé "image" spécifiée dans votre fichier - - Être poussé vers le bon dépôt Docker en utilisant les identifiants locaux (situés dans `.docker/config`) - -Utilisation d'un [exemple de fichier Docker Compose](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/buildconfig/docker-compose.yml): - -```yaml -version: "2" - -services: - foo: - build: "./build" - image: docker.io/foo/bar -``` - -En utilisant `kompose up` avec une clé `build` : - -```none -$ kompose up -INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar' -INFO Building image 'docker.io/foo/bar' from directory 'build' -INFO Image 'docker.io/foo/bar' from directory 'build' built successfully -INFO Pushing image 'foo/bar:latest' to registry 'docker.io' -INFO Attempting authentication credentials 'https://index.docker.io/v1/ -INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io' -INFO We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. If you need different kind of resources, use the 'kompose convert' and 'kubectl apply -f' commands instead. - -INFO Deploying application in "default" namespace -INFO Successfully created Service: foo -INFO Successfully created Deployment: foo - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. -``` - -Afin de désactiver cette fonctionnalité, ou de choisir d'utiliser la génération de BuildConfig (avec OpenShift) `--build (local|build-config|none)` peut être passé. - -```sh -# Désactiver la construction/poussée d'images Docker -$ kompose up --build none - -# Générer des artefacts de Build Config pour OpenShift -$ kompose up --provider openshift --build build-config -``` - ## Autres conversions La transformation par défaut `komposer` va générer des [Déploiements](/docs/concepts/workloads/controllers/deployment/) et [Services](/docs/concepts/services-networking/service/) de Kubernetes, au format yaml. Vous avez une autre option pour générer json avec `-j`. Vous pouvez aussi générer des objets de [Replication Controllers](/docs/concepts/workloads/controllers/replicationcontroller/), [Daemon Sets](/docs/concepts/workloads/controllers/daemonset/), ou [Helm](https://github.com/helm/helm) charts. diff --git a/content/ja/docs/concepts/cluster-administration/addons.md b/content/ja/docs/concepts/cluster-administration/addons.md index 466491cd4c..f0f1baa402 100644 --- a/content/ja/docs/concepts/cluster-administration/addons.md +++ b/content/ja/docs/concepts/cluster-administration/addons.md @@ -21,7 +21,6 @@ content_type: concept * [Canal](https://github.com/tigera/canal/tree/master/k8s-install)はFlannelとCalicoをあわせたもので、ネットワークとネットワークポリシーを提供します。 * [Cilium](https://github.com/cilium/cilium)は、L3のネットワークとネットワークポリシーのプラグインで、HTTP/API/L7のポリシーを透過的に強制できます。ルーティングとoverlay/encapsulationモードの両方をサポートしており、他のCNIプラグイン上で機能できます。 * [CNI-Genie](https://github.com/Huawei-PaaS/CNI-Genie)は、KubernetesをCalico、Canal、Flannel、Romana、Weaveなど選択したCNIプラグインをシームレスに接続できるようにするプラグインです。 -* [Contiv](https://contiv.github.io)は、さまざまなユースケースと豊富なポリシーフレームワーク向けに設定可能なネットワーク(BGPを使用したネイティブのL3、vxlanを使用したオーバーレイ、古典的なL2、Cisco-SDN/ACI)を提供します。Contivプロジェクトは完全に[オープンソース](https://github.com/contiv)です。[インストーラ](https://github.com/contiv/install)はkubeadmとkubeadm以外の両方をベースとしたインストールオプションがあります。 * [Contrail](https://www.juniper.net/us/en/products-services/sdn/contrail/contrail-networking/)は、[Tungsten Fabric](https://tungsten.io)をベースにしている、オープンソースでマルチクラウドに対応したネットワーク仮想化およびポリシー管理プラットフォームです。ContrailおよびTungsten Fabricは、Kubernetes、OpenShift、OpenStack、Mesosなどのオーケストレーションシステムと統合されており、仮想マシン、コンテナ/Pod、ベアメタルのワークロードに隔離モードを提供します。 * [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually)は、Kubernetesで使用できるオーバーレイネットワークプロバイダーです。 * [Knitter](https://github.com/ZTE/Knitter/)は、1つのKubernetes Podで複数のネットワークインターフェイスをサポートするためのプラグインです。 diff --git a/content/ja/docs/concepts/scheduling-eviction/pod-overhead.md b/content/ja/docs/concepts/scheduling-eviction/pod-overhead.md new file mode 100644 index 0000000000..f88da29e8f --- /dev/null +++ b/content/ja/docs/concepts/scheduling-eviction/pod-overhead.md @@ -0,0 +1,160 @@ +--- +title: Podのオーバーヘッド +content_type: concept +weight: 30 +--- + + + +{{< feature-state for_k8s_version="v1.18" state="beta" >}} + + +PodをNode上で実行する時に、Pod自身は大量のシステムリソースを消費します。これらのリソースは、Pod内のコンテナ(群)を実行するために必要なリソースとして追加されます。Podのオーバーヘッドは、コンテナの要求と制限に加えて、Podのインフラストラクチャで消費されるリソースを計算するための機能です。 + + + + + + +Kubernetesでは、Podの[RuntimeClass](/docs/concepts/containers/runtime-class/)に関連するオーバーヘッドに応じて、[アドミッション](/ja/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks)時にPodのオーバーヘッドが設定されます。 + +Podのオーバーヘッドを有効にした場合、Podのスケジューリング時にコンテナのリソース要求の合計に加えて、オーバーヘッドも考慮されます。同様に、Kubeletは、Podのcgroupのサイズ決定時およびPodの退役の順位付け時に、Podのオーバーヘッドを含めます。 + +## Podのオーバーヘッドの有効化　{#set-up} + +クラスター全体で`PodOverhead`の[フィーチャーゲート](/ja/docs/reference/command-line-tools-reference/feature-gates/)が有効になっていること（1.18時点ではデフォルトでオンになっています）と、`overhead`フィールドを定義する`RuntimeClass`が利用されていることを確認する必要があります。 + +## 使用例 + +Podのオーバーヘッド機能を使用するためには、`overhead`フィールドが定義されたRuntimeClassが必要です。例として、仮想マシンとゲストOSにPodあたり約120MiBを使用する仮想化コンテナランタイムで、次のようなRuntimeClassを定義できます。 + +```yaml +--- +kind: RuntimeClass +apiVersion: node.k8s.io/v1 +metadata: + name: kata-fc +handler: kata-fc +overhead: + podFixed: + memory: "120Mi" + cpu: "250m" +``` + +`kata-fc`RuntimeClassハンドラーを指定して作成されたワークロードは、リソースクォータの計算や、Nodeのスケジューリング、およびPodのcgroupのサイズ決定にメモリーとCPUのオーバーヘッドが考慮されます。 + +次のtest-podのワークロードの例を実行するとします。 + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: test-pod +spec: + runtimeClassName: kata-fc + containers: + - name: busybox-ctr + image: busybox + stdin: true + tty: true + resources: + limits: + cpu: 500m + memory: 100Mi + - name: nginx-ctr + image: nginx + resources: + limits: + cpu: 1500m + memory: 100Mi +``` + +アドミッション時、RuntimeClass[アドミッションコントローラー](/docs/reference/access-authn-authz/admission-controllers/)は、RuntimeClass内に記述された`オーバーヘッド`を含むようにワークロードのPodSpecを更新します。もし既にPodSpec内にこのフィールドが定義済みの場合、そのPodは拒否されます。この例では、RuntimeClassの名前しか指定されていないため、アドミッションコントローラーは`オーバーヘッド`を含むようにPodを変更します。 + +RuntimeClassのアドミッションコントローラーの後、更新されたPodSpecを確認できます。 + +```bash +kubectl get pod test-pod -o jsonpath='{.spec.overhead}' +``` + +出力は次の通りです: +``` +map[cpu:250m memory:120Mi] +``` +ResourceQuotaが定義されている場合、コンテナ要求の合計と`オーバーヘッド`フィールドがカウントされます。 + +kube-schedulerが新しいPodを実行すべきNodeを決定する際、スケジューラーはそのPodの`オーバーヘッド`と、そのPodに対するコンテナ要求の合計を考慮します。この例だと、スケジューラーは、要求とオーバーヘッドを追加し、2.25CPUと320MiBのメモリを持つNodeを探します。 + +PodがNodeにスケジュールされると、そのNodeのkubeletはPodのために新しい{{< glossary_tooltip text="cgroup" term_id="cgroup" >}}を生成します。基盤となるコンテナランタイムがコンテナを作成するのは、このPod内です。 + +リソースにコンテナごとの制限が定義されている場合(制限が定義されているGuaranteed QoSまたはBustrable QoS)、kubeletはそのリソース(CPUはcpu.cfs_quota_us、メモリはmemory.limit_in_bytes)に関連するPodのcgroupの上限を設定します。この上限は、コンテナの制限とPodSpecで定義された`オーバーヘッド`の合計に基づきます。 + +CPUについては、PodがGuaranteedまたはBurstable QoSの場合、kubeletはコンテナの要求の合計とPodSpecに定義された`オーバーヘッド`に基づいて`cpu.share`を設定します。 + +次の例より、ワークロードに対するコンテナの要求を確認できます。 +```bash +kubectl get pod test-pod -o jsonpath='{.spec.containers[*].resources.limits}' +``` + +コンテナの要求の合計は、CPUは2000m、メモリーは200MiBです。 +``` +map[cpu: 500m memory:100Mi] map[cpu:1500m memory:100Mi] +``` + +Nodeで観測される値と比較してみましょう。 +```bash +kubectl describe node | grep test-pod -B2 +``` + +出力では、2250mのCPUと320MiBのメモリーが要求されており、Podのオーバーヘッドが含まれていることが分かります。 +``` + Namespace Name CPU Requests CPU Limits Memory Requests Memory Limits AGE + --------- ---- ------------ ---------- --------------- ------------- --- + default test-pod 2250m (56%) 2250m (56%) 320Mi (1%) 320Mi (1%) 36m +``` + +## Podのcgroupの制限を確認 + +ワークロードで実行中のNode上にある、Podのメモリーのcgroupを確認します。次に示す例では、CRI互換のコンテナランタイムのCLIを提供するNodeで[`crictl`](https://github.com/kubernetes-sigs/cri-tools/blob/master/docs/crictl.md)を使用しています。これはPodのオーバーヘッドの動作を示すための高度な例であり、ユーザーがNode上で直接cgroupsを確認する必要はありません。 + +まず、特定のNodeで、Podの識別子を決定します。 + +```bash +# PodがスケジュールされているNodeで実行 +POD_ID="$(sudo crictl pods --name test-pod -q)" +``` + +ここから、Podのcgroupのパスが決定します。 +```bash +# PodがスケジュールされているNodeで実行 +sudo crictl inspectp -o=json $POD_ID | grep cgroupsPath +``` + +結果のcgroupパスにはPodの`ポーズ中`コンテナも含まれます。Podレベルのcgroupは１つ上のディレクトリです。 +``` + "cgroupsPath": "/kubepods/podd7f4b509-cf94-4951-9417-d1087c92a5b2/7ccf55aee35dd16aca4189c952d83487297f3cd760f1bbf09620e206e7d0c27a" +``` + +今回のケースでは、Podのcgroupパスは、`kubepods/podd7f4b509-cf94-4951-9417-d1087c92a5b2`となります。メモリーのPodレベルのcgroupの設定を確認しましょう。 +```bash +# PodがスケジュールされているNodeで実行 +# また、Podに割り当てられたcgroupと同じ名前に変更 + cat /sys/fs/cgroup/memory/kubepods/podd7f4b509-cf94-4951-9417-d1087c92a5b2/memory.limit_in_bytes +``` + +予想通り320MiBです。 +``` +335544320 +``` + +### Observability + +Podのオーバヘッドが利用されているタイミングを特定し、定義されたオーバーヘッドで実行されているワークロードの安定性を観察するため、[kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)には`kube_pod_overhead`というメトリクスが用意されています。この機能はv1.9のkube-state-metricsでは利用できませんが、次のリリースで期待されています。それまでは、kube-state-metricsをソースからビルドする必要があります。 + + + +## {{% heading "whatsnext" %}} + + +* [RuntimeClass](/ja/docs/concepts/containers/runtime-class/) +* [Podのオーバーヘッドの設計](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/688-pod-overhead) diff --git a/content/ja/docs/concepts/scheduling-eviction/scheduling-framework.md b/content/ja/docs/concepts/scheduling-eviction/scheduling-framework.md new file mode 100644 index 0000000000..23ab9f5750 --- /dev/null +++ b/content/ja/docs/concepts/scheduling-eviction/scheduling-framework.md @@ -0,0 +1,174 @@ +--- +title: スケジューリングフレームワーク +content_type: concept +weight: 90 +--- + + + +{{< feature-state for_k8s_version="v1.19" state="stable" >}} + +スケジューリングフレームワークはKubernetesのスケジューラーに対してプラグイン可能なアーキテクチャです。 +このアーキテクチャは、既存のスケジューラーに新たに「プラグイン」としてAPI群を追加するもので、プラグインはスケジューラー内部にコンパイルされます。このAPI群により、スケジューリングの「コア」の軽量かつ保守しやすい状態に保ちながら、ほとんどのスケジューリングの機能をプラグインとして実装することができます。このフレームワークの設計に関する技術的な情報についてはこちらの[スケジューリングフレームワークの設計提案][kep]をご覧ください。 + +[kep]: https://github.com/kubernetes/enhancements/blob/master/keps/sig-scheduling/624-scheduling-framework/README.md + + + + +# フレームワークのワークフロー + +スケジューリングフレームワークは、いくつかの拡張点を定義しています。スケジューラープラグインは、1つ以上の拡張点で呼び出されるように登録します。これらのプラグインの中には、スケジューリングの決定を変更できるものから、単に情報提供のみを行うだけのものなどがあります。 + +この1つのPodをスケジュールしようとする各動作は**Scheduling Cycle**と**Binding Cycle**の2つのフェーズに分けられます。 + +## Scheduling Cycle & Binding Cycle + +Scheduling CycleではPodが稼働するNodeを決定し、Binding Cycleではそれをクラスターに適用します。この2つのサイクルを合わせて「スケジューリングコンテキスト」と呼びます。 + +Scheduling CycleではPodに対して1つ1つが順番に実行され、Binding Cyclesでは並列に実行されます。 + +Podがスケジューリング不能と判断された場合や、内部エラーが発生した場合、Scheduling CycleまたはBinding Cycleを中断することができます。その際、Podはキューに戻され再試行されます。 + +## 拡張点 + +次の図はPodに対するスケジューリングコンテキストとスケジューリングフレームワークが公開する拡張点を示しています。この図では「Filter」がフィルタリングのための「Predicate」、「Scoring」がスコアリングのための「Priorities」機能に相当します。 + +1つのプラグインを複数の拡張点に登録することで、より複雑なタスクやステートフルなタスクを実行することができます。 + +{{< figure src="/images/docs/scheduling-framework-extensions.png" title="scheduling framework extension points" class="diagram-large">}} + +### QueueSort {#queue-sort} + +これらのプラグインはスケジューリングキュー内のPodをソートするために使用されます。このプラグインは、基本的に`Less(Pod1, Pod2)`という関数を提供します。また、このプラグインは、1つだけ有効化できます。 + +### PreFilter {#pre-filter} + +これらのプラグインは、Podに関する情報を前処理したり、クラスターやPodが満たすべき特定の条件をチェックするために使用されます。もし、PreFilterプラグインのいずれかがエラーを返した場合、Scheduling Cycleは中断されます。 + +### Filter + +FilterプラグインはPodを実行できないNodeを候補から除外します。各Nodeに対して、スケジューラーは設定された順番でFilterプラグインを呼び出します。もし、いずれかのFilterプラグインが途中でそのNodeを実行不可能とした場合、残りのプラグインではそのNodeは呼び出されません。Nodeは同時に評価されることがあります。 + +### PostFilter {#post-filter} + +これらのプラグインはFilterフェーズで、Podに対して実行可能なNodeが見つからなかった場合にのみ呼び出されます。このプラグインは設定された順番で呼び出されます。もしいずれかのPostFilterプラグインが、あるNodeを「スケジュール可能(Schedulable)」と目星をつけた場合、残りのプラグインは呼び出されません。典型的なPostFilterの実装はプリエンプション方式で、他のPodを先取りして、Podをスケジューリングできるようにしようとします。 + +### PreScore {#pre-score} + +これらのプラグインは、Scoreプラグインが使用する共有可能な状態を生成する「スコアリングの事前」作業を行うために使用されます。このプラグインがエラーを返した場合、Scheduling Cycleは中断されます。 + +### Score {#scoring} + +これらのプラグインはフィルタリングのフェーズを通過したNodeをランク付けするために使用されます。スケジューラーはそれぞれのNodeに対して、それぞれのscoringプラグインを呼び出します。スコアの最小値と最大値の範囲が明確に定義されます。[NormalizeScore](#normalize-scoring)フェーズの後、スケジューラーは設定されたプラグインの重みに従って、全てのプラグインからNodeのスコアを足し合わせます。 + +### NormalizeScore {#normalize-scoring} + +これらのプラグインはスケジューラーが最終的なNodeの順位を計算する前にスコアを修正するために使用されます。この拡張点に登録されたプラグインは、同じプラグインの[Score](#scoring)の結果を使用して呼び出されます。各プラグインはScheduling Cycle毎に、1回呼び出されます。 + + +例えば、`BlinkingLightScorer`というプラグインが、点滅する光の数に基づいてランク付けをするとします。 + +```go +func ScoreNode(_ *v1.pod, n *v1.Node) (int, error) { + return getBlinkingLightCount(n) +} +``` + +ただし、`NodeScoreMax`に比べ、点滅をカウントした最大値の方が小さい場合があります。これを解決するために、`BlinkingLightScorer`も拡張点に登録する必要があります。 + +```go +func NormalizeScores(scores map[string]int) { + highest := 0 + for _, score := range scores { + highest = max(highest, score) + } + for node, score := range scores { + scores[node] = score*NodeScoreMax/highest + } +} +``` + +NormalizeScoreプラグインが途中でエラーを返した場合、Scheduling Cycleは中断されます。 + +{{< note >}} +「Reserveの事前」作業を行いたいプラグインは、NormalizeScore拡張点を使用してください。 +{{< /note >}} + +### Reserve {#reserve} + +Reserve拡張を実装したプラグインには、ReserveとUnreserve　という2つのメソッドがあり、それぞれ`Reserve` +と`Unreserve`と呼ばれる2つの情報スケジューリングフェーズを返します。 +実行状態を保持するプラグイン（別名「ステートフルプラグイン」）は、これらのフェーズを使用して、Podに対してNodeのリソースが予約されたり予約解除された場合に、スケジューラーから通知を受け取ります。 + +Reserveフェーズは、スケジューラーが実際にPodを指定されたNodeにバインドする前に発生します。このフェーズはスケジューラーがバインドが成功するのを待つ間にレースコンディションの発生を防ぐためにあります。 +各Reserveプラグインの`Reserve`メソッドは成功することも失敗することもあります。もしどこかの`Reserve`メソッドの呼び出しが失敗すると、後続のプラグインは実行されず、Reserveフェーズは失敗したものとみなされます。全てのプラグインの`Reserve`メソッドが成功した場合、Reserveフェーズは成功とみなされ、残りのScheduling CycleとBinding Cycleが実行されます。 + +Unreserveフェーズは、Reserveフェーズまたは後続のフェーズが失敗した場合に、呼び出されます。この時、**全ての**Reserveプラグインの`Unreserve`メソッドが、`Reserve`メソッドの呼び出された逆の順序で実行されます。このフェーズは予約されたPodに関連する状態をクリーンアップするためにあります。 + +{{< caution >}} +`Unreserve`メソッドの実装は冪等性を持つべきであり、この処理で問題があった場合に失敗させてはなりません。 +{{< /caution >}} + + +### Permit + +_Permit_ プラグインは、各PodのScheduling Cycleの終了時に呼び出され、候補Nodeへのバインドを阻止もしくは遅延させるために使用されます。permitプラグインは次の3つのうちどれかを実行できます。 + +1. **承認(approve)** \ + 全てのPermitプラグインから承認(approve)されたPodは、バインド処理へ送られます。 + +1. **拒否(deny)** \ + もしどれか1つのPermitプラグインがPodを拒否(deny)した場合、そのPodはスケジューリングキューに戻されます。 + これは[Reserveプラグイン](#reserve)内のUnreserveフェーズで呼び出されます。 + +1. **待機(wait)** (タイムアウトあり) \ + もしPermitプラグインが「待機(wait)」を返した場合、そのPodは内部の「待機中」Podリストに保持され、このPodに対するBinding Cycleは開始されるものの、承認(approve)されるまで直接ブロックされます。もしタイムアウトが発生した場合、この**待機(wait)**は**deny**へ変わり、対象のPodはスケジューリングキューに戻されると共に、[Reserveプラグイン](#reserve)のUnreserveフェーズが呼び出されます。 + +{{< note >}} +どのプラグインも「待機中」Podリストにアクセスして、それらを承認(approve)することができますが(参考:[`FrameworkHandle`](https://git.k8s.io/enhancements/keps/sig-scheduling/624-scheduling-framework#frameworkhandle))、その中の予約済みPodのバインドを承認(approve)できるのはPermitプラグインだけであると予想します。承認(approve)されたPodは、[PreBind](#pre-bind)フェーズへ送られます。 +{{< /note >}} + +### PreBind {#pre-bind} + +これらのプラグインは、Podがバインドされる前に必要な作業を行うために使用されます。例えば、Podの実行を許可する前に、ネットワークボリュームをプロビジョニングし、Podを実行予定のNodeにマウントすることができます。 + +もし、いずれかのPreBindプラグインがエラーを返した場合、Podは[拒否](#reserve)され、スケジューリングキューに戻されます。 + +### Bind + +これらのプラグインはPodをNodeにバインドするために使用されます。このプラグインは全てのPreBindプラグインの処理が完了するまで呼ばれません。それぞれのBindプラグインは設定された順序で呼び出されます。このプラグインは、与えられたPodを処理するかどうかを選択することができます。もしPodを処理することを選択した場合、**残りのBindプラグインは全てスキップされます。** + +### PostBind {#post-bind} + +これは単に情報提供のための拡張点です。Post-bindプラグインはPodのバインドが成功した後に呼び出されます。これはBinding Cycleの最後であり、関連するリソースのクリーンアップに使用されます。 + +## プラグインAPI + +プラグインAPIには2つの段階があります。まず、プラグインを登録し設定することです。そして、拡張点インターフェースを使用することです。このインターフェースは次のような形式をとります。 + +```go +type Plugin interface { + Name() string +} + +type QueueSortPlugin interface { + Plugin + Less(*v1.pod, *v1.pod) bool +} + +type PreFilterPlugin interface { + Plugin + PreFilter(context.Context, *framework.CycleState, *v1.pod) error +} + +// ... +``` + +## プラグインの設定 + +スケジューラーの設定でプラグインを有効化・無効化することができます。Kubernetes v1.18以降を使用しているなら、ほとんどのスケジューリング[プラグイン](/docs/reference/scheduling/config/#scheduling-plugins)は使用されており、デフォルトで有効になっています。 + +デフォルトのプラグインに加えて、独自のスケジューリングプラグインを実装し、デフォルトのプラグインと一緒に使用することも可能です。詳しくは[スケジューラープラグイン](https://github.com/kubernetes-sigs/scheduler-plugins)をご覧下さい。 + +Kubernetes v1.18以降を使用しているなら、プラグインのセットをスケジューラープロファイルとして設定し、様々な種類のワークロードに適合するように複数のプロファイルを定義することが可能です。詳しくは[複数のプロファイル](/docs/reference/scheduling/config/#multiple-profiles)をご覧下さい。 diff --git a/content/ja/docs/home/_index.md b/content/ja/docs/home/_index.md index 44419b4890..097c6f6fce 100644 --- a/content/ja/docs/home/_index.md +++ b/content/ja/docs/home/_index.md @@ -59,7 +59,7 @@ cards: title: "K8sリリースノート" description: "もしKubernetesをインストールする、また最新バージョンにアップグレードする場合、最新のリリースノートを参照してください。" button: "Kubernetesをダウンロードする" - button_path: "/docs/setup/release/notes" + button_path: "/releases/download" - name: about title: ドキュメントについて description: このWebサイトには、Kubernetesの最新バージョンと過去4世代のドキュメントが含まれています。 diff --git a/content/ja/docs/setup/best-practices/certificates.md b/content/ja/docs/setup/best-practices/certificates.md index 7fbf4bf8b8..b1e5448be7 100644 --- a/content/ja/docs/setup/best-practices/certificates.md +++ b/content/ja/docs/setup/best-practices/certificates.md @@ -62,15 +62,15 @@ CAの秘密鍵をクラスターにコピーしたくない場合、自身で全 必要な証明書: -| デフォルトCN | 親認証局 | 組織 　　　　　　| 種類 | ホスト名 (SAN) | -|-------------------------------|---------------------------|----------------|----------------------------------------|---------------------------------------------| -| kube-etcd | etcd-ca | | server, client | `localhost`, `127.0.0.1` | +| デフォルトCN | 親認証局 | 組織 　　　　　　| 種類 | ホスト名 (SAN) | +|-------------------------------|---------------------------|----------------|----------------------------------------|-----------------------------------------------------| +| kube-etcd | etcd-ca | | server, client | ``, ``, `localhost`, `127.0.0.1` | | kube-etcd-peer | etcd-ca | | server, client | ``, ``, `localhost`, `127.0.0.1` | -| kube-etcd-healthcheck-client | etcd-ca | | client | | -| kube-apiserver-etcd-client | etcd-ca | system:masters | client | | -| kube-apiserver | kubernetes-ca | | server | ``, ``, ``, `[1]` | -| kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | -| front-proxy-client | kubernetes-front-proxy-ca | | client | | +| kube-etcd-healthcheck-client | etcd-ca | | client | | +| kube-apiserver-etcd-client | etcd-ca | system:masters | client | | +| kube-apiserver | kubernetes-ca | | server | ``, ``, ``, `[1]` | +| kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | +| front-proxy-client | kubernetes-front-proxy-ca | | client | | [1]: クラスターに接続するIPおよびDNS名( [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/)を使用する場合と同様、ロードバランサーのIPおよびDNS名、`kubernetes`、`kubernetes.default`、`kubernetes.default.svc`、`kubernetes.default.svc.cluster`、`kubernetes.default.svc.cluster.local`) diff --git a/content/ja/docs/tasks/administer-cluster/securing-a-cluster.md b/content/ja/docs/tasks/administer-cluster/securing-a-cluster.md new file mode 100644 index 0000000000..d1a852efa2 --- /dev/null +++ b/content/ja/docs/tasks/administer-cluster/securing-a-cluster.md @@ -0,0 +1,197 @@ +--- +title: クラスターのセキュリティ +content_type: task +--- + + + +このドキュメントでは、偶発的または悪意のあるアクセスからクラスターを保護するためのトピックについて説明します。 +また、全体的なセキュリティに関する推奨事項を提供します。 + + +## {{% heading "prerequisites" %}} + + +* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + + + + + +## Kubernetes APIへのアクセスの制御 + +Kubernetesは完全にAPI駆動であるため、誰がクラスターにアクセスできるか、どのようなアクションを実行できるかを制御・制限することが第一の防御策となります。 + +### すべてのAPIトラフィックにTLS(Transport Layer Security)を使用する + +Kubernetesは、クラスター内のすべてのAPI通信がデフォルトでTLSにより暗号化されていることを期待しており、大半のインストール方法では、必要な証明書を作成してクラスターコンポーネントに配布することができます。 + +コンポーネントやインストール方法によっては、HTTP上のローカルポートを有効にする場合があることに注意してください。管理者は、潜在的に保護されていないトラフィックを特定するために、各コンポーネントの設定に精通している必要があります。 + +### APIの認証 + +クラスターのインストール時に、共通のアクセスパターンに合わせて、APIサーバーが使用する認証メカニズムを選択します。 +例えば、シングルユーザーの小規模なクラスターでは、シンプルな証明書や静的なBearerトークンを使用することができます。 +大規模なクラスターでは、ユーザーをグループに細分化できる既存のOIDCまたはLDAPサーバーを統合することができます。 + +ノード、プロキシー、スケジューラー、ボリュームプラグインなど、インフラの一部であるものも含めて、すべてのAPIクライアントを認証する必要があります。 +これらのクライアントは通常、[service accounts](/docs/reference/access-authn-authz/service-accounts-admin/)であるか、またはx509クライアント証明書を使用しており、クラスター起動時に自動的に作成されるか、クラスターインストールの一部として設定されます。 + +詳細については、[認証](/ja/docs/reference/access-authn-authz/authentication/)を参照してください。 + +### APIの認可 + +認証されると、すべてのAPIコールは認可チェックを通過することになります。 + +Kubernetesには、統合された[RBAC](/ja/docs/reference/access-authn-authz/rbac/)コンポーネントが搭載されており、入力されたユーザーやグループを、ロールにまとめられたパーミッションのセットにマッチさせます。 +これらのパーミッションは、動詞(get, create, delete)とリソース(pods, services, nodes)を組み合わせたもので、ネームスペース・スコープまたはクラスター・スコープに対応しています。 +すぐに使えるロールのセットが提供されており、クライアントが実行したいアクションに応じて、デフォルトで適切な責任の分離を提供します。 + +[Node](/docs/reference/access-authn-authz/node/)と[RBAC](/ja/docs/reference/access-authn-authz/rbac/)の承認者は、[NodeRestriction](/docs/reference/access-authn-authz/admission-controllers/#noderestriction)のアドミッションプラグインと組み合わせて使用することをお勧めします。 + +認証の場合と同様に、小規模なクラスターにはシンプルで幅広い役割が適切かもしれません。 +しかし、より多くのユーザーがクラスターに関わるようになるとチームを別の名前空間に分け、より限定的な役割を持たせることが必要になるかもしれません。 +認可においては、あるオブジェクトの更新が、他の場所でどのようなアクションを起こすかを理解することが重要です。 + +たとえば、ユーザーは直接Podを作成することはできませんが、ユーザーに代わってPodを作成するDeploymentの作成を許可することで、間接的にそれらのPodを作成することができます。 +同様に、APIからノードを削除すると、そのノードにスケジューリングされていたPodが終了し、他のノードに再作成されます。 +すぐに使えるロールは、柔軟性と一般的なユースケースのバランスを表していますが、より限定的なロールは、偶発的なエスカレーションを防ぐために慎重に検討する必要があります。 +すぐに使えるロールがニーズを満たさない場合は、ユースケースに合わせてロールを作成することができます。 + +詳しくは[authorization reference section](/docs/reference/access-authn-authz/authorization/)に参照してください。 + +## Kubeletへのアクセスの制御 + +Kubeletsは、ノードやコンテナの強力な制御を可能にするHTTPSエンドポイントを公開しています。 +デフォルトでは、KubeletsはこのAPIへの認証されていないアクセスを許可しています。 + +本番環境のクラスターでは、Kubeletの認証と認可を有効にする必要があります。 + +詳細は、[Kubelet 認証/認可](/ja/docs/reference/command-line-tools-reference/kubelet-authentication-authorization)に参照してください。 + +## ワークロードやユーザーのキャパシティーを実行時に制御 + +Kubernetesにおける権限付与は、意図的にハイレベルであり、リソースに対する粗いアクションに焦点を当てています。 + +より強力なコントロールは**policies**として存在し、それらのオブジェクトがクラスタや自身、その他のリソースにどのように作用するかをユースケースによって制限します。 + +### クラスターのリソース使用量の制限 + +[リソースクォータ](/ja/docs/concepts/policy/resource-quotas/)は、ネームスペースに付与されるリソースの数や容量を制限するものです。 + +これは、ネームスペースが割り当てることのできるCPU、メモリー、永続的なディスクの量を制限するためによく使われますが、各ネームスペースに存在するPod、サービス、ボリュームの数を制御することもできます。 + +[Limit ranges](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/)は、上記のリソースの一部の最大または最小サイズを制限することで、ユーザーがメモリーなどの一般的に予約されたリソースに対して不当に高いまたは低い値を要求するのを防いだり、何も指定されていない場合にデフォルトの制限を提供したりします。 + +### コンテナが利用する特権の制御 + +Podの定義には、[security context](/docs/tasks/configure-pod-container/security-context/)が含まれており、ノード上の特定の Linux ユーザー(rootなど)として実行するためのアクセス、特権的に実行するためのアクセス、ホストネットワークにアクセスするためのアクセス、その他の制御を要求することができます。 +[Pod security policies](/docs/concepts/policy/pod-security-policy/)は、危険なセキュリティコンテキスト設定を提供できるユーザーやサービスアカウントを制限することができます。 + +たとえば、Podのセキュリティポリシーでは、ボリュームマウント、特に`hostPath`を制限することができ、これはPodの制御すべき側面です。 +一般に、ほとんどのアプリケーションワークロードでは、ホストリソースへのアクセスを制限する必要があります。 +ホスト情報にアクセスすることなく、ルートプロセス(uid 0)として正常に実行できます。 +ただし、ルートユーザーに関連する権限を考慮して、非ルートユーザーとして実行するようにアプリケーションコンテナを記述する必要があります。 + +## コンテナが不要なカーネルモジュールをロードしないようにします + +Linuxカーネルは、ハードウェアが接続されたときやファイルシステムがマウントされたときなど、特定の状況下で必要となるカーネルモジュールをディスクから自動的にロードします。 +特にKubernetesでは、非特権プロセスであっても、適切なタイプのソケットを作成するだけで、特定のネットワークプロトコル関連のカーネルモジュールをロードさせることができます。これにより、管理者が使用されていないと思い込んでいるカーネルモジュールのセキュリティホールを攻撃者が利用できる可能性があります。 +特定のモジュールが自動的にロードされないようにするには、そのモジュールをノードからアンインストールしたり、ルールを追加してブロックしたりします。 + +ほとんどのLinuxディストリビューションでは、`/etc/modprobe.d/kubernetes-blacklist.conf`のような内容のファイルを作成することで実現できます。 + +``` +# DCCPは必要性が低く、複数の深刻な脆弱性があり、保守も十分ではありません。 +blacklist dccp + +# SCTPはほとんどのKubernetesクラスタでは使用されておらず、また過去には脆弱性がありました。 +blacklist sctp +``` + +モジュールのロードをより一般的にブロックするには、SELinuxなどのLinuxセキュリティモジュールを使って、コンテナに対する `module_request`権限を完全に拒否し、いかなる状況下でもカーネルがコンテナ用のモジュールをロードできないようにすることができます。 +(Podは、手動でロードされたモジュールや、より高い権限を持つプロセスに代わってカーネルがロードしたモジュールを使用することはできます)。 + + +### ネットワークアクセスの制限 + +名前空間の[ネットワークポリシー](/ja/docs/tasks/administer-cluster/declare-network-policy/)により、アプリケーション作成者は、他の名前空間のPodが自分の名前空間内のPodやポートにアクセスすることを制限することができます。 + +サポートされている[Kubernetes networking providers](/ja/docs/concepts/cluster-administration/networking/)の多くは、ネットワークポリシーを尊重するようになりました。 +クォータやリミットの範囲は、ユーザーがノードポートや負荷分散サービスを要求するかどうかを制御するためにも使用でき、多くのクラスターでは、ユーザーのアプリケーションがクラスターの外で見えるかどうかを制御できます。 +ノードごとのファイアウォール、クロストークを防ぐための物理的なクラスタノードの分離、高度なネットワークポリシーなど、プラグインや環境ごとにネットワークルールを制御する追加の保護機能が利用できる場合もあります。 + +### クラウドメタデータのAPIアクセスを制限 + +クラウドプラットフォーム(AWS、Azure、GCEなど)では、しばしばメタデータサービスをインスタンスローカルに公開しています。 +デフォルトでは、これらのAPIはインスタンス上で実行されているPodからアクセスでき、そのノードのクラウド認証情報や、kubelet認証情報などのプロビジョニングデータを含むことができます。 +これらの認証情報は、クラスター内でのエスカレーションや、同じアカウントの他のクラウドサービスへのエスカレーションに使用できます。 + +クラウドプラットフォーム上でKubernetesを実行する場合は、インスタンスの認証情報に与えられるパーミッションを制限し、[ネットワークポリシー](/ja/docs/tasks/administer-cluster/declare-network-policy/)を使用してメタデータAPIへのPodのアクセスを制限し、プロビジョニングデータを使用してシークレットを配信することは避けてください。 + +### Podのアクセス可能ノードを制御 + +デフォルトでは、どのノードがPodを実行できるかについての制限はありません。 +Kubernetesは、エンドユーザーが利用できる[Node上へのPodのスケジューリング](/ja/docs/concepts/scheduling-eviction/assign-pod-node/)と[TaintとToleration](/ja/docs/concepts/scheduling-eviction/taint-and-toleration/)を提供します。 +多くのクラスターでは、ワークロードを分離するためにこれらのポリシーを使用することは、作者が採用したり、ツールを使って強制したりする慣習になっています。 + +管理者としては、ベータ版のアドミッションプラグイン「PodNodeSelector」を使用して、ネームスペース内のPodをデフォルトまたは特定のノードセレクタを必要とするように強制することができます。 +エンドユーザーがネームスペースを変更できない場合は、特定のワークロード内のすべてのPodの配置を強く制限することができます。 + +## クラスターのコンポーネントの保護 + +このセクションでは、クラスターを危険から守るための一般的なパターンを説明します。 + +### etcdへのアクセスの制限 + +API用のetcdバックエンドへの書き込みアクセスは、クラスタ全体のrootを取得するのと同等であり、読み取りアクセスはかなり迅速にエスカレートするために使用できます。 +管理者は、TLSクライアント証明書による相互認証など、APIサーバーからetcdサーバーへの強力な認証情報を常に使用すべきであり、API サーバーのみがアクセスできるファイアウォールの後ろにetcdサーバーを隔離することがしばしば推奨されます。 + +{{< caution >}} +クラスター内の他のコンポーネントが、完全なキースペースへの読み取りまたは書き込みアクセスを持つマスターetcdインスタンスへのアクセスを許可することは、クラスター管理者のアクセスを許可することと同じです。 +マスター以外のコンポーネントに別のetcdインスタンスを使用するか、またはetcd ACLを使用してキースペースのサブセットへの読み取りおよび書き込みアクセスを制限することを強く推奨します。 +{{< /caution >}} + +### 監査ログの有効 + +[audit logger](/docs/tasks/debug-application-cluster/audit/)はベータ版の機能で、APIによって行われたアクションを記録し、侵害があった場合に後から分析できるようにするものです。 + +監査ログを有効にして、ログファイルを安全なサーバーにアーカイブすることをお勧めします。 + +### アルファまたはベータ機能へのアクセスの制限 + +アルファ版およびベータ版のKubernetesの機能は活発に開発が行われており、セキュリティ上の脆弱性をもたらす制限やバグがある可能性があります。 +常に、アルファ版またはベータ版の機能が提供する価値と、セキュリティ体制に起こりうるリスクを比較して評価してください。 +疑問がある場合は、使用しない機能を無効にしてください。 + +### インフラの認証情報を頻繁に交換 + +秘密やクレデンシャルの有効期間が短いほど、攻撃者がそのクレデンシャルを利用することは難しくなります。 +証明書の有効期間を短く設定し、そのローテーションを自動化します。 +発行されたトークンの利用可能期間を制御できる認証プロバイダーを使用し、可能な限り短いライフタイムを使用します。 +外部統合でサービス・アカウント・トークンを使用する場合、これらのトークンを頻繁にローテーションすることを計画します。 +例えば、ブートストラップ・フェーズが完了したら、ノードのセットアップに使用したブートストラップ・トークンを失効させるか、その認証を解除する必要があります。 + +### サードパーティの統合を有効にする前に確認 + +Kubernetesへの多くのサードパーティの統合は、クラスターのセキュリティプロファイルを変更する可能性があります。 +統合を有効にする際には、アクセスを許可する前に、拡張機能が要求するパーミッションを常に確認してください。 + +例えば、多くのセキュリティ統合は、事実上そのコンポーネントをクラスター管理者にしているクラスター上のすべての秘密を見るためのアクセスを要求するかもしれません。 +疑問がある場合は、可能な限り単一の名前空間で機能するように統合を制限してください。 +Podを作成するコンポーネントも、`kube-system`名前空間のような名前空間内で行うことができれば、予想外に強力になる可能性があります。これは、サービスアカウントのシークレットにアクセスしたり、サービスアカウントに寛容な[pod security policies](/docs/concepts/policy/pod-security-policy/)へのアクセスが許可されている場合に、昇格したパーミッションでPodが実行される可能性があるからです。 + +### etcdにあるSecretを暗号化 + +一般的に、etcdデータベースにはKubernetes APIを介してアクセス可能なあらゆる情報が含まれており、クラスターの状態に対する大きな可視性を攻撃者へ与える可能性があります。 +よく吟味されたバックアップおよび暗号化ソリューションを使用して、常にバックアップを暗号化し、可能な場合はフルディスク暗号化の使用を検討してください。 + +Kubernetesは1.7で導入された機能である[encryption at rest](/docs/tasks/administer-cluster/encrypt-data/)をサポートしており、これは1.13からはベータ版となっています。 +これは、etcdの`Secret`リソースを暗号化し、etcdのバックアップにアクセスした人が、それらのシークレットの内容を見ることを防ぎます。 +この機能は現在ベータ版ですが、バックアップが暗号化されていない場合や、攻撃者がetcdへの読み取りアクセスを得た場合に、追加の防御レベルを提供します。 + +### セキュリティアップデートのアラートの受信と脆弱性の報告 + +[kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce)に参加してください。 +グループに参加すると、セキュリティアナウンスに関するメールを受け取ることができます。 +脆弱性の報告方法については、[security reporting](/docs/reference/issues-security/security/)ページを参照してください。 diff --git a/content/ja/examples/admin/sched/my-scheduler.yaml b/content/ja/examples/admin/sched/my-scheduler.yaml index 3e51d12721..5c84398133 100644 --- a/content/ja/examples/admin/sched/my-scheduler.yaml +++ b/content/ja/examples/admin/sched/my-scheduler.yaml @@ -49,13 +49,15 @@ spec: livenessProbe: httpGet: path: /healthz - port: 10251 + port: 10259 + scheme: HTTPS initialDelaySeconds: 15 name: kube-second-scheduler readinessProbe: httpGet: path: /healthz - port: 10251 + port: 10259 + scheme: HTTPS resources: requests: cpu: '0.1' diff --git a/content/ko/docs/concepts/workloads/controllers/deployment.md b/content/ko/docs/concepts/workloads/controllers/deployment.md index e9725d2eea..7bcd5e94c5 100644 --- a/content/ko/docs/concepts/workloads/controllers/deployment.md +++ b/content/ko/docs/concepts/workloads/controllers/deployment.md @@ -1131,7 +1131,7 @@ API 버전 `apps/v1` 에서는 `.spec.selector` 와 `.metadata.labels` 이 설 `.spec.strategy.rollingUpdate.maxUnavailable` 은 업데이트 프로세스 중에 사용할 수 없는 최대 파드의 수를 지정하는 선택적 필드이다. 이 값은 절대 숫자(예: 5) 또는 의도한 파드 비율(예: 10%)이 될 수 있다. -절대 값은 반올림해서 백분율로 계산한다. +절대 값은 내림해서 백분율로 계산한다. 만약 `.spec.strategy.rollingUpdate.maxSurge` 가 0이면 값이 0이 될 수 없다. 기본 값은 25% 이다. 예를 들어 이 값을 30%로 설정하면 롤링업데이트 시작시 즉각 이전 레플리카셋의 크기를 @@ -1144,7 +1144,7 @@ API 버전 `apps/v1` 에서는 `.spec.selector` 와 `.metadata.labels` 이 설 `.spec.strategy.rollingUpdate.maxSurge` 는 의도한 파드의 수에 대해 생성할 수 있는 최대 파드의 수를 지정하는 선택적 필드이다. 이 값은 절대 숫자(예: 5) 또는 의도한 파드 비율(예: 10%)이 될 수 있다. `MaxUnavailable` 값이 0이면 이 값은 0이 될 수 없다. -절대 값은 반올림해서 백분율로 계산한다. 기본 값은 25% 이다. +절대 값은 올림해서 백분율로 계산한다. 기본 값은 25% 이다. 예를 들어 이 값을 30%로 설정하면 롤링업데이트 시작시 새 레플리카셋의 크기를 즉시 조정해서 기존 및 새 파드의 전체 갯수를 의도한 파드의 130%를 넘지 않도록 한다. diff --git a/content/ko/docs/tasks/run-application/horizontal-pod-autoscale.md b/content/ko/docs/tasks/run-application/horizontal-pod-autoscale.md index 3e0856e511..ef322e4b6d 100644 --- a/content/ko/docs/tasks/run-application/horizontal-pod-autoscale.md +++ b/content/ko/docs/tasks/run-application/horizontal-pod-autoscale.md @@ -51,7 +51,7 @@ Horizontal Pod Autoscaling을 활용하는 쿠버네티스는 Horizontal Pod Autoscaling을 간헐적으로(intermittently) 실행되는 -컨트롤 루프 형태로 구현했다(지숙적인 프로세스가 아니다). +컨트롤 루프 형태로 구현했다(지속적인 프로세스가 아니다). 실행 주기는 [`kube-controller-manager`](/docs/reference/command-line-tools-reference/kube-controller-manager/)의 `--horizontal-pod-autoscaler-sync-period` 파라미터에 의해 설정된다(기본 주기는 15초이다). diff --git a/content/pt-br/blog/_posts/2022-02-17-updated-dockershim-faq.md b/content/pt-br/blog/_posts/2022-02-17-updated-dockershim-faq.md new file mode 100644 index 0000000000..526ec6e344 --- /dev/null +++ b/content/pt-br/blog/_posts/2022-02-17-updated-dockershim-faq.md @@ -0,0 +1,208 @@ +--- +layout: blog +title: "Atualizado: Perguntas frequentes (FAQ) sobre a remoção do Dockershim" +date: 2022-02-17 +slug: dockershim-faq +aliases: [ '/dockershim' ] +--- + +**Esta é uma atualização do artigo original [FAQ sobre a depreciação do Dockershim](/blog/2020/12/02/dockershim-faq/), +publicado no final de 2020.** + +Este documento aborda algumas perguntas frequentes sobre a +descontinuação e remoção do _dockershim_, que foi +[anunciado](/blog/2020/12/08/kubernetes-1-20-release-announcement/) +como parte do lançamento do Kubernetes v1.20. Para obter mais detalhes sobre +o que isso significa, confira a postagem do blog +[Não entre em pânico: Kubernetes e Docker](/pt-br/blog/2020/12/02/dont-panic-kubernetes-and-docker/). + +Além disso, você pode ler [verifique se a remoção do dockershim afeta você](/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you/) +para determinar qual impacto a remoção do _dockershim_ teria para você +ou para sua organização. + +Como o lançamento do Kubernetes 1.24 se tornou iminente, estamos trabalhando bastante para tentar fazer uma transição suave. + +- Escrevemos uma postagem no blog detalhando nosso [compromisso e os próximos passos](/blog/2022/01/07/kubernetes-is-moving-on-from-dockershim/). +- Acreditamos que não há grandes obstáculos para a migração para [outros agentes de execução de contêiner](/docs/setup/production-environment/container-runtimes/#container-runtimes). +- Há também um guia [Migrando do dockershim](/docs/tasks/administer-cluster/migrating-from-dockershim/) disponível. +- Também criamos uma página para listar + [artigos sobre a remoção do dockershim e sobre o uso de agentes de execução compatíveis com CRI](/docs/reference/node/topics-on-dockershim-and-cri-compatible-runtimes/). Essa lista inclui alguns dos documentos já mencionados e também + abrange fontes externas selecionadas (incluindo guias de fornecedores). + +### Por que o _dockershim_ está sendo removido do Kubernetes? + +As primeiras versões do Kubernetes funcionavam apenas com um ambiente de execução de contêiner específico: +Docker Engine. Mais tarde, o Kubernetes adicionou suporte para trabalhar com outros agentes de execução de contêiner. +O padrão CRI (_Container Runtime Interface_ ou Interface de Agente de Execução de Containers) foi [criado](/blog/2016/12/container-runtime-interface-cri-in-kubernetes/) para +habilitar a interoperabilidade entre orquestradores (como Kubernetes) e diferentes agentes +de execução de contêiner. +O Docker Engine não implementa essa interface (CRI), então o projeto Kubernetes criou um +código especial para ajudar na transição, e tornou esse código _dockershim_ parte do projeto +Kubernetes. + +O código _dockershim_ sempre foi destinado a ser uma solução temporária (daí o nome: _shim_). +Você pode ler mais sobre a discussão e o planejamento da comunidade na +[Proposta de remoção do Dockershim para aprimoramento do Kubernetes][drkep]. +Na verdade, manter o _dockershim_ se tornou um fardo pesado para os mantenedores do Kubernetes. + +Além disso, recursos que são amplamente incompatíveis com o _dockershim_, como +_cgroups v2_ e _namespaces_ de usuário estão sendo implementados nos agentes de execução de CRI +mais recentes. A remoção do suporte para o _dockershim_ permitirá um maior +desenvolvimento nessas áreas. + +[drkep]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2221-remove-dockershim + +### Ainda posso usar o Docker Engine no Kubernetes 1.23? + +Sim, a única coisa que mudou na versão 1.20 é a presença de um aviso no log de inicialização +do [kubelet] se estiver usando o Docker Engine como agente de execução de contêiner. +Você verá este aviso em todas as versões até 1.23. A remoção do _dockershim_ ocorre no Kubernetes 1.24. + +[kubelet]: /docs/reference/command-line-tools-reference/kubelet/ + +### Quando o _dockershim_ será removido? + +Dado o impacto dessa mudança, estamos definindo um cronograma de depreciação mais longo. +A remoção do _dockershim_ está agendada para o Kubernetes v1.24, consulte a +[Proposta de remoção do Dockershim para aprimoramento do Kubernetes][drkep]. +O projeto Kubernetes trabalhará em estreita colaboração com fornecedores e outros ecossistemas para garantir +uma transição suave e avaliará os acontecimentos à medida que a situação for evoluindo. + +### Ainda posso usar o Docker Engine como meu agente de execução do contêiner? + +Primeiro, se você usa o Docker em seu próprio PC para desenvolver ou testar contêineres: nada muda. +Você ainda pode usar o Docker localmente, independentemente dos agentes de execução de contêiner que +você usa em seus Clusters Kubernetes. Os contêineres tornam esse tipo de interoperabilidade possível. + +Mirantis e Docker [comprometeram-se][mirantis] a manter um adaptador substituto para o +Docker Engine, e a manter este adaptador mesmo após o _dockershim_ ser removido +do Kubernetes. O adaptador substituto é chamado [`cri-dockerd`](https://github.com/Mirantis/cri-dockerd). + +[mirantis]: https://www.mirantis.com/blog/mirantis-to-take-over-support-of-kubernetes-dockershim-2/ + +### Minhas imagens de contêiner existentes ainda funcionarão? + +Sim, as imagens produzidas a partir do `docker build` funcionarão com todas as implementações do CRI. +Todas as suas imagens existentes ainda funcionarão exatamente da mesma forma. + +#### E as imagens privadas? + +Sim. Todos os agentes de execução de CRI são compatíveis com as mesmas configurações de segredos usadas no +Kubernetes, seja por meio do PodSpec ou ServiceAccount. + +### Docker e contêineres são a mesma coisa? + +Docker popularizou o padrão de contêineres Linux e tem sido fundamental no +desenvolvimento desta tecnologia. No entanto, os contêineres já existiam +no Linux há muito tempo. O ecossistema de contêineres cresceu para ser muito +mais abrangente do que apenas Docker. Padrões como o OCI e o CRI ajudaram muitas +ferramentas a crescer e prosperar no nosso ecossistema, alguns substituindo +aspectos do Docker, enquanto outros aprimoram funcionalidades já existentes. + +### Existem exemplos de pessoas que usam outros agentes de execução de contêineres em produção hoje? + +Todos os artefatos produzidos pelo projeto Kubernetes (binários Kubernetes) são validados +a cada lançamento de versão. + +Além disso, o projeto [kind] vem usando containerd há algum tempo e tem +visto uma melhoria na estabilidade para seu caso de uso. Kind e containerd são executados +várias vezes todos os dias para validar quaisquer alterações na base de código do Kubernetes. +Outros projetos relacionados seguem um padrão semelhante, demonstrando a estabilidade e +usabilidade de outros agentes de execução de contêiner. Como exemplo, o OpenShift 4.x utiliza +o agente de execução [CRI-O] em produção desde junho de 2019. + +Para outros exemplos e referências, dê uma olhada em projetos adeptos do containerd e +CRI-O, dois agentes de execução de contêineres sob o controle da _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 + +### As pessoas continuam referenciando OCI, o que é isso? + +OCI significa _[Open Container Initiative]_ (ou Iniciativa Open Source de Contêineres), que padronizou muitas das +interfaces entre ferramentas e tecnologias de contêiner. Eles mantêm uma +especificação padrão para imagens de contêiner (OCI image-spec) e para +contêineres em execução (OCI runtime-spec). Eles também mantêm uma implementação real +da especificação do agente de execução na forma de [runc], que é o agente de execução padrão +para ambos [containerd] e [CRI-O]. O CRI baseia-se nessas especificações de baixo nível para +fornecer um padrão de ponta a ponta para gerenciar contêineres. + +[Open Container Initiative]: https://opencontainers.org/about/overview/ +[runc]: https://github.com/opencontainers/runc +[containerd]: https://containerd.io/ + +### Qual implementação de CRI devo usar? + +Essa é uma pergunta complexa e depende de muitos fatores. Se você estiver +trabalhando com Docker, mudar para containerd deve ser uma troca relativamente fácil e +terá um desempenho estritamente melhor e menos sobrecarga. No entanto, nós encorajamos você a +explorar todas as opções do [cenário CNCF], pois outro agente de execução de contêiner +pode funcionar ainda melhor para o seu ambiente. + +[cenário CNCF]: https://landscape.cncf.io/card-mode?category=container-runtime&grouping=category + +### O que devo ficar atento ao mudar a minha implementação de CRI utilizada? + +Embora o código de conteinerização base seja o mesmo entre o Docker e a maioria dos +CRIs (incluindo containerd), existem algumas poucas diferenças. Alguns +pontos a se considerar ao migrar são: + +- Configuração de _log_ +- Limitações de recursos de agentes de execução +- Scripts de provisionamento que chamam o docker ou usam o docker por meio de seu soquete de controle +- Plugins kubectl que exigem CLI do docker ou o soquete de controle +- Ferramentas do projeto Kubernetes que requerem acesso direto ao Docker Engine + (por exemplo: a ferramenta depreciada `kube-imagepuller`) +- Configuração de funcionalidades como `registry-mirrors` e _registries_ inseguros +- Outros scripts de suporte ou _daemons_ que esperam que o Docker Engine esteja disponível e seja executado + fora do Kubernetes (por exemplo, agentes de monitoramento ou segurança) +- GPUs ou hardware especial e como eles se integram ao seu agente de execução e ao Kubernetes + +Se você usa solicitações ou limites de recursos do Kubernetes ou usa DaemonSets para coleta de logs +em arquivos, eles continuarão a funcionar da mesma forma. Mas se você personalizou +sua configuração `dockerd`, você precisará adaptá-la para seu novo agente de execução de +contêiner assim que possível. + +Outro aspecto a ser observado é que ferramentas para manutenção do sistema ou execuções dentro de um +contêiner no momento da criação de imagens podem não funcionar mais. Para o primeiro, a ferramenta +[`crictl`][cr] pode ser utilizada como um substituto natural (veja +[migrando do docker cli para o crictl](https://kubernetes.io/docs/tasks/debug-application-cluster/crictl/#mapping-from-docker-cli-to-crictl)) +e para o último, você pode usar novas opções de construções de contêiner, como [img], [buildah], +[kaniko], ou [buildkit-cli-for-kubectl] que não requerem 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 + +Para containerd, você pode começar com sua [documentação] para ver quais opções de configuração +estão disponíveis à medida que você vá realizando a migração. + +[documentação]: https://github.com/containerd/cri/blob/master/docs/registry.md + +Para obter instruções sobre como usar containerd e CRI-O com Kubernetes, consulte o +documentação do Kubernetes em [Agentes de execução de contêineres] + +[Agentes de execução de contêineres]: /docs/setup/production-environment/container-runtimes/ + +### E se eu tiver mais perguntas? + +Se você usa uma distribuição do Kubernetes com suporte do fornecedor, pode perguntar a eles sobre +planos de atualização para seus produtos. Para perguntas de usuário final, poste-as +no nosso fórum da comunidade de usuários: https://discuss.kubernetes.io/. + +Você também pode conferir a excelente postagem do blog +[Espere, o Docker está depreciado no Kubernetes agora?][dep], uma discussão técnica mais aprofundada +sobre as mudanças. + +[dep]: https://dev.to/inductor/wait-docker-is-deprecated-in-kubernetes-now-what-do-i-do-e4m + +### Posso ganhar um abraço? + +Sim, ainda estamos dando abraços se solicitado. 🤗🤗🤗 diff --git a/content/pt-br/docs/concepts/policy/limit-range.md b/content/pt-br/docs/concepts/policy/limit-range.md new file mode 100644 index 0000000000..929a760c2e --- /dev/null +++ b/content/pt-br/docs/concepts/policy/limit-range.md @@ -0,0 +1,58 @@ +--- +title: Intervalos de limite +content_type: concept +weight: 10 +--- + + + +Por padrão, os cointêineres são executados com [recursos computacionais](/docs/concepts/configuration/manage-resources-containers/) ilimitados em um cluster Kubernetes. Com cotas de recursos, os administradores de cluster podem restringir o consumo e a criação de recursos baseado no {{< glossary_tooltip text="namespace" term_id="namespace" >}}. Dentro de um _namespace_, pod ou contêiner pode haver o consumo de quantidade de CPU e memória definidos de acordo com a cota de recursos do _namespace_. Existe a preocupação de que um Pod ou contêiner possa monopolizar todos os recursos disponíveis, justamente por conta disso existe o conceito de _Limit Range_, ou intervalos de limite, que pode ser definido como uma política utilizada para a restrição de alocação de recursos (para pods ou contêineres) em um _namespace_. + + + +Um _LimitRange_ fornece restrições que podem: + +- Aplicar o uso mínimo e máximo de recursos computacionais por pod ou contêiner em um _namespace_. +- Impor a solicitação de armazenamento mínimo e máximo por _PersistentVolumeClaim_ em um _namespace_. +- Impor a proporção entre solicitação e limite para um recurso em um _namespace_. +- Definir a solicitação/limite padrão para recursos computacionais em um _namespace_ e utilizá-los automaticamente nos contêineres em tempo de execução. + +## Ativando o LimitRange + +O suporte ao _LimitRange_ foi ativado por padrão desde o Kubernetes 1.10. + +Um _LimitRange_ é aplicado em um _namespace_ específico quando há um objeto _LimitRange_ nesse _namespace_. + +O nome de um objeto _LimitRange_ deve ser um [nome de subdomínio DNS](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names) válido. + +### Visão geral do Limit Range + +- O administrador cria um _LimitRange_ em um _namespace_. +- Os usuários criam recursos como pods, contêineres e _PersistentVolumeClaims_ no _namespace_. +- O controlador de admissão `LimitRanger` impõe padrões e limites para todos os pods e contêineres que não definem os requisitos de recursos computacionais e rastreia o uso para garantir que não exceda o mínimo, o máximo e a proporção de recursos definidos em qualquer _LimitRange_ presente no _namespace_. +- Se estiver criando ou atualizando um recurso (Pod, Container, _PersistentVolumeClaim_) que viola uma restrição _LimitRange_, a solicitação ao servidor da API falhará com um código de status HTTP `403 FORBIDDEN` e uma mensagem explicando a restrição violada. +- Se um _LimitRange_ for ativado em um _namespace_ para recursos computacionais como `cpu` e `memória`, os usuários deverão especificar solicitações ou limites para esses valores. Caso contrário, o sistema pode rejeitar a criação do pod. +- As validações de _LimitRange_ ocorrem apenas no estágio de Admissão de Pod, não em Pods em Execução. + +Alguns exemplos de políticas que podem ser criadas utilizando os intervalos de limite são: + +- Em um cluster de 2 nós com capacidade de 8 GiB de RAM e 16 núcleos, restrinja os Pods em um namespace para solicitar 100m de CPU com um limite máximo de 500m para CPU e solicitar 200Mi para memória com um limite máximo de 600Mi para memória. +- Defina o limite e a solicitação de CPU padrão para 150m e a solicitação padrão de memória para 300Mi para contêineres iniciados sem solicitações de CPU e memória em suas especificações. + +Caso os limites totais do namespace sejam menores que a soma dos limites dos Pods/Contêineres, pode haver contenção por recursos. Nesse caso, os contêineres ou Pods não serão criados. + +Nem a contenção nem as alterações em um _LimitRange_ afetarão os recursos já criados. + +## {{% heading "whatsnext" %}} + +Consulte o [documento de design LimitRanger](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_limit_range.md) para obter mais informações. + +Para exemplos de uso de limites, leia: + +- [Como configurar restrições mínimas e máximas de CPU por _namespace_](/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace/). +- [Como configurar restrições de memória mínima e máxima por _namespace_](/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace/). +- [como configurar solicitações e limites de CPU padrão por _namespace_](/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace/). +- [como configurar solicitações e limites de memória padrão por _namespace_](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/). +- [como configurar o consumo mínimo e máximo de armazenamento por _namespace_](/docs/tasks/administer-cluster/limit-storage-consumption/#limitrange-to-limit-requests-for-storage). +- Um [exemplo detalhado de configuração de cota por _namespace_](/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/). + diff --git a/content/pt-br/docs/concepts/policy/resource-quotas.md b/content/pt-br/docs/concepts/policy/resource-quotas.md new file mode 100644 index 0000000000..b20baffb83 --- /dev/null +++ b/content/pt-br/docs/concepts/policy/resource-quotas.md @@ -0,0 +1,649 @@ +--- +title: Cotas de Recursos +content_type: concept +weight: 20 +--- + + + +Quando vários usuários ou equipes compartilham um cluster com um número fixo de nós, +há uma preocupação de que uma equipe possa usar mais do que é justo durante o compartilhamento de recursos. + +As cotas de recursos são uma ferramenta para os administradores resolverem essa preocupação. + + + +Uma cota de recurso, definida por um objeto `ResourceQuota`, fornece restrições que limitam +consumo de recursos agregados por _namespace_. Pode limitar a quantidade de objetos que podem +ser criado em um _namespace_ por tipo, bem como a quantidade total de recursos computacionais que podem +ser consumidos por recursos nesse _namespace_. + +As cotas de recursos funcionam assim: + +- Diferentes equipes trabalham em diferentes _namespaces_. Atualmente, isso é voluntário, mas o suporte para tornar isso obrigatório por meio de ACLs está planejado. + +- O administrador cria uma `ResourceQuota` para cada _namespace_. + +- Os usuários criam recursos (pods, serviços, etc.) no _namespace_ e o sistema de cotas rastreia o uso para garantir que ele não exceda os limites de recursos definidos em um `ResourceQuota`. + + +- Se a criação ou atualização de um recurso violar uma restrição de cota, a solicitação falhará com código de status HTTP `403 FORBIDDEN` acompanhado de uma mensagem explicando a restrição que foi violada. + +- Se a cota estiver habilitada em um _namespace_ para recursos computacionais como `cpu` e `memória`, os usuários devem especificar solicitações ou limites para esses valores; caso contrário, o sistema de cotas poderá rejeitar a criação de pods. Dica: use o controlador de admissão `LimitRanger` para forçar padrões para pods que não exigem recursos computacionais. + + Veja o [passo a passo](/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/) + para um exemplo de como evitar este problema. + +O nome de um objeto `ResourceQuota` deve ser um [nome do subdomínio DNS](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names) válido. + +Exemplos de políticas que podem ser criadas usando _namespaces_ e cotas são: + +- Em um cluster com capacidade de 32 GiB de RAM e 16 núcleos, deixe a equipe A usar 20 GiB e 10 núcleos, deixe B usar 10GiB e 4 núcleos e mantenha 2GiB e 2 núcleos em reserva para alocação futura. +- Limite o _namespace_ "testing" para usar 1 núcleo e 1GiB de RAM. Deixe o namespace "produção" usar qualquer quantia. + +Caso a capacidade total do cluster seja menor que a soma das cotas dos _namespaces_, pode haver contenção de recursos. Isso é tratado por ordem de chegada. + +Nem a contenção nem as alterações na cota afetarão os recursos já criados. + +## Ativando a cota de recursos + +O suporte à cota de recursos é ativado por padrão para muitas distribuições do Kubernetes. Isto é +ativado quando a flag {{< glossary_tooltip text="API server" term_id="kube-apiserver" >}} `--enable-admission-plugins=` tem `ResourceQuota` como +um de seus argumentos. + +Uma cota de recurso é aplicada em um _namespace_ específico quando há um `ResourceQuota` nesse _namespace_. + +## Cota de recursos computacionais + +Você pode limitar a soma total de [recursos computacionais](/docs/concepts/configuration/manage-resources-containers/) que pode ser solicitado em um determinado _namespace_. + +Os seguintes tipos de recursos são suportados: + +| Nome do Recurso | Descrição | +| --------------------- | ----------------------------------------------------------- | +| `limits.cpu` | Em todos os pods em um estado não terminal, a soma dos limites de CPU não pode exceder esse valor. | +| `limits.memory` | Em todos os pods em um estado não terminal, a soma dos limites de memória não pode exceder esse valor.| +| `requests.cpu` | Em todos os pods em um estado não terminal, a soma das solicitações da CPU não pode exceder esse valor. | +| `requests.memory` | Em todos os pods em um estado não terminal, a soma das solicitações de memória não pode exceder esse valor. | +| `hugepages-` | Em todos os pods em um estado não terminal, o número de solicitações de grandes páginas do tamanho especificado não pode exceder esse valor. | +| `cpu` | O mesmo que `requests.cpu` | +| `memory` | O mesmo que `requests.memory` | + +### Cota de recursos para recursos estendidos + +Além dos recursos mencionados acima, na versão 1.10, suporte a cotas para [recursos estendidos](/docs/concepts/configuration/manage-resources-containers/#extended-resources) foi adicionado. + +Como o `overcommit` não é permitido para recursos estendidos, não faz sentido especificar tanto `requests` e `limits` para o mesmo recurso estendido em uma cota. Portanto, para recursos estendidos, apenas itens de cota com prefixo `requests.` é permitido por enquanto. + +Tome o recurso GPU como exemplo, se o nome do recurso for `nvidia.com/gpu` e você quiser limitar o número total de GPUs solicitadas em um _namespace_ para 4, você pode definir uma cota da seguinte maneira: + +* `requests.nvidia.com/gpu: 4` + +Veja [como visualizar e definir cotas](#viewing-and-setting-quotas) para mais informações. + + +## Cota de recursos de armazenamento + +Você pode limitar a soma total de [recursos de armazenamento](/docs/concepts/storage/persistent-volumes/) que podem ser solicitados em um determinado _namespace_. + +Além disso, você pode limitar o consumo de recursos de armazenamento com base na classe de armazenamento associada. + +| Nome do recurso | Descrição | +| --------------------- | ----------------------------------------------------------- | +| `requests.storage` | Em todas as solicitações de volume persistentes, a soma das solicitações de armazenamento não pode exceder esse valor.| +| `persistentvolumeclaims` | O número total de [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) que podem existir no namespace. | +| `.storageclass.storage.k8s.io/requests.storage` | Em todas as solicitações de volume persistentes associadas ao ``, a soma das solicitações de armazenamento não pode exceder esse valor. | +| `.storageclass.storage.k8s.io/persistentvolumeclaims` | Em todas as declarações de volume persistentes associadas ao storage-class-name, o número total de [declarações de volume persistente](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) que podem existir no namespace. | + +Por exemplo, se um operador deseja cotar armazenamento com classe de armazenamento `gold` separada da classe de armazenamento `bronze`, o operador pode definir uma cota da seguinte forma: + +* `gold.storageclass.storage.k8s.io/requests.storage: 500Gi` +* `bronze.storageclass.storage.k8s.io/requests.storage: 100Gi` + +Na versão 1.8, o suporte de cota para armazenamento temporário local foi adicionado como um recurso alfa: + +| Nome do Recurso | Descrição | +| ------------------------------- |----------------------------------------------------------- | +| `requests.ephemeral-storage` | Em todos os pods no _namespace_, a soma das solicitações de armazenamento local efêmero não pode exceder esse valor.| +| `limits.ephemeral-storage` | Em todos os pods no _namespace_, a soma dos limites de armazenamento temporário local não pode exceder esse valor. | +| `ephemeral-storage` | O mesmo que `requests.ephemeral-storage`. | + +{{< note >}} +Ao usar um tempo de execução do contêiner CRI, os logs do contêiner serão contabilizados na cota de armazenamento efêmero. Isso pode resultar no despejo inesperado de pods que esgotaram suas cotas de armazenamento. Consulte [Arquitetura de registro](/docs/concepts/cluster-administration/logging/) para mais detalhes. +{{< /note >}} + +## Cota de contagem de objetos + +Você pode definir cotas para o número total de determinados recursos de todos os padrões, tipos de recursos com _namespace_ usando a seguinte sintaxe: + +* `count/.` para recursos de grupos não principais +* `count/` para recursos do grupo principal + +Exemplo de conjunto de recursos que os usuários podem querer colocar na cota de contagem de objetos: + +* `count/persistentvolumeclaims` +* `count/services` +* `count/secrets` +* `count/configmaps` +* `count/replicationcontrollers` +* `count/deployments.apps` +* `count/replicasets.apps` +* `count/statefulsets.apps` +* `count/jobs.batch` +* `count/cronjobs.batch` + +A mesma sintaxe pode ser usada para recursos personalizados. Por exemplo, para criar uma cota em um recurso personalizado `widgets` no grupo de API `example.com`, use `count/widgets.example.com`. + +Ao usar a cota de recurso `count/*`, um objeto é cobrado na cota se existir no armazenamento do servidor. Esses tipos de cotas são úteis para proteger contra o esgotamento dos recursos de armazenamento. Por exemplo, você pode desejar limitar o número de segredos em um servidor devido ao seu grande tamanho. Muitos segredos em um cluster podem +na verdade, impedir que servidores e controladores sejam iniciados. Você pode definir uma cota para projetos para proteger contra um `CronJob` mal configurado. `CronJobs` que criam muitos `Jobs` em um _namespace_ podem levar a uma negação de serviço. + +Também é possível fazer uma cota de contagem de objetos genéricos em um conjunto limitado de recursos. +Os seguintes tipos são suportados: + +| Nome do Recurso | Descrição | +| ------------------------------- | ------------------------------------------------- | +| `configmaps` | O número total de `ConfigMaps` que podem existir no namespace. | +| `persistentvolumeclaims` | O número total de [PersistentVolumeClaims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) que podem existir no namespace. | +| `pods` | O número total de pods em um estado não terminal que pode existir no namespace. Um pod está em um estado terminal se `.status.phase in (Failed, Succeeded)` for verdadeiro. | +| `replicationcontrollers` | O número total de `ReplicationControllers` que podem existir no _namespace_. | +| `resourcequotas` | O número total de `ResourceQuotas` que podem existir no _namespace_. | +| `services` | O número total de Serviços que podem existir no _namespace_. | +| `services.loadbalancers` | O número total de serviços do tipo `LoadBalancer` que podem existir no _namespace_. | +| `services.nodeports` | O número total de serviços do tipo `NodePort` que podem existir no _namespace_. | +| `secrets` | O número total de segredos que podem existir no _namespace_. | + +Por exemplo, a cota de `pods` conta e impõe um número máximo de `pods` criados em um único _namespace_ que não é terminal. Você pode querer definir uma cota `pods`em um _namespace_ para evitar o caso em que um usuário cria muitos `pods` pequenos e esgota o fornecimento de IPs de pod do cluster. + +## Escopos de cota + +Cada cota pode ter um conjunto associado de `scopes`. Uma cota só medirá o uso de um recurso se corresponder +a interseção de escopos enumerados. + +Quando um escopo é adicionado à cota, ele limita o número de recursos aos quais ele dá suporte a aqueles que pertencem ao escopo. Os recursos especificados na cota fora do conjunto permitido resultam em um erro de validação. + +| Escopo | Descrição | +| ----- | ----------- | +| `Terminating` | Pods correspondentes onde `.spec.activeDeadlineSeconds >= 0` | +| `NotTerminating` | Pods correspondentes onde `.spec.activeDeadlineSeconds is nil` | +| `BestEffort` | Pods correspondentes que tenham a qualidade de serviço de melhor esforço. | +| `NotBestEffort` | Pods correspondentes que não têm qualidade de serviço de melhor esforço. | +| `PriorityClass` | Corresponde aos pods que fazem referência à [classe de prioridade](/docs/concepts/scheduling-eviction/pod-priority-preemption) especificada. | +| `CrossNamespacePodAffinity` | Corresponde a pods que tenham [termos de (anti)afinidade](/docs/concepts/scheduling-eviction/assign-pod-node) de _namespace_ cruzado. | + +O escopo `BestEffort` restringe uma cota ao rastreamento do seguinte recurso: + +* `pods` + +Os escopos `Termination`, `NotTerminate`, `NotBestEffort` e `PriorityClass`restringem uma cota para rastrear os seguintes recursos: + +* `pods` +* `cpu` +* `memory` +* `requests.cpu` +* `requests.memory` +* `limits.cpu` +* `limits.memory` + +Observe que você não pode especificar os escopos `Terminate` e o `NotTerminate`na mesma cota, e você também não pode especificar o `BestEffort` e`NotBestEffort` na mesma cota. + +O `scopeSelector` suporta os seguintes valores no campo `operator`: + +* `In` +* `NotIn` +* `Exists` +* `DoesNotExist` + +Ao usar um dos seguintes valores como o `scopeName` ao definir o`scopeSelector`, o `operator` deve ser `Exists`. + +* `Terminating` +* `NotTerminating` +* `BestEffort` +* `NotBestEffort` + +Se o `operator` for `In` ou `NotIn`, o campo `values` deve ter pelo menos um valor. Por exemplo: + +```yaml + scopeSelector: + matchExpressions: + - scopeName: PriorityClass + operator: In + values: + - middle +``` + +Se o `operator` for `Exists` ou `DoesNotExist`, o campo `values` *NÃO* deve ser especificado. + +### Cota de recursos por classe de prioridade + +{{< feature-state for_k8s_version="v1.17" state="stable" >}} + +Os pods podem ser criados em uma [prioridade](/docs/concepts/scheduling-eviction/pod-priority-preemption/#pod-priority) específica. Você pode controlar o consumo de recursos do sistema de um pod com base na prioridade de um pod, usando o `scopeSelector` +campo na especificação de cota. + +Uma cota é correspondida e consumida apenas se `scopeSelector` na especificação de cota selecionar o pod. + +Quando a cota está no escopo da classe de prioridade usando o campo `scopeSelector`, objeto de cota +está restrito a rastrear apenas os seguintes recursos: + +* `pods` +* `cpu` +* `memory` +* `ephemeral-storage` +* `limits.cpu` +* `limits.memory` +* `limits.ephemeral-storage` +* `requests.cpu` +* `requests.memory` +* `requests.ephemeral-storage` + +Este exemplo cria um objeto de cota e o corresponde a pods em prioridades específicas. O exemplo +funciona da seguinte forma: + +- Os pods no cluster têm uma das três classes de prioridade, "baixa", "média", "alta". +- Um objeto de cota é criado para cada prioridade. + +Salve o seguinte YAML em um arquivo `quota.yml`. + +```yaml +apiVersion: v1 +kind: List +items: +- apiVersion: v1 + kind: ResourceQuota + metadata: + name: pods-high + spec: + hard: + cpu: "1000" + memory: 200Gi + pods: "10" + scopeSelector: + matchExpressions: + - operator : In + scopeName: PriorityClass + values: ["high"] +- apiVersion: v1 + kind: ResourceQuota + metadata: + name: pods-medium + spec: + hard: + cpu: "10" + memory: 20Gi + pods: "10" + scopeSelector: + matchExpressions: + - operator : In + scopeName: PriorityClass + values: ["medium"] +- apiVersion: v1 + kind: ResourceQuota + metadata: + name: pods-low + spec: + hard: + cpu: "5" + memory: 10Gi + pods: "10" + scopeSelector: + matchExpressions: + - operator : In + scopeName: PriorityClass + values: ["low"] +``` + +Aplique o YAML usando `kubectl create`. + +```shell +kubectl create -f ./quota.yml +``` + +``` +resourcequota/pods-high created +resourcequota/pods-medium created +resourcequota/pods-low created +``` + +Verifique se a cota `Used` é `0` usando `kubectl describe quota`. + +```shell +kubectl describe quota +``` + +``` +Name: pods-high +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 0 1k +memory 0 200Gi +pods 0 10 + + +Name: pods-low +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 0 5 +memory 0 10Gi +pods 0 10 + + +Name: pods-medium +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 0 10 +memory 0 20Gi +pods 0 10 +``` + +Crie um pod com prioridade "high". Salve o seguinte YAML em um arquivo `high-priority-pod.yml`. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: high-priority +spec: + containers: + - name: high-priority + image: ubuntu + command: ["/bin/sh"] + args: ["-c", "while true; do echo hello; sleep 10;done"] + resources: + requests: + memory: "10Gi" + cpu: "500m" + limits: + memory: "10Gi" + cpu: "500m" + priorityClassName: high +``` + +Applique com `kubectl create`. + +```shell +kubectl create -f ./high-priority-pod.yml +``` + +Verifique se as estatísticas "Used" para a cota de prioridade "high", `pods-high` foram alteradas e se +as outras duas cotas permanecem inalteradas. + +```shell +kubectl describe quota +``` + +``` +Name: pods-high +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 500m 1k +memory 10Gi 200Gi +pods 1 10 + + +Name: pods-low +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 0 5 +memory 0 10Gi +pods 0 10 + + +Name: pods-medium +Namespace: default +Resource Used Hard +-------- ---- ---- +cpu 0 10 +memory 0 20Gi +pods 0 10 +``` + +### Cota de afinidade de pod entre _namespaces_ + +{{< feature-state for_k8s_version="v1.22" state="beta" >}} + +Os operadores podem usar o escopo de cota `CrossNamespacePodAffinity` para limitar quais _namespaces_ têm permissão para ter pods com termos de afinidade que cruzam _namespaces_. Especificamente, ele controla quais pods são permitidos para definir os campos `namespaces` ou `namespaceSelector` em termos de afinidade de pod. + +Impedir que os usuários usem termos de afinidade entre _namespaces_ pode ser desejável, pois um pod +com restrições antiafinidade pode bloquear pods de todos os outros _namespaces_ de ser agendado em um domínio de falha. + +O uso desses operadores de escopo pode impedir certos _namespaces_ (`foo-ns` no exemplo abaixo) de ter pods que usam afinidade de pod entre _namespaces_ criando um objeto de cota de recurso nesse _namespace_ com escopo `CrossNamespaceAffinity` e limite rígido de 0: + +```yaml +apiVersion: v1 +kind: ResourceQuota +metadata: + name: disable-cross-namespace-affinity + namespace: foo-ns +spec: + hard: + pods: "0" + scopeSelector: + matchExpressions: + - scopeName: CrossNamespaceAffinity +``` + +Se os operadores quiserem proibir o uso de `namespaces` e `namespaceSelector` por padrão, e +permitir apenas para _namespaces_ específicos, eles podem configurar `CrossNamespaceAffinity`como um recurso limitado definindo o sinalizador kube-apiserver --admission-control-config-file +para o caminho do seguinte arquivo de configuração: + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: +- name: "ResourceQuota" + configuration: + apiVersion: apiserver.config.k8s.io/v1 + kind: ResourceQuotaConfiguration + limitedResources: + - resource: pods + matchScopes: + - scopeName: CrossNamespaceAffinity +``` + +Com a configuração acima, os pods podem usar `namespaces` e `namespaceSelector` apenas na afinidade do pod se o _namespace_ em que foram criados tiver um objeto de cota de recurso com escopo `CrossNamespaceAffinity` e um limite rígido maior ou igual ao número de pods usando esses campos. + +Esse recurso é beta e ativado por padrão. Você pode desativá-lo usando o [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) `PodAffinityNamespaceSelector` no kube-apiserver e no kube-scheduler. + +## Solicitações comparadas aos limites {#requests-vs-limits} + +Ao alocar recursos computacionais, cada contêiner pode especificar uma solicitação e um valor limite para CPU ou memória. A cota pode ser configurada para cotar qualquer valor. + +Se a cota tiver um valor especificado para `requests.cpu` ou `requests.memory`, ela exigirá que cada container faça uma solicitação explícita para esses recursos. Se a cota tiver um valor especificado para `limits.cpu` ou `limits.memory`, em seguida exige que cada contêiner de entrada especifique um limite explícito para esses recursos. + +## Como visualizar e definir cotas + +O Kubectl é compatível com a criação, atualização e visualização de cotas: + +```shell +kubectl create namespace myspace +``` + +```shell +cat < compute-resources.yaml +apiVersion: v1 +kind: ResourceQuota +metadata: + name: compute-resources +spec: + hard: + requests.cpu: "1" + requests.memory: 1Gi + limits.cpu: "2" + limits.memory: 2Gi + requests.nvidia.com/gpu: 4 +EOF +``` + +```shell +kubectl create -f ./compute-resources.yaml --namespace=myspace +``` + +```shell +cat < object-counts.yaml +apiVersion: v1 +kind: ResourceQuota +metadata: + name: object-counts +spec: + hard: + configmaps: "10" + persistentvolumeclaims: "4" + pods: "4" + replicationcontrollers: "20" + secrets: "10" + services: "10" + services.loadbalancers: "2" +EOF +``` + +```shell +kubectl create -f ./object-counts.yaml --namespace=myspace +``` + +```shell +kubectl get quota --namespace=myspace +``` + +```none +NAME AGE +compute-resources 30s +object-counts 32s +``` + +```shell +kubectl describe quota compute-resources --namespace=myspace +``` + +```none +Name: compute-resources +Namespace: myspace +Resource Used Hard +-------- ---- ---- +limits.cpu 0 2 +limits.memory 0 2Gi +requests.cpu 0 1 +requests.memory 0 1Gi +requests.nvidia.com/gpu 0 4 +``` + +```shell +kubectl describe quota object-counts --namespace=myspace +``` + +```none +Name: object-counts +Namespace: myspace +Resource Used Hard +-------- ---- ---- +configmaps 0 10 +persistentvolumeclaims 0 4 +pods 0 4 +replicationcontrollers 0 20 +secrets 1 10 +services 0 10 +services.loadbalancers 0 2 +``` + +Kubectl also supports object count quota for all standard namespaced resources +using the syntax `count/.`: + +```shell +kubectl create namespace myspace +``` + +```shell +kubectl create quota test --hard=count/deployments.apps=2,count/replicasets.apps=4,count/pods=3,count/secrets=4 --namespace=myspace +``` + +```shell +kubectl create deployment nginx --image=nginx --namespace=myspace --replicas=2 +``` + +```shell +kubectl describe quota --namespace=myspace +``` + +``` +Name: test +Namespace: myspace +Resource Used Hard +-------- ---- ---- +count/deployments.apps 1 2 +count/pods 2 3 +count/replicasets.apps 1 4 +count/secrets 1 4 +``` + +## Capacidade e cota de Cluster + +`ResourceQuotas` são independentes da capacidade do cluster. Eles estão expresso em unidades absolutas. Portanto, se você adicionar nós ao cluster, isso *não* +dá automaticamente a cada _namespace_ a capacidade de consumir mais recursos. + +Às vezes, políticas mais complexas podem ser necessárias, como: + +- Divida proporcionalmente os recursos totais do cluster entre várias equipes. +- Permita que cada locatário aumente o uso de recursos conforme necessário, mas tenha um generoso limite para evitar o esgotamento acidental de recursos. +- Detecte a demanda de um _namespace_, adicione nós e aumente a cota. + +Tais políticas podem ser implementadas usando `ResourceQuotas` como blocos de construção, por +escrevendo um "controlador" que observa o uso da cota e ajusta os limites rígidos da cota de cada _namespace_ de acordo com outros sinais. + +Observe que a cota de recursos divide os recursos agregados do cluster, mas não cria restrições em torno dos nós: pods de vários _namespaces_ podem ser executados no mesmo nó. + +## Limite de consumo de classe de prioridade por padrão + +Pode ser desejado que os pods com uma prioridade particular, por exemplo. "cluster-services", +deve ser permitido em um _namespace_, se, e somente se, existir um objeto de cota correspondente. + +Com este mecanismo, os operadores podem restringir o uso de certas classes de prioridade para um número limitado de _namespaces_ , e nem todos poderão consumir essas classes de prioridade por padrão. + +Para impor isso, a flag `kube-apiserver` `--admission-control-config-file` deve ser +usada para passar o caminho para o seguinte arquivo de configuração: + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: +- name: "ResourceQuota" + configuration: + apiVersion: apiserver.config.k8s.io/v1 + kind: ResourceQuotaConfiguration + limitedResources: + - resource: pods + matchScopes: + - scopeName: PriorityClass + operator: In + values: ["cluster-services"] +``` + +Em seguida, crie um objeto de cota de recurso no _namespace_ `kube-system`: + +{{< codenew file="policy/priority-class-resourcequota.yaml" >}} + +```shell +kubectl apply -f https://k8s.io/examples/policy/priority-class-resourcequota.yaml -n kube-system +``` + +```none +resourcequota/pods-cluster-services created +``` + +Nesse caso, a criação de um pod será permitida se: + +1. O `priorityClassName` do pod não foi especificado. +1. O `priorityClassName` do pod é especificado com um valor diferente de `cluster-services`. +1. O `priorityClassName` do pod está definido como `cluster-services`, ele deve ser criado no namespace `kube-system` e passou na verificação de cota de recursos. + +Uma solicitação de criação de pod é rejeitada caso seu `priorityClassName` estiver definido como `cluster-services` e deve ser criado em um _namespace_ diferente de `kube-system`. + +## {{% heading "whatsnext" %}} + +- Veja o [documento de design de cota de recursos](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_resource_quota.md) para mais informações. +- Veja um [exemplo detalhado de como usar a cota de recursos](/docs/tasks/administer-cluster/quota-api-object/). +- Leia o [documento de design de suporte de cota para prioridade de classe](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/scheduling/pod-priority-resourcequota.md). +- Veja [recursos limitados](https://github.com/kubernetes/kubernetes/pull/36765) diff --git a/content/pt-br/examples/policy/priority-class-resourcequota.yaml b/content/pt-br/examples/policy/priority-class-resourcequota.yaml new file mode 100644 index 0000000000..7350d00c8f --- /dev/null +++ b/content/pt-br/examples/policy/priority-class-resourcequota.yaml @@ -0,0 +1,10 @@ +apiVersion: v1 +kind: ResourceQuota +metadata: + name: pods-cluster-services +spec: + scopeSelector: + matchExpressions: + - operator : In + scopeName: PriorityClass + values: ["cluster-services"] \ No newline at end of file diff --git a/content/ru/docs/concepts/architecture/controller.md b/content/ru/docs/concepts/architecture/controller.md index 4f28a51836..3df6517fa4 100644 --- a/content/ru/docs/concepts/architecture/controller.md +++ b/content/ru/docs/concepts/architecture/controller.md @@ -11,7 +11,7 @@ weight: 30 Вот один из примеров контура управления: термостат в помещении. Когда вы устанавливаете температуру, это говорит термостату о вашем *желаемом состоянии*. Фактическая температура в помещении - это -*текущее состояние*. Термостат действует так, чтобы приблизить текущее состояние к елаемому состоянию, путем включения или выключения оборудования. +*текущее состояние*. Термостат действует так, чтобы приблизить текущее состояние к желаемому состоянию, путем включения или выключения оборудования. {{< glossary_definition term_id="controller" length="short">}} diff --git a/content/ru/docs/concepts/cluster-administration/addons.md b/content/ru/docs/concepts/cluster-administration/addons.md index 7d6777621e..e86d485949 100644 --- a/content/ru/docs/concepts/cluster-administration/addons.md +++ b/content/ru/docs/concepts/cluster-administration/addons.md @@ -21,7 +21,6 @@ content_type: concept * [Canal](https://github.com/tigera/canal/tree/master/k8s-install) объединяет Flannel и Calico, обеспечивая сеть и сетевую политик. * [Cilium](https://github.com/cilium/cilium) - это плагин сети L3 и сетевой политики, который может прозрачно применять политики HTTP/API/L7. Поддерживаются как режим маршрутизации, так и режим наложения/инкапсуляции, и он может работать поверх других подключаемых модулей CNI. * [CNI-Genie](https://github.com/Huawei-PaaS/CNI-Genie) позволяет Kubernetes легко подключаться к выбору плагинов CNI, таких как Calico, Canal, Flannel, Romana или Weave. -* [Contiv](https://contiv.github.io) предоставляет настраиваемую сеть (собственный L3 с использованием BGP, слоя с использованием vxlan, классический L2 и Cisco-SDN/ACI) для различных вариантов использования и обширную структуру политик. Проект Contiv имеет полностью [открытый исходный код](https://github.com/contiv). [Установка](https://github.com/contiv/install) обеспечивает варианты на основе как kubeadm так и без kubeadm. * [Contrail](https://www.juniper.net/us/en/products-services/sdn/contrail/contrail-networking/), основан на [Tungsten Fabric](https://tungsten.io), представляет собой платформу для виртуализации мультиоблачных сетей с открытым исходным кодом и управления политиками. Contrail и Tungsten Fabric are интегрированы с системами оркестровки, такими как Kubernetes, OpenShift, OpenStack и Mesos, и обеспечивают режимы изоляции для виртуальных машин, контейнеров/pod-ов и рабочих нагрузок без операционной системы. * [Flannel](https://github.com/flannel-io/flannel#deploying-flannel-manually) - это поставщик оверлейной сети, который можно использовать с Kubernetes. * [Knitter](https://github.com/ZTE/Knitter/) - это плагин для поддержки нескольких сетевых интерфейсов Kubernetes pod-ов. diff --git a/content/ru/docs/concepts/overview/what-is-kubernetes.md b/content/ru/docs/concepts/overview/what-is-kubernetes.md index 51abd33f44..1f9f463269 100644 --- a/content/ru/docs/concepts/overview/what-is-kubernetes.md +++ b/content/ru/docs/concepts/overview/what-is-kubernetes.md @@ -17,7 +17,7 @@ card: Kubernetes — это портативная расширяемая платформа с открытым исходным кодом для управления контейнеризованными рабочими нагрузками и сервисами, которая облегчает как декларативную настройку, так и автоматизацию. У платформы есть большая, быстро растущая экосистема. Сервисы, поддержка и инструменты Kubernetes широко доступны. -Название Kubernetes происходит от греческого, что означает рулевой или штурман. Google открыл исходный код Kubernetes в 2014 году. Kubernetes основывается на [десятилетнем опыте работе Google с масштабными рабочими нагрузками](https://research.google/pubs/pub43438), в сочетании с лучшими в своем классе идеями и практиками сообщества. +Название Kubernetes происходит от греческого, что означает рулевой или штурман. Google открыл исходный код Kubernetes в 2014 году. Kubernetes основывается на [десятилетнем опыте работы Google с масштабными рабочими нагрузками](https://research.google/pubs/pub43438), в сочетании с лучшими в своем классе идеями и практиками сообщества. ## История Давайте вернемся назад и посмотрим, почему Kubernetes так полезен. diff --git a/content/vi/docs/concepts/architecture/_index.md b/content/vi/docs/concepts/architecture/_index.md old mode 100755 new mode 100644 diff --git a/content/zh/blog/_posts/2022-02-17-updated-dockershim-faq.md b/content/zh/blog/_posts/2022-02-17-updated-dockershim-faq.md new file mode 100644 index 0000000000..9a1cac8cc2 --- /dev/null +++ b/content/zh/blog/_posts/2022-02-17-updated-dockershim-faq.md @@ -0,0 +1,373 @@ +--- +layout: blog +title: "更新：弃用 Dockershim 的常见问题" +date: 2022-02-17 +slug: dockershim-faq +aliases: [ '/dockershim' ] +--- + + + +**本文是针对2020年末发布的[弃用 Dockershim 的常见问题](/zh/blog/2020/12/02/dockershim-faq/)的博客更新。** + + +本文回顾了自 Kubernetes v1.20 版本[宣布](/zh/blog/2020/12/08/kubernetes-1-20-release-announcement/)弃用 +Dockershim 以来所引发的一些常见问题。关于弃用细节以及这些细节背后的含义，请参考博文 +[别慌: Kubernetes 和 Docker](/zh/blog/2020/12/02/dont-panic-kubernetes-and-docker/)。 + + +你还可以查阅：[检查弃用 Dockershim 对你的影响](/zh/docs/tasks/administer-cluster/migrating-from-dockershim/check-if-dockershim-deprecation-affects-you/)这篇文章， +以确定弃用 dockershim 会对你或你的组织带来多大的影响。 + + +随着 Kubernetes 1.24 版本的发布迫在眉睫，我们一直在努力尝试使其能够平稳升级顺利过渡。 + + +- 我们已经写了一篇博文，详细说明了我们的[承诺和后续操作](/blog/2022/01/07/kubernetes-is-moving-on-from-dockershim/)。 +- 我们我们相信可以无障碍的迁移到其他[容器运行时](/zh/docs/setup/production-environment/container-runtimes/#container-runtimes)。 +- 我们撰写了 [dockershim 迁移指南](/docs/tasks/administer-cluster/migrating-from-dockershim/)供你参考。 +- 我们还创建了一个页面来列出[有关 dockershim 移除和使用 CRI 兼容运行时的文章](/zh/docs/reference/node/topics-on-dockershim-and-cri-compatible-runtimes/)。 + 该列表包括一些已经提到的文档，还涵盖了选定的外部资源（包括供应商指南）。 + + +### 为什么会从 Kubernetes 中移除 dockershim ？ + + +Kubernetes 的早期版本仅适用于特定的容器运行时：Docker Engine。 +后来，Kubernetes 增加了对使用其他容器运行时的支持。[创建](/blog/2016/12/container-runtime-interface-cri-in-kubernetes/) CRI +标准是为了实现编排器（如 Kubernetes）和许多不同的容器运行时之间交互操作。 +Docker Engine 没有实现（CRI）接口，因此 Kubernetes 项目创建了特殊代码来帮助过渡， +并使 dockershim 代码成为 Kubernetes 的一部分。 + + +dockershim 代码一直是一个临时解决方案（因此得名：shim）。 +你可以阅读 [Kubernetes 移除 Dockershim 增强方案](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2221-remove-dockershim) +以了解相关的社区讨论和计划。 +事实上，维护 dockershim 已经成为 Kubernetes 维护者的沉重负担。 + + +此外，在较新的 CRI 运行时中实现了与 dockershim 不兼容的功能，例如 cgroups v2 和用户命名空间。 +取消对 dockershim 的支持将加速这些领域的发展。 + + +### 在 Kubernetes 1.23 版本中还可以使用 Docker Engine 吗？ + + +可以使用，在 1.20 版本中唯一的改动是，如果使用 Docker Engine， +在 [kubelet](/zh/docs/reference/command-line-tools-reference/kubelet/) +启动时会打印一个警告日志。 +你将在 1.23 版本及以前版本看到此警告。dockershim 将在 Kubernetes 1.24 版本中移除 。 + + +### 什么时候移除 dockershim ？ + + +考虑到此变更带来的影响，我们使用了一个加长的废弃时间表。 +dockershim 计划在 Kubernetes v1.24 中进行移除， +参见 [Kubernetes 移除 Dockershim 增强方案](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2221-remove-dockershim)。 +Kubernetes 项目将与供应商和其他生态系统组织密切合作，以确保平稳过渡，并将依据事态的发展评估后续事项。 + + +### 我还可以使用 Docker Engine 作为我的容器运行时吗？ + + +首先，如果你在自己的电脑上使用 Docker 用来做开发或测试容器：它将与之前没有任何变化。 +无论你为 Kubernetes 集群使用什么容器运行时，你都可以在本地使用 Docker。容器使这种交互成为可能。 + + +Mirantis 和 Docker 已[承诺](https://www.mirantis.com/blog/mirantis-to-take-over-support-of-kubernetes-dockershim-2/) +为 Docker Engine 维护一个替代适配器， +并在 dockershim 从 Kubernetes 移除后维护该适配器。 +替代适配器名为 [`cri-dockerd`](https://github.com/Mirantis/cri-dockerd)。 + + +### 我现有的容器镜像还能正常工作吗？ + + +当然可以，`docker build` 创建的镜像适用于任何 CRI 实现。 +所有你的现有镜像将和往常一样工作。 + + +### 私有镜像呢？ + + +当然可以。所有 CRI 运行时均支持在 Kubernetes 中相同的拉取（pull）Secret 配置， +无论是通过 PodSpec 还是 ServiceAccount。 + + +### Docker 和容器是一回事吗？ + + +Docker 普及了 Linux 容器模式，并在开发底层技术方面发挥了重要作用， +但是 Linux 中的容器已经存在了很长时间。容器的生态相比于 Docker 具有更宽广的领域。 +OCI 和 CRI 等标准帮助许多工具在我们的生态系统中发展壮大， +其中一些替代了 Docker 的某些方面，而另一些则增强了现有功能。 + + +### 现在是否有在生产系统中使用其他运行时的例子？ + + +Kubernetes 所有项目在所有版本中出产的工件（Kubernetes 二进制文件）都经过了验证。 + + +此外，[kind](https://kind.sigs.k8s.io/) 项目使用 containerd 已经有一段时间了，并且提高了其用例的稳定性。 +Kind 和 containerd 每天都会被多次使用来验证对 Kubernetes 代码库的任何更改。 +其他相关项目也遵循同样的模式，从而展示了其他容器运行时的稳定性和可用性。 +例如，OpenShift 4.x 从 2019 年 6 月以来，就一直在生产环境中使用 [CRI-O](https://cri-o.io/) 运行时。 + + +至于其他示例和参考资料，你可以查看 containerd 和 CRI-O 的使用者列表， +这两个容器运行时是云原生基金会（[CNCF](https://cncf.io)）下的项目。 + +- [containerd](https://github.com/containerd/containerd/blob/master/ADOPTERS.md) +- [CRI-O](https://github.com/cri-o/cri-o/blob/master/ADOPTERS.md) + + +### 人们总在谈论 OCI，它是什么？ + + +OCI 是 [Open Container Initiative](https://opencontainers.org/about/overview/) 的缩写， +它标准化了容器工具和底层实现之间的大量接口。 +它们维护了打包容器镜像（OCI image）和运行时（OCI runtime）的标准规范。 +它们还以 [runc](https://github.com/opencontainers/runc) 的形式维护了一个 runtime-spec 的真实实现， +这也是 [containerd](https://containerd.io/) 和 [CRI-O](https://cri-o.io/) 依赖的默认运行时。 +CRI 建立在这些底层规范之上，为管理容器提供端到端的标准。 + + +### 我应该用哪个 CRI 实现？ + + +这是一个复杂的问题，依赖于许多因素。 +如果你正在使用 Docker，迁移到 containerd 应该是一个相对容易地转换，并将获得更好的性能和更少的开销。 +然而，我们鼓励你探索 [CNCF landscape](https://landscape.cncf.io/card-mode?category=container-runtime&grouping=category) +提供的所有选项，做出更适合你的选择。 + + +### 当切换 CRI 实现时，应该注意什么？ + + +虽然 Docker 和大多数 CRI（包括 containerd）之间的底层容器化代码是相同的， +但其周边部分却存在差异。迁移时要考虑如下常见事项： + + +- 日志配置 +- 运行时的资源限制 +- 调用 docker 或通过其控制套接字使用 docker 的节点配置脚本 +- 需要访问 docker 命令或控制套接字的 kubectl 插件 +- 需要直接访问 Docker Engine 的 Kubernetes 工具（例如：已弃用的 'kube-imagepuller' 工具） +- `registry-mirrors` 和不安全注册表等功能的配置 +- 保障 Docker Engine 可用、且运行在 Kubernetes 之外的脚本或守护进程（例如：监视或安全代理） +- GPU 或特殊硬件，以及它们如何与你的运行时和 Kubernetes 集成 + + +如果你只是用了 Kubernetes 资源请求/限制或基于文件的日志收集 DaemonSet，它们将继续稳定工作， +但是如果你用了自定义了 dockerd 配置，则可能需要为新的容器运行时做一些适配工作。 + + +另外还有一个需要关注的点，那就是当创建镜像时，系统维护或嵌入容器方面的任务将无法工作。 +对于前者，可以用 [`crictl`](https://github.com/kubernetes-sigs/cri-tools) 工具作为临时替代方案 +(参阅[从 docker cli 到 crictl 的映射](/zh/docs/tasks/debug-application-cluster/crictl/#mapping-from-docker-cli-to-crictl))。 +对于后者，可以用新的容器创建选项，例如 +[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)， +他们都不需要 Docker。 + + +对于 containerd，你可查阅有关它的[文档](https://github.com/containerd/cri/blob/master/docs/registry.md)， +获取迁移时可用的配置选项。 + + +有关如何在 Kubernetes 中使用 containerd 和 CRI-O 的说明， +请参阅 [Kubernetes 相关文档](/docs/setup/production-environment/container-runtimes/) + + +### 我还有其他问题怎么办？ + + +如果你使用了供应商支持的 Kubernetes 发行版，你可以咨询供应商他们产品的升级计划。 +对于最终用户的问题，请把问题发到我们的最终用户社区的论坛：https://discuss.kubernetes.io/。 + + +你也可以看看这篇优秀的博客文章：[等等，Docker 被 Kubernetes 弃用了?](https://dev.to/inductor/wait-docker-is-deprecated-in-kubernetes-now-what-do-i-do-e4m) +对这些变化进行更深入的技术讨论。 + + +### 我可以加入吗？ + + +当然，只要你愿意，随时随地欢迎。🤗🤗🤗 \ No newline at end of file diff --git a/content/zh/docs/concepts/cluster-administration/addons.md b/content/zh/docs/concepts/cluster-administration/addons.md index c579cacc17..15b9efe804 100644 --- a/content/zh/docs/concepts/cluster-administration/addons.md +++ b/content/zh/docs/concepts/cluster-administration/addons.md @@ -31,7 +31,6 @@ Add-ons 扩展了 Kubernetes 的功能。 * [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. * [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](http://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](http://github.com/contiv). The [installer](http://github.com/contiv/install) provides both kubeadm and non-kubeadm based installation options. * [Contrail](http://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 network solution supporting multiple networking in Kubernetes. @@ -55,9 +54,6 @@ Add-ons 扩展了 Kubernetes 的功能。 同时支持路由（routing）和覆盖/封装（overlay/encapsulation）模式。 * [CNI-Genie](https://github.com/Huawei-PaaS/CNI-Genie) 使 Kubernetes 无缝连接到一种 CNI 插件， 例如：Flannel、Calico、Canal、Romana 或者 Weave。 -* [Contiv](https://contiv.github.io) 为多种用例提供可配置网络（使用 BGP 的原生 L3，使用 vxlan 的覆盖网络， - 经典 L2 和 Cisco-SDN/ACI）和丰富的策略框架。Contiv 项目完全[开源](https://github.com/contiv)。 - [安装工具](https://github.com/contiv/install)同时提供基于和不基于 kubeadm 的安装选项。 * 基于 [Tungsten Fabric](https://tungsten.io) 的 [Contrail](https://www.juniper.net/us/en/products-services/sdn/contrail/contrail-networking/) 是一个开源的多云网络虚拟化和策略管理平台，Contrail 和 Tungsten Fabric 与业务流程系统 diff --git a/content/zh/docs/concepts/cluster-administration/manage-deployment.md b/content/zh/docs/concepts/cluster-administration/manage-deployment.md index 2ff9274d62..30be88f7cc 100644 --- a/content/zh/docs/concepts/cluster-administration/manage-deployment.md +++ b/content/zh/docs/concepts/cluster-administration/manage-deployment.md @@ -236,10 +236,10 @@ persistentvolumeclaim/my-pvc created ``` +If you're interested in learning more about `kubectl`, go ahead and read [Command line tool (kubectl)](/docs/reference/kubectl/). +--> 如果你有兴趣进一步学习关于 `kubectl` 的内容，请阅读 -[kubectl 概述](/zh/docs/reference/kubectl/overview/)。 +[命令行工具（kubectl）](/zh/docs/reference/kubectl/)。 - 当你定义 {{< glossary_tooltip text="Pod" term_id="pod" >}} 时可以选择性地为每个 {{< glossary_tooltip text="容器" term_id="container" >}}设定所需要的资源数量。 最常见的可设定资源是 CPU 和内存（RAM）大小；此外还有其他类型的资源。 -当你为 Pod 中的 Container 指定了资源 __请求__ 时，调度器就利用该信息决定将 Pod 调度到哪个节点上。 +当你为 Pod 中的 Container 指定了资源 __请求__ 时， +{{< glossary_tooltip text="kube-scheduler" term_id="kube-scheduler" >}} +就利用该信息决定将 Pod 调度到哪个节点上。 当你还为 Container 指定了资源 __约束__ 时，kubelet 就可以确保运行的容器不会使用超出所设约束的资源。 kubelet 还会为容器预留所 __请求__ 数量的系统资源，供其使用。 @@ -65,7 +69,7 @@ more RAM. 运行，那么该容器就可以尝试使用更多的内存。 -如果某 Container 设置了自己的内存限制但未设置内存请求，Kubernetes +如果某容器设置了自己的内存限制但未设置内存请求，Kubernetes 自动为其设置与内存限制相匹配的请求值。类似的，如果某 Container 设置了 -CPU 限制值但未设置 CPU 请求值，则 Kubernetes 自动为其设置 CPU 请求 -并使之与 CPU 限制值匹配。 +CPU 限制值但未设置 CPU 请求值，则 Kubernetes 自动为其设置 CPU +请求并使之与 CPU 限制值匹配。 {{< /note >}} ## 资源类型 {#resource-types} -*CPU* 和*内存*都是*资源类型*。每种资源类型具有其基本单位。 +*CPU* 和 *内存* 都是 *资源类型*。每种资源类型具有其基本单位。 CPU 表达的是计算处理能力，其单位是 [Kubernetes CPUs](#meaning-of-cpu)。 内存的单位是字节。 -如果你使用的是 Kubernetes v1.14 或更高版本，则可以指定巨页（Huge Page）资源。 +对于 Linux 负载，则可以指定巨页（Huge Page）资源。 巨页是 Linux 特有的功能，节点内核在其中分配的内存块比默认页大小大得多。 例如，在默认页面大小为 4KiB 的系统上，你可以指定约束 `hugepages-2Mi: 80Mi`。 @@ -141,16 +145,21 @@ consumed. They are distinct from [Services](/docs/concepts/services-networking/service/) are objects that can be read and modified through the Kubernetes API server. --> -CPU 和内存统称为*计算资源*，或简称为*资源*。 +CPU 和内存统称为“计算资源”，或简称为“资源”。 计算资源的数量是可测量的，可以被请求、被分配、被消耗。 它们与 [API 资源](/zh/docs/concepts/overview/kubernetes-api/) 不同。 API 资源（如 Pod 和 [Service](/zh/docs/concepts/services-networking/service/)）是可通过 Kubernetes API 服务器读取和修改的对象。 +## Pod 和 容器的资源请求和约束 + +针对每个容器，你都可以指定其资源约束和请求，包括如下选项： * `spec.containers[].resources.limits.cpu` * `spec.containers[].resources.limits.memory` @@ -159,93 +168,114 @@ Each Container of a Pod can specify one or more of the following: * `spec.containers[].resources.requests.memory` * `spec.containers[].resources.requests.hugepages-` -Although requests and limits can only be specified on individual Containers, it -is convenient to talk about Pod resource requests and limits. A -*Pod resource request/limit* for a particular resource type is the sum of the -resource requests/limits of that type for each Container in the Pod. + - -## Pod 和 容器的资源请求和约束 - -Pod 中的每个容器都可以指定以下的一个或者多个值： - -- `spec.containers[].resources.limits.cpu` -- `spec.containers[].resources.limits.memory` -- `spec.containers[].resources.limits.hugepages-` -- `spec.containers[].resources.requests.cpu` -- `spec.containers[].resources.requests.memory` -- `spec.containers[].resources.requests.hugepages-` - -尽管请求和限制值只能在单个容器上指定，我们仍可方便地计算出 Pod 的资源请求和约束。 -Pod 对特定资源类型的请求/约束值是 Pod 中各容器对该类型资源的请求/约束值的总和。 +尽管你只能逐个容器地指定请求和限制值，考虑 Pod 的总体资源请求和约束也是有用的。 +对特定资源而言，Pod 的资源请求/约束值是 Pod 中各容器对该类型资源的请求/约束值的总和。 ## Kubernetes 中的资源单位 {#resource-units-in-kubernetes} -### CPU 的含义 {#meaning-of-cpu} +### CPU 资源单位 {#meaning-of-cpu} -CPU 资源的约束和请求以 *CPU* 为单位。 - -Kubernetes 中的一个 CPU 等于云平台上的 **1 个 vCPU/核**和裸机 Intel -处理器上的 **1 个超线程**。 - -你也可以表达带小数 CPU 的请求。`spec.containers[].resources.requests.cpu` 为 0.5 -的 Container 肯定能够获得请求 1 CPU 的容器的一半 CPU 资源。表达式 `0.1` 等价于表达式 `100m`， -可以看作 “100 millicpu”。有些人说成是“一百毫 cpu”，其实说的是同样的事情。 -具有小数点（如 `0.1`）的请求由 API 转换为 `100m`；最大精度是 `1m`。 -因此，或许你应该优先考虑使用 `100m` 的形式。 - -CPU 总是按绝对数量来请求的，不可以使用相对数量； -0.1 的 CPU 在单核、双核、48 核的机器上的意义是一样的。 +CPU 资源的约束和请求以 “cpu” 为单位。 +在 Kubernetes 中，一个 CPU 等于**1 个物理 CPU 核** 或者 **一个虚拟核**， +取决于节点是一台物理主机还是运行在某物理主机上的虚拟机。 +你也可以表达带小数 CPU 的请求。 +当你定义一个容器，将其 `spec.containers[].resources.requests.cpu` 设置为 0.5 时， +你所请求的 CPU 是你请求 `1.0` CPU 时的一半。 +对于 CPU 资源单位，[数量](/docs/reference/kubernetes-api/common-definitions/quantity/) +表达式 `0.1` 等价于表达式 `100m`，可以看作 “100 millicpu”。 +有些人说成是“一百毫核”，其实说的是同样的事情。 + + +CPU 资源总是设置为资源的绝对数量而非相对数量值。 +例如，无论容器运行在单核、双核或者 48-核的机器上，`500m` CPU 表示的是大约相同的计算能力。 + +{{< note >}} + +Kubernetes 不允许设置精度小于 `1m` 的 CPU 资源。 +因此，当 CPU 单位小于 `1` 或 `1000m` 时，使用毫核的形式是有用的； +例如 `5m` 而不是 `0.005`。 +{{< /note >}} + + -## 内存的含义 {#meaning-of-memory} +## 内存资源单位 {#meaning-of-memory} -内存的约束和请求以字节为单位。你可以使用以下后缀之一以一般整数或定点数字形式来表示内存： -E、P、T、G、M、k。你也可以使用对应的 2 的幂数：Ei、Pi、Ti、Gi、Mi、Ki。 +`memory` 的约束和请求以字节为单位。 +你可以使用普通的证书，或者带有以下 +[数量](/docs/reference/kubernetes-api/common-definitions/quantity/)后缀 +的定点数字来表示内存：E、P、T、G、M、k。 +你也可以使用对应的 2 的幂数：Ei、Pi、Ti、Gi、Mi、Ki。 例如，以下表达式所代表的是大致相同的值： ``` -128974848、129e6、129M、123Mi +128974848、129e6、129M、128974848000m、123Mi ``` -下面是个例子。 +请注意后缀的大小写。如果你请求 `400m` 内存，实际上请求的是 0.4 字节。 +如果有人这样设定资源请求或限制，可能他的实际想法是申请 400 兆字节（`400Mi`） +或者 400M 字节。 -以下 Pod 有两个 Container。每个 Container 的请求为 0.25 cpu 和 64MiB（226 字节）内存， -每个容器的资源约束为 0.5 cpu 和 128MiB 内存。 -你可以认为该 Pod 的资源请求为 0.5 cpu 和 128 MiB 内存，资源限制为 1 cpu 和 256MiB 内存。 + +## 容器资源示例 {#example-1} + +以下 Pod 有两个容器。每个容器的请求为 0.25 CPU 和 64MiB（226 字节）内存， +每个容器的资源约束为 0.5 CPU 和 128MiB 内存。 +你可以认为该 Pod 的资源请求为 0.5 CPU 和 128 MiB 内存，资源限制为 1 CPU 和 256MiB 内存。 ```yaml apiVersion: v1 @@ -256,9 +286,6 @@ spec: containers: - name: app image: images.my-company.example/app:v4 - env: - - name: MYSQL_ROOT_PASSWORD - value: "password" resources: requests: memory: "64Mi" @@ -284,7 +311,8 @@ When you create a Pod, the Kubernetes scheduler selects a node for the Pod to run on. Each node has a maximum capacity for each of the resource types: the amount of CPU and memory it can provide for Pods. The scheduler ensures that, for each resource type, the sum of the resource requests of the scheduled -Containers is less than the capacity of the node. Note that although actual memory +containers is less than the capacity of the node. +Note that although actual memory or CPU resource usage on nodes is very low, the scheduler still refuses to place a Pod on a node if the capacity check fails. This protects against a resource shortage on a node when resource usage later increases, for example, during a @@ -300,84 +328,88 @@ daily peak in request rate. 当稍后节点上资源用量增加，例如到达请求率的每日峰值区间时，节点上也不会出现资源不足的问题。 -## 带资源约束的 Pod 如何运行 +## Kubernetes 应用资源请求与约束的方式 {#how-pods-with-resource-limits-are-run} -当 kubelet 启动 Pod 中的 Container 时，它会将 CPU 和内存约束信息传递给容器运行时。 +当 kubelet 启动 Pod 中的容器时，它会将容器的 CPU 和内存请求与约束信息传递给容器运行时。 -当使用 Docker 时： +在 Linux 系统上，容器运行时通常会配置内核 +{{< glossary_tooltip text="CGroups" term_id="cgroup" >}}，负责应用并实施所定义的请求。 - -- `spec.containers[].resources.requests.cpu` 先被转换为可能是小数的基础值，再乘以 1024。 - 这个数值和 2 的较大者用作 `docker run` 命令中的 - [`--cpu-shares`](https://docs.docker.com/engine/reference/run/#/cpu-share-constraint) - 标志的值。 -- `spec.containers[].resources.limits.cpu` 先被转换为 millicore 值，再乘以 100。 - 其结果就是每 100 毫秒内容器可以使用的 CPU 时间总量，单位为微秒。在此期间（100ms）， - 容器所使用的 CPU 时间不可以超过它被分配的时间。 - - {{< note >}} - 默认的配额（Quota）周期为 100 毫秒。CPU 配额的最小精度为 1 毫秒。 - {{}} - -- `spec.containers[].resources.limits.memory` 被转换为整数值，作为 `docker run` 命令中的 - [`--memory`](https://docs.docker.com/engine/reference/run/#/user-memory-constraints) - 参数值。 +- CPU 约束值定义的是容器可使用的 CPU 时间的硬性上限。 + 在每个调度周期（时间片）期间，Linux 内核检查是否已经超出该约束值； + 内核会在允许该 cgroup 恢复执行之前会等待。 + +- CPU 请求值定义的是一个权重值。如果若干不同的容器（CGroups）需要在一个共享的系统上竞争运行， + CPU 请求值大的负载会获得比请求值小的负载更多的 CPU 时间。 + +- 内存请求值主要用于（Kubernetes）Pod 调度期间。在一个启用了 CGroup v2 的节点上， + 容器运行时可能会使用内存请求值作为设置 `memory.min` 和 `memory.low` 的提示值。 + +- 内存约束值定义的是 CGroup 的内存约束。如果容器尝试分配的内存量超出约束值， + 则 Linux 内核的内存不足处理子系统会被激活，并停止尝试分配内存的容器中的某个进程。 + 如果该进程在容器中 PID 为 1，而容器被标记为可重新启动，则 Kubernetes + 会重新启动该容器。 + +- Pod 或容器的内存约束值也适用于通过内存供应的卷，例如 `emptyDir` 卷。 + kubelet 会跟踪 `tmpfs` 形式的 emptyDir 卷用量，将其作为容器的内存用量， + 而不是临时存储用量。 -如果 Container 超过其内存限制，则可能会被终止。如果容器可重新启动，则与所有其他类型的 -运行时失效一样，kubelet 将重新启动容器。 +如果某容器内存用量超过其内存请求值并且所在节点内存不足时，容器所处的 Pod +可能被{{< glossary_tooltip text="逐出" term_id="eviction" >}}. -如果一个 Container 内存用量超过其内存请求值，那么当节点内存不足时，容器所处的 Pod 可能被逐出。 +每个容器可能被允许也可能不被允许使用超过其 CPU 约束的处理时间。 +但是，容器运行时不会由于 CPU 使用率过高而杀死 Pod 或容器。 -每个 Container 可能被允许也可能不被允许使用超过其 CPU 约束的处理时间。 -但是，容器不会由于 CPU 使用率过高而被杀死。 - -要确定 Container 是否会由于资源约束而无法调度或被杀死，请参阅[疑难解答](#troubleshooting) 部分。 +要确定某容器是否会由于资源约束而无法调度或被杀死，请参阅[疑难解答](#troubleshooting)节。 ## 监控计算和内存资源用量 -Pod 的资源使用情况是作为 Pod 状态的一部分来报告的。 +kubelet 会将 Pod 的资源使用情况作为 Pod +[`status`](/zh/docs/concepts/overview/working-with-objects/kubernetes-objects/#object-spec-and-status) +的一部分来报告的。 -如果为集群配置了可选的 -[监控工具](/zh/docs/tasks/debug-application-cluster/resource-usage-monitoring/)， -则可以直接从 -[指标 API](/zh/docs/tasks/debug-application-cluster/resource-metrics-pipeline/#the-metrics-api) +如果为集群配置了可选的[监控工具](/zh/docs/tasks/debug-application-cluster/resource-usage-monitoring/)， +则可以直接从[指标 API](/zh/docs/tasks/debug-application-cluster/resource-metrics-pipeline/#the-metrics-api) 或者监控工具获得 Pod 的资源使用情况。 + {{< feature-state for_k8s_version="v1.10" state="beta" >}} 节点通常还可以具有本地的临时性存储，由本地挂接的可写入设备或者有时也用 RAM @@ -425,7 +458,7 @@ The kubelet also uses this kind of storage to hold [node-level container logs](/docs/concepts/cluster-administration/logging/#logging-at-the-node-level), container images, and the writable layers of running containers. -If a node fails, the data in its ephemeral storage can be lost. +If a node fails, the data in its ephemeral storage can be lost. Your applications cannot expect any performance SLAs (disk IOPS for example) from local ephemeral storage. @@ -569,43 +602,44 @@ kubelet 会将 `tmpfs` emptyDir 卷的用量当作容器内存用量，而不是 ### 为本地临时性存储设置请求和约束值 -你可以使用 _ephemeral-storage_ 来管理本地临时性存储。 -Pod 中的每个 Container 可以设置以下属性： +你可以使用 `ephemeral-storage` 来管理本地临时性存储。 +Pod 中的每个容器可以设置以下属性： * `spec.containers[].resources.limits.ephemeral-storage` * `spec.containers[].resources.requests.ephemeral-storage` -`ephemeral-storage` 的请求和约束值是按字节计量的。你可以使用一般整数或者定点数字 +`ephemeral-storage` 的请求和约束值是按量纲计量的。你可以使用一般整数或者定点数字 加上下面的后缀来表达存储量：E、P、T、G、M、K。 你也可以使用对应的 2 的幂级数来表达：Ei、Pi、Ti、Gi、Mi、Ki。 例如，下面的表达式所表达的大致是同一个值： -``` -128974848, 129e6, 129M, 123Mi -``` +- `128974848` +- `129e6` +- `129M` +- `123Mi` -在下面的例子中，Pod 包含两个 Container。每个 Container 请求 2 GiB 大小的本地临时性存储。 -每个 Container 都设置了 4 GiB 作为其本地临时性存储的约束值。 +在下面的例子中，Pod 包含两个容器。每个容器请求 2 GiB 大小的本地临时性存储。 +每个容器都设置了 4 GiB 作为其本地临时性存储的约束值。 因此，整个 Pod 的本地临时性存储请求是 4 GiB，且其本地临时性存储的约束为 8 GiB。 ```yaml @@ -644,9 +678,11 @@ spec: ### How Pods with ephemeral-storage requests are scheduled When you create a Pod, the Kubernetes scheduler selects a node for the Pod to -run on. Each node has a maximum amount of local ephemeral storage it can provide for Pods. For more information, see [Node Allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable). +run on. Each node has a maximum amount of local ephemeral storage it can provide for Pods. +For more information, see +[Node Allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable). -The scheduler ensures that the sum of the resource requests of the scheduled Containers is less than the capacity of the node. +The scheduler ensures that the sum of the resource requests of the scheduled containers is less than the capacity of the node. --> ### 带临时性存储的 Pods 的调度行为 @@ -657,7 +693,7 @@ The scheduler ensures that the sum of the resource requests of the scheduled Con [节点可分配资源](/zh/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) 节。 -调度器会确保所调度的 Containers 的资源请求总和不会超出节点的资源容量。 +调度器会确保所调度的容器的资源请求总和不会超出节点的资源容量。 ##### 其他资源 {#other-resources} @@ -918,7 +953,16 @@ that requests the resource to be scheduled on that node. 以在集群中节点的 `status.capacity` 中为其配置可用数量。 完成此操作后，节点的 `status.capacity` 字段中将包含新资源。 kubelet 会异步地对 `status.allocatable` 字段执行自动更新操作，使之包含新资源。 -请注意，由于调度器在评估 Pod 是否适合在某节点上执行时会使用节点的 `status.allocatable` 值， + + +由于调度器在评估 Pod 是否适合在某节点上执行时会使用节点的 `status.allocatable` 值， +调度器只会考虑异步更新之后的新值。 在更新节点容量使之包含新资源之后和请求该资源的第一个 Pod 被调度到该节点之间， 可能会有短暂的延迟。 @@ -929,7 +973,6 @@ Here is an example showing how to use `curl` to form an HTTP request that advertises five "example.com/foo" resources on node `k8s-node-1` whose master is `k8s-master`. --> - **示例：** 这是一个示例，显示了如何使用 `curl` 构造 HTTP 请求，公告主节点为 `k8s-master` @@ -963,14 +1006,14 @@ Cluster-level extended resources are not tied to nodes. They are usually managed by scheduler extenders, which handle the resource consumption and resource quota. You can specify the extended resources that are handled by scheduler extenders -in [scheduler policy configuration](/docs/reference/config-api/kube-scheduler-policy-config.v1/) +in [scheduler policy configuration](/docs/reference/config-api/kube-scheduler-config.v1beta3/) --> #### 集群层面的扩展资源 {#cluster-level-extended-resources} 集群层面的扩展资源并不绑定到具体节点。 它们通常由调度器扩展程序（Scheduler Extenders）管理，这些程序处理资源消耗和资源配额。 -你可以在[调度器策略配置](/zh/docs/reference/config-api/kube-scheduler-policy-config.v1/) +你可以在[调度器策略配置](/zh/docs/reference/config-api/kube-scheduler-config.v1beta3/) 中指定由调度器扩展程序处理的扩展资源。 **示例：** @@ -1091,9 +1134,10 @@ spec: - ## PID 限制 {#pid-limiting} 进程 ID（PID）限制允许对 kubelet 进行配置，以限制给定 Pod 可以消耗的 PID 数量。 @@ -1102,43 +1146,52 @@ Process ID (PID) limits allow for the configuration of a kubelet to limit the nu ## 疑难解答 -### 我的 Pod 处于悬决状态且事件信息显示 failedScheduling +### 我的 Pod 处于悬决状态且事件信息显示 `FailedScheduling` 如果调度器找不到该 Pod 可以匹配的任何节点，则该 Pod 将保持未被调度状态， 直到找到一个可以被调度到的位置。每当调度器找不到 Pod 可以调度的地方时， -会产生一个事件，如下所示： +会产生一个 [Event](/docs/reference/kubernetes-api/cluster-resources/event-v1/)。 +你可以使用 `kubectl` 来查看 Pod 的事件；例如： ```shell -kubectl describe pod frontend | grep -A 3 Events +kubectl describe pod frontend | grep -A 9999999999 Events ``` + ``` Events: - FirstSeen LastSeen Count From Subobject PathReason Message - 36s 5s 6 {scheduler} FailedScheduling Failed for reason PodExceedsFreeCPU and possibly others + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning FailedScheduling 23s default-scheduler 0/42 nodes available: insufficient cpu ``` - 在上述示例中，由于节点上的 CPU 资源不足，名为 “frontend” 的 Pod 无法被调度。 由于内存不足（PodExceedsFreeMemory）而导致失败时，也有类似的错误消息。 一般来说，如果 Pod 处于悬决状态且有这种类型的消息时，你可以尝试如下几件事情： @@ -1147,12 +1200,15 @@ You can check node capacities and amounts allocated with the - 终止不需要的 Pod，为悬决的 Pod 腾出空间。 - 检查 Pod 所需的资源是否超出所有节点的资源容量。例如，如果所有节点的容量都是`cpu：1`， 那么一个请求为 `cpu: 1.1` 的 Pod 永远不会被调度。 +- 检查节点上的污点设置。如果集群中节点上存在污点，而新的 Pod 不能容忍污点， + 调度器只会考虑将 Pod 调度到不带有该污点的节点上。 你可以使用 `kubectl describe nodes` 命令检查节点容量和已分配的资源数量。 例如： ```shell kubectl describe nodes e2e-test-node-pool-4lw4 ``` + ``` Name: e2e-test-node-pool-4lw4 [ ... 这里忽略了若干行以便阅读 ...] @@ -1184,34 +1240,60 @@ Allocated resources: In the preceding output, you can see that if a Pod requests more than 1120m CPUs or 6.23Gi of memory, it will not fit on the node. -By looking at the `Pods` section, you can see which Pods are taking up space on +By looking at the "Pods" section, you can see which Pods are taking up space on the node. - -The amount of resources available to Pods is less than the node capacity, because -system daemons use a portion of the available resources. The `allocatable` field -[NodeStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#nodestatus-v1-core) -gives the amount of resources that are available to Pods. For more information, see -[Node Allocatable Resources](https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md). -The [resource quota](/docs/concepts/policy/resource-quotas/) feature can be configured -to limit the total amount of resources that can be consumed. If used in conjunction -with namespaces, it can prevent one team from hogging all the resources. --> 在上面的输出中，你可以看到如果 Pod 请求超过 1120m CPU 或者 6.23Gi 内存，节点将无法满足。 -通过查看 `Pods` 部分，你将看到哪些 Pod 占用了节点上的资源。 +通过查看 "Pods" 部分，你将看到哪些 Pod 占用了节点上的资源。 -可供 Pod 使用的资源量小于节点容量，因为系统守护程序也会使用一部分可用资源。 -[NodeStatus](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#nodestatus-v1-core) -的 `allocatable` 字段给出了可用于 Pod 的资源量。 -有关更多信息，请参阅 [节点可分配资源](https://git.k8s.io/community/contributors/design-proposals/node-allocatable.md)。 + +Pods 可用的资源量低于节点的资源总量，因为系统守护进程也会使用一部分可用资源。 +在 Kubernetes API 中，每个 Node 都有一个 `.status.allocatable` 字段 +（详情参见 [NodeStatus](/docs/reference/kubernetes-api/cluster-resources/node-v1/#NodeStatus)）。 -可以配置 [资源配额](/zh/docs/concepts/policy/resource-quotas/) 功能特性 -以限制可以使用的资源总量。 -如果与名字空间配合一起使用，就可以防止一个团队占用所有资源。 + +字段 `.status.allocatable` 描述节点上可以用于 Pod 的资源总量（例如：15 个虚拟 +CPU、7538 MiB 内存）。关于 Kubernetes 中节点可分配资源的信息，可参阅 +[为系统守护进程预留计算资源](/zh/docs/tasks/administer-cluster/reserve-compute-resources/)。 + + +你可以配置[资源配额](/zh/docs/concepts/policy/resource-quotas/)功能特性以限制每个名字空间可以使用的资源总量。 +当某名字空间中存在 ResourceQuota 时，Kubernetes 会在该名字空间中的对象强制实施配额。 +例如，如果你为不同的团队分配名字空间，你可以为这些名字空间添加 ResourceQuota。 +设置资源配额有助于防止一个团队占用太多资源，以至于这种占用会影响其他团队。 + +你还需要考虑为这些名字空间设置授权访问： +为名字空间提供 **全部** 的写权限时，具有合适权限的人可能删除所有资源， +包括所配置的 ResourceQuota。 @@ -1225,6 +1307,11 @@ whether a Container is being killed because it is hitting a resource limit, call kubectl describe pod simmemleak-hra99 ``` + +输出类似于： + ``` Name: simmemleak-hra99 Namespace: default @@ -1235,7 +1322,6 @@ Status: Running Reason: Message: IP: 10.244.2.75 -Replication Controllers: simmemleak (1/1 replicas created) Containers: simmemleak: Image: saadali/simmemleak @@ -1254,57 +1340,47 @@ Conditions: Type Status Ready False Events: - FirstSeen LastSeen Count From SubobjectPath Reason Message - Tue, 07 Jul 2015 12:53:51 -0700 Tue, 07 Jul 2015 12:53:51 -0700 1 {scheduler } scheduled Successfully assigned simmemleak-hra99 to kubernetes-node-tf0f - Tue, 07 Jul 2015 12:53:51 -0700 Tue, 07 Jul 2015 12:53:51 -0700 1 {kubelet kubernetes-node-tf0f} implicitly required container POD pulled Pod container image "k8s.gcr.io/pause:0.8.0" already present on machine - Tue, 07 Jul 2015 12:53:51 -0700 Tue, 07 Jul 2015 12:53:51 -0700 1 {kubelet kubernetes-node-tf0f} implicitly required container POD created Created with docker id 6a41280f516d - Tue, 07 Jul 2015 12:53:51 -0700 Tue, 07 Jul 2015 12:53:51 -0700 1 {kubelet kubernetes-node-tf0f} implicitly required container POD started Started with docker id 6a41280f516d - Tue, 07 Jul 2015 12:53:51 -0700 Tue, 07 Jul 2015 12:53:51 -0700 1 {kubelet kubernetes-node-tf0f} spec.containers{simmemleak} created Created with docker id 87348f12526a + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 42s default-scheduler Successfully assigned simmemleak-hra99 to kubernetes-node-tf0f + Normal Pulled 41s kubelet Container image "saadali/simmemleak:latest" already present on machine + Normal Created 41s kubelet Created container simmemleak + Normal Started 40s kubelet Started container simmemleak + Normal Killing 32s kubelet Killing container with id ead3fb35-5cf5-44ed-9ae1-488115be66c6: Need to kill Pod ``` -在上面的例子中，`Restart Count: 5` 意味着 Pod 中的 `simmemleak` 容器被终止并重启了五次。 - -你可以使用 `kubectl get pod` 命令加上 `-o go-template=...` 选项来获取之前终止容器的状态。 - -```shell -kubectl get pod -o go-template='{{range.status.containerStatuses}}{{"Container Name: "}}{{.name}}{{"\r\nLastState: "}}{{.lastState}}{{end}}' simmemleak-hra99 -``` -``` -Container Name: simmemleak -LastState: map[terminated:map[exitCode:137 reason:OOM Killed startedAt:2015-07-07T20:58:43Z finishedAt:2015-07-07T20:58:43Z containerID:docker://0e4095bba1feccdfe7ef9fb6ebffe972b4b14285d5acdec6f0d3ae8a22fad8b2]] -``` +在上面的例子中，`Restart Count: 5` 意味着 Pod 中的 `simmemleak` +容器被终止并且（到目前为止）重启了五次。 +原因 `OOMKilled` 显示容器尝试使用超出其限制的内存量。 - -你可以看到容器因为 `reason:OOM killed` 而被终止，`OOM` 表示内存不足（Out Of Memory）。 +你接下来要做的或许是检查应用代码，看看是否存在内存泄露。 +如果你发现应用的行为与你所预期的相同，则可以考虑为该容器设置一个更高的内存约束 +（也可能需要设置请求值）。 ## {{% heading "whatsnext" %}} - * 获取[分配内存资源给容器和 Pod ](/zh/docs/tasks/configure-pod-container/assign-memory-resource/) 的实践经验 * 获取[分配 CPU 资源给容器和 Pod ](/zh/docs/tasks/configure-pod-container/assign-cpu-resource/) 的实践经验 -* 关于请求和约束之间的区别，细节信息可参见[资源服务质量](https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md) -* 阅读 API 参考文档中 [Container](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#container-v1-core) 部分。 -* 阅读 API 参考文档中 [ResourceRequirements](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcerequirements-v1-core) 部分。 -* 阅读 XFS 中关于[项目配额](https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-quotas.html) 的文档。 -* 阅读更多关于[kube-scheduler 策略参考 (v1)](/zh/docs/reference/config-api/kube-scheduler-policy-config.v1/) 的文档。 +* 阅读 API 参考中 [Container](/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container) + 和其[资源请求](/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources)定义。 +* 阅读 XFS 中[配额](https://xfs.org/docs/xfsdocs-xml-dev/XFS_User_Guide/tmp/en-US/html/xfs-quotas.html)的文档 +* 进一步阅读 [kube-scheduler 配置参考 (v1beta3)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta3/) diff --git a/content/zh/docs/concepts/policy/pod-security-policy.md b/content/zh/docs/concepts/policy/pod-security-policy.md index 7be672cb0b..f1b099352d 100644 --- a/content/zh/docs/concepts/policy/pod-security-policy.md +++ b/content/zh/docs/concepts/policy/pod-security-policy.md @@ -3,6 +3,7 @@ title: Pod 安全策略 content_type: concept weight: 30 --- + ### AppArmor 通过 PodSecurityPolicy 上的注解来控制。 详情请参阅 -[AppArmor 文档](/zh/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations)。 +[AppArmor 文档](/zh/docs/tutorials/policy/apparmor/#podsecuritypolicy-annotations)。 -1. 检查是否在使用 Kubernetes v1.11+，以便 NodeRestriction 功能可用。 -2. 确保你在使用[节点授权](/zh/docs/reference/access-authn-authz/node/)并且已经_启用_ +1. 确保你在使用[节点授权](/zh/docs/reference/access-authn-authz/node/)并且已经 _启用_ [NodeRestriction 准入插件](/zh/docs/reference/access-authn-authz/admission-controllers/#noderestriction)。 -3. 将 `node-restriction.kubernetes.io/` 前缀下的标签添加到 Node 对象， +2. 将 `node-restriction.kubernetes.io/` 前缀下的标签添加到 Node 对象， 然后在节点选择器中使用这些标签。 例如，`example.com.node-restriction.kubernetes.io/fips=true` 或 `example.com.node-restriction.kubernetes.io/pci-dss=true`。 @@ -216,7 +214,7 @@ feature, greatly expands the types of constraints you can express. The key enhan 3. you can constrain against labels on other pods running on the node (or other topological domain), rather than against labels on the node itself, which allows rules about which pods can and cannot be co-located --> -1. 语言更具表现力（不仅仅是“对完全匹配规则的 AND”） +1. 语言表达能力更强（不仅仅是“对完全匹配规则的 AND”） 2. 你可以发现规则是“软需求”/“偏好”，而不是硬性要求，因此， 如果调度器无法满足该要求，仍然调度该 Pod 3. 你可以使用节点上（或其他拓扑域中）的 Pod 的标签来约束，而不是使用 @@ -369,7 +367,7 @@ in the [scheduler configuration](/docs/reference/scheduling/config/). For exampl 例如： ```yaml -apiVersion: kubescheduler.config.k8s.io/v1beta1 +apiVersion: kubescheduler.config.k8s.io/v1beta3 kind: KubeSchedulerConfiguration profiles: diff --git a/content/zh/docs/concepts/scheduling-eviction/pod-overhead.md b/content/zh/docs/concepts/scheduling-eviction/pod-overhead.md index 998a2c3327..c0abf0bf58 100644 --- a/content/zh/docs/concepts/scheduling-eviction/pod-overhead.md +++ b/content/zh/docs/concepts/scheduling-eviction/pod-overhead.md @@ -32,11 +32,6 @@ _POD 开销_ 是一个特性，用于计算 Pod 基础设施在容器请求和 - - -## Pod 开销 -## Kubernetes 连接容器模型 +## Kubernetes 连接容器的模型 既然有了一个持续运行、可复制的应用，我们就能够将它暴露到网络上。 -在讨论 Kubernetes 网络连接的方式之前，非常值得与 Docker 中 “正常” 方式的网络进行对比。 -默认情况下，Docker 使用私有主机网络连接，只能与同在一台机器上的容器进行通信。 -为了实现容器的跨节点通信，必须在机器自己的 IP 上为这些容器分配端口，为容器进行端口转发或者代理。 - -多个开发人员或是提供容器的团队之间协调端口的分配很难做到规模化，那些难以控制的集群级别的问题，都会交由用户自己去处理。 Kubernetes 假设 Pod 可与其它 Pod 通信，不管它们在哪个主机上。 -Kubernetes 给 Pod 分配属于自己的集群私有 IP 地址，所以没必要在 Pod 或映射到的容器的端口和主机端口之间显式地创建连接。 -这表明了在 Pod 内的容器都能够连接到本地的每个端口，集群中的所有 Pod 不需要通过 NAT 转换就能够互相看到。 -文档的剩余部分详述如何在一个网络模型之上运行可靠的服务。 +Kubernetes 给每一个 Pod 分配一个集群私有 IP 地址，所以没必要在 +Pod 与 Pod 之间创建连接或将容器的端口映射到主机端口。 +这意味着同一个 Pod 内的所有容器能通过 localhost 上的端口互相连通，集群中的所有 Pod +也不需要通过 NAT 转换就能够互相看到。 +本文档的剩余部分详述如何在上述网络模型之上运行可靠的服务。 -该指南使用一个简单的 Nginx server 来演示并证明谈到的概念。 +本指南使用一个简单的 Nginx 服务器来演示概念验证原型。 @@ -45,7 +40,7 @@ Create an nginx Pod, and note that it has a container port specification: ## 在集群中暴露 Pod 我们在之前的示例中已经做过，然而让我们以网络连接的视角再重做一遍。 -创建一个 Nginx Pod，并且注意，它有一个容器端口的规范： +创建一个 Nginx Pod，注意其中包含一个容器端口的规约： {{< codenew file="service/networking/run-my-nginx.yaml" >}} @@ -77,16 +72,17 @@ kubectl get pods -l run=my-nginx -o yaml | grep podIP ``` -应该能够通过 ssh 登录到集群中的任何一个节点上，使用 curl 也能调通所有 IP 地址。 +你应该能够通过 ssh 登录到集群中的任何一个节点上，并使用诸如 `curl` 之类的工具向这两个 IP 地址发出查询请求。 需要注意的是，容器不会使用该节点上的 80 端口，也不会使用任何特定的 NAT 规则去路由流量到 Pod 上。 -这意味着可以在同一个节点上运行多个 Pod，使用相同的容器端口，并且可以从集群中任何其他的 Pod 或节点上使用 IP 的方式访问到它们。 -像 Docker 一样，端口能够被发布到主机节点的接口上，但是出于网络模型的原因应该从根本上减少这种用法。 +这意味着可以在同一个节点上运行多个 Nginx Pod，使用相同的 `containerPort`，并且可以从集群中任何其他的 +Pod 或节点上使用 IP 的方式访问到它们。 +如果你想的话，你依然可以将宿主节点的某个端口的流量转发到 Pod 中，但是出于网络模型的原因，你不必这么做。 -如果对此好奇，可以获取更多关于 [如何实现网络模型](/zh/docs/concepts/cluster-administration/networking/#how-to-achieve-this) 的内容。 +如果对此好奇，请参考 [Kubernetes 网络模型](/zh/docs/concepts/cluster-administration/networking/#the-kubernetes-network-model)。 ## 创建 Service -我们有 Pod 在一个扁平的、集群范围的地址空间中运行 Nginx 服务，可以直接连接到这些 Pod，但如果某个节点死掉了会发生什么呢？ +我们有一组在一个扁平的、集群范围的地址空间中运行 Nginx 服务的 Pod。 +理论上，你可以直接连接到这些 Pod，但如果某个节点死掉了会发生什么呢？ Pod 会终止，Deployment 将创建新的 Pod，且使用不同的 IP。这正是 Service 要解决的问题。 -Kubernetes Service 从逻辑上定义了运行在集群中的一组 Pod，这些 Pod 提供了相同的功能。 +Kubernetes Service 是集群中提供相同功能的一组 Pod 的抽象表达。 当每个 Service 创建时，会被分配一个唯一的 IP 地址（也称为 clusterIP）。 -这个 IP 地址与一个 Service 的生命周期绑定在一起，当 Service 存在的时候它也不会改变。 +这个 IP 地址与 Service 的生命周期绑定在一起，只要 Service 存在，它就不会改变。 可以配置 Pod 使它与 Service 进行通信，Pod 知道与 Service 通信将被自动地负载均衡到该 Service 中的某些 Pod 上。 可以使用 `kubectl expose` 命令为 2个 Nginx 副本创建一个 Service： @@ -120,7 +117,7 @@ service/my-nginx exposed This is equivalent to `kubectl apply -f` the following yaml: --> -这等价于使用 `kubectl create -f` 命令创建，对应如下的 yaml 文件： +这等价于使用 `kubectl create -f` 命令及如下的 yaml 文件创建： {{< codenew file="service/networking/nginx-svc.yaml" >}} @@ -134,11 +131,11 @@ View [Service](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/ API object to see the list of supported fields in service definition. Check your Service: --> -上述规约将创建一个 Service，对应具有标签 `run: my-nginx` 的 Pod，目标 TCP 端口 80， -并且在一个抽象的 Service 端口（`targetPort`：容器接收流量的端口；`port`：抽象的 Service -端口，可以使任何其它 Pod 访问该 Service 的端口）上暴露。 -查看 [Service API 对象](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core) -了解 Service 定义支持的字段列表。 +上述规约将创建一个 Service，该 Service 会将所有具有标签 `run: my-nginx` 的 Pod 的 TCP +80 端口暴露到一个抽象的 Service 端口上（`targetPort`：容器接收流量的端口；`port`：可任意取值的抽象的 Service +端口，其他 Pod 通过该端口访问 Service）。 +查看 [Service](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core) +API 对象以了解 Service 所能接受的字段列表。 查看你的 Service 资源: ```shell @@ -158,7 +155,7 @@ matching the Service's selector will automatically get added to the endpoints. Check the endpoints, and note that the IPs are the same as the Pods created in the first step: --> -正如前面所提到的，一个 Service 由一组 backend Pod 组成。这些 Pod 通过 `endpoints` 暴露出来。 +正如前面所提到的，一个 Service 由一组 Pod 提供支撑。这些 Pod 通过 `endpoints` 暴露出来。 Service Selector 将持续评估，结果被 POST 到一个名称为 `my-nginx` 的 Endpoint 对象上。 当 Pod 终止后，它会自动从 Endpoint 中移除，新的能够匹配上 Service Selector 的 Pod 将自动地被添加到 Endpoint 中。 检查该 Endpoint，注意到 IP 地址与在第一步创建的 Pod 是相同的。 @@ -194,7 +191,7 @@ never hits the wire. If you're curious about how this works you can read more about the [service proxy](/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies). --> -现在，能够从集群中任意节点上使用 curl 命令请求 Nginx Service `:` 。 +现在，你应该能够从集群中任意节点上使用 curl 命令向 `:` 发送请求以访问 Nginx Service。 注意 Service IP 完全是虚拟的，它从来没有走过网络，如果对它如何工作的原理感到好奇， 可以进一步阅读[服务代理](/zh/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies) 的内容。 @@ -204,12 +201,12 @@ about the [service proxy](/docs/concepts/services-networking/service/#virtual-ip Kubernetes supports 2 primary modes of finding a Service - environment variables and DNS. The former works out of the box while the latter requires the -[CoreDNS cluster addon](https://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/coredns). +[CoreDNS cluster addon](https://releases.k8s.io/{{< param "fullversion" >}}/cluster/addons/dns/coredns). --> ## 访问 Service -Kubernetes支持两种查找服务的主要模式: 环境变量和DNS。 前者开箱即用，而后者则需要[CoreDNS集群插件] -[CoreDNS 集群插件](https://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/coredns). +Kubernetes支持两种查找服务的主要模式: 环境变量和 DNS。前者开箱即用，而后者则需要 +[CoreDNS 集群插件](https://releases.k8s.io/{{< param "fullversion" >}}/cluster/addons/dns/coredns). ### 环境变量 -当 Pod 在 Node 上运行时，kubelet 会为每个活跃的 Service 添加一组环境变量。 -这会有一个顺序的问题。想了解为何，检查正在运行的 Nginx Pod 的环境变量（Pod 名称将不会相同）： +当 Pod 在节点上运行时，kubelet 会针对每个活跃的 Service 为 Pod 添加一组环境变量。 +这就引入了一个顺序的问题。为解释这个问题，让我们先检查正在运行的 Nginx Pod +的环境变量（你的环境中的 Pod 名称将会与下面示例命令中的不同）： ```shell kubectl exec my-nginx-3800858182-jr4a2 -- printenv | grep SERVICE @@ -254,10 +252,11 @@ replicas. This will give you scheduler-level Service spreading of your Pods variables: --> -注意，还没有谈及到 Service。这是因为创建副本先于 Service。 -这样做的另一个缺点是，调度器可能在同一个机器上放置所有 Pod，如果该机器宕机则所有的 Service 都会挂掉。 -正确的做法是，我们杀掉 2 个 Pod，等待 Deployment 去创建它们。 -这次 Service 会 *先于* 副本存在。这将实现调度器级别的 Service，能够使 Pod 分散创建（假定所有的 Node 都具有同样的容量），以及正确的环境变量： +能看到环境变量中并没有你创建的 Service 相关的值。这是因为副本的创建先于 Service。 +这样做的另一个缺点是，调度器可能会将所有 Pod 部署到同一台机器上，如果该机器宕机则整个 Service 都会离线。 +要改正的话，我们可以先终止这 2 个 Pod，然后等待 Deployment 去重新创建它们。 +这次 Service 会*先于*副本存在。这将实现调度器级别的 Pod 按 Service +分布（假定所有的节点都具有同样的容量），并提供正确的环境变量： ```shell kubectl scale deployment my-nginx --replicas=0; kubectl scale deployment my-nginx --replicas=2; @@ -274,7 +273,7 @@ my-nginx-3800858182-j4rm4 1/1 Running 0 5s 10.244.3.8 You may notice that the pods have different names, since they are killed and recreated. --> -可能注意到，Pod 具有不同的名称，因为它们被杀掉后并被重新创建。 +你可能注意到，Pod 具有不同的名称，这是因为它们是被重新创建的。 ```shell kubectl exec my-nginx-3800858182-e9ihh -- printenv | grep SERVICE @@ -293,8 +292,8 @@ KUBERNETES_SERVICE_PORT_HTTPS=443 Kubernetes offers a DNS cluster addon Service that automatically assigns dns names to other Services. You can check if it's running on your cluster: --> -Kubernetes 提供了一个 DNS 插件 Service，它使用 skydns 自动为其它 Service 指派 DNS 名字。 -如果它在集群中处于运行状态，可以通过如下命令来检查： +Kubernetes 提供了一个自动为其它 Service 分配 DNS 名字的 DNS 插件 Service。 +你可以通过如下命令检查它是否在工作： ```shell kubectl get services kube-dns --namespace=kube-system @@ -305,18 +304,15 @@ kube-dns ClusterIP 10.0.0.10 53/UDP,53/TCP 8m ``` -如果没有在运行，可以[启用它](https://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/kube-dns/README.md#how-do-i-configure-it)。 -本段剩余的内容，将假设已经有一个 Service，它具有一个长久存在的 IP（my-nginx）， -一个为该 IP 指派名称的 DNS 服务器。 这里我们使用 CoreDNS 集群插件（应用名为 `kube-dns`）， -所以可以通过标准做法，使在集群中的任何 Pod 都能与该 Service 通信（例如：`gethostbyname()`）。 +本段剩余的内容假设你已经有一个拥有持久 IP 地址的 Service（my-nginx），以及一个为其 +IP 分配名称的 DNS 服务器。 这里我们使用 CoreDNS 集群插件（应用名为 `kube-dns`）， +所以在集群中的任何 Pod 中，你都可以使用标准方法（例如：`gethostbyname()`）与该 Service 通信。 如果 CoreDNS 没有在运行，你可以参照 -[CoreDNS README](https://github.com/coredns/deployment/tree/master/kubernetes) 或者 -[安装 CoreDNS](/zh/docs/tasks/administer-cluster/coredns/#installing-coredns) 来启用它。 +[CoreDNS README](https://github.com/coredns/deployment/tree/master/kubernetes) +或者[安装 CoreDNS](/zh/docs/tasks/administer-cluster/coredns/#installing-coredns) 来启用它。 让我们运行另一个 curl 应用来进行测试： ```shell @@ -351,21 +347,21 @@ Till now we have only accessed the nginx server from within the cluster. Before * An nginx server configured to use the certificates * A [secret](/docs/concepts/configuration/secret/) that makes the certificates accessible to pods -You can acquire all these from the [nginx https example](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/https-nginx/). This requires having go and make tools installed. If you don't want to install those, then follow the manual steps later. In short: +You can acquire all these from the [nginx https example](https://github.com/kubernetes/examples/tree/master/staging/https-nginx/). This requires having go and make tools installed. If you don't want to install those, then follow the manual steps later. In short: --> ## 保护 Service {#securing-the-service} 到现在为止，我们只在集群内部访问了 Nginx 服务器。在将 Service 暴露到因特网之前，我们希望确保通信信道是安全的。 -为实现这一目的，可能需要： +为实现这一目的，需要： -* 用于 HTTPS 的自签名证书（除非已经有了一个识别身份的证书） +* 用于 HTTPS 的自签名证书（除非已经有了一个身份证书） * 使用证书配置的 Nginx 服务器 -* 使证书可以访问 Pod 的 [Secret](/zh/docs/concepts/configuration/secret/) +* 使 Pod 可以访问证书的 [Secret](/zh/docs/concepts/configuration/secret/) -你可以从 [Nginx https 示例](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/https-nginx/) -获取所有上述内容。你需要安装 go 和 make 工具。如果你不想安装这些软件，可以按照 -后文所述的手动执行步骤执行操作。简要过程如下： +你可以从 +[Nginx https 示例](https://github.com/kubernetes/examples/tree/master/staging/https-nginx/)获取所有上述内容。 +你需要安装 go 和 make 工具。如果你不想安装这些软件，可以按照后文所述的手动执行步骤执行操作。简要过程如下： ```shell make keys KEY=/tmp/nginx.key CERT=/tmp/nginx.crt @@ -385,19 +381,6 @@ nginxsecret kubernetes.io/tls 2 1m 以下是 configmap： ```shell @@ -420,9 +403,9 @@ Following are the manual steps to follow in case you run into problems running m 以下是你在运行 make 时遇到问题时要遵循的手动步骤（例如，在 Windows 上）： ```shell -# Create a public private key pair +# 创建公钥和相对应的私钥 openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /d/tmp/nginx.key -out /d/tmp/nginx.crt -subj "/CN=my-nginx/O=my-nginx" -# Convert the keys to base64 encoding +# 对密钥实施 base64 编码 cat /d/tmp/nginx.crt | base64 cat /d/tmp/nginx.key | base64 ``` @@ -447,7 +430,7 @@ data: -现在使用文件创建 Secrets： +现在使用文件创建 Secret： ```shell kubectl apply -f nginxsecrets.yaml @@ -462,7 +445,7 @@ nginxsecret kubernetes.io/tls 2 1m -现在修改 nginx 副本，启动一个使用在秘钥中的证书的 HTTPS 服务器和 Service，暴露端口（80 和 443）： +现在修改 nginx 副本以启动一个使用 Secret 中的证书的 HTTPS 服务器以及相应的用于暴露其端口（80 和 443）的 Service： {{< codenew file="service/networking/nginx-secure-app.yaml" >}} @@ -470,7 +453,7 @@ Now modify your nginx replicas to start an https server using the certificate in Noteworthy points about the nginx-secure-app manifest: - It contains both Deployment and Service specification in the same file. -- The [nginx server](https://github.com/kubernetes/examples/tree/{{< param "githubbranch" >}}/staging/https-nginx/default.conf) +- The [nginx server](https://github.com/kubernetes/examples/tree/master/staging/https-nginx/default.conf) serves HTTP traffic on port 80 and HTTPS traffic on 443, and nginx Service exposes both ports. - Each container has access to the keys through a volume mounted at `/etc/nginx/ssl`. @@ -478,10 +461,10 @@ Noteworthy points about the nginx-secure-app manifest: --> 关于 nginx-secure-app 清单，值得注意的几点如下： -- 它在相同的文件中包含了 Deployment 和 Service 的规约 -- [nginx 服务器](https://github.com/kubernetes/kubernetes/tree/{{< param "githubbranch" >}}/staging/https-nginx/default.conf) - 处理 80 端口上的 HTTP 流量，以及 443 端口上的 HTTPS 流量，Nginx Service 暴露了这两个端口。 -- 每个容器访问挂载在 /etc/nginx/ssl 卷上的秘钥。这需要在 Nginx 服务器启动之前安装好。 +- 它将 Deployment 和 Service 的规约放在了同一个文件中。 +- [Nginx 服务器](https://github.com/kubernetes/examples/tree/master/staging/https-nginx/default.conf)通过 + 80 端口处理 HTTP 流量，通过 443 端口处理 HTTPS 流量，而 Nginx Service 则暴露了这两个端口。 +- 每个容器能通过挂载在 `/etc/nginx/ssl` 的卷访问秘钥。卷和密钥需要在 Nginx 服务器启动*之前*配置好。 ```shell kubectl delete deployments,svc my-nginx; kubectl create -f ./nginx-secure-app.yaml @@ -508,7 +491,7 @@ Let's test this from a pod (the same secret is being reused for simplicity, the 注意最后一步我们是如何提供 `-k` 参数执行 curl 命令的，这是因为在证书生成时， 我们不知道任何关于运行 nginx 的 Pod 的信息，所以不得不在执行 curl 命令时忽略 CName 不匹配的情况。 通过创建 Service，我们连接了在证书中的 CName 与在 Service 查询时被 Pod 使用的实际 DNS 名字。 -让我们从一个 Pod 来测试（为了简化使用同一个秘钥，Pod 仅需要使用 nginx.crt 去访问 Service）： +让我们从一个 Pod 来测试（为了方便，这里使用同一个 Secret，Pod 仅需要使用 nginx.crt 去访问 Service）： {{< codenew file="service/networking/curlpod.yaml" >}} @@ -538,10 +521,10 @@ node has a public IP. --> ## 暴露 Service -对我们应用的某些部分，可能希望将 Service 暴露在一个外部 IP 地址上。 +对应用的某些部分，你可能希望将 Service 暴露在一个外部 IP 地址上。 Kubernetes 支持两种实现方式：NodePort 和 LoadBalancer。 -在上一段创建的 Service 使用了 `NodePort`，因此 Nginx https 副本已经就绪， -如果使用一个公网 IP，能够处理 Internet 上的流量。 +在上一段创建的 Service 使用了 `NodePort`，因此，如果你的节点有一个公网 +IP，那么 Nginx HTTPS 副本已经能够处理因特网上的流量。 ```shell kubectl get svc my-nginx -o yaml | grep nodePort -C 5 @@ -579,18 +562,18 @@ kubectl get nodes -o yaml | grep ExternalIP -C 1 type: ExternalIP allocatable: ... -$ curl https://: -k +$ curl https://: -k ...

Welcome to nginx!

``` -让我们重新创建一个 Service，使用一个云负载均衡器，只需要将 `my-nginx` Service 的 `Type` -由 `NodePort` 改成 `LoadBalancer`。 +让我们重新创建一个 Service 以使用云负载均衡器。 +将 `my-nginx` Service 的 `Type` 由 `NodePort` 改成 `LoadBalancer`： ```shell kubectl edit svc my-nginx @@ -616,17 +599,15 @@ output, in fact, so you'll need to do `kubectl describe service my-nginx` to see it. You'll see something like this: --> -在 `EXTERNAL-IP` 列指定的 IP 地址是在公网上可用的。`CLUSTER-IP` 只在集群/私有云网络中可用。 +在 `EXTERNAL-IP` 列中的 IP 地址能在公网上被访问到。`CLUSTER-IP` 只能从集群/私有云网络中访问。 -注意，在 AWS 上类型 `LoadBalancer` 创建一个 ELB，它使用主机名（比较长），而不是 IP。 -它太长以至于不能适配标准 `kubectl get svc` 的输出，事实上需要通过执行 `kubectl describe service my-nginx` 命令来查看它。 +注意，在 AWS 上，类型 `LoadBalancer` 的服务会创建一个 ELB，且 ELB 使用主机名（比较长），而不是 IP。 +ELB 的主机名太长以至于不能适配标准 `kubectl get svc` 的输出，所以需要通过执行 +`kubectl describe service my-nginx` 命令来查看它。 可以看到类似如下内容： ```shell kubectl describe service my-nginx -``` - -``` ... LoadBalancer Ingress: a320587ffd19711e5a37606cf4a74574-1142138393.us-east-1.elb.amazonaws.com ... diff --git a/content/zh/docs/concepts/services-networking/ingress-controllers.md b/content/zh/docs/concepts/services-networking/ingress-controllers.md index aca161b967..6f409182fd 100644 --- a/content/zh/docs/concepts/services-networking/ingress-controllers.md +++ b/content/zh/docs/concepts/services-networking/ingress-controllers.md @@ -29,9 +29,9 @@ Ingress 控制器不是随集群自动启动的。 基于此页面，你可选择最适合你的集群的 ingress 控制器实现。 Kubernetes 作为一个项目，目前支持和维护 -[AWS](https://github.com/kubernetes-sigs/aws-load-balancer-controller#readme)， -[GCE](https://git.k8s.io/ingress-gce/README.md) -和 [nginx](https://git.k8s.io/ingress-nginx/README.md#readme) Ingress 控制器。 +[AWS](https://github.com/kubernetes-sigs/aws-load-balancer-controller#readme)、 +[GCE](https://git.k8s.io/ingress-gce/README.md) +和 [Nginx](https://git.k8s.io/ingress-nginx/README.md#readme) Ingress 控制器。 @@ -46,32 +46,37 @@ Kubernetes 作为一个项目，目前支持和维护 * [AKS Application Gateway Ingress Controller](https://azure.github.io/application-gateway-kubernetes-ingress/) is an ingress controller that configures the [Azure Application Gateway](https://docs.microsoft.com/azure/application-gateway/overview). * [Ambassador](https://www.getambassador.io/) API Gateway is an [Envoy](https://www.envoyproxy.io)-based ingress controller. +* [Apache APISIX ingress controller](https://github.com/apache/apisix-ingress-controller) is an [Apache APISIX](https://github.com/apache/apisix)-based ingress controller. * [Avi Kubernetes Operator](https://github.com/vmware/load-balancer-and-ingress-services-for-kubernetes) provides L4-L7 load-balancing using [VMware NSX Advanced Load Balancer](https://avinetworks.com/). -* [BFE Ingress Controller](https://github.com/bfenetworks/ingress-bfe) is a [BFE](https://www.bfe-networks.net)-based ingress controller. -* The [Citrix ingress controller](https://github.com/citrix/citrix-k8s-ingress-controller#readme) works with - Citrix Application Delivery Controller. -* [Contour](https://projectcontour.io/) is an [Envoy](https://www.envoyproxy.io/) based ingress controller. -* [EnRoute](https://getenroute.io/) is an [Envoy](https://www.envoyproxy.io) based API gateway that can run as an ingress controller. --> * [AKS 应用程序网关 Ingress 控制器](https://azure.github.io/application-gateway-kubernetes-ingress/) 是一个配置 [Azure 应用程序网关](https://docs.microsoft.com/azure/application-gateway/overview) 的 Ingress 控制器。 * [Ambassador](https://www.getambassador.io/) API 网关是一个基于 - [Envoy](https://www.envoyproxy.io) 的 Ingress - 控制器。 + [Envoy](https://www.envoyproxy.io) 的 Ingress 控制器。 * [Apache APISIX Ingress 控制器](https://github.com/apache/apisix-ingress-controller) 是一个基于 [Apache APISIX 网关](https://github.com/apache/apisix) 的 Ingress 控制器。 * [Avi Kubernetes Operator](https://github.com/vmware/load-balancer-and-ingress-services-for-kubernetes) 使用 [VMware NSX Advanced Load Balancer](https://avinetworks.com/) 提供第 4 到第 7 层的负载均衡。 -* [BFE Ingress 控制器](https://github.com/bfenetworks/ingress-bfe) 是一个基于 [BFE](https://www.bfe-networks.net) 的 Ingress 控制器。 + +* [BFE Ingress 控制器](https://github.com/bfenetworks/ingress-bfe)是一个基于 + [BFE](https://www.bfe-networks.net) 的 Ingress 控制器。 * [Citrix Ingress 控制器](https://github.com/citrix/citrix-k8s-ingress-controller#readme) 可以用来与 Citrix Application Delivery Controller 一起使用。 * [Contour](https://projectcontour.io/) 是一个基于 [Envoy](https://www.envoyproxy.io/) 的 Ingress 控制器。 -* [EnRoute](https://getenroute.io/) 是一个基于 [Envoy](https://www.envoyproxy.io) API 网关， - 可以作为 Ingress 控制器来执行。 -* [Easegress IngressController](https://github.com/megaease/easegress/blob/main/doc/ingresscontroller.md) 是一个基于 [Easegress](https://megaease.com/easegress/) API 网关，可以作为 Ingress 控制器来执行。 +* [EnRoute](https://getenroute.io/) 是一个基于 [Envoy](https://www.envoyproxy.io) + 的 API 网关，可以用作 Ingress 控制器。 +* [Easegress IngressController](https://github.com/megaease/easegress/blob/main/doc/reference/ingresscontroller.md) + 是一个基于 [Easegress](https://megaease.com/easegress/) 的 API 网关，可以用作 Ingress 控制器。 +* [用于 Kubernetes 的 Kong Ingress 控制器](https://github.com/Kong/kubernetes-ingress-controller#readme) + 是一个用来驱动 [Kong Gateway](https://konghq.com/kong/) 的 Ingress 控制器。 +* [用于 Kubernetes 的 NGINX Ingress 控制器](https://www.nginx.com/products/nginx-ingress-controller/) + 能够与 [NGINX](https://www.nginx.com/resources/glossary/nginx/) + 网页服务器（作为代理）一起使用。 +* [Pomerium Ingress 控制器](https://www.pomerium.com/docs/k8s/ingress.html) + 基于 [Pomerium](https://pomerium.com/)，能提供上下文感知的准入策略。 +* [Skipper](https://opensource.zalando.com/skipper/kubernetes/ingress-controller/) HTTP + 路由器和反向代理可用于服务组装，支持包括 Kubernetes Ingress + 这类使用场景，是一个用以构造你自己的定制代理的库。 + -* [用于 Kubernetes 的 Kong Ingress 控制器](https://github.com/Kong/kubernetes-ingress-controller#readme) - 是一个用来驱动 [Kong Gateway](https://konghq.com/kong/) 的 Ingress 控制器。 -* [用于 Kubernetes 的 NGINX Ingress 控制器](https://www.nginx.com/products/nginx-ingress-controller/) - 能够与 [NGINX](https://www.nginx.com/resources/glossary/nginx/) Web 服务器（作为代理） - 一起使用。 -* [Skipper](https://opensource.zalando.com/skipper/kubernetes/ingress-controller/) HTTP - 路由器和反向代理可用于服务组装，支持包括 Kubernetes Ingress 这类使用场景， - 设计用来作为构造你自己的定制代理的库。 * [Traefik Kubernetes Ingress 提供程序](https://doc.traefik.io/traefik/providers/kubernetes-ingress/) 是一个用于 [Traefik](https://traefik.io/traefik/) 代理的 Ingress 控制器。 * [Tyk Operator](https://github.com/TykTechnologies/tyk-operator) @@ -130,23 +139,31 @@ Kubernetes 作为一个项目，目前支持和维护 ## 使用多个 Ingress 控制器 +你可以使用 +[Ingress 类](/zh/docs/concepts/services-networking/ingress/#ingress-class)在集群中部署任意数量的 +Ingress 控制器。 +请注意你的 Ingress 类资源的 `.metadata.name` 字段。 +当你创建 Ingress 时，你需要用此字段的值来设置 Ingress 对象的 `ingressClassName` 字段（请参考 +[IngressSpec v1 reference](/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec)）。 +`ingressClassName` +是之前的[注解](/zh/docs/concepts/services-networking/ingress/#deprecated-annotation)做法的替代。 -If you do not define a class, your cloud provider may use a default ingress controller. + - -你可以在集群中部署[任意数量的 ingress 控制器](https://git.k8s.io/ingress-nginx/docs/user-guide/multiple-ingress.md#multiple-ingress-controllers)。 -创建 ingress 时，应该使用适当的 -[`ingress.class`](https://git.k8s.io/ingress-gce/docs/faq/README.md#how-do-i-run-multiple-ingress-controllers-in-the-same-cluster) -注解每个 Ingress 以表明在集群中如果有多个 Ingress 控制器时，应该使用哪个 Ingress 控制器。 - -如果不定义 `ingress.class`，云提供商可能使用默认的 Ingress 控制器。 +如果你不为 Ingress 指定一个 IngressClass，并且你的集群中只有一个 IngressClass 被标记为了集群默认，那么 +Kubernetes 会[应用](/zh/docs/concepts/services-networking/ingress/#default-ingress-class)此默认 +IngressClass。 +你可以通过将 +[`ingressclass.kubernetes.io/is-default-class` 注解](/zh/docs/reference/labels-annotations-taints/#ingressclass-kubernetes-io-is-default-class) +的值设置为 `"true"` 来将一个 IngressClass 标记为集群默认。 理想情况下，所有 Ingress 控制器都应满足此规范，但各种 Ingress 控制器的操作略有不同。 diff --git a/content/zh/docs/concepts/services-networking/ingress.md b/content/zh/docs/concepts/services-networking/ingress.md index c1ee7b6078..2a1548d654 100644 --- a/content/zh/docs/concepts/services-networking/ingress.md +++ b/content/zh/docs/concepts/services-networking/ingress.md @@ -31,15 +31,14 @@ For clarity, this guide defines the following terms: * Cluster network: A set of links, logical or physical, that facilitate communication within a cluster according to the Kubernetes [networking model](/docs/concepts/cluster-administration/networking/). * Service: A Kubernetes {{< glossary_tooltip term_id="service" >}} that identifies a set of Pods using {{< glossary_tooltip text="label" term_id="label" >}} selectors. Unless mentioned otherwise, Services are assumed to have virtual IPs only routable within the cluster network. --> -* 节点（Node）: Kubernetes 集群中其中一台工作机器，是集群的一部分。 +* 节点（Node）: Kubernetes 集群中的一台工作机器，是集群的一部分。 * 集群（Cluster）: 一组运行由 Kubernetes 管理的容器化应用程序的节点。 在此示例和在大多数常见的 Kubernetes 部署环境中，集群中的节点都不在公共网络中。 -* 边缘路由器（Edge router）: 在集群中强制执行防火墙策略的路由器（router）。 - 可以是由云提供商管理的网关，也可以是物理硬件。 -* 集群网络（Cluster network）: 一组逻辑的或物理的连接，根据 Kubernetes - [网络模型](/zh/docs/concepts/cluster-administration/networking/) 在集群内实现通信。 -* 服务（Service）：Kubernetes {{< glossary_tooltip text="服务" term_id="service" >}}使用 - {{< glossary_tooltip text="标签" term_id="label" >}}选择算符（selectors）标识的一组 Pod。 +* 边缘路由器（Edge Router）: 在集群中强制执行防火墙策略的路由器。可以是由云提供商管理的网关，也可以是物理硬件。 +* 集群网络（Cluster Network）: 一组逻辑的或物理的连接，根据 Kubernetes + [网络模型](/zh/docs/concepts/cluster-administration/networking/)在集群内实现通信。 +* 服务（Service）：Kubernetes {{< glossary_tooltip term_id="service" >}}， + 使用{{< glossary_tooltip text="标签" term_id="label" >}}选择器（selectors）辨认一组 Pod。 除非另有说明，否则假定服务只具有在集群网络中可路由的虚拟 IP。 -可以将 Ingress 配置为服务提供外部可访问的 URL、负载均衡流量、终止 SSL/TLS，以及提供基于名称的虚拟主机等能力。 +Ingress 可为 Service 提供外部可访问的 URL、负载均衡流量、终止 SSL/TLS，以及基于名称的虚拟托管。 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers) 通常负责通过负载均衡器来实现 Ingress，尽管它也可以配置边缘路由器或其他前端来帮助处理流量。 Ingress 不会公开任意端口或协议。 将 HTTP 和 HTTPS 以外的服务公开到 Internet 时，通常使用 -[Service.Type=NodePort](/zh/docs/concepts/services-networking/service/#nodeport) +[Service.Type=NodePort](/zh/docs/concepts/services-networking/service/#type-nodeport) 或 [Service.Type=LoadBalancer](/zh/docs/concepts/services-networking/service/#loadbalancer) -类型的服务。 +类型的 Service。 ## 环境准备 -你必须具有 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers) 才能满足 Ingress 的要求。 +你必须拥有一个 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers) 才能满足 Ingress 的要求。 仅创建 Ingress 资源本身没有任何效果。 - 与所有其他 Kubernetes 资源一样，Ingress 需要使用 `apiVersion`、`kind` 和 `metadata` 字段。 - Ingress 对象的命名必须是合法的 [DNS 子域名名称](/zh/docs/concepts/overview/working-with-objects/names#dns-subdomain-names)。 - 有关使用配置文件的一般信息，请参见[部署应用](/zh/docs/tasks/run-application/run-stateless-application-deployment/)、 +与所有其他 Kubernetes 资源一样，Ingress 需要指定 `apiVersion`、`kind` 和 `metadata` 字段。 +Ingress 对象的命名必须是合法的 [DNS 子域名名称](/zh/docs/concepts/overview/working-with-objects/names#dns-subdomain-names)。 +关于如何使用配置文件，请参见[部署应用](/zh/docs/tasks/run-application/run-stateless-application-deployment/)、 [配置容器](/zh/docs/tasks/configure-pod-container/configure-pod-configmap/)、 [管理资源](/zh/docs/concepts/cluster-administration/manage-deployment/)。 - Ingress 经常使用注解（annotations）来配置一些选项，具体取决于 Ingress 控制器，例如 -[重写目标注解](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md)。 - 不同的 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers) -支持不同的注解。查看文档以供你选择 Ingress 控制器，以了解支持哪些注解。 +Ingress 经常使用注解（annotations）来配置一些选项，具体取决于 Ingress +控制器，例如[重写目标注解](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/rewrite/README.md)。 +不同的 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers)支持不同的注解。 +查看你所选的 Ingress 控制器的文档，以了解其支持哪些注解。 Ingress [规约](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) 提供了配置负载均衡器或者代理服务器所需的所有信息。 最重要的是，其中包含与所有传入请求匹配的规则列表。 -Ingress 资源仅支持用于转发 HTTP 流量的规则。 +Ingress 资源仅支持用于转发 HTTP(S) 流量的规则。 + + +如果 `ingressClassName` 被省略，那么你应该定义一个[默认 Ingress 类](#default-ingress-class)。 + +有一些 Ingress 控制器不需要定义默认的 `IngressClass`。比如：Ingress-NGINX +控制器可以通过[参数](https://kubernetes.github.io/ingress-nginx/#what-is-the-flag-watch-ingress-without-class) +`--watch-ingress-without-class` 来配置。 +不过仍然[推荐](https://kubernetes.github.io/ingress-nginx/#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do) +按[下文](#default-ingress-class)所示来设置默认的 `IngressClass`。 -通常在 Ingress 控制器中会配置 `defaultBackend`（默认后端），以服务于任何不符合规约中 `path` 的请求。 +通常在 Ingress 控制器中会配置 `defaultBackend`（默认后端），以服务于无法与规约中 `path` 匹配的所有请求。 -### DefaultBackend {#default-backend} +An Ingress with no rules sends all traffic to a single default backend and `.spec.defaultBackend` +is the backend that should handle requests in that case. +The `defaultBackend` is conventionally a configuration option of the +[Ingress controller](/docs/concepts/services-networking/ingress-controllers) and +is not specified in your Ingress resources. +If no `.spec.rules` are specified, `.spec.defaultBackend` must be specified. +If `defaultBackend` is not set, the handling of requests that do not match any of the rules will be up to the +ingress controller (consult the documentation for your ingress controller to find out how it handles this case). -没有 `rules` 的 Ingress 将所有流量发送到同一个默认后端。 -`defaultBackend` 通常是 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers) -的配置选项，而非在 Ingress 资源中指定。 - - -如果 `hosts` 或 `paths` 都没有与 Ingress 对象中的 HTTP 请求匹配，则流量将路由到默认后端。 +### 默认后端 {#default-backend} + +没有设置规则的 Ingress 将所有流量发送到同一个默认后端，而 +`.spec.defaultBackend` 则是在这种情况下处理请求的那个默认后端。 +`defaultBackend` 通常是 +[Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers)的配置选项，而非在 +Ingress 资源中指定。 +如果未设置任何的 `.spec.rules`，那么必须指定 `.spec.defaultBackend`。 +如果未设置 `defaultBackend`，那么如何处理所有与规则不匹配的流量将交由 +Ingress 控制器决定（请参考你的 Ingress 控制器的文档以了解它是如何处理那些流量的）。 + +如果没有 `hosts` 或 `paths` 与 Ingress 对象中的 HTTP 请求匹配，则流量将被路由到默认后端。 ### 资源后端 {#resource-backend} -`Resource` 后端是一个 `ObjectRef`，指向同一名字空间中的另一个 -Kubernetes，将其作为 Ingress 对象。`Resource` 与 `Service` 配置是互斥的，在 -二者均被设置时会无法通过合法性检查。 +`Resource` 后端是一个引用，指向同一命名空间中的另一个 Kubernetes 资源，将其作为 Ingress 对象。 +`Resource` 后端与 Service 后端是互斥的，在二者均被设置时会无法通过合法性检查。 `Resource` 后端的一种常见用法是将所有入站数据导向带有静态资产的对象存储后端。 {{< codenew file="service/networking/ingress-resource-backend.yaml" >}} @@ -410,41 +437,140 @@ IngressClass 资源包含额外的配置，其中包括应当实现该类的控 {{< codenew file="service/networking/external-lb.yaml" >}} -IngressClass 资源包含一个可选的 `parameters` 字段，可用于为该类引用额外的、 -特定于具体实现的配置。 +IngressClass 中的 `.spec.parameters` 字段可用于引用其他资源以提供额外的相关配置。 + +参数（`parameters`）的具体类型取决于你在 `.spec.controller` 字段中指定的 Ingress 控制器。 -#### 名字空间域的参数 +### IngressClass scope -{{< feature-state for_k8s_version="v1.22" state="beta" >}} +Depending on your ingress controller, you may be able to use parameters +that you set cluster-wide, or just for one namespace. +--> +### IngressClass 的作用域 + +取决于你的 Ingress 控制器，你可能可以使用集群范围设置的参数或某个名字空间范围的参数。 + +{{< tabs name="tabs_ingressclass_parameter_scope" >}} +{{% tab name="集群作用域" %}} + +IngressClass 的参数默认是集群范围的。 + +如果你设置了 `.spec.parameters` 字段且未设置 `.spec.parameters.scope` +字段，或是将 `.spec.parameters.scope` 字段设为了 `Cluster`，那么该 +IngressClass 所指代的即是一个集群作用域的资源。 +参数的 `kind`（和 `apiGroup` 一起）指向一个集群作用域的 +API（可能是一个定制资源（Custom Resource）），而它的 +`name` 则为此 API 确定了一个具体的集群作用域的资源。 + +示例： +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: external-lb-1 +spec: + controller: example.com/ingress-controller + parameters: + # 此 IngressClass 的配置定义在一个名为 “external-config-1” 的 + # ClusterIngressParameter（API 组为 k8s.example.net）资源中。 + # 这项定义告诉 Kubernetes 去寻找一个集群作用域的参数资源。 + scope: Cluster + apiGroup: k8s.example.net + kind: ClusterIngressParameter + name: external-config-1 +``` +{{% /tab %}} +{{% tab name="命名空间作用域" %}} +{{< feature-state for_k8s_version="v1.23" state="stable" >}} -`parameters` 字段有一个 `scope` 和 `namespace` 字段，可用来引用特定 -于名字空间的资源，对 Ingress 类进行配置。 -`scope` 字段默认为 `Cluster`，表示默认是集群作用域的资源。 -将 `scope` 设置为 `Namespace` 并设置 `namespace` 字段就可以引用某特定 -名字空间中的参数资源。 +如果你设置了 `.spec.parameters` 字段且将 `.spec.parameters.scope` +字段设为了 `Namespace`，那么该 IngressClass 将会引用一个命名空间作用域的资源。 +`.spec.parameters.namespace` 必须和此资源所处的命名空间相同。 -有了名字空间域的参数，就不再需要为一个参数资源配置集群范围的 CustomResourceDefinition。 -除此之外，之前对访问集群范围的资源进行授权，需要用到 RBAC 相关的资源，现在也不再需要了。 +参数的 `kind`（和 `apiGroup` +一起）指向一个命名空间作用域的 API（例如：ConfigMap），而它的 +`name` 则确定了一个位于你指定的命名空间中的具体的资源。 -{{< codenew file="service/networking/namespaced-params.yaml" >}} + +命名空间作用域的参数帮助集群操作者将控制细分到用于工作负载的各种配置中（比如：负载均衡设置、API +网关定义）。如果你使用集群作用域的参数，那么你必须从以下两项中选择一项执行： + +- 每次修改配置，集群操作团队需要批准其他团队的修改。 +- 集群操作团队定义具体的准入控制，比如 [RBAC](/zh/docs/reference/access-authn-authz/rbac/) + 角色与角色绑定，以使得应用程序团队可以修改集群作用域的配置参数资源。 + + +IngressClass API 本身是集群作用域的。 + +这里是一个引用命名空间作用域的配置参数的 IngressClass 的示例： +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: IngressClass +metadata: + name: external-lb-2 +spec: + controller: example.com/ingress-controller + parameters: + # 此 IngressClass 的配置定义在一个名为 “external-config” 的 + # IngressParameter（API 组为 k8s.example.com）资源中， + # 该资源位于 “external-configuration” 命名空间中。 + scope: Namespace + apiGroup: k8s.example.com + kind: IngressParameter + namespace: external-configuration + name: external-config +``` + +{{% /tab %}} +{{< /tabs >}} ### 废弃的注解 {#deprecated-annotation} -在 Kubernetes 1.18 版本引入 IngressClass 资源和 `ingressClassName` 字段之前， -Ingress 类是通过 Ingress 中的一个 `kubernetes.io/ingress.class` 注解来指定的。 +在 Kubernetes 1.18 版本引入 IngressClass 资源和 `ingressClassName` 字段之前，Ingress +类是通过 Ingress 中的一个 `kubernetes.io/ingress.class` 注解来指定的。 这个注解从未被正式定义过，但是得到了 Ingress 控制器的广泛支持。 Ingress 中新的 `ingressClassName` 字段是该注解的替代品，但并非完全等价。 -该注解通常用于引用实现该 Ingress 的控制器的名称， -而这个新的字段则是对一个包含额外 Ingress 配置的 IngressClass 资源的引用， -包括 Ingress 控制器的名称。 +该注解通常用于引用实现该 Ingress 的控制器的名称，而这个新的字段则是对一个包含额外 +Ingress 配置的 IngressClass 资源的引用，包括 Ingress 控制器的名称。 +有一些 Ingress 控制器不需要定义默认的 `IngressClass`。比如：Ingress-NGINX +控制器可以通过[参数](https://kubernetes.github.io/ingress-nginx/#what-is-the-flag-watch-ingress-without-class) +`--watch-ingress-without-class` 来配置。 +不过仍然[推荐](https://kubernetes.github.io/ingress-nginx/#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do) +设置默认的 `IngressClass`。 + +{{< codenew file="service/networking/default-ingressclass.yaml" >}} + -例如，以下 Ingress 会将针对 `first.bar.com` 的请求流量路由到 `service1`， -将针对 `second.bar.com` 的请求流量路由到 `service2`， -而针对该 IP 地址的、没有在请求中定义主机名的请求流量会被路由（即，不提供请求标头） -到 `service3`。 +例如，以下 Ingress 会将请求 `first.bar.com` 的流量路由到 `service1`，将请求 +`second.bar.com` 的流量路由到 `service2`，而所有其他流量都会被路由到 `service3`。 {{< codenew file="service/networking/name-virtual-host-ingress-no-third-host.yaml" >}} @@ -710,12 +846,12 @@ and private key to use for TLS. For example: 你可以通过设定包含 TLS 私钥和证书的{{< glossary_tooltip text="Secret" term_id="secret" >}} 来保护 Ingress。 -Ingress 只支持单个 TLS 端口 443，并假定 TLS 连接终止于 Ingress 节点 -（与 Service 及其 Pod 之间的流量都以明文传输）。 -如果 Ingress 中的 TLS 配置部分指定了不同的主机，那么它们将根据通过 SNI TLS 扩展指定的主机名 -（如果 Ingress 控制器支持 SNI）在同一端口上进行复用。 -TLS Secret 必须包含名为 `tls.crt` 和 `tls.key` 的键名。 -这些数据包含用于 TLS 的证书和私钥。例如： +Ingress 只支持单个 TLS 端口 443，并假定 TLS 连接终止于 +Ingress 节点（与 Service 及其 Pod 之间的流量都以明文传输）。 +如果 Ingress 中的 TLS 配置部分指定了不同的主机，那么它们将根据通过 +SNI TLS 扩展指定的主机名（如果 Ingress 控制器支持 SNI）在同一端口上进行复用。 +TLS Secret 的数据中必须包含用于 TLS 的以键名 `tls.crt` 保存的证书和以键名 `tls.key` 保存的私钥。 +例如： ```yaml apiVersion: v1 @@ -724,8 +860,8 @@ metadata: name: testsecret-tls namespace: default data: - tls.crt: base64 编码的 cert - tls.key: base64 编码的 key + tls.crt: base64 编码的证书 + tls.key: base64 编码的私钥 type: kubernetes.io/tls ``` @@ -747,8 +883,7 @@ certificates would have to be issued for all the possible sub-domains. Therefore section. --> 注意，默认规则上无法使用 TLS，因为需要为所有可能的子域名发放证书。 -因此，`tls` 节区的 `hosts` 的取值需要域 `rules` 节区的 `host` -完全匹配。 +因此，`tls` 字段中的 `hosts` 的取值需要与 `rules` 字段中的 `host` 完全匹配。 {{< /note >}} {{< codenew file="service/networking/tls-example-ingress.yaml" >}} @@ -779,8 +914,8 @@ a Service. --> ### 负载均衡 {#load-balancing} -Ingress 控制器启动引导时使用一些适用于所有 Ingress 的负载均衡策略设置， -例如负载均衡算法、后端权重方案和其他等。 +Ingress 控制器启动引导时使用一些适用于所有 Ingress +的负载均衡策略设置，例如负载均衡算法、后端权重方案等。 更高级的负载均衡概念（例如持久会话、动态权重）尚未通过 Ingress 公开。 你可以通过用于服务的负载均衡器来获取这些功能。 @@ -797,10 +932,8 @@ specific documentation to see how they handle health checks ( 中存在并行的概念，比如 [就绪检查](/zh/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)， 允许你实现相同的目的。 -请检查特定控制器的说明文档（ -[nginx](https://git.k8s.io/ingress-nginx/README.md)， -[GCE](https://git.k8s.io/ingress-gce/README.md#health-checks)） -以了解它们是怎样处理健康检查的。 +请检查特定控制器的说明文档（[nginx](https://git.k8s.io/ingress-nginx/README.md)、 +[GCE](https://git.k8s.io/ingress-gce/README.md#health-checks)）以了解它们是怎样处理健康检查的。 -* 进一步了解 [Ingress API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#ingress-v1beta1-networking-k8s-io) +* 进一步了解 [Ingress](/docs/reference/kubernetes-api/service-resources/ingress-v1/) API * 进一步了解 [Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers/) * [使用 NGINX 控制器在 Minikube 上安装 Ingress](/zh/docs/tasks/access-application-cluster/ingress-minikube/) diff --git a/content/zh/docs/concepts/storage/ephemeral-volumes.md b/content/zh/docs/concepts/storage/ephemeral-volumes.md index 10e0015512..a0a2988030 100644 --- a/content/zh/docs/concepts/storage/ephemeral-volumes.md +++ b/content/zh/docs/concepts/storage/ephemeral-volumes.md @@ -33,7 +33,7 @@ services are often limited by memory size and can move infrequently used data into storage that is slower than memory with little impact on overall performance. --> -有些应用程序需要额外的存储，但并不关心数据在重启后仍然可用，既是否被持久地保存。 +有些应用程序需要额外的存储，但并不关心数据在重启后仍然可用。 例如，缓存服务经常受限于内存大小，将不常用的数据转移到比内存慢、但对总体性能的影响很小的存储中。 ### 通用临时卷 {#generic-ephemeral-volumes} -{{< feature-state for_k8s_version="v1.21" state="beta" >}} - - -这个特性需要启用 `GenericEphemeralVolume` -[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)。 -因为这是一个 beta 特性，默认情况下启用。 +{{< feature-state for_k8s_version="v1.23" state="stable" >}} ### 通用临时卷 {#generic-ephemeral-volumes} - 有关设计的更多信息，参阅 [Generic ephemeral inline volumes KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1698-generic-ephemeral-volumes/README.md)。 -- 关于本特性下一步开发的更多信息，参阅 - [enhancement tracking issue #1698](https://github.com/kubernetes/enhancements/issues/1698)。 diff --git a/content/zh/docs/concepts/storage/persistent-volumes.md b/content/zh/docs/concepts/storage/persistent-volumes.md index 34341afd97..fdf9e6ee50 100644 --- a/content/zh/docs/concepts/storage/persistent-volumes.md +++ b/content/zh/docs/concepts/storage/persistent-volumes.md @@ -666,7 +666,7 @@ size that is within the capacity limits of underlying storage provider. You can @@ -810,7 +810,7 @@ Helper programs relating to the volume type may be required for consumption of a @@ -818,9 +818,9 @@ Currently, storage size is the only resource that can be set or requested. Futu 一般而言，每个 PV 卷都有确定的存储容量。 容量属性是使用 PV 对象的 `capacity` 属性来设置的。 -参考 Kubernetes -[资源模型（Resource Model）](https://git.k8s.io/community/contributors/design-proposals/scheduling/resources.md) -设计提案，了解 `capacity` 字段可以接受的单位。 +参考词汇表中的 +[量纲（Quantity）](/zh/docs/reference/glossary/?all=true#term-quantity) +词条，了解 `capacity` 字段可以接受的单位。 目前，存储大小是可以设置和请求的唯一资源。 未来可能会包含 IOPS、吞吐量等属性。 @@ -1038,19 +1038,19 @@ The following volume types support mount options: --> 以下卷类型支持挂载选项： -* AWSElasticBlockStore -* AzureDisk -* AzureFile -* CephFS -* Cinder （OpenStack 块存储） -* GCEPersistentDisk -* Glusterfs -* NFS -* Quobyte 卷 -* RBD （Ceph 块设备） -* StorageOS -* VsphereVolume -* iSCSI +* `awsElasticBlockStore` +* `azureDisk` +* `azureFile` +* `cephfs` +* `cinder` (**已弃用**于 v1.18) +* `gcePersistentDisk` +* `glusterfs` +* `iscsi` +* `nfs` +* `quobyte` (**已弃用**于 v1.22) +* `rbd` +* `storageos` (**已弃用**于 v1.22) +* `vsphereVolume` -Container 中的文件在磁盘上是临时存放的，这给 Container 中运行的较重要的应用 -程序带来一些问题。问题之一是当容器崩溃时文件丢失。kubelet 会重新启动容器， -但容器会以干净的状态重启。 +Container 中的文件在磁盘上是临时存放的，这给 Container 中运行的较重要的应用程序带来一些问题。 +问题之一是当容器崩溃时文件丢失。 +kubelet 会重新启动容器，但容器会以干净的状态重启。 第二个问题会在同一 `Pod` 中运行多个容器并共享文件时出现。 Kubernetes {{< glossary_tooltip text="卷（Volume）" term_id="volume" >}} 这一抽象概念能够解决这两个问题。 阅读本文前建议你熟悉一下 [Pods](/zh/docs/concepts/workloads/pods)。 @@ -59,15 +59,15 @@ Docker 提供卷驱动程序，但是其功能非常有限。 Kubernetes supports many types of volumes. A {{< glossary_tooltip term_id="pod" text="Pod" >}} can use any number of volume types simultaneously. Ephemeral volume types have a lifetime of a pod, but persistent volumes exist beyond -the lifetime of a pod. When a pod ceases to exist, Kubernetes destroys ephemeral volumes; -however, Kubernetes does not destroy persistent volumes. +the lifetime of a pod. When a pod ceases to exist, Kubernetes destroys ephemeral volumes; +however, Kubernetes does not destroy persistent volumes. For any kind of volume in a given pod, data is preserved across container restarts. --> Kubernetes 支持很多类型的卷。 {{< glossary_tooltip term_id="pod" text="Pod" >}} 可以同时使用任意数目的卷类型。 临时卷类型的生命周期与 Pod 相同，但持久卷可以比 Pod 的存活期长。 -当 Pod 不再存在时，Kubernetes 也会销毁临时卷；不过 Kubernetes 不会销毁 -持久卷。对于给定 Pod 中任何类型的卷，在容器重启期间数据都不会丢失。 +当 Pod 不再存在时，Kubernetes 也会销毁临时卷；不过 Kubernetes 不会销毁持久卷。 +对于给定 Pod 中任何类型的卷，在容器重启期间数据都不会丢失。 卷的核心是一个目录，其中可能存有数据，Pod 中的容器可以访问该目录中的数据。 -所采用的特定的卷类型将决定该目录如何形成的、使用何种介质保存数据以及目录中存放 -的内容。 +所采用的特定的卷类型将决定该目录如何形成的、使用何种介质保存数据以及目录中存放的内容。 使用卷时, 在 `.spec.volumes` 字段中设置为 Pod 提供的卷，并在 `.spec.containers[*].volumeMounts` 字段中声明卷在容器中的挂载位置。 -容器中的进程看到的是由它们的 Docker 镜像和卷组成的文件系统视图。 -[Docker 镜像](https://docs.docker.com/userguide/dockerimages/) -位于文件系统层次结构的根部。各个卷则挂载在镜像内的指定路径上。 -卷不能挂载到其他卷之上，也不能与其他卷有硬链接。 +容器中的进程看到的文件系统视图是由它们的 {{< glossary_tooltip text="容器镜像" term_id="image" >}} +的初始内容以及挂载在容器中的卷（如果定义了的话）所组成的。 +其中根文件系统同容器镜像的内容相吻合。 +任何在该文件系统下的写入操作，如果被允许的话，都会影响接下来容器中进程访问文件系统时所看到的内容。 + + +卷挂载在镜像中的[指定路径](#using-subpath)下。 Pod 配置中的每个容器必须独立指定各个卷的挂载位置。 +卷不能挂载到其他卷之上（不过存在一种[使用 subPath](#using-subpath) 的相关机制），也不能与其他卷有硬链接。 + `awsElasticBlockStore` 卷将 Amazon Web服务（AWS）[EBS 卷](https://aws.amazon.com/ebs/) -挂载到你的 Pod 中。与 `emptyDir` 在 Pod 被删除时也被删除不同，EBS 卷的内容在删除 Pod 时 -会被保留，卷只是被卸载掉了。 +挂载到你的 Pod 中。与 `emptyDir` 在 Pod 被删除时也被删除不同，EBS 卷的内容在删除 Pod +时会被保留，卷只是被卸载掉了。 这意味着 EBS 卷可以预先填充数据，并且该数据可以在 Pod 之间共享。 -如果启用了对 `awsElasticBlockStore` 的 `CSIMigration` 特性支持，所有插件操作都 -不再指向树内插件（In-Tree Plugin），转而指向 `ebs.csi.aws.com` 容器存储接口 -（Container Storage Interface，CSI）驱动。为了使用此特性，必须在集群中安装 +如果启用了对 `awsElasticBlockStore` 的 `CSIMigration` +特性支持，所有插件操作都不再指向树内插件（In-Tree Plugin），转而指向 +`ebs.csi.aws.com` 容器存储接口（Container Storage Interface，CSI）驱动。 +为了使用此特性，必须在集群中安装 [AWS EBS CSI 驱动](https://github.com/kubernetes-sigs/aws-ebs-csi-driver)， 并确保 `CSIMigration` 和 `CSIMigrationAWS` Beta 功能特性被启用。 @@ -308,8 +323,9 @@ that data can be shared between Pods. The `cephfs` can be mounted by multiple writers simultaneously. --> `cephfs` 卷允许你将现存的 CephFS 卷挂载到 Pod 中。 -不像 `emptyDir` 那样会在 Pod 被删除的同时也会被删除，`cephfs` 卷的内容在 Pod 被删除 -时会被保留，只是卷被卸载了。这意味着 `cephfs` 卷可以被预先填充数据，且这些数据可以在 +不像 `emptyDir` 那样会在 Pod 被删除的同时也会被删除，`cephfs` +卷的内容在 Pod 被删除时会被保留，只是卷被卸载了。 +这意味着 `cephfs` 卷可以被预先填充数据，且这些数据可以在 Pod 之间共享。同一 `cephfs` 卷可同时被多个写者挂载。 -[`configMap`](/zh/docs/tasks/configure-pod-container/configure-pod-configmap/) 卷 -提供了向 Pod 注入配置数据的方法。 -ConfigMap 对象中存储的数据可以被 `configMap` 类型的卷引用，然后被 Pod 中运行的 -容器化应用使用。 +[`configMap`](/zh/docs/tasks/configure-pod-container/configure-pod-configmap/) +卷提供了向 Pod 注入配置数据的方法。 +ConfigMap 对象中存储的数据可以被 `configMap` 类型的卷引用，然后被 Pod 中运行的容器化应用使用。 -`log-config` ConfigMap 以卷的形式挂载，并且存储在 `log_level` 条目中的所有内容 -都被挂载到 Pod 的 `/etc/config/log_level` 路径下。 +`log-config` ConfigMap 以卷的形式挂载，并且存储在 `log_level` +条目中的所有内容都被挂载到 Pod 的 `/etc/config/log_level` 路径下。 请注意，这个路径来源于卷的 `mountPath` 和 `log_level` 键对应的 `path`。 {{< note >}} -当启用 `SizeMemoryBackedVolumes` [特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)时， -你可以为基于内存提供的卷指定大小。 +当启用 `SizeMemoryBackedVolumes` [特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/) +时，你可以为基于内存提供的卷指定大小。 如果未指定大小，则基于内存的卷的大小为 Linux 主机上内存的 50％。 {{< /note>}} @@ -589,8 +604,8 @@ targetWWNs expect that those WWNs are from multi-path connections. You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them. --> {{< note >}} -你必须配置 FC SAN Zoning，以便预先向目标 WWN 分配和屏蔽这些 LUN（卷）， -这样 Kubernetes 主机才可以访问它们。 +你必须配置 FC SAN Zoning，以便预先向目标 WWN 分配和屏蔽这些 LUN（卷），这样 +Kubernetes 主机才可以访问它们。 {{< /note >}} -[区域持久盘](https://cloud.google.com/compute/docs/disks/#repds) 功能允许你创建能在 -同一区域的两个可用区中使用的持久盘。 -要使用这个功能，必须以持久卷（PersistentVolume）的方式提供卷；直接从 Pod 引用这种卷 -是不可以的。 +[区域持久盘](https://cloud.google.com/compute/docs/disks/#repds) +功能允许你创建能在同一区域的两个可用区中使用的持久盘。 +要使用这个功能，必须以持久卷（PersistentVolume）的方式提供卷；直接从 +Pod 引用这种卷是不可以的。 #### 手动供应基于区域 PD 的 PersistentVolume {#manually-provisioning-regional-pd-pv} -使用[为 GCE PD 定义的存储类](/zh/docs/concepts/storage/storage-classes/#gce) 可以 -实现动态供应。在创建 PersistentVolume 之前，你首先要创建 PD。 +使用[为 GCE PD 定义的存储类](/zh/docs/concepts/storage/storage-classes/#gce) +可以实现动态供应。在创建 PersistentVolume 之前，你首先要创建 PD。 ```shell gcloud beta compute disks create --size=500GB my-data-disk @@ -824,8 +839,8 @@ and the kubelet, set the `InTreePluginGCEUnregister` flag to `true`. {{< feature-state for_k8s_version="v1.21" state="alpha" >}} -要禁止控制器管理器和 kubelet 加载 `gcePersistentDisk` 存储插件， -请将 `InTreePluginGCEUnregister` 标志设置为 `true`。 +要禁止控制器管理器和 kubelet 加载 `gcePersistentDisk` 存储插件，请将 +`InTreePluginGCEUnregister` 标志设置为 `true`。 {{< warning >}} `gitRepo` 卷类型已经被废弃。如果需要在容器中提供 git 仓库，请将一个 -[EmptyDir](#emptydir) 卷挂载到 InitContainer 中，使用 git 命令完成仓库的克隆操作， -然后将 [EmptyDir](#emptydir) 卷挂载到 Pod 的容器中。 +[EmptyDir](#emptydir) 卷挂载到 InitContainer 中，使用 git +命令完成仓库的克隆操作，然后将 [EmptyDir](#emptydir) 卷挂载到 Pod 的容器中。 {{< /warning >}} 当使用这种类型的卷时要小心，因为： -* HostPath 卷可能会暴露特权系统凭据（例如 Kubelet）或特权 API（例如容器运行时套接字）， - 可用于容器逃逸或攻击集群的其他部分。 -* 具有相同配置（例如基于同一 PodTemplate 创建）的多个 Pod 会由于节点上文件的不同 - 而在不同节点上有不同的行为。 +* HostPath 卷可能会暴露特权系统凭据（例如 Kubelet）或特权 + API（例如容器运行时套接字），可用于容器逃逸或攻击集群的其他部分。 +* 具有相同配置（例如基于同一 PodTemplate 创建）的多个 Pod + 会由于节点上文件的不同而在不同节点上有不同的行为。 * 下层主机上创建的文件或目录只能由 root 用户写入。你需要在 [特权容器](/zh/docs/tasks/configure-pod-container/security-context/) 中以 root 身份运行进程，或者修改主机上的文件权限以便容器能够写入 `hostPath` 卷。 @@ -1078,8 +1093,8 @@ unmounted. This means that an iscsi volume can be pre-populated with data, and that data can be shared between pods. --> `iscsi` 卷能将 iSCSI (基于 IP 的 SCSI) 卷挂载到你的 Pod 中。 -不像 `emptyDir` 那样会在删除 Pod 的同时也会被删除，`iscsi` 卷的内容在删除 Pod 时 -会被保留，卷只是被卸载。 +不像 `emptyDir` 那样会在删除 Pod 的同时也会被删除，`iscsi` +卷的内容在删除 Pod 时会被保留，卷只是被卸载。 这意味着 `iscsi` 卷可以被预先填充数据，并且这些数据可以在 Pod 之间共享。 然而，`local` 卷仍然取决于底层节点的可用性，并不适合所有应用程序。 -如果节点变得不健康，那么`local` 卷也将变得不可被 Pod 访问。使用它的 Pod 将不能运行。 -使用 `local` 卷的应用程序必须能够容忍这种可用性的降低，以及因底层磁盘的耐用性特征 -而带来的潜在的数据丢失风险。 +如果节点变得不健康，那么 `local` 卷也将变得不可被 Pod 访问。使用它的 Pod 将不能运行。 +使用 `local` 卷的应用程序必须能够容忍这种可用性的降低，以及因底层磁盘的耐用性特征而带来的潜在的数据丢失风险。 下面是一个使用 `local` 卷和 `nodeAffinity` 的持久卷示例： @@ -1198,9 +1212,8 @@ such as node resource requirements, node selectors, Pod affinity, and Pod anti-a 使用 `local` 卷时，建议创建一个 StorageClass 并将其 `volumeBindingMode` 设置为 `WaitForFirstConsumer`。要了解更多详细信息，请参考 [local StorageClass 示例](/zh/docs/concepts/storage/storage-classes/#local)。 -延迟卷绑定的操作可以确保 Kubernetes 在为 PersistentVolumeClaim 作出绑定决策时， -会评估 Pod 可能具有的其他节点约束，例如：如节点资源需求、节点选择器、Pod -亲和性和 Pod 反亲和性。 +延迟卷绑定的操作可以确保 Kubernetes 在为 PersistentVolumeClaim 作出绑定决策时，会评估 +Pod 可能具有的其他节点约束，例如：如节点资源需求、节点选择器、Pod亲和性和 Pod 反亲和性。 -`persistentVolumeClaim` 卷用来将[持久卷](/zh/docs/concepts/storage/persistent-volumes/)（PersistentVolume） -挂载到 Pod 中。 -持久卷申领（PersistentVolumeClaim）是用户在不知道特定云环境细节的情况下"申领"持久存储 -（例如 GCE PersistentDisk 或者 iSCSI 卷）的一种方法。 +`persistentVolumeClaim` 卷用来将[持久卷](/zh/docs/concepts/storage/persistent-volumes/)（PersistentVolume）挂载到 Pod 中。 +持久卷申领（PersistentVolumeClaim）是用户在不知道特定云环境细节的情况下“申领”持久存储（例如 +GCE PersistentDisk 或者 iSCSI 卷）的一种方法。 `portworxVolume` 是一个可伸缩的块存储层，能够以超融合（hyperconverged）的方式与 Kubernetes 一起运行。 -[Portworx](https://portworx.com/use-case/kubernetes-storage/) 支持对服务器上存储的指纹处理、 -基于存储能力进行分层以及跨多个服务器整合存储容量。 +[Portworx](https://portworx.com/use-case/kubernetes-storage/) +支持对服务器上存储的指纹处理、基于存储能力进行分层以及跨多个服务器整合存储容量。 Portworx 可以以 in-guest 方式在虚拟机中运行，也可以在裸金属 Linux 节点上运行。 -`projected` 卷类型能将若干现有的卷来源映射到同一目录上。 - -目前，可以映射的卷来源类型如下： - -- [`secret`](#secret) -- [`downwardAPI`](#downwardapi) -- [`configMap`](#configmap) -- `serviceAccountToken` - - -所有的卷来源需要和 Pod 处于相同的命名空间。 -更多详情请参考[一体化卷设计文档](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/all-in-one-volume.md)。 - - - -#### 包含 Secret、downwardAPI 和 configMap 的 Pod 示例 {#example-configuration-secret-downwardapi-configmap} - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - sources: - - secret: - name: mysecret - items: - - key: username - path: my-group/my-username - - downwardAPI: - items: - - path: "labels" - fieldRef: - fieldPath: metadata.labels - - path: "cpu_limit" - resourceFieldRef: - containerName: container-test - resource: limits.cpu - - configMap: - name: myconfigmap - items: - - key: config - path: my-group/my-config -``` - - - -下面是一个带有非默认访问权限设置的多个 secret 的 Pod 示例： - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - sources: - - secret: - name: mysecret - items: - - key: username - path: my-group/my-username - - secret: - name: mysecret2 - items: - - key: password - path: my-group/my-password - mode: 511 -``` - -每个被投射的卷来源都在规约中的 `sources` 内列出。参数几乎相同，除了两处例外： - -* 对于 `secret`，`secretName` 字段已被变更为 `name` 以便与 ConfigMap 命名一致。 -* `defaultMode` 只能在整个投射卷级别指定，而无法针对每个卷来源指定。 - 不过，如上所述，你可以显式地为每个投射项设置 `mode` 值。 - - - -当开启 `TokenRequestProjection` 功能时，可以将当前 -[服务帐号](/zh/docs/reference/access-authn-authz/authentication/#service-account-tokens) -的令牌注入 Pod 中的指定路径。 -下面是一个例子： - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: sa-token-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: token-vol - mountPath: "/service-account" - readOnly: true - volumes: - - name: token-vol - projected: - sources: - - serviceAccountToken: - audience: api - expirationSeconds: 3600 - path: token -``` - - -示例 Pod 具有包含注入服务帐户令牌的映射卷。 -该令牌可以被 Pod 中的容器用来访问 Kubernetes API 服务器。 -`audience` 字段包含令牌的预期受众。 -令牌的接收者必须使用令牌的受众中指定的标识符来标识自己，否则应拒绝令牌。 -此字段是可选的，默认值是 API 服务器的标识符。 - - -`expirationSeconds` 是服务帐户令牌的有效期时长。 -默认值为 1 小时，必须至少 10 分钟（600 秒）。 -管理员还可以通过设置 API 服务器的 `--service-account-max-token-expiration` 选项来 -限制其最大值。 -`path` 字段指定相对于映射卷的挂载点的相对路径。 - -{{< note >}} - -使用投射卷源作为 [subPath](#using-subpath) 卷挂载的容器将不会接收这些卷源的更新。 -{{< /note >}} +投射卷能将若干现有的卷来源映射到同一目录上。更多详情请参考[投射卷](/zh/docs/concepts/storage/projected-volumes/)。 ### quobyte (已弃用) {#quobyte} @@ -1542,32 +1375,32 @@ Quobyte 的 GitHub 项目包含以 CSI 形式部署 Quobyte 的 -`rbd` 卷允许将 [Rados 块设备](https://docs.ceph.com/en/latest/rbd/) 卷挂载到你的 Pod 中. -不像 `emptyDir` 那样会在删除 Pod 的同时也会被删除，`rbd` 卷的内容在删除 Pod 时 -会被保存，卷只是被卸载。 +`rbd` 卷允许将 [Rados 块设备](https://docs.ceph.com/en/latest/rbd/)卷挂载到你的 Pod 中。 +不像 `emptyDir` 那样会在删除 Pod 的同时也会被删除，`rbd` 卷的内容在删除 Pod 时会被保存，卷只是被卸载。 这意味着 `rbd` 卷可以被预先填充数据，并且这些数据可以在 Pod 之间共享。 -{{< caution >}} +{{< note >}} 在使用 RBD 之前，你必须安装运行 Ceph。 -{{< /caution >}} +{{< /note >}} RBD 的一个特性是它可以同时被多个用户以只读方式挂载。 这意味着你可以用数据集预先填充卷，然后根据需要在尽可能多的 Pod 中并行地使用卷。 @@ -1576,6 +1409,59 @@ RBD 的一个特性是它可以同时被多个用户以只读方式挂载。 更多详情请参考 [RBD 示例](https://github.com/kubernetes/examples/tree/master/volumes/rbd)。 + +#### RBD CSI 迁移 {#rbd-csi-migration} + +{{< feature-state for_k8s_version="v1.23" state="alpha" >}} + + +启用 RBD 的 `CSIMigration` 功能后，所有插件操作从现有的树内插件重定向到 +`rbd.csi.ceph.com` {{}} 驱动程序。 +要使用该功能，必须在集群内安装 +[Ceph CSI 驱动](https://github.com/ceph/ceph-csi)，并启用 `CSIMigration` 和 `csiMigrationRBD` +[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)。 + + +{{< note >}} +作为一位管理存储的 Kubernetes 集群操作者，在尝试迁移到 RBD CSI 驱动前，你必须完成下列先决事项： + +* 你必须在集群中安装 v3.5.0 或更高版本的 Ceph CSI 驱动（`rbd.csi.ceph.com`）。 +* 因为 `clusterID` 是 CSI 驱动程序必需的参数，而树内存储类又将 `monitors` + 作为一个必需的参数，所以 Kubernetes 存储管理者需要根据 `monitors` + 的哈希值（例：`#echo -n '' | md5sum`）来创建 + `clusterID`，并保持该 `monitors` 存在于该 `clusterID` 的配置中。 +* 同时，如果树内存储类的 `adminId` 的值不是 `admin`，那么其 `adminSecretName` + 就需要被修改成 `adminId` 参数的 base64 编码值。 +{{< /note >}} + ### secret `secret` 卷用来给 Pod 传递敏感信息，例如密码。你可以将 Secret 存储在 Kubernetes API 服务器上，然后以文件的形式挂在到 Pod 中，无需直接与 Kubernetes 耦合。 -`secret` 卷由 tmpfs（基于 RAM 的文件系统）提供存储，因此它们永远不会被写入非易失性 -（持久化的）存储器。 +`secret` 卷由 tmpfs（基于 RAM 的文件系统）提供存储，因此它们永远不会被写入非易失性（持久化的）存储器。 +#### Portworx CSI 迁移 + +{{< feature-state for_k8s_version="v1.23" state="alpha" >}} + + +Kubernetes 1.23 中加入了 Portworx 的 `CSIMigration` 功能，但默认不会启用，因为该功能仍处于 alpha 阶段。 +该功能会将所有的插件操作从现有的树内插件重定向到 +`pxd.portworx.com` 容器存储接口（Container Storage Interface, CSI）驱动程序。 +集群中必须安装 +[Portworx CSI 驱动](https://docs.portworx.com/portworx-install-with-kubernetes/storage-operations/csi/)。 +要启用此功能，请在 kube-controller-manager 和 kubelet 中设置 `CSIMigrationPortworx=true`。 + -## 使用 subPath {#using-path} +## 使用 subPath {#using-subpath} 有时，在单个 Pod 中共享卷以供多方使用是很有用的。 `volumeMounts.subPath` 属性可用于指定所引用的卷内的子路径，而不是其根路径。 @@ -1934,6 +1841,7 @@ spec: volumeMounts: - name: workdir1 mountPath: /logs + # 包裹变量名的是小括号，而不是大括号 subPathExpr: $(POD_NAME) restartPolicy: Never volumes: @@ -1953,10 +1861,9 @@ Pods. --> ## 资源 {#resources} -`emptyDir` 卷的存储介质（磁盘、SSD 等）是由保存 kubelet 数据的根目录 -（通常是 `/var/lib/kubelet`）的文件系统的介质确定。 -Kubernetes 对 `emptyDir` 卷或者 `hostPath` 卷可以消耗的空间没有限制， -容器之间或 Pod 之间也没有隔离。 +`emptyDir` 卷的存储介质（磁盘、SSD 等）是由保存 kubelet +数据的根目录（通常是 `/var/lib/kubelet`）的文件系统的介质确定。 +Kubernetes 对 `emptyDir` 卷或者 `hostPath` 卷可以消耗的空间没有限制，容器之间或 Pod 之间也没有隔离。 ## 树外（Out-of-Tree）卷插件 {#out-of-tree-volume-plugins} Out-of-Tree 卷插件包括 -{{< glossary_tooltip text="容器存储接口（CSI）" term_id="csi" >}} (CSI) -和 FlexVolume。 -它们使存储供应商能够创建自定义存储插件，而无需将它们添加到 Kubernetes 代码仓库。 +{{< glossary_tooltip text="容器存储接口（CSI）" term_id="csi" >}} +和 FlexVolume（已弃用）。 +它们使存储供应商能够创建自定义存储插件，而无需将插件源码添加到 Kubernetes 代码仓库。 -CSI 和 FlexVolume 都允许独立于 Kubernetes 代码库开发卷插件，并作为扩展部署 -（安装）在 Kubernetes 集群上。 +CSI 和 FlexVolume 都允许独立于 Kubernetes 代码库开发卷插件，并作为扩展部署（安装）在 Kubernetes 集群上。 对于希望创建树外（Out-Of-Tree）卷插件的存储供应商，请参考 [卷插件常见问题](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md)。 @@ -2053,8 +1958,8 @@ A `csi` volume can be used in a Pod in three different ways: * with a [CSI ephemeral volume](/docs/concepts/storage/ephemeral-volumes/#csi-ephemeral-volume) if the driver supports that (beta feature) --> -一旦在 Kubernetes 集群上部署了 CSI 兼容卷驱动程序，用户就可以使用 `csi` 卷类型来 -挂接、挂载 CSI 驱动所提供的卷。 +一旦在 Kubernetes 集群上部署了 CSI 兼容卷驱动程序，用户就可以使用 +`csi` 卷类型来挂接、挂载 CSI 驱动所提供的卷。 `csi` 卷可以在 Pod 中以三种方式使用： @@ -2078,10 +1983,10 @@ persistent volume: CSI driver components to identify which PV objects belong to the CSI driver. --> - `driver`：指定要使用的卷驱动名称的字符串值。 - 这个值必须与 CSI 驱动程序在 `GetPluginInfoResponse` 中返回的值相对应； - 该接口定义在 [CSI 规范](https://github.com/container-storage-interface/spec/blob/master/spec.md#getplugininfo)中。 - Kubernetes 使用所给的值来标识要调用的 CSI 驱动程序；CSI 驱动程序也使用该值来辨识 - 哪些 PV 对象属于该 CSI 驱动程序。 + 这个值必须与 CSI 驱动程序在 `GetPluginInfoResponse` 中返回的值相对应；该接口定义在 + [CSI 规范](https://github.com/container-storage-interface/spec/blob/master/spec.md#getplugininfo)中。 + Kubernetes 使用所给的值来标识要调用的 CSI 驱动程序；CSI + 驱动程序也使用该值来辨识哪些 PV 对象属于该 CSI 驱动程序。 - `volumeHandle`：唯一标识卷的字符串值。 - 该值必须与 CSI 驱动在 `CreateVolumeResponse` 的 `volume_id` 字段中返回的值相对应； - 接口定义在 [CSI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume) 中。 + 该值必须与 CSI 驱动在 `CreateVolumeResponse` 的 `volume_id` 字段中返回的值相对应；接口定义在 + [CSI 规范](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume) 中。 在所有对 CSI 卷驱动程序的调用中，引用该 CSI 卷时都使用此值作为 `volume_id` 参数。 -- `readOnly`：一个可选的布尔值，指示通过 `ControllerPublished` 关联该卷时是否设置 - 该卷为只读。默认值是 false。 +- `readOnly`：一个可选的布尔值，指示通过 `ControllerPublished` 关联该卷时是否设置该卷为只读。默认值是 false。 该值通过 `ControllerPublishVolumeRequest` 中的 `readonly` 字段传递给 CSI 驱动。 -启用 `CSIMigration` 功能后，针对现有树内插件的操作会被重定向到相应的 CSI 插件 -（应已安装和配置）。 -因此，操作员在过渡到取代树内插件的 CSI 驱动时，无需对现有存储类、PV 或 PVC -（指树内插件）进行任何配置更改。 +启用 `CSIMigration` 功能后，针对现有树内插件的操作会被重定向到相应的 CSI 插件（应已安装和配置）。 +因此，操作员在过渡到取代树内插件的 CSI 驱动时，无需对现有存储类、PV 或 PVC（指树内插件）进行任何配置更改。 所支持的操作和功能包括：配备（Provisioning）/删除、挂接（Attach）/解挂（Detach）、 挂载（Mount）/卸载（Unmount）和调整卷大小。 @@ -2252,22 +2155,35 @@ are listed in [Types of Volumes](#volume-types). ### flexVolume +{{< feature-state for_k8s_version="v1.23" state="deprecated" >}} + -FlexVolume 是一个自 1.2 版本（在 CSI 之前）以来在 Kubernetes 中一直存在的树外插件接口。 -它使用基于 exec 的模型来与驱动程序对接。 -用户必须在每个节点（在某些情况下是主控节点）上的预定义卷插件路径中安装 -FlexVolume 驱动程序可执行文件。 +FlexVolume 是一个使用基于 exec 的模型来与驱动程序对接的树外插件接口。 +用户必须在每个节点上的预定义卷插件路径中安装 FlexVolume +驱动程序可执行文件，在某些情况下，控制平面节点中也要安装。 -Pod 通过 `flexvolume` 树内插件与 Flexvolume 驱动程序交互。 -更多详情请参考 [FlexVolume](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-storage/flexvolume.md) 示例。 +Pod 通过 `flexvolume` 树内插件与 FlexVolume 驱动程序交互。 +更多详情请参考 FlexVolume [README](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-storage/flexvolume.md#readme) 文档。 + + +{{< note >}} +FlexVolume 已弃用。推荐使用树外 CSI 驱动来将外部存储整合进 Kubernetes。 + +FlexVolume 驱动的维护者应开发一个 CSI 驱动并帮助用户从 FlexVolume 驱动迁移到 CSI。 +FlexVolume 用户应迁移工作负载以使用对等的 CSI 驱动。 +{{< /note >}} ## 挂载卷的传播 {#mount-propagation} -挂载卷的传播能力允许将容器安装的卷共享到同一 Pod 中的其他容器， -甚至共享到同一节点上的其他 Pod。 +挂载卷的传播能力允许将容器安装的卷共享到同一 Pod 中的其他容器，甚至共享到同一节点上的其他 Pod。 卷的挂载传播特性由 `Container.volumeMounts` 中的 `mountPropagation` 字段控制。 它的值包括： @@ -2320,8 +2235,8 @@ Its values are: 换句话说，如果主机在此挂载卷中挂载任何内容，容器将能看到它被挂载在那里。 - 类似的，配置了 `Bidirectional` 挂载传播选项的 Pod 如果在同一卷上挂载了内容， - 挂载传播设置为 `HostToContainer` 的容器都将能看到这一变化。 + 类似的，配置了 `Bidirectional` 挂载传播选项的 Pod 如果在同一卷上挂载了内容，挂载传播设置为 + `HostToContainer` 的容器都将能看到这一变化。 该模式等同于 [Linux 内核文档](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) 中描述的 `rslave` 挂载传播选项。 @@ -2366,8 +2281,7 @@ Docker as shown below. --> ### 配置 {#configuration} -在某些部署环境中，挂载传播正常工作前，必须在 Docker 中正确配置挂载共享（mount share）， -如下所示。 +在某些部署环境中，挂载传播正常工作前，必须在 Docker 中正确配置挂载共享（mount share），如下所示。 ## ReplicaSet 的工作原理 {#how-a-replicaset-works} -RepicaSet 是通过一组字段来定义的，包括一个用来识别可获得的 Pod +ReplicaSet 是通过一组字段来定义的，包括一个用来识别可获得的 Pod 的集合的选择算符、一个用来标明应该维护的副本个数的数值、一个用来指定应该创建新 Pod 以满足副本个数条件时要使用的 Pod 模板等等。 每个 ReplicaSet 都通过根据需要创建和 删除 Pod 以使得副本个数达到期望值， diff --git a/content/zh/docs/concepts/workloads/controllers/replicationcontroller.md b/content/zh/docs/concepts/workloads/controllers/replicationcontroller.md index 285215a3b2..dbadd4f88d 100644 --- a/content/zh/docs/concepts/workloads/controllers/replicationcontroller.md +++ b/content/zh/docs/concepts/workloads/controllers/replicationcontroller.md @@ -331,7 +331,7 @@ kubectl 将 ReplicationController 缩放为 0 并等待以便在删除 Replicati You can delete a ReplicationController without affecting any of its pods. -Using kubectl, specify the `--cascade=false` option to [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete). +Using kubectl, specify the `--cascade=orphan` option to [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete). When using the REST API or Go client library, simply delete the ReplicationController object. --> @@ -339,7 +339,7 @@ When using the REST API or Go client library, simply delete the ReplicationContr 你可以删除一个 ReplicationController 而不影响它的任何 Pod。 -使用 kubectl，为 [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete) 指定 `--cascade=false` 选项。 +使用 kubectl，为 [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands#delete) 指定 `--cascade=orphan` 选项。 当使用 REST API 或 Go 客户端库时，只需删除 ReplicationController 对象。 @@ -501,12 +501,12 @@ ReplicationController 永远被限制在这个狭隘的职责范围内。 我们甚至计划考虑批量创建 Pod 的机制（查阅 [#170](https://issue.k8s.io/170)）。 ReplicationController 旨在成为可组合的构建基元。 我们希望在它和其他补充原语的基础上构建更高级别的 API 或者工具，以便于将来的用户使用。 kubectl 目前支持的 "macro" 操作（运行、缩放、滚动更新）就是这方面的概念示例。 -例如，我们可以想象类似于 [Asgard](https://techblog.netflix.com/2012/06/asgaard-web-based-cloud-management-and.html) +例如，我们可以想象类似于 [Asgard](https://netflixtechblog.com/asgard-web-based-cloud-management-and-deployment-2c9fc4e4d3a1) 的东西管理 ReplicationController、自动定标器、服务、调度策略、金丝雀发布等。 ### Deployment （推荐） -[`Deployment`](/zh/docs/concepts/workloads/controllers/deployment/) 是一种更高级别的 API 对象， -它以类似于 `kubectl rolling-update` 的方式更新其底层 ReplicaSet 及其 Pod。 -如果你想要这种滚动更新功能，那么推荐使用 Deployment，因为与 `kubectl rolling-update` 不同， -它们是声明式的、服务端的，并且具有其它特性。 +[`Deployment`](/zh/docs/concepts/workloads/controllers/deployment/) 是一种更高级别的 API 对象，用于更新其底层 ReplicaSet 及其 Pod。 +如果你想要这种滚动更新功能，那么推荐使用 Deployment，因为它们是声明式的、服务端的，并且具有其它特性。 -## 更多信息 +## {{% heading "whatsnext" %}} -请阅读[运行无状态的 ReplicationController](/zh/docs/tasks/run-application/run-stateless-application-deployment/)。 +- 了解 [Pods](/zh/docs/concepts/workloads/pods)。 +- 了解 [Depolyment](/zh/docs/concepts/workloads/controllers/deployment/)，ReplicationController 的替代品。 +- `ReplicationController` 是 Kubernetes REST API 的一部分，阅读 {{< api-reference page="workload-resources/replication-controller-v1" >}} + 对象定义以了解 replication controllers 的 API。 diff --git a/content/zh/docs/concepts/workloads/controllers/ttlafterfinished.md b/content/zh/docs/concepts/workloads/controllers/ttlafterfinished.md index 291b88e0d7..0d02b7a04b 100644 --- a/content/zh/docs/concepts/workloads/controllers/ttlafterfinished.md +++ b/content/zh/docs/concepts/workloads/controllers/ttlafterfinished.md @@ -1,65 +1,54 @@ --- -title: 已完成资源的 TTL 控制器 +title: 已完成 Job 的自动清理 content_type: concept weight: 70 --- -{{< feature-state for_k8s_version="v1.21" state="beta" >}} +{{< feature-state for_k8s_version="v1.23" state="stable" >}} -TTL 控制器提供了一种 TTL 机制来限制已完成执行的资源对象的生命周期。 -TTL 控制器目前只处理 {{< glossary_tooltip text="Job" term_id="job" >}}， -可能以后会扩展以处理将完成执行的其他资源，例如 Pod 和自定义资源。 +TTL-after-finished {{}} 提供了一种 TTL 机制来限制已完成执行的资源对象的生命周期。 +TTL 控制器目前只处理 {{< glossary_tooltip text="Job" term_id="job" >}}。 - -此功能目前是 Beta 版而自动启用，并且可以通过 `kube-apiserver` 和 -`kube-controller-manager` 上的 -[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/) -`TTLAfterFinished` 禁用。 -## TTL 控制器 +## TTL-after-finished 控制器 -TTL 控制器现在只支持 Job。集群操作员可以通过指定 Job 的 `.spec.ttlSecondsAfterFinished` +TTL-after-finished 控制器只支持 Job。集群操作员可以通过指定 Job 的 `.spec.ttlSecondsAfterFinished` 字段来自动清理已结束的作业（`Complete` 或 `Failed`），如 [示例](/zh/docs/concepts/workloads/controllers/job/#clean-up-finished-jobs-automatically) 所示。 -TTL 控制器假设资源能在执行完成后的 TTL 秒内被清理，也就是当 TTL 过期后。 -当 TTL 控制器清理资源时，它将做级联删除操作，即删除资源对象的同时也删除其依赖对象。 +TTL-after-finished 控制器假设作业能在执行完成后的 TTL 秒内被清理，也就是当 TTL 过期后。 +当 TTL 控制器清理作业时，它将做级联删除操作，即删除资源对象的同时也删除其依赖对象。 注意，当资源被删除时，由该资源的生命周期保证其终结器（Finalizers）等被执行。 -* 在资源清单（manifest）中指定此字段，以便 Job 在完成后的某个时间被自动清除。 -* 将此字段设置为现有的、已完成的资源，以采用此新功能。 -* 在创建资源时使用 [mutating admission webhook](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) - 动态设置该字段。集群管理员可以使用它对完成的资源强制执行 TTL 策略。 +* 在作业清单（manifest）中指定此字段，以便 Job 在完成后的某个时间被自动清除。 +* 将此字段设置为现有的、已完成的作业，以采用此新功能。 +* 在创建作业时使用 [mutating admission webhook](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) + 动态设置该字段。集群管理员可以使用它对完成的作业强制执行 TTL 策略。 * 使用 [mutating admission webhook](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) - 在资源完成后动态设置该字段，并根据资源状态、标签等选择不同的 TTL 值。 + 在作业完成后动态设置该字段，并根据作业状态、标签等选择不同的 TTL 值。 ## 警告 -### 更新 TTL 秒 +### 更新 TTL 秒数 -请注意，在创建资源或已经执行结束后，仍可以修改其 TTL 周期，例如 Job 的 +请注意，在创建 Job 或已经执行结束后，仍可以修改其 TTL 周期，例如 Job 的 `.spec.ttlSecondsAfterFinished` 字段。 但是一旦 Job 变为可被删除状态（当其 TTL 已过期时），即使您通过 API 增加其 TTL 时长得到了成功的响应，系统也不保证 Job 将被保留。 @@ -111,25 +100,21 @@ returns a successful API response. ### 时间偏差 {#time-skew} -由于 TTL 控制器使用存储在 Kubernetes 资源中的时间戳来确定 TTL 是否已过期， -因此该功能对集群中的时间偏差很敏感，这可能导致 TTL 控制器在错误的时间清理资源对象。 +由于 TTL-after-finished 控制器使用存储在 Kubernetes 资源中的时间戳来确定 TTL 是否已过期， +因此该功能对集群中的时间偏差很敏感，这可能导致 TTL-after-finished 控制器在错误的时间清理资源对象。 -在 Kubernetes 中，需要在所有节点上运行 NTP（参见 -[#6159](https://github.com/kubernetes/kubernetes/issues/6159#issuecomment-93844058)） -以避免时间偏差。时钟并不总是如此正确，但差异应该很小。 +时钟并不总是如此正确，但差异应该很小。 设置非零 TTL 时请注意避免这种风险。 ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/contribute/advanced.md b/content/zh/docs/contribute/advanced.md index 3a69c1f97f..5fe6df4098 100644 --- a/content/zh/docs/contribute/advanced.md +++ b/content/zh/docs/contribute/advanced.md @@ -44,7 +44,7 @@ the documentation, the website style, the processes for reviewing and merging pull requests, or other aspects of the documentation. For maximum transparency, these types of proposals need to be discussed in a SIG Docs meeting or on the [kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). -In addition, it can really help to have some context about the way things +In addition, it can help to have some context about the way things currently work and why past decisions have been made before proposing sweeping changes. The quickest way to get answers to questions about how the documentation currently works is to ask in the `#sig-docs` Slack channel on @@ -55,7 +55,7 @@ currently works is to ask in the `#sig-docs` Slack channel on 评审和合并 PR 的流程或者文档的其他方面产生改进的想法。 为了尽可能透明化，这些提议都需要在 SIG Docs 会议或 [kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)上讨论。 -此外，在提出全面的改进之前，这些讨论能真正帮助我们了解有关“当前工作如何运作”和“以往的决定是为何做出”的背景。 +此外，在提出全面的改进之前，这些讨论能帮助我们了解有关“当前工作如何运作”和“以往的决定是为何做出”的背景。 想了解文档的当前运作方式，最快的途径是咨询 [kubernetes.slack.com](https://kubernetes.slack.com) 中的 `#sig-docs` 聊天群组。 @@ -96,7 +96,7 @@ refer to The SIG Docs representative for a given release coordinates the following tasks: - Monitor the feature-tracking spreadsheet for new or changed features with an - impact on documentation. If documentation for a given feature won't be ready + impact on documentation. If the documentation for a given feature won't be ready for the release, the feature may not be allowed to go into the release. - Attend sig-release meetings regularly and give updates on the status of the docs for the release. @@ -151,19 +151,21 @@ SIG Docs [批准人（Approvers）](/zh/docs/contribute/participating/#approvers - 监听 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com) 上新贡献者的 Issue。 -- 与 PR 管理者合作为新参与者寻找合适的第一个 issues。 +- 与 PR 管理者合作为新参与者寻找[合适的第一个 issues](https://kubernetes.dev/docs/guide/help-wanted/#good-first-issue) 。 - 通过前几个 PR 指导新贡献者为文档存储库作贡献。 - 帮助新的贡献者创建成为 Kubernetes 成员所需的更复杂的 PR。 - [为贡献者提供保荐](#sponsor-a-new-contributor)，使其成为 Kubernetes 成员。 +- 每月召开一次会议，帮助和指导新的贡献者。 当前新贡献者大使将在每次 SIG 文档会议上以及 [Kubernetes #sig-docs 频道](https://kubernetes.slack.com)中宣布。 @@ -205,37 +207,37 @@ membership in the Kubernetes organization. ## 担任 SIG 联合主席 -SIG Docs [批准人（Approvers）](/zh/docs/contribute/participate/roles-and-responsibilities/#approvers) +SIG Docs [成员（Members）](/zh/docs/contribute/participate/roles-and-responsibilities/#members) 可以担任 SIG Docs 的联合主席。 ### 前提条件 -Approvers 必须满足以下要求才能成为联合主席： +Kubernetes 成员必须满足以下要求才能成为联合主席： -- 已维持 SIG Docs approver 身份至少 6 个月 -- [曾领导 Kubernetes 文档发布](/zh/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) - 或者在两个版本发布中有实习经历 - 理解 SIG Docs 工作流程和工具：git、Hugo、本地化、博客子项目 - 理解其他 Kubernetes SIG 和仓库会如何影响 SIG Docs 工作流程，包括： [k/org 中的团队](https://github.com/kubernetes/org/blob/master/config/kubernetes/sig-docs/teams.yaml)、 [k/community 中的流程](https://github.com/kubernetes/community/tree/master/sig-docs)、 [k/test-infra](https://github.com/kubernetes/test-infra/) 中的插件、 [SIG Architecture](https://github.com/kubernetes/community/tree/master/sig-architecture) 中的角色。 + 此外，了解 [Kubernetes 文档发布流程](/docs/contribute/advanced/#coordinate-docs-for-a-kubernetes-release) 的工作原理。 +- 由 SIG Docs 社区直接或通过惰性共识批准。 - 在至少 6 个月的时段内，确保每周至少投入 5 个小时（通常更多） 描述 | 网址 -----|----- @@ -500,7 +501,7 @@ Site strings | [All site strings](#Site-strings-in-i18n) in a new localized TOML 安装 | [所有标题和副标题网址](/zh/docs/setup/) 教程 | [Kubernetes 基础](/zh/docs/tutorials/kubernetes-basics/), [Hello Minikube](/zh/docs/tutorials/hello-minikube/) 网站字符串 | [所有网站字符串](#Site-strings-in-i18n) - +发行版本 | [所有标题和副标题 URL](/releases) @@ -616,6 +617,24 @@ Some language teams have their own language-specific style guide and glossary. F 一些语言团队有自己的特定语言样式指南和词汇表。 例如，请参见[中文本地化指南](/zh/docs/contribute/localization_zh/)。 + + +### 特定语言的 Zoom 会议 + +如果本地化项目需要单独的会议时间， +请联系 SIG Docs 联合主席或技术主管以创建新的重复 Zoom 会议和日历邀请。 +仅当团队维持在足够大的规模并需要单独的会议时才需要这样做。 + +根据 CNCF 政策，本地化团队必须将他们的会议上传到 SIG Docs YouTube 播放列表。 +SIG Docs 联合主席或技术主管可以帮助完成该过程，直到 SIG Docs 实现自动化。 + ## 官方支持的客户端库 @@ -71,19 +71,19 @@ client libraries: - [Kubernetes Python 语言客户端库](https://github.com/kubernetes-client/python) - [Kubernetes Java 语言客户端库](https://github.com/kubernetes-client/java) - [Kubernetes JavaScript 语言客户端库](https://github.com/kubernetes-client/javascript) -- [Kubernetes Dotnet 语言客户端库](https://github.com/kubernetes-client/csharp) +- [Kubernetes C# 语言客户端库](https://github.com/kubernetes-client/csharp) - [Kubernetes Haskell 语言客户端库](https://github.com/kubernetes-client/haskell) ## CLI -* [kubectl](/zh/docs/reference/kubectl/overview/) - 主要的 CLI 工具，用于运行命令和管理 Kubernetes 集群。 +* [kubectl](/zh/docs/reference/kubectl/) - 主要的 CLI 工具，用于运行命令和管理 Kubernetes 集群。 * [JSONPath](/zh/docs/reference/kubectl/jsonpath/) - 通过 kubectl 使用 [JSONPath 表达式](https://goessner.net/articles/JsonPath/) 的语法指南。 * [kubeadm](/zh/docs/reference/setup-tools/kubeadm/) - 此 CLI 工具可轻松配置安全的 Kubernetes 集群。 @@ -105,6 +105,8 @@ client libraries: * [Scheduler Policies](/docs/reference/scheduling/policies) * [Scheduler Profiles](/docs/reference/scheduling/config#profiles) + * List of [ports and protocols](/docs/reference/ports-and-protocols/) that + should be open on control plane and worker nodes --> ## 组件 @@ -121,6 +123,8 @@ client libraries: * [调度策略](/zh/docs/reference/scheduling/policies) * [调度配置](/zh/docs/reference/scheduling/config#profiles) + * 应该在控制平面和工作节点上打开的 [端口和协议](/zh/docs/reference/ports-and-protocols/) - + 列表 ## 配置 API @@ -144,14 +154,32 @@ operator to use or manage a cluster. 尽管这些 API 对于用户或操作者使用或管理集群来说是必不可少的， 它们大都没有以 RESTful 的方式在 API 服务器上公开。 -* [kubelet 配置 (v1beta1)](/zh/docs/reference/config-api/kubelet-config.v1beta1/) -* [kube-scheduler 配置 (v1beta1)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta1/) -* [kube-scheduler 策略参考 (v1)](/zh/docs/reference/config-api/kube-scheduler-policy-config.v1/) +* [kube-apiserver 配置 (v1alpha1)](/zh/docs/reference/config-api/apiserver-config.v1alpha1/) +* [kube-apiserver 配置 (v1)](/zh/docs/reference/config-api/apiserver-config.v1/) +* [kube-apiserver 加密 (v1)](/zh/docs/reference/config-api/apiserver-encryption.v1/) +* [kubelet 配置 (v1alpha1)](/zh/docs/reference/config-api/kubelet-config.v1alpha1/) 和 + [kubelet 配置 (v1beta1)](/zh/docs/reference/config-api/kubelet-config.v1beta1/) +* [kubelet 凭据驱动 (v1alpha1)](/zh/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/) +* [kube-scheduler 配置 (v1beta2)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta2/) 和 + [kube-scheduler 配置 (v1beta3)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta3/) * [kube-proxy 配置 (v1alpha1)](/zh/docs/reference/config-api/kube-proxy-config.v1alpha1/) * [`audit.k8s.io/v1` API](/zh/docs/reference/config-api/apiserver-audit.v1/) -* [客户端认证 API (v1beta1)](/zh/docs/reference/config-api/client-authentication.v1beta1/) +* [客户端认证 API (v1beta1)](/zh/docs/reference/config-api/client-authentication.v1beta1/) 和 + [客户端认证 API (v1)](/zh/docs/reference/config-api/client-authentication.v1/) * [WebhookAdmission 配置 (v1)](/zh/docs/reference/config-api/apiserver-webhookadmission.v1/) + + +## kubeadm 的配置 API + +* [v1beta2](/zh/docs/reference/config-api/kubeadm-config.v1beta2/) +* [v1beta3](/zh/docs/reference/config-api/kubeadm-config.v1beta3/) + 准入控制器可以执行 “验证（Validating）” 和/或 “变更（Mutating）” 操作。 -变更（mutating）控制器可以修改被其接受的对象；验证（validating）控制器则不行。 +变更（mutating）控制器可以根据被其接受的请求修改相关对象；验证（validating）控制器则不行。 + +准入控制器限制创建、删除、修改对象或连接到代理的请求，不限制读取对象的请求。 准入控制过程分为两个阶段。第一阶段，运行变更准入控制器。第二阶段，运行验证准入控制器。 再次提醒，某些控制器既是变更准入控制器又是验证准入控制器。 @@ -995,10 +999,11 @@ This admission controller implements additional validations for checking incomin {{< note >}} -对调整卷大小的支持是一种 Alpha 特性。管理员必须将特性门控 `ExpandPersistentVolumes` +对调整卷大小的支持是一种 Beta 特性。作为集群管理员，你必须确保特性门控 `ExpandPersistentVolumes` 设置为 `true` 才能启用调整大小。 {{< /note >}} @@ -1173,7 +1178,7 @@ PodNodeSelector 允许 Pod 强制在特定标签的节点上运行。 ### PodSecurity {#podsecurity} -{{< feature-state for_k8s_version="v1.22" state="alpha" >}} +{{< feature-state for_k8s_version="v1.23" state="beta" >}} 以下 HTTP 头部字段可用来执行伪装请求： @@ -1841,7 +1841,8 @@ Certificates）。 -作为一种可选方案，响应中还可以包含以 RFC3339 时间戳格式给出的证书到期时间。 +作为一种可选方案，响应中还可以包含以 +[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) +时间戳格式给出的证书到期时间。 证书到期时间的有无会有如下影响： - 如果响应中包含了到期时间，持有者令牌和 TLS 凭据会被缓存，直到到期期限到来、 diff --git a/content/zh/docs/reference/access-authn-authz/authorization.md b/content/zh/docs/reference/access-authn-authz/authorization.md index a9fdc7a094..8cd4e605fa 100644 --- a/content/zh/docs/reference/access-authn-authz/authorization.md +++ b/content/zh/docs/reference/access-authn-authz/authorization.md @@ -263,7 +263,7 @@ no ``` 类似地，检查名字空间 `dev` 里的 `dev-sa` 服务账号是否可以列举名字空间 `target` 里的 Pod： diff --git a/content/zh/docs/reference/access-authn-authz/bootstrap-tokens.md b/content/zh/docs/reference/access-authn-authz/bootstrap-tokens.md index 08b79a5d8d..0960a96716 100644 --- a/content/zh/docs/reference/access-authn-authz/bootstrap-tokens.md +++ b/content/zh/docs/reference/access-authn-authz/bootstrap-tokens.md @@ -113,7 +113,7 @@ controller on the controller manager. Each valid token is backed by a secret in the `kube-system` namespace. You can find the full design doc -[here](https://github.com/kubernetes/community/blob/{{< param "githubbranch" >}}/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md). +[here](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md). Here is what the secret looks like. --> @@ -121,7 +121,7 @@ Here is what the secret looks like. 每个合法的令牌背后对应着 `kube-system` 名字空间中的某个 Secret 对象。 你可以从 -[这里](https://github.com/kubernetes/community/blob/{{< param "githubbranch" >}}/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md). +[这里](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md) 找到完整设计文档。 这是 Secret 看起来的样子。 diff --git a/content/zh/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/zh/docs/reference/access-authn-authz/certificate-signing-requests.md index cd82025d19..503818b5ba 100644 --- a/content/zh/docs/reference/access-authn-authz/certificate-signing-requests.md +++ b/content/zh/docs/reference/access-authn-authz/certificate-signing-requests.md @@ -3,7 +3,7 @@ title: 证书签名请求 content_type: concept weight: 20 --- - -证书 API 支持 -[X.509](https://www.itu.int/rec/T-REC-X.509) +证书 API 支持 +[X.509](https://www.itu.int/rec/T-REC-X.509) 的自动化配置， 它为 Kubernetes API 的客户端提供一个编程接口， -用于从证书颁发机构（CA）请求并获取 X.509 +用于从证书颁发机构（CA）请求并获取 X.509 {{< glossary_tooltip term_id="certificate" text="证书" >}}。 CertificateSigningRequest（CSR）资源用来向指定的签名者申请证书签名， @@ -41,7 +41,7 @@ CertificateSigningRequest（CSR）资源用来向指定的签名者申请证书 - @@ -83,13 +83,13 @@ which tells the configured signer that it must not sign the request. 这就相当于通知了指定的签名者，这个证书不能签名。 @@ -100,8 +100,8 @@ The CertificateSigningRequest `status.certificate` field is empty until the sign 此时，字段 `status.certificate` 要么为空，要么包含一个用 PEM 编码的 X.509 证书。 直到签名完成前，CertificateSigningRequest 的字段 `status.certificate` 都为空。 - @@ -147,18 +147,18 @@ This includes: 以便客户端可以预期到他们的 CSR 将发生什么。 此类信息包括： - 1. **信任分发**：信任（CA 证书包）是如何分发的。 @@ -171,7 +171,7 @@ This includes: 以及签名者决定的过期时间与 CSR `spec.expirationSeconds` 字段不同时的应对手段。 6. **允许/不允许 CA 位**：当 CSR 包含一个签名者并不允许的 CA 证书的请求时，相应的应对手段。 - ### 创建 CertificateSigningRequest {#create-certificatesigningrequest} @@ -480,7 +480,7 @@ spec: EOF ``` - 批准 CSR： @@ -521,7 +521,7 @@ Approve the CSR: kubectl certificate approve myuser ``` - 下面是为这个新用户创建 RoleBinding 的示例命令： @@ -576,7 +576,7 @@ This is a sample command to create a RoleBinding for this new user: kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser ``` - 然后，你需要添加上下文： @@ -604,7 +604,7 @@ Then, you need to add the context: kubectl config set-context myuser --cluster=kubernetes --user=myuser ``` - 来测试一下，把上下文切换为 `myuser`： @@ -613,7 +613,7 @@ To test it, change the context to `myuser`: kubectl config use-context myuser ``` - 同样地，驳回一个 CSR： @@ -663,7 +663,7 @@ Likewise, to deny a CSR: kubectl certificate deny ``` - -驳回（`Denied`）的 CRS： +驳回（`Denied`）的 CSR： ```yaml apiVersion: certificates.k8s.io/v1 @@ -717,7 +717,7 @@ status: type: Denied ``` - -* 对于基于 TLS 的启动引导过程时使用的 certificationsigningrequests API 的读/写权限 -* 为委派的身份验证/授权检查创建 tokenreviews 和 subjectaccessreviews 的能力 +* 对于基于 TLS 的启动引导过程时使用的 + [certificationsigningrequests API](/zh/docs/reference/access-authn-authz/certificate-signing-requests/) + 的读/写权限 +* 为委派的身份验证/授权检查创建 TokenReview 和 SubjectAccessReview 的能力 在将来的版本中，节点鉴权器可能会添加或删除权限，以确保 kubelet 具有正确操作所需的最小权限集。 diff --git a/content/zh/docs/reference/access-authn-authz/webhook.md b/content/zh/docs/reference/access-authn-authz/webhook.md index 8cfdc91592..0ef1e6a18d 100644 --- a/content/zh/docs/reference/access-authn-authz/webhook.md +++ b/content/zh/docs/reference/access-authn-authz/webhook.md @@ -266,6 +266,7 @@ to the REST api. -更多信息可以参考 authorization.v1beta1 API 对象和[webhook.go](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go)。 +更多信息可以参考 authorization.v1beta1 API 对象和 [webhook.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go)。 + diff --git a/content/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md b/content/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md index 4151e1bc99..132accf337 100644 --- a/content/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md +++ b/content/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping.md @@ -15,12 +15,12 @@ content_type: concept 在一个 Kubernetes 集群中，工作节点上的组件（kubelet 和 kube-proxy）需要与 -Kubernetes 主控组件通信，尤其是 kube-apiserver。 +Kubernetes 控制平面组件通信，尤其是 kube-apiserver。 为了确保通信本身是私密的、不被干扰，并且确保集群的每个组件都在与另一个 可信的组件通信，我们强烈建议使用节点上的客户端 TLS 证书。 @@ -89,7 +89,7 @@ Note that the above process depends upon: All of the following are responsibilities of whoever sets up and manages the cluster: 1. Creating the CA key and certificate -2. Distributing the CA certificate to the master nodes, where kube-apiserver is running +2. Distributing the CA certificate to the control plane nodes, where kube-apiserver is running 3. Creating a key and certificate for each kubelet; strongly recommended to have a unique one, with a unique CN, for each kubelet 4. Signing the kubelet certificate using the CA key 5. Distributing the kubelet key and signed certificate to the specific node on which the kubelet is running @@ -100,7 +100,7 @@ a cluster. 负责部署和管理集群的人有以下责任： 1. 创建 CA 密钥和证书 -2. 将 CA 证书发布到 kube-apiserver 运行所在的主控节点上 +2. 将 CA 证书发布到 kube-apiserver 运行所在的控制平面节点上 3. 为每个 kubelet 创建密钥和证书；强烈建议为每个 kubelet 使用独一无二的、 CN 取值与众不同的密钥和证书 4. 使用 CA 密钥对 kubelet 证书签名 @@ -191,21 +191,21 @@ In addition, you need your Kubernetes Certificate Authority (CA). ## Certificate Authority As without bootstrapping, you will need a Certificate Authority (CA) key and certificate. As without bootstrapping, these will be used -to sign the kubelet certificate. As before, it is your responsibility to distribute them to master nodes. +to sign the kubelet certificate. As before, it is your responsibility to distribute them to control plane nodes. --> ## 证书机构 {#certificate-authority} 就像在没有启动引导的情况下，你会需要证书机构（CA）密钥和证书。 这些数据会被用来对 kubelet 证书进行签名。 -如前所述，将证书机构密钥和证书发布到主控节点是你的责任。 +如前所述，将证书机构密钥和证书发布到控制平面节点是你的责任。 -就本文而言，我们假定这些数据被发布到主控节点上的 +就本文而言，我们假定这些数据被发布到控制平面节点上的 `/var/lib/kubernetes/ca.pem`（证书）和 `/var/lib/kubernetes/ca-key.pem`（密钥）文件中。 我们将这两个文件称作“Kubernetes CA 证书和密钥”。 @@ -360,7 +360,7 @@ If you want to use bootstrap tokens, you must enable it on kube-apiserver with t ### 访问密钥和证书 {#access-to-key-and-certificate} -如前所述，你需要创建一个 Kubernetes CA 密钥和证书，并将其发布到主控节点。 +如前所述，你需要创建一个 Kubernetes CA 密钥和证书，并将其发布到控制平面节点。 这些数据会被控制器管理器来对 kubelet 证书进行签名。 ## kubelet 配置 {#kubelet-configuration} -最后，当主控节点被正确配置并且所有必要的身份认证和鉴权机制都就绪时， +最后，当控制平面节点被正确配置并且所有必要的身份认证和鉴权机制都就绪时， 我们可以配置 kubelet。 云驱动配置文件的路径。空字符串表示没有配置文件。 -已弃用：将在 1.23 版本中移除，以便于从 kubelet 中去除云驱动代码。 +已弃用：将在 1.24 或更高版本中移除，以便于从 kubelet 中去除云驱动代码。 @@ -331,11 +331,11 @@ The path to the cloud provider configuration file. Empty string for no configura 云服务的提供者。设置为空字符串表示在没有云驱动的情况下运行。 如果设置了此标志，则云驱动负责确定节点的名称（参考云提供商文档以确定是否以及如何使用主机名）。 -已弃用：将在 1.23 版本中移除，以便于从 kubelet 中去除云驱动代码。 +已弃用：将在 1.24 或更高版本中移除，以便于从 kubelet 中去除云驱动代码。 @@ -574,14 +574,17 @@ Use this for the docker endpoint to communicate with. This docker-s kubelet 使用此目录来保存所下载的配置，跟踪配置运行状况。 如果目录不存在，则 kubelet 创建该目录。此路径可以是绝对路径，也可以是相对路径。 相对路径从 kubelet 的当前工作目录计算。 设置此参数将启用动态 kubelet 配置。必须启用 DynamicKubeletConfig -特性门控之后才能设置此标志；由于此特性为 beta 阶段，对应的特性门控当前默认为 -true。 +特性门控之后才能设置此标志。 +(已弃用：DynamicKubeletConfig 功能在 1.22 中已弃用，不会移至 GA。 +计划在 1.24 或更高版本中从 Kubernetes 中移除。 +请使用其他方式来更新 kubelet 配置。) + @@ -781,12 +784,12 @@ Whether kubelet should exit upon lock-file contention. 设置为 true 表示在计算节点可分配资源数量时忽略硬性逐出阈值设置。 参考 相关文档。 -已启用：将在 1.23 版本中移除。 +已启用：将在 1.24 或更高版本中移除。 @@ -808,11 +811,11 @@ When set to true, Hard eviction thresholds will be ignored while ca [实验性特性] 设置为 true 表示 kubelet 在进行挂载卷操作之前要 在本节点上检查所需的组件（如可执行文件等）是否存在。 -已弃用：将在 1.23 版本中移除，以便使用 CSI。 +已弃用：将在 1.24 或更高版本中移除，以便使用 CSI。 @@ -822,11 +825,11 @@ When set to true, Hard eviction thresholds will be ignored while ca 设置为 true 表示 kubelet 将会集成内核的 memcg 通知机制而不是使用轮询机制来 判断是否达到了内存驱逐阈值。 -此标志将在 1.23 版本移除。 +此标志将在 1.24 或更高版本移除。 已弃用：应在 --config 所给的配置文件中进行设置。 （进一步了解） @@ -853,10 +856,10 @@ If enabled, the kubelet will integrate with the kernel memcg notification to det [实验性特性] 卷挂载器（mounter）的可执行文件的路径。设置为空表示使用默认挂载器 mount。 -已弃用：将在 1.23 版本移除以支持 CSI。 +已弃用：将在 1.24 或更高版本移除以支持 CSI。 @@ -2216,10 +2219,10 @@ Timeout of all runtime requests except long running request - pull, <警告：alpha 特性> seccomp 配置文件目录。 -已弃用：将在 1.23 版本中移除，以使用 <root-dir>/seccomp 目录。 +已弃用：将在 1.23 或更高版本中移除，以使用 <root-dir>/seccomp 目录。 diff --git a/content/zh/docs/reference/config-api/apiserver-config.v1.md b/content/zh/docs/reference/config-api/apiserver-config.v1.md index c57438cda3..87f3945431 100644 --- a/content/zh/docs/reference/config-api/apiserver-config.v1.md +++ b/content/zh/docs/reference/config-api/apiserver-config.v1.md @@ -11,7 +11,11 @@ package: apiserver.config.k8s.io/v1 auto_generated: true --> -v1 包中包含 API 的 v1 版本。 + + +

v1 包中包含 API 的 v1 版本。

-AdmissionConfiguration 为准入控制器提供版本化的配置。 +

AdmissionConfiguration 为准入控制器提供版本化的配置。

@@ -39,9 +43,9 @@ AdmissionConfiguration 为准入控制器提供版本化的配置。 @@ -58,9 +62,9 @@ AdmissionConfiguration 为准入控制器提供版本化的配置。 - [AdmissionConfiguration](#apiserver-config-k8s-io-v1-AdmissionConfiguration) -AdmissionPluginConfiguration 为某个插件提供配置信息。 +

AdmissionPluginConfiguration 为某个插件提供配置信息。

字段描述
- plugins 字段允许为每个准入控制插件设置配置选项。 +

plugins 字段允许为每个准入控制插件设置配置选项。
@@ -71,10 +75,10 @@ AdmissionPluginConfiguration 为某个插件提供配置信息。 @@ -83,23 +87,23 @@ It must match the registered admission plugin name. diff --git a/content/zh/docs/reference/config-api/apiserver-config.v1alpha1.md b/content/zh/docs/reference/config-api/apiserver-config.v1alpha1.md new file mode 100644 index 0000000000..b399f304e3 --- /dev/null +++ b/content/zh/docs/reference/config-api/apiserver-config.v1alpha1.md @@ -0,0 +1,447 @@ +--- +title: kube-apiserver 配置 (v1alpha1) +content_type: tool-reference +package: apiserver.k8s.io/v1alpha1 +auto_generated: true +--- + + +

包 v1alpha1 包含 API 的 v1alpha1 版本。

+ + +## 资源类型 + +- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration) +- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration) +- [TracingConfiguration](#apiserver-k8s-io-v1alpha1-TracingConfiguration) + +## `AdmissionConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionConfiguration} + +

+AdmissionConfiguration 为准入控制器提供版本化的配置信息。 +

+ +
字段描述
- name 是准入控制器的名称。它必须与所注册的准入插件名称匹配。 +

name 是准入控制器的名称。它必须与所注册的准入插件名称匹配。
- path 是指向包含插件配置信息的配置文件的路径。 +

path 是指向包含插件配置信息的配置文件的路径。
configuration
-k8s.io/apimachinery/pkg/runtime.Unknown +k8s.io/apimachinery/pkg/runtime.Unknown 		- configuration 是一个内嵌的配置对象，用来保存插件的配置信息。 - 如果存在，则使用这里的配置信息而不是指向配置文件的路径。 +

configuration 是一个内嵌的配置对象，用来保存插件的配置信息。 + 如果存在，则使用这里的配置信息而不是指向配置文件的路径。
+ + + + + + + + + + +
字段描述
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		AdmissionConfiguration
plugins
+[]AdmissionPluginConfiguration +		 +

+ plugins 允许用户为每个准入控制插件指定设置。 +

+
+ +## `EgressSelectorConfiguration` {#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration} + +

+EgressSelectorConfiguration 为 Egress 选择算符客户端提供版本化的配置选项。 +

+ + + + + + + + + + + + +
字段描述
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		EgressSelectorConfiguration
egressSelections [必需]
+[]EgressSelection +		 +

+ connectionServices 包含一组 Egress 选择算符客户端配置选项。 +

+
+ +## `TracingConfiguration` {#apiserver-k8s-io-v1alpha1-TracingConfiguration} + +

+TracingConfiguration 为跟踪客户端提供版本化的配置信息。 +

+ + + + + + + + + + + + + + + +
字段描述
apiVersion
string		apiserver.k8s.io/v1alpha1
kind
string		TracingConfiguration
endpoint
+string +		 +

+在控制面节点上运行的采集器的端点。 +API 服务器在向采集器发送数据时将 egressType 设置为 ControlPlane。 +这里的语法定义在 https://github.com/grpc/grpc/blob/master/doc/naming.md。 +默认值为 otlpgrpc 的默认值，即 localhost:4317 +这一连接是不安全的，且不支持 TLS。 +

+
samplingRatePerMillion
+int32 +		 +

+ samplingRatePerMillion 设置每一百万个数据点中要采样的样本个数。默认值为 0。 +

+
+ +## `AdmissionPluginConfiguration` {#apiserver-k8s-io-v1alpha1-AdmissionPluginConfiguration} + + +**出现在：** + +- [AdmissionConfiguration](#apiserver-k8s-io-v1alpha1-AdmissionConfiguration) + +

+AdmissionPluginConfiguration 为某个插件提供配置信息。 +

+ + + + + + + + + + + + + + + +
字段描述
name [必需]
+string +		 +

+ name 是准入控制器的名称。此名称必须与所注册的准入插件名称匹配。 +

+
path
+string +		 +

+ path 为指向包含插件配置数据的配置文件的路径。 +

+
configuration
+k8s.io/apimachinery/pkg/runtime.Unknown +		 +

+ configuration 是一个嵌入的配置对象，用作插件的配置数据来源。 + 如果设置了此字段，则使用此字段而不是指向配置文件的路径。 +

+
+ +## `Connection` {#apiserver-k8s-io-v1alpha1-Connection} + + +**出现在：** + +- [EgressSelection](#apiserver-k8s-io-v1alpha1-EgressSelection) + +

+Connection 提供某个 Egress 选择客户端的配置信息。 +

+ + + + + + + + + + + + +
字段描述
proxyProtocol [必需]
+ProtocolType +		 +

+ proxyProtocol 是客户端连接到 konnectivity 服务器所使用的协议。 +

+
transport
+Transport +		 +

+ transport 定义的是传输层的配置。我们使用这个配置来联系 konnectivity 服务器。 + 当 proxyProtocol 是 HTTPConnect 或 GRPC 时需要设置此字段。 +

+
+ +## `EgressSelection` {#apiserver-k8s-io-v1alpha1-EgressSelection} + + +**出现在：** + +- [EgressSelectorConfiguration](#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration) + +

+EgressSelection 为某个 Egress 选择客户端提供配置信息。 +

+ + + + + + + + + + + + +
字段描述
name [必需]
+string +		 +

+ name 是 Egress 选择器的名称。当前支持的取值有 "controlplane"， + "master"，"etcd" 和 "cluster"。 + "master" Egress 选择器已被弃用，推荐使用 "controlplane"。 +

+
connection [必需]
+Connection +		 +

+ connection 是用来配置 Egress 选择器的配置信息。 +

+
+ +## `ProtocolType` {#apiserver-k8s-io-v1alpha1-ProtocolType} + + +（`string` 类型的别名） + +**出现在：** + +- [Connection](#apiserver-k8s-io-v1alpha1-Connection) + +

+ProtocolType 是 connection.protocolType 的合法值集合。 +

+ +## `TCPTransport` {#apiserver-k8s-io-v1alpha1-TCPTransport} + + +**出现在：** + +- [Transport](#apiserver-k8s-io-v1alpha1-Transport) + +

+TCPTransport 提供使用 TCP 连接 konnectivity 服务器时需要的信息。 +

+ + + + + + + + + + + + +
字段描述
url [必需]
+string +		 +

+ url 是要连接的 konnectivity 服务器的位置。例如 "https://127.0.0.1:8131"。 +

+
tlsConfig
+TLSConfig +		 +

+ tlsConfig 是使用 TLS 来连接 konnectivity 服务器时需要的信息。 +

+
+ +## `TLSConfig` {#apiserver-k8s-io-v1alpha1-TLSConfig} + + +**出现在：** + +- [TCPTransport](#apiserver-k8s-io-v1alpha1-TCPTransport) + + +

+TLSConfig 为连接 konnectivity 服务器提供身份认证信息。仅用于 TCPTransport。 +

+ + + + + + + + + + + + + + + +
字段描述
caBundle
+string +		 +

+ caBundle 是指向用来确定与 konnectivity 服务器间信任欢喜的 CA 证书包的文件位置。 + 当 tcpTransport.url 前缀为 "http://" 时必须不设置，或者设置为空。 + 如果 tcpTransport.url 前缀为 "https://" 并且此字段未设置，则默认使用系统的信任根。 +

+
clientKey
+string +		 +

+ clientKey 是与 konnectivity 服务器进行 mtls 握手时使用的客户端秘钥文件位置。 + 如果 `tcp.url` 前缀为 http://，必须不指定或者为空； + 如果 `tcp.url` 前缀为 https://，必须设置。 +

+
clientCert
+string +		 +

+ clientCert 是与 konnectivity 服务器进行 mtls 握手时使用的客户端证书文件位置。 + 如果 `tcp.url` 前缀为 http://，必须不指定或者为空； + 如果 `tcp.url` 前缀为 https://，必须设置。 +

+
+ +## `Transport` {#apiserver-k8s-io-v1alpha1-Transport} + + +**出现在：** + +- [Connection](#apiserver-k8s-io-v1alpha1-Connection) + + +

+Transport 定义联系 konnectivity 服务器时要使用的传输层配置。 +

+ + + + + + + + + + + + +
字段描述
tcp
+TCPTransport +		 +

+ tcp 包含通过 TCP 与 konnectivity 服务器通信时使用的 TCP 配置。 + 目前使用 TCP 传输时不支持 GRPC 的 proxyProtocol。 + tcp 和 uds 二者至少设置一个。 +

+
uds
+UDSTransport +		 +

+ uds 包含通过 UDS 与 konnectivity 服务器通信时使用的 UDS 配置。 + tcp 和 uds 二者至少设置一个。 +

+
+ +## `UDSTransport` {#apiserver-k8s-io-v1alpha1-UDSTransport} + + +**出现在：** + +- [Transport](#apiserver-k8s-io-v1alpha1-Transport) + +

+UDSTransport 设置通过 UDS 连接 konnectivity 服务器时需要的信息。 +

+ + + + + + + + + + +
字段描述
udsName [必需]
+string +		 +

+ udsName 是与 konnectivity 服务器连接时使用的 UNIX 域套接字名称。 + 字段取值不要求包含 unix:// 前缀。 + （例如：/etc/srv/kubernetes/konnectivity-server/konnectivity-server.socket） +

+
+ diff --git a/content/zh/docs/reference/config-api/apiserver-webhookadmission.v1.md b/content/zh/docs/reference/config-api/apiserver-webhookadmission.v1.md index e577e497c6..fc19d21dde 100644 --- a/content/zh/docs/reference/config-api/apiserver-webhookadmission.v1.md +++ b/content/zh/docs/reference/config-api/apiserver-webhookadmission.v1.md @@ -13,11 +13,11 @@ auto_generated: true --> -此 API 的版本是 v1。 +

此 API 的版本是 v1。

## 资源类型 {#resource-types} @@ -26,9 +26,9 @@ Package v1 is the v1 version of the API. ## `WebhookAdmission` {#apiserver-config-k8s-io-v1-WebhookAdmission} -WebhookAdmission 为 Webhook 准入控制器提供配置信息。 +

WebhookAdmission 为 Webhook 准入控制器提供配置信息。

@@ -42,8 +42,8 @@ WebhookAdmission 为 Webhook 准入控制器提供配置信息。 string diff --git a/content/zh/docs/reference/config-api/kube-scheduler-config.v1beta1.md b/content/zh/docs/reference/config-api/kube-scheduler-config.v1beta1.md deleted file mode 100644 index ac32e65674..0000000000 --- a/content/zh/docs/reference/config-api/kube-scheduler-config.v1beta1.md +++ /dev/null @@ -1,2156 +0,0 @@ ---- -title: kube-scheduler Configuration (v1beta1) -content_type: tool-reference -package: kubescheduler.config.k8s.io/v1 -auto_generated: true ---- - - -## Resource Types - - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) -- [DefaultPreemptionArgs](#kubescheduler-config-k8s-io-v1beta1-DefaultPreemptionArgs) -- [InterPodAffinityArgs](#kubescheduler-config-k8s-io-v1beta1-InterPodAffinityArgs) -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) -- [NodeAffinityArgs](#kubescheduler-config-k8s-io-v1beta1-NodeAffinityArgs) -- [NodeLabelArgs](#kubescheduler-config-k8s-io-v1beta1-NodeLabelArgs) -- [NodeResourcesFitArgs](#kubescheduler-config-k8s-io-v1beta1-NodeResourcesFitArgs) -- [NodeResourcesLeastAllocatedArgs](#kubescheduler-config-k8s-io-v1beta1-NodeResourcesLeastAllocatedArgs) -- [NodeResourcesMostAllocatedArgs](#kubescheduler-config-k8s-io-v1beta1-NodeResourcesMostAllocatedArgs) -- [PodTopologySpreadArgs](#kubescheduler-config-k8s-io-v1beta1-PodTopologySpreadArgs) -- [RequestedToCapacityRatioArgs](#kubescheduler-config-k8s-io-v1beta1-RequestedToCapacityRatioArgs) -- [ServiceAffinityArgs](#kubescheduler-config-k8s-io-v1beta1-ServiceAffinityArgs) -- [VolumeBindingArgs](#kubescheduler-config-k8s-io-v1beta1-VolumeBindingArgs) - - - - -## `Policy` {#kubescheduler-config-k8s-io-v1-Policy} - - - - - -Policy describes a struct for a policy resource used in api. - -
字段描述
- - 字段 kubeConfigFile 包含指向 kubeconfig 文件的路径。 + +

字段 kubeConfigFile 包含指向 kubeconfig 文件的路径。
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1
kind
string		Policy
predicates [Required]
-[]PredicatePolicy -		 - Holds the information to configure the fit predicate functions
priorities [Required]
-[]PriorityPolicy -		 - Holds the information to configure the priority functions
extenders [Required]
-[]LegacyExtender -		 - Holds the information to communicate with the extender(s)
hardPodAffinitySymmetricWeight [Required]
-int32 -		 - RequiredDuringScheduling affinity is not symmetric, but there is an implicit PreferredDuringScheduling affinity rule -corresponding to every RequiredDuringScheduling affinity rule. -HardPodAffinitySymmetricWeight represents the weight of implicit PreferredDuringScheduling affinity rule, in the range 1-100.
alwaysCheckAllPredicates [Required]
-bool -		 - When AlwaysCheckAllPredicates is set to true, scheduler checks all -the configured predicates even after one or more of them fails. -When the flag is set to false, scheduler skips checking the rest -of the predicates after it finds one predicate that failed.
- - - -## `ExtenderManagedResource` {#kubescheduler-config-k8s-io-v1-ExtenderManagedResource} - - - - -**Appears in:** - -- [Extender](#kubescheduler-config-k8s-io-v1beta1-Extender) - -- [LegacyExtender](#kubescheduler-config-k8s-io-v1-LegacyExtender) - - -ExtenderManagedResource describes the arguments of extended resources -managed by an extender. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name is the extended resource name.
ignoredByScheduler [Required]
-bool -		 - IgnoredByScheduler indicates whether kube-scheduler should ignore this -resource when applying predicates.
- - - -## `ExtenderTLSConfig` {#kubescheduler-config-k8s-io-v1-ExtenderTLSConfig} - - - - -**Appears in:** - -- [Extender](#kubescheduler-config-k8s-io-v1beta1-Extender) - -- [LegacyExtender](#kubescheduler-config-k8s-io-v1-LegacyExtender) - - -ExtenderTLSConfig contains settings to enable TLS with extender - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
insecure [Required]
-bool -		 - Server should be accessed without verifying the TLS certificate. For testing only.
serverName [Required]
-string -		 - ServerName 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.
certFile [Required]
-string -		 - Server requires TLS client certificate authentication
keyFile [Required]
-string -		 - Server requires TLS client certificate authentication
caFile [Required]
-string -		 - Trusted root certificates for server
certData [Required]
-[]byte -		 - CertData holds PEM-encoded bytes (typically read from a client certificate file). -CertData takes precedence over CertFile
keyData [Required]
-[]byte -		 - KeyData holds PEM-encoded bytes (typically read from a client certificate key file). -KeyData takes precedence over KeyFile
caData [Required]
-[]byte -		 - CAData holds PEM-encoded bytes (typically read from a root certificates bundle). -CAData takes precedence over CAFile
- - - -## `LabelPreference` {#kubescheduler-config-k8s-io-v1-LabelPreference} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -LabelPreference holds the parameters that are used to configure the corresponding priority function - - - - - - - - - - - - - - - - - - -
FieldDescription
label [Required]
-string -		 - Used to identify node "groups"
presence [Required]
-bool -		 - This is a boolean flag -If true, higher priority is given to nodes that have the label -If false, higher priority is given to nodes that do not have the label
- - - -## `LabelsPresence` {#kubescheduler-config-k8s-io-v1-LabelsPresence} - - - - -**Appears in:** - -- [PredicateArgument](#kubescheduler-config-k8s-io-v1-PredicateArgument) - - -LabelsPresence holds the parameters that are used to configure the corresponding predicate in scheduler policy configuration. - - - - - - - - - - - - - - - - - - -
FieldDescription
labels [Required]
-[]string -		 - The list of labels that identify node "groups" -All of the labels should be either present (or absent) for the node to be considered a fit for hosting the pod
presence [Required]
-bool -		 - The boolean flag that indicates whether the labels should be present or absent from the node
- - - -## `LegacyExtender` {#kubescheduler-config-k8s-io-v1-LegacyExtender} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -LegacyExtender holds the parameters used to communicate with the extender. If a verb is unspecified/empty, -it is assumed that the extender chose not to provide that extension. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
urlPrefix [Required]
-string -		 - URLPrefix at which the extender is available
filterVerb [Required]
-string -		 - Verb for the filter call, empty if not supported. This verb is appended to the URLPrefix when issuing the filter call to extender.
preemptVerb [Required]
-string -		 - Verb for the preempt call, empty if not supported. This verb is appended to the URLPrefix when issuing the preempt call to extender.
prioritizeVerb [Required]
-string -		 - Verb for the prioritize call, empty if not supported. This verb is appended to the URLPrefix when issuing the prioritize call to extender.
weight [Required]
-int64 -		 - The numeric multiplier for the node scores that the prioritize call generates. -The weight should be a positive integer
bindVerb [Required]
-string -		 - Verb for the bind call, empty if not supported. This verb is appended to the URLPrefix when issuing the bind call to extender. -If this method is implemented by the extender, it is the extender's responsibility to bind the pod to apiserver. Only one extender -can implement this function.
enableHttps [Required]
-bool -		 - EnableHTTPS specifies whether https should be used to communicate with the extender
tlsConfig [Required]
-ExtenderTLSConfig -		 - TLSConfig specifies the transport layer security config
httpTimeout [Required]
-time.Duration -		 - HTTPTimeout specifies the timeout duration for a call to the extender. Filter timeout fails the scheduling of the pod. Prioritize -timeout is ignored, k8s/other extenders priorities are used to select the node.
nodeCacheCapable [Required]
-bool -		 - NodeCacheCapable specifies that the extender is capable of caching node information, -so the scheduler should only send minimal information about the eligible nodes -assuming that the extender already cached full details of all nodes in the cluster
managedResources
-[]ExtenderManagedResource -		 - ManagedResources is a list of extended resources that are managed by -this extender. -- A pod will be sent to the extender on the Filter, Prioritize and Bind - (if the extender is the binder) phases iff the pod requests at least - one of the extended resources in this list. If empty or unspecified, - all pods will be sent to this extender. -- If IgnoredByScheduler is set to true for a resource, kube-scheduler - will skip checking the resource in predicates.
ignorable [Required]
-bool -		 - Ignorable specifies if the extender is ignorable, i.e. scheduling should not -fail when the extender returns an error or is not reachable.
- - - -## `PredicateArgument` {#kubescheduler-config-k8s-io-v1-PredicateArgument} - - - - -**Appears in:** - -- [PredicatePolicy](#kubescheduler-config-k8s-io-v1-PredicatePolicy) - - -PredicateArgument represents the arguments to configure predicate functions in scheduler policy configuration. -Only one of its members may be specified - - - - - - - - - - - - - - - - - - -
FieldDescription
serviceAffinity [Required]
-ServiceAffinity -		 - The predicate that provides affinity for pods belonging to a service -It uses a label to identify nodes that belong to the same "group"
labelsPresence [Required]
-LabelsPresence -		 - The predicate that checks whether a particular node has a certain label -defined or not, regardless of value
- - - -## `PredicatePolicy` {#kubescheduler-config-k8s-io-v1-PredicatePolicy} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -PredicatePolicy describes a struct of a predicate policy. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Identifier of the predicate policy -For a custom predicate, the name can be user-defined -For the Kubernetes provided predicates, the name is the identifier of the pre-defined predicate
argument [Required]
-PredicateArgument -		 - Holds the parameters to configure the given predicate
- - - -## `PriorityArgument` {#kubescheduler-config-k8s-io-v1-PriorityArgument} - - - - -**Appears in:** - -- [PriorityPolicy](#kubescheduler-config-k8s-io-v1-PriorityPolicy) - - -PriorityArgument represents the arguments to configure priority functions in scheduler policy configuration. -Only one of its members may be specified - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
serviceAntiAffinity [Required]
-ServiceAntiAffinity -		 - The priority function that ensures a good spread (anti-affinity) for pods belonging to a service -It uses a label to identify nodes that belong to the same "group"
labelPreference [Required]
-LabelPreference -		 - The priority function that checks whether a particular node has a certain label -defined or not, regardless of value
requestedToCapacityRatioArguments [Required]
-RequestedToCapacityRatioArguments -		 - The RequestedToCapacityRatio priority function is parametrized with function shape.
- - - -## `PriorityPolicy` {#kubescheduler-config-k8s-io-v1-PriorityPolicy} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -PriorityPolicy describes a struct of a priority policy. - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Identifier of the priority policy -For a custom priority, the name can be user-defined -For the Kubernetes provided priority functions, the name is the identifier of the pre-defined priority function
weight [Required]
-int64 -		 - The numeric multiplier for the node scores that the priority function generates -The weight should be non-zero and can be a positive or a negative integer
argument [Required]
-PriorityArgument -		 - Holds the parameters to configure the given priority function
- - - -## `RequestedToCapacityRatioArguments` {#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -RequestedToCapacityRatioArguments holds arguments specific to RequestedToCapacityRatio priority function. - - - - - - - - - - - - - - - - - - -
FieldDescription
shape [Required]
-[]UtilizationShapePoint -		 - Array of point defining priority function shape.
resources [Required]
-[]ResourceSpec -		 - No description provided. -
- - - -## `ResourceSpec` {#kubescheduler-config-k8s-io-v1-ResourceSpec} - - - - -**Appears in:** - -- [RequestedToCapacityRatioArguments](#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments) - - -ResourceSpec represents single resource and weight for bin packing of priority RequestedToCapacityRatioArguments. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name of the resource to be managed by RequestedToCapacityRatio function.
weight [Required]
-int64 -		 - Weight of the resource.
- - - -## `ServiceAffinity` {#kubescheduler-config-k8s-io-v1-ServiceAffinity} - - - - -**Appears in:** - -- [PredicateArgument](#kubescheduler-config-k8s-io-v1-PredicateArgument) - - -ServiceAffinity holds the parameters that are used to configure the corresponding predicate in scheduler policy configuration. - - - - - - - - - - - - - -
FieldDescription
labels [Required]
-[]string -		 - The list of labels that identify node "groups" -All of the labels should match for the node to be considered a fit for hosting the pod
- - - -## `ServiceAntiAffinity` {#kubescheduler-config-k8s-io-v1-ServiceAntiAffinity} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -ServiceAntiAffinity holds the parameters that are used to configure the corresponding priority function - - - - - - - - - - - - - -
FieldDescription
label [Required]
-string -		 - Used to identify node "groups"
- - - -## `UtilizationShapePoint` {#kubescheduler-config-k8s-io-v1-UtilizationShapePoint} - - - - -**Appears in:** - -- [RequestedToCapacityRatioArguments](#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments) - - -UtilizationShapePoint represents single point of priority function shape. - - - - - - - - - - - - - - - - - - -
FieldDescription
utilization [Required]
-int32 -		 - Utilization (x axis). Valid values are 0 to 100. Fully utilized node maps to 100.
score [Required]
-int32 -		 - Score assigned to given utilization (y axis). Valid values are 0 to 10.
- - - - - -## `ClientConnectionConfiguration` {#ClientConnectionConfiguration} - - - - -**Appears in:** - -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) - - -ClientConnectionConfiguration contains details for constructing a client. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
kubeconfig [Required]
-string -		 - kubeconfig is the path to a KubeConfig file.
acceptContentTypes [Required]
-string -		 - 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.
contentType [Required]
-string -		 - contentType is the content type used when sending data to the server from this client.
qps [Required]
-float32 -		 - qps controls the number of queries per second allowed for this connection.
burst [Required]
-int32 -		 - burst allows extra queries to accumulate when a client is exceeding its rate.
- -## `DebuggingConfiguration` {#DebuggingConfiguration} - - - - -**Appears in:** - -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) - - -DebuggingConfiguration holds configuration for Debugging related features. - - - - - - - - - - - - - - - - - - -
FieldDescription
enableProfiling [Required]
-bool -		 - enableProfiling enables profiling via web interface host:port/debug/pprof/
enableContentionProfiling [Required]
-bool -		 - enableContentionProfiling enables lock contention profiling, if -enableProfiling is true.
- -## `LeaderElectionConfiguration` {#LeaderElectionConfiguration} - - - - -**Appears in:** - -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) - - -LeaderElectionConfiguration defines the configuration of leader election -clients for components that can run with leader election enabled. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
leaderElect [Required]
-bool -		 - leaderElect enables a leader election client to gain leadership -before executing the main loop. Enable this when running replicated -components for high availability.
leaseDuration [Required]
-meta/v1.Duration -		 - 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.
renewDeadline [Required]
-meta/v1.Duration -		 - 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.
retryPeriod [Required]
-meta/v1.Duration -		 - 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.
resourceLock [Required]
-string -		 - resourceLock indicates the resource object type that will be used to lock -during leader election cycles.
resourceName [Required]
-string -		 - resourceName indicates the name of resource object that will be used to lock -during leader election cycles.
resourceNamespace [Required]
-string -		 - resourceName indicates the namespace of resource object that will be used to lock -during leader election cycles.
- -## `LoggingConfiguration` {#LoggingConfiguration} - - - - -**Appears in:** - -- [KubeletConfiguration](#kubelet-config-k8s-io-v1beta1-KubeletConfiguration) - - -LoggingConfiguration contains logging options -Refer [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go) for more information. - - - - - - - - - - - - - - - - - - -
FieldDescription
format [Required]
-string -		 - Format Flag specifies the structure of log messages. -default value of format is `text`
sanitization [Required]
-bool -		 - [Experimental] When enabled prevents logging of fields tagged as sensitive (passwords, keys, tokens). -Runtime log sanitization may introduce significant computation overhead and therefore should not be enabled in production.`)
- - - - -## `DefaultPreemptionArgs` {#kubescheduler-config-k8s-io-v1beta1-DefaultPreemptionArgs} - - - - - -DefaultPreemptionArgs holds arguments used to configure the -DefaultPreemption plugin. - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		DefaultPreemptionArgs
minCandidateNodesPercentage [Required]
-int32 -		 - MinCandidateNodesPercentage is the minimum number of candidates to -shortlist when dry running preemption as a percentage of number of nodes. -Must be in the range [0, 100]. Defaults to 10% of the cluster size if -unspecified.
minCandidateNodesAbsolute [Required]
-int32 -		 - MinCandidateNodesAbsolute is the absolute minimum number of candidates to -shortlist. The likely number of candidates enumerated for dry running -preemption is given by the formula: -numCandidates = max(numNodes ∗ minCandidateNodesPercentage, minCandidateNodesAbsolute) -We say "likely" because there are other factors such as PDB violations -that play a role in the number of candidates shortlisted. Must be at least -0 nodes. Defaults to 100 nodes if unspecified.
- - - -## `InterPodAffinityArgs` {#kubescheduler-config-k8s-io-v1beta1-InterPodAffinityArgs} - - - - - -InterPodAffinityArgs holds arguments used to configure the InterPodAffinity plugin. - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		InterPodAffinityArgs
hardPodAffinityWeight [Required]
-int32 -		 - HardPodAffinityWeight is the scoring weight for existing pods with a -matching hard affinity to the incoming pod.
- - - -## `KubeSchedulerConfiguration` {#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration} - - - - - -KubeSchedulerConfiguration configures a scheduler - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		KubeSchedulerConfiguration
parallelism [Required]
-int32 -		 - Parallelism defines the amount of parallelism in algorithms for scheduling a Pods. Must be greater than 0. Defaults to 16
leaderElection [Required]
-LeaderElectionConfiguration -		 - LeaderElection defines the configuration of leader election client.
clientConnection [Required]
-ClientConnectionConfiguration -		 - ClientConnection specifies the kubeconfig file and client connection -settings for the proxy server to use when communicating with the apiserver.
healthzBindAddress [Required]
-string -		 - HealthzBindAddress is the IP address and port for the health check server to serve on, -defaulting to 0.0.0.0:10251
metricsBindAddress [Required]
-string -		 - MetricsBindAddress is the IP address and port for the metrics server to -serve on, defaulting to 0.0.0.0:10251.
DebuggingConfiguration [Required]
-DebuggingConfiguration -		(Members of DebuggingConfiguration are embedded into this type.) - DebuggingConfiguration holds configuration for Debugging related features -TODO: We might wanna make this a substruct like Debugging componentbaseconfigv1alpha1.DebuggingConfiguration
percentageOfNodesToScore [Required]
-int32 -		 - PercentageOfNodesToScore is the percentage of all nodes that once found feasible -for running a pod, the scheduler stops its search for more feasible nodes in -the cluster. This helps improve scheduler's performance. Scheduler always tries to find -at least "minFeasibleNodesToFind" feasible nodes no matter what the value of this flag is. -Example: if the cluster size is 500 nodes and the value of this flag is 30, -then scheduler stops finding further feasible nodes once it finds 150 feasible ones. -When the value is 0, default percentage (5%--50% based on the size of the cluster) of the -nodes will be scored.
podInitialBackoffSeconds [Required]
-int64 -		 - PodInitialBackoffSeconds is the initial backoff for unschedulable pods. -If specified, it must be greater than 0. If this value is null, the default value (1s) -will be used.
podMaxBackoffSeconds [Required]
-int64 -		 - PodMaxBackoffSeconds is the max backoff for unschedulable pods. -If specified, it must be greater than podInitialBackoffSeconds. If this value is null, -the default value (10s) will be used.
profiles [Required]
-[]KubeSchedulerProfile -		 - Profiles are scheduling profiles that kube-scheduler supports. Pods can -choose to be scheduled under a particular profile by setting its associated -scheduler name. Pods that don't specify any scheduler name are scheduled -with the "default-scheduler" profile, if present here.
extenders [Required]
-[]Extender -		 - Extenders are the list of scheduler extenders, each holding the values of how to communicate -with the extender. These extenders are shared by all scheduler profiles.
- - - -## `NodeAffinityArgs` {#kubescheduler-config-k8s-io-v1beta1-NodeAffinityArgs} - - - - - -NodeAffinityArgs holds arguments to configure the NodeAffinity plugin. - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		NodeAffinityArgs
addedAffinity
-core/v1.NodeAffinity -		 - AddedAffinity is applied to all Pods additionally to the NodeAffinity -specified in the PodSpec. That is, Nodes need to satisfy AddedAffinity -AND .spec.NodeAffinity. AddedAffinity is empty by default (all Nodes -match). -When AddedAffinity is used, some Pods with affinity requirements that match -a specific Node (such as Daemonset Pods) might remain unschedulable.
- - - -## `NodeLabelArgs` {#kubescheduler-config-k8s-io-v1beta1-NodeLabelArgs} - - - - - -NodeLabelArgs holds arguments used to configure the NodeLabel plugin. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		NodeLabelArgs
presentLabels [Required]
-[]string -		 - PresentLabels should be present for the node to be considered a fit for hosting the pod
absentLabels [Required]
-[]string -		 - AbsentLabels should be absent for the node to be considered a fit for hosting the pod
presentLabelsPreference [Required]
-[]string -		 - Nodes that have labels in the list will get a higher score.
absentLabelsPreference [Required]
-[]string -		 - Nodes that don't have labels in the list will get a higher score.
- - - -## `NodeResourcesFitArgs` {#kubescheduler-config-k8s-io-v1beta1-NodeResourcesFitArgs} - - - - - -NodeResourcesFitArgs holds arguments used to configure the NodeResourcesFit plugin. - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		NodeResourcesFitArgs
ignoredResources [Required]
-[]string -		 - IgnoredResources is the list of resources that NodeResources fit filter -should ignore.
ignoredResourceGroups [Required]
-[]string -		 - IgnoredResourceGroups defines the list of resource groups that NodeResources fit filter should ignore. -e.g. if group is ["example.com"], it will ignore all resource names that begin -with "example.com", such as "example.com/aaa" and "example.com/bbb". -A resource group name can't contain '/'.
- - - -## `NodeResourcesLeastAllocatedArgs` {#kubescheduler-config-k8s-io-v1beta1-NodeResourcesLeastAllocatedArgs} - - - - - -NodeResourcesLeastAllocatedArgs holds arguments used to configure NodeResourcesLeastAllocated plugin. - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		NodeResourcesLeastAllocatedArgs
resources [Required]
-[]ResourceSpec -		 - Resources to be managed, if no resource is provided, default resource set with both -the weight of "cpu" and "memory" set to "1" will be applied. -Resource with "0" weight will not accountable for the final score.
- - - -## `NodeResourcesMostAllocatedArgs` {#kubescheduler-config-k8s-io-v1beta1-NodeResourcesMostAllocatedArgs} - - - - - -NodeResourcesMostAllocatedArgs holds arguments used to configure NodeResourcesMostAllocated plugin. - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		NodeResourcesMostAllocatedArgs
resources [Required]
-[]ResourceSpec -		 - Resources to be managed, if no resource is provided, default resource set with both -the weight of "cpu" and "memory" set to "1" will be applied. -Resource with "0" weight will not accountable for the final score.
- - - -## `PodTopologySpreadArgs` {#kubescheduler-config-k8s-io-v1beta1-PodTopologySpreadArgs} - - - - - -PodTopologySpreadArgs holds arguments used to configure the PodTopologySpread plugin. - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		PodTopologySpreadArgs
defaultConstraints
-[]core/v1.TopologySpreadConstraint -		 - DefaultConstraints defines topology spread constraints to be applied to -Pods that don't define any in `pod.spec.topologySpreadConstraints`. -`.defaultConstraints[∗].labelSelectors` must be empty, as they are -deduced from the Pod's membership to Services, ReplicationControllers, -ReplicaSets or StatefulSets. -When not empty, .defaultingType must be "List".
defaultingType
-PodTopologySpreadConstraintsDefaulting -		 - DefaultingType determines how .defaultConstraints are deduced. Can be one -of "System" or "List". - -- "System": Use kubernetes defined constraints that spread Pods among - Nodes and Zones. -- "List": Use constraints defined in .defaultConstraints. - -Defaults to "List" if feature gate DefaultPodTopologySpread is disabled -and to "System" if enabled.
- - - -## `RequestedToCapacityRatioArgs` {#kubescheduler-config-k8s-io-v1beta1-RequestedToCapacityRatioArgs} - - - - - -RequestedToCapacityRatioArgs holds arguments used to configure RequestedToCapacityRatio plugin. - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		RequestedToCapacityRatioArgs
shape [Required]
-[]UtilizationShapePoint -		 - Points defining priority function shape
resources [Required]
-[]ResourceSpec -		 - Resources to be managed
- - - -## `ServiceAffinityArgs` {#kubescheduler-config-k8s-io-v1beta1-ServiceAffinityArgs} - - - - - -ServiceAffinityArgs holds arguments used to configure the ServiceAffinity plugin. - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		ServiceAffinityArgs
affinityLabels [Required]
-[]string -		 - AffinityLabels are homogeneous for pods that are scheduled to a node. -(i.e. it returns true IFF this pod can be added to this node such that all other pods in -the same service are running on nodes with the exact same values for Labels).
antiAffinityLabelsPreference [Required]
-[]string -		 - AntiAffinityLabelsPreference are the labels to consider for service anti affinity scoring.
- - - -## `VolumeBindingArgs` {#kubescheduler-config-k8s-io-v1beta1-VolumeBindingArgs} - - - - - -VolumeBindingArgs holds arguments used to configure the VolumeBinding plugin. - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1beta1
kind
string		VolumeBindingArgs
bindTimeoutSeconds [Required]
-int64 -		 - BindTimeoutSeconds is the timeout in seconds in volume binding operation. -Value must be non-negative integer. The value zero indicates no waiting. -If this value is nil, the default value (600) will be used.
- - - -## `Extender` {#kubescheduler-config-k8s-io-v1beta1-Extender} - - - - -**Appears in:** - -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) - - -Extender holds the parameters used to communicate with the extender. If a verb is unspecified/empty, -it is assumed that the extender chose not to provide that extension. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
urlPrefix [Required]
-string -		 - URLPrefix at which the extender is available
filterVerb [Required]
-string -		 - Verb for the filter call, empty if not supported. This verb is appended to the URLPrefix when issuing the filter call to extender.
preemptVerb [Required]
-string -		 - Verb for the preempt call, empty if not supported. This verb is appended to the URLPrefix when issuing the preempt call to extender.
prioritizeVerb [Required]
-string -		 - Verb for the prioritize call, empty if not supported. This verb is appended to the URLPrefix when issuing the prioritize call to extender.
weight [Required]
-int64 -		 - The numeric multiplier for the node scores that the prioritize call generates. -The weight should be a positive integer
bindVerb [Required]
-string -		 - Verb for the bind call, empty if not supported. This verb is appended to the URLPrefix when issuing the bind call to extender. -If this method is implemented by the extender, it is the extender's responsibility to bind the pod to apiserver. Only one extender -can implement this function.
enableHTTPS [Required]
-bool -		 - EnableHTTPS specifies whether https should be used to communicate with the extender
tlsConfig [Required]
-ExtenderTLSConfig -		 - TLSConfig specifies the transport layer security config
httpTimeout [Required]
-meta/v1.Duration -		 - HTTPTimeout specifies the timeout duration for a call to the extender. Filter timeout fails the scheduling of the pod. Prioritize -timeout is ignored, k8s/other extenders priorities are used to select the node.
nodeCacheCapable [Required]
-bool -		 - NodeCacheCapable specifies that the extender is capable of caching node information, -so the scheduler should only send minimal information about the eligible nodes -assuming that the extender already cached full details of all nodes in the cluster
managedResources
-[]ExtenderManagedResource -		 - ManagedResources is a list of extended resources that are managed by -this extender. -- A pod will be sent to the extender on the Filter, Prioritize and Bind - (if the extender is the binder) phases iff the pod requests at least - one of the extended resources in this list. If empty or unspecified, - all pods will be sent to this extender. -- If IgnoredByScheduler is set to true for a resource, kube-scheduler - will skip checking the resource in predicates.
ignorable [Required]
-bool -		 - Ignorable specifies if the extender is ignorable, i.e. scheduling should not -fail when the extender returns an error or is not reachable.
- - - -## `KubeSchedulerProfile` {#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerProfile} - - - - -**Appears in:** - -- [KubeSchedulerConfiguration](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerConfiguration) - - -KubeSchedulerProfile is a scheduling profile. - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
schedulerName [Required]
-string -		 - SchedulerName is the name of the scheduler associated to this profile. -If SchedulerName matches with the pod's "spec.schedulerName", then the pod -is scheduled with this profile.
plugins [Required]
-Plugins -		 - Plugins specify the set of plugins that should be enabled or disabled. -Enabled plugins are the ones that should be enabled in addition to the -default plugins. Disabled plugins are any of the default plugins that -should be disabled. -When no enabled or disabled plugin is specified for an extension point, -default plugins for that extension point will be used if there is any. -If a QueueSort plugin is specified, the same QueueSort Plugin and -PluginConfig must be specified for all profiles.
pluginConfig [Required]
-[]PluginConfig -		 - PluginConfig is an optional set of custom plugin arguments for each plugin. -Omitting config args for a plugin is equivalent to using the default config -for that plugin.
- - - -## `Plugin` {#kubescheduler-config-k8s-io-v1beta1-Plugin} - - - - -**Appears in:** - -- [PluginSet](#kubescheduler-config-k8s-io-v1beta1-PluginSet) - - -Plugin specifies a plugin name and its weight when applicable. Weight is used only for Score plugins. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name defines the name of plugin
weight [Required]
-int32 -		 - Weight defines the weight of plugin, only used for Score plugins.
- - - -## `PluginConfig` {#kubescheduler-config-k8s-io-v1beta1-PluginConfig} - - - - -**Appears in:** - -- [KubeSchedulerProfile](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerProfile) - - -PluginConfig specifies arguments that should be passed to a plugin at the time of initialization. -A plugin that is invoked at multiple extension points is initialized once. Args can have arbitrary structure. -It is up to the plugin to process these Args. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name defines the name of plugin being configured
args [Required]
-k8s.io/apimachinery/pkg/runtime.RawExtension -		 - Args defines the arguments passed to the plugins at the time of initialization. Args can have arbitrary structure.
- - - -## `PluginSet` {#kubescheduler-config-k8s-io-v1beta1-PluginSet} - - - - -**Appears in:** - -- [Plugins](#kubescheduler-config-k8s-io-v1beta1-Plugins) - - -PluginSet specifies enabled and disabled plugins for an extension point. -If an array is empty, missing, or nil, default plugins at that extension point will be used. - - - - - - - - - - - - - - - - - - -
FieldDescription
enabled [Required]
-[]Plugin -		 - Enabled specifies plugins that should be enabled in addition to default plugins. -These are called after default plugins and in the same order specified here.
disabled [Required]
-[]Plugin -		 - Disabled specifies default plugins that should be disabled. -When all default plugins need to be disabled, an array containing only one "∗" should be provided.
- - - -## `Plugins` {#kubescheduler-config-k8s-io-v1beta1-Plugins} - - - - -**Appears in:** - -- [KubeSchedulerProfile](#kubescheduler-config-k8s-io-v1beta1-KubeSchedulerProfile) - - -Plugins include multiple extension points. When specified, the list of plugins for -a particular extension point are the only ones enabled. If an extension point is -omitted from the config, then the default set of plugins is used for that extension point. -Enabled plugins are called in the order specified here, after default plugins. If they need to -be invoked before default plugins, default plugins must be disabled and re-enabled here in desired order. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
queueSort [Required]
-PluginSet -		 - QueueSort is a list of plugins that should be invoked when sorting pods in the scheduling queue.
preFilter [Required]
-PluginSet -		 - PreFilter is a list of plugins that should be invoked at "PreFilter" extension point of the scheduling framework.
filter [Required]
-PluginSet -		 - Filter is a list of plugins that should be invoked when filtering out nodes that cannot run the Pod.
postFilter [Required]
-PluginSet -		 - PostFilter is a list of plugins that are invoked after filtering phase, no matter whether filtering succeeds or not.
preScore [Required]
-PluginSet -		 - PreScore is a list of plugins that are invoked before scoring.
score [Required]
-PluginSet -		 - Score is a list of plugins that should be invoked when ranking nodes that have passed the filtering phase.
reserve [Required]
-PluginSet -		 - Reserve is a list of plugins invoked when reserving/unreserving resources -after a node is assigned to run the pod.
permit [Required]
-PluginSet -		 - Permit is a list of plugins that control binding of a Pod. These plugins can prevent or delay binding of a Pod.
preBind [Required]
-PluginSet -		 - PreBind is a list of plugins that should be invoked before a pod is bound.
bind [Required]
-PluginSet -		 - Bind is a list of plugins that should be invoked at "Bind" extension point of the scheduling framework. -The scheduler call these plugins in order. Scheduler skips the rest of these plugins as soon as one returns success.
postBind [Required]
-PluginSet -		 - PostBind is a list of plugins that should be invoked after a pod is successfully bound.
- - - -## `PodTopologySpreadConstraintsDefaulting` {#kubescheduler-config-k8s-io-v1beta1-PodTopologySpreadConstraintsDefaulting} - -(Alias of `string`) - - -**Appears in:** - -- [PodTopologySpreadArgs](#kubescheduler-config-k8s-io-v1beta1-PodTopologySpreadArgs) - - -PodTopologySpreadConstraintsDefaulting defines how to set default constraints -for the PodTopologySpread plugin. - - - - - -## `ResourceSpec` {#kubescheduler-config-k8s-io-v1beta1-ResourceSpec} - - - - -**Appears in:** - -- [NodeResourcesLeastAllocatedArgs](#kubescheduler-config-k8s-io-v1beta1-NodeResourcesLeastAllocatedArgs) - -- [NodeResourcesMostAllocatedArgs](#kubescheduler-config-k8s-io-v1beta1-NodeResourcesMostAllocatedArgs) - -- [RequestedToCapacityRatioArgs](#kubescheduler-config-k8s-io-v1beta1-RequestedToCapacityRatioArgs) - - -ResourceSpec represents single resource and weight for bin packing of priority RequestedToCapacityRatioArguments. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name of the resource to be managed by RequestedToCapacityRatio function.
weight [Required]
-int64 -		 - Weight of the resource.
- - - -## `UtilizationShapePoint` {#kubescheduler-config-k8s-io-v1beta1-UtilizationShapePoint} - - - - -**Appears in:** - -- [RequestedToCapacityRatioArgs](#kubescheduler-config-k8s-io-v1beta1-RequestedToCapacityRatioArgs) - - -UtilizationShapePoint represents single point of priority function shape. - - - - - - - - - - - - - - - - - - -
FieldDescription
utilization [Required]
-int32 -		 - Utilization (x axis). Valid values are 0 to 100. Fully utilized node maps to 100.
score [Required]
-int32 -		 - Score assigned to given utilization (y axis). Valid values are 0 to 10.
- - diff --git a/content/zh/docs/reference/config-api/kube-scheduler-policy-config.v1.md b/content/zh/docs/reference/config-api/kube-scheduler-policy-config.v1.md deleted file mode 100644 index e694f7ecbc..0000000000 --- a/content/zh/docs/reference/config-api/kube-scheduler-policy-config.v1.md +++ /dev/null @@ -1,799 +0,0 @@ ---- -title: kube-scheduler Policy Configuration (v1) -content_type: tool-reference -package: kubescheduler.config.k8s.io/v1 -auto_generated: true ---- - - -## Resource Types - - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - - - -## `Policy` {#kubescheduler-config-k8s-io-v1-Policy} - - - - - -Policy describes a struct for a policy resource used in api. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
apiVersion
string		kubescheduler.config.k8s.io/v1
kind
string		Policy
predicates [Required]
-[]PredicatePolicy -		 - Holds the information to configure the fit predicate functions
priorities [Required]
-[]PriorityPolicy -		 - Holds the information to configure the priority functions
extenders [Required]
-[]LegacyExtender -		 - Holds the information to communicate with the extender(s)
hardPodAffinitySymmetricWeight [Required]
-int32 -		 - RequiredDuringScheduling affinity is not symmetric, but there is an implicit PreferredDuringScheduling affinity rule -corresponding to every RequiredDuringScheduling affinity rule. -HardPodAffinitySymmetricWeight represents the weight of implicit PreferredDuringScheduling affinity rule, in the range 1-100.
alwaysCheckAllPredicates [Required]
-bool -		 - When AlwaysCheckAllPredicates is set to true, scheduler checks all -the configured predicates even after one or more of them fails. -When the flag is set to false, scheduler skips checking the rest -of the predicates after it finds one predicate that failed.
- - - -## `ExtenderManagedResource` {#kubescheduler-config-k8s-io-v1-ExtenderManagedResource} - - - - -**Appears in:** - -- [Extender](#kubescheduler-config-k8s-io-v1beta1-Extender) - -- [LegacyExtender](#kubescheduler-config-k8s-io-v1-LegacyExtender) - - -ExtenderManagedResource describes the arguments of extended resources -managed by an extender. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name is the extended resource name.
ignoredByScheduler [Required]
-bool -		 - IgnoredByScheduler indicates whether kube-scheduler should ignore this -resource when applying predicates.
- - - -## `ExtenderTLSConfig` {#kubescheduler-config-k8s-io-v1-ExtenderTLSConfig} - - - - -**Appears in:** - -- [Extender](#kubescheduler-config-k8s-io-v1beta1-Extender) - -- [LegacyExtender](#kubescheduler-config-k8s-io-v1-LegacyExtender) - - -ExtenderTLSConfig contains settings to enable TLS with extender - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
insecure [Required]
-bool -		 - Server should be accessed without verifying the TLS certificate. For testing only.
serverName [Required]
-string -		 - ServerName 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.
certFile [Required]
-string -		 - Server requires TLS client certificate authentication
keyFile [Required]
-string -		 - Server requires TLS client certificate authentication
caFile [Required]
-string -		 - Trusted root certificates for server
certData [Required]
-[]byte -		 - CertData holds PEM-encoded bytes (typically read from a client certificate file). -CertData takes precedence over CertFile
keyData [Required]
-[]byte -		 - KeyData holds PEM-encoded bytes (typically read from a client certificate key file). -KeyData takes precedence over KeyFile
caData [Required]
-[]byte -		 - CAData holds PEM-encoded bytes (typically read from a root certificates bundle). -CAData takes precedence over CAFile
- - - -## `LabelPreference` {#kubescheduler-config-k8s-io-v1-LabelPreference} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -LabelPreference holds the parameters that are used to configure the corresponding priority function - - - - - - - - - - - - - - - - - - -
FieldDescription
label [Required]
-string -		 - Used to identify node "groups"
presence [Required]
-bool -		 - This is a boolean flag -If true, higher priority is given to nodes that have the label -If false, higher priority is given to nodes that do not have the label
- - - -## `LabelsPresence` {#kubescheduler-config-k8s-io-v1-LabelsPresence} - - - - -**Appears in:** - -- [PredicateArgument](#kubescheduler-config-k8s-io-v1-PredicateArgument) - - -LabelsPresence holds the parameters that are used to configure the corresponding predicate in scheduler policy configuration. - - - - - - - - - - - - - - - - - - -
FieldDescription
labels [Required]
-[]string -		 - The list of labels that identify node "groups" -All of the labels should be either present (or absent) for the node to be considered a fit for hosting the pod
presence [Required]
-bool -		 - The boolean flag that indicates whether the labels should be present or absent from the node
- - - -## `LegacyExtender` {#kubescheduler-config-k8s-io-v1-LegacyExtender} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -LegacyExtender holds the parameters used to communicate with the extender. If a verb is unspecified/empty, -it is assumed that the extender chose not to provide that extension. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
urlPrefix [Required]
-string -		 - URLPrefix at which the extender is available
filterVerb [Required]
-string -		 - Verb for the filter call, empty if not supported. This verb is appended to the URLPrefix when issuing the filter call to extender.
preemptVerb [Required]
-string -		 - Verb for the preempt call, empty if not supported. This verb is appended to the URLPrefix when issuing the preempt call to extender.
prioritizeVerb [Required]
-string -		 - Verb for the prioritize call, empty if not supported. This verb is appended to the URLPrefix when issuing the prioritize call to extender.
weight [Required]
-int64 -		 - The numeric multiplier for the node scores that the prioritize call generates. -The weight should be a positive integer
bindVerb [Required]
-string -		 - Verb for the bind call, empty if not supported. This verb is appended to the URLPrefix when issuing the bind call to extender. -If this method is implemented by the extender, it is the extender's responsibility to bind the pod to apiserver. Only one extender -can implement this function.
enableHttps [Required]
-bool -		 - EnableHTTPS specifies whether https should be used to communicate with the extender
tlsConfig [Required]
-ExtenderTLSConfig -		 - TLSConfig specifies the transport layer security config
httpTimeout [Required]
-time.Duration -		 - HTTPTimeout specifies the timeout duration for a call to the extender. Filter timeout fails the scheduling of the pod. Prioritize -timeout is ignored, k8s/other extenders priorities are used to select the node.
nodeCacheCapable [Required]
-bool -		 - NodeCacheCapable specifies that the extender is capable of caching node information, -so the scheduler should only send minimal information about the eligible nodes -assuming that the extender already cached full details of all nodes in the cluster
managedResources
-[]ExtenderManagedResource -		 - ManagedResources is a list of extended resources that are managed by -this extender. -- A pod will be sent to the extender on the Filter, Prioritize and Bind - (if the extender is the binder) phases iff the pod requests at least - one of the extended resources in this list. If empty or unspecified, - all pods will be sent to this extender. -- If IgnoredByScheduler is set to true for a resource, kube-scheduler - will skip checking the resource in predicates.
ignorable [Required]
-bool -		 - Ignorable specifies if the extender is ignorable, i.e. scheduling should not -fail when the extender returns an error or is not reachable.
- - - -## `PredicateArgument` {#kubescheduler-config-k8s-io-v1-PredicateArgument} - - - - -**Appears in:** - -- [PredicatePolicy](#kubescheduler-config-k8s-io-v1-PredicatePolicy) - - -PredicateArgument represents the arguments to configure predicate functions in scheduler policy configuration. -Only one of its members may be specified - - - - - - - - - - - - - - - - - - -
FieldDescription
serviceAffinity [Required]
-ServiceAffinity -		 - The predicate that provides affinity for pods belonging to a service -It uses a label to identify nodes that belong to the same "group"
labelsPresence [Required]
-LabelsPresence -		 - The predicate that checks whether a particular node has a certain label -defined or not, regardless of value
- - - -## `PredicatePolicy` {#kubescheduler-config-k8s-io-v1-PredicatePolicy} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -PredicatePolicy describes a struct of a predicate policy. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Identifier of the predicate policy -For a custom predicate, the name can be user-defined -For the Kubernetes provided predicates, the name is the identifier of the pre-defined predicate
argument [Required]
-PredicateArgument -		 - Holds the parameters to configure the given predicate
- - - -## `PriorityArgument` {#kubescheduler-config-k8s-io-v1-PriorityArgument} - - - - -**Appears in:** - -- [PriorityPolicy](#kubescheduler-config-k8s-io-v1-PriorityPolicy) - - -PriorityArgument represents the arguments to configure priority functions in scheduler policy configuration. -Only one of its members may be specified - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
serviceAntiAffinity [Required]
-ServiceAntiAffinity -		 - The priority function that ensures a good spread (anti-affinity) for pods belonging to a service -It uses a label to identify nodes that belong to the same "group"
labelPreference [Required]
-LabelPreference -		 - The priority function that checks whether a particular node has a certain label -defined or not, regardless of value
requestedToCapacityRatioArguments [Required]
-RequestedToCapacityRatioArguments -		 - The RequestedToCapacityRatio priority function is parametrized with function shape.
- - - -## `PriorityPolicy` {#kubescheduler-config-k8s-io-v1-PriorityPolicy} - - - - -**Appears in:** - -- [Policy](#kubescheduler-config-k8s-io-v1-Policy) - - -PriorityPolicy describes a struct of a priority policy. - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Identifier of the priority policy -For a custom priority, the name can be user-defined -For the Kubernetes provided priority functions, the name is the identifier of the pre-defined priority function
weight [Required]
-int64 -		 - The numeric multiplier for the node scores that the priority function generates -The weight should be non-zero and can be a positive or a negative integer
argument [Required]
-PriorityArgument -		 - Holds the parameters to configure the given priority function
- - - -## `RequestedToCapacityRatioArguments` {#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -RequestedToCapacityRatioArguments holds arguments specific to RequestedToCapacityRatio priority function. - - - - - - - - - - - - - - - - - - -
FieldDescription
shape [Required]
-[]UtilizationShapePoint -		 - Array of point defining priority function shape.
resources [Required]
-[]ResourceSpec -		 - No description provided. -
- - - -## `ResourceSpec` {#kubescheduler-config-k8s-io-v1-ResourceSpec} - - - - -**Appears in:** - -- [RequestedToCapacityRatioArguments](#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments) - - -ResourceSpec represents single resource and weight for bin packing of priority RequestedToCapacityRatioArguments. - - - - - - - - - - - - - - - - - - -
FieldDescription
name [Required]
-string -		 - Name of the resource to be managed by RequestedToCapacityRatio function.
weight [Required]
-int64 -		 - Weight of the resource.
- - - -## `ServiceAffinity` {#kubescheduler-config-k8s-io-v1-ServiceAffinity} - - - - -**Appears in:** - -- [PredicateArgument](#kubescheduler-config-k8s-io-v1-PredicateArgument) - - -ServiceAffinity holds the parameters that are used to configure the corresponding predicate in scheduler policy configuration. - - - - - - - - - - - - - -
FieldDescription
labels [Required]
-[]string -		 - The list of labels that identify node "groups" -All of the labels should match for the node to be considered a fit for hosting the pod
- - - -## `ServiceAntiAffinity` {#kubescheduler-config-k8s-io-v1-ServiceAntiAffinity} - - - - -**Appears in:** - -- [PriorityArgument](#kubescheduler-config-k8s-io-v1-PriorityArgument) - - -ServiceAntiAffinity holds the parameters that are used to configure the corresponding priority function - - - - - - - - - - - - - -
FieldDescription
label [Required]
-string -		 - Used to identify node "groups"
- - - -## `UtilizationShapePoint` {#kubescheduler-config-k8s-io-v1-UtilizationShapePoint} - - - - -**Appears in:** - -- [RequestedToCapacityRatioArguments](#kubescheduler-config-k8s-io-v1-RequestedToCapacityRatioArguments) - - -UtilizationShapePoint represents single point of priority function shape. - - - - - - - - - - - - - - - - - - -
FieldDescription
utilization [Required]
-int32 -		 - Utilization (x axis). Valid values are 0 to 100. Fully utilized node maps to 100.
score [Required]
-int32 -		 - Score assigned to given utilization (y axis). Valid values are 0 to 10.
- - diff --git a/content/zh/docs/reference/config-api/kubelet-config.v1alpha1.md b/content/zh/docs/reference/config-api/kubelet-config.v1alpha1.md new file mode 100644 index 0000000000..ad7e4908f4 --- /dev/null +++ b/content/zh/docs/reference/config-api/kubelet-config.v1alpha1.md @@ -0,0 +1,324 @@ +--- +title: Kubelet 配置 (v1alpha1) +content_type: tool-reference +package: kubelet.config.k8s.io/v1alpha1 +auto_generated: true +--- + + + + +## 资源类型 + +- [CredentialProviderConfig](#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig) + +## `FormatOptions` {#FormatOptions} + + +**出现在：** + +- [LoggingConfiguration](#LoggingConfiguration) + + +FormatOptions 包含为不同类型日志格式提供的选项。 + + + + + + + + + +
字段描述
json [必需]
+JSONOptions +		 + + [试验特性] json 中包含 "json" 日志格式的选项。 +
+ +## `JSONOptions` {#JSONOptions} + + +**出现在：** + +- [FormatOptions](#FormatOptions) + + +JSONOptions 包含用于 "json" 日志格式的选项。 + + + + + + + + + + + + + +
字段描述
splitStream [必需]
+bool +		 + + [试验特性] splitStream 将错误信息重定向到标准错误输出（stderr）， +将提示信息重定向到标准输出（stdout），并为二者提供缓存。默认配置是将两类信息都写出到标准输出， +并且不提供缓存。 +
infoBufferSize [必需]
+k8s.io/apimachinery/pkg/api/resource.QuantityValue +		 + + [试验特性] infoBufferSize 设置使用分离数据流时信息数据流的大小。 +默认值是 0，意味着禁止缓存。 +
+ +## `VModuleConfiguration` {#VModuleConfiguration} + + +（`[]k8s.io/component-base/config/v1alpha1.VModuleItem` 的别名） + + +**出现在：** + +- [LoggingConfiguration](#LoggingConfiguration) + + +VModuleConfiguration 是一个集合，其中包含一个个的文件名（或者文件名模式） +及对应的详细程度阈值。 + +## `CredentialProviderConfig` {#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig} + + +CredentialProviderConfig 包含有关每个 exec 凭据提供者的配置信息。 +Kubelet 从磁盘上读取这些配置信息，并根据 CredentialProvider 类型启用各个提供者。 + + + + + + + + + + + +
字段描述
apiVersion
string		kubelet.config.k8s.io/v1alpha1
kind
string		CredentialProviderConfig
providers [必需]
+[]CredentialProvider +		 + + providers 是一组凭据提供者插件，这些插件会被 kubelet 启用。 +多个提供者可以匹配到同一镜像上，这时，来自所有提供者的凭据信息都会返回给 kubelet。 +如果针对同一镜像调用了多个提供者，则结果会被组合起来。如果提供者返回的认证主键有重复， +列表中先出现的提供者所返回的值将被使用。 +
+ +## `CredentialProvider` {#kubelet-config-k8s-io-v1alpha1-CredentialProvider} + + +**出现在：** + +- [CredentialProviderConfig](#kubelet-config-k8s-io-v1alpha1-CredentialProviderConfig) + + +CredentialProvider 代表的是要被 kubelet 调用的一个 exec 插件。 +这一插件只会在所拉取的镜像与该插件所处理的镜像匹配时才会被调用（参见 matchImages）。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
字段描述
name [必需]
+string +		 + + name 是凭据提供者的名称（必需）。此名称必须与 kubelet + 所看到的提供者可执行文件的名称匹配。可执行文件必须位于 kubelet 的 + bin 目录（通过 --image-credential-provider-bin-dir 设置）下。 +
matchImages [必需]
+[]string +		 + +

matchImages 是一个必须设置的字符串列表，用来匹配镜像以便确定是否要调用此提供者。 +如果字符串之一与 kubelet 所请求的镜像匹配，则此插件会被调用并给予提供凭证的机会。 +镜像应该包含镜像库域名和 URL 路径。

+

matchImages 中的每个条目都是一个模式字符串，其中可以包含端口号和路径。 +域名部分可以包含统配符，但端口或路径部分不可以。通配符可以用作子域名，例如 +'∗.k8s.io' 或 'k8s.∗.io'，以及顶级域名，如 'k8s.∗'。

+

对类似 'app∗.k8s.io' 这类部分子域名的匹配也是支持的。 +每个通配符只能用来匹配一个子域名段，所以 '∗.io' 不会匹配 '∗.k8s.io'。

+

镜像与 matchImages 之间存在匹配时，以下条件都要满足：

+
    +
  • 二者均包含相同个数的域名部分，并且每个域名部分都对应匹配；
    • +
  • matchImages 条目中的 URL 路径部分必须是目标镜像的 URL 路径的前缀；
    • +
  • 如果 matchImages 条目中包含端口号，则端口号也必须与镜像端口号匹配。
    • +
+

matchImages 的一些示例如下：

+
    +
  • 123456789.dkr.ecr.us-east-1.amazonaws.com
    • +
  • ∗.azurecr.io
    • +
  • gcr.io
    • +
  • ∗.∗.registry.io
    • +
  • registry.io:8080/path
    • +
+
defaultCacheDuration [必需]
+meta/v1.Duration +		 + + defaultCacheDuration 是插件在内存中缓存凭据的默认时长， +在插件响应中没有给出缓存时长时，使用这里设置的值。此字段是必需的。 +
apiVersion [必需]
+string +		 + +

要求 exec 插件 CredentialProviderRequest 请求的输入版本。 + 所返回的 CredentialProviderResponse 必须使用与输入相同的编码版本。当前支持的值有：

+
    +
  • credentialprovider.kubelet.k8s.io/v1alpha1
    • +
+
args
+[]string +		 + + 在执行插件可执行文件时要传递给命令的参数。 +
env
+[]ExecEnvVar +		 + + env 定义要提供给插件进程的额外的环境变量。 +这些环境变量会与主机上的其他环境变量以及 client-go 所使用的环境变量组合起来， +一起传递给插件。 +
+ +## `ExecEnvVar` {#kubelet-config-k8s-io-v1alpha1-ExecEnvVar} + + +**出现在：** + +- [CredentialProvider](#kubelet-config-k8s-io-v1alpha1-CredentialProvider) + + +ExecEnvVar 用来在执行基于 exec 的凭据插件时设置环境变量。 + + + + + + + + + + + + + +
字段描述
name [必需]
+string +		 + + 环境变量名称。 +
value [必需]
+string +		 + + 环境变量取值。 +
+ diff --git a/content/zh/docs/reference/glossary/container-runtime.md b/content/zh/docs/reference/glossary/container-runtime.md index badb4bcfcd..36a0caf416 100644 --- a/content/zh/docs/reference/glossary/container-runtime.md +++ b/content/zh/docs/reference/glossary/container-runtime.md @@ -35,11 +35,14 @@ tags: -Kubernetes 支持多个容器运行环境: {{< glossary_tooltip term_id="docker">}}、 +Kubernetes 支持容器运行时，例如 +{{< glossary_tooltip term_id="docker">}}、 {{< glossary_tooltip term_id="containerd" >}}、{{< glossary_tooltip term_id="cri-o" >}} -以及任何实现 [Kubernetes CRI (容器运行环境接口)](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/container-runtime-interface.md)。 +以及 [Kubernetes CRI (容器运行环境接口)](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/container-runtime-interface.md) +的其他任何实现。 \ No newline at end of file diff --git a/content/zh/docs/reference/glossary/extensions.md b/content/zh/docs/reference/glossary/extensions.md index 7c3e43cddf..bec430f31d 100644 --- a/content/zh/docs/reference/glossary/extensions.md +++ b/content/zh/docs/reference/glossary/extensions.md @@ -32,9 +32,10 @@ tags: -大多数集群管理员会使用托管的 Kubernetes 或其某种发行包。因此，大多数 Kubernetes 用户将需要 +许多集群管理员会使用托管的 Kubernetes 或其某种发行包，这些集群预装了扩展。 +因此，大多数 Kubernetes 用户将不需要 安装[扩展组件](/zh/docs/concepts/extend-kubernetes/extend-cluster/#extensions)， -较少用户会需要编写新的扩展组件。 +需要编写新的扩展组件的用户就更少了。 diff --git a/content/zh/docs/reference/glossary/finalizer.md b/content/zh/docs/reference/glossary/finalizer.md index 9d3c48f4cf..82b462784c 100644 --- a/content/zh/docs/reference/glossary/finalizer.md +++ b/content/zh/docs/reference/glossary/finalizer.md @@ -41,15 +41,16 @@ Finalizer 提醒{{}}清 当你告诉 Kubernetes 删除一个指定了 Finalizer 的对象时， -Kubernetes API 会将该对象标记为删除，使其进入只读状态。 +Kubernetes API 通过填充 `.metadata.deletionTimestamp` 来标记要删除的对象， +并返回`202`状态码 (HTTP "已接受") 使其进入只读状态。 此时控制平面或其他组件会采取 Finalizer 所定义的行动， 而目标对象仍然处于终止中（Terminating）的状态。 这些行动完成后，控制器会删除目标对象相关的 Finalizer。 diff --git a/content/zh/docs/reference/glossary/flexvolume.md b/content/zh/docs/reference/glossary/flexvolume.md index df657c62ca..e0f15afb4c 100644 --- a/content/zh/docs/reference/glossary/flexvolume.md +++ b/content/zh/docs/reference/glossary/flexvolume.md @@ -4,7 +4,7 @@ id: flexvolume date: 2018-06-25 full_link: /zh/docs/concepts/storage/volumes/#flexvolume short_description: > - Flexvolume 是创建树外卷插件的一种接口。 + FlexVolume 是一个已弃用的接口，用于创建树外卷插件。 {{< glossary_tooltip text="容器存储接口（CSI）" term_id="csi" >}} 是比 Flexvolume 更新的接口，它解决了 Flexvolumes 的一些问题。 @@ -19,15 +19,15 @@ id: flexvolume date: 2018-06-25 full_link: /docs/concepts/storage/volumes/#flexvolume short_description: > - FlexVolume is an interface for creating out-of-tree volume plugins. The {{< glossary_tooltip text="Container Storage Interface" term_id="csi" >}} is a newer interface which addresses several problems with FlexVolumes. + FlexVolume is a deprecated interface for creating out-of-tree volume plugins. The {{< glossary_tooltip text="Container Storage Interface" term_id="csi" >}} is a newer interface that addresses several problems with FlexVolume. aka: tags: - storage --> -Flexvolume 是创建树外卷插件的一种接口。 +FlexVolume 是一个已弃用的接口，用于创建树外卷插件。 {{< glossary_tooltip text="容器存储接口（CSI）" term_id="csi" >}} 是比 Flexvolume 更新的接口，它解决了 Flexvolume 的一些问题。 diff --git a/content/zh/docs/reference/glossary/kube-scheduler.md b/content/zh/docs/reference/glossary/kube-scheduler.md index e855034fa2..9d6a1842fb 100644 --- a/content/zh/docs/reference/glossary/kube-scheduler.md +++ b/content/zh/docs/reference/glossary/kube-scheduler.md @@ -2,7 +2,7 @@ title: kube-scheduler id: kube-scheduler date: 2018-04-12 -full_link: /docs/reference/generated/kube-scheduler/ +full_link: /zh/docs/reference/command-line-tools-reference/kube-scheduler/ short_description: > 控制平面组件，负责监视新创建的、未指定运行节点的 Pod，选择节点让 Pod 在上面运行。 @@ -17,7 +17,7 @@ tags: title: kube-scheduler id: kube-scheduler date: 2018-04-12 -full_link: /docs/reference/generated/kube-scheduler/ +full_link: /docs/reference/command-line-tools-reference/kube-scheduler/ short_description: > Control plane component that watches for newly created pods with no assigned node, and selects a node for them to run on. diff --git a/content/zh/docs/reference/glossary/kubectl.md b/content/zh/docs/reference/glossary/kubectl.md index 2c8bde22eb..c32cd0812d 100644 --- a/content/zh/docs/reference/glossary/kubectl.md +++ b/content/zh/docs/reference/glossary/kubectl.md @@ -4,9 +4,10 @@ id: kubectl date: 2018-04-12 full_link: /docs/user-guide/kubectl-overview/ short_description: > - kubectl 是用来和 Kubernetes API 服务器进行通信的命令行工具。 + kubectl 是用来和 Kubernetes 集群进行通信的命令行工具。 aka: +- kubectl tags: - tool - fundamental @@ -19,9 +20,10 @@ id: kubectl date: 2018-04-12 full_link: /docs/user-guide/kubectl-overview/ short_description: > - A command line tool for communicating with a Kubernetes API server. + A command line tool for communicating with a Kubernetes cluster. aka: +- kubectl tags: - tool - fundamental @@ -29,15 +31,17 @@ tags: --> - kubectl 是用来和 {{< glossary_tooltip text="Kubernetes API" term_id="kubernetes-api" >}} 服务器进行通信的命令行工具。 - +kubectl 是使用 Kubernetes API 与 Kubernetes +集群的{{}}进行通信的命令行工具。 -您可以使用 kubectl 创建、检查、更新和删除 Kubernetes 对象。 +你可以使用 `kubectl` 创建、检视、更新和删除 Kubernetes 对象。 diff --git a/content/zh/docs/reference/glossary/namespace.md b/content/zh/docs/reference/glossary/namespace.md index 27e2e5018f..5934d748fe 100644 --- a/content/zh/docs/reference/glossary/namespace.md +++ b/content/zh/docs/reference/glossary/namespace.md @@ -4,7 +4,7 @@ id: namespace date: 2018-04-12 full_link: /zh/docs/concepts/overview/working-with-objects/namespaces/ short_description: > - 名字空间是 Kubernetes 为了在同一物理集群上支持多个虚拟集群而使用的一种抽象。 + 名字空间是 Kubernetes 用来支持隔离单个集群中的资源组的一种抽象。 aka: tags: @@ -18,7 +18,7 @@ id: namespace date: 2018-04-12 full_link: /docs/concepts/overview/working-with-objects/namespaces/ short_description: > - An abstraction used by Kubernetes to support multiple virtual clusters on the same physical cluster. + An abstraction used by Kubernetes to support isolation of groups of resources within a single cluster. aka: tags: @@ -27,16 +27,19 @@ tags: --> -名字空间是 Kubernetes 为了在同一物理集群上支持多个虚拟集群而使用的一种抽象。 +名字空间是 Kubernetes 用来支持隔离单个 {{< glossary_tooltip text="集群" term_id="cluster" >}}中的资源组的一种抽象。 -名字空间用来组织集群中对象，并为集群资源划分提供了一种方法。同一名字空间内的资源名称必须唯一，但跨名字空间时不作要求。 +名字空间用来组织集群中对象，并为集群资源划分提供了一种方法。 +同一名字空间内的资源名称必须唯一，但跨名字空间时不作要求。 +基于名字空间的作用域限定仅适用于名字空间作用域的对象（例如 Deployment、Services 等）， +而不适用于集群作用域的对象（例如 StorageClass、Node、PersistentVolume 等）。 在一些文档里名字空间也称为命名空间。 diff --git a/content/zh/docs/reference/glossary/pod-disruption-budget.md b/content/zh/docs/reference/glossary/pod-disruption-budget.md index a900db749d..444bec87e3 100644 --- a/content/zh/docs/reference/glossary/pod-disruption-budget.md +++ b/content/zh/docs/reference/glossary/pod-disruption-budget.md @@ -35,6 +35,15 @@ tags: --> - [Pod Disruption Budget](/zh/docs/concepts/workloads/pods/disruptions/) 使应用所有者能够为多实例应用创建一个对象，来确保一定数量的具有指定标签的 Pod 在任何时候都不会被主动驱逐。 PDB 无法防止非主动的中断，但是会计入预算（budget）。 \ No newline at end of file + [Pod 干扰预算（Pod Disruption Budget，PDB）](/zh/docs/concepts/workloads/pods/disruptions/) + 使应用所有者能够为多实例应用创建一个对象，来确保一定数量的具有指定标签的 Pod 在任何时候都不会被主动驱逐。 + +PDB 无法防止非主动的中断，但是会计入预算（budget）。 diff --git a/content/zh/docs/reference/glossary/preemption.md b/content/zh/docs/reference/glossary/preemption.md index 3475e6ab01..328d0abfac 100644 --- a/content/zh/docs/reference/glossary/preemption.md +++ b/content/zh/docs/reference/glossary/preemption.md @@ -2,7 +2,7 @@ title: 抢占（Preemption） id: preemption date: 2019-01-31 -full_link: /zh/docs/concepts/configuration/pod-priority-preemption/#preemption +full_link: /zh/docs/concepts/scheduling-eviction/pod-priority-preemption/#preemption short_description: > Kubernetes 中的抢占逻辑通过驱逐节点上的低优先级 Pod 来帮助悬决的 Pod 找到合适的节点。 @@ -16,7 +16,7 @@ tags: title: Preemption id: preemption date: 2019-01-31 -full_link: /docs/concepts/configuration/pod-priority-preemption/#preemption +full_link: /docs/concepts/scheduling-eviction/pod-priority-preemption/#preemption short_description: > Preemption logic in Kubernetes helps a pending Pod to find a suitable Node by evicting low priority Pods existing on that Node. @@ -34,9 +34,9 @@ Kubernetes 中的抢占逻辑通过驱逐{{< glossary_tooltip term_id="node" >}} 如果一个 Pod 无法调度，调度器会尝试 -[抢占](/zh/docs/concepts/configuration/pod-priority-preemption/#preemption) +[抢占](/zh/docs/concepts/scheduling-eviction/pod-priority-preemption/#preemption) 较低优先级的 Pod，以使得悬决的 Pod 有可能被调度。 diff --git a/content/zh/docs/reference/glossary/quantity.md b/content/zh/docs/reference/glossary/quantity.md index 03cc80051c..bb349400ad 100644 --- a/content/zh/docs/reference/glossary/quantity.md +++ b/content/zh/docs/reference/glossary/quantity.md @@ -17,7 +17,7 @@ id: quantity date: 2018-08-07 full_link: short_description: > - A whole-number representation of small or large numbers using SI suffixes. + A whole-number representation of small or large numbers using [SI](https://en.wikipedia.org/wiki/International_System_of_Units) suffixes. aka: tags: @@ -27,7 +27,7 @@ tags: -使用全数字来表示较小数值或使用 SI 后缀表示较大数值的表示法。 +使用全数字来表示较小数值或使用 [SI](https://zh.wikipedia.org/wiki/International_System_of_Units) 后缀表示较大数值的表示法。 diff --git a/content/zh/docs/reference/glossary/secret.md b/content/zh/docs/reference/glossary/secret.md index ef1c8e9516..9eb093ac6a 100644 --- a/content/zh/docs/reference/glossary/secret.md +++ b/content/zh/docs/reference/glossary/secret.md @@ -37,9 +37,11 @@ tags: -Secret 允许用户对如何使用敏感信息进行更多的控制，并减少信息意外暴露的风险，包括静态[encryption（加密）](/zh/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted)。 +Secret 允许用户对如何使用敏感信息进行更多的控制，并减少信息意外暴露的风险。 +默认情况下，Secret 值被编码为 base64 字符串并以非加密的形式存储，但可以配置为 +[静态加密（Encrypt at rest）](/zh/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted)。 {{< glossary_tooltip text="Pod" term_id="pod" >}} 通过挂载卷中的文件的方式引用 Secret，或者通过 kubelet 为 pod 拉取镜像时引用。 Secret 非常适合机密数据使用，而 [ConfigMaps](/zh/docs/tasks/configure-pod-container/configure-pod-configmap/) 适用于非机密数据。 diff --git a/content/zh/docs/reference/issues-security/security.md b/content/zh/docs/reference/issues-security/security.md index ba62808259..3124098682 100644 --- a/content/zh/docs/reference/issues-security/security.md +++ b/content/zh/docs/reference/issues-security/security.md @@ -34,11 +34,6 @@ Join the [kubernetes-security-announce](https://groups.google.com/forum/#!forum/ --> 加入 [kubernetes-security-announce](https://groups.google.com/forum/#!forum/kubernetes-security-announce) 组，以获取关于安全性和主要 API 公告的电子邮件。 - -你也可以使用[此链接](https://groups.google.com/forum/feed/kubernetes-security-announce/msgs/rss_v2_0.xml?num=50) 订阅上述的 RSS 反馈。 - @@ -57,14 +52,18 @@ To make a report, please email the private [security@kubernetes.io](mailto:secur 详细信息电子邮件到[security@kubernetes.io](mailto:security@kubernetes.io)列表。 -你还可以通过电子邮件向私有 [security@kubernetes.io](mailto:security@kubernetes.io) 列表发送电子邮件，邮件中应该包含[所有 Kubernetes 错误报告](https://git.k8s.io/kubernetes/.github/ISSUE_TEMPLATE/bug-report.md)所需的详细信息。 +你还可以通过电子邮件向私有 [security@kubernetes.io](mailto:security@kubernetes.io) +列表发送电子邮件，邮件中应该包含 +[所有 Kubernetes 错误报告](https://github.com/kubernetes/kubernetes/blob/master/.github/ISSUE_TEMPLATE/bug-report.yaml) +所需的详细信息。 -你可以使用[产品安全团队成员](https://git.k8s.io/security/README.md#product-security-committee-psc) -的 GPG 密钥加密你的电子邮件到此列表。使用 GPG 加密不需要公开。 +你可以使用[安全响应委员会成员](https://git.k8s.io/security/README.md#product-security-committee-psc)的 +GPG 密钥加密你的发往邮件列表的邮件。揭示问题时不需要使用 GPG 来加密。 -每个报告在 3 个工作日内由产品安全团队成员确认和分析。这将启动[安全发布过程](https://git.k8s.io/sig-release/security-release-process-documentation/security-release-process.md#disclosures)。 +每个报告在 3 个工作日内由安全响应委员会成员确认和分析。这将启动[安全发布过程](https://git.k8s.io/sig-release/security-release-process-documentation/security-release-process.md#disclosures)。 -与产品安全团队共享的任何漏洞信息都保留在 Kubernetes 项目中，除非有必要修复该问题，否则不会传播到其他项目。 +与安全响应委员会共享的任何漏洞信息都保留在 Kubernetes 项目中，除非有必要修复该问题，否则不会传播到其他项目。 -公开披露日期由 Kubernetes 产品安全团队和 bug 提交者协商。我们倾向于在用户缓解措施可用时尽快完全披露该 bug。 +公开披露日期由 Kubernetes 安全响应委员会和 bug 提交者协商。 +我们倾向于在能够为用户提供缓解措施之后尽快完全披露该 bug。 diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/_index.md b/content/zh/docs/reference/kubernetes-api/common-definitions/_index.md new file mode 100644 index 0000000000..372df75c58 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/_index.md @@ -0,0 +1,5 @@ +--- +title: "公共定义" +weight: 9 +--- + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/delete-options.md b/content/zh/docs/reference/kubernetes-api/common-definitions/delete-options.md new file mode 100644 index 0000000000..a4bd2e0405 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/delete-options.md @@ -0,0 +1,139 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/apimachinery/pkg/apis/meta/v1" + kind: "DeleteOptions" +content_type: "api_reference" +description: "删除 API 对象时可能会提供删除选项。" +title: "删除选项" +weight: 1 +auto_generated: true +--- + + + +`import "k8s.io/apimachinery/pkg/apis/meta/v1"` + + +删除 API 对象时可能会提供 DeleteOptions。 + +
+ + + +- **apiVersion** (string) + + `APIVersion` 定义对象表示的版本化模式。 + 服务器应将已识别的模式转换为最新的内部值，并可能拒绝无法识别的值。 + 更多信息：https ://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + + + +- **dryRun** ([]string) + + 该值如果存在，则表示不应保留修改。 + 无效或无法识别的 `dryRun` 指令将导致错误响应并且不会进一步处理请求。有效值为： + + - `All`：处理所有试运行阶段（Dry Run Stages） + + + +- **gracePeriodSeconds** (int64) + + 表示对象被删除之前的持续时间（以秒为单位）。 + 值必须是非负整数。零值表示立即删除。如果此值为 `nil`，则将使用指定类型的默认宽限期。如果未指定，则为每个对象的默认值。 + + + +- **kind** (string) + + `kind` 是一个字符串值，表示此对象代表的 REST 资源。 + 服务器可以从客户端提交请求的端点推断出此值。此值无法更新，是驼峰的格式。 + 更多信息：https ://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds 。 + + + +- **orphanDependents** (boolean) + + 已弃用：该字段将在 1.7 中弃用，请使用 `propagationPolicy` 字段。 + 该字段表示依赖对象是否应该是孤儿。如果为 true/false，对象的 finalizers 列表中会被添加上或者移除掉 “orphan” 终结器（Finalizer）。 + 可以设置此字段或者设置 `propagationPolicy` 字段，但不能同时设置以上两个字段。 + + + +- **preconditions** (Preconditions) + + 先决条件必须在执行删除之前完成。如果无法满足这些条件，将返回 409（冲突）状态。 + + + *执行操作（更新、删除等）之前必须满足先决条件。* + + - **preconditions.resourceVersion** (string) + + 指定目标资源版本（resourceVersion）。 + + - **preconditions.uid** (string) + + 指定目标 UID. + + + +- **propagationPolicy** (string) + + 表示是否以及如何执行垃圾收集。可以设置此字段或 `orphanDependents` 字段，但不能同时设置二者。 + 默认策略由 `metadata.finalizers` 中现有终结器（Finalizer）集合和特定资源的默认策略决定。 + 可接受的值为： `Orphan` - 令依赖对象成为孤儿对象；`Background` - 允许垃圾收集器在后台删除依赖项；`Foreground` - 一个级联策略，前台删除所有依赖项。 + + + + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/label-selector.md b/content/zh/docs/reference/kubernetes-api/common-definitions/label-selector.md new file mode 100644 index 0000000000..ffa372d2df --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/label-selector.md @@ -0,0 +1,103 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/apimachinery/pkg/apis/meta/v1" + kind: "LabelSelector" +content_type: "api_reference" +description: "标签选择器是对一组资源的标签查询。" +title: "标签选择器" +weight: 2 +auto_generated: true +--- + + + +`import "k8s.io/apimachinery/pkg/apis/meta/v1"` + + + +标签选择器是对一组资源的标签查询。 + +`matchLabels` 和 `matchExpressions` 的结果按逻辑与的关系组合。一个 `empty` 标签选择器匹配所有对象。一个 `null` 标签选择器不匹配任何对象。 + +
+ + + +- **matchExpressions** ([]LabelSelectorRequirement) + + `matchExpressions` 是 `LabelSelectorRequirement` 的列表，这些需求结果按逻辑与的关系来计算。 + + + *标签选择器要求是包含值、键和关联键和值的运算符的选择器。* + + + + - **matchExpressions.key** (string)， 必填 + + *补丁策略: 按照键 `key` 合并* + + `key` 是选择器应用的标签键. + + + + - **matchExpressions.operator** (string)，必填 + + operator 表示键与一组值的关系。有效的运算符包括 `In`、`NotIn`、`Exists` 和 `DoesNotExist`。 + + + + - **matchExpressions.values** ([]string) + + `values` 是一个字符串值数组。如果运算符为 `In` 或 `NotIn`，则 `values` 数组必须为非空。 + + 如果运算符是 `Exists` 或 `DoesNotExist`，则 `values` 数组必须为空。 + + 该数组在战略性补丁（Strategic Merge Patch）期间被替换。 + + + + - **matchLabels** (map[string]string) + + `matchLabels` 是 {`key`,`value`} 键值对的映射。 + + `matchLabels` 映射中的单个 {`key`,`value`} 键值对相当于 `matchExpressions` 的一个元素，其键字段为 `key`，运算符为 `In`，`values` 数组仅包含 `value`。 + + 所表达的需求最终要按逻辑与的关系组合。 + + + + + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/list-meta.md b/content/zh/docs/reference/kubernetes-api/common-definitions/list-meta.md new file mode 100644 index 0000000000..a4779fcd4d --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/list-meta.md @@ -0,0 +1,93 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/apimachinery/pkg/apis/meta/v1" + kind: "ListMeta" +content_type: "api_reference" +description: "ListMeta 描述了合成资源必须具有的元数据，包括列表和各种状态对象。" +title: "ListMeta" +weight: 3 +auto_generated: true +--- + + + + +`import "k8s.io/apimachinery/pkg/apis/meta/v1"` + + +`ListMeta` 描述了合成资源必须具有的元数据，包括列表和各种状态对象。 +一个资源仅能有 `{ObjectMeta, ListMeta}` 中的一个。 + +
+ + + +- **continue** (string) + + 如果用户对返回的条目数量设置了限制，则 `continue` 可能被设置，表示服务器有更多可用的数据。 + 该值是不透明的，可用于向提供此列表服务的端点发出另一个请求，以检索下一组可用的对象。 + 如果服务器配置已更改或时间已过去几分钟，则可能无法继续提供一致的列表。 + 除非你在错误消息中收到此令牌（token），否则使用此 `continue` 值时返回的 `resourceVersion` + 字段应该和第一个响应中的值是相同的。 + + + +- **remainingItemCount** (int64) + + `remainingItemCount` 是列表中未包含在此列表响应中的后续项目的数量。 + 如果列表请求包含标签或字段选择器，则剩余项目的数量是未知的，并且在序列化期间该字段将保持未设置和省略。 + 如果列表是完整的（因为它没有分块或者这是最后一个块），那么就没有剩余的项目，并且在序列化过程中该字段将保持未设置和省略。 + 早于 v1.15 的服务器不设置此字段。`remainingItemCount` 的预期用途是*估计*集合的大小。 + 客户端不应依赖于设置准确的 `remainingItemCount`。 + + + +- **resourceVersion** (string) + + 标识该对象的服务器内部版本的字符串，客户端可以用该字段来确定对象何时被更改。 + 该值对客户端是不透明的，并且应该原样传回给服务器。该值由系统填充，只读。 + 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency。 + + + +- **selfLink** (string) + + selfLink 表示此对象的 URL，由系统填充，只读。 + + 已弃用。 Kubernetes 将在 1.20 版本中停止传播该字段，并计划在 1.21 版本中删除该字段。 + + + + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/local-object-reference.md b/content/zh/docs/reference/kubernetes-api/common-definitions/local-object-reference.md new file mode 100644 index 0000000000..198d2bd193 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/local-object-reference.md @@ -0,0 +1,46 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/api/core/v1" + kind: "LocalObjectReference" +content_type: "api_reference" +description: "LocalObjectReference 包含足够的信息，可以让你在同一命名空间内找到引用的对象。" +title: "LocalObjectReference" +weight: 4 +auto_generated: true +--- + + + +`import "k8s.io/api/core/v1"` + + +LocalObjectReference 包含足够的信息，可以让你在同一命名空间（namespace）内找到引用的对象。 + +
+ + +- **name** (string) + + 被引用者的名称。 + 更多信息: https://kubernetes.io/zh/docs/concepts/overview/working-with-objects/names/#names。 + + + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md b/content/zh/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md new file mode 100755 index 0000000000..e643330a1b --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/node-selector-requirement.md @@ -0,0 +1,82 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/api/core/v1" + kind: "NodeSelectorRequirement" +content_type: "api_reference" +description: "节点选择器是要求包含键、值和关联键和值的运算符的选择器" +title: "NodeSelectorRequirement" +weight: 5 +auto_generated: true +--- + + +`import "k8s.io/api/core/v1"` + + + + 节点选择器是要求包含键、值和关联键和值的运算符的选择器。 + +
+ + +- **key** (string), 必选 + + 选择器适用的标签键。 + + +- **operator** (string), 必选 + + 表示键与一组值的关系的运算符。有效的运算符包括：In、NotIn、Exists、DoesNotExist、Gt 和 Lt。 + + 可选值: + - `"DoesNotExist"` + - `"Exists"` + - `"Gt"` + - `"In"` + - `"Lt"` + - `"NotIn"` + + +- **values** ([]string) + + 字符串数组。如果运算符为 In 或 NotIn，则数组必须为非空。 + 如果运算符为 Exists 或 DoesNotExist，则数组必须为空。 + 如果运算符为 Gt 或 Lt，则数组必须有一个元素，该元素将被译为整数。 + 该数组在合并计划补丁时将被替换。 + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/object-field-selector.md b/content/zh/docs/reference/kubernetes-api/common-definitions/object-field-selector.md new file mode 100644 index 0000000000..536c9b7f86 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/object-field-selector.md @@ -0,0 +1,54 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/api/core/v1" + kind: "ObjectFieldSelector" +content_type: "api_reference" +description: "ObjectFieldSelector 选择对象的 APIVersioned 字段。" +title: "ObjectFieldSelector" +weight: 6 +auto_generated: true +--- + + + + + +`import "k8s.io/api/core/v1"` + + +ObjectFieldSelector 选择对象的 APIVersioned 字段。 + +
+ + +- **fieldPath** (string), 必需的 + + 在指定 API 版本中要选择的字段的路径。 + +- **apiVersion** (string) + + `fieldPath` 写入时所使用的模式版本，默认为 "v1"。 + + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/object-reference.md b/content/zh/docs/reference/kubernetes-api/common-definitions/object-reference.md new file mode 100644 index 0000000000..2655586d21 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/object-reference.md @@ -0,0 +1,111 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/api/core/v1" + kind: "ObjectReference" +content_type: "api_reference" +description: "ObjectReference 包含足够的信息，可以让你检查或修改引用的对象。" +title: "ObjectReference" +weight: 8 +auto_generated: true +--- + + + + + + +`import "k8s.io/api/core/v1"` + + + +ObjectReference包含足够的信息，允许你检查或修改引用的对象。 + +
+ + + + +- **apiVersion** (string) + + 被引用者的 API 版本。 + +- **fieldPath** (string) + + 如果引用的是对象的某个对象是整个对象，则该字符串而不是应包含的 JSON/Go 字段有效访问语句， + 例如`desiredState.manifest.containers[ 2 ]`。例如，如果对象引用针对的是 Pod 中的一个容器， + 此字段取值类似于：`spec.containers{name}`（`name`指触发的容器的名称）， + 或者如果没有指定容器名称，`spec.containers[ 2 ]`（此Pod中索引为2的容器）。 + 选择这种只是为了有一些定义好的语法来引用对象的部分。 + +- **kind** (string) + + 被引用者的类别（kind）。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md #types-kinds + +- **name** (string) + + 被引用对象的名称。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + +- **namespace** (string) + + 被引用对象的名字空间。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ + +- **resourceVersion** (string) + + 被引用对象的特定资源版本（如果有）。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency + +- **uid** (string) + + 被引用对象的UID。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids + diff --git a/content/zh/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md b/content/zh/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md new file mode 100644 index 0000000000..fead44fe99 --- /dev/null +++ b/content/zh/docs/reference/kubernetes-api/common-definitions/typed-local-object-reference.md @@ -0,0 +1,79 @@ +--- +api_metadata: + apiVersion: "" + import: "k8s.io/api/core/v1" + kind: "TypedLocalObjectReference" +content_type: "api_reference" +description: "TypedLocalObjectReference 包含足够的信息，可以让你在同一个名称空间中定位指定类型的引用对象。" +title: "TypedLocalObjectReference" +weight: 13 +auto_generated: true +--- + + + + + + +`import "k8s.io/api/core/v1"` + + + +TypedLocalObjectReference 包含足够的信息，可以让你在同一个名称空间中定位特定类型的引用对象。 + + +
+ +- **kind** (string), 必需 + + Kind 是被引用的资源的类型 + +- **name** (string), 必需 + + Name 是被引用的资源的名称 + +- **apiGroup** (string) + + APIGroup 是被引用资源的组。如果不指定 APIGroup，则指定的 Kind 必须在核心 API 组中。对于任何其它第三方类型，都需要 APIGroup。 + + + + + diff --git a/content/zh/docs/reference/labels-annotations-taints.md b/content/zh/docs/reference/labels-annotations-taints.md deleted file mode 100644 index e4b1fdfe70..0000000000 --- a/content/zh/docs/reference/labels-annotations-taints.md +++ /dev/null @@ -1,519 +0,0 @@ ---- -title: 常见的标签、注解和污点 -content_type: concept -weight: 20 ---- - - - - - -Kubernetes 预留命名空间 kubernetes.io 用于所有的标签和注解。 - -本文档有两个作用，一是作为可用值的参考，二是作为赋值的协调点。 - - - -## kubernetes.io/arch - -示例：`kubernetes.io/arch=amd64` - -用于：Node - - -Kubelet 用 Go 定义的 `runtime.GOARCH` 生成该标签的键值。在混合使用 arm 和 x86 节点的场景中，此键值可以带来极大便利。 - -## kubernetes.io/os - -示例：`kubernetes.io/os=linux` - -用于：Node - - -Kubelet 用 Go 定义的 `runtime.GOOS` 生成该标签的键值。在混合使用异构操作系统场景下（例如：混合使用 Linux 和 Windows 节点），此键值可以带来极大便利。 - -## kubernetes.io/metadata.name - -示例：`kubernetes.io/metadata.name=mynamespace` - -用于：Namespaces - - -当 `NamespaceDefaultLabelName` [特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/) -被启用时，Kubernetes API 服务器会在所有命名空间上设置此标签。标签值被设置为命名空间的名称。 - -如果你想使用标签 {{< glossary_tooltip text="选择器" term_id="selector" >}} 来指向特定的命名空间，这很有用。 - -## beta.kubernetes.io/arch (deprecated) - - -此标签已被弃用，取而代之的是 `kubernetes.io/arch`. - -## beta.kubernetes.io/os (deprecated) - - -此标签已被弃用，取而代之的是 `kubernetes.io/os`. - -## kubernetes.io/hostname {#kubernetesiohostname} - -示例：`kubernetes.io/hostname=ip-172-20-114-199.ec2.internal` - -用于：Node - - -Kubelet 用主机名生成此标签。需要注意的是主机名可修改，这是把“实际的”主机名通过参数 `--hostname-override` 传给 `kubelet` 实现的。 - -此标签也可用做拓扑层次的一个部分。更多信息参见[topology.kubernetes.io/zone](#topologykubernetesiozone)。 - -## controller.kubernetes.io/pod-deletion-cost {#pod-deletion-cost} - -示例：`controller.kubernetes.io/pod-deletion-cost=10` - -用于：Pod - - -该注解用于设置 [Pod 删除开销](/zh/docs/concepts/workloads/controllers/replicaset/#pod-deletion-cost)， -允许用户影响 ReplicaSet 的缩减顺序。该注解解析为 `int32` 类型。 - -## beta.kubernetes.io/instance-type (deprecated) - -{{< note >}} - -从 v1.17 起，此标签被弃用，取而代之的是 [node.kubernetes.io/instance-type](#nodekubernetesioinstance-type). -{{< /note >}} - - -## node.kubernetes.io/instance-type {#nodekubernetesioinstance-type} - -示例：`node.kubernetes.io/instance-type=m3.medium` - -用于：Node - - -Kubelet 用 `cloudprovider` 定义的实例类型生成此标签。 -所以只有用到 `cloudprovider` 的场合，才会设置此标签。 -此标签非常有用，特别是在你希望把特定工作负载打到特定实例类型的时候，但更常见的调度方法是基于 Kubernetes 调度器来执行基于资源的调度。 -你应该聚焦于使用基于属性的调度方式，而尽量不要依赖实例类型（例如：应该申请一个 GPU，而不是 `g2.2xlarge`）。 - -## failure-domain.beta.kubernetes.io/region (deprecated) {#failure-domainbetakubernetesioregion} - -参见 [topology.kubernetes.io/region](#topologykubernetesioregion). - -{{< note >}} - -从 v1.17 开始，此标签被弃用，取而代之的是 [topology.kubernetes.io/region](#topologykubernetesioregion). -{{< /note >}} - -## failure-domain.beta.kubernetes.io/zone (deprecated) {#failure-domainbetakubernetesiozone} - -参见 [topology.kubernetes.io/zone](#topologykubernetesiozone). - -{{< note >}} - -从 v1.17 开始，此标签被弃用，取而代之的是 [topology.kubernetes.io/zone](#topologykubernetesiozone). -{{< /note >}} - -## statefulset.kubernetes.io/pod-name {#statefulsetkubernetesiopod-name} - -示例：`statefulset.kubernetes.io/pod-name=mystatefulset-7` - - -当 StatefulSet 控制器为 StatefulSet 创建 Pod 时，控制平面会在该 Pod 上设置此标签。 -标签的值是正在创建的 Pod 的名称。 - -更多细节请参见 StatefulSet 文章中的 [Pod 名称标签](/zh/docs/concepts/workloads/controllers/statefulset/#pod-name-label)。 - -## topology.kubernetes.io/region {#topologykubernetesioregion} - -示例 - -`topology.kubernetes.io/region=us-east-1` - -参见 [topology.kubernetes.io/zone](#topologykubernetesiozone). - -## topology.kubernetes.io/zone {#topologykubernetesiozone} - -示例: - -`topology.kubernetes.io/zone=us-east-1c` - -用于：Node, PersistentVolume - - -Node 场景：`kubelet` 或外部的 `cloud-controller-manager` 用 `cloudprovider` 提供的信息生成此标签。 -所以只有在用到 `cloudprovider` 的场景下，此标签才会被设置。 -但如果此标签在你的拓扑中有意义，你也可以考虑在 node 上设置它。 - -PersistentVolume 场景：拓扑自感知的卷制备程序将在 `PersistentVolumes` 上自动设置节点亲和性限制。 - - -一个可用区（zone）表示一个逻辑故障域。Kubernetes 集群通常会跨越多个可用区以提高可用性。 -虽然可用区的确切定义留给基础设施来决定，但可用区常见的属性包括：可用区内的网络延迟非常低，可用区内的网络通讯没成本，独立于其他可用区的故障域。 -例如，一个可用区中的节点可以共享交换机，但不同可用区则不会。 - - -一个地区（region）表示一个更大的域，由一个到多个可用区组成。对于 Kubernetes 来说，跨越多个地区的集群很罕见。 -虽然可用区和地区的确切定义留给基础设施来决定，但地区的常见属性包括：地区间比地区内更高的网络延迟，地区间网络流量更高的成本，独立于其他可用区或是地区的故障域。例如，一个地区内的节点可以共享电力基础设施（例如 UPS 或发电机），但不同地区内的节点显然不会。 - - -Kubernetes 对可用区和地区的结构做出一些假设： -1）地区和可用区是层次化的：可用区是地区的严格子集，任何可用区都不能再 2 个地区中出现。 -2）可用区名字在地区中独一无二：例如地区 "africa-east-1" 可由可用区 "africa-east-1a" 和 "africa-east-1b" 构成。 - - -你可以安全的假定拓扑类的标签是固定不变的。即使标签严格来说是可变的，但使用者依然可以假定一个节点只有通过销毁、重建的方式，才能在可用区间移动。 - - -Kubernetes 能以多种方式使用这些信息。 -例如，调度器自动地尝试将 ReplicaSet 中的 Pod 打散在单可用区集群的不同节点上（以减少节点故障的影响，参见[kubernetes.io/hostname](#kubernetesiohostname)）。 -在多可用区的集群中，这类打散分布的行为也会应用到可用区（以减少可用区故障的影响）。 -做到这一点靠的是 _SelectorSpreadPriority_。 - - -_SelectorSpreadPriority_ 是一种最大能力分配方法（best effort）。如果集群中的可用区是异构的（例如：不同数量的节点，不同类型的节点，或不同的 Pod 资源需求），这种分配方法可以防止平均分配 Pod 到可用区。如果需要，你可以用同构的可用区（相同数量和类型的节点）来减少潜在的不平衡分布。 - - -调度器（通过 _VolumeZonePredicate_ 的预测）也会保障声明了某卷的 Pod 只能分配到该卷相同的可用区。 -卷不支持跨可用区挂载。 - - -如果 `PersistentVolumeLabel` 不支持给 PersistentVolume 自动打标签，你可以考虑手动加标签（或增加 `PersistentVolumeLabel` 支持）。 -有了 `PersistentVolumeLabel`，调度器可以防止 Pod 挂载不同可用区中的卷。 -如果你的基础架构没有此限制，那你根本就没有必要给卷增加 zone 标签。 - -## node.kubernetes.io/windows-build {#nodekubernetesiowindows-build} - -示例: `node.kubernetes.io/windows-build=10.0.17763` - -用于：Node - - -当 kubelet 运行于 Microsoft Windows，它给节点自动打标签，以记录 Windows Server 的版本。 - -标签值的格式为 "主版本.次版本.构建号" - -## service.kubernetes.io/headless {#servicekubernetesioheadless} - -示例：`service.kubernetes.io/headless=""` - -用于：Service - - -在无头（headless）服务的场景下，控制平面为 Endpoint 对象添加此标签。 - -## kubernetes.io/service-name {#kubernetesioservice-name} - -示例：`kubernetes.io/service-name="nginx"` - -用于：Service - - -Kubernetes 用此标签区分多个服务。当前仅用于 `ELB`(Elastic Load Balancer)。 - -## endpointslice.kubernetes.io/managed-by {#endpointslicekubernetesiomanaged-by} - -示例：`endpointslice.kubernetes.io/managed-by="controller"` - -用于：EndpointSlices - - -此标签用来指向管理 EndpointSlice 的控制器或实体。 -此标签的目的是用集群中不同的控制器或实体来管理不同的 EndpointSlice。 - -## endpointslice.kubernetes.io/skip-mirror {#endpointslicekubernetesioskip-mirror} - -示例：`endpointslice.kubernetes.io/skip-mirror="true"` - -用于：Endpoints - - -此标签在 Endpoints 资源上设为 `"true"` 指示 EndpointSliceMirroring 控制器不要镜像此 EndpointSlices 资源。 - -## service.kubernetes.io/service-proxy-name {#servicekubernetesioservice-proxy-name} - -示例：`service.kubernetes.io/service-proxy-name="foo-bar"` - -用于：Service - - -kube-proxy 把此标签用于客户代理，将服务控制委托给客户代理。 - -## experimental.windows.kubernetes.io/isolation-type - -示例：`experimental.windows.kubernetes.io/isolation-type: "hyperv"` - -用于：Pod - - -此注解用于运行 Hyper-V 隔离的 Windows 容器。 -要使用 Hyper-V 隔离特性，并创建 Hyper-V 隔离容器，kubelet 应该用特性门控 HyperVContainer=true 来启动，并且 Pod 应该包含注解 `experimental.windows.kubernetes.io/isolation-type=hyperv`。 - -{{< note >}} -你只能在单容器 Pod 上设置此注解。 -{{< /note >}} - -## ingressclass.kubernetes.io/is-default-class - -示例：`ingressclass.kubernetes.io/is-default-class: "true"` - -用于：IngressClass - - -当唯一的 IngressClass 资源将此注解的值设为 "true"，没有指定类型的新 Ingress 资源将使用此默认类型。 - -## kubernetes.io/ingress.class (deprecated) - -{{< note >}} - -从 v1.18 开始，此注解被弃用，取而代之的是 `spec.ingressClassName`。 -{{< /note >}} - -## storageclass.kubernetes.io/is-default-class - -示例：`storageclass.kubernetes.io/is-default-class=true` - -用于：StorageClass - - -当单个的 StorageClass 资源将这个注解设置为 `"true"` 时，新的持久卷申领（PVC） -资源若未指定类别，将被设定为此默认类别。 - -## alpha.kubernetes.io/provided-node-ip - -示例：`alpha.kubernetes.io/provided-node-ip: "10.0.0.1"` - -用于：Node - - -kubectl 在 Node 上设置此注解，表示它的 IPv4 地址。 - -当 kubectl 由外部的云供应商启动时，在 Node 上设置此注解，表示由命令行标记(`--node-ip`)设置的 IP 地址。 -cloud-controller-manager 向云供应商验证此 IP 是否有效。 - -## batch.kubernetes.io/job-completion-index - -示例：`batch.kubernetes.io/job-completion-index: "3"` - -用于：Pod - - -kube-controller-manager 中的 Job 控制器给创建使用索引 -[完成模式](/zh/docs/concepts/workloads/controllers/job/#completion-mode) -的 Pod 设置此注解。 - -## kubectl.kubernetes.io/default-container - -示例：`kubectl.kubernetes.io/default-container: "front-end-app"` - - -注解的值是此 Pod 的默认容器名称。 -例如，`kubectl logs` 或 `kubectl exec` 没有 `-c` 或 `--container` 参数时，将使用这个默认的容器。 - -## endpoints.kubernetes.io/over-capacity - -示例：`endpoints.kubernetes.io/over-capacity:warning` - -用于：Endpoints - - -在 Kubernetes 集群 v1.21（或更高版本）中，如果 Endpoint 超过 1000 个，Endpoint 控制器 -就会向其添加这个注解。该注解表示 Endpoint 资源已超过容量。 - -**以下列出的污点只能用于 Node** - -## node.kubernetes.io/not-ready - -示例：`node.kubernetes.io/not-ready:NoExecute` - - -节点控制器通过健康监控来检测节点是否就绪，并据此添加/删除此污点。 - -## node.kubernetes.io/unreachable - -示例：`node.kubernetes.io/unreachable:NoExecute` - - -如果 [NodeCondition](/docs/concepts/architecture/nodes/#condition) 的 `Ready` 键值为 `Unknown`，节点控制器将添加污点到 node。 - -## node.kubernetes.io/unschedulable - -示例：`node.kubernetes.io/unschedulable:NoSchedule` - - -当初始化节点时，添加此污点，来避免竟态的发生。 - -## node.kubernetes.io/memory-pressure - -示例：`node.kubernetes.io/memory-pressure:NoSchedule` - - -kubelet 依据节点上观测到的 `memory.available` 和 `allocatableMemory.available` 来检测内存压力。 -用观测值对比 kubelet 设置的阈值，以判断节点状态和污点是否可以被添加/移除。 - -## node.kubernetes.io/disk-pressure - -示例：`node.kubernetes.io/disk-pressure:NoSchedule` - - -kubelet 依据节点上观测到的 `imagefs.available`、`imagefs.inodesFree`、`nodefs.available` 和 `nodefs.inodesFree`(仅 Linux) 来判断磁盘压力。 -用观测值对比 kubelet 设置的阈值，以确定节点状态和污点是否可以被添加/移除。 - -## node.kubernetes.io/network-unavailable - -示例：`node.kubernetes.io/network-unavailable:NoSchedule` - - -它初始由 kubectl 设置，云供应商用它来指示对额外网络配置的需求。 -仅当云中的路由器配置妥当后，云供应商才会移除此污点。 - -## node.kubernetes.io/pid-pressure - -示例：`node.kubernetes.io/pid-pressure:NoSchedule` - - -kubelet 检查 `/proc/sys/kernel/pid_max` 尺寸的 D 值（D-value），以及节点上 Kubernetes 消耗掉的 PID，以获取可用的 PID 数量，此数量可通过指标 `pid.available` 得到。 -然后用此指标对比 kubelet 设置的阈值，以确定节点状态和污点是否可以被添加/移除。 - -## node.cloudprovider.kubernetes.io/uninitialized - -示例：`node.cloudprovider.kubernetes.io/uninitialized:NoSchedule` - - -当 kubelet 由外部云供应商启动时，在节点上设置此污点以标记节点不可用，直到一个 cloud-controller-manager 控制器初始化此节点之后，才会移除此污点。 - -## node.cloudprovider.kubernetes.io/shutdown - -示例：`node.cloudprovider.kubernetes.io/shutdown:NoSchedule` - - -如果一个云供应商的节点被指定为关机状态，节点被打上污点 `node.cloudprovider.kubernetes.io/shutdown`，污点的影响为 `NoSchedule`。 diff --git a/content/zh/docs/reference/labels-annotations-taints/_index.md b/content/zh/docs/reference/labels-annotations-taints/_index.md new file mode 100644 index 0000000000..1fd14e8b6d --- /dev/null +++ b/content/zh/docs/reference/labels-annotations-taints/_index.md @@ -0,0 +1,1040 @@ +--- +title: 众所周知的标签、注解和污点 +content_type: concept +weight: 20 +no_list: true +--- + + + + + +Kubernetes 将所有标签和注解保留在 kubernetes.io Namespace中。 + +本文档既可作为值的参考，也可作为分配值的协调点。 + + + +## API 对象上使用的标签、注解和污点 + +### kubernetes.io/arch {#kubernetes-io-arch} + +例子：`kubernetes.io/arch=amd64` + +用于：Node + +Kubelet 使用 Go 定义的 `runtime.GOARCH` 填充它。 如果你混合使用 ARM 和 X86 节点，这会很方便。 + +### kubernetes.io/os {#kubernetes-io-os} + +例子：`kubernetes.io/os=linux` + +用于：Node + +Kubelet 使用 Go 定义的 `runtime.GOOS` 填充它。如果你在集群中混合使用操作系统（例如：混合 Linux 和 Windows 节点），这会很方便。 + +### kubernetes.io/metadata.name {#kubernetes-io-metadata-name} + +例子：`kubernetes.io/metadata.name=mynamespace` + +用于：Namespace + +Kubernetes API 服务器（{{}} 的一部分）在所有 Namespace 上设置此标签。 +标签值被设置 Namespace 的名称。你无法更改此标签的值。 + +如果你想使用标签{{}}定位特定 Namespace，这很有用。 + +### beta.kubernetes.io/arch (已弃用) {#beta-kubernetes-io-arch} + +此标签已被弃用。请改用`kubernetes.io/arch`。 + +### beta.kubernetes.io/os (已弃用) {#beta-kubernetes-io-os} + +此标签已被弃用。请改用`kubernetes.io/os`。 + + +### kubernetes.io/hostname {#kubernetesiohostname} + +例子：`kubernetes.io/hostname=ip-172-20-114-199.ec2.internal` + +用于：Node + +Kubelet 使用主机名填充此标签。请注意，可以通过将 `--hostname-override` 标志传递给 `kubelet` 来替代“实际”主机名。 + +此标签也用作拓扑层次结构的一部分。 有关详细信息，请参阅 [topology.kubernetes.io/zone](#topologykubernetesiozone)。 + + +### kubernetes.io/change-cause {#change-cause} + +例子：`kubernetes.io/change-cause=kubectl edit --record deployment foo` + +用于：所有对象 + +此注解是对某些事物发生变更的原因的最佳猜测。 + +将 `--record` 添加到可能会更改对象的 `kubectl` 命令时会填充它。 + + +### kubernetes.io/description {#description} + +例子：`kubernetes.io/description: "Description of K8s object."` + +用于：所有对象 + +此注解用于描述给定对象的特定行为。 + + +### kubernetes.io/enforce-mountable-secrets {#enforce-mountable-secrets} + +例子：`kubernetes.io/enforce-mountable-secrets: "true"` + +用于：ServiceAccount + +此注解的值必须为 **true** 才能生效。此注解表示作为此服务帐户运行的 Pod 只能引用在服务帐户的 `secrets` 字段中指定的 Secret API 对象。 + + +### controller.kubernetes.io/pod-deletion-cost {#pod-deletion-cost} + +例子：`controller.kubernetes.io/pod-deletion-cost=10` + +用于：Pod + +该注解用于设置 [Pod 删除成本](/docs/concepts/workloads/controllers/replicaset/#pod-deletion-cost) 允许用户影响 ReplicaSet 缩减顺序。注解解析为 `int32` 类型。 + +### beta.kubernetes.io/instance-type (已弃用) {#beta-kubernetes-io-instance-type} + + +{{< note >}} 从 v1.17 开始，此标签已弃用，取而代之的是 [node.kubernetes.io/instance-type](#nodekubernetesioinstance-type)。 {{< /note >}} + + +### node.kubernetes.io/instance-type {#nodekubernetesioinstance-type} + +例子：`node.kubernetes.io/instance-type=m3.medium` + +用于：Node + +Kubelet 使用 `cloudprovider` 定义的实例类型填充它。 +仅当你使用 `cloudprovider` 时才会设置此项。如果你希望将某些工作负载定位到某些实例类型，则此设置非常方便，但通常你希望依靠 Kubernetes 调度程序来执行基于资源的调度。 +你应该基于属性而不是实例类型来调度（例如：需要 GPU，而不是需要 `g2.2xlarge`）。 + + +### failure-domain.beta.kubernetes.io/region (已弃用) {#failure-domainbetakubernetesioregion} + +请参阅 [topology.kubernetes.io/region](#topologykubernetesioregion)。 + + +{{< note >}} 从 v1.17 开始，此标签已弃用，取而代之的是 [topology.kubernetes.io/region](#topologykubernetesioregion)。 {{}} + + +### failure-domain.beta.kubernetes.io/zone (已弃用) {#failure-domainbetakubernetesiozone} + +请参阅 [topology.kubernetes.io/zone](#topologykubernetesiozone)。 + + +{{< note >}} 从 v1.17 开始，此标签已弃用，取而代之的是 [topology.kubernetes.io/zone](#topologykubernetesiozone)。 {{}} + + +### statefulset.kubernetes.io/pod-name {#statefulsetkubernetesiopod-name} + +例子：`statefulset.kubernetes.io/pod-name=mystatefulset-7` + +当 StatefulSet 控制器为 StatefulSet 创建 Pod 时，控制平面会在该 Pod 上设置此标签。标签的值是正在创建的 Pod 的名称。 + +有关详细信息，请参阅 StatefulSet 主题中的 [Pod 名称标签](/docs/concepts/workloads/controllers/statefulset/#pod-name-label)。 + + +### topology.kubernetes.io/region {#topologykubernetesioregion} + +例子：`topology.kubernetes.io/region=us-east-1` + +请参阅 [topology.kubernetes.io/zone](#topologykubernetesiozone)。 + + +### topology.kubernetes.io/zone {#topologykubernetesiozone} + +例子：`topology.kubernetes.io/zone=us-east-1c` + +用于：Node、PersistentVolume + +在 Node 上：`kubelet` 或外部 `cloud-controller-manager` 使用 `cloudprovider` 提供的信息填充它。仅当你使用 `cloudprovider` 时才会设置此项。 +但是，如果它在你的拓扑中有意义，你应该考虑在 Node 上设置它。 + +在 PersistentVolume 上：拓扑感知卷配置器将自动在 `PersistentVolume` 上设置 Node 亲和性约束。 + +一个 Zone 代表一个逻辑故障域。 Kubernetes 集群通常跨越多个 Zone 以提高可用性。虽然 Zone 的确切定义留给基础设施实现， +但 Zone 的常见属性包括 Zone 内非常低的网络延迟、 Zone 内的免费网络流量以及与其他 Zone 的故障独立性。 +例如，一个 Zone 内的 Node 可能共享一个网络交换机，但不同 Zone 中的 Node 无法共享交换机。 + +一个 Region 代表一个更大的域，由一个或多个 Zone 组成。Kubernetes 集群跨多个 Region 并不常见，虽然 Zone 或 Region 的确切定义留给基础设施实现， +但 Region 的共同属性包括它们之间的网络延迟比它们内部更高，它们之间的网络流量成本非零，以及与其他 Zone 或 Region 的故障独立性。 +例如，一个 Region 内的 Node 可能共享电力基础设施（例如 UPS 或发电机），但不同 Region 的 Node 通常不会共享电力基础设施。 + + +Kubernetes 对 Zone 和 Region 的结构做了一些假设： + +1. Zone 和 Region 是分层的： Zone 是 Region 的严格子集，没有 Zone 可以在两个 Region 中； + +2. Zone 名称跨 Region 是唯一的；例如， Region “africa-east-1” 可能由 Zone “africa-east-1a” 和 “africa-east-1b” 组成。 + + +你可以大胆假设拓扑标签不会改变。尽管严格地讲标签是可变的，但节点的用户可以假设给定 +节点只能通过销毁和重新创建才能完成 Zone 间移动。 + + +Kubernetes 可以通过多种方式使用这些信息。例如，调度程序会自动尝试将 ReplicaSet 中的 Pod +分布在单 Zone 集群中的多个节点上（以便减少节点故障的影响，请参阅 [kubernetes.io/hostname](#kubernetesiohostname)）。 +对于多 Zone 集群，这种分布行为也适用于 Zone（以减少 Zone 故障的影响）。 +Zone 级别的 Pod 分布是通过 _SelectorSpreadPriority_ 实现的。 + + +_SelectorSpreadPriority_ 是一个尽力而为的放置机制。如果集群中的 Zone 是异构的 +（例如：节点数量不同、节点类型不同或 Pod 资源需求有别等），这种放置机制可能会让你的 +Pod 无法实现跨 Zone 均匀分布。 +如果需要，你可以使用同质 Zone（节点数量和类型均相同）来减少不均匀分布的可能性。 + + +调度程序还将（通过 _VolumeZonePredicate_ 条件）确保申领给定卷的 Pod 仅被放置在与该卷相同的 Zone 中。 +卷不能跨 Zone 挂接。 + + +你应该考虑手动添加标签（或添加对 `PersistentVolumeLabel` 的支持）。 +基于 `PersistentVolumeLabel` ，调度程序可以防止 Pod 挂载来自其他 Zone 的卷。如果你的基础架构没有此限制，则不需要将 Zone 标签添加到卷上。 + + +### volume.beta.kubernetes.io/storage-provisioner (已弃用) {#volume-beta-kubernetes-io-storage-provisioner} + +例子：`volume.beta.kubernetes.io/storage-provisioner: k8s.io/minikube-hostpath` + +用于：PersistentVolumeClaim + +此注解已被弃用。 + + +### volume.kubernetes.io/storage-provisioner {#volume-kubernetes-io-storage-provisioner} + +用于：PersistentVolumeClaim + +此注解将被添加到根据需要动态制备的 PVC 上。 + + +### node.kubernetes.io/windows-build {#nodekubernetesiowindows-build} + +例子：`node.kubernetes.io/windows-build=10.0.17763` + +用于：Node + +当 kubelet 在 Microsoft Windows 上运行时，它会自动标记其所在节点以记录所使用的 Windows Server 的版本。 + +标签的值采用 “MajorVersion.MinorVersion.BuildNumber” 格式。 + + +### service.kubernetes.io/headless {#servicekubernetesioheadless} + +例子：`service.kubernetes.io/headless=""` + +用于：Service + +当拥有的 Service 是无头类型时，控制平面将此标签添加到 Endpoints 对象。 + + +### kubernetes.io/service-name {#kubernetesioservice-name} + +例子：`kubernetes.io/service-name="nginx"` + +用于：Service + +Kubernetes 使用这个标签来区分多个服务。目前仅用于 `ELB` （弹性负载均衡器）。 + + +### endpointslice.kubernetes.io/managed-by {#endpointslicekubernetesiomanaged-by} + +例子：`endpointslice.kubernetes.io/managed-by="controller"` + +用于：EndpointSlice + +用于标示管理 EndpointSlice 的控制器或实体。该标签旨在使不同的 EndpointSlice +对象能够由同一集群内的不同控制器或实体管理。 + + +### endpointslice.kubernetes.io/skip-mirror {#endpointslicekubernetesioskip-mirror} + +例子：`endpointslice.kubernetes.io/skip-mirror="true"` + +用于：Endpoints + +可以在 Endpoints 资源上将此标签设置为 `"true"`，以指示 EndpointSliceMirroring +控制器不应使用 EndpointSlice 镜像此 Endpoints 资源。 + + +### service.kubernetes.io/service-proxy-name {#servicekubernetesioservice-proxy-name} + +例子：`service.kubernetes.io/service-proxy-name="foo-bar"` + +用于：Service + +kube-proxy 自定义代理会使用这个标签，它将服务控制委托给自定义代理。 + + +### experimental.windows.kubernetes.io/isolation-type (已弃用) {#experimental-windows-kubernetes-io-isolation-type} + +例子：`experimental.windows.kubernetes.io/isolation-type: "hyperv"` + +用于：Pod + +注解用于运行具有 Hyper-V 隔离的 Windows 容器。要使用 Hyper-V 隔离功能并创建 Hyper-V +隔离容器，kubelet 启动时应该需要设置特性门控 HyperVContainer=true。 + + +{{< note >}} +你只能在具有单个容器的 Pod 上设置此注解。 +从 v1.20 开始，此注解已弃用。1.21 中删除了实验性 Hyper-V 支持。 +{{}} + + +### ingressclass.kubernetes.io/is-default-class {#ingressclass-kubernetes-io-is-default-class} + +例子：`ingressclass.kubernetes.io/is-default-class: "true"` + +用于：IngressClass + +当单个 IngressClass 资源将此注解设置为 `"true"`时，新的未指定 Ingress 类的 Ingress +资源将被设置为此默认类。 + + +### kubernetes.io/ingress.class (已弃用) {#kubernetes-io-ingress-class} + +{{< note >}} +从 v1.18 开始，不推荐使用此注解以鼓励使用 `spec.ingressClassName`。 +{{}} + + +### storageclass.kubernetes.io/is-default-class {#storageclass-kubernetes-io-is-default-class} + +例子：`storageclass.kubernetes.io/is-default-class=true` + +用于：StorageClass + +当单个 StorageClass 资源将此注解设置为 `"true"` 时，新的未指定存储类的 PersistentVolumeClaim +资源将被设置为此默认类。 + + +### alpha.kubernetes.io/provided-node-ip {#alpha-kubernetes-io-provided-node-ip} + +例子：`alpha.kubernetes.io/provided-node-ip: "10.0.0.1"` + +用于：Node + +kubelet 可以在 Node 上设置此注解来表示其配置的 IPv4 地址。 + +当使用“外部”云驱动启动时，kubelet 会在 Node 上设置此注解以表示从命令行标志 ( `--node-ip` ) 设置的 IP 地址。 +云控制器管理器通过云驱动验证此 IP 是否有效。 + + +### batch.kubernetes.io/job-completion-index {#batch-kubernetes-io-job-completion-index} + +例子：`batch.kubernetes.io/job-completion-index: "3"` + +用于：Pod + +kube-controller-manager 中的 Job 控制器为使用 Indexed +[完成模式](/zh/docs/concepts/workloads/controllers/job/#completion-mode)创建的 Pod +设置此注解。 + + +### kubectl.kubernetes.io/default-container {#kubectl-kubernetes-io-default-container} + +例子：`kubectl.kubernetes.io/default-container: "front-end-app"` + +此注解的值是此 Pod 的默认容器名称。例如，未指定 `-c` 或 `--container` 标志时执行 +`kubectl logs` 或 `kubectl exec` 命令将使用此默认容器。 + + +### endpoints.kubernetes.io/over-capacity {#endpoints-kubernetes-io-over-capacity} + +例子：`endpoints.kubernetes.io/over-capacity:truncated` + +用于：Endpoints + +在 Kubernetes 集群 v1.22（或更高版本）中，如果 Endpoints 资源超过 1000 个，Endpoints +控制器会将此注解添加到 Endpoints 资源。 +注解表示 Endpoints 资源已超出容量，并且已将 Endpoints 数截断为 1000。 + + +### batch.kubernetes.io/job-tracking {#batch-kubernetes-io-job-tracking} + +例子：`batch.kubernetes.io/job-tracking: ""` + +用于：Job + +Job 上存在此注解表明控制平面正在[使用 Finalizer 追踪 Job](/zh/docs/concepts/workloads/controllers/job/#job-tracking-with-finalizers)。 +你 **不** 可以手动添加或删除此注解。 + + +### scheduler.alpha.kubernetes.io/preferAvoidPods (deprecated) {#scheduleralphakubernetesio-preferavoidpods} + +用于：Node + +此注解需要启用 [NodePreferAvoidPods 调度插件](/zh/docs/reference/scheduling/config/#scheduling-plugins)。 +该插件自 Kubernetes 1.22 起已被弃用。 +请改用[污点和容忍度](/zh/docs/concepts/scheduling-eviction/taint-and-toleration/)。 + +**下面列出的污点总是在 Node 上使用** + + +### node.kubernetes.io/not-ready {#node-kubernetes-io-not-ready} + +例子：`node.kubernetes.io/not-ready:NoExecute` + +Node 控制器通过监控 Node 的健康状况来检测 Node 是否准备就绪，并相应地添加或删除此污点。 + +### node.kubernetes.io/unreachable {#node-kubernetes-io-unreachable} + +例子：`node.kubernetes.io/unreachable:NoExecute` + +Node 控制器将此污点添加到对应[节点状况](/zh/docs/concepts/architecture/nodes/#condition) `Ready` +为 `Unknown` 的 Node 上。 + + +### node.kubernetes.io/unschedulable {#node-kubernetes-io-unschedulable} + +例子：`node.kubernetes.io/unschedulable:NoSchedule` + +在初始化 Node 期间，为避免竞争条件，此污点将被添加到 Node 上。 + + +### node.kubernetes.io/memory-pressure {#node-kubernetes-io-memory-pressure} + +例子：`node.kubernetes.io/memory-pressure:NoSchedule` + +kubelet 根据在 Node 上观察到的 `memory.available` 和 `allocatableMemory.available` 检测内存压力。 +然后将观察到的值与可以在 kubelet 上设置的相应阈值进行比较，以确定是否应添加/删除 Node 状况和污点。 + + +### node.kubernetes.io/disk-pressure {#node-kubernetes-io-disk-pressure} + +例子：`node.kubernetes.io/disk-pressure:NoSchedule` + +kubelet 根据在 Node 上观察到的 `imagefs.available`、`imagefs.inodesFree`、`nodefs.available` 和 `nodefs.inodesFree`（仅限 Linux ）检测磁盘压力。 +然后将观察到的值与可以在 kubelet 上设置的相应阈值进行比较，以确定是否应添加/删除 Node 状况和污点。 + + +### node.kubernetes.io/network-unavailable {#node-kubernetes-io-network-unavailable} + +例子：`node.kubernetes.io/network-unavailable:NoSchedule` + +当使用的云驱动指示需要额外的网络配置时，此注解最初由 kubelet 设置。 +只有云上的路由被正确地配置了，此污点才会被云驱动移除 + + +### node.kubernetes.io/pid-pressure {#node-kubernetes-io-pid-pressure} + +例子：`node.kubernetes.io/pid-pressure:NoSchedule` + +kubelet 检查 `/proc/sys/kernel/pid_max` 大小的 D 值和 Kubernetes 在 Node 上消耗的 PID， +以获取可用 PID 数量，并将其作为 `pid.available` 指标值。 +然后该指标与在 kubelet 上设置的相应阈值进行比较，以确定是否应该添加/删除 Node 状况和污点。 + + +### node.cloudprovider.kubernetes.io/uninitialized {#node-cloudprovider-kubernetes-io-shutdown} + +例子：`node.cloudprovider.kubernetes.io/uninitialized:NoSchedule` + +在使用“外部”云驱动启动 kubelet 时，在 Node 上设置此污点以将其标记为不可用，直到来自 +cloud-controller-manager 的控制器初始化此 Node，然后移除污点。 + + +### node.cloudprovider.kubernetes.io/shutdown {#node-cloudprovider-kubernetes-io-shutdown} + +例子：`node.cloudprovider.kubernetes.io/shutdown:NoSchedule` + +如果 Node 处于云驱动所指定的关闭状态，则 Node 会相应地被设置污点，对应的污点和效果为 +`node.cloudprovider.kubernetes.io/shutdown` 和 `NoSchedule`。 + + +### pod-security.kubernetes.io/enforce {#pod-security-kubernetes-io-enforce} + +例子：`pod-security.kubernetes.io/enforce: baseline` + +用于：Namespace + +值**必须**是 `privileged`、`baseline` 或 `restricted` 之一，它们对应于 +[Pod 安全标准](/zh/docs/concepts/security/pod-security-standards) 级别。 +特别地，`enforce` 标签 **禁止** 在带标签的 Namespace 中创建任何不符合指示级别要求的 Pod。 + +请请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### pod-security.kubernetes.io/enforce-version {#pod-security-kubernetes-io-enforce-version} + +例子：`pod-security.kubernetes.io/enforce-version: {{< skew latestVersion >}}` + +用于：Namespace + +值**必须**是 `latest` 或格式为 `v.` 的有效 Kubernetes 版本。 +此注解决定了在验证提交的 Pod 时要应用的 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards)策略的版本。 + +请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### pod-security.kubernetes.io/audit {#pod-security-kubernetes-io-audit} + +例子：`pod-security.kubernetes.io/audit: baseline` + +用于：Namespace + +值**必须**是与 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards) 级别相对应的 +`privileged`、`baseline` 或 `restricted` 之一。 +具体来说，`audit` 标签不会阻止在带标签的 Namespace 中创建不符合指示级别要求的 Pod， +但会向该 Pod 添加审计注解。 + +请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### pod-security.kubernetes.io/audit-version {#pod-security-kubernetes-io-audit-version} + +例子：`pod-security.kubernetes.io/audit-version: {{< skew latestVersion >}}` + +用于：Namespace + +值**必须**是 `latest` 或格式为 `v.` 的有效 Kubernetes 版本。 +此注解决定了在验证提交的 Pod 时要应用的 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards)策略的版本。 + +请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### pod-security.kubernetes.io/warn {#pod-security-kubernetes-io-warn} + +例子：`pod-security.kubernetes.io/warn: baseline` + +用于：Namespace + +值**必须**是与 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards)级别相对应的 +`privileged`、`baseline` 或 `restricted` 之一。特别地， +`warn` 标签不会阻止在带标签的 Namespace 中创建不符合指示级别概述要求的 Pod，但会在这样做后向用户返回警告。 +请注意，在创建或更新包含 Pod 模板的对象时也会显示警告，例如 Deployment、Jobs、StatefulSets 等。 + +请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### pod-security.kubernetes.io/warn-version {#pod-security-kubernetes-io-warn-version} + +例子：`pod-security.kubernetes.io/warn-version: {{< skew latestVersion >}}` + +用于：Namespace + +值**必须**是 `latest` 或格式为 `v.` 的有效 Kubernetes 版本。 +此注解决定了在验证提交的 Pod 时要应用的 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards)策略的版本。 +请注意，在创建或更新包含 Pod 模板的对象时也会显示警告， +例如 Deployment、Jobs、StatefulSets 等。 + +请参阅[在名字空间级别实施 Pod 安全性](/zh/docs/concepts/security/pod-security-admission)了解更多信息。 + + +### seccomp.security.alpha.kubernetes.io/pod (已弃用) {#seccomp-security-alpha-kubernetes-io-pod} + +此注解自 Kubernetes v1.19 起已被弃用，将在 v1.25 中失效。 +要为 Pod 指定安全设置，请在 Pod 规范中包含 `securityContext` 字段。 +Pod 的 `.spec` 中的 [`securityContext`](/zh/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context) +字段定义了 Pod 级别的安全属性。 +你[为 Pod 设置安全上下文](/zh/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) 时， +你所给出的设置适用于该 Pod 中的所有容器。 + + +### container.seccomp.security.alpha.kubernetes.io/[NAME] {#container-seccomp-security-alpha-kubernetes-io} + +此注解自 Kubernetes v1.19 起已被弃用，将在 v1.25 中失效。 +教程[使用 seccomp 限制容器的系统调用](/zh/docs/tutorials/clusters/seccomp/)将引导你完成将 +seccomp 配置文件应用于 Pod 或其容器的步骤。 +该教程介绍了在 Kubernetes 中配置 seccomp 的支持机制，基于在 Pod 的 `.spec` 中设置 `securityContext`。 + + +## 用于审计的注解 {#annonations-used-for-audit} + +- [`pod-security.kubernetes.io/exempt`](/zh/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-exempt) +- [`pod-security.kubernetes.io/enforce-policy`](/zh/zh/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-enforce-policy) +- [`pod-security.kubernetes.io/audit-violations`](/zh/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-audit-violations) + +在[审计注解](/zh/docs/reference/labels-annotations-taints/audit-annotations/)页面上查看更多详细信息。 \ No newline at end of file diff --git a/content/zh/docs/reference/labels-annotations-taints/audit-annotations.md b/content/zh/docs/reference/labels-annotations-taints/audit-annotations.md new file mode 100644 index 0000000000..2ab584e4ed --- /dev/null +++ b/content/zh/docs/reference/labels-annotations-taints/audit-annotations.md @@ -0,0 +1,102 @@ +--- +title: "审计注解" +weight: 1 +--- + + + + +该页面作为 kubernetes.io 名字空间的审计注解的参考。这些注解适用于 API 组 `audit.k8s.io` 中的 `Event` 对象。 + + +{{< note >}} +Kubernetes API 中不使用以下注解。当你在集群中[启用审计](/zh/docs/tasks/debug-application-cluster/audit/)时， +审计事件数据将使用 API 组 `audit.k8s.io` 中的 `Event` 写入。 +注解适用于审计事件。审计事件不同于[事件 API ](/zh/docs/reference/kubernetes-api/cluster-resources/event-v1/) +（API 组 `events.k8s.io`）中的对象。 +{{}} + + + +## pod-security.kubernetes.io/exempt {#pod-security-kubernetes-io-exempt} + +例子：`pod-security.kubernetes.io/exempt: namespace` + +值**必须**是对应于 [Pod 安全豁免](/zh/docs/concepts/security/pod-security-admission/#exemptions)维度的 +`user`、`namespace` 或 `runtimeClass` 之一。 +此注解指示 PodSecurity 基于哪个维度的强制豁免执行。 + + +## pod-security.kubernetes.io/enforce-policy {#pod-security-kubernetes-io-enforce-policy} + +例子：`pod-security.kubernetes.io/enforce-policy: restricted:latest` + +值**必须**是对应于 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards) 级别的 +`privileged:<版本>`、`baseline:<版本>`、`restricted:<版本>`， +关联的版本**必须**是 `latest` 或格式为 `v.` 的有效 Kubernetes 版本。 +此注解通知有关在 PodSecurity 准入期间允许或拒绝 Pod 的执行级别。 + +有关详细信息，请参阅 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards/)。 + + +## pod-security.kubernetes.io/audit-violations {#pod-security-kubernetes-io-audit-violations} + +例子：`pod-security.kubernetes.io/audit-violations: would violate +PodSecurity "restricted:latest": allowPrivilegeEscalation != false (container +"example" must set securityContext.allowPrivilegeEscalation=false), ...` + +注解值给出审计策略违规的详细说明，它包含所违反的 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards/)级别以及 +PodSecurity 执行中违反的特定策略及对应字段。 + +有关详细信息，请参阅 [Pod 安全标准](/zh/docs/concepts/security/pod-security-standards/)。 \ No newline at end of file diff --git a/content/zh/docs/reference/scheduling/policies.md b/content/zh/docs/reference/scheduling/policies.md index 41f115be08..dbc6a95860 100644 --- a/content/zh/docs/reference/scheduling/policies.md +++ b/content/zh/docs/reference/scheduling/policies.md @@ -1,209 +1,42 @@ --- title: 调度策略 content_type: concept -weight: 10 +sitemap: + priority: 0.2 # Scheduling priorities are deprecated --- - - - -{{< glossary_tooltip text="kube-scheduler" term_id="kube-scheduler" >}} -根据调度策略指定的*断言（predicates）*和*优先级（priorities）* -分别对节点进行[过滤和打分](/zh/docs/concepts/scheduling-eviction/kube-scheduler/#kube-scheduler-implementation)。 - - -你可以通过执行 `kube-scheduler --policy-config-file ` 或 -`kube-scheduler --policy-configmap ` -设置并使用[调度策略](/zh/docs/reference/config-api/kube-scheduler-policy-config.v1/)。 - - - - - -## 断言 {#predicates} - - - -以下*断言*实现了过滤接口： - - -- `PodFitsHostPorts`：检查 Pod 请求的端口（网络协议类型）在节点上是否可用。 - - -- `PodFitsHost`：检查 Pod 是否通过主机名指定了 Node。 - - -- `PodFitsResources`：检查节点的空闲资源（例如，CPU和内存）是否满足 Pod 的要求。 - - -- `MatchNodeSelector`：检查 Pod 的节点{{< glossary_tooltip text="选择算符" term_id="selector" >}} - 和节点的 {{< glossary_tooltip text="标签" term_id="label" >}} 是否匹配。 - - -- `NoVolumeZoneConflict`：给定该存储的故障区域限制， - 评估 Pod 请求的{{< glossary_tooltip text="卷" term_id="volume" >}}在节点上是否可用。 - - -- `NoDiskConflict`：根据 Pod 请求的卷是否在节点上已经挂载，评估 Pod 和节点是否匹配。 - - -- `MaxCSIVolumeCount`：决定附加 {{< glossary_tooltip text="CSI" term_id="csi" >}} 卷的数量，判断是否超过配置的限制。 - - -- `PodToleratesNodeTaints`：检查 Pod 的{{< glossary_tooltip text="容忍" term_id="toleration" >}} - 是否能容忍节点的{{< glossary_tooltip text="污点" term_id="taint" >}}。 - - -- `CheckVolumeBinding`：基于 Pod 的卷请求，评估 Pod 是否适合节点，这里的卷包括绑定的和未绑定的 - {{< glossary_tooltip text="PVCs" term_id="persistent-volume-claim" >}} 都适用。 - - - -## 优先级 {#priorities} - - -以下*优先级*实现了打分接口： - - -- `SelectorSpreadPriority`：属于同一 {{< glossary_tooltip text="Service" term_id="service" >}}、 - {{< glossary_tooltip term_id="statefulset" >}} 或 - {{< glossary_tooltip term_id="replica-set" >}} 的 Pod，跨主机部署。 - - -- `InterPodAffinityPriority`：实现了 [Pod 间亲和性与反亲和性](/zh/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity)的优先级。 - -- `LeastRequestedPriority`：偏向最少请求资源的节点。 - 换句话说，节点上的 Pod 越多，使用的资源就越多，此策略给出的排名就越低。 - - -- `MostRequestedPriority`：支持最多请求资源的节点。 - 该策略将 Pod 调度到整体工作负载所需的最少的一组节点上。 - - -- `RequestedToCapacityRatioPriority`：使用默认的打分方法模型，创建基于 ResourceAllocationPriority 的 requestedToCapacity。 - - -- `BalancedResourceAllocation`：偏向平衡资源使用的节点。 - - -- `NodePreferAvoidPodsPriority`：根据节点的注解 `scheduler.alpha.kubernetes.io/preferAvoidPods` 对节点进行优先级排序。 - 你可以使用它来暗示两个不同的 Pod 不应在同一节点上运行。 - - -- `NodeAffinityPriority`：根据节点亲和中 PreferredDuringSchedulingIgnoredDuringExecution 字段对节点进行优先级排序。 - 你可以在[将 Pod 分配给节点](/zh/docs/concepts/scheduling-eviction/assign-pod-node/)中了解更多。 - - -- `TaintTolerationPriority`：根据节点上无法忍受的污点数量，给所有节点进行优先级排序。 - 此策略会根据排序结果调整节点的等级。 - - -- `ImageLocalityPriority`：偏向已在本地缓存 Pod 所需容器镜像的节点。 - - -- `ServiceSpreadingPriority`：对于给定的 Service，此策略旨在确保该 Service 关联的 Pod 在不同的节点上运行。 - 它偏向把 Pod 调度到没有该服务的节点。 - 整体来看，Service 对于单个节点故障变得更具弹性。 - - -- `EqualPriority`：给予所有节点相等的权重。 - - -- `EvenPodsSpreadPriority`：实现了 [Pod 拓扑扩展约束](/zh/docs/concepts/workloads/pods/pod-topology-spread-constraints/)的优先级排序。 +在 Kubernetes v1.23 版本之前，可以使用调度策略来指定 *predicates* 和 *priorities* 进程。 +例如，可以通过运行 `kube-scheduler --policy-config-file ` 或者 + `kube-scheduler --policy-configmap ` 设置调度策略。 +但是从 Kubernetes v1.23 版本开始，不再支持这种调度策略。 +同样地也不支持相关的 `policy-config-file`、 `policy-configmap`、 `policy-configmap-namespace` 以及 `use-legacy-policy-config` 标志。 +你可以通过使用 [调度配置](/zh/docs/reference/scheduling/config/)来实现类似的行为。 ## {{% heading "whatsnext" %}} - -* 了解[调度](/zh/docs/concepts/scheduling-eviction/kube-scheduler/) -* 了解 [kube-scheduler 配置](/zh/docs/reference/scheduling/config/) -* 阅读 [kube-scheduler 配置参考 (v1beta1)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta2) -* 阅读 [kube-scheduler 策略参考 (v1)](/zh/docs/reference/config-api/kube-scheduler-policy-config.v1/) + +* 了解 [调度](/zh/docs/concepts/scheduling-eviction/kube-scheduler/)。 +* 了解 [kube-scheduler 配置](/zh/docs/reference/scheduling/config/)。 +* 阅读 [kube-scheduler 配置参考(v1beta3)](/zh/docs/reference/config-api/kube-scheduler-config.v1beta3/)。 + diff --git a/content/zh/docs/setup/learning-environment/_index.md b/content/zh/docs/setup/learning-environment/_index.md index f68e52a439..e7d409c1b6 100644 --- a/content/zh/docs/setup/learning-environment/_index.md +++ b/content/zh/docs/setup/learning-environment/_index.md @@ -11,41 +11,3 @@ weight: 20 {{/* If you're localizing this page, you only need to copy the front matter */}} {{/* and add a redirect into "/static/_redirects", for YOUR localization. */}} --> - -## kind - - -你可以使用 [`kind`](https://kind.sigs.k8s.io/docs/) 来在本地计算机上运行 Kubernetes。 -此工具要求你已经安装并配置了 [Docker](https://docs.docker.com/get-docker/)。 - -kind [快速入门](https://kind.sigs.k8s.io/docs/user/quick-start/)页面 -为你展示了如何开始使用 kind 的相关信息。 - -## minikube - - -与 `kind` 类似，[`minikube`](https://minikube.sigs.k8s.io/) 是一个允许你在 -本地运行 Kubernetes 的工具。`minikube` 在你的个人计算机上运行一个单节点的 -Kubernetes 集群（包括 Windows、macOS 和 Linux PC 机），这样你可以尝试 -Kubernetes 或者执行每天的开发工作。 - -如果你所关注的是如何安装该工具，可以查阅官方的 -[Get Started!](https://minikube.sigs.k8s.io/docs/start/) -文档。 - diff --git a/content/zh/docs/setup/production-environment/tools/kops.md b/content/zh/docs/setup/production-environment/tools/kops.md index 94b448361a..73b322da64 100644 --- a/content/zh/docs/setup/production-environment/tools/kops.md +++ b/content/zh/docs/setup/production-environment/tools/kops.md @@ -410,12 +410,12 @@ See the [list of add-ons](/docs/concepts/cluster-administration/addons/) to expl ## {{% heading "whatsnext" %}} * 了解有关 Kubernetes 的[概念](/zh/docs/concepts/) 和 - [`kubectl`](/zh/docs/reference/kubectl/overview/) 有关的更多信息。 + [`kubectl`](/zh/docs/reference/kubectl/) 有关的更多信息。 * 了解 `kops` [高级用法](https://github.com/kubernetes/kops)。 * 请参阅 `kops` [文档](https://github.com/kubernetes/kops) 获取教程、 最佳做法和高级配置选项。 diff --git a/content/zh/docs/tasks/access-application-cluster/access-cluster.md b/content/zh/docs/tasks/access-application-cluster/access-cluster.md index 706afa0779..1dd18f0c90 100644 --- a/content/zh/docs/tasks/access-application-cluster/access-cluster.md +++ b/content/zh/docs/tasks/access-application-cluster/access-cluster.md @@ -1,4 +1,4 @@ ---- +--- title: 访问集群 weight: 20 content_type: concept @@ -50,10 +50,10 @@ kubectl config view 有许多 [例子](/zh/docs/reference/kubectl/cheatsheet/) 介绍了如何使用 kubectl， -可以在 [kubectl手册](/zh/docs/reference/kubectl/overview/) 中找到更完整的文档。 +可以在 [kubectl 参考](/zh/docs/reference/kubectl/overview/) 中找到更完整的文档。 + ### 不使用 kubectl proxy 在 Kubernetes 1.3 或更高版本中，`kubectl config view` 不再显示 token。 -使用 `kubectl describe secret ...` 来获取默认服务帐户的 token，如下所示： - +使用 `kubectl apply` 和 `kubectl describe secret ...` 及 grep 和剪切操作来为 default 服务帐户创建令牌，如下所示： `grep/cut` 方法实现： +首先，创建 Secret，请求默认 ServiceAccount 的令牌： +```shell +kubectl apply -f - < +接下来，等待令牌控制器使用令牌填充 Secret： +```shell +while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do + echo "waiting for token..." >&2 + sleep 1 +done +``` + +捕获并使用生成的令牌： ```shell APISERVER=$(kubectl config view | grep server | cut -f 2- -d ":" | tr -d " ") -TOKEN=$(kubectl describe secret $(kubectl get secrets | grep default | cut -f1 -d ' ') | 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 ``` ```json @@ -172,7 +201,7 @@ curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure ```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 ) +TOKEN=$(kubectl get secret default-token -o jsonpath='{.data.token}' | base64 --decode ) curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure ``` diff --git a/content/zh/docs/tasks/access-application-cluster/web-ui-dashboard.md b/content/zh/docs/tasks/access-application-cluster/web-ui-dashboard.md index 70becf1797..e19888913f 100644 --- a/content/zh/docs/tasks/access-application-cluster/web-ui-dashboard.md +++ b/content/zh/docs/tasks/access-application-cluster/web-ui-dashboard.md @@ -9,7 +9,9 @@ card: --- #### 手动构建 API 服务器代理 URLs {#manually-constructing-apiserver-proxy-urls} @@ -160,6 +170,15 @@ If you haven't specified a name for your port, you don't have to specify *port_n `http://`*`kubernetes_master_address`*`/api/v1/namespaces/`*`namespace_name`*`/services/`*`service_name[:port_name]`*`/proxy` 如果还没有为你的端口指定名称，你可以不用在 URL 中指定 *port_name*。 +对于命名和未命名端口，你还可以使用端口号代替 *port_name*。 + +默认情况下，API 服务器使用 HTTP 为你的服务提供代理。 要使用 HTTPS，请在服务名称前加上 `https:`： +`http:///api/v1/namespaces//services//proxy` +URL 的 `` 段支持的格式为： +* `` - 使用 http 代理到默认或未命名端口 +* `:` - 使用 http 代理到指定的端口名称或端口号 +* `https::` - 使用 https 代理到默认或未命名端口（注意尾随冒号） +* `https::` - 使用 https 代理到指定的端口名称或端口号 +## 升级 etcd 集群 +有关 etcd 升级的更多详细信息，请参阅 [etcd 升级](https://etcd.io/docs/latest/upgrades/)文档。 +{{< note >}} +在开始升级之前，请先备份你的 etcd 集群。 +{{< /note >}} + diff --git a/content/zh/docs/tasks/administer-cluster/developing-cloud-controller-manager.md b/content/zh/docs/tasks/administer-cluster/developing-cloud-controller-manager.md index 96cb157012..6b47fa7b01 100644 --- a/content/zh/docs/tasks/administer-cluster/developing-cloud-controller-manager.md +++ b/content/zh/docs/tasks/administer-cluster/developing-cloud-controller-manager.md @@ -16,7 +16,7 @@ content_type: concept {{< feature-state for_k8s_version="v1.11" state="beta" >}} -{{< glossary_definition term_id="cloud-controller-manager" length="all" prepend="组件 cloud-controller-manager 是">}} +{{< glossary_definition term_id="cloud-controller-manager" length="all">}} @@ -27,44 +27,43 @@ Since cloud providers develop and release at a different pace compared to the Ku --> ## 背景 -由于云驱动的开发和发布与 Kubernetes 项目本身步调不同，将特定于云环境 -的代码抽象到 `cloud-controller-manager` 二进制组件有助于云厂商独立于 -Kubernetes 核心代码推进其驱动开发。 +由于云驱动的开发和发布与 Kubernetes 项目本身步调不同，将特定于云环境的代码抽象到 +`cloud-controller-manager` 二进制组件有助于云厂商独立于 Kubernetes +核心代码推进其驱动开发。 -Kubernetes 项目提供 cloud-controller-manager 的框架代码，其中包含 Go -语言的接口，便于你（或者你的云驱动提供者）接驳你自己的实现。 -这意味着每个云驱动可以通过从 Kubernetes 核心代码导入软件包来实现一个 -cloud-controller-manager；每个云驱动会通过调用 -`cloudprovider.RegisterCloudProvider` 接口来注册其自身实现代码，从而更新 -记录可用云驱动的全局变量。 +Kubernetes 项目提供 cloud-controller-manager 的框架代码，其中包含 Go 语言的接口， +便于你（或者你的云驱动提供者）接驳你自己的实现。这意味着每个云驱动可以通过从 +Kubernetes 核心代码导入软件包来实现一个 cloud-controller-manager； +每个云驱动会通过调用 `cloudprovider.RegisterCloudProvider` 接口来注册其自身实现代码， +从而更新一个用来记录可用云驱动的全局变量。 ## 开发 -### Out of Tree +### 树外（Out of Tree） -要为你的云环境构建一个 out-of-tree 云控制器管理器： +要为你的云环境构建一个树外（Out-of-Tree）云控制器管理器： -1. 使用满足 [cloudprovider.Interface](https://github.com/kubernetes/cloud-provider/blob/master/cloud.go) - 的实现创建一个 Go 语言包。 +1. 使用满足 [`cloudprovider.Interface`](https://github.com/kubernetes/cloud-provider/blob/master/cloud.go) + 接口的实现来创建一个 Go 语言包。 2. 使用来自 Kubernetes 核心代码库的 [cloud-controller-manager 中的 main.go](https://github.com/kubernetes/kubernetes/blob/master/cmd/cloud-controller-manager/main.go) - 作为 main.go 的模板。如上所述，唯一的区别应该是将导入的云包。 + 作为 `main.go` 的模板。如上所述，唯一的区别应该是将导入的云包不同。 3. 在 `main.go` 中导入你的云包，确保你的包有一个 `init` 块来运行 - [cloudprovider.RegisterCloudProvider](https://github.com/kubernetes/cloud-provider/blob/master/plugins.go)。 + [`cloudprovider.RegisterCloudProvider`](https://github.com/kubernetes/cloud-provider/blob/master/plugins.go)。 很多云驱动都将其控制器管理器代码以开源代码的形式公开。 -如果你在开发一个新的 cloud-controller-manager，你可以选择某个 out-of-tree +如果你在开发一个新的 cloud-controller-manager，你可以选择某个树外（Out-of-Tree） 云控制器管理器作为出发点。 -### In Tree +### 树内（In Tree） -对于 in-tree 驱动，你可以将 in-tree 云控制器管理器作为群集中的 -{{< glossary_tooltip term_id="daemonset" text="Daemonset" >}} 来运行。 +对于树内（In-Tree）驱动，你可以将树内云控制器管理器作为集群中的 +{{< glossary_tooltip term_id="daemonset" text="DaemonSet" >}} 来运行。 有关详细信息，请参阅[云控制器管理器管理](/zh/docs/tasks/administer-cluster/running-cloud-controller/)。 diff --git a/content/zh/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes.md b/content/zh/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes.md index bce123e306..4e08ce2c60 100644 --- a/content/zh/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes.md +++ b/content/zh/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes.md @@ -289,10 +289,10 @@ Install-WindowsFeature -Name containers ``` 安装 Docker -操作指南在 [Install Docker Engine - Enterprise on Windows Servers](https://hub.docker.com/editions/enterprise/docker-ee-server-windows)。 +操作指南在 [Install Docker Engine - Enterprise on Windows Servers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server#install-docker)。 -标志设置的值是一个按 NUMA 节点所给的内存预留的值的列表，用逗号分开。 +标志设置的值是一个按 NUMA 节点的不同内存类型所给的内存预留的值的列表，用逗号分开。 +可以使用分号作为分隔符来指定跨多个 NUMA 节点的内存预留。 只有在内存管理器特性被启用的语境下，这个参数才有意义。 内存管理器不会使用这些预留的内存来为容器负载分配内存。 @@ -426,7 +428,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' ``` 自从 Kubernetes 1.20 宣布 [弃用 dockershim](/zh/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)， 各类疑问随之而来：这对各类工作负载和 Kubernetes 部署会产生什么影响。 -你会发现这篇博文对于更好地理解此问题非常有用： -[弃用 Dockershim 常见问题](/zh/blog/2020/12/02/dockershim-faq/) +我们的[弃用 Dockershim 常见问题](/blog/2022/02/17/dockershim-faq/)可以帮助你更好地理解这个问题。 本页讲解你的集群把 Docker 用作容器运行时的运作机制， 并提供使用 `dockershim` 时，它所扮演角色的详细信息， -继而展示了一组验证步骤，可用来检查弃用 `dockershim` 对你的工作负载的影响。 +继而展示了一组操作，可用来检查弃用 `dockershim` 对你的工作负载是否有影响。 -虽然你通过 Docker 创建了应用容器，但这些容器却可以运行于所有容器运行时。 -所以这种使用 Docker 容器运行时的方式并不构成对 Docker 的依赖。 +即使你是通过 Docker 创建的应用容器，也不妨碍你在其他任何容器运行时上运行这些容器。 +这种使用 Docker 的方式并不构成对 Docker 作为一个容器运行时的依赖。 -当用了替代的容器运行时之后，Docker 命令可能不工作，甚至产生意外的输出。 -这才是判定你是否依赖于 Docker 的方法。 +当用了别的容器运行时之后，Docker 命令可能不工作，或者产生意外的输出。 +下面是判定你是否依赖于 Docker 的方法。 1. 确认没有特权 Pod 执行 Docker 命令（如 `docker ps`）、重新启动 Docker - 服务（如 `systemctl restart docker.service`）或修改 - Docker 配置文件 `/etc/docker/daemon.json`。 + 服务（如 `systemctl restart docker.service`）或修改 Docker 配置文件 + `/etc/docker/daemon.json`。 2. 检查 Docker 配置文件（如 `/etc/docker/daemon.json`）中容器镜像仓库的镜像（mirror）站点设置。 这些配置通常需要针对不同容器运行时来重新设置。 -3. 检查确保在 Kubernetes 基础设施之外的节点上运行的脚本和应用程序没有执行Docker命令。 +3. 检查确保在 Kubernetes 基础设施之外的节点上运行的脚本和应用程序没有执行 Docker 命令。 可能的情况如： - SSH 到节点排查故障； - 节点启动脚本； - 直接安装在节点上的监控和安全代理。 -4. 检查执行上述特权操作的第三方工具。详细操作请参考： - [从 dockershim 迁移遥测和安全代理](/zh/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents) +4. 检查执行上述特权操作的第三方工具。详细操作请参考 + [从 dockershim 迁移遥测和安全代理](/zh/docs/tasks/administer-cluster/migrating-from-dockershim/migrating-telemetry-and-security-agents)。 5. 确认没有对 dockershim 行为的间接依赖。这是一种极端情况，不太可能影响你的应用。 - 一些工具很可能被配置为使用了 Docker 特性，比如，基于特定指标发警报，或者在故障排查指令的一个环节中搜索特定的日志信息。 - 如果你有此类配置的工具，需要在迁移之前，在测试集群上完成功能验证。 + 一些工具很可能被配置为使用了 Docker 特性，比如，基于特定指标发警报， + 或者在故障排查指令的一个环节中搜索特定的日志信息。 + 如果你有此类配置的工具，需要在迁移之前，在测试集群上测试这类行为。 [容器运行时](/zh/docs/concepts/containers/#container-runtimes)是一个软件，用来运行组成 Kubernetes Pod 的容器。 -Kubernetes 负责编排和调度 Pod；在每一个节点上， -{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} +Kubernetes 负责编排和调度 Pod；在每一个节点上，{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} 使用抽象的容器运行时接口，所以你可以任意选用兼容的容器运行时。 你可以阅读博文 -[Kubernetes 容器集成功能的正式发布](/zh/blog/2018/05/24/kubernetes-containerd-integration-goes-ga/) +[Kubernetes 正式支持集成 Containerd](/zh/blog/2018/05/24/kubernetes-containerd-integration-goes-ga/)。 ![Dockershim 和 Containerd CRI 的实现对比图](/images/blog/2018-05-24-kubernetes-containerd-integration-goes-ga/cri-containerd.png) @@ -138,8 +138,8 @@ So any Docker tooling or fancy UI you might have used before to check on these containers is no longer available. --> 切换到容器运行时 Containerd 可以消除掉中间环节。 -所有以前遗留的容器可由 Containerd 这类容器运行时来运行和管理，操作体验也和以前一样。 -但是现在，由于直接用容器运行时调度容器，所以它们对 Docker 来说是不可见的。 +所有相同的容器都可由 Containerd 这类容器运行时来运行。 +但是现在，由于直接用容器运行时调度容器，它们对 Docker 是不可见的。 因此，你以前用来检查这些容器的 Docker 工具或漂亮的 UI 都不再可用。 {{< note >}} - -如果你用 Kubernetes 运行工作负载，最好通过 Kubernetes API停止容器，而不是通过容器运行时 +如果你在用 Kubernetes 运行工作负载，最好通过 Kubernetes API 停止容器， +而不是通过容器运行时来停止它们 （此建议适用于所有容器运行时，不仅仅是针对 Docker）。 - {{< /note >}} 你仍然可以下载镜像，或者用 `docker build` 命令创建它们。 但用 Docker 创建、下载的镜像，对于容器运行时和 Kubernetes，均不可见。 -为了在 Kubernetes 中使用，需要把镜像推送（push）到某注册中心。 +为了在 Kubernetes 中使用，需要把镜像推送（push）到某镜像仓库。 + diff --git a/content/zh/docs/tasks/administer-cluster/nodelocaldns.md b/content/zh/docs/tasks/administer-cluster/nodelocaldns.md index 46d92d0c8f..b68fd3ed1e 100644 --- a/content/zh/docs/tasks/administer-cluster/nodelocaldns.md +++ b/content/zh/docs/tasks/administer-cluster/nodelocaldns.md @@ -1,18 +1,13 @@ --- -reviewers: -- bowei -- zihongz title: 在 Kubernetes 集群中使用 NodeLocal DNSCache content_type: task --- @@ -22,14 +17,10 @@ This page provides an overview of NodeLocal DNSCache feature in Kubernetes. --> 本页概述了 Kubernetes 中的 NodeLocal DNSCache 功能。 - - ## {{% heading "prerequisites" %}} - {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} - -NodeLocal DNSCache 通过在集群节点上作为 DaemonSet 运行 dns 缓存代理来提高集群 DNS 性能。 -在当今的体系结构中，处于 ClusterFirst DNS 模式的 Pod 可以连接到 kube-dns serviceIP 进行 DNS 查询。 +NodeLocal DNSCache 通过在集群节点上作为 DaemonSet 运行 DNS 缓存代理来提高集群 DNS 性能。 +在当今的体系结构中，运行在 ClusterFirst DNS 模式下的 Pod 可以连接到 kube-dns `serviceIP` 进行 DNS 查询。 通过 kube-proxy 添加的 iptables 规则将其转换为 kube-dns/CoreDNS 端点。 -借助这种新架构，Pods 将可以访问在同一节点上运行的 dns 缓存代理，从而避免了 iptables DNAT 规则和连接跟踪。 -本地缓存代理将查询 kube-dns 服务以获取集群主机名的缓存缺失（默认为 cluster.local 后缀）。 +借助这种新架构，Pods 将可以访问在同一节点上运行的 DNS 缓存代理，从而避免 iptables DNAT 规则和连接跟踪。 +本地缓存代理将查询 kube-dns 服务以获取集群主机名的缓存缺失（默认为 "`cluster.local`" 后缀）。 -* 使用当前的 DNS 体系结构，如果没有本地 kube-dns/CoreDNS 实例，则具有最高 DNS QPS 的 Pod 可能必须延伸到另一个节点。 -在这种脚本下，拥有本地缓存将有助于改善延迟。 +* 使用当前的 DNS 体系结构，如果没有本地 kube-dns/CoreDNS 实例，则具有最高 DNS QPS + 的 Pod 可能必须延伸到另一个节点。 + 在这种场景下，拥有本地缓存将有助于改善延迟。 -* 跳过 iptables DNAT 和连接跟踪将有助于减少 [conntrack 竞争](https://github.com/kubernetes/kubernetes/issues/56903)并避免 UDP DNS 条目填满 conntrack 表。 +* 跳过 iptables DNAT 和连接跟踪将有助于减少 + [conntrack 竞争](https://github.com/kubernetes/kubernetes/issues/56903) + 并避免 UDP DNS 条目填满 conntrack 表。 -* 从本地缓存代理到 kube-dns 服务的连接可以升级到 TCP 。 -TCP conntrack 条目将在连接关闭时被删除，相反 UDP 条目必须超时([默认](https://www.kernel.org/doc/Documentation/networking/nf_conntrack-sysctl.txt) `nf_conntrack_udp_timeout` 是 30 秒) +* 从本地缓存代理到 kube-dns 服务的连接可以升级为 TCP 。 + TCP conntrack 条目将在连接关闭时被删除，相反 UDP 条目必须超时 + （[默认](https://www.kernel.org/doc/Documentation/networking/nf_conntrack-sysctl.txt) + `nf_conntrack_udp_timeout` 是 30 秒）。 -* 将 DNS 查询从 UDP 升级到 TCP 将减少归因于丢弃的 UDP 数据包和 DNS 超时的尾部等待时间，通常长达 30 秒（3 次重试+ 10 秒超时）。 +* 将 DNS 查询从 UDP 升级到 TCP 将减少由于被丢弃的 UDP 包和 DNS 超时而带来的尾部等待时间； + 这类延时通常长达 30 秒（3 次重试 + 10 秒超时）。 + 由于 nodelocal 缓存监听 UDP DNS 查询，应用不需要变更。 -* 在节点级别对 dns 请求的度量和可见性。 +* 在节点级别对 DNS 请求的度量和可见性。 -启用 NodeLocal DNSCache 之后，这是 DNS 查询所遵循的路径： - +启用 NodeLocal DNSCache 之后，DNS 查询所遵循的路径如下： -{{< figure src="/images/docs/nodelocaldns.svg" alt="NodeLocal DNSCache 流" title="Nodelocal DNSCache 流" caption="此图显示了 NodeLocal DNSCache 如何处理 DNS 查询。" >}} +{{< figure src="/images/docs/nodelocaldns.svg" alt="NodeLocal DNSCache 流" title="Nodelocal DNSCache 流" caption="此图显示了 NodeLocal DNSCache 如何处理 DNS 查询。" class="diagram-medium" >}} {{< note >}} NodeLocal DNSCache 的本地侦听 IP 地址可以是任何地址，只要该地址不和你的集群里现有的 IP 地址发生冲突。 -推荐使用本地范围内的地址，例如，IPv4 链路本地区段 169.254.0.0/16 内的地址， -或者 IPv6 唯一本地地址区段 fd00::/8 内的地址。 +推荐使用本地范围内的地址，例如，IPv4 链路本地区段 '169.254.0.0/16' 内的地址， +或者 IPv6 唯一本地地址区段 'fd00::/8' 内的地址。 {{< /note >}} * 如果使用 IPv6，在使用 IP:Port 格式的时候需要把 CoreDNS 配置文件里的所有 IPv6 地址用方括号包起来。 - 如果你使用上述的示例清单，需要把 [配置行 L70](https://github.com/kubernetes/kubernetes/blob/b2ecd1b3a3192fbbe2b9e348e095326f51dc43dd/cluster/addons/dns/nodelocaldns/nodelocaldns.yaml#L70) + 如果你使用上述的示例清单，需要把 + [配置行 L70](https://github.com/kubernetes/kubernetes/blob/b2ecd1b3a3192fbbe2b9e348e095326f51dc43dd/cluster/addons/dns/nodelocaldns/nodelocaldns.yaml#L70) 修改为 `health [__PILLAR__LOCAL__DNS__]:8080`。 * 把清单里的变量更改为正确的值： - * kubedns=`kubectl get svc kube-dns -n kube-system -o jsonpath={.spec.clusterIP}` - * domain=`` + ``` + kubedns=`kubectl get svc kube-dns -n kube-system -o jsonpath={.spec.clusterIP}` + domain= + localdns= + ``` - * localdns=`` - - `` 的默认值是 "cluster.local"。 `` 是 NodeLocal DNSCache 选择的本地侦听 IP 地址。 + `` 的默认值是 "`cluster.local`"。`` 是 + NodeLocal DNSCache 选择的本地侦听 IP 地址。 - * 如果 kube-proxy 运行在 IPTABLES 模式： + * 如果 kube-proxy 运行在 IPTABLES 模式： - ``` bash - sed -i "s/__PILLAR__LOCAL__DNS__/$localdns/g; s/__PILLAR__DNS__DOMAIN__/$domain/g; s/__PILLAR__DNS__SERVER__/$kubedns/g" nodelocaldns.yaml - ``` + ``` bash + sed -i "s/__PILLAR__LOCAL__DNS__/$localdns/g; s/__PILLAR__DNS__DOMAIN__/$domain/g; s/__PILLAR__DNS__SERVER__/$kubedns/g" nodelocaldns.yaml + ``` - node-local-dns Pods 会设置 `__PILLAR__CLUSTER__DNS__` 和 `__PILLAR__UPSTREAM__SERVERS__`。 - 在此模式下, node-local-dns Pods 会同时侦听 kube-dns 服务的 IP 地址和 `` 的地址， - 以便 Pods 可以使用其中任何一个 IP 地址来查询 DNS 记录。 - - * 如果 kube-proxy 运行在 IPVS 模式： + * 如果 kube-proxy 运行在 IPVS 模式： - ``` bash - sed -i "s/__PILLAR__LOCAL__DNS__/$localdns/g; s/__PILLAR__DNS__DOMAIN__/$domain/g; s/__PILLAR__DNS__SERVER__//g; s/__PILLAR__CLUSTER__DNS__/$kubedns/g" nodelocaldns.yaml - ``` + ``` bash + sed -i "s/__PILLAR__LOCAL__DNS__/$localdns/g; s/__PILLAR__DNS__DOMAIN__/$domain/g; s/__PILLAR__DNS__SERVER__//g; s/__PILLAR__CLUSTER__DNS__/$kubedns/g" nodelocaldns.yaml + ``` - 在此模式下，node-local-dns Pods 只会侦听 `` 的地址。 - node-local-dns 接口不能绑定 kube-dns 的集群 IP 地址，因为 IPVS 负载均衡 - 使用的接口已经占用了该地址。 - node-local-dns Pods 会设置 `__PILLAR__UPSTREAM__SERVERS__`。 + 在此模式下，node-local-dns Pods 只会侦听 `` 的地址。 + node-local-dns 接口不能绑定 kube-dns 的集群 IP 地址，因为 IPVS 负载均衡 + 使用的接口已经占用了该地址。 + node-local-dns Pods 会设置 `__PILLAR__UPSTREAM__SERVERS__`。 * 运行 `kubectl create -f nodelocaldns.yaml` -* 如果 kube-proxy 运行在 IPVS 模式，需要修改 kubelet 的 `--cluster-dns` 参数为 NodeLocal DNSCache 正在侦听的 `` 地址。 - 否则，不需要修改 `--cluster-dns` 参数，因为 NodeLocal DNSCache 会同时侦听 kube-dns 服务的 IP 地址和 `` 的地址。 +* 如果 kube-proxy 运行在 IPVS 模式，需要修改 kubelet 的 `--cluster-dns` 参数 + NodeLocal DNSCache 正在侦听的 `` 地址。 + 否则，不需要修改 `--cluster-dns` 参数，因为 NodeLocal DNSCache 会同时侦听 + kube-dns 服务的 IP 地址和 `` 的地址。 启用后，node-local-dns Pods 将在每个集群节点上的 kube-system 名字空间中运行。 -此 Pod 在缓存模式下运行 [CoreDNS](https://github.com/coredns/coredns) ，因此每个节点都可以使用不同插件公开的所有 CoreDNS 指标。 +此 Pod 在缓存模式下运行 [CoreDNS](https://github.com/coredns/coredns) ， +因此每个节点都可以使用不同插件公开的所有 CoreDNS 指标。 + +如果要禁用该功能，你可以使用 `kubectl delete -f ` 来删除 DaemonSet。 +你还应该回滚你对 kubelet 配置所做的所有改动。 + + +## StubDomains 和上游服务器配置 + + +`node-local-dns` Pod 能够自动读取 `kube-system` 名字空间中 `kube-dns` ConfigMap +中保存的 StubDomains 和上游服务器信息。ConfigMap 中的内容需要遵从 +[此示例](/zh/docs/tasks/administer-cluster/dns-custom-nameservers/#example-1) +中所给的格式。 +`node-local-dns` ConfigMap 也可被直接修改，使用 Corefile 格式设置 stubDomain 配置。 +某些云厂商可能不允许直接修改 `node-local-dns` ConfigMap 的内容。 +在这种情况下，可以更新 `kube-dns` ConfigMap。 + + +## 设置内存限制 + + +`node-local-dns` Pod 使用内存来保存缓存项并处理查询。 +由于它们并不监视 Kubernetes 对象变化，集群规模或者 Service/Endpoints +的数量都不会直接影响内存用量。内存用量会受到 DNS 查询模式的影响。 +根据 [CoreDNS 文档](https://github.com/coredns/deployment/blob/master/kubernetes/Scaling_CoreDNS.md), + +> The default cache size is 10000 entries, which uses about 30 MB when completely filled. +> （默认的缓存大小是 10000 个表项，当完全填充时会使用约 30 MB 内存） + + +这一数值是（缓存完全被填充时）每个服务器块的内存用量。 +通过设置小一点的缓存大小可以降低内存用量。 + +并发查询的数量会影响内存需求，因为用来处理查询请求而创建的 Go 协程都需要一定量的内存。 +你可以在 forward 插件中使用 `max_concurrent` 选项设置并发查询数量上限。 + + +如果一个 `node-local-dns` Pod 尝试使用的内存超出可提供的内存量 +（因为系统资源总量的，或者所配置的[资源约束](/zh/docs/concepts/configuration/manage-resources-containers/)）的原因， +操作系统可能会关闭这一 Pod 的容器。 +发生这种情况时，被终止的（"OOMKilled"）容器不会清理其启动期间所添加的定制包过滤规则。 +该 `node-local-dns` 容器应该会被重启（因其作为 DaemonSet 的一部分被管理）， +但因上述原因可能每次容器失败时都会导致 DNS 有一小段时间不可用： +the packet filtering rules direct DNS queries to a local Pod that is unhealthy +（包过滤器规则将 DNS 查询转发到本地某个不健康的 Pod）。 + + +通过不带限制地运行 `node-local-dns` Pod 并度量其内存用量峰值，你可以为其确定一个合适的内存限制值。 +你也可以安装并使用一个运行在 “Recommender Mode（建议者模式）” 的 +[VerticalPodAutoscaler](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler)， +并查看该组件输出的建议信息。 -如果要禁用该功能，你可以使用 `kubectl delete -f ` 来删除 DaemonSet。你还应该恢复你对 kubelet 配置所做的所有改动。 diff --git a/content/zh/docs/tasks/administer-cluster/reserve-compute-resources.md b/content/zh/docs/tasks/administer-cluster/reserve-compute-resources.md index 251de2231e..f26665b416 100644 --- a/content/zh/docs/tasks/administer-cluster/reserve-compute-resources.md +++ b/content/zh/docs/tasks/administer-cluster/reserve-compute-resources.md @@ -166,7 +166,7 @@ flag. It is recommended that the kubernetes system daemons are placed under a top level control group (`runtime.slice` on systemd machines for example). Each system daemon should ideally run within its own child control group. Refer to -[the design proposal](https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md#recommended-cgroups-setup) +[the design proposal](https://git.k8s.io/design-proposals-archive/node/node-allocatable.md#recommended-cgroups-setup) for more details on recommended control group hierarchy. Note that Kubelet **does not** create `--kube-reserved-cgroup` if it doesn't @@ -179,7 +179,7 @@ exist. Kubelet will fail if an invalid cgroup is specified. `runtime.slice`）。 理想情况下每个系统守护进程都应该在其自己的子控制组中运行。 请参考 -[这个设计方案](https://git.k8s.io/community/contributors/design-proposals/node/node-allocatable.md#recommended-cgroups-setup)， +[这个设计方案](https://git.k8s.io/design-proposals-archive/node/node-allocatable.md#recommended-cgroups-setup)， 进一步了解关于推荐控制组层次结构的细节。 请注意，如果 `--kube-reserved-cgroup` 不存在，Kubelet 将 **不会** 创建它。 diff --git a/content/zh/docs/tasks/administer-cluster/safely-drain-node.md b/content/zh/docs/tasks/administer-cluster/safely-drain-node.md index c07c282b78..da8281715e 100644 --- a/content/zh/docs/tasks/administer-cluster/safely-drain-node.md +++ b/content/zh/docs/tasks/administer-cluster/safely-drain-node.md @@ -174,154 +174,16 @@ 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. +For more information, see [API-initiated eviction](/docs/concepts/scheduling-eviction/api-eviction/). --> ## 驱逐 API {#the-eviction-api} 如果你不喜欢使用 [kubectl drain](/docs/reference/generated/kubectl/kubectl-commands/#drain) （比如避免调用外部命令，或者更细化地控制 pod 驱逐过程）， 你也可以用驱逐 API 通过编程的方式达到驱逐的效果。 - - -首先应该熟悉使用 -[Kubernetes 语言客户端](/zh/docs/tasks/administer-cluster/access-cluster-api/#programmatic-access-to-the-api)。 - -Pod 的 Eviction 子资源可以看作是一种策略控制的 DELETE 操作，作用于 Pod 本身。 -要尝试驱逐（更准确地说，尝试 *创建* 一个 Eviction），需要用 POST 发出所尝试的操作。这里有一个例子： - -{{< tabs name="Eviction_example" >}} -{{% tab name="policy/v1" %}} - -{{< note >}} -`policy/v1` 驱逐在 v1.22+ 中可用。在之前版本中请使用 `policy/v1beta1` 。 -{{< /note >}} - - -```json -{ - "apiVersion": "policy/v1", - "kind": "Eviction", - "metadata": { - "name": "quux", - "namespace": "default" - } -} -``` -{{% /tab %}} -{{% tab name="policy/v1beta1" %}} - -{{< note >}} -在 v1.22 中已弃用，以 `policy/v1` 取代 -{{< /note >}} - -```json -{ - "apiVersion": "policy/v1beta1", - "kind": "Eviction", - "metadata": { - "name": "quux", - "namespace": "default" - } -} -``` -{{% /tab %}} -{{< /tabs >}} - - -你可以使用 `curl` 尝试驱逐： - -```bash -curl -v -H 'Content-type: application/json' http://127.0.0.1:8080/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json -``` - - -API 可以通过以下三种方式之一进行响应： - -- 如果驱逐被授权，那么 Pod 将被删掉，并且你会收到 `200 OK`， - 就像你向 Pod 的 URL 发送了 `DELETE` 请求一样。 -- 如果按照预算中规定，目前的情况不允许的驱逐，你会收到 `429 Too Many Requests`。 - 这通常用于对 *一些* 请求进行通用速率限制， - 但这里我们的意思是：此请求 *现在* 不允许，但以后可能会允许。 - 目前，调用者不会得到任何 `Retry-After` 的提示，但在将来的版本中可能会得到。 -- 如果有一些错误的配置，比如多个预算指向同一个 Pod，你将得到 `500 Internal Server Error`。 - - -对于一个给定的驱逐请求，有两种情况： - -- 没有匹配这个 Pod 的预算。这种情况，服务器总是返回 `200 OK`。 -- 至少匹配一个预算。在这种情况下，上述三种回答中的任何一种都可能适用。 - - -## 驱逐阻塞 - -在某些情况下，应用程序可能会到达一个中断状态，除了 429 或 500 之外，它将永远不会返回任何内容。 -例如 ReplicaSet 创建的替换 Pod 没有变成就绪状态，或者被驱逐的最后一个 -Pod 有很长的终止宽限期，就会发生这种情况。 - - -在这种情况下，有两种可能的解决方案： - -- 中止或暂停自动操作。调查应用程序卡住的原因，并重新启动自动化。 -- 经过适当的长时间等待后，从集群中删除 Pod 而不是使用驱逐 API。 - -Kubernetes 并没有具体说明在这种情况下应该采取什么行为， -这应该由应用程序所有者和集群所有者紧密沟通，并达成对行动一致意见。 +更多信息，请参阅 [API 发起的驱逐](/zh/docs/concepts/scheduling-eviction/api-eviction/)。 ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/tasks/administer-cluster/securing-a-cluster.md b/content/zh/docs/tasks/administer-cluster/securing-a-cluster.md index 151c9f212a..ffc364d3ea 100644 --- a/content/zh/docs/tasks/administer-cluster/securing-a-cluster.md +++ b/content/zh/docs/tasks/administer-cluster/securing-a-cluster.md @@ -257,10 +257,10 @@ to the metadata API, and avoid using provisioning data to deliver secrets. --> ### 限制云元数据 API 访问 -云平台（AWS、Azure、GCE 等）经常将元数据服务暴露给本地实例。 -默认情况下，这些 API 可由运行在实例上的 Pod 访问，且其中可能包含该云节点的凭据或配置数据 -（如 kubelet 凭据）。 -这些凭据可以用于在集群内提升权限或获得权限访问同一账户的其他云服务。 +云平台（AWS, Azure, GCE 等）经常将 metadata 本地服务暴露给实例。 +默认情况下，这些 API 可由运行在实例上的 Pod 访问，并且可以包含 +该云节点的凭据或配置数据（如 kubelet 凭据）。 +这些凭据可以用于在集群内升级或在同一账户下升级到其他云服务。 在云平台上运行 Kubernetes 时，需要限制对实例凭据的权限，使用 [网络策略](/zh/docs/tasks/administer-cluster/declare-network-policy/) diff --git a/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md b/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md index bc254322d7..d67101cb85 100644 --- a/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md +++ b/content/zh/docs/tasks/administer-cluster/sysctl-cluster.md @@ -122,7 +122,7 @@ The following sysctls are supported in the _safe_ set: - `net.ipv4.ip_local_port_range` - `net.ipv4.tcp_syncookies` - `net.ipv4.ping_group_range` （从 Kubernetes 1.18 开始） -- `net.ipv4.ip_unprivileged_port_start` (从 Kubernetes 1.22 开始). +- `net.ipv4.ip_unprivileged_port_start` （从 Kubernetes 1.22 开始）。 类似于安装安全补丁、事件日志收集等这类管理性质的任务可以在不需要集群操作员登录到每个 Windows 节点的前提下执行。HostProcess 容器可以以主机上存在的任何用户账户来运行， @@ -58,7 +58,7 @@ Windows 节点的前提下执行。HostProcess 容器可以以主机上存在的 这意味着基础镜像的版本不必与主机操作系统的版本匹配。 不过，仍然建议你像使用 Windows 服务器容器负载那样，使用相同的基础镜像版本， 这样你就不会有一些未使用的镜像占用节点上的存储空间。HostProcess 容器也支持 -在容器卷内执行[卷挂载](./create-hostprocess-pod#volume-mounts)。 +在容器卷内执行[卷挂载](#volume-mounts)。 - HostProcess 容器需要 containerd 1.6 或更高版本的 {{< glossary_tooltip text="容器运行时" term_id="container-runtime" >}}。 @@ -145,13 +145,14 @@ filesystem or Hyper-V isolation are supported for HostProcess containers. 用户账号所实施的资源约束外，不提供任何形式的隔离。HostProcess 容器不支持文件系统或 Hyper-V 隔离。 - 卷挂载是被支持的，并且要花在到容器卷下。参见[卷挂载](#volume-mounts)。 - 默认情况下有一组主机用户账户可供 HostProcess 容器使用。 diff --git a/content/zh/docs/tasks/configure-pod-container/security-context.md b/content/zh/docs/tasks/configure-pod-container/security-context.md index a131d450c1..7a226f37f9 100644 --- a/content/zh/docs/tasks/configure-pod-container/security-context.md +++ b/content/zh/docs/tasks/configure-pod-container/security-context.md @@ -1,5 +1,5 @@ --- -title: 为 Pod 或容器配置安全性上下文 +title: 为 Pod 或容器配置安全上下文 content_type: task weight: 80 --- @@ -21,7 +21,8 @@ a Pod or Container. Security context settings include, but are not limited to: * Discretionary Access Control: Permission to access an object, like a file, is based on [user ID (UID) and group ID (GID)](https://wiki.archlinux.org/index.php/users_and_groups). -* [Security Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux): Objects are assigned security labels. +* [Security Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux): + Objects are assigned security labels. * Running as privileged or unprivileged. * [Linux Capabilities](https://linux-audit.com/linux-capabilities-hardening-linux-binaries-by-removing-setuid/): Give a process some privileges, but not all the privileges of the root user. @@ -29,8 +30,8 @@ a Pod or Container. Security context settings include, but are not limited to: 安全上下文（Security Context）定义 Pod 或 Container 的特权与访问控制设置。 安全上下文包括但不限于： -* 自主访问控制（Discretionary Access Control）：基于 - [用户 ID（UID）和组 ID（GID）](https://wiki.archlinux.org/index.php/users_and_groups). +* 自主访问控制（Discretionary Access Control）： + 基于[用户 ID（UID）和组 ID（GID）](https://wiki.archlinux.org/index.php/users_and_groups) 来判定对对象（例如文件）的访问权限。 * [安全性增强的 Linux（SELinux）](https://zh.wikipedia.org/wiki/%E5%AE%89%E5%85%A8%E5%A2%9E%E5%BC%BA%E5%BC%8FLinux)： 为对象赋予安全性标签。 @@ -38,21 +39,31 @@ a Pod or Container. Security context settings include, but are not limited to: * [Linux 权能](https://linux-audit.com/linux-capabilities-hardening-linux-binaries-by-removing-setuid/): 为进程赋予 root 用户的部分特权而非全部特权。 -* [AppArmor](/zh/docs/tutorials/clusters/apparmor/)：使用程序框架来限制个别程序的权能。 -* [Seccomp](/zh/docs/tutorials/clusters/seccomp/)：过滤进程的系统调用。 -* AllowPrivilegeEscalation：控制进程是否可以获得超出其父进程的特权。 +* [AppArmor](/zh/docs/tutorials/security/apparmor/)：使用程序配置来限制个别程序的权能。 +* [Seccomp](/zh/docs/tutorials/security/seccomp/)：过滤进程的系统调用。 +* `allowPrivilegeEscalation`：控制进程是否可以获得超出其父进程的特权。 此布尔值直接控制是否为容器进程设置 [`no_new_privs`](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt)标志。 - 当容器以特权模式运行或者具有 `CAP_SYS_ADMIN` 权能时，AllowPrivilegeEscalation 总是为 true。 + 当容器满足一下条件之一时，`allowPrivilegeEscalation` 总是为 true： + + - 以特权模式运行，或者 + - 具有 `CAP_SYS_ADMIN` 权能 + * readOnlyRootFilesystem：以只读方式加载容器的根文件系统。 +输出类似于： + +```none uid=1000 gid=3000 groups=2000 ``` -你会看到 `gid` 值为 3000，也就是 `runAsGroup` 字段的值。 +从输出中你会看到 `gid` 值为 3000，也就是 `runAsGroup` 字段的值。 如果 `runAsGroup` 被忽略，则 `gid` 会取值 0（root），而进程就能够与 root 用户组所拥有以及要求 root 用户组访问权限的文件交互。 @@ -251,18 +267,21 @@ slowing Pod startup. You can use the `fsGroupChangePolicy` field inside a `secur to control the way that Kubernetes checks and manages ownership and permissions for a volume. --> -默认情况下，Kubernetes 在挂载一个卷时，会递归地更改每个卷中的内容的属主和访问权限，使之与 Pod -的 `securityContext` 中指定的 `fsGroup` 匹配。 +默认情况下，Kubernetes 在挂载一个卷时，会递归地更改每个卷中的内容的属主和访问权限， +使之与 Pod 的 `securityContext` 中指定的 `fsGroup` 匹配。 对于较大的数据卷，检查和变更属主与访问权限可能会花费很长时间，降低 Pod 启动速度。 你可以在 `securityContext` 中使用 `fsGroupChangePolicy` 字段来控制 Kubernetes 检查和管理卷属主和访问权限的方式。 {{< note >}} -此字段对于[`secret`](/zh/docs/concepts/storage/volumes/#secret)、 +此字段对于 [`secret`](/zh/docs/concepts/storage/volumes/#secret)、 [`configMap`](/zh/docs/concepts/storage/volumes/#configmap) 和 [`emptydir`](/zh/docs/concepts/storage/volumes/#emptydir) 这类临时性存储无效。 @@ -316,23 +335,24 @@ ownership and permission change, `fsGroupChangePolicy` does not take effect, and as specified by CSI, the driver is expected to mount the volume with the provided `fsGroup`, resulting in a volume that is readable/writable by the `fsGroup`. +--> +如果你部署了一个[容器存储接口 (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) +驱动，而该驱动支持 `VOLUME_MOUNT_GROUP` `NodeServiceCapability`， +在 `securityContext` 中指定 `fsGroup` 来设置文件所有权和权限的过程将由 CSI +驱动而不是 Kubernetes 来执行，前提是 Kubernetes 的 `DelegateFSGroupToCSIDriver` +特性门控已启用。在这种情况下，由于 Kubernetes 不执行任何所有权和权限更改， +`fsGroupChangePolicy` 不会生效，并且按照 CSI 的规定，CSI 驱动应该使用所指定的 +`fsGroup` 来挂载卷，从而生成了一个对 `fsGroup` 可读/可写的卷. + -如果你部署了一个[容器存储接口 (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) -驱动支持 `VOLUME_MOUNT_GROUP` `NodeServiceCapability`， -在 `securityContext` 中指定 `fsGroup` 来设置文件所有权和权限的过程将由 CSI 驱动 -而不是 Kubernetes 来执行，前提是 Kubernetes 的 `DelegateFSGroupToCSIDriver` -特性门控已启用。在这种情况下，由于 Kubernetes 不执行任何 -所有权和权限更改，`fsGroupChangePolicy` 不会生效，并且 -按照 CSI 的规定，CSI 驱动应该使用所指定的 `fsGroup` 来挂载卷，从而生成了一个对 `fsGroup` 可读/可写的卷. - 更多的信息请参考 [KEP](https://github.com/gnufied/enhancements/blob/master/keps/sig-storage/2317-fsgroup-on-mount/README.md) -和 [CSI 规范](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume) 中的字 -段 `VolumeCapability.MountVolume.volume_mount_group` 的描述 。 +和 [CSI 规范](https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume) +中的字段 `VolumeCapability.MountVolume.volume_mount_group` 的描述。 -输出显示进程以用户 2000 账号运行。该值是在 Container 的 `runAsUser` 中设置的。 +输出显示进程以用户 2000 运行。该值是在 Container 的 `runAsUser` 中设置的。 该设置值重载了 Pod 层面所设置的值 1000。 ``` @@ -434,12 +453,12 @@ Here is configuration file that does not add or remove any Container capabilitie --> ## 为 Container 设置权能 {#set-capabilities-for-a-container} -使用 [Linux 权能](https://man7.org/linux/man-pages/man7/capabilities.7.html)，你可以 -赋予进程 root 用户所拥有的某些特权，但不必赋予其全部特权。 -要为 Container 添加或移除 Linux 权能，可以在 Container 清单的 `securityContext` 节 -包含 `capabilities` 字段。 +使用 [Linux 权能](https://man7.org/linux/man-pages/man7/capabilities.7.html)， +你可以赋予进程 root 用户所拥有的某些特权，但不必赋予其全部特权。 +要为 Container 添加或移除 Linux 权能，可以在 Container 清单的 `securityContext` +节包含 `capabilities` 字段。 -首先，查看不包含 `capabilities` 字段时候会发生什么。 +首先，看一下不包含 `capabilities` 字段时候会发生什么。 下面是一个配置文件，其中没有添加或移除容器的权能： {{< codenew file="pods/security/security-context-3.yaml" >}} @@ -598,12 +617,15 @@ for definitions of the capability constants. 了解权能常数的定义。 {{< note >}} Linux 权能常数定义的形式为 `CAP_XXX`。但是你在 Container 清单中列举权能时， -要将权能名称中的 `CAP_` 部分去掉。例如，要添加 `CAP_SYS_TIME`，可在权能 -列表中添加 `SYS_TIME`。 +要将权能名称中的 `CAP_` 部分去掉。例如，要添加 `CAP_SYS_TIME`， +可在权能列表中添加 `SYS_TIME`。 {{< /note >}} -## 为容器设置 Seccomp 样板 +## 为容器设置 Seccomp 配置 -若要为容器设置 Seccomp 样板（Profile），可在你的 Pod 或 Container 清单的 +若要为容器设置 Seccomp 配置（Profile），可在你的 Pod 或 Container 清单的 `securityContext` 节中包含 `seccompProfile` 字段。该字段是一个 [SeccompProfile](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#seccompprofile-v1-core) 对象，包含 `type` 和 `localhostProfile` 属性。 `type` 的合法选项包括 `RuntimeDefault`、`Unconfined` 和 `Localhost`。 -`localhostProfile` 只能在 `type: Localhost` 配置下才需要设置。 -该字段标明节点上预先配置的样板的路径，路径是相对于 kubelet 所配置的 -Seccomp 样板路径（使用 `--root-dir` 配置）而言的。 +`localhostProfile` 只能在 `type: Localhost` 配置下才可以设置。 +该字段标明节点上预先设定的配置的路径，路径是相对于 kubelet 所配置的 +Seccomp 配置路径（使用 `--root-dir` 设置）而言的。 -下面是一个例子，设置容器使用节点上容器运行时的默认样板作为 Seccomp 样板： +下面是一个例子，设置容器使用节点上容器运行时的默认配置作为 Seccomp 配置： ```yaml ... @@ -704,15 +726,15 @@ Pod 的安全上下文适用于 Pod 中的容器，也适用于 Pod 所挂载的 * `fsGroup`：支持属主管理的卷会被修改，将其属主变更为 `fsGroup` 所指定的 GID， 并且对该 GID 可写。进一步的细节可参阅 @@ -763,9 +785,9 @@ kubectl delete pod security-context-demo-4 --> * [PodSecurityContext](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritycontext-v1-core) API 定义 * [SecurityContext](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#securitycontext-v1-core) API 定义 -* [使用最新的安全性增强来调优 Docker](https://github.com/containerd/containerd/blob/main/docs/cri/config.md) -* [安全性上下文的设计文档](https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md) -* [属主管理的设计文档](https://git.k8s.io/community/contributors/design-proposals/storage/volume-ownership-management.md) +* [使用最新的安全性增强来调优 Docker（英文）](https://github.com/containerd/containerd/blob/main/docs/cri/config.md) +* [安全上下文的设计文档（英文）](https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md) +* [属主管理的设计文档（英文）](https://git.k8s.io/community/contributors/design-proposals/storage/volume-ownership-management.md) * [Pod 安全策略](/zh/docs/concepts/policy/pod-security-policy/) -* [AllowPrivilegeEscalation 的设计文档](https://git.k8s.io/community/contributors/design-proposals/auth/no-new-privs.md) +* [AllowPrivilegeEscalation 的设计文档（英文）](https://git.k8s.io/community/contributors/design-proposals/auth/no-new-privs.md) diff --git a/content/zh/docs/tasks/configure-pod-container/translate-compose-kubernetes.md b/content/zh/docs/tasks/configure-pod-container/translate-compose-kubernetes.md index e0cc2fec77..6a96b492a6 100644 --- a/content/zh/docs/tasks/configure-pod-container/translate-compose-kubernetes.md +++ b/content/zh/docs/tasks/configure-pod-container/translate-compose-kubernetes.md @@ -285,10 +285,7 @@ you need is an existing `docker-compose.yml` file. - CLI - [`kompose convert`](#kompose-convert) - - [`kompose up`](#kompose-up) - - [`kompose down`](#kompose-down) - 文档 - - [构建和推送 Docker 镜像](#build-and-push-docker-images) - [其他转换方式](#其他转换方式) - [标签](#labels) - [重启](#restart) @@ -447,219 +441,6 @@ If you are manually pushing the Openshift artifacts using ``oc create -f``, you imagestream 工件，以解决 Openshift 的这个问题：https://github.com/openshift/origin/issues/4518 。 {{< /note >}} -## `kompose up` - - -Kompose 支持通过 `kompose up` 直接将你的"复合的（composed）" 应用程序 -部署到 Kubernetes 或 OpenShift。 - - -### Kubernetes `kompose up` 示例 - -```shell -kompose --file ./examples/docker-guestbook.yml up -``` - -```none -We are going to create Kubernetes deployments and services for your Dockerized application. -If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. - -INFO Successfully created service: redis-master -INFO Successfully created service: redis-slave -INFO Successfully created service: frontend -INFO Successfully created deployment: redis-master -INFO Successfully created deployment: redis-slave -INFO Successfully created deployment: frontend - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods' for details. -``` - -```shell -kubectl get deployment,svc,pods -``` - -``` -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -deployment.extensions/frontend 1 1 1 1 4m -deployment.extensions/redis-master 1 1 1 1 4m -deployment.extensions/redis-slave 1 1 1 1 4m - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -service/frontend ClusterIP 10.0.174.12 80/TCP 4m -service/kubernetes ClusterIP 10.0.0.1 443/TCP 13d -service/redis-master ClusterIP 10.0.202.43 6379/TCP 4m -service/redis-slave ClusterIP 10.0.1.85 6379/TCP 4m - -NAME READY STATUS RESTARTS AGE -pod/frontend-2768218532-cs5t5 1/1 Running 0 4m -pod/redis-master-1432129712-63jn8 1/1 Running 0 4m -pod/redis-slave-2504961300-nve7b 1/1 Running 0 4m -``` - - -{{< note >}} - -- 你必须有一个运行正常的 Kubernetes 集群，该集群具有预先配置的 kubectl 上下文。 -- 此操作仅生成 Deployment 和 Service 对象并将其部署到 Kubernetes。 - 如果需要部署其他不同类型的资源，请使用 `kompose convert` 和 `kubectl create -f` 命令。 -{{< /note >}} - - -### OpenShift `kompose up` 示例 - -```shell -kompose --file ./examples/docker-guestbook.yml --provider openshift up -``` - -```none -We are going to create OpenShift DeploymentConfigs and Services for your Dockerized application. -If you need different kind of resources, use the 'kompose convert' and 'oc create -f' commands instead. - -INFO Successfully created service: redis-slave -INFO Successfully created service: frontend -INFO Successfully created service: redis-master -INFO Successfully created deployment: redis-slave -INFO Successfully created ImageStream: redis-slave -INFO Successfully created deployment: frontend -INFO Successfully created ImageStream: frontend -INFO Successfully created deployment: redis-master -INFO Successfully created ImageStream: redis-master - -Your application has been deployed to OpenShift. You can run 'oc get dc,svc,is' for details. -``` - -```shell -oc get dc,svc,is -``` - -```none -NAME REVISION DESIRED CURRENT TRIGGERED BY -dc/frontend 0 1 0 config,image(frontend:v4) -dc/redis-master 0 1 0 config,image(redis-master:e2e) -dc/redis-slave 0 1 0 config,image(redis-slave:v1) -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -svc/frontend 172.30.46.64 80/TCP 8s -svc/redis-master 172.30.144.56 6379/TCP 8s -svc/redis-slave 172.30.75.245 6379/TCP 8s -NAME DOCKER REPO TAGS UPDATED -is/frontend 172.30.12.200:5000/fff/frontend -is/redis-master 172.30.12.200:5000/fff/redis-master -is/redis-slave 172.30.12.200:5000/fff/redis-slave v1 -``` - -{{< note >}} - -你必须有一个运行正常的 OpenShift 集群，该集群具有预先配置的 `oc` 上下文 (`oc login`)。 -{{< /note >}} - -## `kompose down` - - -你一旦将"复合(composed)" 应用部署到 Kubernetes，`kompose down` -命令将能帮你通过删除 Deployment 和 Service 对象来删除应用。 -如果需要删除其他资源，请使用 'kubectl' 命令。 - -```shell -kompose --file docker-guestbook.yml down -``` - -``` -INFO Successfully deleted service: redis-master -INFO Successfully deleted deployment: redis-master -INFO Successfully deleted service: redis-slave -INFO Successfully deleted deployment: redis-slave -INFO Successfully deleted service: frontend -INFO Successfully deleted deployment: frontend -``` - -{{< note >}} - -- 你必须有一个运行正常的 Kubernetes 集群，该集群具有预先配置的 kubectl 上下文。 -{{< /note >}} - - -## 构建和推送 Docker 镜像 {#build-and-push-docker-images} - -Kompose 支持构建和推送 Docker 镜像。如果 Docker Compose 文件中使用了 `build` -关键字，你的镜像将会： - -- 使用文档中指定的 `image` 键自动构建 Docker 镜像 -- 使用本地凭据推送到正确的 Docker 仓库 - -使用 [Docker Compose 文件示例](https://raw.githubusercontent.com/kubernetes/kompose/master/examples/buildconfig/docker-compose.yml) - -```yaml -version: "2" - -services: - foo: - build: "./build" - image: docker.io/foo/bar -``` - - -使用带有 `build` 键的 `kompose up` 命令： - -```shell -kompose up -``` - -```none -INFO Build key detected. Attempting to build and push image 'docker.io/foo/bar' -INFO Building image 'docker.io/foo/bar' from directory 'build' -INFO Image 'docker.io/foo/bar' from directory 'build' built successfully -INFO Pushing image 'foo/bar:latest' to registry 'docker.io' -INFO Attempting authentication credentials 'https://index.docker.io/v1/ -INFO Successfully pushed image 'foo/bar:latest' to registry 'docker.io' -INFO We are going to create Kubernetes Deployments, Services and PersistentVolumeClaims for your Dockerized application. If you need different kind of resources, use the 'kompose convert' and 'kubectl create -f' commands instead. - -INFO Deploying application in "default" namespace -INFO Successfully created Service: foo -INFO Successfully created Deployment: foo - -Your application has been deployed to Kubernetes. You can run 'kubectl get deployment,svc,pods,pvc' for details. -``` - - -要想禁用该功能，或者使用 BuildConfig 中的版本（在 OpenShift 中）， -可以通过传递 `--build (local|build-config|none)` 参数来实现。 - -```shell -# 禁止构造和推送 Docker 镜像 -kompose up --build none - -# 为 OpenShift 生成 Build Config 工件 -kompose up --provider openshift --build build-config -``` - {{< note >}} 在有些容器运行时中，`command` 字段对应 `entrypoint`，请参阅下面的 @@ -161,73 +160,6 @@ command: ["/bin/sh"] args: ["-c", "while true; do echo hello; sleep 10;done"] ``` - -## 说明事项 {#notes} - -下表给出了 Docker 与 Kubernetes 中对应的字段名称。 - -| 描述 | Docker 字段名称 | Kubernetes 字段名称 | -|--------------------|--------------------|-----------------------| -| 容器执行的命令 | Entrypoint | command | -| 传给命令的参数 | Cmd | args | - - -如果要覆盖默认的 Entrypoint 与 Cmd，需要遵循如下规则： - -* 如果在容器配置中没有设置 `command` 或者 `args`，那么将使用 Docker 镜像自带的命令及其参数。 - -* 如果在容器配置中只设置了 `command` 但是没有设置 `args`，那么容器启动时只会执行该命令， - Docker 镜像中自带的命令及其参数会被忽略。 - -* 如果在容器配置中只设置了 `args`，那么 Docker 镜像中自带的命令会使用该新参数作为其执行时的参数。 - -* 如果在容器配置中同时设置了 `command` 与 `args`，那么 Docker 镜像中自带的命令及其参数会被忽略。 - 容器启动时只会执行配置中设置的命令，并使用配置中设置的参数作为命令的参数。 - - -下面是一些例子： - -| 镜像 Entrypoint | 镜像 Cmd | 容器 command | 容器 args | 命令执行 | -|--------------------|------------------|---------------------|--------------------|------------------| -| `[/ep-1]` | `[foo bar]` | <not set> | <not set> | `[ep-1 foo bar]` | -| `[/ep-1]` | `[foo bar]` | `[/ep-2]` | <not set> | `[ep-2]` | -| `[/ep-1]` | `[foo bar]` | <not set> | `[zoo boo]` | `[ep-1 zoo boo]` | -| `[/ep-1]` | `[foo bar]` | `[/ep-2]` | `[zoo boo]` | `[ep-2 zoo boo]` | - ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/tasks/job/automated-tasks-with-cron-jobs.md b/content/zh/docs/tasks/job/automated-tasks-with-cron-jobs.md index 0f2f5e90b6..731d560c5d 100644 --- a/content/zh/docs/tasks/job/automated-tasks-with-cron-jobs.md +++ b/content/zh/docs/tasks/job/automated-tasks-with-cron-jobs.md @@ -30,6 +30,7 @@ Cron jobs can also schedule individual tasks for a specific time, such as if you --> 在Kubernetes v1.21 版本中，CronJob 被提升为通用版本。如果你使用的是旧版本的 Kubernetes，请参考你正在使用的 Kubernetes 版本的文档，这样你就能看到准确的信息。旧的 Kubernetes 版本不支持`batch/v1` CronJob API。 + 你可以利用 [CronJobs](/zh/docs/concepts/workloads/controllers/cron-jobs) 执行基于时间调度的任务。这些自动化任务和 Linux 或者 Unix 系统的 [Cron](https://en.wikipedia.org/wiki/Cron) 任务类似。 CronJobs 在创建周期性以及重复性的任务时很有帮助，例如执行备份操作或者发送邮件。CronJobs 也可以在特定时间调度单个任务，例如你想调度低活跃周期的任务。 @@ -43,6 +44,7 @@ For more limitations, see [CronJobs](/docs/concepts/workloads/controllers/cron-j CronJobs 有一些限制和特点。 例如，在特定状况下，同一个 CronJob 可以创建多个任务。 因此，任务应该是幂等的。 + 查看更多限制，请参考 [CronJobs](/zh/docs/concepts/workloads/controllers/cron-jobs)。 ## {{% heading "prerequisites" %}} @@ -134,16 +136,14 @@ hello */1 * * * * False 0 50s 75s ``` -你应该能看到 “hello” CronJob 在 `LAST-SCHEDULE` 声明的时间点成功的调度了一次任务。 +你应该能看到 `hello` CronJob 在 `LAST SCHEDULE` 声明的时间点成功的调度了一次任务。 有 0 个活跃的任务意味着任务执行完毕或者执行失败。 -现在，找到最后一次调度任务创建的 Pod 并查看一个 Pod 的标准输出。请注意任务名称和 Pod 名称是不同的。 +现在，找到最后一次调度任务创建的 Pod 并查看一个 Pod 的标准输出。 +输出与此类似： ``` Fri Feb 22 11:02:09 UTC 2019 @@ -359,6 +363,6 @@ By default, they are set to 3 and 1 respectively. Setting a limit to `0` corres `.spec.successfulJobsHistoryLimit` 和 `.spec.failedJobsHistoryLimit`是可选的。 这两个字段指定应保留多少已完成和失败的任务。 -默认设置为3和1。限制设置为0代表相应类型的任务完成后不会保留。 +默认设置为3和1。限制设置为 `0` 代表相应类型的任务完成后不会保留。 diff --git a/content/zh/docs/tasks/job/parallel-processing-expansion.md b/content/zh/docs/tasks/job/parallel-processing-expansion.md index 9e2c0a2c86..2f5a8e13c3 100644 --- a/content/zh/docs/tasks/job/parallel-processing-expansion.md +++ b/content/zh/docs/tasks/job/parallel-processing-expansion.md @@ -279,13 +279,13 @@ First, copy and paste the following template of a Job object, into a file called 首先，复制下面的 Job 对象模板到一个名为 `job.yaml.jinja2` 的文件。 ```liquid -{%- set params = [{ "name": "apple", "url": "http://dbpedia.org/resource/Apple", }, +{% set params = [{ "name": "apple", "url": "http://dbpedia.org/resource/Apple", }, { "name": "banana", "url": "http://dbpedia.org/resource/Banana", }, { "name": "cherry", "url": "http://dbpedia.org/resource/Cherry" }] %} -{%- for p in params %} -{%- set name = p["name"] %} -{%- set url = p["url"] %} +{% for p in params %} +{% set name = p["name"] %} +{% set url = p["url"] %} --- apiVersion: batch/v1 kind: Job @@ -305,7 +305,7 @@ spec: image: busybox command: ["sh", "-c", "echo Processing URL {{ url }} && sleep 5"] restartPolicy: Never -{%- endfor %} +{% endfor %} ``` 你可能想设置 [`.spec.updateStrategy.rollingUpdate.maxUnavailable`](/zh/docs/concepts/workloads/controllers/deployment/#max-unavailable) (默认为 1)， [`.spec.minReadySeconds`](/zh/docs/concepts/workloads/controllers/deployment/#min-ready-seconds) (默认为 0) 和 -[`.spec.maxSurge`](/zh/docs/concepts/workloads/controllers/deployment/#max-surge) (一种 Beta 阶段的特性，默认为 25%) +[`.spec.updateStrategy.rollingUpdate.maxSurge`](/zh/docs/reference/kubernetes-api/workload-resources/daemon-set-v1/#DaemonSetSpec) +（一种 Beta 阶段的特性，默认为 0）。 修补你的 Deployment: -{{< tabs name="kubectl_retainkeys_example" >}} -{{{< tab name="Bash" codelang="bash" >}} -kubectl patch deployment retainkeys-demo --type merge --patch "$(cat patch-file-no-retainkeys.yaml)" -{{< /tab >}} -{{< tab name="PowerShell" codelang="posh" >}} -kubectl patch deployment retainkeys-demo --type merge --patch $(Get-Content patch-file-no-retainkeys.yaml -Raw) -{{< /tab >}}} -{{< /tabs >}} +```shell +kubectl patch deployment patch-demo --patch-file patch-file.yaml +``` 检查 Deployment 的内容： @@ -625,10 +615,10 @@ The following commands are equivalent: 以下命令是等价的： ```shell -kubectl patch deployment patch-demo --patch "$(cat patch-file.yaml)" +kubectl patch deployment patch-demo --patch-file patch-file.yaml" kubectl patch deployment patch-demo --patch 'spec:\n template:\n spec:\n containers:\n - name: patch-demo-ctr-2\n image: redis' -kubectl patch deployment patch-demo --patch "$(cat patch-file.json)" +kubectl patch deployment patch-demo --patch-file patch-file.json" kubectl patch deployment patch-demo --patch '{"spec": {"template": {"spec": {"containers": [{"name": "patch-demo-ctr-2","image": "redis"}]}}}}' ``` @@ -681,6 +671,3 @@ Strategic merge patch is not supported for custom resources. * [使用配置文件执行 Kubernetes 对象的指令式管理](/zh/docs/tasks/manage-kubernetes-objects/imperative-config) * [使用配置文件对 Kubernetes 对象进行声明式管理](/zh/docs/tasks/manage-kubernetes-objects/declarative-config/) - - - diff --git a/content/zh/docs/tasks/tools/install-kubectl-windows.md b/content/zh/docs/tasks/tools/install-kubectl-windows.md index a52e7bd375..617ca3f3ce 100644 --- a/content/zh/docs/tasks/tools/install-kubectl-windows.md +++ b/content/zh/docs/tasks/tools/install-kubectl-windows.md @@ -106,17 +106,23 @@ The following methods exist for installing kubectl on Windows: ``` -1. 将可执行文件的路径添加到 `PATH`。 +1. 将 kubectl 二进制文件夹附加或添加到你的 `PATH` 环境变量中。 1. 测试一下，确保此 `kubectl` 的版本和期望版本一致： ```cmd kubectl version --client ``` + 或者使用下面命令来查看版本的详细信息： + ```cmd + kubectl version --client --output=yaml + ``` + -1. 将可执行文件添加到你的 `PATH` 环境变量。 +1. 将 kubectl 二进制文件夹附加或添加到你的 `PATH` 环境变量中。 1. 验证插件是否安装成功 diff --git a/content/zh/docs/tutorials/_index.md b/content/zh/docs/tutorials/_index.md index a4440f7ba7..2feb4bd56d 100644 --- a/content/zh/docs/tutorials/_index.md +++ b/content/zh/docs/tutorials/_index.md @@ -23,11 +23,10 @@ each of which has a sequence of steps. Before walking through each tutorial, you may want to bookmark the [Standardized Glossary](/docs/reference/glossary/) page for later references. --> -Kubernetes 文档的这一部分包含教程。每个教程展示了如何完成一个比单个 -[任务](/zh/docs/tasks/)更大的目标。 +Kubernetes 文档的这一部分包含教程。 +每个教程展示了如何完成一个比单个[任务](/zh/docs/tasks/)更大的目标。 通常一个教程有几个部分，每个部分都有一系列步骤。在浏览每个教程之前， -您可能希望将[标准化术语表](/zh/docs/reference/glossary/)页面添加到书签，供以后参考。 - +你可能希望将[标准化术语表](/zh/docs/reference/glossary/)页面添加到书签，供以后参考。 ## 基础知识 {#basics} -* [Kubernetes 基础知识](/zh/docs/tutorials/Kubernetes-Basics/)是一个深入的 - 交互式教程，帮助您理解 Kubernetes 系统，并尝试一些基本的 Kubernetes 特性。 - -* [介绍 Kubernetes (edx)](https://www.edx.org/course/introduction-kubernetes-linuxfoundationx-lfs158x#) - +* [Kubernetes 基础知识](/zh/docs/tutorials/Kubernetes-Basics/) + 是一个深入的交互式教程，帮助你理解 Kubernetes 系统，并尝试一些基本的 Kubernetes 特性。 +* [Kubernetes 介绍 (edX)](https://www.edx.org/course/introduction-kubernetes-linuxfoundationx-lfs158x#) * [你好 Minikube](/zh/docs/tutorials/hello-minikube/) -## 集群 {#clusters} - -* [AppArmor](/zh/docs/tutorials/clusters/apparmor/) - -* [seccomp](/zh/docs/tutorials/clusters/seccomp/) - ## 安全 {#security} * [在集群级别应用 Pod 安全标准](/zh/docs/tutorials/security/cluster-level-pss/) * [在名字空间级别应用 Pod 安全标准](/zh/docs/tutorials/security/ns-level-pss/) +* [AppArmor](/zh/docs/tutorials/security/apparmor/) +* [seccomp](/zh/docs/tutorials/security/seccomp/) ## {{% heading "whatsnext" %}} @@ -136,6 +118,6 @@ If you would like to write a tutorial, see [Content Page Types](/docs/contribute/style/page-content-types/) for information about the tutorial page. --> -如果您想编写教程，请参阅[内容页面类型](/zh/docs/contribute/style/page-content-types/) +如果你要编写教程，请参阅[内容页面类型](/zh/docs/contribute/style/page-content-types/) 以获取有关教程页面类型的信息。 diff --git a/content/zh/docs/tutorials/hello-minikube.md b/content/zh/docs/tutorials/hello-minikube.md index 445f806c33..f9c15568c9 100644 --- a/content/zh/docs/tutorials/hello-minikube.md +++ b/content/zh/docs/tutorials/hello-minikube.md @@ -244,10 +244,10 @@ Pod runs a Container based on the provided Docker image. {{< note >}} -有关 `kubectl` 命令的更多信息，请参阅 [kubectl 概述](/zh/docs/reference/kubectl/overview/)。 +有关 `kubectl` 命令的更多信息，请参阅 [kubectl 概述](/zh/docs/reference/kubectl/)。 {{< /note >}} +{{- else -}} + +{{- end -}} + +{{- end -}} {{ with .Params.js }}{{ range (split . ",") }} {{ end }}{{ else }}{{ end }} diff --git a/scripts/.spelling_failures b/scripts/.spelling_failures new file mode 100644 index 0000000000..8b0d9e0815 --- /dev/null +++ b/scripts/.spelling_failures @@ -0,0 +1,10 @@ +content/en/blog/_posts/2016-05-00-Coreosfest2016-Kubernetes-Community.md +content/en/blog/_posts/2016-10-00-Dynamic-Provisioning-And-Storage-In-Kubernetes.md +content/en/blog/_posts/2017-02-00-Postgresql-Clusters-Kubernetes-Statefulsets.md +content/en/blog/_posts/2018-06-28-Airflow-Kubernetes-Operator.md +content/en/blog/_posts/2018-10-02-network-bootable-farm-with-ltsp.md +content/en/blog/_posts/2019-03-19-kubeedge-k8s-based-edge-intro.md +content/en/blog/_posts/2020-05-06-third-party-dual-sourced-content.md +content/en/blog/_posts/2020-05-21-wsl2-dockerdesktop-k8s.md +content/en/blog/_posts/2020-07-27-kubernetes-1-17-release-interview.md + diff --git a/scripts/verify-spelling.sh b/scripts/verify-spelling.sh index c259d65ddb..2871dfa76a 100755 --- a/scripts/verify-spelling.sh +++ b/scripts/verify-spelling.sh @@ -15,14 +15,14 @@ # limitations under the License. ########## # This script verifies mispellings in location. Today it only supports -# verifying English locale but can be modified in a future to support -# also other locales. +# verifying English locale but can be modified in a future to support +# other locales also # You need to run this script inside the root directory of "website" git repo. -# +# # Syntax: verify-spelling.sh LOCALE # Example: verify-spelling.sh en # If no locale is passed, it will assume "en" -# +# # Requirements: # - go v1.14 or superior version @@ -34,6 +34,8 @@ set -o pipefail TOOL_VERSION="v0.3.4" +KUBE_ROOT=$(dirname "${BASH_SOURCE[0]}")/.. + LANGUAGE="${1:-en}" # cd to the root path ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" @@ -60,10 +62,15 @@ cd "${ROOT}" RES=0 echo "Checking spelling..." ERROR_LOG="${TMP_DIR}/errors.log" -git ls-files | grep content/${LANGUAGE} | xargs misspell > "${ERROR_LOG}" + +# NOTE we usually don't correct old blog articles, so we ignore them in +# this file. +skipping_file="${KUBE_ROOT}/scripts/.spelling_failures" +failing_packages=$(sed "s| | -e |g" "${skipping_file}") +git ls-files -z | grep --null-data "^content/${LANGUAGE}" | grep --null-data -v -e "${failing_packages}" | xargs -0 -r misspell > "${ERROR_LOG}" if [[ -s "${ERROR_LOG}" ]]; then sed 's/^/error: /' "${ERROR_LOG}" # add 'error' to each line to highlight in e2e status - echo "Found spelling errors!" + echo "Found spelling errors!" >&2 RES=1 fi exit "${RES}" diff --git a/static/_redirects b/static/_redirects index ab0fdb5f55..b8b28e1948 100644 --- a/static/_redirects +++ b/static/_redirects @@ -245,6 +245,7 @@ /docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/ /docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/ 301 /docs/tasks/access-kubernetes-api/setup-extension-api-server/ /docs/tasks/extend-kubernetes/setup-extension-api-server/ 301 +/docs/tasks/administer-cluster/access-cluster-services/ /docs/tasks/access-application-cluster/access-cluster-services/ 301 /docs/tasks/administer-cluster/apply-resource-quota-limit/ /docs/tasks/administer-cluster/quota-api-object/ 301 /docs/tasks/administer-cluster/assign-pods-nodes/ /docs/tasks/configure-pod-container/assign-pods-nodes/ 301 /docs/tasks/administer-cluster/calico-network-policy/ /docs/tasks/administer-cluster/network-policy-provider/calico-network-policy/ 301 diff --git a/static/css/community.css b/static/css/community.css index 9bd94d3dab..99ad2948fa 100644 --- a/static/css/community.css +++ b/static/css/community.css @@ -1,19 +1,425 @@ -div.community_main h1, h2, h3 { - border-bottom: 1px solid #cccccc; - margin-bottom: 30px; - padding-bottom: 10px; - padding-top: 10px; +body.cid-community #banner { + aspect-ratio: 1500 / 293; /* match source image */ + display: block; + width: 100%; + margin: 0 0 2.5em 0; + max-height: min(calc(2.5vw + min(24em, calc(2 * 293px))), 50vh); + object-fit: cover; + overflow: clip; } -div.community_main { - padding: 50px 100px; +body.cid-community .community-section #h2 { + font-weight: 200; + margin-top: 1em; + margin-bottom: 0.5em; + text-align: center; + letter-spacing: 0.15em; + text-transform: uppercase; } -div.community_main ul, -div.community_main li { - list-style: disc; - list-style-position: inside; - padding: 10px 0; - font-size: 16px; +body.cid-community .community-section h2:before, +body.cid-community .community-section h2:after { + background-color: #aaaaaa; + content: ""; + display: inline-block; + height: 1px; + position: relative; + vertical-align: middle; + width: 35%; +} + +body.cid-community .community-section h2:before { + right: 0.5em; + margin-left: -50%; +} + +body.cid-community .community-section h2:after { + left: 0.5em; + margin-right: -50%; +} + +body.cid-community .community-section, body.cid-community #navigation-items { + max-width: min(85vw,100em); + margin-left: auto; + margin-right: auto; +} + +body.cid-community .community-section { + margin-top: 1em; + margin-bottom: 1em; + padding: 0.5em 0; + justify-content: space-evenly; + align-items: baseline; + align-content: space-between; + min-height: 10em; + text-align: center; /* overridden for paragraphs */ +} + +body.cid-community .community-section:first-child { + padding-top: max(3vh,1.5em); +} + +body.cid-community #navigation-items { + padding: 0.25em; + + width: 100vw; + max-width: initial; + + margin-top: 2.5em; + margin-bottom: 2.5em; + + gap: 1.25em; + + border-bottom: 1px solid #aaaaaa; + border-top: 1px solid #aaaaaa; + display: flex; + flex-direction: row; + flex-wrap: wrap; +} + +/* Allow fallback if calc() fails */ +body.cid-community #navigation-items { + padding-left: calc((100vw - min(85vw,120em))/2); + padding-right: calc((100vw - min(85vw,120em))/2); +} + +body.cid-community #navigation-items .community-nav-item { + flex-grow: 1; + text-align: center; + letter-spacing: 0.08em; + padding-top: 0.2em; + padding-bottom: 0.2em; + word-spacing: initial; + text-decoration: none; + text-transform: uppercase; font-weight: 400; + color: #303030; + background: #ffffff; + font-size: 1.1em; + padding: 0.2em; + margin: 0; + max-width: 75vw; + min-width: 10%; + min-height: 2em; } + +body.cid-community .community-section > p:not(.community-simple) { + line-height: 1.5em; + text-align: initial; +} + +body.cid-community .community-section#introduction, +body.cid-community .community-section#introduction > p { + line-height: 1.75em; + font-weight: 300; + letter-spacing: 0.04em; +} + +body.cid-community #gallery { + display: flex; + max-width: 100vw; + gap: 0.75rem; + justify-content: center; + margin-left: auto; + margin-right: auto; +} + +body.cid-community #gallery img { + display: block; + flex-basis: 0; + flex-grow: 0; + height: min(20em, 90vh); +} + +/* see media queries later in file */ +body.cid-community #gallery img.community-gallery-mobile { + display: none; +} + + + + +body.cid-community .community-section#events { + width: 100vw; + max-width: initial; + margin-bottom: 0; + + /* no events + background-image: url('/images/community/event-bg.jpg'); + background-size: 100% auto; + background-position: center; + color: #fff; + */ + display: none; +} + +body.cid-community .community-section#values { + width: 100vw; + max-width: initial; + background-image: url('/images/community/event-bg.jpg'); + color: #fff; + padding: 2em; + margin-top: 3em; +} +body.cid-community .community-section#values { + padding-left: calc((100vw - min(75vw,120em))/2); + padding-right: calc((100vw - min(75vw,120em))/2); +} + +body.cid-community .community-section#meetups { + width: 100vw; + max-width: initial; + margin-top: 0; + + background: url('/images/community/kubernetes-community-final.jpg'), url('/images/community/kubernetes-community-column.png'); + background-position: 80% center, left center; + background-repeat: no-repeat, repeat; + background-size: auto 100%, cover; + color: #fff; + + width: 100vw; + /* fallback in case calc() fails */ + padding: 5vw; + padding-bottom: 1em; + min-height: min(24em,50vh); +} + +body.cid-community .community-section#meetups { + padding-left: calc((100vw - min(75vw,100em))/2); + padding-right: calc((100vw - min(75vw,100em))/2); +} + +body.cid-community a.community-cta-button { + appearance: button; + display: inline-block; + margin: 0.75em auto 0 auto; /* gap before button */ + + background-color: #0662EE; + color: white; + + border-radius: 6px; + padding: 0.75em; + min-height: 3em; + min-width: max(5vw, 9em); + + text-align: center; +} + +body.cid-community a.community-cta-button > span.community-cta { + color: inherit; + background: transparent; + + letter-spacing: 0.02em; + font-weight: bold; + text-transform: uppercase; +} + +body.cid-community .fullbutton { + appearance: button; + display: inline-block; + margin: auto; + margin-top: 2rem; + background-color: #0662EE; + color: white; + font-size: 1.5em; + border-radius: 0.3333em; + padding: 0.5em; + letter-spacing: 0.07em; + font-weight: bold; +} + +body.cid-community #videos { + width: 100vw; + max-width: initial; + padding: 0.5em 5vw 5% 5vw; /* fallback in case calc() fails */ + background-color: #eeeeee; + margin-top: 4em; +} + +body.cid-community #videos { + padding-left: calc((100vw - min(95vw,160em))/2); + padding-right: calc((100vw - min(95vw,160em))/2); +} + +body.cid-community #videos .container { + display: flex; + flex-wrap: wrap; + gap: max(12px,2em); + max-width: 95vw; + justify-content: center; + margin-left: auto; + margin-right: auto; +} + + +body.cid-community .video { + width: min(80vw,max(31%, 24em)); + flex-basis: 31%; + flex-shrink: 1; +} + +body.cid-community .video .videocta { + display: block; + margin: 0.25em 0 0em 0; + text-align: center; + padding: 0.25em; + padding-bottom: 2em; + text-align: center; + color: #0662EE; + text-transform: uppercase; + font-weight: bold; + letter-spacing: 0.06em; + line-height: 1.25em; + clear: both; +} + +body.cid-community .video iframe { + min-width: 95%; + height: auto; + aspect-ratio: 16 / 9; +} + +body.cid-community #resources { + margin-top: 5%; + margin-bottom: 3%; +} + +body.cid-community #resources .container { + width: 100%; + display: flex; + flex-wrap: none; + gap: 2em; + justify-content: center; + margin-left: auto; + margin-right: auto; +} + + +body.cid-community #resources .container > .community-resource { + flex-basis: auto; + width: 100%; + flex-shrink: 1; +} + +body.cid-community #resources .container > .community-resource img { + max-height: min(6em, 50vh); + width: auto; + display: block; + margin: 1em auto 0.75em auto; +} + +body.cid-community #resources .container > .community-resource a { + text-transform: uppercase; +} + +body.cid-community .resourcebox { + height: 100%; + min-height: 370px; +} + + + + +body.cid-community .community-section.community-frame { + width: 100vw; +} + +body.cid-community .community-section.community-frame .twittercol1 { + width: 100%; +} + +body.cid-community details > summary { + color: #303030; +} + +body.cid-community #cncf-code-of-conduct-intro, +body.cid-community #cncf-code-of-conduct { + max-width: min(90vw, 100em); + padding-left: 0.5em; + padding-right: 0.5em; + margin-left: auto; + margin-right: auto; +} + +body.cid-community #cncf-code-of-conduct { + padding-bottom: 8em; + padding-top: 0.25em; + margin-top: 0; +} + +/* duplication not needed */ +body.cid-community #values-legacy h1 { + display: none; +} + +body.cid-community #values-legacy h2, +body.cid-community #cncf-code-of-conduct h2 { + margin-top: 0.25em; + margin-bottom: 1em; + color: #0662EE; +} + +body.cid-community #values-legacy h2:before, +body.cid-community #values-legacy h2:after, +body.cid-community #cncf-code-of-conduct h2:before, +body.cid-community #cncf-code-of-conduct h2:after { + display: none; /* skip decoration */ +} + + +@media only screen and (max-width: 640px) { + body.cid-community #navigation-items { + justify-content: flex-start; + text-align: left; + gap: min(2px,0.125em); + } + body.cid-community #navigation-items div.community-nav-item { + width: 100%; + text-align: left; + min-height: initial; + flex-shrink: 0; + } + body.cid-community .video { + max-width: 80vw; + flex-basis: auto; + } + body.cid-community #resources .container { + flex-wrap: wrap; + } + body.cid-community #resources .container .community-resource { + max-width: min(80vw, 24rem); + } + body.cid-community a.community-cta-button { + font-size: 1.5rem; + } +} + +@media only screen and (max-width: 1024px) { + body.cid-community #gallery img.community-gallery-desktop { + display: none; + } + body.cid-community #gallery img.community-gallery-mobile { + display: initial; + max-width: 95vw; + height: auto; + } + body.cid-community .video { + flex-basis: max(30em,80vw); + max-width: max(32em, 75vw); + } + body.cid-community .video .videocta { + padding-bottom: 0.5em; + } +} + +@media only screen and (min-width: 1024px) { + body.cid-community br.optional { + display: none; + } + body.cid-community .community-section:not(:first-of-type) { + min-height: max(20em,18vh); + } + body.cid-community .community-section#meetups p:last-of-type { + margin-bottom: 6em; /* extra space for background */ + } +} \ No newline at end of file diff --git a/static/css/newcommunity.css b/static/css/legacy_community.css similarity index 97% rename from static/css/newcommunity.css rename to static/css/legacy_community.css index e62e4ab8c5..80b0404344 100644 --- a/static/css/newcommunity.css +++ b/static/css/legacy_community.css @@ -1,3 +1,22 @@ +div.community_main h1, h2, h3 { + border-bottom: 1px solid #cccccc; + margin-bottom: 30px; + padding-bottom: 10px; + padding-top: 10px; +} + +div.community_main { + padding: 50px 100px; +} + +div.community_main ul, +div.community_main li { + list-style: disc; + list-style-position: inside; + padding: 10px 0; + font-size: 16px; + font-weight: 400; +} .SandboxRoot.env-bp-430 .timeline-Tweet-text { font-size: 13pt !important; diff --git a/static/images/community/discuss.png b/static/images/community/discuss.png index 9e83b8ee53..41cb139b57 100644 Binary files a/static/images/community/discuss.png and b/static/images/community/discuss.png differ diff --git a/static/images/community/kubernetes-community-column.png b/static/images/community/kubernetes-community-column.png new file mode 100644 index 0000000000..f7b4b692fd Binary files /dev/null and b/static/images/community/kubernetes-community-column.png differ diff --git a/static/images/community/serverfault.png b/static/images/community/serverfault.png new file mode 100644 index 0000000000..3892daa7aa Binary files /dev/null and b/static/images/community/serverfault.png differ diff --git a/static/images/community/slack.png b/static/images/community/slack.png index c408648bc0..c4386e9075 100644 Binary files a/static/images/community/slack.png and b/static/images/community/slack.png differ diff --git a/static/images/community/stack.png b/static/images/community/stack.png index 08e2aff1d7..550440c5d5 100644 Binary files a/static/images/community/stack.png and b/static/images/community/stack.png differ diff --git a/static/images/community/twitter.png b/static/images/community/twitter.png index 339ed1b015..0e5a443c0a 100644 Binary files a/static/images/community/twitter.png and b/static/images/community/twitter.png differ