From d705d9ed1c285808ab27aeafb602a825e3392f93 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Sat, 18 Jun 2022 16:28:55 +0800 Subject: [PATCH] Batch fix links (3) --- .../node-pressure-eviction.md | 7 +- .../taint-and-toleration.md | 14 +- .../security/pod-security-standards.md | 13 +- .../concepts/security/rbac-good-practices.md | 30 +++-- .../concepts/security/windows-security.md | 23 ++-- .../concepts/services-networking/service.md | 121 ++++++++++++------ .../concepts/storage/ephemeral-volumes.md | 30 +++-- content/en/docs/concepts/workloads/_index.md | 2 +- .../workloads/controllers/statefulset.md | 55 +++++--- 9 files changed, 195 insertions(+), 100 deletions(-) diff --git a/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md b/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md index 6142c050c6..78835c3a7d 100644 --- a/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md +++ b/content/en/docs/concepts/scheduling-eviction/node-pressure-eviction.md @@ -66,8 +66,8 @@ the signal. The value for `memory.available` is derived from the cgroupfs instead of tools like `free -m`. This is important because `free -m` does not work in a -container, and if users use the [node -allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) feature, out of resource decisions +container, and if users use the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable) +feature, out of resource decisions are made local to the end user Pod part of the cgroup hierarchy as well as the root node. This [script](/examples/admin/resource/memory-available.sh) reproduces the same set of steps that the kubelet performs to calculate @@ -87,7 +87,8 @@ does not support other configurations. {{}} Some kubelet garbage collection features are deprecated in favor of eviction. -For a list of the deprecated features, see [kubelet garbage collection deprecation](/docs/concepts/cluster-administration/kubelet-garbage-collection/#deprecation). +For a list of the deprecated features, see +[kubelet garbage collection deprecation](/docs/concepts/architecture/garbage-collection/#deprecation). {{}} ### Eviction thresholds diff --git a/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md b/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md index 4bb3471745..82e812c53b 100644 --- a/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md +++ b/content/en/docs/concepts/scheduling-eviction/taint-and-toleration.md @@ -15,14 +15,15 @@ is a property of {{< glossary_tooltip text="Pods" term_id="pod" >}} that *attrac a set of {{< glossary_tooltip text="nodes" term_id="node" >}} (either as a preference or a hard requirement). _Taints_ are the opposite -- they allow a node to repel a set of pods. -_Tolerations_ are applied to pods. Tolerations allow the scheduler to schedule pods with matching taints. Tolerations allow scheduling but don't guarantee scheduling: the scheduler also [evaluates other parameters](/docs/concepts/scheduling-eviction/pod-priority-preemption/) as part of its function. +_Tolerations_ are applied to pods. Tolerations allow the scheduler to schedule pods with matching +taints. Tolerations allow scheduling but don't guarantee scheduling: the scheduler also +[evaluates other parameters](/docs/concepts/scheduling-eviction/pod-priority-preemption/) +as part of its function. Taints and tolerations work together to ensure that pods are not scheduled onto inappropriate nodes. One or more taints are applied to a node; this marks that the node should not accept any pods that do not tolerate the taints. - - ## Concepts @@ -266,7 +267,8 @@ This ensures that DaemonSet pods are never evicted due to these problems. ## Taint Nodes by Condition The control plane, using the node {{}}, -automatically creates taints with a `NoSchedule` effect for [node conditions](/docs/concepts/scheduling-eviction/node-pressure-eviction/#node-conditions). +automatically creates taints with a `NoSchedule` effect for +[node conditions](/docs/concepts/scheduling-eviction/node-pressure-eviction/#node-conditions). The scheduler checks taints, not node conditions, when it makes scheduling decisions. This ensures that node conditions don't directly affect scheduling. @@ -297,7 +299,7 @@ arbitrary tolerations to DaemonSets. ## {{% heading "whatsnext" %}} -* Read about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/) and how you can configure it +* Read about [Node-pressure Eviction](/docs/concepts/scheduling-eviction/node-pressure-eviction/) + and how you can configure it * Read about [Pod Priority](/docs/concepts/scheduling-eviction/pod-priority-preemption/) - diff --git a/content/en/docs/concepts/security/pod-security-standards.md b/content/en/docs/concepts/security/pod-security-standards.md index 47e93d3e9e..d60f3b0ae1 100644 --- a/content/en/docs/concepts/security/pod-security-standards.md +++ b/content/en/docs/concepts/security/pod-security-standards.md @@ -462,11 +462,11 @@ of individual policies are not defined here. {{% thirdparty-content %}} Other alternatives for enforcing policies are being developed in the Kubernetes ecosystem, such as: + - [Kubewarden](https://github.com/kubewarden) - [Kyverno](https://kyverno.io/policies/pod-security/) - [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) - ## FAQ ### Why isn't there a profile between privileged and baseline? @@ -493,9 +493,9 @@ built-in [Pod Security Admission Controller](/docs/concepts/security/pod-securit ### What profiles should I apply to my Windows Pods? Windows in Kubernetes has some limitations and differentiators from standard Linux-based -workloads. Specifically, many of the Pod SecurityContext fields [have no effect on -Windows](/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#v1-podsecuritycontext). As -such, no standardized Pod Security profiles currently exist. +workloads. Specifically, many of the Pod SecurityContext fields +[have no effect on Windows](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext). +As such, no standardized Pod Security profiles currently exist. If you apply the restricted profile for a Windows pod, this **may** have an impact on the pod at runtime. The restricted profile requires enforcing Linux-specific restrictions (such as seccomp @@ -504,7 +504,9 @@ these Linux-specific values, then the Windows pod should still work normally wit profile. However, the lack of enforcement means that there is no additional restriction, for Pods that use Windows containers, compared to the baseline profile. -The use of the HostProcess flag to create a HostProcess pod should only be done in alignment with the privileged policy. Creation of a Windows HostProcess pod is blocked under the baseline and restricted policies, so any HostProcess pod should be considered privileged. +The use of the HostProcess flag to create a HostProcess pod should only be done in alignment with the privileged policy. +Creation of a Windows HostProcess pod is blocked under the baseline and restricted policies, +so any HostProcess pod should be considered privileged. ### What about sandboxed Pods? @@ -518,3 +520,4 @@ kernel. This allows for workloads requiring heightened permissions to still be i Additionally, the protection of sandboxed workloads is highly dependent on the method of sandboxing. As such, no single recommended profile is recommended for all sandboxed workloads. + diff --git a/content/en/docs/concepts/security/rbac-good-practices.md b/content/en/docs/concepts/security/rbac-good-practices.md index cfcc8b3cb9..42436bb202 100644 --- a/content/en/docs/concepts/security/rbac-good-practices.md +++ b/content/en/docs/concepts/security/rbac-good-practices.md @@ -15,7 +15,8 @@ execute their roles. It is important to ensure that, when designing permissions users, the cluster administrator understands the areas where privilge escalation could occur, to reduce the risk of excessive access leading to security incidents. -The good practices laid out here should be read in conjunction with the general [RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update). +The good practices laid out here should be read in conjunction with the general +[RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update). @@ -34,7 +35,8 @@ some general rules that can be applied are : not just to all object types presently in the cluster, but also to all future object types which are created in the future. - Administrators should not use `cluster-admin` accounts except where specifically needed. - Providing a low privileged account with [impersonation rights](/docs/reference/access-authn-authz/authentication/#user-impersonation) + Providing a low privileged account with + [impersonation rights](/docs/reference/access-authn-authz/authentication/#user-impersonation) can avoid accidental modification of cluster resources. - Avoid adding users to the `system:masters` group. Any user who is a member of this group bypasses all RBAC rights checks and will always have unrestricted superuser access, which cannot be @@ -44,15 +46,17 @@ some general rules that can be applied are : ### Minimize distribution of privileged tokens -Ideally, pods shouldn't be assigned service accounts that have been granted powerful permissions (for example, any of the rights listed under -[privilege escalation risks](#privilege-escalation-risks)). +Ideally, pods shouldn't be assigned service accounts that have been granted powerful permissions +(for example, any of the rights listed under [privilege escalation risks](#privilege-escalation-risks)). In cases where a workload requires powerful permissions, consider the following practices: - Limit the number of nodes running powerful pods. Ensure that any DaemonSets you run are necessary and are run with least privilege to limit the blast radius of container escapes. - Avoid running powerful pods alongside untrusted or publicly-exposed ones. Consider using - [Taints and Toleration](/docs/concepts/scheduling-eviction/taint-and-toleration/), [NodeAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity), or [PodAntiAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity) to ensure - pods don't run alongside untrusted or less-trusted Pods. Pay especial attention to + [Taints and Toleration](/docs/concepts/scheduling-eviction/taint-and-toleration/), + [NodeAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity), or + [PodAntiAffinity](/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity) + to ensure pods don't run alongside untrusted or less-trusted Pods. Pay especial attention to situations where less-trustworthy Pods are not meeting the **Restricted** Pod Security Standard. ### Hardening @@ -107,7 +111,7 @@ with the ability to create suitably secure and isolated Pods, you should enforce You can use [Pod Security admission](/docs/concepts/security/pod-security-admission/) or other (third party) mechanisms to implement that enforcement. -You can also use the deprecated [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) mechanism +You can also use the deprecated [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) mechanism to restrict users' abilities to create privileged Pods (N.B. PodSecurityPolicy is scheduled for removal in version 1.25). @@ -117,7 +121,9 @@ Secrets they would not have through RBAC directly. ### Persistent volume creation -As noted in the [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems) documentation, access to create PersistentVolumes can allow for escalation of access to the underlying host. Where access to persistent storage is required trusted administrators should create +As noted in the [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/#volumes-and-file-systems) +documentation, access to create PersistentVolumes can allow for escalation of access to the underlying host. +Where access to persistent storage is required trusted administrators should create PersistentVolumes, and constrained users should use PersistentVolumeClaims to access that storage. ### Access to `proxy` subresource of Nodes @@ -130,7 +136,8 @@ granting rights to this resource. ### Escalate verb Generally the RBAC system prevents users from creating clusterroles with more rights than -they possess. The exception to this is the `escalate` verb. As noted in the [RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update), +they possess. The exception to this is the `escalate` verb. As noted in the +[RBAC documentation](/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update), users with this right can effectively escalate their privileges. ### Bind verb @@ -173,8 +180,11 @@ objects to create a denial of service condition either based on the size or numb specifically relevant in multi-tenant clusters if semi-trusted or untrusted users are allowed limited access to a system. -One option for mitigation of this issue would be to use [resource quotas](/docs/concepts/policy/resource-quotas/#object-count-quota) +One option for mitigation of this issue would be to use +[resource quotas](/docs/concepts/policy/resource-quotas/#object-count-quota) to limit the quantity of objects which can be created. ## {{% heading "whatsnext" %}} + * To learn more about RBAC, see the [RBAC documentation](/docs/reference/access-authn-authz/rbac/). + diff --git a/content/en/docs/concepts/security/windows-security.md b/content/en/docs/concepts/security/windows-security.md index 8c0704ac2b..c6523e3a43 100644 --- a/content/en/docs/concepts/security/windows-security.md +++ b/content/en/docs/concepts/security/windows-security.md @@ -22,34 +22,41 @@ storage (as compared to using tmpfs / in-memory filesystems on Linux). As a clus operator, you should take both of the following additional measures: 1. Use file ACLs to secure the Secrets' file location. -1. Apply volume-level encryption using [BitLocker](https://docs.microsoft.com/windows/security/information-protection/bitlocker/bitlocker-how-to-deploy-on-windows-server). +1. Apply volume-level encryption using + [BitLocker](https://docs.microsoft.com/windows/security/information-protection/bitlocker/bitlocker-how-to-deploy-on-windows-server). ## Container users [RunAsUsername](/docs/tasks/configure-pod-container/configure-runasusername) can be specified for Windows Pods or containers to execute the container processes as specific user. This is roughly equivalent to -[RunAsUser](/docs/concepts/policy/pod-security-policy/#users-and-groups). +[RunAsUser](/docs/concepts/security/pod-security-policy/#users-and-groups). Windows containers offer two default user accounts, ContainerUser and ContainerAdministrator. The differences between these two user accounts are covered in -[When to use ContainerAdmin and ContainerUser user accounts](https://docs.microsoft.com/virtualization/windowscontainers/manage-containers/container-security#when-to-use-containeradmin-and-containeruser-user-accounts) within Microsoft's _Secure Windows containers_ documentation. +[When to use ContainerAdmin and ContainerUser user accounts](https://docs.microsoft.com/virtualization/windowscontainers/manage-containers/container-security#when-to-use-containeradmin-and-containeruser-user-accounts) +within Microsoft's _Secure Windows containers_ documentation. Local users can be added to container images during the container build process. {{< note >}} -* [Nano Server](https://hub.docker.com/_/microsoft-windows-nanoserver) based images run as `ContainerUser` by default -* [Server Core](https://hub.docker.com/_/microsoft-windows-servercore) based images run as `ContainerAdministrator` by default +* [Nano Server](https://hub.docker.com/_/microsoft-windows-nanoserver) based images run as + `ContainerUser` by default +* [Server Core](https://hub.docker.com/_/microsoft-windows-servercore) based images run as + `ContainerAdministrator` by default {{< /note >}} -Windows containers can also run as Active Directory identities by utilizing [Group Managed Service Accounts](/docs/tasks/configure-pod-container/configure-gmsa/) +Windows containers can also run as Active Directory identities by utilizing +[Group Managed Service Accounts](/docs/tasks/configure-pod-container/configure-gmsa/) ## Pod-level security isolation Linux-specific pod security context mechanisms (such as SELinux, AppArmor, Seccomp, or custom POSIX capabilities) are not supported on Windows nodes. -Privileged containers are [not supported](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext) on Windows. -Instead [HostProcess containers](/docs/tasks/configure-pod-container/create-hostprocess-pod) can be used on Windows to perform many of the tasks performed by privileged containers on Linux. +Privileged containers are [not supported](/docs/concepts/windows/intro/#compatibility-v1-pod-spec-containers-securitycontext) +on Windows. +Instead [HostProcess containers](/docs/tasks/configure-pod-container/create-hostprocess-pod) +can be used on Windows to perform many of the tasks performed by privileged containers on Linux. diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index ad5af427ec..c88375164b 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/content/en/docs/concepts/services-networking/service.md @@ -299,9 +299,14 @@ thus is only available to use as-is. ### Configuration Note that the kube-proxy starts up in different modes, which are determined by its configuration. -- The kube-proxy's configuration is done via a ConfigMap, and the ConfigMap for kube-proxy effectively deprecates the behaviour for almost all of the flags for the kube-proxy. +- The kube-proxy's configuration is done via a ConfigMap, and the ConfigMap for kube-proxy + effectively deprecates the behaviour for almost all of the flags for the kube-proxy. - The ConfigMap for the kube-proxy does not support live reloading of configuration. -- The ConfigMap parameters for the kube-proxy cannot all be validated and verified on startup. For example, if your operating system doesn't allow you to run iptables commands, the standard kernel kube-proxy implementation will not work. Likewise, if you have an operating system which doesn't support `netsh`, it will not run in Windows userspace mode. +- The ConfigMap parameters for the kube-proxy cannot all be validated and verified on startup. + For example, if your operating system doesn't allow you to run iptables commands, + the standard kernel kube-proxy implementation will not work. + Likewise, if you have an operating system which doesn't support `netsh`, + it will not run in Windows userspace mode. ### User space proxy mode {#proxy-mode-userspace} @@ -492,7 +497,11 @@ variables and DNS. ### Environment variables When a Pod is run on a Node, the kubelet adds a set of environment variables -for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables, where the Service name is upper-cased and dashes are converted to underscores. It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) that are compatible with Docker Engine's "_[legacy container links](https://docs.docker.com/network/links/)_" feature. +for each active Service. It adds `{SVCNAME}_SERVICE_HOST` and `{SVCNAME}_SERVICE_PORT` variables, +where the Service name is upper-cased and dashes are converted to underscores. +It also supports variables (see [makeLinkVariables](https://github.com/kubernetes/kubernetes/blob/dd2d12f6dc0e654c15d5db57a5f9f6ba61192726/pkg/kubelet/envvars/envvars.go#L72)) +that are compatible with Docker Engine's +"_[legacy container links](https://docs.docker.com/network/links/)_" feature. For example, the Service `redis-master` which exposes TCP port 6379 and has been allocated cluster IP address 10.0.0.11, produces the following environment @@ -604,8 +613,10 @@ The default is `ClusterIP`. to use the `ExternalName` type. {{< /note >}} -You can also use [Ingress](/docs/concepts/services-networking/ingress/) to expose your Service. Ingress is not a Service type, but it acts as the entry point for your cluster. It lets you consolidate your routing rules -into a single resource as it can expose multiple services under the same IP address. +You can also use [Ingress](/docs/concepts/services-networking/ingress/) to expose your Service. +Ingress is not a Service type, but it acts as the entry point for your cluster. +It lets you consolidate your routing rules into a single resource as it can expose multiple +services under the same IP address. ### Type NodePort {#type-nodeport} @@ -620,9 +631,14 @@ field of the [kube-proxy configuration file](/docs/reference/config-api/kube-proxy-config.v1alpha1/) to particular IP block(s). -This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) to specify IP address ranges that kube-proxy should consider as local to this node. +This flag takes a comma-delimited list of IP blocks (e.g. `10.0.0.0/8`, `192.0.2.0/25`) +to specify IP address ranges that kube-proxy should consider as local to this node. -For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, kube-proxy only selects the loopback interface for NodePort Services. The default for `--nodeport-addresses` is an empty list. This means that kube-proxy should consider all available network interfaces for NodePort. (That's also compatible with earlier Kubernetes releases). +For example, if you start kube-proxy with the `--nodeport-addresses=127.0.0.0/8` flag, +kube-proxy only selects the loopback interface for NodePort Services. +The default for `--nodeport-addresses` is an empty list. +his means that kube-proxy should consider all available network interfaces for NodePort. +(That's also compatible with earlier Kubernetes releases). If you want a specific port number, you can specify a value in the `nodePort` field. The control plane will either allocate you that port or report that @@ -689,7 +705,8 @@ status: - ip: 192.0.2.127 ``` -Traffic from the external load balancer is directed at the backend Pods. The cloud provider decides how it is load balanced. +Traffic from the external load balancer is directed at the backend Pods. +The cloud provider decides how it is load balanced. Some cloud providers allow you to specify the `loadBalancerIP`. In those cases, the load-balancer is created with the user-specified `loadBalancerIP`. If the `loadBalancerIP` field is not specified, @@ -704,7 +721,11 @@ to create a static type public IP address resource. This public IP address resou be in the same resource group of the other automatically created resources of the cluster. For example, `MC_myResourceGroup_myAKSCluster_eastus`. -Specify the assigned IP address as loadBalancerIP. Ensure that you have updated the securityGroupName in the cloud provider configuration file. For information about troubleshooting `CreatingLoadBalancerFailed` permission issues see, [Use a static IP address with the Azure Kubernetes Service (AKS) load balancer](https://docs.microsoft.com/en-us/azure/aks/static-ip) or [CreatingLoadBalancerFailed on AKS cluster with advanced networking](https://github.com/Azure/AKS/issues/357). +Specify the assigned IP address as loadBalancerIP. Ensure that you have updated the +`securityGroupName` in the cloud provider configuration file. +For information about troubleshooting `CreatingLoadBalancerFailed` permission issues see, +[Use a static IP address with the Azure Kubernetes Service (AKS) load balancer](https://docs.microsoft.com/en-us/azure/aks/static-ip) +or [CreatingLoadBalancerFailed on AKS cluster with advanced networking](https://github.com/Azure/AKS/issues/357). {{< /note >}} @@ -760,7 +781,8 @@ Unprefixed names are reserved for end-users. In a mixed environment it is sometimes necessary to route traffic from Services inside the same (virtual) network address block. -In a split-horizon DNS environment you would need two Services to be able to route both external and internal traffic to your endpoints. +In a split-horizon DNS environment you would need two Services to be able to route both external +and internal traffic to your endpoints. To set an internal load balancer, add one of the following annotations to your Service depending on the cloud Service provider you're using. @@ -925,7 +947,9 @@ you can use the following annotations: In the above example, if the Service contained three ports, `80`, `443`, and `8443`, then `443` and `8443` would use the SSL certificate, but `80` would be proxied HTTP. -From Kubernetes v1.9 onwards you can use [predefined AWS SSL policies](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) with HTTPS or SSL listeners for your Services. +From Kubernetes v1.9 onwards you can use +[predefined AWS SSL policies](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) +with HTTPS or SSL listeners for your Services. To see which policies are available for use, you can use the `aws` command line tool: ```bash @@ -981,14 +1005,17 @@ specifies the logical hierarchy you created for your Amazon S3 bucket. metadata: name: my-service annotations: - service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "true" # Specifies whether access logs are enabled for the load balancer - service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "60" + service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "true" + # The interval for publishing the access logs. You can specify an interval of either 5 or 60 (minutes). - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: "my-bucket" + service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "60" + # The name of the Amazon S3 bucket where the access logs are stored - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "my-bucket-prefix/prod" + service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: "my-bucket" + # The logical hierarchy you created for your Amazon S3 bucket, for example `my-bucket-prefix/prod` + service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "my-bucket-prefix/prod" ``` #### Connection Draining on AWS @@ -997,7 +1024,8 @@ Connection draining for Classic ELBs can be managed with the annotation `service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled` set to the value of `"true"`. The annotation `service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout` can -also be used to set maximum time, in seconds, to keep the existing connections open before deregistering the instances. +also be used to set maximum time, in seconds, to keep the existing connections open before +deregistering the instances. ```yaml metadata: @@ -1015,50 +1043,56 @@ There are other annotations to manage Classic Elastic Load Balancers that are de metadata: name: my-service annotations: + # The time, in seconds, that the connection is allowed to be idle (no data has been sent + # over the connection) before it is closed by the load balancer service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "60" - # The time, in seconds, that the connection is allowed to be idle (no data has been sent over the connection) before it is closed by the load balancer - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" # Specifies whether cross-zone load balancing is enabled for the load balancer + service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" - service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "environment=prod,owner=devops" # A comma-separated list of key-value pairs which will be recorded as # additional tags in the ELB. + service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags: "environment=prod,owner=devops" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "" # The number of successive successful health checks required for a backend to # be considered healthy for traffic. Defaults to 2, must be between 2 and 10 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-healthy-threshold: "" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3" # The number of unsuccessful health checks required for a backend to be # considered unhealthy for traffic. Defaults to 6, must be between 2 and 10 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-unhealthy-threshold: "3" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "20" # The approximate interval, in seconds, between health checks of an # individual instance. Defaults to 10, must be between 5 and 300 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval: "20" - service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "5" # The amount of time, in seconds, during which no response means a failed # health check. This value must be less than the service.beta.kubernetes.io/aws-load-balancer-healthcheck-interval # value. Defaults to 5, must be between 2 and 60 + service.beta.kubernetes.io/aws-load-balancer-healthcheck-timeout: "5" - service.beta.kubernetes.io/aws-load-balancer-security-groups: "sg-53fae93f" # A list of existing security groups to be configured on the ELB created. Unlike the annotation - # service.beta.kubernetes.io/aws-load-balancer-extra-security-groups, this replaces all other security groups previously assigned to the ELB and also overrides the creation + # service.beta.kubernetes.io/aws-load-balancer-extra-security-groups, this replaces all other + # security groups previously assigned to the ELB and also overrides the creation # of a uniquely generated security group for this ELB. - # The first security group ID on this list is used as a source to permit incoming traffic to target worker nodes (service traffic and health checks). - # If multiple ELBs are configured with the same security group ID, only a single permit line will be added to the worker node security groups, that means if you delete any + # The first security group ID on this list is used as a source to permit incoming traffic to + # target worker nodes (service traffic and health checks). + # If multiple ELBs are configured with the same security group ID, only a single permit line + # will be added to the worker node security groups, that means if you delete any # of those ELBs it will remove the single permit line and block access for all ELBs that shared the same security group ID. # This can cause a cross-service outage if not used properly + service.beta.kubernetes.io/aws-load-balancer-security-groups: "sg-53fae93f" - service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-53fae93f,sg-42efd82e" - # A list of additional security groups to be added to the created ELB, this leaves the uniquely generated security group in place, this ensures that every ELB - # has a unique security group ID and a matching permit line to allow traffic to the target worker nodes (service traffic and health checks). + # A list of additional security groups to be added to the created ELB, this leaves the uniquely + # generated security group in place, this ensures that every ELB + # has a unique security group ID and a matching permit line to allow traffic to the target worker nodes + # (service traffic and health checks). # Security groups defined here can be shared between services. + service.beta.kubernetes.io/aws-load-balancer-extra-security-groups: "sg-53fae93f,sg-42efd82e" - service.beta.kubernetes.io/aws-load-balancer-target-node-labels: "ingress-gw,gw-name=public-api" # A comma separated list of key-value pairs which are used # to select the target nodes for the load balancer + service.beta.kubernetes.io/aws-load-balancer-target-node-labels: "ingress-gw,gw-name=public-api" ``` #### Network Load Balancer support on AWS {#aws-nlb-support} @@ -1075,7 +1109,8 @@ To use a Network Load Balancer on AWS, use the annotation `service.beta.kubernet ``` {{< note >}} -NLB only works with certain instance classes; see the [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) +NLB only works with certain instance classes; see the +[AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-register-targets.html#register-deregister-targets) on Elastic Load Balancing for a list of supported instance types. {{< /note >}} @@ -1182,7 +1217,8 @@ spec: ``` {{< note >}} -ExternalName accepts an IPv4 address string, but as a DNS name comprised of digits, not as an IP address. ExternalNames that resemble IPv4 addresses are not resolved by CoreDNS or ingress-nginx because ExternalName +ExternalName accepts an IPv4 address string, but as a DNS name comprised of digits, not as an IP address. +ExternalNames that resemble IPv4 addresses are not resolved by CoreDNS or ingress-nginx because ExternalName is intended to specify a canonical DNS name. To hardcode an IP address, consider using [headless Services](#headless-services). {{< /note >}} @@ -1196,9 +1232,13 @@ can start its Pods, add appropriate selectors or endpoints, and change the Service's `type`. {{< warning >}} -You may have trouble using ExternalName for some common protocols, including HTTP and HTTPS. If you use ExternalName then the hostname used by clients inside your cluster is different from the name that the ExternalName references. +You may have trouble using ExternalName for some common protocols, including HTTP and HTTPS. +If you use ExternalName then the hostname used by clients inside your cluster is different from +the name that the ExternalName references. -For protocols that use hostnames this difference may lead to errors or unexpected responses. HTTP requests will have a `Host:` header that the origin server does not recognize; TLS servers will not be able to provide a certificate matching the hostname that the client connected to. +For protocols that use hostnames this difference may lead to errors or unexpected responses. +HTTP requests will have a `Host:` header that the origin server does not recognize; +TLS servers will not be able to provide a certificate matching the hostname that the client connected to. {{< /warning >}} {{< note >}} @@ -1357,12 +1397,15 @@ through a load-balancer, though in those cases the client IP does get altered. #### IPVS iptables operations slow down dramatically in large scale cluster e.g 10,000 Services. -IPVS is designed for load balancing and based on in-kernel hash tables. So you can achieve performance consistency in large number of Services from IPVS-based kube-proxy. Meanwhile, IPVS-based kube-proxy has more sophisticated load balancing algorithms (least conns, locality, weighted, persistence). +IPVS is designed for load balancing and based on in-kernel hash tables. +So you can achieve performance consistency in large number of Services from IPVS-based kube-proxy. +Meanwhile, IPVS-based kube-proxy has more sophisticated load balancing algorithms +(least conns, locality, weighted, persistence). ## API Object Service is a top-level resource in the Kubernetes REST API. You can find more details -about the API object at: [Service API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core). +about the [Service API object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#service-v1-core). ## Supported protocols {#protocol-support} @@ -1388,7 +1431,8 @@ provider offering this facility. (Most do not). ##### Support for multihomed SCTP associations {#caveat-sctp-multihomed} {{< warning >}} -The support of multihomed SCTP associations requires that the CNI plugin can support the assignment of multiple interfaces and IP addresses to a Pod. +The support of multihomed SCTP associations requires that the CNI plugin can support the +assignment of multiple interfaces and IP addresses to a Pod. NAT for multihomed SCTP associations requires special logic in the corresponding kernel modules. {{< /warning >}} @@ -1437,3 +1481,4 @@ followed by the data from the client. * Read [Connecting Applications with Services](/docs/concepts/services-networking/connect-applications-service/) * Read about [Ingress](/docs/concepts/services-networking/ingress/) * Read about [EndpointSlices](/docs/concepts/services-networking/endpoint-slices/) + diff --git a/content/en/docs/concepts/storage/ephemeral-volumes.md b/content/en/docs/concepts/storage/ephemeral-volumes.md index 27ea999ccf..045bcafe76 100644 --- a/content/en/docs/concepts/storage/ephemeral-volumes.md +++ b/content/en/docs/concepts/storage/ephemeral-volumes.md @@ -76,8 +76,8 @@ is managed by kubelet, or injecting different data. {{< feature-state for_k8s_version="v1.16" state="beta" >}} -This feature requires the `CSIInlineVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. It -is enabled by default starting with Kubernetes 1.16. +This feature requires the `CSIInlineVolume` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) +to be enabled. It is enabled by default starting with Kubernetes 1.16. {{< note >}} CSI ephemeral volumes are only supported by a subset of CSI drivers. @@ -136,8 +136,11 @@ should not be exposed to users through the use of inline ephemeral volumes. Cluster administrators who need to restrict the CSI drivers that are allowed to be used as inline volumes within a Pod spec may do so by: -- Removing `Ephemeral` from `volumeLifecycleModes` in the CSIDriver spec, which prevents the driver from being used as an inline ephemeral volume. -- Using an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) to restrict how this driver is used. + +- Removing `Ephemeral` from `volumeLifecycleModes` in the CSIDriver spec, which prevents the + driver from being used as an inline ephemeral volume. +- Using an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) + to restrict how this driver is used. ### Generic ephemeral volumes @@ -207,7 +210,7 @@ because then the scheduler is free to choose a suitable node for the Pod. With immediate binding, the scheduler is forced to select a node that has access to the volume once it is available. -In terms of [resource ownership](/docs/concepts/workloads/controllers/garbage-collection/#owners-dependents), +In terms of [resource ownership](/docs/concepts/architecture/garbage-collection/#owners-dependents), a Pod that has generic ephemeral storage is the owner of the PersistentVolumeClaim(s) that provide that ephemeral storage. When the Pod is deleted, the Kubernetes garbage collector deletes the PVC, which then usually @@ -252,10 +255,11 @@ Enabling the GenericEphemeralVolume feature allows users to create PVCs indirectly if they can create Pods, even if they do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit their security model, they should -use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) that rejects objects like Pods that have a generic ephemeral volume. +use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/) +that rejects objects like Pods that have a generic ephemeral volume. -The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) still applies, so -even if users are allowed to use this new mechanism, they cannot use +The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) +still applies, so even if users are allowed to use this new mechanism, they cannot use it to circumvent other policies. ## {{% heading "whatsnext" %}} @@ -266,11 +270,13 @@ See [local ephemeral storage](/docs/concepts/configuration/manage-resources-cont ### CSI ephemeral volumes -- For more information on the design, see the [Ephemeral Inline CSI - volumes KEP](https://github.com/kubernetes/enhancements/blob/ad6021b3d61a49040a3f835e12c8bb5424db2bbb/keps/sig-storage/20190122-csi-inline-volumes.md). -- For more information on further development of this feature, see the [enhancement tracking issue #596](https://github.com/kubernetes/enhancements/issues/596). +- For more information on the design, see the + [Ephemeral Inline CSI volumes KEP](https://github.com/kubernetes/enhancements/blob/ad6021b3d61a49040a3f835e12c8bb5424db2bbb/keps/sig-storage/20190122-csi-inline-volumes.md). +- For more information on further development of this feature, see the + [enhancement tracking issue #596](https://github.com/kubernetes/enhancements/issues/596). ### Generic ephemeral volumes - For more information on the design, see the -[Generic ephemeral inline volumes KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1698-generic-ephemeral-volumes/README.md). + [Generic ephemeral inline volumes KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1698-generic-ephemeral-volumes/README.md). + diff --git a/content/en/docs/concepts/workloads/_index.md b/content/en/docs/concepts/workloads/_index.md index 2c9dd8aa8e..dffd727505 100644 --- a/content/en/docs/concepts/workloads/_index.md +++ b/content/en/docs/concepts/workloads/_index.md @@ -70,7 +70,7 @@ visit [Configuration](/docs/concepts/configuration/). There are two supporting concepts that provide backgrounds about how Kubernetes manages pods for applications: -* [Garbage collection](/docs/concepts/workloads/controllers/garbage-collection/) tidies up objects +* [Garbage collection](/docs/concepts/architecture/garbage-collection/) tidies up objects from your cluster after their _owning resource_ has been removed. * The [_time-to-live after finished_ controller](/docs/concepts/workloads/controllers/ttlafterfinished/) removes Jobs once a defined time has passed since they completed. diff --git a/content/en/docs/concepts/workloads/controllers/statefulset.md b/content/en/docs/concepts/workloads/controllers/statefulset.md index 2ae481a431..1687399abd 100644 --- a/content/en/docs/concepts/workloads/controllers/statefulset.md +++ b/content/en/docs/concepts/workloads/controllers/statefulset.md @@ -39,10 +39,18 @@ that provides a set of stateless replicas. ## Limitations -* The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. -* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the StatefulSet. This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources. -* StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) to be responsible for the network identity of the Pods. You are responsible for creating this Service. -* StatefulSets do not provide any guarantees on the termination of pods when a StatefulSet is deleted. To achieve ordered and graceful termination of the pods in the StatefulSet, it is possible to scale the StatefulSet down to 0 prior to deletion. +* The storage for a given Pod must either be provisioned by a + [PersistentVolume Provisioner](https://github.com/kubernetes/examples/tree/master/staging/persistent-volume-provisioning/README.md) + based on the requested `storage class`, or pre-provisioned by an admin. +* Deleting and/or scaling a StatefulSet down will *not* delete the volumes associated with the + StatefulSet. This is done to ensure data safety, which is generally more valuable than an + automatic purge of all related StatefulSet resources. +* StatefulSets currently require a [Headless Service](/docs/concepts/services-networking/service/#headless-services) + to be responsible for the network identity of the Pods. You are responsible for creating this + Service. +* StatefulSets do not provide any guarantees on the termination of pods when a StatefulSet is + deleted. To achieve ordered and graceful termination of the pods in the StatefulSet, it is + possible to scale the StatefulSet down to 0 prior to deletion. * When using [Rolling Updates](#rolling-updates) with the default [Pod Management Policy](#pod-management-policies) (`OrderedReady`), it's possible to get into a broken state that requires @@ -108,18 +116,24 @@ In the above example: * A Headless Service, named `nginx`, is used to control the network domain. * The StatefulSet, named `web`, has a Spec that indicates that 3 replicas of the nginx container will be launched in unique Pods. -* The `volumeClaimTemplates` will provide stable storage using [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume Provisioner. +* The `volumeClaimTemplates` will provide stable storage using + [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a + PersistentVolume Provisioner. The name of a StatefulSet object must be a valid [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). ### Pod Selector -You must set the `.spec.selector` field of a StatefulSet to match the labels of its `.spec.template.metadata.labels`. Failing to specify a matching Pod Selector will result in a validation error during StatefulSet creation. +You must set the `.spec.selector` field of a StatefulSet to match the labels of its +`.spec.template.metadata.labels`. Failing to specify a matching Pod Selector will result in a +validation error during StatefulSet creation. ### Volume Claim Templates -You can set the `.spec.volumeClaimTemplates` which can provide stable storage using [PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume Provisioner. +You can set the `.spec.volumeClaimTemplates` which can provide stable storage using +[PersistentVolumes](/docs/concepts/storage/persistent-volumes/) provisioned by a PersistentVolume +Provisioner. ### Minimum ready seconds @@ -128,9 +142,11 @@ You can set the `.spec.volumeClaimTemplates` which can provide stable storage u `.spec.minReadySeconds` is an optional field that specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. -Please note that this feature is beta and enabled by default. Please opt out by unsetting the StatefulSetMinReadySeconds flag, if you don't +Please note that this feature is beta and enabled by default. Please opt out by unsetting the +StatefulSetMinReadySeconds flag, if you don't want this feature to be enabled. This field defaults to 0 (the Pod will be considered -available as soon as it is ready). To learn more about when a Pod is considered ready, see [Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). +available as soon as it is ready). To learn more about when a Pod is considered ready, see +[Container Probes](/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). ## Pod Identity @@ -166,8 +182,8 @@ remembered and reused, even after the Pod is running, for at least a few seconds If you need to discover Pods promptly after they are created, you have a few options: - Query the Kubernetes API directly (for example, using a watch) rather than relying on DNS lookups. -- Decrease the time of caching in your Kubernetes DNS provider (typically this means editing the config map for CoreDNS, which currently caches for 30 seconds). - +- Decrease the time of caching in your Kubernetes DNS provider (typically this means editing the + config map for CoreDNS, which currently caches for 30 seconds). As mentioned in the [limitations](#limitations) section, you are responsible for creating the [Headless Service](/docs/concepts/services-networking/service/#headless-services) @@ -189,7 +205,9 @@ Cluster Domain will be set to `cluster.local` unless ### Stable Storage -For each VolumeClaimTemplate entry defined in a StatefulSet, each Pod receives one PersistentVolumeClaim. In the nginx example above, each Pod receives a single PersistentVolume with a StorageClass of `my-storage-class` and 1 Gib of provisioned storage. If no StorageClass +For each VolumeClaimTemplate entry defined in a StatefulSet, each Pod receives one +PersistentVolumeClaim. In the nginx example above, each Pod receives a single PersistentVolume +with a StorageClass of `my-storage-class` and 1 Gib of provisioned storage. If no StorageClass is specified, then the default StorageClass will be used. When a Pod is (re)scheduled onto a node, its `volumeMounts` mount the PersistentVolumes associated with its PersistentVolume Claims. Note that, the PersistentVolumes associated with the @@ -210,7 +228,9 @@ the StatefulSet. * Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready. * Before a Pod is terminated, all of its successors must be completely shutdown. -The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of 0. This practice is unsafe and strongly discouraged. For further explanation, please refer to [force deleting StatefulSet Pods](/docs/tasks/run-application/force-delete-stateful-set-pod/). +The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of 0. This practice +is unsafe and strongly discouraged. For further explanation, please refer to +[force deleting StatefulSet Pods](/docs/tasks/run-application/force-delete-stateful-set-pod/). When the nginx example above is created, three Pods will be deployed in the order web-0, web-1, web-2. web-1 will not be deployed before web-0 is @@ -256,7 +276,8 @@ annotations for the Pods in a StatefulSet. There are two possible values: create new Pods that reflect modifications made to a StatefulSet's `.spec.template`. `RollingUpdate` -: The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a StatefulSet. This is the default update strategy. +: The `RollingUpdate` update strategy implements automated, rolling update for the Pods in a + StatefulSet. This is the default update strategy. ## Rolling Updates @@ -299,7 +320,7 @@ unavailable Pod in the range `0` to `replicas - 1`, it will be counted towards {{< note >}} The `maxUnavailable` field is in Alpha stage and it is honored only by API servers that are running with the `MaxUnavailableStatefulSet` -[feature gate](/docs/reference/commmand-line-tools-reference/feature-gates/) +[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) enabled. {{< /note >}} @@ -375,8 +396,8 @@ spec: ... ``` -The StatefulSet {{}} adds [owner -references](/docs/concepts/overview/working-with-objects/owners-dependents/#owner-references-in-object-specifications) +The StatefulSet {{}} adds +[owner references](/docs/concepts/overview/working-with-objects/owners-dependents/#owner-references-in-object-specifications) to its PVCs, which are then deleted by the {{}} after the Pod is terminated. This enables the Pod to cleanly unmount all volumes before the PVCs are deleted (and before the backing PV and