feat: K8s pilot corpus — 8 pages + config entry + JSON rewrite

Land the minimal K8s corpus needed to run the 6-question pilot:

- Fetch 8 pages from kubernetes.io/docs (pods, deployment,
replicaset, configmap, secret, node-pressure-eviction,
network-policies, pod-security-admission) via defuddle. Flat
`k8s_*.md` naming mirrors the existing `fastapi_*.md` precedent.
- Expand `corpora.k8s` in `configs/default.yaml`: flip
`available: true`, add `golden_dataset` pointer, drop
`refusal_threshold` from 0.30 placeholder to 0.02 for the pilot
smoke test. Two-line inline comment preserves the 0.30
launch-intent rationale pending the full tuning sweep.
- Rewrite `k8s_golden_pilot.json` `expected_sources` from
path-style (`concepts/workloads/pods`) to filename stems
(`k8s_pods.md`) so the exact-string match in
`retrieval_precision_at_k` works. `source_pages` stays as the
human-readable path anchor.
- Fix three `source_snippets` that drifted from the live page text:
pilot_002 (deployment rollout sentence paraphrase), pilot_003
(secret snippet now link-free substring), pilot_006 (added
backticks to match fetched markdown).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

agent_bench/evaluation/datasets/k8s_golden_pilot.json

@@ -12,7 +12,7 @@
       "id": "k8s_pilot_001",
       "question": "In Kubernetes, does each Pod receive its own IP address, and how do containers inside the same Pod talk to each other?",
       "expected_answer_keywords": ["unique", "IP address", "shared", "localhost"],
-      "expected_sources": ["concepts/workloads/pods"],
+      "expected_sources": ["k8s_pods.md"],
       "category": "retrieval",
       "difficulty": "easy",
       "requires_calculator": false,
@@ -31,8 +31,8 @@
       "question": "When you update a Deployment's pod template, what mechanism does Kubernetes use to transition Pods from the old version to the new one, and what role does the ReplicaSet play?",
       "expected_answer_keywords": ["ReplicaSet", "new ReplicaSet", "old ReplicaSet", "controlled rate", "replicas", "selector"],
       "expected_sources": [
-        "concepts/workloads/controllers/deployment",
-        "concepts/workloads/controllers/replicaset"
+        "k8s_deployment.md",
+        "k8s_replicaset.md"
       ],
       "category": "retrieval",
       "difficulty": "hard",
@@ -42,7 +42,7 @@
       "is_multi_hop": true,
       "source_chunk_ids": [],
       "source_snippets": [
-        "A new ReplicaSet is created and the Deployment manages moving the Pods from the old ReplicaSet to the new one at a controlled rate",
+        "A new ReplicaSet is created, and the Deployment gradually scales it up while scaling down the old ReplicaSet, ensuring Pods are replaced at a controlled rate",
         "A ReplicaSet is defined with fields, including a selector that specifies how to identify Pods it can acquire, a number of replicas indicating how many Pods it should be maintaining"
       ],
       "source_pages": [
@@ -56,8 +56,8 @@
       "question": "What is the key difference between a ConfigMap and a Secret when deciding where to store sensitive application data like database passwords?",
       "expected_answer_keywords": ["non-confidential", "confidential", "Secret", "ConfigMap", "encryption", "etcd"],
       "expected_sources": [
-        "concepts/configuration/configmap",
-        "concepts/configuration/secret"
+        "k8s_configmap.md",
+        "k8s_secret.md"
       ],
       "category": "retrieval",
       "difficulty": "medium",
@@ -68,7 +68,7 @@
       "source_chunk_ids": [],
       "source_snippets": [
         "A ConfigMap is an API object used to store non-confidential data in key-value pairs",
-        "Secrets are similar to ConfigMaps but are specifically intended to hold confidential data"
+        "specifically intended to hold confidential data"
       ],
       "source_pages": [
         "concepts/configuration/configmap",
@@ -80,7 +80,7 @@
       "id": "k8s_pilot_004",
       "question": "If I set a custom value for one hard eviction threshold on the kubelet (e.g., memory.available) but leave the other thresholds unset, what happens to the defaults for the thresholds I didn't override?",
       "expected_answer_keywords": ["zero", "default", "not inherited", "custom", "all thresholds", "explicit"],
-      "expected_sources": ["concepts/scheduling-eviction/node-pressure-eviction"],
+      "expected_sources": ["k8s_node_pressure_eviction.md"],
       "category": "retrieval",
       "difficulty": "hard",
       "requires_calculator": false,
@@ -98,7 +98,7 @@
       "id": "k8s_pilot_005",
       "question": "How do I configure a Kubernetes NetworkPolicy to enforce mutual TLS (mTLS) between Pods in the same namespace?",
       "expected_answer_keywords": ["not", "does not", "NetworkPolicy", "service mesh", "TLS", "ingress controller"],
-      "expected_sources": ["concepts/services-networking/network-policies"],
+      "expected_sources": ["k8s_network_policies.md"],
       "category": "retrieval",
       "difficulty": "medium",
       "requires_calculator": false,
@@ -116,7 +116,7 @@
       "id": "k8s_pilot_006",
       "question": "As of the Kubernetes v1.31 snapshot, what is the feature state (alpha, beta, or stable) of the built-in Pod Security admission controller, and in which version did it reach that state?",
       "expected_answer_keywords": ["stable", "v1.25", "Pod Security", "admission controller"],
-      "expected_sources": ["concepts/security/pod-security-admission"],
+      "expected_sources": ["k8s_pod_security_admission.md"],
       "category": "retrieval",
       "difficulty": "easy",
       "requires_calculator": false,
@@ -125,7 +125,7 @@
       "is_multi_hop": false,
       "source_chunk_ids": [],
       "source_snippets": [
-        "FEATURE STATE: Kubernetes v1.25 [stable]"
+        "FEATURE STATE: `Kubernetes v1.25 [stable]`"
       ],
       "source_pages": ["concepts/security/pod-security-admission"],
       "source_sections": [""]

configs/default.yaml

@@ -103,15 +103,10 @@ corpora:
     label: "Kubernetes"
     store_path: .cache/store_k8s
     data_path: data/k8s_docs
-    # PLACEHOLDER — tune against K8s golden dataset once it exists.
-    # K8s has more cross-referenced concepts than FastAPI, so relevance
-    # spreads across more chunks; the threshold likely lands higher.
-    refusal_threshold: 0.30
+    refusal_threshold: 0.02  # PILOT: matches fastapi working value for 6-pilot smoke test.
+                             # 0.30 placeholder remains the launch-intent; full tuning sweep
+                             # lands with the 25-question golden set (see DECISIONS.md).
     top_k: 5
     max_iterations: 3
-    # available=false keeps the K8s corpus in the schema (dashboard
-    # shows the toggle as disabled) but skips it from corpus_map at
-    # startup. Flip to true after data/k8s_docs/ is curated and
-    # `make ingest-k8s` has built .cache/store_k8s. See
-    # data/k8s_docs/SOURCES.md for the curation policy.
-    available: false
+    golden_dataset: agent_bench/evaluation/datasets/k8s_golden_pilot.json
+    available: true

data/k8s_docs/k8s_configmap.md

@@ -0,0 +1,281 @@
+A ConfigMap is an API object used to store non-confidential data in key-value pairs. [Pods](https://kubernetes.io/docs/concepts/workloads/pods/ "A Pod represents a set of running containers in your cluster.") can consume ConfigMaps as environment variables, command-line arguments, or as configuration files in a [volume](https://kubernetes.io/docs/concepts/storage/volumes/ "A directory containing data, accessible to the containers in a pod.").
+
+A ConfigMap allows you to decouple environment-specific configuration from your [container images](https://kubernetes.io/docs/reference/glossary/?all=true#term-image "Stored instance of a container that holds a set of software needed to run an application."), so that your applications are easily portable.
+
+> [!caution] Caution:
+> ConfigMap does not provide secrecy or encryption. If the data you want to store are confidential, use a [Secret](https://kubernetes.io/docs/concepts/configuration/secret/ "Stores sensitive information, such as passwords, OAuth tokens, and ssh keys.") rather than a ConfigMap, or use additional (third party) tools to keep your data private.
+
+## Motivation
+
+Use a ConfigMap for setting configuration data separately from application code.
+
+For example, imagine that you are developing an application that you can run on your own computer (for development) and in the cloud (to handle real traffic). You write the code to look in an environment variable named `DATABASE_HOST`. Locally, you set that variable to `localhost`. In the cloud, you set it to refer to a Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/ "A way to expose an application running on a set of Pods as a network service.") that exposes the database component to your cluster. This lets you fetch a container image running in the cloud and debug the exact same code locally if needed.
+
+> [!info] Note:
+> A ConfigMap is not designed to hold large chunks of data. The data stored in a ConfigMap cannot exceed 1 MiB. If you need to store settings that are larger than this limit, you may want to consider mounting a volume or use a separate database or file service.
+
+## ConfigMap object
+
+A ConfigMap is an [API object](https://kubernetes.io/docs/concepts/overview/working-with-objects/#kubernetes-objects "An entity in the Kubernetes system, representing part of the state of your cluster.") 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 strings while the `binaryData` field is designed to contain binary data as base64-encoded strings.
+
+The name of a ConfigMap must be a valid [DNS subdomain name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names).
+
+Each key under the `data` or the `binaryData` field must consist of alphanumeric characters, `-`, `_` or `.`. The keys stored in `data` must not overlap with the keys in the `binaryData` field.
+
+Starting from v1.19, you can add an `immutable` field to a ConfigMap definition to create an [immutable ConfigMap](#configmap-immutable).
+
+## ConfigMaps and Pods
+
+You can write a Pod `spec` that refers to a ConfigMap and configures the container(s) in that Pod based on the data in the ConfigMap. The Pod and the ConfigMap must be in the same [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces "An abstraction used by Kubernetes to support isolation of groups of resources within a single cluster.").
+
+> [!info] Note:
+> The `spec` of a [static Pod](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/ "A pod managed directly by the kubelet daemon on a specific node.") cannot refer to a ConfigMap or any other API objects.
+
+Here's an example ConfigMap that has some keys with single values, and other keys where the value looks like a fragment of a configuration format.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: game-demo
+data:
+  # property-like keys; each key maps to a simple value
+  player_initial_lives: "3"
+  ui_properties_file_name: "user-interface.properties"
+
+  # file-like keys
+  game.properties: |
+    enemy.types=aliens,monsters
+    player.maximum-lives=5    
+  user-interface.properties: |
+    color.good=purple
+    color.bad=yellow
+    allow.textmode=true
+```
+
+There are four different ways that you can use a ConfigMap to configure a container inside a Pod:
+
+1. Inside a container command and args
+2. Environment variables for a container
+3. Add a file in read-only volume, for the application to read
+4. Write code to run inside the Pod that uses the Kubernetes API to read a ConfigMap
+
+These different methods lend themselves to different ways of modeling the data being consumed. For the first three methods, the [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet "An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.") uses the data from the ConfigMap when it launches container(s) for a Pod.
+
+The fourth method means you have to write code to read the ConfigMap and its data. However, because you're using the Kubernetes API directly, your application can subscribe to get updates whenever the ConfigMap changes, and react when that happens. By accessing the Kubernetes API directly, this technique also lets you access a ConfigMap in a different namespace.
+
+Here's an example Pod that uses values from `game-demo` to configure a Pod:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: configmap-demo-pod
+spec:
+  containers:
+    - name: demo
+      image: alpine
+      command: ["sleep", "3600"]
+      env:
+        # Define the environment variable
+        - name: PLAYER_INITIAL_LIVES # Notice that the case is different here
+                                     # from the key name in the ConfigMap.
+          valueFrom:
+            configMapKeyRef:
+              name: game-demo           # The ConfigMap this value comes from.
+              key: player_initial_lives # The key to fetch.
+        - name: UI_PROPERTIES_FILE_NAME
+          valueFrom:
+            configMapKeyRef:
+              name: game-demo
+              key: ui_properties_file_name
+      volumeMounts:
+      - name: config
+        mountPath: "/config"
+        readOnly: true
+  volumes:
+  # You set volumes at the Pod level, then mount them into containers inside that Pod
+  - name: config
+    configMap:
+      # Provide the name of the ConfigMap you want to mount.
+      name: game-demo
+      # An array of keys from the ConfigMap to create as files
+      items:
+      - key: "game.properties"
+        path: "game.properties"
+      - key: "user-interface.properties"
+        path: "user-interface.properties"
+```
+
+A ConfigMap doesn't differentiate between single line property values and multi-line file-like values. What matters is how Pods and other objects consume those values.
+
+For this example, defining a volume and mounting it inside the `demo` container as `/config` creates two files, `/config/game.properties` and `/config/user-interface.properties`, even though there are four keys in the ConfigMap. This is because the Pod definition specifies an `items` array in the `volumes` section. If you omit the `items` array entirely, every key in the ConfigMap becomes a file with the same name as the key, and you get 4 files.
+
+## Using ConfigMaps
+
+ConfigMaps can be mounted as data volumes. ConfigMaps can also be used by other parts of the system, without being directly exposed to the Pod. For example, ConfigMaps can hold data that other parts of the system should use for configuration.
+
+The most common way to use ConfigMaps is to configure settings for containers running in a Pod in the same namespace. You can also use a ConfigMap separately.
+
+For example, you might encounter [addons](https://kubernetes.io/docs/concepts/cluster-administration/addons/ "Resources that extend the functionality of Kubernetes.") or [operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ "A specialized controller used to manage a custom resource") that adjust their behavior based on a ConfigMap.
+
+### Using ConfigMaps as files from a Pod
+
+To consume a ConfigMap in a volume in a Pod:
+
+1. Create a ConfigMap or use an existing one. Multiple Pods can reference the same ConfigMap.
+2. Modify your Pod definition to add a volume under `.spec.volumes[]`. Name the volume anything, and have a `.spec.volumes[].configMap.name` field set to reference your ConfigMap object.
+3. Add a `.spec.containers[].volumeMounts[]` to each container that needs the ConfigMap. Specify `.spec.containers[].volumeMounts[].readOnly = true` and `.spec.containers[].volumeMounts[].mountPath` to an unused directory name where you would like the ConfigMap to appear.
+4. Modify your image or command line so that the program looks for files in that directory. Each key in the ConfigMap `data` map becomes the filename under `mountPath`.
+
+This is an example of a Pod that mounts a ConfigMap 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
+    configMap:
+      name: myconfigmap
+```
+
+Each ConfigMap 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 ConfigMap.
+
+#### Mounted ConfigMaps are updated automatically
+
+When a ConfigMap currently consumed in a volume is updated, projected keys are eventually updated as well. The kubelet checks whether the mounted ConfigMap is fresh on every periodic sync. However, the kubelet uses its local cache for getting the current value of the ConfigMap. The type of the cache is configurable using the `configMapAndSecretChangeDetectionStrategy` field in the [KubeletConfiguration struct](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/). A ConfigMap 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 ConfigMap 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).
+
+ConfigMaps consumed as environment variables are not updated automatically and require a pod restart.
+
+> [!info] Note:
+> A container using a ConfigMap as a [subPath](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath) volume mount will not receive ConfigMap updates.
+
+### Using Configmaps as environment variables
+
+To use a Configmap in an [environment variable](https://kubernetes.io/docs/concepts/containers/container-environment/ "Container environment variables are name=value pairs that provide useful information into containers running in a Pod.") in a Pod:
+
+1. For each container in your Pod specification, add an environment variable for each Configmap key that you want to use to the `env[].valueFrom.configMapKeyRef` field.
+2. Modify your image and/or command line so that the program looks for values in the specified environment variables.
+
+This is an example of defining a ConfigMap as a pod environment variable:
+
+The following ConfigMap (myconfigmap.yaml) stores two properties: username and access\_level:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: myconfigmap
+data:
+  username: k8s-admin
+  access_level: "1"
+```
+
+The following command will create the ConfigMap object:
+
+```shell
+kubectl apply -f myconfigmap.yaml
+```
+
+The following Pod consumes the content of the ConfigMap as environment variables:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: env-configmap
+spec:
+  containers:
+    - name: app
+      command: ["/bin/sh", "-c", "printenv"]
+      image: busybox:latest
+      envFrom:
+        - configMapRef:
+            name: myconfigmap
+```
+
+The `envFrom` field instructs Kubernetes to create environment variables from the sources nested within it. The inner `configMapRef` refers to a ConfigMap by its name and selects all its key-value pairs. Add the Pod to your cluster, then retrieve its logs to see the output from the printenv command. This should confirm that the two key-value pairs from the ConfigMap have been set as environment variables:
+
+```shell
+kubectl apply -f env-configmap.yaml
+```
+```shell
+kubectl logs pod/env-configmap
+```
+
+The output is similar to this:
+
+```console
+...
+username: "k8s-admin"
+access_level: "1"
+...
+```
+
+Sometimes a Pod won't require access to all the values in a ConfigMap. For example, you could have another Pod which only uses the username value from the ConfigMap. For this use case, you can use the `env.valueFrom` syntax instead, which lets you select individual keys in a ConfigMap. The name of the environment variable can also be different from the key within the ConfigMap. For example:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: env-configmap
+spec:
+  containers:
+  - name: envars-test-container
+    image: nginx
+    env:
+    - name: CONFIGMAP_USERNAME
+      valueFrom:
+        configMapKeyRef:
+          name: myconfigmap
+          key: username
+```
+
+In the Pod created from this manifest, you will see that the environment variable `CONFIGMAP_USERNAME` is set to the value of the `username` value from the ConfigMap. Other keys from the ConfigMap data are not copied into the environment.
+
+It's important to note that the range of characters allowed for environment variable names in pods is [restricted](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config). If any keys do not meet the rules, those keys are not made available to your container, though the Pod is allowed to start.
+
+## Immutable ConfigMaps
+
+FEATURE STATE: `Kubernetes v1.21 [stable]`
+
+The Kubernetes feature *Immutable Secrets and ConfigMaps* provides an option to set individual Secrets and ConfigMaps as immutable. For clusters that extensively use ConfigMaps (at least tens of thousands of unique ConfigMap to Pod mounts), preventing changes to their data has the following advantages:
+
+- 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 ConfigMaps marked as immutable.
+
+You can create an immutable ConfigMap by setting the `immutable` field to `true`. For example:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  ...
+data:
+  ...
+immutable: true
+```
+
+Once a ConfigMap is marked as immutable, it is *not* possible to revert this change nor to mutate the contents of the `data` or the `binaryData` field. You can only delete and recreate the ConfigMap. Because existing Pods maintain a mount point to the deleted ConfigMap, it is recommended to recreate these pods.
+
+## What's next
+
+- Read about [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/).
+- Read [Configure a Pod to Use a ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/).
+- Read about [changing a ConfigMap (or any other Kubernetes object)](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/)
+- Read [The Twelve-Factor App](https://12factor.net/) to understand the motivation for separating code from configuration.
+  
+
+Last modified November 21, 2025 at 2:18 PM PST: [Fix formatting of kubectl logs command (69fb346f79)](https://github.com/kubernetes/website/commit/69fb346f79076561c9e5fdb6e65aed5b927e8ce5)

data/k8s_docs/k8s_deployment.md

@@ -0,0 +1,1092 @@
+A Deployment manages a set of Pods to run an application workload, usually one that doesn't maintain state.
+
+A *Deployment* provides declarative updates for [Pods](https://kubernetes.io/docs/concepts/workloads/pods/ "A Pod represents a set of running containers in your cluster.") and [ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/ "ReplicaSet ensures that a specified number of Pod replicas are running at one time").
+
+You describe a *desired state* in a Deployment, and the Deployment [Controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.") changes the actual state to the desired state at a controlled rate. You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.
+
+> [!info] Note:
+> Do not manage ReplicaSets owned by a Deployment. Consider opening an issue in the main Kubernetes repository if your use case is not covered below.
+
+## Use Case
+
+The following are typical use cases for Deployments:
+
+- [Create a Deployment to rollout a ReplicaSet](#creating-a-deployment). The ReplicaSet creates Pods in the background. Check the status of the rollout to see if it succeeds or not.
+- [Declare the new state of the Pods](#updating-a-deployment) by updating the PodTemplateSpec of the Deployment. A new ReplicaSet is created, and the Deployment gradually scales it up while scaling down the old ReplicaSet, ensuring Pods are replaced at a controlled rate. Each new ReplicaSet updates the revision of the Deployment.
+- [Rollback to an earlier Deployment revision](#rolling-back-a-deployment) if the current state of the Deployment is not stable. Each rollback updates the revision of the Deployment.
+- [Scale up the Deployment to facilitate more load](#scaling-a-deployment).
+- [Pause the rollout of a Deployment](#pausing-and-resuming-a-deployment) to apply multiple fixes to its PodTemplateSpec and then resume it to start a new rollout.
+- [Use the status of the Deployment](#deployment-status) as an indicator that a rollout has stuck.
+- [Clean up older ReplicaSets](#clean-up-policy) that you don't need anymore.
+
+## Creating a Deployment
+
+The following is an example of a Deployment. It creates a ReplicaSet to bring up three `nginx` Pods:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  labels:
+    app: nginx
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+```
+
+In this example:
+
+- A Deployment named `nginx-deployment` is created, indicated by the `.metadata.name` field. This name will become the basis for the ReplicaSets and Pods which are created later. See [Writing a Deployment Spec](#writing-a-deployment-spec) for more details.
+- The Deployment creates a ReplicaSet that creates three replicated Pods, indicated by the `.spec.replicas` field.
+- The `.spec.selector` field defines how the created ReplicaSet finds which Pods to manage. In this case, you select a label that is defined in the Pod template (`app: nginx`). However, more sophisticated selection rules are possible, as long as the Pod template itself satisfies the rule.
+	> [!info] Note:
+	> The `.spec.selector.matchLabels` field is a map of {key,value} pairs. A single {key,value} in the `matchLabels` map is equivalent to an element of `matchExpressions`, whose `key` field is "key", the `operator` is "In", and the `values` array contains only "value". All of the requirements, from both `matchLabels` and `matchExpressions`, must be satisfied in order to match.
+- The `.spec.template` field contains the following sub-fields:
+	- The Pods are labeled `app: nginx` using the `.metadata.labels` field.
+		- The Pod template's specification, or `.spec` field, indicates that the Pods run one container, `nginx`, which runs the `nginx` [Docker Hub](https://hub.docker.com/) image at version 1.14.2.
+		- Create one container and name it `nginx` using the `.spec.containers[0].name` field.
+
+Before you begin, make sure your Kubernetes cluster is up and running. Follow the steps given below to create the above Deployment:
+
+1. Create the Deployment by running the following command:
+	```shell
+	kubectl apply -f https://k8s.io/examples/controllers/nginx-deployment.yaml
+	```
+2. Run `kubectl get deployments` to check if the Deployment was created.
+	If the Deployment is still being created, the output is similar to the following:
+	```
+	NAME               READY   UP-TO-DATE   AVAILABLE   AGE
+	nginx-deployment   0/3     0            0           1s
+	```
+	When you inspect the Deployments in your cluster, the following fields are displayed:
+	- `NAME` lists the names of the Deployments in the namespace.
+		- `READY` displays how many replicas of the application are available to your users. It follows the pattern ready/desired.
+		- `UP-TO-DATE` displays the number of replicas that have been updated to achieve the desired state.
+		- `AVAILABLE` displays how many replicas of the application are available to your users.
+		- `AGE` displays the amount of time that the application has been running.
+	Notice how the number of desired replicas is 3 according to `.spec.replicas` field.
+3. To see the Deployment rollout status, run `kubectl rollout status deployment/nginx-deployment`.
+	The output is similar to:
+	```
+	Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
+	deployment "nginx-deployment" successfully rolled out
+	```
+4. Run the `kubectl get deployments` again a few seconds later. The output is similar to this:
+	```
+	NAME               READY   UP-TO-DATE   AVAILABLE   AGE
+	nginx-deployment   3/3     3            3           18s
+	```
+	Notice that the Deployment has created all three replicas, and all replicas are up-to-date (they contain the latest Pod template) and available.
+5. To see the ReplicaSet (`rs`) created by the Deployment, run `kubectl get rs`. The output is similar to this:
+	```
+	NAME                          DESIRED   CURRENT   READY   AGE
+	nginx-deployment-75675f5897   3         3         3       18s
+	```
+	ReplicaSet output shows the following fields:
+	- `NAME` lists the names of the ReplicaSets in the namespace.
+		- `DESIRED` displays the desired number of *replicas* of the application, which you define when you create the Deployment. This is the *desired state*.
+		- `CURRENT` displays how many replicas are currently running.
+		- `READY` displays how many replicas of the application are available to your users.
+		- `AGE` displays the amount of time that the application has been running.
+	Notice that the name of the ReplicaSet is always formatted as `[DEPLOYMENT-NAME]-[HASH]`. This name will become the basis for the Pods which are created.
+	The `HASH` string is the same as the `pod-template-hash` label on the ReplicaSet.
+6. To see the labels automatically generated for each Pod, run `kubectl get pods --show-labels`. The output is similar to:
+	```
+	NAME                                READY     STATUS    RESTARTS   AGE       LABELS
+	nginx-deployment-75675f5897-7ci7o   1/1       Running   0          18s       app=nginx,pod-template-hash=75675f5897
+	nginx-deployment-75675f5897-kzszj   1/1       Running   0          18s       app=nginx,pod-template-hash=75675f5897
+	nginx-deployment-75675f5897-qqcnn   1/1       Running   0          18s       app=nginx,pod-template-hash=75675f5897
+	```
+	The created ReplicaSet ensures that there are three `nginx` Pods.
+
+> [!info] Note:
+> You must specify an appropriate selector and Pod template labels in a Deployment (in this case, `app: nginx`).
+> 
+> Do not overlap labels or selectors with other controllers (including other Deployments and StatefulSets). Kubernetes doesn't stop you from overlapping, and if multiple controllers have overlapping selectors those controllers might conflict and behave unexpectedly.
+
+### Pod-template-hash label
+
+> [!caution] Caution:
+> Do not change this label.
+
+The `pod-template-hash` label is added by the Deployment controller to every ReplicaSet that a Deployment creates or adopts.
+
+This label ensures that child ReplicaSets of a Deployment do not overlap. It is generated by hashing the `PodTemplate` of the ReplicaSet and using the resulting hash as the label value that is added to the ReplicaSet selector, Pod template labels, and in any existing Pods that the ReplicaSet might have.
+
+## Updating a Deployment
+
+> [!info] Note:
+> A Deployment's rollout is triggered if and only if the Deployment's Pod template (that is, `.spec.template`) is changed, for example if the labels or container images of the template are updated. Other updates, such as scaling the Deployment, do not trigger a rollout.
+
+Follow the steps given below to update your Deployment:
+
+1. Let's update the nginx Pods to use the `nginx:1.16.1` image instead of the `nginx:1.14.2` image.
+	```shell
+	kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1
+	```
+	or use the following command:
+	```shell
+	kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
+	```
+	where `deployment/nginx-deployment` indicates the Deployment, `nginx` indicates the Container the update will take place and `nginx:1.16.1` indicates the new image and its tag.
+	The output is similar to:
+	```
+	deployment.apps/nginx-deployment image updated
+	```
+	Alternatively, you can `edit` the Deployment and change `.spec.template.spec.containers[0].image` from `nginx:1.14.2` to `nginx:1.16.1`:
+	```shell
+	kubectl edit deployment/nginx-deployment
+	```
+	The output is similar to:
+	```
+	deployment.apps/nginx-deployment edited
+	```
+2. To see the rollout status, run:
+	```shell
+	kubectl rollout status deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
+	```
+	or
+	```
+	deployment "nginx-deployment" successfully rolled out
+	```
+
+Get more details on your updated Deployment:
+
+- After the rollout succeeds, you can view the Deployment by running `kubectl get deployments`. The output is similar to this:
+	```
+	NAME               READY   UP-TO-DATE   AVAILABLE   AGE
+	nginx-deployment   3/3     3            3           36s
+	```
+- Run `kubectl get rs` to see that the Deployment updated the Pods by creating a new ReplicaSet and scaling it up to 3 replicas, as well as scaling down the old ReplicaSet to 0 replicas.
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME                          DESIRED   CURRENT   READY   AGE
+	nginx-deployment-1564180365   3         3         3       6s
+	nginx-deployment-2035384211   0         0         0       36s
+	```
+- Running `get pods` should now show only the new Pods:
+	```shell
+	kubectl get pods
+	```
+	The output is similar to this:
+	```
+	NAME                                READY     STATUS    RESTARTS   AGE
+	nginx-deployment-1564180365-khku8   1/1       Running   0          14s
+	nginx-deployment-1564180365-nacti   1/1       Running   0          14s
+	nginx-deployment-1564180365-z9gth   1/1       Running   0          14s
+	```
+	Next time you want to update these Pods, you only need to update the Deployment's Pod template again.
+	Deployment ensures that only a certain number of Pods are down while they are being updated. By default, it ensures that at least 75% of the desired number of Pods are up (25% max unavailable).
+	Deployment also ensures that only a certain number of Pods are created above the desired number of Pods. By default, it ensures that at most 125% of the desired number of Pods are up (25% max surge).
+	For example, if you look at the above Deployment closely, you will see that it first creates a new Pod, then deletes an old Pod, and creates another new one. It does not kill old Pods until a sufficient number of new Pods have come up, and does not create new Pods until a sufficient number of old Pods have been killed. It makes sure that at least 3 Pods are available and that at max 4 Pods in total are available. In case of a Deployment with 4 replicas, the number of Pods would be between 3 and 5.
+- Get details of your Deployment:
+	```shell
+	kubectl describe deployments
+	```
+	The output is similar to this:
+	```
+	Name:                   nginx-deployment
+	Namespace:              default
+	CreationTimestamp:      Thu, 30 Nov 2017 10:56:25 +0000
+	Labels:                 app=nginx
+	Annotations:            deployment.kubernetes.io/revision=2
+	Selector:               app=nginx
+	Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable
+	StrategyType:           RollingUpdate
+	MinReadySeconds:        0
+	RollingUpdateStrategy:  25% max unavailable, 25% max surge
+	Pod Template:
+	  Labels:  app=nginx
+	   Containers:
+	    nginx:
+	      Image:        nginx:1.16.1
+	      Port:         80/TCP
+	      Environment:  <none>
+	      Mounts:       <none>
+	    Volumes:        <none>
+	  Conditions:
+	    Type           Status  Reason
+	    ----           ------  ------
+	    Available      True    MinimumReplicasAvailable
+	    Progressing    True    NewReplicaSetAvailable
+	  OldReplicaSets:  <none>
+	  NewReplicaSet:   nginx-deployment-1564180365 (3/3 replicas created)
+	  Events:
+	    Type    Reason             Age   From                   Message
+	    ----    ------             ----  ----                   -------
+	    Normal  ScalingReplicaSet  2m    deployment-controller  Scaled up replica set nginx-deployment-2035384211 to 3
+	    Normal  ScalingReplicaSet  24s   deployment-controller  Scaled up replica set nginx-deployment-1564180365 to 1
+	    Normal  ScalingReplicaSet  22s   deployment-controller  Scaled down replica set nginx-deployment-2035384211 to 2
+	    Normal  ScalingReplicaSet  22s   deployment-controller  Scaled up replica set nginx-deployment-1564180365 to 2
+	    Normal  ScalingReplicaSet  19s   deployment-controller  Scaled down replica set nginx-deployment-2035384211 to 1
+	    Normal  ScalingReplicaSet  19s   deployment-controller  Scaled up replica set nginx-deployment-1564180365 to 3
+	    Normal  ScalingReplicaSet  14s   deployment-controller  Scaled down replica set nginx-deployment-2035384211 to 0
+	```
+	Here you see that when you first created the Deployment, it created a ReplicaSet (nginx-deployment-2035384211) and scaled it up to 3 replicas directly. When you updated the Deployment, it created a new ReplicaSet (nginx-deployment-1564180365) and scaled it up to 1 and waited for it to come up. Then it scaled down the old ReplicaSet to 2 and scaled up the new ReplicaSet to 2 so that at least 3 Pods were available and at most 4 Pods were created at all times. It then continued scaling up and down the new and the old ReplicaSet, with the same rolling update strategy. Finally, you'll have 3 available replicas in the new ReplicaSet, and the old ReplicaSet is scaled down to 0.
+
+> [!info] Note:
+> Kubernetes doesn't count terminating Pods when calculating the number of `availableReplicas`, which must be between `replicas - maxUnavailable` and `replicas + maxSurge`. As a result, you might notice that there are more Pods than expected during a rollout, and that the total resources consumed by the Deployment is more than `replicas + maxSurge` until the `terminationGracePeriodSeconds` of the terminating Pods expires.
+
+### Rollover (aka multiple updates in-flight)
+
+Each time a new Deployment is observed by the Deployment controller, a ReplicaSet is created to bring up the desired Pods. If the Deployment is updated, the existing ReplicaSet that controls Pods whose labels match `.spec.selector` but whose template does not match `.spec.template` is scaled down. Eventually, the new ReplicaSet is scaled to `.spec.replicas` and all old ReplicaSets is scaled to 0.
+
+If you update a Deployment while an existing rollout is in progress, the Deployment creates a new ReplicaSet as per the update and start scaling that up, and rolls over the ReplicaSet that it was scaling up previously -- it will add it to its list of old ReplicaSets and start scaling it down.
+
+For example, suppose you create a Deployment to create 5 replicas of `nginx:1.14.2`, but then update the Deployment to create 5 replicas of `nginx:1.16.1`, when only 3 replicas of `nginx:1.14.2` had been created. In that case, the Deployment immediately starts killing the 3 `nginx:1.14.2` Pods that it had created, and starts creating `nginx:1.16.1` Pods. It does not wait for the 5 replicas of `nginx:1.14.2` to be created before changing course.
+
+### Label selector updates
+
+It is generally discouraged to make label selector updates and it is suggested to plan your selectors up front. A Deployment's label selector is **immutable** after creation; it cannot be updated via `kubectl patch`, `kubectl edit`, `kubectl apply`, or tools like `helm upgrade`.
+
+If you must change the selector, you have to delete the Deployment and recreate it. Exercise great caution and ensure you grasp the following implications:
+
+- **Additions:** When you create a new Deployment with a narrower selector, the new Deployment **must** also have a suitable Pod template. If you have an existing manifest and you edit the manifest to narrow the selector, you need to edit the metadata of the Pod template inside that Deployment, adding the new labels to match, as otherwise the API server returns a validation error. This is a *non-overlapping* change: the new Deployment will not "see" the old Pods (which lack the new label), causing the old ReplicaSet to be **orphaned** and a brand-new ReplicaSet to be created.
+- **Value Updates:** Changing the existing value in a selector key (e.g., from `v1` to `v2`) results in the same behavior as additions (orphaning and recreation).
+- **Removals:** Removing an existing key from the Deployment selector does not require any changes in the Pod template labels. This is an *overlapping* change: the new, broader selector would match the old Pods. Existing ReplicaSets are not orphaned, and a new ReplicaSet is not created, but note that the removed label still exists in any existing Pods and ReplicaSets. You can clean that up by triggering a rollout for the Deployment.
+
+## Rolling Back a Deployment
+
+Sometimes, you may want to rollback a Deployment; for example, when the Deployment is not stable, such as crash looping. By default, all of the Deployment's rollout history is kept in the system so that you can rollback anytime you want (you can change that by modifying revision history limit).
+
+> [!info] Note:
+> A Deployment's revision is created when a Deployment's rollout is triggered. This means that the new revision is created if and only if the Deployment's Pod template (`.spec.template`) is changed, for example if you update the labels or container images of the template. Other updates, such as scaling the Deployment, do not create a Deployment revision, so that you can facilitate simultaneous manual- or auto-scaling. This means that when you roll back to an earlier revision, only the Deployment's Pod template part is rolled back.
+
+- Suppose that you made a typo while updating the Deployment, by putting the image name as `nginx:1.161` instead of `nginx:1.16.1`:
+	```shell
+	kubectl set image deployment/nginx-deployment nginx=nginx:1.161
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment image updated
+	```
+- The rollout gets stuck. You can verify it by checking the rollout status:
+	```shell
+	kubectl rollout status deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	Waiting for rollout to finish: 1 out of 3 new replicas have been updated...
+	```
+- Press Ctrl-C to stop the above rollout status watch. For more information on stuck rollouts, [read more here](#deployment-status).
+- You see that the number of old replicas (adding the replica count from `nginx-deployment-1564180365` and `nginx-deployment-2035384211`) is 3, and the number of new replicas (from `nginx-deployment-3066724191`) is 1.
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME                          DESIRED   CURRENT   READY   AGE
+	nginx-deployment-1564180365   3         3         3       25s
+	nginx-deployment-2035384211   0         0         0       36s
+	nginx-deployment-3066724191   1         1         0       6s
+	```
+- Looking at the Pods created, you see that 1 Pod created by new ReplicaSet is stuck in an image pull loop.
+	```shell
+	kubectl get pods
+	```
+	The output is similar to this:
+	```
+	NAME                                READY     STATUS             RESTARTS   AGE
+	nginx-deployment-1564180365-70iae   1/1       Running            0          25s
+	nginx-deployment-1564180365-jbqqo   1/1       Running            0          25s
+	nginx-deployment-1564180365-hysrc   1/1       Running            0          25s
+	nginx-deployment-3066724191-08mng   0/1       ImagePullBackOff   0          6s
+	```
+	> [!info] Note:
+	> The Deployment controller stops the bad rollout automatically, and stops scaling up the new ReplicaSet. This depends on the rollingUpdate parameters (`maxUnavailable` specifically) that you have specified. Kubernetes by default sets the value to 25%.
+- Get the description of the Deployment:
+	```shell
+	kubectl describe deployment
+	```
+	The output is similar to this:
+	```
+	Name:           nginx-deployment
+	Namespace:      default
+	CreationTimestamp:  Tue, 15 Mar 2016 14:48:04 -0700
+	Labels:         app=nginx
+	Selector:       app=nginx
+	Replicas:       3 desired | 1 updated | 4 total | 3 available | 1 unavailable
+	StrategyType:       RollingUpdate
+	MinReadySeconds:    0
+	RollingUpdateStrategy:  25% max unavailable, 25% max surge
+	Pod Template:
+	  Labels:  app=nginx
+	  Containers:
+	   nginx:
+	    Image:        nginx:1.161
+	    Port:         80/TCP
+	    Host Port:    0/TCP
+	    Environment:  <none>
+	    Mounts:       <none>
+	  Volumes:        <none>
+	Conditions:
+	  Type           Status  Reason
+	  ----           ------  ------
+	  Available      True    MinimumReplicasAvailable
+	  Progressing    True    ReplicaSetUpdated
+	OldReplicaSets:     nginx-deployment-1564180365 (3/3 replicas created)
+	NewReplicaSet:      nginx-deployment-3066724191 (1/1 replicas created)
+	Events:
+	  FirstSeen LastSeen    Count   From                    SubObjectPath   Type        Reason              Message
+	  --------- --------    -----   ----                    -------------   --------    ------              -------
+	  1m        1m          1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled up replica set nginx-deployment-2035384211 to 3
+	  22s       22s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled up replica set nginx-deployment-1564180365 to 1
+	  22s       22s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled down replica set nginx-deployment-2035384211 to 2
+	  22s       22s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled up replica set nginx-deployment-1564180365 to 2
+	  21s       21s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled down replica set nginx-deployment-2035384211 to 1
+	  21s       21s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled up replica set nginx-deployment-1564180365 to 3
+	  13s       13s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled down replica set nginx-deployment-2035384211 to 0
+	  13s       13s         1       {deployment-controller }                Normal      ScalingReplicaSet   Scaled up replica set nginx-deployment-3066724191 to 1
+	```
+	To fix this, you need to rollback to a previous revision of Deployment that is stable.
+
+### Checking Rollout History of a Deployment
+
+Follow the steps given below to check the rollout history:
+
+1. First, check the revisions of this Deployment:
+	```shell
+	kubectl rollout history deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	deployments "nginx-deployment"
+	REVISION    CHANGE-CAUSE
+	1           <none>
+	2           <none>
+	3           <none>
+	```
+	`CHANGE-CAUSE` is copied from the Deployment annotation `kubernetes.io/change-cause` to its revisions upon creation. You can specify the `CHANGE-CAUSE` message by:
+	- Annotating the Deployment with `kubectl annotate deployment/nginx-deployment kubernetes.io/change-cause="image updated to 1.16.1"`
+		- Manually editing the manifest of the resource.
+		- Using tooling that sets the annotation automatically.
+	> [!info] Note:
+	> In older versions of Kubernetes, you could use the `--record` flag with kubectl commands to automatically populate the `CHANGE-CAUSE` field. This flag is deprecated and will be removed in a future release.
+2. To see the details of each revision, run:
+	```shell
+	kubectl rollout history deployment/nginx-deployment --revision=2
+	```
+	The output is similar to this:
+	```
+	deployments "nginx-deployment" revision 2
+	  Labels:       app=nginx
+	          pod-template-hash=1159050644
+	  Containers:
+	   nginx:
+	    Image:      nginx:1.16.1
+	    Port:       80/TCP
+	     QoS Tier:
+	        cpu:      BestEffort
+	        memory:   BestEffort
+	    Environment Variables:      <none>
+	  No volumes.
+	```
+
+### Rolling Back to a Previous Revision
+
+Follow the steps given below to rollback the Deployment from the current version to the previous version, which is version 2.
+
+1. Now you've decided to undo the current rollout and rollback to the previous revision:
+	```shell
+	kubectl rollout undo deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment rolled back
+	```
+	Alternatively, you can rollback to a specific revision by specifying it with `--to-revision`:
+	```shell
+	kubectl rollout undo deployment/nginx-deployment --to-revision=2
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment rolled back
+	```
+	For more details about rollout related commands, read [`kubectl rollout`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#rollout).
+	The Deployment is now rolled back to a previous stable revision. As you can see, a `DeploymentRollback` event for rolling back to revision 2 is generated from Deployment controller.
+2. Check if the rollback was successful and the Deployment is running as expected, run:
+	```shell
+	kubectl get deployment nginx-deployment
+	```
+	The output is similar to this:
+	```
+	NAME               READY   UP-TO-DATE   AVAILABLE   AGE
+	nginx-deployment   3/3     3            3           30m
+	```
+3. Get the description of the Deployment:
+	```shell
+	kubectl describe deployment nginx-deployment
+	```
+	The output is similar to this:
+	```
+	Name:                   nginx-deployment
+	Namespace:              default
+	CreationTimestamp:      Sun, 02 Sep 2018 18:17:55 -0500
+	Labels:                 app=nginx
+	Annotations:            deployment.kubernetes.io/revision=4
+	Selector:               app=nginx
+	Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable
+	StrategyType:           RollingUpdate
+	MinReadySeconds:        0
+	RollingUpdateStrategy:  25% max unavailable, 25% max surge
+	Pod Template:
+	  Labels:  app=nginx
+	  Containers:
+	   nginx:
+	    Image:        nginx:1.16.1
+	    Port:         80/TCP
+	    Host Port:    0/TCP
+	    Environment:  <none>
+	    Mounts:       <none>
+	  Volumes:        <none>
+	Conditions:
+	  Type           Status  Reason
+	  ----           ------  ------
+	  Available      True    MinimumReplicasAvailable
+	  Progressing    True    NewReplicaSetAvailable
+	OldReplicaSets:  <none>
+	NewReplicaSet:   nginx-deployment-c4747d96c (3/3 replicas created)
+	Events:
+	  Type    Reason              Age   From                   Message
+	  ----    ------              ----  ----                   -------
+	  Normal  ScalingReplicaSet   12m   deployment-controller  Scaled up replica set nginx-deployment-75675f5897 to 3
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled up replica set nginx-deployment-c4747d96c to 1
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled down replica set nginx-deployment-75675f5897 to 2
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled up replica set nginx-deployment-c4747d96c to 2
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled down replica set nginx-deployment-75675f5897 to 1
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled up replica set nginx-deployment-c4747d96c to 3
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled down replica set nginx-deployment-75675f5897 to 0
+	  Normal  ScalingReplicaSet   11m   deployment-controller  Scaled up replica set nginx-deployment-595696685f to 1
+	  Normal  DeploymentRollback  15s   deployment-controller  Rolled back deployment "nginx-deployment" to revision 2
+	  Normal  ScalingReplicaSet   15s   deployment-controller  Scaled down replica set nginx-deployment-595696685f to 0
+	```
+
+## Scaling a Deployment
+
+You can scale a Deployment by using the following command:
+
+```shell
+kubectl scale deployment/nginx-deployment --replicas=10
+```
+
+The output is similar to this:
+
+```
+deployment.apps/nginx-deployment scaled
+```
+
+Assuming [horizontal Pod autoscaling](https://kubernetes.io/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/) is enabled in your cluster, you can set up an autoscaler for your Deployment and choose the minimum and maximum number of Pods you want to run based on the CPU utilization of your existing Pods.
+
+```shell
+kubectl autoscale deployment/nginx-deployment --min=10 --max=15 --cpu-percent=80%
+```
+
+The output is similar to this:
+
+```
+deployment.apps/nginx-deployment scaled
+```
+
+### Proportional scaling
+
+RollingUpdate Deployments support running multiple versions of an application at the same time. When you or an autoscaler scales a RollingUpdate Deployment that is in the middle of a rollout (either in progress or paused), the Deployment controller balances the additional replicas in the existing active ReplicaSets (ReplicaSets with Pods) in order to mitigate risk. This is called *proportional scaling*.
+
+For example, you are running a Deployment with 10 replicas, [maxSurge](#max-surge) =3, and [maxUnavailable](#max-unavailable) =2.
+
+- Ensure that the 10 replicas in your Deployment are running.
+	```shell
+	kubectl get deploy
+	```
+	The output is similar to this:
+	```
+	NAME                 DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+	nginx-deployment     10        10        10           10          50s
+	```
+- You update to a new image which happens to be unresolvable from inside the cluster.
+	```shell
+	kubectl set image deployment/nginx-deployment nginx=nginx:sometag
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment image updated
+	```
+- The image update starts a new rollout with ReplicaSet nginx-deployment-1989198191, but it's blocked due to the `maxUnavailable` requirement that you mentioned above. Check out the rollout status:
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME                          DESIRED   CURRENT   READY     AGE
+	nginx-deployment-1989198191   5         5         0         9s
+	nginx-deployment-618515232    8         8         8         1m
+	```
+- Then a new scaling request for the Deployment comes along. The autoscaler increments the Deployment replicas to 15. The Deployment controller needs to decide where to add these new 5 replicas. If you weren't using proportional scaling, all 5 of them would be added in the new ReplicaSet. With proportional scaling, you spread the additional replicas across all ReplicaSets. Bigger proportions go to the ReplicaSets with the most replicas and lower proportions go to ReplicaSets with less replicas. Any leftovers are added to the ReplicaSet with the most replicas. ReplicaSets with zero replicas are not scaled up.
+
+In our example above, 3 replicas are added to the old ReplicaSet and 2 replicas are added to the new ReplicaSet. The rollout process should eventually move all replicas to the new ReplicaSet, assuming the new replicas become healthy. To confirm this, run:
+
+```shell
+kubectl get deploy
+```
+
+The output is similar to this:
+
+```
+NAME                 DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+nginx-deployment     15        18        7            8           7m
+```
+
+The rollout status confirms how the replicas were added to each ReplicaSet.
+
+```shell
+kubectl get rs
+```
+
+The output is similar to this:
+
+```
+NAME                          DESIRED   CURRENT   READY     AGE
+nginx-deployment-1989198191   7         7         0         7m
+nginx-deployment-618515232    11        11        11        7m
+```
+
+## Pausing and Resuming a rollout of a Deployment
+
+When you update a Deployment, or plan to, you can pause rollouts for that Deployment before you trigger one or more updates. When you're ready to apply those changes, you resume rollouts for the Deployment. This approach allows you to apply multiple fixes in between pausing and resuming without triggering unnecessary rollouts.
+
+- For example, with a Deployment that was created:
+	Get the Deployment details:
+	```shell
+	kubectl get deploy
+	```
+	The output is similar to this:
+	```
+	NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
+	nginx     3         3         3            3           1m
+	```
+	Get the rollout status:
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME               DESIRED   CURRENT   READY     AGE
+	nginx-2142116321   3         3         3         1m
+	```
+- Pause by running the following command:
+	```shell
+	kubectl rollout pause deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment paused
+	```
+- Then update the image of the Deployment:
+	```shell
+	kubectl set image deployment/nginx-deployment nginx=nginx:1.16.1
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment image updated
+	```
+- Notice that no new rollout started:
+	```shell
+	kubectl rollout history deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	deployments "nginx"
+	REVISION  CHANGE-CAUSE
+	1   <none>
+	```
+- Get the rollout status to verify that the existing ReplicaSet has not changed:
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME               DESIRED   CURRENT   READY     AGE
+	nginx-2142116321   3         3         3         2m
+	```
+- You can make as many updates as you wish, for example, update the resources that will be used:
+	```shell
+	kubectl set resources deployment/nginx-deployment -c=nginx --limits=cpu=200m,memory=512Mi
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment resource requirements updated
+	```
+	The initial state of the Deployment prior to pausing its rollout will continue its function, but new updates to the Deployment will not have any effect as long as the Deployment rollout is paused.
+- Eventually, resume the Deployment rollout and observe a new ReplicaSet coming up with all the new updates:
+	```shell
+	kubectl rollout resume deployment/nginx-deployment
+	```
+	The output is similar to this:
+	```
+	deployment.apps/nginx-deployment resumed
+	```
+- [Watch](https://kubernetes.io/docs/reference/using-api/api-concepts/#api-verbs "A verb that is used to track changes to an object in Kubernetes as a stream.") the status of the rollout until it's done.
+	```shell
+	kubectl get rs --watch
+	```
+	The output is similar to this:
+	```
+	NAME               DESIRED   CURRENT   READY     AGE
+	nginx-2142116321   2         2         2         2m
+	nginx-3926361531   2         2         0         6s
+	nginx-3926361531   2         2         1         18s
+	nginx-2142116321   1         2         2         2m
+	nginx-2142116321   1         2         2         2m
+	nginx-3926361531   3         2         1         18s
+	nginx-3926361531   3         2         1         18s
+	nginx-2142116321   1         1         1         2m
+	nginx-3926361531   3         3         1         18s
+	nginx-3926361531   3         3         2         19s
+	nginx-2142116321   0         1         1         2m
+	nginx-2142116321   0         1         1         2m
+	nginx-2142116321   0         0         0         2m
+	nginx-3926361531   3         3         3         20s
+	```
+- Get the status of the latest rollout:
+	```shell
+	kubectl get rs
+	```
+	The output is similar to this:
+	```
+	NAME               DESIRED   CURRENT   READY     AGE
+	nginx-2142116321   0         0         0         2m
+	nginx-3926361531   3         3         3         28s
+	```
+
+> [!info] Note:
+> You cannot rollback a paused Deployment until you resume it.
+
+## Deployment status
+
+A Deployment enters various states during its lifecycle. It can be [progressing](#progressing-deployment) while rolling out a new ReplicaSet, it can be [complete](#complete-deployment), or it can [fail to progress](#failed-deployment).
+
+### Progressing Deployment
+
+Kubernetes marks a Deployment as *progressing* when one of the following tasks is performed:
+
+- The Deployment creates a new ReplicaSet.
+- The Deployment is scaling up its newest ReplicaSet.
+- The Deployment is scaling down its older ReplicaSet(s).
+- New Pods become ready or available (ready for at least [MinReadySeconds](#min-ready-seconds)).
+
+When the rollout becomes “progressing”, the Deployment controller adds a condition with the following attributes to the Deployment's `.status.conditions`:
+
+- `type: Progressing`
+- `status: "True"`
+- `reason: NewReplicaSetCreated` | `reason: FoundNewReplicaSet` | `reason: ReplicaSetUpdated`
+
+You can monitor the progress for a Deployment by using `kubectl rollout status`.
+
+### Complete Deployment
+
+Kubernetes marks a Deployment as *complete* when it has the following characteristics:
+
+- All of the replicas associated with the Deployment have been updated to the latest version you've specified, meaning any updates you've requested have been completed.
+- All of the replicas associated with the Deployment are available.
+- No old replicas for the Deployment are running.
+
+When the rollout becomes “complete”, the Deployment controller sets a condition with the following attributes to the Deployment's `.status.conditions`:
+
+- `type: Progressing`
+- `status: "True"`
+- `reason: NewReplicaSetAvailable`
+
+This `Progressing` condition will retain a status value of `"True"` until a new rollout is initiated. The condition holds even when availability of replicas changes (which does instead affect the `Available` condition).
+
+You can check if a Deployment has completed by using `kubectl rollout status`. If the rollout completed successfully, `kubectl rollout status` returns a zero exit code.
+
+```shell
+kubectl rollout status deployment/nginx-deployment
+```
+
+The output is similar to this:
+
+```
+Waiting for rollout to finish: 2 of 3 updated replicas are available...
+deployment "nginx-deployment" successfully rolled out
+```
+
+and the exit status from `kubectl rollout` is 0 (success):
+
+```shell
+echo $?
+```
+```
+0
+```
+
+### Failed Deployment
+
+Your Deployment may get stuck trying to deploy its newest ReplicaSet without ever completing. This can occur due to some of the following factors:
+
+- Insufficient quota
+- Readiness probe failures
+- Image pull errors
+- Insufficient permissions
+- Limit ranges
+- Application runtime misconfiguration
+
+One way you can detect this condition is to specify a deadline parameter in your Deployment spec: ([`.spec.progressDeadlineSeconds`](#progress-deadline-seconds)). `.spec.progressDeadlineSeconds` denotes the number of seconds the Deployment controller waits before indicating (in the Deployment status) that the Deployment progress has stalled.
+
+The following `kubectl` command sets the spec with `progressDeadlineSeconds` to make the controller report lack of progress of a rollout for a Deployment after 10 minutes:
+
+```shell
+kubectl patch deployment/nginx-deployment -p '{"spec":{"progressDeadlineSeconds":600}}'
+```
+
+The output is similar to this:
+
+```
+deployment.apps/nginx-deployment patched
+```
+
+Once the deadline has been exceeded, the Deployment controller adds a DeploymentCondition with the following attributes to the Deployment's `.status.conditions`:
+
+- `type: Progressing`
+- `status: "False"`
+- `reason: ProgressDeadlineExceeded`
+
+This condition can also fail early and is then set to status value of `"False"` due to reasons as `ReplicaSetCreateError`. Also, the deadline is not taken into account anymore once the Deployment rollout completes.
+
+See the [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) for more information on status conditions.
+
+> [!info] Note:
+> Kubernetes takes no action on a stalled Deployment other than to report a status condition with `reason: ProgressDeadlineExceeded`. Higher level orchestrators can take advantage of it and act accordingly, for example, rollback the Deployment to its previous version.
+
+> [!info] Note:
+> If you pause a Deployment rollout, Kubernetes does not check progress against your specified deadline. You can safely pause a Deployment rollout in the middle of a rollout and resume without triggering the condition for exceeding the deadline.
+
+You may experience transient errors with your Deployments, either due to a low timeout that you have set or due to any other kind of error that can be treated as transient. For example, let's suppose you have insufficient quota. If you describe the Deployment you will notice the following section:
+
+```shell
+kubectl describe deployment nginx-deployment
+```
+
+The output is similar to this:
+
+```
+<...>
+Conditions:
+  Type            Status  Reason
+  ----            ------  ------
+  Available       True    MinimumReplicasAvailable
+  Progressing     True    ReplicaSetUpdated
+  ReplicaFailure  True    FailedCreate
+<...>
+```
+
+If you run `kubectl get deployment nginx-deployment -o yaml`, the Deployment status is similar to this:
+
+```
+status:
+  availableReplicas: 2
+  conditions:
+  - lastTransitionTime: 2016-10-04T12:25:39Z
+    lastUpdateTime: 2016-10-04T12:25:39Z
+    message: Replica set "nginx-deployment-4262182780" is progressing.
+    reason: ReplicaSetUpdated
+    status: "True"
+    type: Progressing
+  - lastTransitionTime: 2016-10-04T12:25:42Z
+    lastUpdateTime: 2016-10-04T12:25:42Z
+    message: Deployment has minimum availability.
+    reason: MinimumReplicasAvailable
+    status: "True"
+    type: Available
+  - lastTransitionTime: 2016-10-04T12:25:39Z
+    lastUpdateTime: 2016-10-04T12:25:39Z
+    message: 'Error creating: pods "nginx-deployment-4262182780-" is forbidden: exceeded quota:
+      object-counts, requested: pods=1, used: pods=3, limited: pods=2'
+    reason: FailedCreate
+    status: "True"
+    type: ReplicaFailure
+  observedGeneration: 3
+  replicas: 2
+  unavailableReplicas: 2
+```
+
+Eventually, once the Deployment progress deadline is exceeded, Kubernetes updates the status and the reason for the Progressing condition:
+
+```
+Conditions:
+  Type            Status  Reason
+  ----            ------  ------
+  Available       True    MinimumReplicasAvailable
+  Progressing     False   ProgressDeadlineExceeded
+  ReplicaFailure  True    FailedCreate
+```
+
+You can address an issue of insufficient quota by scaling down your Deployment, by scaling down other controllers you may be running, or by increasing quota in your namespace. If you satisfy the quota conditions and the Deployment controller then completes the Deployment rollout, you'll see the Deployment's status update with a successful condition (`status: "True"` and `reason: NewReplicaSetAvailable`).
+
+```
+Conditions:
+  Type          Status  Reason
+  ----          ------  ------
+  Available     True    MinimumReplicasAvailable
+  Progressing   True    NewReplicaSetAvailable
+```
+
+`type: Available` with `status: "True"` means that your Deployment has minimum availability. Minimum availability is dictated by the parameters specified in the deployment strategy. `type: Progressing` with `status: "True"` means that your Deployment is either in the middle of a rollout and it is progressing or that it has successfully completed its progress and the minimum required new replicas are available (see the Reason of the condition for the particulars - in our case `reason: NewReplicaSetAvailable` means that the Deployment is complete).
+
+You can check if a Deployment has failed to progress by using `kubectl rollout status`. `kubectl rollout status` returns a non-zero exit code if the Deployment has exceeded the progression deadline.
+
+```shell
+kubectl rollout status deployment/nginx-deployment
+```
+
+The output is similar to this:
+
+```
+Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
+error: deployment "nginx" exceeded its progress deadline
+```
+
+and the exit status from `kubectl rollout` is 1 (indicating an error):
+
+```shell
+echo $?
+```
+```
+1
+```
+
+### Operating on a failed deployment
+
+All actions that apply to a complete Deployment also apply to a failed Deployment. You can scale it up/down, roll back to a previous revision, or even pause it if you need to apply multiple tweaks in the Deployment Pod template.
+
+## Clean up Policy
+
+You can set `.spec.revisionHistoryLimit` field in a Deployment to specify how many old ReplicaSets for this Deployment you want to retain. The rest will be garbage-collected in the background. By default, it is 10.
+
+> [!info] Note:
+> Explicitly setting this field to 0, will result in cleaning up all the history of your Deployment thus that Deployment will not be able to roll back.
+
+The cleanup only starts **after** a Deployment reaches a [complete state](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#complete-deployment). If you set `.spec.revisionHistoryLimit` to 0, any rollout nonetheless triggers creation of a new ReplicaSet before Kubernetes removes the old one.
+
+Even with a non-zero revision history limit, you can have more ReplicaSets than the limit you configure. For example, if pods are crash looping, and there are multiple rolling updates events triggered over time, you might end up with more ReplicaSets than the `.spec.revisionHistoryLimit` because the Deployment never reaches a complete state.
+
+## Canary Deployment
+
+If you want to roll out releases to a subset of users or servers using the Deployment, you can create multiple Deployments, one for each release, following the canary pattern described in [managing resources](https://kubernetes.io/docs/concepts/workloads/management/#canary-deployments).
+
+## Writing a Deployment Spec
+
+As with all other Kubernetes configs, a Deployment needs `.apiVersion`, `.kind`, and `.metadata` fields. For general information about working with config files, see [deploying applications](https://kubernetes.io/docs/tasks/run-application/run-stateless-application-deployment/), configuring containers, and [using kubectl to manage resources](https://kubernetes.io/docs/concepts/overview/working-with-objects/object-management/) documents.
+
+When the control plane creates new Pods for a Deployment, the `.metadata.name` of the Deployment is part of the basis for naming those Pods. The name of a Deployment must be a valid [DNS subdomain](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) value, but this can produce unexpected results for the Pod hostnames. For best compatibility, the name should follow the more restrictive rules for a [DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names).
+
+A Deployment also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
+
+### Pod Template
+
+The `.spec.template` and `.spec.selector` are the only required fields of the `.spec`.
+
+The `.spec.template` is a [Pod template](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). It has exactly the same schema as a [Pod](https://kubernetes.io/docs/concepts/workloads/pods/ "A Pod represents a set of running containers in your cluster."), except it is nested and does not have an `apiVersion` or `kind`.
+
+In addition to required fields for a Pod, a Pod template in a Deployment must specify appropriate labels and an appropriate restart policy. For labels, make sure not to overlap with other controllers. See [selector](#selector).
+
+Only a [`.spec.template.spec.restartPolicy`](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy) equal to `Always` is allowed, which is the default if not specified.
+
+### Replicas
+
+`.spec.replicas` is an optional field that specifies the number of desired Pods. It defaults to 1.
+
+Should you manually scale a Deployment, example via `kubectl scale deployment deployment --replicas=X`, and then you update that Deployment based on a manifest (for example: by running `kubectl apply -f deployment.yaml`), then applying that manifest overwrites the manual scaling that you previously did.
+
+If a [HorizontalPodAutoscaler](https://kubernetes.io/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/) (or any similar API for horizontal scaling) is managing scaling for a Deployment, don't set `.spec.replicas`.
+
+Instead, allow the Kubernetes [control plane](https://kubernetes.io/docs/reference/glossary/?all=true#term-control-plane "The container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers.") to manage the `.spec.replicas` field automatically.
+
+### Selector
+
+`.spec.selector` is a required field that specifies a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) for the Pods targeted by this Deployment.
+
+`.spec.selector` must match `.spec.template.metadata.labels`, or it will be rejected by the API.
+
+In API version `apps/v1`, `.spec.selector` and `.metadata.labels` do not default to `.spec.template.metadata.labels` if not set. So they must be set explicitly. Also note that `.spec.selector` is immutable after creation of the Deployment in `apps/v1`.
+
+A Deployment may terminate Pods whose labels match the selector if their template is different from `.spec.template` or if the total number of such Pods exceeds `.spec.replicas`. It brings up new Pods with `.spec.template` if the number of Pods is less than the desired number.
+
+> [!info] Note:
+> You should not create other Pods whose labels match this selector, either directly, by creating another Deployment, or by creating another controller such as a ReplicaSet or a ReplicationController. If you do so, the first Deployment thinks that it created these other Pods. Kubernetes does not stop you from doing this.
+
+If you have multiple controllers that have overlapping selectors, the controllers will fight with each other and won't behave correctly.
+
+### Strategy
+
+`.spec.strategy` specifies the strategy used to replace old Pods by new ones. `.spec.strategy.type` can be "Recreate" or "RollingUpdate". "RollingUpdate" is the default value.
+
+#### Recreate Deployment
+
+All existing Pods are killed before new ones are created when `.spec.strategy.type==Recreate`.
+
+> [!info] Note:
+> This will only guarantee Pod termination previous to creation for upgrades. If you upgrade a Deployment, all Pods of the old revision will be terminated immediately. Successful removal is awaited before any Pod of the new revision is created. If you manually delete a Pod, the lifecycle is controlled by the ReplicaSet and the replacement will be created immediately (even if the old Pod is still in a Terminating state). If you need an "at most" guarantee for your Pods, you should consider using a [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/).
+
+#### Rolling Update Deployment
+
+The Deployment updates Pods in a rolling update fashion (gradually scale down the old ReplicaSets and scale up the new one) when `.spec.strategy.type==RollingUpdate`. You can specify `maxUnavailable` and `maxSurge` to control the rolling update process.
+
+##### Max Unavailable
+
+`.spec.strategy.rollingUpdate.maxUnavailable` is an optional field that specifies the maximum number of Pods that can be unavailable during the update process. The value can be an absolute number (for example, 5) or a percentage of desired Pods (for example, 10%). The absolute number is calculated from percentage by rounding down. The value cannot be 0 if `.spec.strategy.rollingUpdate.maxSurge` is 0. The default value is 25%.
+
+For example, when this value is set to 30%, the old ReplicaSet can be scaled down to 70% of desired Pods immediately when the rolling update starts. Once new Pods are ready, old ReplicaSet can be scaled down further, followed by scaling up the new ReplicaSet, ensuring that the total number of Pods available at all times during the update is at least 70% of the desired Pods.
+
+##### Max Surge
+
+`.spec.strategy.rollingUpdate.maxSurge` is an optional field that specifies the maximum number of Pods that can be created over the desired number of Pods. The value can be an absolute number (for example, 5) or a percentage of desired Pods (for example, 10%). The value cannot be 0 if `maxUnavailable` is 0. The absolute number is calculated from the percentage by rounding up. The default value is 25%.
+
+For example, when this value is set to 30%, the new ReplicaSet can be scaled up immediately when the rolling update starts, such that the total number of old and new Pods does not exceed 130% of desired Pods. Once old Pods have been killed, the new ReplicaSet can be scaled up further, ensuring that the total number of Pods running at any time during the update is at most 130% of desired Pods.
+
+Here are some Rolling Update Deployment examples that use the `maxUnavailable` and `maxSurge`:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: nginx-deployment
+ labels:
+   app: nginx
+spec:
+ replicas: 3
+ selector:
+   matchLabels:
+     app: nginx
+ template:
+   metadata:
+     labels:
+       app: nginx
+   spec:
+     containers:
+     - name: nginx
+       image: nginx:1.14.2
+       ports:
+       - containerPort: 80
+ strategy:
+   type: RollingUpdate
+   rollingUpdate:
+     maxUnavailable: 1
+```
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: nginx-deployment
+ labels:
+   app: nginx
+spec:
+ replicas: 3
+ selector:
+   matchLabels:
+     app: nginx
+ template:
+   metadata:
+     labels:
+       app: nginx
+   spec:
+     containers:
+     - name: nginx
+       image: nginx:1.14.2
+       ports:
+       - containerPort: 80
+ strategy:
+   type: RollingUpdate
+   rollingUpdate:
+     maxSurge: 1
+```
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: nginx-deployment
+ labels:
+   app: nginx
+spec:
+ replicas: 3
+ selector:
+   matchLabels:
+     app: nginx
+ template:
+   metadata:
+     labels:
+       app: nginx
+   spec:
+     containers:
+     - name: nginx
+       image: nginx:1.14.2
+       ports:
+       - containerPort: 80
+ strategy:
+   type: RollingUpdate
+   rollingUpdate:
+     maxSurge: 1
+     maxUnavailable: 1
+```
+
+### Progress Deadline Seconds
+
+`.spec.progressDeadlineSeconds` is an optional field that specifies the number of seconds you want to wait for your Deployment to progress before the system reports back that the Deployment has [failed progressing](#failed-deployment) - surfaced as a condition with `type: Progressing`, `status: "False"`. and `reason: ProgressDeadlineExceeded` in the status of the resource. The Deployment controller will keep retrying the Deployment. This defaults to 600. In the future, once automatic rollback will be implemented, the Deployment controller will roll back a Deployment as soon as it observes such a condition.
+
+If specified, this field needs to be greater than `.spec.minReadySeconds`.
+
+### Min Ready Seconds
+
+`.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. This 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](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes).
+
+### Terminating Pods
+
+FEATURE STATE: `Kubernetes v1.35 [beta]` (enabled by default)
+
+You can see the terminating pods only if the `DeploymentReplicaSetTerminatingReplicas` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) is enabled on the [API server](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) and on the [kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume additional resources during that period. As a result, the total number of all pods can temporarily exceed `.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the Deployment.
+
+### Revision History Limit
+
+A Deployment's revision history is stored in the ReplicaSets it controls.
+
+`.spec.revisionHistoryLimit` is an optional field that specifies the number of old ReplicaSets to retain to allow rollback. These old ReplicaSets consume resources in `etcd` and crowd the output of `kubectl get rs`. The configuration of each Deployment revision is stored in its ReplicaSets; therefore, once an old ReplicaSet is deleted, you lose the ability to rollback to that revision of Deployment. By default, 10 old ReplicaSets will be kept, however its ideal value depends on the frequency and stability of new Deployments.
+
+More specifically, setting this field to zero means that all old ReplicaSets with 0 replicas will be cleaned up. In this case, a new Deployment rollout cannot be undone, since its revision history is cleaned up.
+
+### Paused
+
+`.spec.paused` is an optional boolean field for pausing and resuming a Deployment. The only difference between a paused Deployment and one that is not paused, is that any changes into the PodTemplateSpec of the paused Deployment will not trigger new rollouts as long as it is paused. A Deployment is not paused by default when it is created.
+
+## What's next
+
+- Learn more about [Pods](https://kubernetes.io/docs/concepts/workloads/pods/).
+- [Run a stateless application using a Deployment](https://kubernetes.io/docs/tasks/run-application/run-stateless-application-deployment/).
+- Read the [Deployment](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/) to understand the Deployment API.
+- Read about [PodDisruptionBudget](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
+- Use kubectl to [create a Deployment](https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-app/deploy-intro/).
+  
+
+Last modified March 15, 2026 at 3:21 PM PST: [fix: replace deprecated argument \`--cpu-percent\` with \`--cpu\` (af93a0a732)](https://github.com/kubernetes/website/commit/af93a0a732cf3057895c62e615a212a44aa6cec7)

data/k8s_docs/k8s_network_policies.md

@@ -0,0 +1,416 @@
+If you want to control traffic flow at the IP address or port level (OSI layer 3 or 4), NetworkPolicies allow you to specify rules for traffic flow within your cluster, and also between Pods and the outside world. Your cluster must use a network plugin that supports NetworkPolicy enforcement.
+
+If you want to control traffic flow at the IP address or port level for TCP, UDP, and SCTP protocols, then you might consider using Kubernetes NetworkPolicies for particular applications in your cluster. NetworkPolicies are an application-centric construct which allow you to specify how a [pod](https://kubernetes.io/docs/concepts/workloads/pods/ "A Pod represents a set of running containers in your cluster.") is allowed to communicate with various network "entities" (we use the word "entity" here to avoid overloading the more common terms such as "endpoints" and "services", which have specific Kubernetes connotations) over the network. NetworkPolicies apply to a connection with a pod on one or both ends, and are not relevant to other connections.
+
+The entities that a Pod can communicate with are identified through a combination of the following three identifiers:
+
+1. Other pods that are allowed (exception: a pod cannot block access to itself)
+2. Namespaces that are allowed
+3. IP blocks (exception: traffic to and from the node where a Pod is running is always allowed, regardless of the IP address of the Pod or the node)
+
+When defining a pod- or namespace-based NetworkPolicy, you use a [selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ "Allows users to filter a list of resources based on labels.") to specify what traffic is allowed to and from the Pod(s) that match the selector.
+
+Meanwhile, when IP-based NetworkPolicies are created, we define policies based on IP blocks (CIDR ranges).
+
+## Prerequisites
+
+Network policies are implemented by the [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/). To use network policies, you must be using a networking solution which supports NetworkPolicy. Creating a NetworkPolicy resource without a controller that implements it will have no effect.
+
+## The two sorts of pod isolation
+
+There are two sorts of isolation for a pod: isolation for egress, and isolation for ingress. They concern what connections may be established. "Isolation" here is not absolute, rather it means "some restrictions apply". The alternative, "non-isolated for $direction", means that no restrictions apply in the stated direction. The two sorts of isolation (or not) are declared independently, and are both relevant for a connection from one pod to another.
+
+By default, a pod is non-isolated for egress; all outbound connections are allowed. A pod is isolated for egress if there is any NetworkPolicy that both selects the pod and has "Egress" in its `policyTypes`; we say that such a policy applies to the pod for egress. When a pod is isolated for egress, the only allowed connections from the pod are those allowed by the `egress` list of some NetworkPolicy that applies to the pod for egress. Reply traffic for those allowed connections will also be implicitly allowed. The effects of those `egress` lists combine additively.
+
+By default, a pod is non-isolated for ingress; all inbound connections are allowed. A pod is isolated for ingress if there is any NetworkPolicy that both selects the pod and has "Ingress" in its `policyTypes`; we say that such a policy applies to the pod for ingress. When a pod is isolated for ingress, the only allowed connections into the pod are those from the pod's node and those allowed by the `ingress` list of some NetworkPolicy that applies to the pod for ingress. Reply traffic for those allowed connections will also be implicitly allowed. The effects of those `ingress` lists combine additively.
+
+Network policies do not conflict; they are additive. If any policy or policies apply to a given pod for a given direction, the connections allowed in that direction from that pod is the union of what the applicable policies allow. Thus, order of evaluation does not affect the policy result.
+
+For a connection from a source pod to a destination pod to be allowed, both the egress policy on the source pod and the ingress policy on the destination pod need to allow the connection. If either side does not allow the connection, it will not happen.
+
+## The NetworkPolicy resource
+
+See the [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#networkpolicy-v1-networking-k8s-io) reference for a full definition of the resource.
+
+An example NetworkPolicy might look like this:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: test-network-policy
+  namespace: default
+spec:
+  podSelector:
+    matchLabels:
+      role: db
+  policyTypes:
+  - Ingress
+  - Egress
+  ingress:
+  - from:
+    - ipBlock:
+        cidr: 172.17.0.0/16
+        except:
+        - 172.17.1.0/24
+    - namespaceSelector:
+        matchLabels:
+          project: myproject
+    - podSelector:
+        matchLabels:
+          role: frontend
+    ports:
+    - protocol: TCP
+      port: 6379
+  egress:
+  - to:
+    - ipBlock:
+        cidr: 10.0.0.0/24
+    ports:
+    - protocol: TCP
+      port: 5978
+```
+
+> [!info] Note:
+> POSTing this to the API server for your cluster will have no effect unless your chosen networking solution supports network policy.
+
+**Mandatory Fields**: As with all other Kubernetes config, a NetworkPolicy needs `apiVersion`, `kind`, and `metadata` fields. For general information about working with config files, see [Configure a Pod to Use a ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/), and [Object Management](https://kubernetes.io/docs/concepts/overview/working-with-objects/object-management/).
+
+**spec**: NetworkPolicy [spec](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) has all the information needed to define a particular network policy in the given namespace.
+
+**podSelector**: Each NetworkPolicy includes a `podSelector` which selects the grouping of pods to which the policy applies. The example policy selects pods with the label "role=db". An empty `podSelector` selects all pods in the namespace.
+
+**policyTypes**: Each NetworkPolicy includes a `policyTypes` list which may include either `Ingress`, `Egress`, or both. The `policyTypes` field indicates whether or not the given policy applies to ingress traffic to selected pod, egress traffic from selected pods, or both. If no `policyTypes` are specified on a NetworkPolicy then by default `Ingress` will always be set and `Egress` will be set if the NetworkPolicy has any egress rules.
+
+**ingress**: Each NetworkPolicy may include a list of allowed `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. The example policy contains a single rule, which matches traffic on a single port, from one of three sources, the first specified via an `ipBlock`, the second via a `namespaceSelector` and the third via a `podSelector`.
+
+**egress**: Each NetworkPolicy may include a list of allowed `egress` rules. Each rule allows traffic which matches both the `to` and `ports` sections. The example policy contains a single rule, which matches traffic on a single port to any destination in `10.0.0.0/24`.
+
+So, the example NetworkPolicy:
+
+1. isolates `role=db` pods in the `default` namespace for both ingress and egress traffic (if they weren't already isolated)
+2. (Ingress rules) allows connections to all pods in the `default` namespace with the label `role=db` on TCP port 6379 from:
+	- any pod in the `default` namespace with the label `role=frontend`
+		- any pod in a namespace with the label `project=myproject`
+		- IP addresses in the ranges `172.17.0.0` – `172.17.0.255` and `172.17.2.0` – `172.17.255.255` (ie, all of `172.17.0.0/16` except `172.17.1.0/24`)
+3. (Egress rules) allows connections from any pod in the `default` namespace with the label `role=db` to CIDR `10.0.0.0/24` on TCP port 5978
+
+See the [Declare Network Policy](https://kubernetes.io/docs/tasks/administer-cluster/declare-network-policy/) walkthrough for further examples.
+
+## Behavior of to and from selectors
+
+There are four kinds of selectors that can be specified in an `ingress` `from` section or `egress` `to` section:
+
+**podSelector**: This selects particular Pods in the same namespace as the NetworkPolicy which should be allowed as ingress sources or egress destinations.
+
+**namespaceSelector**: This selects particular namespaces for which all Pods should be allowed as ingress sources or egress destinations.
+
+**namespaceSelector** *and* **podSelector**: A single `to` / `from` entry that specifies both `namespaceSelector` and `podSelector` selects particular Pods within particular namespaces. Be careful to use correct YAML syntax. For example:
+
+```yaml
+...
+ingress:
+- from:
+  - namespaceSelector:
+      matchLabels:
+        user: alice
+    podSelector:
+      matchLabels:
+        role: client
+...
+```
+
+This policy contains a single `from` element allowing connections from Pods with the label `role=client` in namespaces with the label `user=alice`. But the following policy is different:
+
+```yaml
+...
+ingress:
+- from:
+  - namespaceSelector:
+      matchLabels:
+        user: alice
+  - podSelector:
+      matchLabels:
+        role: client
+...
+```
+
+It contains two elements in the `from` array, and allows connections from Pods in the local Namespace with the label `role=client`, *or* from any Pod in any namespace with the label `user=alice`.
+
+When in doubt, use `kubectl describe` to see how Kubernetes has interpreted the policy.
+
+**ipBlock**: This selects particular IP CIDR ranges to allow as ingress sources or egress destinations. These should be cluster-external IPs, since Pod IPs are ephemeral and unpredictable.
+
+Cluster ingress and egress mechanisms often require rewriting the source or destination IP of packets. In cases where this happens, it is not defined whether this happens before or after NetworkPolicy processing, and the behavior may be different for different combinations of network plugin, cloud provider, `Service` implementation, etc.
+
+In the case of ingress, this means that in some cases you may be able to filter incoming packets based on the actual original source IP, while in other cases, the "source IP" that the NetworkPolicy acts on may be the IP of a `LoadBalancer` or of the Pod's node, etc.
+
+For egress, this means that connections from pods to `Service` IPs that get rewritten to cluster-external IPs may or may not be subject to `ipBlock` -based policies.
+
+## Default policies
+
+By default, if no policies exist in a namespace, then all ingress and egress traffic is allowed to and from pods in that namespace. The following examples let you change the default behavior in that namespace.
+
+### Default deny all ingress traffic
+
+You can create a "default" ingress isolation policy for a namespace by creating a NetworkPolicy that selects all pods but does not allow any ingress traffic to those pods.
+
+```yaml
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny-ingress
+spec:
+  podSelector: {}
+  policyTypes:
+  - Ingress
+```
+
+This ensures that even pods that aren't selected by any other NetworkPolicy will still be isolated for ingress. This policy does not affect isolation for egress from any pod.
+
+### Allow all ingress traffic
+
+If you want to allow all incoming connections to all pods in a namespace, you can create a policy that explicitly allows that.
+
+```yaml
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-all-ingress
+spec:
+  podSelector: {}
+  ingress:
+  - {}
+  policyTypes:
+  - Ingress
+```
+
+With this policy in place, no additional policy or policies can cause any incoming connection to those pods to be denied. This policy has no effect on isolation for egress from any pod.
+
+### Default deny all egress traffic
+
+You can create a "default" egress isolation policy for a namespace by creating a NetworkPolicy that selects all pods but does not allow any egress traffic from those pods.
+
+```yaml
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny-egress
+spec:
+  podSelector: {}
+  policyTypes:
+  - Egress
+```
+
+This ensures that even pods that aren't selected by any other NetworkPolicy will not be allowed egress traffic. This policy does not change the ingress isolation behavior of any pod.
+
+> [!caution] Caution:
+> A default deny-all egress policy also blocks DNS traffic. If your workloads need DNS resolution, you must add a separate NetworkPolicy that allows egress to your cluster's DNS service.
+
+### Allow all egress traffic
+
+If you want to allow all connections from all pods in a namespace, you can create a policy that explicitly allows all outgoing connections from pods in that namespace.
+
+```yaml
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-all-egress
+spec:
+  podSelector: {}
+  egress:
+  - {}
+  policyTypes:
+  - Egress
+```
+
+With this policy in place, no additional policy or policies can cause any outgoing connection from those pods to be denied. This policy has no effect on isolation for ingress to any pod.
+
+### Default deny all ingress and all egress traffic
+
+You can create a "default" policy for a namespace which prevents all ingress AND egress traffic by creating the following NetworkPolicy in that namespace.
+
+```yaml
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny-all
+spec:
+  podSelector: {}
+  policyTypes:
+  - Ingress
+  - Egress
+```
+
+This ensures that even pods that aren't selected by any other NetworkPolicy will not be allowed ingress or egress traffic.
+
+## Network traffic filtering
+
+NetworkPolicy is defined for [layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_layer) connections (TCP, UDP, and optionally SCTP). For all the other protocols, the behaviour may vary across network plugins.
+
+> [!info] Note:
+> You must be using a [CNI](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/ "Container network interface (CNI) plugins are a type of Network plugin that adheres to the appc/CNI specification.") plugin that supports SCTP protocol NetworkPolicies.
+
+When a `deny all` network policy is defined, it is only guaranteed to deny TCP, UDP and SCTP connections. For other protocols, such as ARP or ICMP, the behaviour is undefined. The same applies to allow rules: when a specific pod is allowed as ingress source or egress destination, it is undefined what happens with (for example) ICMP packets. Protocols such as ICMP may be allowed by some network plugins and denied by others.
+
+## Targeting a range of ports
+
+FEATURE STATE: `Kubernetes v1.25 [stable]`
+
+When writing a NetworkPolicy, you can target a range of ports instead of a single port.
+
+This is achievable with the usage of the `endPort` field, as the following example:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: multi-port-egress
+  namespace: default
+spec:
+  podSelector:
+    matchLabels:
+      role: db
+  policyTypes:
+    - Egress
+  egress:
+    - to:
+        - ipBlock:
+            cidr: 10.0.0.0/24
+      ports:
+        - protocol: TCP
+          port: 32000
+          endPort: 32768
+```
+
+The above rule allows any Pod with label `role=db` on the namespace `default` to communicate with any IP within the range `10.0.0.0/24` over TCP, provided that the target port is between the range 32000 and 32768.
+
+The following restrictions apply when using this field:
+
+- The `endPort` field must be equal to or greater than the `port` field.
+- `endPort` can only be defined if `port` is also defined.
+- Both ports must be numeric.
+
+> [!info] Note:
+> Your cluster must be using a [CNI](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/ "Container network interface (CNI) plugins are a type of Network plugin that adheres to the appc/CNI specification.") plugin that supports the `endPort` field in NetworkPolicy specifications. If your [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) does not support the `endPort` field and you specify a NetworkPolicy with that, the policy will be applied only for the single `port` field.
+
+## Targeting multiple namespaces by label
+
+In this scenario, your `Egress` NetworkPolicy targets more than one namespace using their label names. For this to work, you need to label the target namespaces. For example:
+
+```shell
+kubectl label namespace frontend namespace=frontend
+kubectl label namespace backend namespace=backend
+```
+
+Add the labels under `namespaceSelector` in your NetworkPolicy document. For example:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: egress-namespaces
+spec:
+  podSelector:
+    matchLabels:
+      app: myapp
+  policyTypes:
+  - Egress
+  egress:
+  - to:
+    - namespaceSelector:
+        matchExpressions:
+        - key: namespace
+          operator: In
+          values: ["frontend", "backend"]
+```
+
+> [!info] Note:
+> It is not possible to directly specify the name of the namespaces in a NetworkPolicy. You must use a `namespaceSelector` with `matchLabels` or `matchExpressions` to select the namespaces based on their labels.
+
+## Targeting a Namespace by its name
+
+The Kubernetes control plane sets an immutable label `kubernetes.io/metadata.name` on all namespaces, the value of the label is the namespace name.
+
+While NetworkPolicy cannot target a namespace by its name with some object field, you can use the standardized label to target a specific namespace.
+
+## Pod lifecycle
+
+> [!info] Note:
+> The following applies to clusters with a conformant networking plugin and a conformant implementation of NetworkPolicy.
+
+When a new NetworkPolicy object is created, it may take some time for a network plugin to handle the new object. If a pod that is affected by a NetworkPolicy is created before the network plugin has completed NetworkPolicy handling, that pod may be started unprotected, and isolation rules will be applied when the NetworkPolicy handling is completed.
+
+Once the NetworkPolicy is handled by a network plugin,
+
+1. All newly created pods affected by a given NetworkPolicy will be isolated before they are started. Implementations of NetworkPolicy must ensure that filtering is effective throughout the Pod lifecycle, even from the very first instant that any container in that Pod is started. Because they are applied at Pod level, NetworkPolicies apply equally to init containers, sidecar containers, and regular containers.
+2. Allow rules will be applied eventually after the isolation rules (or may be applied at the same time). In the worst case, a newly created pod may have no network connectivity at all when it is first started, if isolation rules were already applied, but no allow rules were applied yet.
+
+Every created NetworkPolicy will be handled by a network plugin eventually, but there is no way to tell from the Kubernetes API when exactly that happens.
+
+Therefore, pods must be resilient against being started up with different network connectivity than expected. If you need to make sure the pod can reach certain destinations before being started, you can use an [init container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) to wait for those destinations to be reachable before kubelet starts the app containers.
+
+Every NetworkPolicy will be applied to all selected pods eventually. Because the network plugin may implement NetworkPolicy in a distributed manner, it is possible that pods may see a slightly inconsistent view of network policies when the pod is first created, or when pods or policies change. For example, a newly-created pod that is supposed to be able to reach both Pod A on Node 1 and Pod B on Node 2 may find that it can reach Pod A immediately, but cannot reach Pod B until a few seconds later.
+
+## NetworkPolicy and hostNetwork pods
+
+NetworkPolicy behaviour for `hostNetwork` pods is undefined, but it should be limited to 2 possibilities:
+
+- The network plugin can distinguish `hostNetwork` pod traffic from all other traffic (including being able to distinguish traffic from different `hostNetwork` pods on the same node), and will apply NetworkPolicy to `hostNetwork` pods just like it does to pod-network pods.
+- The network plugin cannot properly distinguish `hostNetwork` pod traffic, and so it ignores `hostNetwork` pods when matching `podSelector` and `namespaceSelector`. Traffic to/from `hostNetwork` pods is treated the same as all other traffic to/from the node IP. (This is the most common implementation.)
+
+This applies when
+
+1. a `hostNetwork` pod is selected by `spec.podSelector`.
+	```yaml
+	...
+	spec:
+	  podSelector:
+	    matchLabels:
+	      role: client
+	...
+	```
+2. a `hostNetwork` pod is selected by a `podSelector` or `namespaceSelector` in an `ingress` or `egress` rule.
+	```yaml
+	...
+	ingress:
+	  - from:
+	    - podSelector:
+	        matchLabels:
+	          role: client
+	...
+	```
+
+At the same time, since `hostNetwork` pods have the same IP addresses as the nodes they reside on, their connections will be treated as node connections. For example, you can allow traffic from a `hostNetwork` Pod using an `ipBlock` rule.
+
+## What you can't do with network policies (at least, not yet)
+
+As of Kubernetes 1.35, the following functionality does not exist in the NetworkPolicy API, but you might be able to implement workarounds using Operating System components (such as SELinux, OpenVSwitch, IPTables, and so on) or Layer 7 technologies (Ingress controllers, Service Mesh implementations) or admission controllers. In case you are new to network security in Kubernetes, its worth noting that the following User Stories cannot (yet) be implemented using the NetworkPolicy API.
+
+- Forcing internal cluster traffic to go through a common gateway (this might be best served with a service mesh or other proxy).
+- Anything TLS related (use a service mesh or ingress controller for this).
+- Node specific policies (you can use CIDR notation for these, but you cannot target nodes by their Kubernetes identities specifically).
+- Targeting of services by name (you can, however, target pods or namespaces by their [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels "Tags objects with identifying attributes that are meaningful and relevant to users."), which is often a viable workaround).
+- Creation or management of "Policy requests" that are fulfilled by a third party.
+- Default policies which are applied to all namespaces or pods (there are some third party Kubernetes distributions and projects which can do this).
+- Advanced policy querying and reachability tooling.
+- The ability to log network security events (for example connections that are blocked or accepted).
+- The ability to explicitly deny policies (currently the model for NetworkPolicies are deny by default, with only the ability to add allow rules).
+- The ability to prevent loopback or incoming host traffic (Pods cannot currently block localhost access, nor do they have the ability to block access from their resident node).
+
+## NetworkPolicy's impact on existing connections
+
+When the set of NetworkPolicies that applies to an existing connection changes - this could happen either due to a change in NetworkPolicies or if the relevant labels of the namespaces/pods selected by the policy (both subject and peers) are changed in the middle of an existing connection - it is implementation defined as to whether the change will take effect for that existing connection or not. Example: A policy is created that leads to denying a previously allowed connection, the underlying network plugin implementation is responsible for defining if that new policy will close the existing connections or not. It is recommended not to modify policies/pods/namespaces in ways that might affect existing connections.
+
+## What's next
+
+- See the [Declare Network Policy](https://kubernetes.io/docs/tasks/administer-cluster/declare-network-policy/) walkthrough for further examples.
+- See more [recipes](https://github.com/ahmetb/kubernetes-network-policy-recipes) for common scenarios enabled by the NetworkPolicy resource.
+  
+
+Last modified March 28, 2026 at 12:37 PM PST: [docs: add caution about DNS being blocked by deny-all egress (0a474b2b1a)](https://github.com/kubernetes/website/commit/0a474b2b1a8d5ac94d09fd5f4ee109a61e6ff511)

data/k8s_docs/k8s_node_pressure_eviction.md

@@ -0,0 +1,339 @@
+Node-pressure eviction is the process by which the [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet "An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.") proactively terminates pods to reclaim [resource](https://kubernetes.io/docs/reference/glossary/?all=true#term-infrastructure-resource "A defined amount of infrastructure available for consumption (CPU, memory, etc).") on nodes.  
+
+The [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet "An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.") monitors resources like memory, disk space, and filesystem inodes on your cluster's nodes. When one or more of these resources reach specific consumption levels, the kubelet can proactively fail one or more pods on the node to reclaim resources and prevent starvation.
+
+During a node-pressure eviction, the kubelet sets the [phase](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase) for the selected pods to `Failed`, and terminates the Pod.
+
+Node-pressure eviction is not the same as [API-initiated eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/).
+
+The kubelet does not respect your configured [PodDisruptionBudget](https://kubernetes.io/docs/reference/glossary/?all=true#term-pod-disruption-budget "An object that limits the number of Pods of a replicated application that are down simultaneously from voluntary disruptions.") or the pod's `terminationGracePeriodSeconds`. If you use [soft eviction thresholds](#soft-eviction-thresholds), the kubelet respects your configured `eviction-max-pod-grace-period`. If you use [hard eviction thresholds](#hard-eviction-thresholds), the kubelet uses a `0s` grace period (immediate shutdown) for termination.
+
+## Self healing behavior
+
+The kubelet attempts to [reclaim node-level resources](#reclaim-node-resources) before it terminates end-user pods. For example, it removes unused container images when disk resources are starved.
+
+If the pods are managed by a [workload](https://kubernetes.io/docs/concepts/workloads/ "A workload is an application running on Kubernetes.") management object (such as [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ "A StatefulSet manages deployment and scaling of a set of Pods, with durable storage and persistent identifiers for each Pod.") or [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.")) that replaces failed pods, the control plane (`kube-controller-manager`) creates new pods in place of the evicted pods.
+
+### Self healing for static pods
+
+If you are running a [static pod](https://kubernetes.io/docs/concepts/workloads/pods/#static-pods) on a node that is under resource pressure, the kubelet may evict that static Pod. The kubelet then tries to create a replacement, because static Pods always represent an intent to run a Pod on that node.
+
+The kubelet takes the *priority* of the static pod into account when creating a replacement. If the static pod manifest specifies a low priority, and there are higher-priority Pods defined within the cluster's control plane, and the node is under resource pressure, the kubelet may not be able to make room for that static pod. The kubelet continues to attempt to run all static pods even when there is resource pressure on a node.
+
+## Eviction signals and thresholds
+
+The kubelet uses various parameters to make eviction decisions, like the following:
+
+- Eviction signals
+- Eviction thresholds
+- Monitoring intervals
+
+### Eviction signals
+
+Eviction signals are the current state of a particular resource at a specific point in time. The kubelet uses eviction signals to make eviction decisions by comparing the signals to eviction thresholds, which are the minimum amount of the resource that should be available on the node.
+
+The kubelet uses the following eviction signals:
+
+| Eviction Signal | Description | Linux Only |
+| --- | --- | --- |
+| `memory.available` | `memory.available`:= `node.status.capacity[memory]` - `node.stats.memory.workingSet` |  |
+| `nodefs.available` | `nodefs.available`:= `node.stats.fs.available` |  |
+| `nodefs.inodesFree` | `nodefs.inodesFree`:= `node.stats.fs.inodesFree` | • |
+| `imagefs.available` | `imagefs.available`:= `node.stats.runtime.imagefs.available` |  |
+| `imagefs.inodesFree` | `imagefs.inodesFree`:= `node.stats.runtime.imagefs.inodesFree` | • |
+| `containerfs.available` | `containerfs.available`:= `node.stats.runtime.containerfs.available` |  |
+| `containerfs.inodesFree` | `containerfs.inodesFree`:= `node.stats.runtime.containerfs.inodesFree` | • |
+| `pid.available` | `pid.available`:= `node.stats.rlimit.maxpid` - `node.stats.rlimit.curproc` | • |
+
+In this table, the **Description** column shows how kubelet gets the value of the signal. Each signal supports either a percentage or a literal value. The kubelet calculates the percentage value relative to the total capacity associated with the signal.
+
+#### Memory signals
+
+On Linux nodes, 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](https://kubernetes.io/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](https://kubernetes.io/examples/admin/resource/memory-available.sh) or [cgroupv2 script](https://kubernetes.io/examples/admin/resource/memory-available-cgroupv2.sh) reproduces the same set of steps that the kubelet performs to calculate `memory.available`. The kubelet excludes inactive\_file (the number of bytes of file-backed memory on the inactive LRU list) from its calculation, as it assumes that memory is reclaimable under pressure.
+
+On Windows nodes, the value for `memory.available` is derived from the node's global memory commit levels (queried through the [`GetPerformanceInfo()`](https://learn.microsoft.com/windows/win32/api/psapi/nf-psapi-getperformanceinfo) system call) by subtracting the node's global [`CommitTotal`](https://learn.microsoft.com/windows/win32/api/psapi/ns-psapi-performance_information) from the node's [`CommitLimit`](https://learn.microsoft.com/windows/win32/api/psapi/ns-psapi-performance_information). Please note that `CommitLimit` can change if the node's page-file size changes!
+
+#### Filesystem signals
+
+The kubelet recognizes three specific filesystem identifiers that can be used with eviction signals (`<identifier>.inodesFree` or `<identifier>.available`):
+
+1. `nodefs`: The node's main filesystem, used for local disk volumes, emptyDir volumes not backed by memory, log storage, ephemeral storage, and more. For example, `nodefs` contains `/var/lib/kubelet`.
+2. `imagefs`: An optional filesystem that container runtimes can use to store container images (which are the read-only layers) and container writable layers.
+3. `containerfs`: An optional filesystem that container runtime can use to store the writeable layers. Similar to the main filesystem (see `nodefs`), it's used to store local disk volumes, emptyDir volumes not backed by memory, log storage, and ephemeral storage, except for the container images. When `containerfs` is used, the `imagefs` filesystem can be split to only store images (read-only layers) and nothing else.
+
+> [!info] Note:
+> FEATURE STATE: `Kubernetes v1.31 [beta]` (enabled by default)
+> 
+> The *split image filesystem* feature, which enables support for the `containerfs` filesystem, adds several new eviction signals, thresholds and metrics. To use `containerfs`, the Kubernetes release v1.35 requires the `KubeletSeparateDiskGC` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) to be enabled. Currently, only CRI-O (v1.29 or higher) offers the `containerfs` filesystem support.
+
+As such, kubelet generally allows three options for container filesystems:
+
+- Everything is on the single `nodefs`, also referred to as "rootfs" or simply "root", and there is no dedicated image filesystem.
+- Container storage (see `nodefs`) is on a dedicated disk, and `imagefs` (writable and read-only layers) is separate from the root filesystem. This is often referred to as "split disk" (or "separate disk") filesystem.
+- Container filesystem `containerfs` (same as `nodefs` plus writable layers) is on root and the container images (read-only layers) are stored on separate `imagefs`. This is often referred to as "split image" filesystem.
+
+The kubelet will attempt to auto-discover these filesystems with their current configuration directly from the underlying container runtime and will ignore other local node filesystems.
+
+The kubelet does not support other container filesystems or storage configurations, and it does not currently support multiple filesystems for images and containers.
+
+### Deprecated kubelet garbage collection features
+
+Some kubelet garbage collection features are deprecated in favor of eviction:
+
+| Existing Flag | Rationale |
+| --- | --- |
+| `--maximum-dead-containers` | deprecated once old logs are stored outside of container's context |
+| `--maximum-dead-containers-per-container` | deprecated once old logs are stored outside of container's context |
+| `--minimum-container-ttl-duration` | deprecated once old logs are stored outside of container's context |
+
+### Eviction thresholds
+
+You can specify custom eviction thresholds for the kubelet to use when it makes eviction decisions. You can configure [soft](#soft-eviction-thresholds) and [hard](#hard-eviction-thresholds) eviction thresholds.
+
+Eviction thresholds have the form `[eviction-signal][operator][quantity]`, where:
+
+- `eviction-signal` is the [eviction signal](#eviction-signals) to use.
+- `operator` is the [relational operator](https://en.wikipedia.org/wiki/Relational_operator#Standard_relational_operators) you want, such as `<` (less than).
+- `quantity` is the eviction threshold amount, such as `1Gi`. The value of `quantity` must match the quantity representation used by Kubernetes. You can use either literal values or percentages (`%`).
+
+For example, if a node has 10GiB of total memory and you want trigger eviction if the available memory falls below 1GiB, you can define the eviction threshold as either `memory.available<10%` or `memory.available<1Gi` (you cannot use both).
+
+#### Soft eviction thresholds
+
+A soft eviction threshold pairs an eviction threshold with a required administrator-specified grace period. The kubelet does not evict pods until the grace period is exceeded. The kubelet returns an error on startup if you do not specify a grace period.
+
+You can specify both a soft eviction threshold grace period and a maximum allowed pod termination grace period for kubelet to use during evictions. If you specify a maximum allowed grace period and the soft eviction threshold is met, the kubelet uses the lesser of the two grace periods. If you do not specify a maximum allowed grace period, the kubelet kills evicted pods immediately without graceful termination.
+
+You can use the following flags to configure soft eviction thresholds:
+
+- `eviction-soft`: A set of eviction thresholds like `memory.available<1.5Gi` that can trigger pod eviction if held over the specified grace period.
+- `eviction-soft-grace-period`: A set of eviction grace periods like `memory.available=1m30s` that define how long a soft eviction threshold must hold before triggering a Pod eviction.
+- `eviction-max-pod-grace-period`: The maximum allowed grace period (in seconds) to use when terminating pods in response to a soft eviction threshold being met.
+
+#### Hard eviction thresholds
+
+A hard eviction threshold has no grace period. When a hard eviction threshold is met, the kubelet kills pods immediately without graceful termination to reclaim the starved resource.
+
+You can use the `eviction-hard` flag to configure a set of hard eviction thresholds like `memory.available<1Gi`.
+
+The kubelet has the following default hard eviction thresholds:
+
+- `memory.available<100Mi` (Linux nodes)
+- `memory.available<500Mi` (Windows nodes)
+- `nodefs.available<10%`
+- `imagefs.available<15%`
+- `nodefs.inodesFree<5%` (Linux nodes)
+- `imagefs.inodesFree<5%` (Linux nodes)
+
+These default values of hard eviction thresholds will only be set if none of the parameters is changed. If you change the value of any parameter, then the values of other parameters will not be inherited as the default values and will be set to zero. In order to provide custom values, you should provide all the thresholds respectively. You can also set the kubelet config MergeDefaultEvictionSettings to true in the kubelet configuration file. If set to true and any parameter is changed, then the other parameters will inherit their default values instead of 0.
+
+The `containerfs.available` and `containerfs.inodesFree` (Linux nodes) default eviction thresholds will be set as follows:
+
+- If a single filesystem is used for everything, then `containerfs` thresholds are set the same as `nodefs`.
+- If separate filesystems are configured for both images and containers, then `containerfs` thresholds are set the same as `imagefs`.
+
+Setting custom overrides for thresholds related to `containersfs` is currently not supported, and a warning will be issued if an attempt to do so is made; any provided custom values will, as such, be ignored.
+
+## Eviction monitoring interval
+
+The kubelet evaluates eviction thresholds based on its configured `housekeeping-interval`, which defaults to `10s`.
+
+## Node conditions
+
+The kubelet reports [node conditions](https://kubernetes.io/docs/concepts/architecture/nodes/#condition) to reflect that the node is under pressure because hard or soft eviction threshold is met, independent of configured grace periods.
+
+The kubelet maps eviction signals to node conditions as follows:
+
+| Node Condition | Eviction Signal | Description |
+| --- | --- | --- |
+| `MemoryPressure` | `memory.available` | Available memory on the node has satisfied an eviction threshold |
+| `DiskPressure` | `nodefs.available`, `nodefs.inodesFree`, `imagefs.available`, `imagefs.inodesFree`, `containerfs.available`, or `containerfs.inodesFree` | Available disk space and inodes on either the node's root filesystem, image filesystem, or container filesystem has satisfied an eviction threshold |
+| `PIDPressure` | `pid.available` | Available processes identifiers on the (Linux) node has fallen below an eviction threshold |
+
+The control plane also [maps](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#taint-nodes-by-condition) these node conditions to taints.
+
+The kubelet updates the node conditions based on the configured `--node-status-update-frequency`, which defaults to `10s`.
+
+### Node condition oscillation
+
+In some cases, nodes oscillate above and below soft eviction thresholds without holding for the defined grace periods. This causes the reported node condition to constantly switch between `true` and `false`, leading to bad eviction decisions.
+
+To protect against oscillation, you can use the `eviction-pressure-transition-period` flag, which controls how long the kubelet must wait before transitioning a node condition to a different state. The transition period has a default value of `5m`.
+
+### Reclaiming node level resources
+
+The kubelet tries to reclaim node-level resources before it evicts end-user pods.
+
+When a `DiskPressure` node condition is reported, the kubelet reclaims node-level resources based on the filesystems on the node.
+
+#### Without imagefs or containerfs
+
+If the node only has a `nodefs` filesystem that meets eviction thresholds, the kubelet frees up disk space in the following order:
+
+1. Garbage collect dead pods and containers.
+2. Delete unused images.
+
+#### With imagefs
+
+If the node has a dedicated `imagefs` filesystem for container runtimes to use, the kubelet does the following:
+
+- If the `nodefs` filesystem meets the eviction thresholds, the kubelet garbage collects dead pods and containers.
+- If the `imagefs` filesystem meets the eviction thresholds, the kubelet deletes all unused images.
+
+#### With imagefs and containerfs
+
+If the node has a dedicated `containerfs` alongside the `imagefs` filesystem configured for the container runtimes to use, then kubelet will attempt to reclaim resources as follows:
+
+- If the `containerfs` filesystem meets the eviction thresholds, the kubelet garbage collects dead pods and containers.
+- If the `imagefs` filesystem meets the eviction thresholds, the kubelet deletes all unused images.
+
+### Pod selection for kubelet eviction
+
+If the kubelet's attempts to reclaim node-level resources don't bring the eviction signal below the threshold, the kubelet begins to evict end-user pods.
+
+The kubelet uses the following parameters to determine the pod eviction order:
+
+1. Whether the pod's resource usage exceeds requests
+2. [Pod Priority](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/)
+3. The pod's resource usage relative to requests
+
+As a result, kubelet ranks and evicts pods in the following order:
+
+1. `BestEffort` or `Burstable` pods where the usage exceeds requests. These pods are evicted based on their Priority and then by how much their usage level exceeds the request.
+2. `Guaranteed` pods and `Burstable` pods where the usage is less than requests are evicted last, based on their Priority.
+
+> [!info] Note:
+> The kubelet does not use the pod's [QoS class](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/) to determine the eviction order. You can use the QoS class to estimate the most likely pod eviction order when reclaiming resources like memory. QoS classification does not apply to EphemeralStorage requests, so the above scenario will not apply if the node is, for example, under `DiskPressure`.
+
+`Guaranteed` pods are guaranteed only when requests and limits are specified for all the containers and they are equal. These pods will never be evicted because of another pod's resource consumption. If a system daemon (such as `kubelet` and `journald`) is consuming more resources than were reserved via `system-reserved` or `kube-reserved` allocations, and the node only has `Guaranteed` or `Burstable` pods using less resources than requests left on it, then the kubelet must choose to evict one of these pods to preserve node stability and to limit the impact of resource starvation on other pods. In this case, it will choose to evict pods of lowest Priority first.
+
+If you are running a [static pod](https://kubernetes.io/docs/concepts/workloads/pods/#static-pods) and want to avoid having it evicted under resource pressure, set the `priority` field for that Pod directly. Static pods do not support the `priorityClassName` field.
+
+When the kubelet evicts pods in response to inode or process ID starvation, it uses the Pods' relative priority to determine the eviction order, because inodes and PIDs have no requests.
+
+The kubelet sorts pods differently based on whether the node has a dedicated `imagefs` or `containerfs` filesystem:
+
+#### Without imagefs or containerfs (nodefs and imagefs use the same filesystem)
+
+- If `nodefs` triggers evictions, the kubelet sorts pods based on their total disk usage (`local volumes + logs and a writable layer of all containers`).
+
+#### With imagefs (nodefs and imagefs filesystems are separate)
+
+- If `nodefs` triggers evictions, the kubelet sorts pods based on `nodefs` usage (`local volumes + logs of all containers`).
+- If `imagefs` triggers evictions, the kubelet sorts pods based on the writable layer usage of all containers.
+
+#### With imagesfs and containerfs (imagefs and containerfs have been split)
+
+- If `containerfs` triggers evictions, the kubelet sorts pods based on `containerfs` usage (`local volumes + logs and a writable layer of all containers`).
+- If `imagefs` triggers evictions, the kubelet sorts pods based on the `storage of images` rank, which represents the disk usage of a given image.
+
+### Minimum eviction reclaim
+
+> [!info] Note:
+> As of Kubernetes v1.35, you cannot set a custom value for the `containerfs.available` metric. The configuration for this specific metric will be set automatically to reflect values set for either the `nodefs` or `imagefs`, depending on the configuration.
+
+In some cases, pod eviction only reclaims a small amount of the starved resource. This can lead to the kubelet repeatedly hitting the configured eviction thresholds and triggering multiple evictions.
+
+You can use the `--eviction-minimum-reclaim` flag or a [kubelet config file](https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/) to configure a minimum reclaim amount for each resource. When the kubelet notices that a resource is starved, it continues to reclaim that resource until it reclaims the quantity you specify.
+
+For example, the following configuration sets minimum reclaim amounts:
+
+```yaml
+apiVersion: kubelet.config.k8s.io/v1beta1
+kind: KubeletConfiguration
+evictionHard:
+  memory.available: "500Mi"
+  nodefs.available: "1Gi"
+  imagefs.available: "100Gi"
+evictionMinimumReclaim:
+  memory.available: "0Mi"
+  nodefs.available: "500Mi"
+  imagefs.available: "2Gi"
+```
+
+In this example, if the `nodefs.available` signal meets the eviction threshold, the kubelet reclaims the resource until the signal reaches the threshold of 1GiB, and then continues to reclaim the minimum amount of 500MiB, until the available nodefs storage value reaches 1.5GiB.
+
+Similarly, the kubelet tries to reclaim the `imagefs` resource until the `imagefs.available` value reaches `102Gi`, representing 102 GiB of available container image storage. If the amount of storage that the kubelet could reclaim is less than 2GiB, the kubelet doesn't reclaim anything.
+
+The default `eviction-minimum-reclaim` is `0` for all resources.
+
+## Node out of memory behavior
+
+If the node experiences an *out of memory* (OOM) event prior to the kubelet being able to reclaim memory, the node depends on the [oom\_killer](https://lwn.net/Articles/391222/) to respond.
+
+The kubelet sets an `oom_score_adj` value for each container based on the QoS for the pod.
+
+| Quality of Service | `oom_score_adj` |
+| --- | --- |
+| `Guaranteed` | \-997 |
+| `BestEffort` | 1000 |
+| `Burstable` | *min(max(2, 1000 - (1000 × memoryRequestBytes) / machineMemoryCapacityBytes), 999)* |
+
+> [!info] Note:
+> The kubelet also sets an `oom_score_adj` value of `-997` for any containers in Pods that have `system-node-critical` [Priority](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#pod-priority "Pod Priority indicates the importance of a Pod relative to other Pods.").
+
+If the kubelet can't reclaim memory before a node experiences OOM, the `oom_killer` calculates an `oom_score` based on the percentage of memory it's using on the node, and then adds the `oom_score_adj` to get an effective `oom_score` for each container. It then kills the container with the highest score.
+
+This means that containers in low QoS pods that consume a large amount of memory relative to their scheduling requests are killed first.
+
+Unlike pod eviction, if a container is OOM killed, the kubelet can restart it based on its `restartPolicy`.
+
+## Good practices
+
+The following sections describe good practice for eviction configuration.
+
+### Schedulable resources and eviction policies
+
+When you configure the kubelet with an eviction policy, you should make sure that the scheduler will not schedule pods if they will trigger eviction because they immediately induce memory pressure.
+
+Consider the following scenario:
+
+- Node memory capacity: 10GiB
+- Operator wants to reserve 10% of memory capacity for system daemons (kernel, `kubelet`, etc.)
+- Operator wants to evict Pods at 95% memory utilization to reduce incidence of system OOM.
+
+For this to work, the kubelet is launched as follows:
+
+```none
+--eviction-hard=memory.available<500Mi
+--system-reserved=memory=1.5Gi
+```
+
+In this configuration, the `--system-reserved` flag reserves 1.5GiB of memory for the system, which is `10% of the total memory + the eviction threshold amount`.
+
+The node can reach the eviction threshold if a pod is using more than its request, or if the system is using more than 1GiB of memory, which makes the `memory.available` signal fall below 500MiB and triggers the threshold.
+
+### DaemonSets and node-pressure eviction
+
+Pod priority is a major factor in making eviction decisions. If you do not want the kubelet to evict pods that belong to a DaemonSet, give those pods a high enough priority by specifying a suitable `priorityClassName` in the pod spec. You can also use a lower priority, or the default, to only allow pods from that DaemonSet to run when there are enough resources.
+
+## Known issues
+
+The following sections describe known issues related to out of resource handling.
+
+### kubelet may not observe memory pressure right away
+
+By default, the kubelet polls cAdvisor to collect memory usage stats at a regular interval. If memory usage increases within that window rapidly, the kubelet may not observe `MemoryPressure` fast enough, and the OOM killer will still be invoked.
+
+You can use the `--kernel-memcg-notification` flag to enable the `memcg` notification API on the kubelet to get notified immediately when a threshold is crossed.
+
+If you are not trying to achieve extreme utilization, but a sensible measure of overcommit, a viable workaround for this issue is to use the `--kube-reserved` and `--system-reserved` flags to allocate memory for the system.
+
+### active\_file memory is not considered as available memory
+
+On Linux, the kernel tracks the number of bytes of file-backed memory on active least recently used (LRU) list as the `active_file` statistic. The kubelet treats `active_file` memory areas as not reclaimable. For workloads that make intensive use of block-backed local storage, including ephemeral local storage, kernel-level caches of file and block data means that many recently accessed cache pages are likely to be counted as `active_file`. If enough of these kernel block buffers are on the active LRU list, the kubelet is liable to observe this as high resource use and taint the node as experiencing memory pressure - triggering pod eviction.
+
+For more details, see [https://github.com/kubernetes/kubernetes/issues/43916](https://github.com/kubernetes/kubernetes/issues/43916)
+
+You can work around that behavior by setting the memory limit and memory request the same for containers likely to perform intensive I/O activity. You will need to estimate or measure an optimal memory limit value for that container.
+
+## What's next
+
+- Learn about [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/)
+- Learn about [Pod Priority and Preemption](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/)
+- Learn about [PodDisruptionBudgets](https://kubernetes.io/docs/tasks/run-application/configure-pdb/)
+- Learn about [Quality of Service](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/) (QoS)
+- Check out the [Eviction API](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#create-eviction-pod-v1-core)
+  
+
+Last modified September 19, 2025 at 9:38 PM PST: [fix: typos (a5d40c68e0)](https://github.com/kubernetes/website/commit/a5d40c68e0dda7c44cff5c6331747b502eede79a)

data/k8s_docs/k8s_pod_security_admission.md

@@ -0,0 +1,93 @@
+An overview of the Pod Security Admission Controller, which can enforce the Pod Security Standards.
+
+FEATURE STATE: `Kubernetes v1.25 [stable]`
+
+The Kubernetes [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) define different isolation levels for Pods. These standards let you define how you want to restrict the behavior of pods in a clear, consistent fashion.
+
+Kubernetes offers a built-in *Pod Security* [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/ "A piece of code that intercepts requests to the Kubernetes API server prior to persistence of the object.") to enforce the Pod Security Standards. Pod security restrictions are applied at the [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces "An abstraction used by Kubernetes to support isolation of groups of resources within a single cluster.") level when pods are created.
+
+### Built-in Pod Security admission enforcement
+
+This page is part of the documentation for Kubernetes v1.35. If you are running a different version of Kubernetes, consult the documentation for that release.
+
+## Pod Security levels
+
+Pod Security admission places requirements on a Pod's [Security Context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) and other related fields according to the three levels defined by the [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/): `privileged`, `baseline`, and `restricted`. Refer to the [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) page for an in-depth look at those requirements.
+
+## Pod Security Admission labels for namespaces
+
+Once the feature is enabled or the webhook is installed, you can configure namespaces to define the admission control mode you want to use for pod security in each namespace. Kubernetes defines a set of [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels "Tags objects with identifying attributes that are meaningful and relevant to users.") that you can set to define which of the predefined Pod Security Standard levels you want to use for a namespace. The label you select defines what action the [control plane](https://kubernetes.io/docs/reference/glossary/?all=true#term-control-plane "The container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers.") takes if a potential violation is detected:
+
+| Mode | Description |
+| --- | --- |
+| **enforce** | Policy violations will cause the pod to be rejected. |
+| **audit** | Policy violations will trigger the addition of an audit annotation to the event recorded in the [audit log](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/), but are otherwise allowed. |
+| **warn** | Policy violations will trigger a user-facing warning, but are otherwise allowed. |
+
+A namespace can configure any or all modes, or even set a different level for different modes.
+
+For each mode, there are two labels that determine the policy used:
+
+```yaml
+# The per-mode level label indicates which policy level to apply for the mode.
+#
+# MODE must be one of \`enforce\`, \`audit\`, or \`warn\`.
+# LEVEL must be one of \`privileged\`, \`baseline\`, or \`restricted\`.
+pod-security.kubernetes.io/<MODE>: <LEVEL>
+
+# Optional: per-mode version label that can be used to pin the policy to the
+# version that shipped with a given Kubernetes minor version (for example v1.35).
+#
+# MODE must be one of \`enforce\`, \`audit\`, or \`warn\`.
+# VERSION must be a valid Kubernetes minor version, or \`latest\`.
+pod-security.kubernetes.io/<MODE>-version: <VERSION>
+```
+
+Check out [Enforce Pod Security Standards with Namespace Labels](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/) to see example usage.
+
+## Workload resources and Pod templates
+
+Pods are often created indirectly, by creating a [workload object](https://kubernetes.io/docs/concepts/workloads/controllers/) such as a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.") or [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/ "A finite or batch task that runs to completion."). The workload object defines a *Pod template* and a [controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.") for the workload resource creates Pods based on that template. To help catch violations early, both the audit and warning modes are applied to the workload resources. However, enforce mode is **not** applied to workload resources, only to the resulting pod objects.
+
+## Exemptions
+
+You can define *exemptions* from pod security enforcement in order to allow the creation of pods that would have otherwise been prohibited due to the policy associated with a given namespace. Exemptions can be statically configured in the [Admission Controller configuration](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-admission-controller/#configure-the-admission-controller).
+
+Exemptions must be explicitly enumerated. Requests meeting exemption criteria are *ignored* by the Admission Controller (all `enforce`, `audit` and `warn` behaviors are skipped). Exemption dimensions include:
+
+- **Usernames:** requests from users with an exempt authenticated (or impersonated) username are ignored.
+- **RuntimeClassNames:** pods and [workload resources](#workload-resources-and-pod-templates) specifying an exempt runtime class name are ignored.
+- **Namespaces:** pods and [workload resources](#workload-resources-and-pod-templates) in an exempt namespace are ignored.
+
+> [!caution] Caution:
+> Most pods are created by a controller in response to a [workload resource](#workload-resources-and-pod-templates), meaning that exempting an end user will only exempt them from enforcement when creating pods directly, but not when creating a workload resource. Controller service accounts (such as `system:serviceaccount:kube-system:replicaset-controller`) should generally not be exempted, as doing so would implicitly exempt any user that can create the corresponding workload resource.
+
+Updates to the following pod fields are exempt from policy checks, meaning that if a pod update request only changes these fields, it will not be denied even if the pod is in violation of the current policy level:
+
+- Any metadata updates **except** changes to the seccomp or AppArmor annotations:
+	- `seccomp.security.alpha.kubernetes.io/pod` (deprecated)
+		- `container.seccomp.security.alpha.kubernetes.io/*` (deprecated)
+		- `container.apparmor.security.beta.kubernetes.io/*` (deprecated)
+- Valid updates to `.spec.activeDeadlineSeconds`
+- Valid updates to `.spec.tolerations`
+
+## Metrics
+
+Here are the Prometheus metrics exposed by kube-apiserver:
+
+- `pod_security_errors_total`: This metric indicates the number of errors preventing normal evaluation. Non-fatal errors may result in the latest restricted profile being used for enforcement.
+- `pod_security_evaluations_total`: This metric indicates the number of policy evaluations that have occurred, not counting ignored or exempt requests during exporting.
+- `pod_security_exemptions_total`: This metric indicates the number of exempt requests, not counting ignored or out of scope requests.
+
+## What's next
+
+- [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/)
+- [Enforcing Pod Security Standards](https://kubernetes.io/docs/setup/best-practices/enforcing-pod-security-standards/)
+- [Enforce Pod Security Standards by Configuring the Built-in Admission Controller](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-admission-controller/)
+- [Enforce Pod Security Standards with Namespace Labels](https://kubernetes.io/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/)
+
+If you are running an older version of Kubernetes and want to upgrade to a version of Kubernetes that does not include PodSecurityPolicies, read [migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/).
+
+  
+
+Last modified March 07, 2024 at 4:54 PM PST: [AppArmor v1.30 docs update (4f11f83a45)](https://github.com/kubernetes/website/commit/4f11f83a451b55d2e79ccd0472058b9f59e562ed)

data/k8s_docs/k8s_pods.md

@@ -0,0 +1,305 @@
+*Pods* are the smallest deployable units of computing that you can create and manage in Kubernetes.
+
+A *Pod* (as in a pod of whales or pea pod) is a group of one or more [containers](https://kubernetes.io/docs/concepts/containers/ "A lightweight and portable executable image that contains software and all of its dependencies."), with shared storage and network resources, and a specification for how to run the containers. A Pod's contents are always co-located and co-scheduled, and run in a shared context. A Pod models an application-specific "logical host": it contains one or more application containers which are relatively tightly coupled. In non-cloud contexts, applications executed on the same physical or virtual machine are analogous to cloud applications executed on the same logical host.
+
+As well as application containers, a Pod can contain [init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ "One or more initialization containers that must run to completion before any app containers run.") that run during Pod startup. You can also inject [ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/ "A type of container type that you can temporarily run inside a Pod") for debugging a running Pod.
+
+## What is a Pod?
+
+> [!info] Note:
+> You need to install a [container runtime](https://kubernetes.io/docs/setup/production-environment/container-runtimes/) into each node in the cluster so that Pods can run there.
+
+The shared context of a Pod is a set of Linux namespaces, cgroups, and potentially other facets of isolation - the same things that isolate a [container](https://kubernetes.io/docs/concepts/containers/ "A lightweight and portable executable image that contains software and all of its dependencies."). Within a Pod's context, the individual applications may have further sub-isolations applied.
+
+A Pod is similar to a set of containers with shared namespaces and shared filesystem volumes.
+
+Pods in a Kubernetes cluster are used in two main ways:
+
+- **Pods that run a single container**. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container; Kubernetes manages Pods rather than managing the containers directly.
+- **Pods that run multiple containers that need to work together**. A Pod can encapsulate an application composed of [multiple co-located containers](#how-pods-manage-multiple-containers) that are tightly coupled and need to share resources. These co-located containers form a single cohesive unit.
+	Grouping multiple co-located and co-managed containers in a single Pod is a relatively advanced use case. You should use this pattern only in specific instances in which your containers are tightly coupled.
+	You don't need to run multiple containers to provide replication (for resilience or capacity); if you need multiple replicas, see [Workload management](https://kubernetes.io/docs/concepts/workloads/controllers/).
+
+## Using Pods
+
+The following is an example of a Pod which consists of a container running the image `nginx:1.14.2`.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+spec:
+  containers:
+  - name: nginx
+    image: nginx:1.14.2
+    ports:
+    - containerPort: 80
+```
+
+To create the Pod shown above, run the following command:
+
+```shell
+kubectl apply -f https://k8s.io/examples/pods/simple-pod.yaml
+```
+
+Pods are generally not created directly and are created using workload resources. See [Working with Pods](#working-with-pods) for more information on how Pods are used with workload resources.
+
+### Workload resources for managing pods
+
+Usually you don't need to create Pods directly, even singleton Pods. Instead, create them using workload resources such as [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.") or [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/ "A finite or batch task that runs to completion."). If your Pods need to track state, consider the [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ "A StatefulSet manages deployment and scaling of a set of Pods, with durable storage and persistent identifiers for each Pod.") resource.
+
+Each Pod is meant to run a single instance of a given application. If you want to scale your application horizontally (to provide more overall resources by running more instances), you should use multiple Pods, one for each instance. In Kubernetes, this is typically referred to as *replication*. Replicated Pods are usually created and managed as a group by a workload resource and its [controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.").
+
+See [Pods and controllers](#pods-and-controllers) for more information on how Kubernetes uses workload resources, and their controllers, to implement application scaling and auto-healing.
+
+Pods natively provide two kinds of shared resources for their constituent containers: [networking](#pod-networking) and [storage](#pod-storage).
+
+## Working with Pods
+
+You'll rarely create individual Pods directly in Kubernetes—even singleton Pods. This is because Pods are designed as relatively ephemeral, disposable entities. When a Pod gets created (directly by you, or indirectly by a [controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.")), the new Pod is scheduled to run on a [Node](https://kubernetes.io/docs/concepts/architecture/nodes/ "A node is a worker machine in Kubernetes.") in your cluster. The Pod remains on that node until the Pod finishes execution, the Pod object is deleted, the Pod is *evicted* for lack of resources, or the node fails.
+
+> [!info] Note:
+> Restarting a container in a Pod should not be confused with restarting a Pod. A Pod is not a process, but an environment for running container(s). A Pod persists until it is deleted.
+
+The name of a Pod must be a valid [DNS subdomain](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) value, but this can produce unexpected results for the Pod hostname. For best compatibility, the name should follow the more restrictive rules for a [DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names).
+
+### Pod OS
+
+FEATURE STATE: `Kubernetes v1.25 [stable]`
+
+You should set the `.spec.os.name` field to either `windows` or `linux` to indicate the OS on which you want the pod to run. These two are the only operating systems supported for now by Kubernetes. In the future, this list may be expanded.
+
+In Kubernetes v1.35, the value of `.spec.os.name` does not affect how the [kube-scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/ "Control plane component that watches for newly created pods with no assigned node, and selects a node for them to run on.") picks a node for the Pod to run on. In any cluster where there is more than one operating system for running nodes, you should set the [kubernetes.io/os](https://kubernetes.io/docs/reference/labels-annotations-taints/#kubernetes-io-os) label correctly on each node, and define pods with a `nodeSelector` based on the operating system label. The kube-scheduler assigns your pod to a node based on other criteria and may or may not succeed in picking a suitable node placement where the node OS is right for the containers in that Pod. The [Pod security standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) also use this field to avoid enforcing policies that aren't relevant to the operating system.
+
+### Pods and controllers
+
+You can use workload resources to create and manage multiple Pods for you. A controller for the resource handles replication and rollout and automatic healing in case of Pod failure. For example, if a Node fails, a controller notices that Pods on that Node have stopped working and creates a replacement Pod. The scheduler places the replacement Pod onto a healthy Node.
+
+Here are some examples of workload resources that manage one or more Pods:
+
+- [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.")
+- [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ "A StatefulSet manages deployment and scaling of a set of Pods, with durable storage and persistent identifiers for each Pod.")
+- [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset "Ensures a copy of a Pod is running across a set of nodes in a cluster.")
+
+### Specifying a Workload reference
+
+FEATURE STATE: `Kubernetes v1.35 [alpha]` (disabled by default)
+
+By default, Kubernetes schedules every Pod individually. However, some tightly-coupled applications need a group of Pods to be scheduled simultaneously to function correctly.
+
+You can link a Pod to a [Workload](https://kubernetes.io/docs/concepts/workloads/workload-api/) object using a [Workload reference](https://kubernetes.io/docs/concepts/workloads/pods/workload-reference/). This tells the `kube-scheduler` that the Pod is part of a specific group, enabling it to make coordinated placement decisions for the entire group at once.
+
+### Pod templates
+
+Controllers for [workload](https://kubernetes.io/docs/concepts/workloads/ "A workload is an application running on Kubernetes.") resources create Pods from a *pod template* and manage those Pods on your behalf.
+
+PodTemplates are specifications for creating Pods, and are included in workload resources such as [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/), and [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/).
+
+Each controller for a workload resource uses the `PodTemplate` inside the workload object to make actual Pods. The `PodTemplate` is part of the desired state of whatever workload resource you used to run your app.
+
+When you create a Pod, you can include [environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) in the Pod template for the containers that run in the Pod.
+
+The sample below is a manifest for a simple Job with a `template` that starts one container. The container in that Pod prints a message then pauses.
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: hello
+spec:
+  template:
+    # This is the pod template
+    spec:
+      containers:
+      - name: hello
+        image: busybox:1.28
+        command: ['sh', '-c', 'echo "Hello, Kubernetes!" && sleep 3600']
+      restartPolicy: OnFailure
+    # The pod template ends here
+```
+
+Modifying the pod template or switching to a new pod template has no direct effect on the Pods that already exist. If you change the pod template for a workload resource, that resource needs to create replacement Pods that use the updated template.
+
+For example, the StatefulSet controller ensures that the running Pods match the current pod template for each StatefulSet object. If you edit the StatefulSet to change its pod template, the StatefulSet starts to create new Pods based on the updated template. Eventually, all of the old Pods are replaced with new Pods, and the update is complete.
+
+Each workload resource implements its own rules for handling changes to the Pod template. If you want to read more about StatefulSet specifically, read [Update strategy](https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#updating-statefulsets) in the StatefulSet Basics tutorial.
+
+On Nodes, the [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet "An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.") does not directly observe or manage any of the details around pod templates and updates; those details are abstracted away. That abstraction and separation of concerns simplifies system semantics, and makes it feasible to extend the cluster's behavior without changing existing code.
+
+## Pod update and replacement
+
+As mentioned in the previous section, when the Pod template for a workload resource is changed, the controller creates new Pods based on the updated template instead of updating or patching the existing Pods.
+
+Kubernetes doesn't prevent you from managing Pods directly. It is possible to update some fields of a running Pod, in place. However, Pod update operations like [`patch`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#patch-pod-v1-core), and [`replace`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#replace-pod-v1-core) have some limitations:
+
+- Most of the metadata about a Pod is immutable. For example, you cannot change the `namespace`, `name`, `uid`, or `creationTimestamp` fields.
+- If the `metadata.deletionTimestamp` is set, no new entry can be added to the `metadata.finalizers` list.
+- Pod updates may not change fields other than `spec.containers[*].image`, `spec.initContainers[*].image`, `spec.activeDeadlineSeconds`, `spec.terminationGracePeriodSeconds`, `spec.tolerations` or `spec.schedulingGates`. For `spec.tolerations`, you can only add new entries.
+- When updating the `spec.activeDeadlineSeconds` field, two types of updates are allowed:
+	1. setting the unassigned field to a positive number;
+		2. updating the field from a positive number to a smaller, non-negative number.
+
+### Pod subresources
+
+The above update rules apply to regular pod updates, but other pod fields can be updated through *subresources*.
+
+- **Resize:** The `resize` subresource allows container resources (`spec.containers[*].resources`) to be updated. See [Resize Container Resources](https://kubernetes.io/docs/tasks/configure-pod-container/resize-container-resources/) for more details.
+- **Ephemeral Containers:** The `ephemeralContainers` subresource allows [ephemeral containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/ "A type of container type that you can temporarily run inside a Pod") to be added to a Pod. See [Ephemeral Containers](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/) for more details.
+- **Status:** The `status` subresource allows the pod status to be updated. This is typically only used by the Kubelet and other system controllers.
+- **Binding:** The `binding` subresource allows setting the pod's `spec.nodeName` via a `Binding` request. This is typically only used by the [scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/ "Control plane component that watches for newly created pods with no assigned node, and selects a node for them to run on.").
+
+### Pod generation
+
+- The `metadata.generation` field is unique. It will be automatically set by the system such that new pods have a `metadata.generation` of 1, and every update to mutable fields in the pod's spec will increment the `metadata.generation` by 1.
+
+FEATURE STATE: `Kubernetes v1.35 [stable]` (enabled by default)
+
+- `observedGeneration` is a field that is captured in the `status` section of the Pod object. The Kubelet will set `status.observedGeneration` to track the pod state to the current pod status. The pod's `status.observedGeneration` will reflect the `metadata.generation` of the pod at the point that the pod status is being reported.
+
+> [!info] Note:
+> The `status.observedGeneration` field is managed by the kubelet and external controllers should **not** modify this field.
+
+Different status fields may either be associated with the `metadata.generation` of the current sync loop, or with the `metadata.generation` of the previous sync loop. The key distinction is whether a change in the `spec` is reflected directly in the `status` or is an indirect result of a running process.
+
+#### Direct Status Updates
+
+For status fields where the allocated spec is directly reflected, the `observedGeneration` will be associated with the current `metadata.generation` (Generation N).
+
+This behavior applies to:
+
+- **Resize Status**: The status of a resource resize operation.
+- **Allocated Resources**: The resources allocated to the Pod after a resize.
+- **Ephemeral Containers**: When a new ephemeral container is added, and it is in `Waiting` state.
+
+#### Indirect Status Updates
+
+For status fields that are an indirect result of running the spec, the `observedGeneration` will be associated with the `metadata.generation` of the previous sync loop (Generation N-1).
+
+This behavior applies to:
+
+- **Container Image**: The `ContainerStatus.ImageID` reflects the image from the previous generation until the new image is pulled and the container is updated.
+- **Actual Resources**: During an in-progress resize, the actual resources in use still belong to the previous generation's request.
+- **Container state**: During an in-progress resize, with require restart policy reflects the previous generation's request.
+- **activeDeadlineSeconds** & **terminationGracePeriodSeconds** & **deletionTimestamp**: The effects of these fields on the Pod's status are a result of the previously observed specification.
+
+## Resource sharing and communication
+
+Pods enable data sharing and communication among their constituent containers.
+
+### Storage in Pods
+
+A Pod can specify a set of shared storage [volumes](https://kubernetes.io/docs/concepts/storage/volumes/ "A directory containing data, accessible to the containers in a pod."). All containers in the Pod can access the shared volumes, allowing those containers to share data. Volumes also allow persistent data in a Pod to survive in case one of the containers within needs to be restarted. See [Storage](https://kubernetes.io/docs/concepts/storage/) for more information on how Kubernetes implements shared storage and makes it available to Pods.
+
+### Pod networking
+
+Each Pod is assigned a unique IP address for each address family. Every container in a Pod shares the network namespace, including the IP address and network ports. Inside a Pod (and **only** then), the containers that belong to the Pod can communicate with one another using `localhost`. When containers in a Pod communicate with entities *outside the Pod*, they must coordinate how they use the shared network resources (such as ports). Within a Pod, containers share an IP address and port space, and can find each other via `localhost`. The containers in a Pod can also communicate with each other using standard inter-process communications like SystemV semaphores or POSIX shared memory. Containers in different Pods have distinct IP addresses and can not communicate by OS-level IPC without special configuration. Containers that want to interact with a container running in a different Pod can use IP networking to communicate.
+
+Containers within the Pod see the system hostname as being the same as the configured `name` for the Pod. There's more about this in the [networking](https://kubernetes.io/docs/concepts/cluster-administration/networking/) section.
+
+## Pod security settings
+
+To set security constraints on Pods and containers, you use the `securityContext` field in the Pod specification. This field gives you granular control over what a Pod or individual containers can do. See [Advanced Pod Configuration](https://kubernetes.io/docs/concepts/workloads/pods/advanced-pod-config/) for more details.
+
+For basic security configuration, you should meet the Baseline Pod security standard and run containers as non-root. You can set simple security contexts:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: security-context-demo
+spec:
+  securityContext:
+    runAsUser: 1000
+    runAsGroup: 3000
+    fsGroup: 2000
+  containers:
+  - name: sec-ctx-demo
+    image: busybox
+    command: ["sh", "-c", "sleep 1h"]
+```
+
+For advanced security context configuration including capabilities, seccomp profiles, and detailed security options, see the [security concepts](https://kubernetes.io/docs/concepts/security/) section.
+
+- To learn about kernel-level security constraints that you can use, see [Linux kernel security constraints for Pods and containers](https://kubernetes.io/docs/concepts/security/linux-kernel-security-constraints/).
+- To learn more about the Pod security context, see [Configure a Security Context for a Pod or Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
+
+## Resource requests and limits
+
+When you specify a Pod, you can optionally specify how much of each resource a container needs. The most common resources to specify are CPU and memory (RAM).
+
+When you specify the resource *request* for containers in a Pod, the kube-scheduler uses this information to decide which node to place the Pod on. When you specify a resource *limit* for a container, the kubelet enforces those limits so that the running container is not allowed to use more of that resource than the limit you set.
+
+CPU limits are enforced by CPU throttling. When a container approaches its CPU limit, the kernel restricts its access to CPU. Memory limits are enforced by the kernel with out-of-memory (OOM) kills when a container exceeds its limit.
+
+> [!info] Note:
+> Setting CPU limits involves a trade-off. CPU limits help prevent noisy neighbor problems where a single workload starves others on the same node. This is especially important in multi-tenant environments. However, CPU limits can cause throttling even when the node has spare CPU capacity, potentially degrading latency-sensitive workload performance. Whether to set CPU limits depends on your environment, workload characteristics, and isolation requirements.
+
+For details on resource units, enforcement behavior, and configuration examples, see [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
+
+## Static Pods
+
+*Static Pods* are managed directly by the kubelet daemon on a specific node, without the [API server](https://kubernetes.io/docs/concepts/architecture/#kube-apiserver "Control plane component that serves the Kubernetes API.") observing them. Whereas most Pods are managed by the control plane (for example, a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.")), for static Pods, the kubelet directly supervises each static Pod (and restarts it if it fails).
+
+Static Pods are always bound to one [Kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet "An agent that runs on each node in the cluster. It makes sure that containers are running in a pod.") on a specific node. The main use for static Pods is to run a self-hosted control plane: in other words, using the kubelet to supervise the individual [control plane components](https://kubernetes.io/docs/concepts/architecture/#control-plane-components).
+
+The kubelet automatically tries to create a [mirror Pod](https://kubernetes.io/docs/reference/glossary/?all=true#term-mirror-pod "An object in the API server that tracks a static pod on a kubelet.") on the Kubernetes API server for each static Pod. This means that the Pods running on a node are visible on the API server, but cannot be controlled from there. See the guide [Create static Pods](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/) for more information.
+
+> [!info] Note:
+> The `spec` of a static Pod cannot refer to other API objects (e.g., [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ "Provides an identity for processes that run in a Pod."), [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/ "An API object used to store non-confidential data in key-value pairs. Can be consumed as environment variables, command-line arguments, or configuration files in a volume."), [Secret](https://kubernetes.io/docs/concepts/configuration/secret/ "Stores sensitive information, such as passwords, OAuth tokens, and ssh keys."), etc).
+
+## Pods with multiple containers
+
+Pods are designed to support multiple cooperating processes (as containers) that form a cohesive unit of service. The containers in a Pod are automatically co-located and co-scheduled on the same physical or virtual machine in the cluster. The containers can share resources and dependencies, communicate with one another, and coordinate when and how they are terminated.
+
+Pods in a Kubernetes cluster are used in two main ways:
+
+- **Pods that run a single container**. The "one-container-per-Pod" model is the most common Kubernetes use case; in this case, you can think of a Pod as a wrapper around a single container; Kubernetes manages Pods rather than managing the containers directly.
+- **Pods that run multiple containers that need to work together**. A Pod can encapsulate an application composed of multiple co-located containers that are tightly coupled and need to share resources. These co-located containers form a single cohesive unit of service—for example, one container serving data stored in a shared volume to the public, while a separate [sidecar container](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/ "An auxilliary container that stays running throughout the lifecycle of a Pod.") refreshes or updates those files. The Pod wraps these containers, storage resources, and an ephemeral network identity together as a single unit.
+
+For example, you might have a container that acts as a web server for files in a shared volume, and a separate [sidecar container](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) that updates those files from a remote source, as in the following diagram:
+
+![Pod creation diagram](https://kubernetes.io/images/docs/pod.svg)
+
+Pod creation diagram
+
+Some Pods have [init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ "One or more initialization containers that must run to completion before any app containers run.") as well as [app containers](https://kubernetes.io/docs/reference/glossary/?all=true#term-app-container "A container used to run part of a workload. Compare with init container."). By default, init containers run and complete before the app containers are started.
+
+You can also have [sidecar containers](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) that provide auxiliary services to the main application Pod (for example: a service mesh).
+
+FEATURE STATE: `Kubernetes v1.33 [stable]` (enabled by default)
+
+Enabled by default, the `SidecarContainers` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) allows you to specify `restartPolicy: Always` for init containers. Setting the `Always` restart policy ensures that the containers where you set it are treated as *sidecars* that are kept running during the entire lifetime of the Pod. Containers that you explicitly define as sidecar containers start up before the main application Pod and remain running until the Pod is shut down.
+
+## Container probes
+
+A *probe* is a diagnostic performed periodically by the kubelet on a container. To perform a diagnostic, the kubelet can invoke different actions:
+
+- `ExecAction` (performed with the help of the container runtime)
+- `TCPSocketAction` (checked directly by the kubelet)
+- `HTTPGetAction` (checked directly by the kubelet)
+
+You can read more about [probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes) in the Pod Lifecycle documentation.
+
+## What's next
+
+- Learn about the [lifecycle of a Pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/).
+- Read about [PodDisruptionBudget](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
+- Pod is a top-level resource in the Kubernetes REST API. The [Pod](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/) object definition describes the object in detail.
+- [The Distributed System Toolkit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/) explains common layouts for Pods with more than one container.
+- Read about [Pod topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/)
+- Read [Advanced Pod Configuration](https://kubernetes.io/docs/concepts/workloads/pods/advanced-pod-config/) to learn the topic in detail. That page covers aspects of Pod configuration beyond the essentials, including:
+	- PriorityClasses
+		- RuntimeClasses
+		- advanced ways to configure *scheduling*: the way that Kubernetes decides which node a Pod should run on.
+
+To understand the context for why Kubernetes wraps a common Pod API in other resources (such as [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ "A StatefulSet manages deployment and scaling of a set of Pods, with durable storage and persistent identifiers for each Pod.") or [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ "Manages a replicated application on your cluster.")), you can read about the prior art, including:
+
+- [Aurora](https://aurora.apache.org/documentation/latest/reference/configuration/#job-schema)
+- [Borg](https://research.google/pubs/large-scale-cluster-management-at-google-with-borg/)
+- [Marathon](https://github.com/d2iq-archive/marathon)
+- [Omega](https://research.google/pubs/pub41684/)
+- [Tupperware](https://engineering.fb.com/data-center-engineering/tupperware/).
+  
+
+Last modified February 28, 2026 at 10:29 PM PST: [add resource requests and limits trade-off (79b3410c32)](https://github.com/kubernetes/website/commit/79b3410c328e4225eb7a9384ca2a6cb0a3b7c5ce)

data/k8s_docs/k8s_replicaset.md

@@ -0,0 +1,399 @@
+A ReplicaSet's purpose is to maintain a stable set of replica Pods running at any given time. Usually, you define a Deployment and let that Deployment manage ReplicaSets automatically.
+
+A ReplicaSet's purpose is to maintain a stable set of replica Pods running at any given time. As such, it is often used to guarantee the availability of a specified number of identical Pods.
+
+## How a ReplicaSet works
+
+A ReplicaSet is defined with fields, including a selector that specifies how to identify Pods it can acquire, a number of replicas indicating how many Pods it should be maintaining, and a pod template specifying the data of new Pods it should create to meet the number of replicas criteria. A ReplicaSet then fulfills its purpose by creating and deleting Pods as needed to reach the desired number. When a ReplicaSet needs to create new Pods, it uses its Pod template.
+
+A ReplicaSet is linked to its Pods via the Pods' [metadata.ownerReferences](https://kubernetes.io/docs/concepts/architecture/garbage-collection/#owners-dependents) field, which specifies what resource the current object is owned by. All Pods acquired by a ReplicaSet have their owning ReplicaSet's identifying information within their ownerReferences field. It's through this link that the ReplicaSet knows of the state of the Pods it is maintaining and plans accordingly.
+
+A ReplicaSet identifies new Pods to acquire by using its selector. If there is a Pod that has no OwnerReference or the OwnerReference is not a [Controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.") and it matches a ReplicaSet's selector, it will be immediately acquired by said ReplicaSet.
+
+## When to use a ReplicaSet
+
+A ReplicaSet ensures that a specified number of pod replicas are running at any given time. However, a Deployment is a higher-level concept that manages ReplicaSets and provides declarative updates to Pods along with a lot of other useful features. Therefore, we recommend using Deployments instead of directly using ReplicaSets, unless you require custom update orchestration or don't require updates at all.
+
+This actually means that you may never need to manipulate ReplicaSet objects: use a Deployment instead, and define your application in the spec section.
+
+## Example
+
+```yaml
+apiVersion: apps/v1
+kind: ReplicaSet
+metadata:
+  name: frontend
+  labels:
+    app: guestbook
+    tier: frontend
+spec:
+  # modify replicas according to your case
+  replicas: 3
+  selector:
+    matchLabels:
+      tier: frontend
+  template:
+    metadata:
+      labels:
+        tier: frontend
+    spec:
+      containers:
+      - name: php-redis
+        image: us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
+```
+
+Saving this manifest into `frontend.yaml` and submitting it to a Kubernetes cluster will create the defined ReplicaSet and the Pods that it manages.
+
+```shell
+kubectl apply -f https://kubernetes.io/examples/controllers/frontend.yaml
+```
+
+You can then get the current ReplicaSets deployed:
+
+```shell
+kubectl get rs
+```
+
+And see the frontend one you created:
+
+```
+NAME       DESIRED   CURRENT   READY   AGE
+frontend   3         3         3       6s
+```
+
+You can also check on the state of the ReplicaSet:
+
+```shell
+kubectl describe rs/frontend
+```
+
+And you will see output similar to:
+
+```
+Name:         frontend
+Namespace:    default
+Selector:     tier=frontend
+Labels:       app=guestbook
+              tier=frontend
+Annotations:  <none>
+Replicas:     3 current / 3 desired
+Pods Status:  3 Running / 0 Waiting / 0 Succeeded / 0 Failed
+Pod Template:
+  Labels:  tier=frontend
+  Containers:
+   php-redis:
+    Image:        us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
+    Port:         <none>
+    Host Port:    <none>
+    Environment:  <none>
+    Mounts:       <none>
+  Volumes:        <none>
+Events:
+  Type    Reason            Age   From                   Message
+  ----    ------            ----  ----                   -------
+  Normal  SuccessfulCreate  13s   replicaset-controller  Created pod: frontend-gbgfx
+  Normal  SuccessfulCreate  13s   replicaset-controller  Created pod: frontend-rwz57
+  Normal  SuccessfulCreate  13s   replicaset-controller  Created pod: frontend-wkl7w
+```
+
+And lastly you can check for the Pods brought up:
+
+```shell
+kubectl get pods
+```
+
+You should see Pod information similar to:
+
+```
+NAME             READY   STATUS    RESTARTS   AGE
+frontend-gbgfx   1/1     Running   0          10m
+frontend-rwz57   1/1     Running   0          10m
+frontend-wkl7w   1/1     Running   0          10m
+```
+
+You can also verify that the owner reference of these pods is set to the frontend ReplicaSet. To do this, get the yaml of one of the Pods running:
+
+```shell
+kubectl get pods frontend-gbgfx -o yaml
+```
+
+The output will look similar to this, with the frontend ReplicaSet's info set in the metadata's ownerReferences field:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  creationTimestamp: "2024-02-28T22:30:44Z"
+  generateName: frontend-
+  labels:
+    tier: frontend
+  name: frontend-gbgfx
+  namespace: default
+  ownerReferences:
+  - apiVersion: apps/v1
+    blockOwnerDeletion: true
+    controller: true
+    kind: ReplicaSet
+    name: frontend
+    uid: e129deca-f864-481b-bb16-b27abfd92292
+...
+```
+
+## Non-Template Pod acquisitions
+
+While you can create bare Pods with no problems, it is strongly recommended to make sure that the bare Pods do not have labels which match the selector of one of your ReplicaSets. The reason for this is because a ReplicaSet is not limited to owning Pods specified by its template-- it can acquire other Pods in the manner specified in the previous sections.
+
+Take the previous frontend ReplicaSet example, and the Pods specified in the following manifest:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod1
+  labels:
+    tier: frontend
+spec:
+  containers:
+  - name: hello1
+    image: gcr.io/google-samples/hello-app:2.0
+
+---
+
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod2
+  labels:
+    tier: frontend
+spec:
+  containers:
+  - name: hello2
+    image: gcr.io/google-samples/hello-app:1.0
+```
+
+As those Pods do not have a Controller (or any object) as their owner reference and match the selector of the frontend ReplicaSet, they will immediately be acquired by it.
+
+Suppose you create the Pods after the frontend ReplicaSet has been deployed and has set up its initial Pod replicas to fulfill its replica count requirement:
+
+```shell
+kubectl apply -f https://kubernetes.io/examples/pods/pod-rs.yaml
+```
+
+The new Pods will be acquired by the ReplicaSet, and then immediately terminated as the ReplicaSet would be over its desired count.
+
+Fetching the Pods:
+
+```shell
+kubectl get pods
+```
+
+The output shows that the new Pods are either already terminated, or in the process of being terminated:
+
+```
+NAME             READY   STATUS        RESTARTS   AGE
+frontend-b2zdv   1/1     Running       0          10m
+frontend-vcmts   1/1     Running       0          10m
+frontend-wtsmm   1/1     Running       0          10m
+pod1             0/1     Terminating   0          1s
+pod2             0/1     Terminating   0          1s
+```
+
+If you create the Pods first:
+
+```shell
+kubectl apply -f https://kubernetes.io/examples/pods/pod-rs.yaml
+```
+
+And then create the ReplicaSet however:
+
+```shell
+kubectl apply -f https://kubernetes.io/examples/controllers/frontend.yaml
+```
+
+You shall see that the ReplicaSet has acquired the Pods and has only created new ones according to its spec until the number of its new Pods and the original matches its desired count. As fetching the Pods:
+
+```shell
+kubectl get pods
+```
+
+Will reveal in its output:
+
+```
+NAME             READY   STATUS    RESTARTS   AGE
+frontend-hmmj2   1/1     Running   0          9s
+pod1             1/1     Running   0          36s
+pod2             1/1     Running   0          36s
+```
+
+In this manner, a ReplicaSet can own a non-homogeneous set of Pods
+
+## Writing a ReplicaSet manifest
+
+As with all other Kubernetes API objects, a ReplicaSet needs the `apiVersion`, `kind`, and `metadata` fields. For ReplicaSets, the `kind` is always a ReplicaSet.
+
+When the control plane creates new Pods for a ReplicaSet, the `.metadata.name` of the ReplicaSet is part of the basis for naming those Pods. The name of a ReplicaSet must be a valid [DNS subdomain](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) value, but this can produce unexpected results for the Pod hostnames. For best compatibility, the name should follow the more restrictive rules for a [DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names).
+
+A ReplicaSet also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
+
+### Pod Template
+
+The `.spec.template` is a [pod template](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates) which is also required to have labels in place. In our `frontend.yaml` example we had one label: `tier: frontend`. Be careful not to overlap with the selectors of other controllers, lest they try to adopt this Pod.
+
+For the template's [restart policy](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy) field, `.spec.template.spec.restartPolicy`, the only allowed value is `Always`, which is the default.
+
+### Pod Selector
+
+The `.spec.selector` field is a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). As discussed [earlier](#how-a-replicaset-works) these are the labels used to identify potential Pods to acquire. In our `frontend.yaml` example, the selector was:
+
+```yaml
+matchLabels:
+  tier: frontend
+```
+
+In the ReplicaSet, `.spec.template.metadata.labels` must match `spec.selector`, or it will be rejected by the API.
+
+> [!info] Note:
+> For 2 ReplicaSets specifying the same `.spec.selector` but different `.spec.template.metadata.labels` and `.spec.template.spec` fields, each ReplicaSet ignores the Pods created by the other ReplicaSet.
+
+### Replicas
+
+You can specify how many Pods should run concurrently by setting `.spec.replicas`. The ReplicaSet will create/delete its Pods to match this number.
+
+If you do not specify `.spec.replicas`, then it defaults to 1.
+
+## Working with ReplicaSets
+
+### Deleting a ReplicaSet and its Pods
+
+To delete a ReplicaSet and all of its Pods, use [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete). The [Garbage collector](https://kubernetes.io/docs/concepts/architecture/garbage-collection/) automatically deletes all of the dependent Pods by default.
+
+When using the REST API or the `client-go` library, you must set `propagationPolicy` to `Background` or `Foreground` in the `-d` option. For example:
+
+```shell
+kubectl proxy --port=8080
+curl -X DELETE  'localhost:8080/apis/apps/v1/namespaces/default/replicasets/frontend' \
+  -d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Foreground"}' \
+  -H "Content-Type: application/json"
+```
+
+### Deleting just a ReplicaSet
+
+You can delete a ReplicaSet without affecting any of its Pods using [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete) with the `--cascade=orphan` option. When using the REST API or the `client-go` library, you must set `propagationPolicy` to `Orphan`. For example:
+
+```shell
+kubectl proxy --port=8080
+curl -X DELETE  'localhost:8080/apis/apps/v1/namespaces/default/replicasets/frontend' \
+  -d '{"kind":"DeleteOptions","apiVersion":"v1","propagationPolicy":"Orphan"}' \
+  -H "Content-Type: application/json"
+```
+
+Once the original is deleted, you can create a new ReplicaSet to replace it. As long as the old and new `.spec.selector` are the same, then the new one will adopt the old Pods. However, it will not make any effort to make existing Pods match a new, different pod template. To update Pods to a new spec in a controlled way, use a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#creating-a-deployment), as ReplicaSets do not support a rolling update directly.
+
+### Terminating Pods
+
+FEATURE STATE: `Kubernetes v1.35 [beta]` (enabled by default)
+
+You can enable this feature by setting the `DeploymentReplicaSetTerminatingReplicas` [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) on the [API server](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) and on the [kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
+
+Pods that become terminating due to deletion or scale down may take a long time to terminate, and may consume additional resources during that period. As a result, the total number of all pods can temporarily exceed `.spec.replicas`. Terminating pods can be tracked using the `.status.terminatingReplicas` field of the ReplicaSet.
+
+### Isolating Pods from a ReplicaSet
+
+You can remove Pods from a ReplicaSet by changing their labels. This technique may be used to remove Pods from service for debugging, data recovery, etc. Pods that are removed in this way will be replaced automatically ( assuming that the number of replicas is not also changed).
+
+### Scaling a ReplicaSet
+
+A ReplicaSet can be easily scaled up or down by simply updating the `.spec.replicas` field. The ReplicaSet controller ensures that a desired number of Pods with a matching label selector are available and operational.
+
+When scaling down, the ReplicaSet controller chooses which pods to delete by sorting the available pods to prioritize scaling down pods based on the following general algorithm:
+
+1. Pending (and unschedulable) pods are scaled down first
+2. If `controller.kubernetes.io/pod-deletion-cost` annotation is set, then the pod with the lower value will come first.
+3. Pods on nodes with more replicas come before pods on nodes with fewer replicas.
+4. If the pods' creation times differ, the pod that was created more recently comes before the older pod (the creation times are bucketed on an integer log scale).
+
+If all of the above match, then selection is random.
+
+### Pod deletion cost
+
+FEATURE STATE: `Kubernetes v1.22 [beta]`
+
+Using the [`controller.kubernetes.io/pod-deletion-cost`](https://kubernetes.io/docs/reference/labels-annotations-taints/#pod-deletion-cost) annotation, users can set a preference regarding which pods to remove first when downscaling a ReplicaSet.
+
+The annotation should be set on the pod, the range is \[-2147483648, 2147483647\]. It represents the cost of deleting a pod compared to other pods belonging to the same ReplicaSet. Pods with lower deletion cost are preferred to be deleted before pods with higher deletion cost.
+
+The implicit value for this annotation for pods that don't set it is 0; negative values are permitted. Invalid values will be rejected by the API server.
+
+This feature is beta and enabled by default. You can disable it using the [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) `PodDeletionCost` in both kube-apiserver and kube-controller-manager.
+
+> [!info] Note:
+> - This is honored on a best-effort basis, so it does not offer any guarantees on pod deletion order.
+> - Users should avoid updating the annotation frequently, such as updating it based on a metric value, because doing so will generate a significant number of pod updates on the apiserver.
+
+#### Example Use Case
+
+The different pods of an application could have different utilization levels. On scale down, the application may prefer to remove the pods with lower utilization. To avoid frequently updating the pods, the application should update `controller.kubernetes.io/pod-deletion-cost` once before issuing a scale down (setting the annotation to a value proportional to pod utilization level). This works if the application itself controls the down scaling; for example, the driver pod of a Spark deployment.
+
+### ReplicaSet as a Horizontal Pod Autoscaler Target
+
+A ReplicaSet can also be a target for [Horizontal Pod Autoscalers (HPA)](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). That is, a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting the ReplicaSet we created in the previous example.
+
+```yaml
+apiVersion: autoscaling/v1
+kind: HorizontalPodAutoscaler
+metadata:
+  name: frontend-scaler
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: ReplicaSet
+    name: frontend
+  minReplicas: 3
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 50
+```
+
+Saving this manifest into `hpa-rs.yaml` and submitting it to a Kubernetes cluster should create the defined HPA that autoscales the target ReplicaSet depending on the CPU usage of the replicated Pods.
+
+```shell
+kubectl apply -f https://k8s.io/examples/controllers/hpa-rs.yaml
+```
+
+Alternatively, you can use the `kubectl autoscale` command to accomplish the same (and it's easier!)
+
+```shell
+kubectl autoscale rs frontend --max=10 --min=3 --cpu=50%
+```
+
+## Alternatives to ReplicaSet
+
+### Deployment (recommended)
+
+[`Deployment`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) is an object which can own ReplicaSets and update them and their Pods via declarative, server-side rolling updates. While ReplicaSets can be used independently, today they're mainly used by Deployments as a mechanism to orchestrate Pod creation, deletion and updates. When you use Deployments you don't have to worry about managing the ReplicaSets that they create. Deployments own and manage their ReplicaSets. As such, it is recommended to use Deployments when you want ReplicaSets.
+
+### Bare Pods
+
+Unlike the case where a user directly created Pods, a ReplicaSet replaces Pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicaSet even if your application requires only a single Pod. Think of it similarly to a process supervisor, only it supervises multiple Pods across multiple nodes instead of individual processes on a single node. A ReplicaSet delegates local container restarts to some agent on the node such as Kubelet.
+
+### Job
+
+Use a [`Job`](https://kubernetes.io/docs/concepts/workloads/controllers/job/) instead of a ReplicaSet for Pods that are expected to terminate on their own (that is, batch jobs).
+
+### DaemonSet
+
+Use a [`DaemonSet`](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) instead of a ReplicaSet for Pods that provide a machine-level function, such as machine monitoring or machine logging. These Pods have a lifetime that is tied to a machine lifetime: the Pod needs to be running on the machine before other Pods start, and are safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
+
+### ReplicationController
+
+ReplicaSets are the successors to [ReplicationControllers](https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/). The two serve the same purpose, and behave similarly, except that a ReplicationController does not support set-based selector requirements as described in the [labels user guide](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors). As such, ReplicaSets are preferred over ReplicationControllers
+
+## What's next
+
+- Learn about [Pods](https://kubernetes.io/docs/concepts/workloads/pods/).
+- Learn about [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).
+- [Run a Stateless Application Using a Deployment](https://kubernetes.io/docs/tasks/run-application/run-stateless-application-deployment/), which relies on ReplicaSets to work.
+- `ReplicaSet` is a top-level resource in the Kubernetes REST API. Read the [ReplicaSet](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/replica-set-v1/) object definition to understand the API for replica sets.
+- Read about [PodDisruptionBudget](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/) and how you can use it to manage application availability during disruptions.
+  
+
+Last modified September 26, 2025 at 6:20 PM PST: [Fix HPA CLI example in ReplicaSet doc (55add008ed)](https://github.com/kubernetes/website/commit/55add008edd6efd03de533257d4cf79628f58103)

data/k8s_docs/k8s_secret.md

@@ -0,0 +1,549 @@
+A Secret is an object that contains a small amount of sensitive data such as a password, a token, or a key. Such information might otherwise be put in a [Pod](https://kubernetes.io/docs/concepts/workloads/pods/ "A Pod represents a set of running containers in your cluster.") specification or in a [container image](https://kubernetes.io/docs/reference/glossary/?all=true#term-image "Stored instance of a container that holds a set of software needed to run an application."). Using a Secret means that you don't need to include confidential data in your 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 sensitive data to nonvolatile storage.
+
+Secrets are similar to [ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/ "An API object used to store non-confidential data in key-value pairs. Can be consumed as environment variables, command-line arguments, or configuration files in a volume.") but are specifically intended to hold confidential data.
+
+> [!caution] Caution:
+> Kubernetes Secrets are, by default, stored unencrypted in the API server's underlying data store (etcd). Anyone with API access can retrieve or modify a Secret, and so can anyone with access to etcd. Additionally, anyone who is authorized to create a Pod in a namespace can use that access to read any Secret in that namespace; this includes indirect access such as the ability to create a Deployment.
+> 
+> In order to safely use Secrets, take at least the following steps:
+> 
+> 1. [Enable Encryption at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) for Secrets.
+> 2. [Enable or configure RBAC rules](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) with least-privilege access to Secrets.
+> 3. Restrict Secret access to specific containers.
+> 4. [Consider using external Secret store providers](https://secrets-store-csi-driver.sigs.k8s.io/concepts.html#provider-for-the-secrets-store-csi-driver).
+> 
+> For more guidelines to manage and improve the security of your Secrets, refer to [Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).
+
+See [Information security for Secrets](#information-security-for-secrets) for more details.
+
+## Uses for Secrets
+
+You can use Secrets for purposes such as the following:
+
+- [Set environment variables for a container](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data).
+- [Provide credentials such as SSH keys or passwords to Pods](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#provide-prod-test-creds).
+- [Allow the kubelet to pull container images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
+
+The Kubernetes control plane also uses Secrets; for example, [bootstrap token Secrets](#bootstrap-token-secrets) are a mechanism to help automate node registration.
+
+### 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`, 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`.
+
+> [!info] 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.
+
+```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: registry.k8s.io/busybox
+      command:
+        - ls
+        - "-l"
+        - "/etc/secret-volume"
+      volumeMounts:
+        - name: secret-volume
+          readOnly: true
+          mountPath: "/etc/secret-volume"
+```
+
+### 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.
+
+### 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](https://kubernetes.io/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 manage sensitive data. 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](https://kubernetes.io/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](https://kubernetes.io/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 [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ "A specialized controller used to manage a custom resource") 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.
+
+## Types of Secret
+
+When creating a Secret, you can specify its type using the `type` field of the [Secret](https://kubernetes.io/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 built-in types for some common usage scenarios. These types vary in terms of the validations performed and the constraints Kubernetes imposes on them.
+
+| Built-in Type | Usage |
+| --- | --- |
+| `Opaque` | arbitrary user-defined data |
+| `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 |
+| `kubernetes.io/ssh-auth` | credentials for SSH authentication |
+| `kubernetes.io/tls` | data for a TLS client or server |
+| `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).
+
+Kubernetes doesn't impose any constraints on the type name. However, if you 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 you don't explicitly specify a type in a Secret manifest. When you create a Secret using `kubectl`, you must use the `generic` subcommand to indicate an `Opaque` Secret type. For example, the following command creates an empty Secret of type `Opaque`:
+
+```shell
+kubectl create secret generic empty-secret
+kubectl get secret empty-secret
+```
+
+The output looks like:
+
+```
+NAME           TYPE     DATA   AGE
+empty-secret   Opaque   0      2m6s
+```
+
+The `DATA` column shows the number of data items stored in the Secret. In this case, `0` means you have created an empty Secret.
+
+### ServiceAccount token Secrets
+
+A `kubernetes.io/service-account-token` type of Secret is used to store a token credential that identifies a [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ "Provides an identity for processes that run in a Pod."). This is a legacy mechanism that provides long-lived ServiceAccount credentials to Pods.
+
+In Kubernetes v1.22 and later, the recommended approach is to obtain a short-lived, automatically rotating ServiceAccount token by using the [`TokenRequest`](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/) API instead. You can get these short-lived tokens using the following methods:
+
+- Call the `TokenRequest` API either directly or by using an API client like `kubectl`. For example, you can use the [`kubectl create token`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#-em-token-em-) command.
+- Request a mounted token in a [projected volume](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/#bound-service-account-token-volume) in your Pod manifest. Kubernetes creates the token and mounts it in the Pod. The token is automatically invalidated when the Pod that it's mounted in is deleted. For details, see [Launch a Pod using service account token projection](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#launch-a-pod-using-service-account-token-projection).
+
+> [!info] Note:
+> You should only create a ServiceAccount token Secret if you can't use the `TokenRequest` API to obtain a token, and the security exposure of persisting a non-expiring token credential in a readable API object is acceptable to you. For instructions, see [Manually create a long-lived API token for a ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-an-api-token-for-a-serviceaccount).
+
+When using this Secret type, you need to ensure that the `kubernetes.io/service-account.name` annotation is set to an existing ServiceAccount name. If you are creating both the ServiceAccount and the Secret objects, you should create the ServiceAccount object first.
+
+After the Secret is created, a Kubernetes [controller](https://kubernetes.io/docs/concepts/architecture/controller/ "A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.") fills in some other fields such as the `kubernetes.io/service-account.uid` annotation, and the `token` key in the `data` field, which is populated with an authentication token.
+
+The following example configuration declares a ServiceAccount token Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-sa-sample
+  annotations:
+    kubernetes.io/service-account.name: "sa-name"
+type: kubernetes.io/service-account-token
+data:
+  extra: YmFyCg==
+```
+
+After creating the Secret, wait for Kubernetes to populate the `token` key in the `data` field.
+
+See the [ServiceAccount](https://kubernetes.io/docs/concepts/security/service-accounts/) documentation for more information on how ServiceAccounts work. You can also check the `automountServiceAccountToken` field and the `serviceAccountName` field of the [`Pod`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#pod-v1-core) for information on referencing ServiceAccount credentials from within Pods.
+
+### Docker config Secrets
+
+If you are creating a Secret to store credentials for accessing a container image registry, you must use one of the following `type` values for that Secret:
+
+- `kubernetes.io/dockercfg`: store a serialized `~/.dockercfg` which is the legacy format for configuring Docker command line. The Secret `data` field contains a `.dockercfg` key whose value is the content of a base64 encoded `~/.dockercfg` file.
+- `kubernetes.io/dockerconfigjson`: store a serialized JSON that follows the same format rules as the `~/.docker/config.json` file, which is a new format for `~/.dockercfg`. The Secret `data` field must contain a `.dockerconfigjson` key for which the value is the content of a base64 encoded `~/.docker/config.json` file.
+
+Below is an example for a `kubernetes.io/dockercfg` type of Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-dockercfg
+type: kubernetes.io/dockercfg
+data:
+  .dockercfg: |
+    eyJhdXRocyI6eyJodHRwczovL2V4YW1wbGUvdjEvIjp7ImF1dGgiOiJvcGVuc2VzYW1lIn19fQo=
+```
+
+> [!info] Note:
+> If you do not want to perform the base64 encoding, you can choose to use the `stringData` field instead.
+
+When you create Docker config Secrets using a manifest, the API 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.
+
+You can also use `kubectl` to create a Secret for accessing a container registry, such as when you don't have a Docker configuration file:
+
+```shell
+kubectl create secret docker-registry secret-tiger-docker \
+  --docker-email=tiger@acme.example \
+  --docker-username=tiger \
+  --docker-password=pass1234 \
+  --docker-server=my-registry.example:5000
+```
+
+This command creates a Secret of type `kubernetes.io/dockerconfigjson`.
+
+Retrieve the `.data.dockerconfigjson` field from that new Secret and decode the data:
+
+```shell
+kubectl get secret secret-tiger-docker -o jsonpath='{.data.*}' | base64 -d
+```
+
+The output is equivalent to the following JSON document (which is also a valid Docker configuration file):
+
+```json
+{
+  "auths": {
+    "my-registry.example:5000": {
+      "username": "tiger",
+      "password": "pass1234",
+      "email": "tiger@acme.example",
+      "auth": "dGlnZXI6cGFzczEyMzQ="
+    }
+  }
+}
+```
+
+> [!caution] Caution:
+> 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.
+> 
+> It is suggested to use [credential providers](https://kubernetes.io/docs/tasks/administer-cluster/kubelet-credential-provider/) to dynamically and securely provide pull secrets on-demand.
+
+### 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
+
+Both values for the above two keys are base64 encoded strings. You can alternatively provide the clear text content using the `stringData` field in the Secret manifest.
+
+The following manifest is an example of a basic authentication Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-basic-auth
+type: kubernetes.io/basic-auth
+stringData:
+  username: admin # required field for kubernetes.io/basic-auth
+  password: t0p-Secret # required field for kubernetes.io/basic-auth
+```
+
+> [!info] Note:
+> The `stringData` field for a Secret does not work well with server-side apply.
+
+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.
+
+### SSH authentication Secrets
+
+The builtin type `kubernetes.io/ssh-auth` is provided for storing data used in 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 manifest is an example of a Secret used for SSH public/private key authentication:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-ssh-auth
+type: kubernetes.io/ssh-auth
+data:
+  # the data is abbreviated in this example
+  ssh-privatekey: |
+    UG91cmluZzYlRW1vdGljb24lU2N1YmE=
+```
+
+The SSH authentication Secret type is provided only for convenience. You can create an `Opaque` type 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. The Kubernetes API verifies that the required keys are set for a Secret of this type.
+
+> [!caution] Caution:
+> SSH private keys do not establish trusted communication between an SSH client and host server on their own. A secondary means of establishing trust is needed to mitigate "man in the middle" attacks, such as a `known_hosts` file added to a ConfigMap.
+
+### TLS Secrets
+
+The `kubernetes.io/tls` Secret type is for storing 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](https://kubernetes.io/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.
+
+As an alternative to using `stringData`, you can use the `data` field to provide the base64 encoded certificate and private key. For details, see [Constraints on Secret names and data](#restriction-names-data).
+
+The following YAML contains an example config for a TLS Secret:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: secret-tls
+type: kubernetes.io/tls
+data:
+  # values are base64 encoded, which obscures them but does NOT provide
+  # any useful level of confidentiality
+  # Replace the following values with your own base64-encoded certificate and key.
+  tls.crt: "REPLACE_WITH_BASE64_CERT" 
+  tls.key: "REPLACE_WITH_BASE64_KEY"
+```
+
+The TLS Secret type is provided only for convenience. You can create an `Opaque` type for credentials used for TLS authentication. However, using the defined and public Secret type (`kubernetes.io/tls`) helps ensure the consistency of Secret format in your project. The API server verifies if the required keys are set for a Secret of this type.
+
+To create a TLS Secret using `kubectl`, use the `tls` subcommand:
+
+```shell
+kubectl create secret tls my-tls-secret \
+  --cert=path/to/cert/file \
+  --key=path/to/key/file
+```
+
+The public/private key pair must exist before hand. The public key certificate for `--cert` must be.PEM encoded and must match the given private key for `--key`.
+
+### Bootstrap token Secrets
+
+The `bootstrap.kubernetes.io/token` Secret type is for tokens used during the node bootstrap process. It stores tokens used to sign well-known ConfigMaps.
+
+A bootstrap token Secret is usually created in the `kube-system` namespace and named in the form `bootstrap-token-<token-id>` where `<token-id>` is a 6 character string of the token ID.
+
+As a Kubernetes manifest, a bootstrap token Secret might look like the following:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: bootstrap-token-5emitj
+  namespace: kube-system
+type: bootstrap.kubernetes.io/token
+data:
+  auth-extra-groups: c3lzdGVtOmJvb3RzdHJhcHBlcnM6a3ViZWFkbTpkZWZhdWx0LW5vZGUtdG9rZW4=
+  expiration: MjAyMC0wOS0xM1QwNDozOToxMFo=
+  token-id: NWVtaXRq
+  token-secret: a3E0Z2lodnN6emduMXAwcg==
+  usage-bootstrap-authentication: dHJ1ZQ==
+  usage-bootstrap-signing: dHJ1ZQ==
+```
+
+A bootstrap token Secret has the following keys specified under `data`:
+
+- `token-id`: A random 6 character string as the token identifier. Required.
+- `token-secret`: A random 16 character string as the actual token Secret. Required.
+- `description`: A human-readable string that describes what the token is used for. Optional.
+- `expiration`: An absolute UTC time using [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) specifying when the token should be expired. Optional.
+- `usage-bootstrap-<usage>`: A boolean flag indicating additional usage for the bootstrap token.
+- `auth-extra-groups`: A comma-separated list of group names that will be authenticated as in addition to the `system:bootstrappers` group.
+
+You can alternatively provide the values in the `stringData` field of the Secret without base64 encoding them:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  # Note how the Secret is named
+  name: bootstrap-token-5emitj
+  # A bootstrap token Secret usually resides in the kube-system namespace
+  namespace: kube-system
+type: bootstrap.kubernetes.io/token
+stringData:
+  auth-extra-groups: "system:bootstrappers:kubeadm:default-node-token"
+  expiration: "2020-09-13T04:39:10Z"
+  # This token ID is used in the name
+  token-id: "5emitj"
+  token-secret: "kq4gihvszzgn1p0r"
+  # This token can be used for authentication
+  usage-bootstrap-authentication: "true"
+  # and it can be used for signing
+  usage-bootstrap-signing: "true"
+```
+
+> [!info] Note:
+> The `stringData` field for a Secret does not work well with server-side apply.
+
+## Working with Secrets
+
+### Creating a Secret
+
+There are several options to create a Secret:
+
+- [Use `kubectl`](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
+- [Use a configuration file](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-config-file/)
+- [Use the Kustomize tool](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
+
+#### Constraints on Secret names and data
+
+The name of a Secret object must be a valid [DNS subdomain name](https://kubernetes.io/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. If the conversion to base64 string is not desirable, you can choose to specify the `stringData` field instead, which accepts arbitrary strings as values.
+
+The keys of `data` and `stringData` must consist of alphanumeric characters, `-`, `_` or `.`. All key-value pairs in the `stringData` field are internally 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
+
+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](https://kubernetes.io/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 unless it is [immutable](#secret-immutable). To edit a Secret, use one of the following methods:
+
+- [Use `kubectl`](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/#edit-secret)
+- [Use a configuration file](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-config-file/#edit-secret)
+
+You can also edit the data in a Secret using the [Kustomize tool](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/#edit-secret). However, this method creates a new `Secret` object with the edited data.
+
+Depending on how you created the Secret, as well as how the Secret is used in your Pods, updates to existing `Secret` objects are propagated automatically to Pods that use the data. For more information, refer to [Using Secrets as files from a Pod](#using-secrets-as-files-from-a-pod) section.
+
+### Using a Secret
+
+Secrets can be mounted as data volumes or exposed as [environment variables](https://kubernetes.io/docs/concepts/containers/container-environment/ "Container environment variables are name=value pairs that provide useful information into containers running in a Pod.") 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
+
+When you reference a Secret in a Pod, you can mark the Secret as *optional*, such as in the following example. If an optional Secret doesn't exist, Kubernetes ignores it.
+
+```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: true
+```
+
+By default, Secrets are 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 non-optional Secret and that Secret does exist, but is missing the named key, the Pod fails during startup.
+
+### 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.
+
+For instructions, refer to [Create a Pod that has access to the secret data through a Volume](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#create-a-pod-that-has-access-to-the-secret-data-through-a-volume).
+
+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.
+
+> [!info] Note:
+> A container using a Secret as a [subPath](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath) volume mount does not receive automated Secret updates.
+
+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](https://kubernetes.io/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 [environment variable](https://kubernetes.io/docs/concepts/containers/container-environment/ "Container environment variables are name=value pairs that provide useful information into containers running in a Pod.") in a Pod:
+
+1. For each container in your Pod specification, add an environment variable for each Secret key that you want to use to the `env[].valueFrom.secretKeyRef` field.
+2. Modify your image and/or command line so that the program looks for values in the specified environment variables.
+
+For instructions, refer to [Define container environment variables using Secret data](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data).
+
+It's important to note that the range of characters allowed for environment variable names in pods is [restricted](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config). If any keys do not meet the rules, those keys are not made available to your container, though the Pod is allowed to start.
+
+### Container image pull Secrets
+
+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.
+
+#### 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#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](https://kubernetes.io/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](https://kubernetes.io/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
+
+You cannot use ConfigMaps or Secrets with [static Pods](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/ "A pod managed directly by the kubelet daemon on a specific node.").
+
+## Immutable Secrets
+
+FEATURE STATE: `Kubernetes v1.21 [stable]`
+
+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
+- (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.
+
+### Marking a Secret as immutable
+
+You can create an immutable Secret by setting the `immutable` field to `true`. For example,
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata: ...
+data: ...
+immutable: true
+```
+
+You can also update any existing mutable Secret to make it immutable.
+
+> [!info] 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. Existing Pods maintain a mount point to the deleted Secret - it is recommended to recreate these pods.
+
+## Information security for Secrets
+
+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 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.
+
+Authorization configuration affects how Secret data can be accessed within a namespace. For example, granting **list** or **watch** permissions on Secrets allows a subject to read all Secret data in that namespace, not only the Secrets explicitly referenced by its Pods. Restrict access to the minimum set of permissions required for a workload to function, and avoid granting broad roles such as `cluster-admin` unless required for administrative purposes.
+
+Also see the [Authorization documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
+
+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.
+
+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.
+
+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.
+
+### Configure least-privilege access to Secrets
+
+To enhance the security measures around Secrets, use separate namespaces to isolate access to mounted secrets.
+
+> [!danger] Warning:
+> Any containers that run with `privileged: true` on a node can access all Secrets used on that node.
+
+## What's next
+
+- For guidelines to manage and improve the security of your Secrets, refer to [Good practices for Kubernetes Secrets](https://kubernetes.io/docs/concepts/security/secrets-good-practices/).
+- Learn how to [manage Secrets using `kubectl`](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
+- Learn how to [manage Secrets using config file](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-config-file/)
+- Learn how to [manage Secrets using kustomize](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
+- Read the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/) for `Secret`
+  
+
+Last modified March 17, 2026 at 1:33 AM PST: [Improve security clarification for Kubernetes Secrets (#54644) (8af7916eb8)](https://github.com/kubernetes/website/commit/8af7916eb81024c5da7a9b4c4477db18e5fffda2)