Document the tolerations deprecation and fix the dev nodeSelector notes

src/content/self-hosted/helm-configuration.mdx

@@ -144,7 +144,7 @@ api:
 
 The cluster autoscaler service. Disabled by default.
 It instructs the Kubernetes cluster autoscaler to scale nodes if the real cpu/memory usage of a node is beyond the limits.
-Use `tolerations.devPool` to limit the autoscaler analysis to a subset of cluster nodes.
+Use [`globals.nodeSelectors.dev`](self-hosted/helm-configuration.mdx#nodeselectors) to limit the autoscaler analysis to a subset of cluster nodes. The deprecated `tolerations.devPool` is still honored and takes precedence over it when set.
 
 > **Requirements**: cluster autoscaler and metrics server must be installed in your cluster.
 
@@ -355,8 +355,16 @@ The daemonset performs the following tasks on each node:
 You can restrict the nodes where the daemonset is deployed using `dev` [tolerations](self-hosted/helm-configuration.mdx#tolerations) and [nodeSelectors](self-hosted/helm-configuration.mdx#nodeselectors):
 
 ```yaml
-tolerations:
-  devPool: dev
+globals:
+  nodeSelectors:
+    dev:
+      okteto-node-pool: dev
+  tolerations:
+    dev:
+      - key: okteto-node-pool
+        operator: Equal
+        value: dev
+        effect: NoSchedule
 ```
 
 ### defaultBackend
@@ -388,11 +396,6 @@ The defaultBackend provides the following features:
 - **Autowake namespaces**: When a user accesses an endpoint from a sleeping namespace, the defaultBackend will issue a wake command.
 - **Custom error pages**: When users access endpoints that encounter errors, the defaultBackend serves custom error pages with contextual hints on how to resolve the issue. This provides a better user experience by offering clear explanations and actionable steps instead of generic error messages. Common scenarios include accessing sleeping namespaces, or service unavailability. These error pages work automatically and require no additional configuration.
 
-```yaml
-tolerations:
-  devPool: dev
-```
-
 ### frontend
 
 The frontend service serves the web application.
@@ -847,7 +850,7 @@ globals:
 Specifies the node selectors to be applied to pods, categorized under `okteto` or `dev`:
 
 - `okteto`: Node selectors applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset).
-- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. These node selectors are only applied when a corresponding `tolerations.devPool` is defined. It also applies to the [Okteto Daemonset](#daemonset). This is a legacy behavior and may change in future releases.
+- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. It also applies to the [Okteto Daemonset](#daemonset).
 
 ```yaml
 globals:
@@ -860,7 +863,9 @@ globals:
 ```
 
 :::note
-Node selectors defined in `globals.nodeSelectors.dev` will not be applied to user workloads unless a `tolerations.devPool` value is also set. This coupling is due to a legacy implementation and may be revised in future updates.
+If the nodes you select are tainted, you must also define a matching toleration in [`globals.tolerations.dev`](#tolerations). A node selector on its own will place user workloads on nodes they cannot tolerate, and they will stay `Pending`.
+
+These node selectors do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations).
 :::
 
 #### priorityClassName
@@ -887,7 +892,7 @@ globals:
 Specifies the tolerations to be applied to pods, categorized under `okteto` or `dev`:
 
 - `okteto`: Tolerations applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset).
-- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. Required for `globals.nodeSelectors.dev` to take effect. This also applies to the [Okteto Daemonset](#daemonset).
+- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. This also applies to the [Okteto Daemonset](#daemonset).
 
 ```yaml
 globals:
@@ -904,8 +909,14 @@ globals:
       effect: "NoSchedule"
 ```
 
+:::warning
+The older `tolerations.oktetoPool`, `tolerations.buildPool` and `tolerations.devPool` values are deprecated and will be removed in Okteto Chart 2.0. Installing the chart while they are set prints a deprecation warning. Use `globals.tolerations` and [`globals.nodeSelectors`](#nodeselectors) instead, together with [`buildkit.tolerations` and `buildkit.nodeSelectors`](#buildkit) for BuildKit. See the [migration guide](https://community.okteto.com/t/important-update-migrating-to-new-implementation-of-okteto-pod-tolerations-and-node-selectors/1281) for the full mapping.
+:::
+
 :::note
-To apply node selectors for user workloads, you must define a `devPool` entry in `globals.tolerations`. See the [nodeSelectors](#nodeselectors) section for more details.
+If the nodes selected by [`globals.nodeSelectors.dev`](#nodeselectors) are tainted, define a matching toleration under `dev` above so that user workloads can schedule onto them.
+
+These tolerations do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations).
 :::
 
 ### ingress
@@ -1393,6 +1404,64 @@ ingress-nginx:
 
 The full list of values is [available here](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml).
 
+#### Node selectors and tolerations
+
+[`globals.nodeSelectors`](#nodeselectors) and [`globals.tolerations`](#tolerations) apply to Okteto's own components. They do **not** reach the two ingress controllers or [Reloader](#reloader), which are separate charts and read their own values instead.
+
+If you run Okteto on dedicated node pools, or on any node pool that carries a taint, configure all of them:
+
+```yaml
+globals:
+  nodeSelectors:
+    okteto:
+      okteto-node-pool: okteto
+  tolerations:
+    okteto:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+ingress-nginx:
+  controller:
+    nodeSelector:
+      okteto-node-pool: okteto
+    tolerations:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+okteto-nginx:
+  controller:
+    nodeSelector:
+      okteto-node-pool: okteto
+    tolerations:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+reloader:
+  reloader:
+    deployment:
+      nodeSelector:
+        okteto-node-pool: okteto
+      tolerations:
+        - key: okteto-node-pool
+          operator: Equal
+          value: okteto
+          effect: NoSchedule
+```
+
+:::warning
+Leaving these out fails silently. The chart installs successfully, and the ingress controllers and Reloader schedule onto whichever nodes accept them, which on a cluster with dedicated pools is usually the untainted default pool. If every pool in the cluster is tainted, they stay `Pending` instead.
+:::
+
+These charts also accept `affinity`, `topologySpreadConstraints` and `priorityClassName` under the same keys. They are maintained upstream, so check their own value references for the authoritative list: [ingress-nginx](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml), used by both the `ingress-nginx` and `okteto-nginx` keys, and [Reloader](https://github.com/stakater/Reloader#parameters).
+
+For a worked example on ARM node pools, which are tainted by the cloud provider, see [ARM Support](self-hosted/manage/arm-support.mdx).
+
 #### ingress-nginx & okteto-nginx default values
 
 Okteto sets specific values on the embedded ingress-nginx chart to enable features dependent on the ingress-controller. The values can be checked with the following command:

versioned_docs/version-1.47/self-hosted/helm-configuration.mdx

@@ -144,7 +144,7 @@ api:
 
 The cluster autoscaler service. Disabled by default.
 It instructs the Kubernetes cluster autoscaler to scale nodes if the real cpu/memory usage of a node is beyond the limits.
-Use `tolerations.devPool` to limit the autoscaler analysis to a subset of cluster nodes.
+Use [`globals.nodeSelectors.dev`](self-hosted/helm-configuration.mdx#nodeselectors) to limit the autoscaler analysis to a subset of cluster nodes. The deprecated `tolerations.devPool` is still honored and takes precedence over it when set.
 
 > **Requirements**: cluster autoscaler and metrics server must be installed in your cluster.
 
@@ -355,8 +355,16 @@ The daemonset performs the following tasks on each node:
 You can restrict the nodes where the daemonset is deployed using `dev` [tolerations](self-hosted/helm-configuration.mdx#tolerations) and [nodeSelectors](self-hosted/helm-configuration.mdx#nodeselectors):
 
 ```yaml
-tolerations:
-  devPool: dev
+globals:
+  nodeSelectors:
+    dev:
+      okteto-node-pool: dev
+  tolerations:
+    dev:
+      - key: okteto-node-pool
+        operator: Equal
+        value: dev
+        effect: NoSchedule
 ```
 
 ### defaultBackend
@@ -388,11 +396,6 @@ The defaultBackend provides the following features:
 - **Autowake namespaces**: When a user accesses an endpoint from a sleeping namespace, the defaultBackend will issue a wake command.
 - **Custom error pages**: When users access endpoints that encounter errors, the defaultBackend serves custom error pages with contextual hints on how to resolve the issue. This provides a better user experience by offering clear explanations and actionable steps instead of generic error messages. Common scenarios include accessing sleeping namespaces, or service unavailability. These error pages work automatically and require no additional configuration.
 
-```yaml
-tolerations:
-  devPool: dev
-```
-
 ### frontend
 
 The frontend service serves the web application.
@@ -847,7 +850,7 @@ globals:
 Specifies the node selectors to be applied to pods, categorized under `okteto` or `dev`:
 
 - `okteto`: Node selectors applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset).
-- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. These node selectors are only applied when a corresponding `tolerations.devPool` is defined. It also applies to the [Okteto Daemonset](#daemonset). This is a legacy behavior and may change in future releases.
+- `dev`: Node selectors applied to pods created by user applications, which run in namespaces managed by Okteto. It also applies to the [Okteto Daemonset](#daemonset).
 
 ```yaml
 globals:
@@ -860,7 +863,9 @@ globals:
 ```
 
 :::note
-Node selectors defined in `globals.nodeSelectors.dev` will not be applied to user workloads unless a `tolerations.devPool` value is also set. This coupling is due to a legacy implementation and may be revised in future updates.
+If the nodes you select are tainted, you must also define a matching toleration in [`globals.tolerations.dev`](#tolerations). A node selector on its own will place user workloads on nodes they cannot tolerate, and they will stay `Pending`.
+
+These node selectors do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations).
 :::
 
 #### priorityClassName
@@ -887,7 +892,7 @@ globals:
 Specifies the tolerations to be applied to pods, categorized under `okteto` or `dev`:
 
 - `okteto`: Tolerations applied to pods running in the `okteto` namespace, excluding the [Okteto Daemonset](#daemonset).
-- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. Required for `globals.nodeSelectors.dev` to take effect. This also applies to the [Okteto Daemonset](#daemonset).
+- `dev`: Tolerations applied to pods created by user applications, which run in namespaces managed by Okteto. This also applies to the [Okteto Daemonset](#daemonset).
 
 ```yaml
 globals:
@@ -904,8 +909,14 @@ globals:
       effect: "NoSchedule"
 ```
 
+:::warning
+The older `tolerations.oktetoPool`, `tolerations.buildPool` and `tolerations.devPool` values are deprecated and will be removed in Okteto Chart 2.0. Installing the chart while they are set prints a deprecation warning. Use `globals.tolerations` and [`globals.nodeSelectors`](#nodeselectors) instead, together with [`buildkit.tolerations` and `buildkit.nodeSelectors`](#buildkit) for BuildKit. See the [migration guide](https://community.okteto.com/t/important-update-migrating-to-new-implementation-of-okteto-pod-tolerations-and-node-selectors/1281) for the full mapping.
+:::
+
 :::note
-To apply node selectors for user workloads, you must define a `devPool` entry in `globals.tolerations`. See the [nodeSelectors](#nodeselectors) section for more details.
+If the nodes selected by [`globals.nodeSelectors.dev`](#nodeselectors) are tainted, define a matching toleration under `dev` above so that user workloads can schedule onto them.
+
+These tolerations do not apply to the ingress controllers or Reloader. See [Node selectors and tolerations](#node-selectors-and-tolerations).
 :::
 
 ### ingress
@@ -1393,6 +1404,64 @@ ingress-nginx:
 
 The full list of values is [available here](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml).
 
+#### Node selectors and tolerations
+
+[`globals.nodeSelectors`](#nodeselectors) and [`globals.tolerations`](#tolerations) apply to Okteto's own components. They do **not** reach the two ingress controllers or [Reloader](#reloader), which are separate charts and read their own values instead.
+
+If you run Okteto on dedicated node pools, or on any node pool that carries a taint, configure all of them:
+
+```yaml
+globals:
+  nodeSelectors:
+    okteto:
+      okteto-node-pool: okteto
+  tolerations:
+    okteto:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+ingress-nginx:
+  controller:
+    nodeSelector:
+      okteto-node-pool: okteto
+    tolerations:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+okteto-nginx:
+  controller:
+    nodeSelector:
+      okteto-node-pool: okteto
+    tolerations:
+      - key: okteto-node-pool
+        operator: Equal
+        value: okteto
+        effect: NoSchedule
+
+reloader:
+  reloader:
+    deployment:
+      nodeSelector:
+        okteto-node-pool: okteto
+      tolerations:
+        - key: okteto-node-pool
+          operator: Equal
+          value: okteto
+          effect: NoSchedule
+```
+
+:::warning
+Leaving these out fails silently. The chart installs successfully, and the ingress controllers and Reloader schedule onto whichever nodes accept them, which on a cluster with dedicated pools is usually the untainted default pool. If every pool in the cluster is tainted, they stay `Pending` instead.
+:::
+
+These charts also accept `affinity`, `topologySpreadConstraints` and `priorityClassName` under the same keys. They are maintained upstream, so check their own value references for the authoritative list: [ingress-nginx](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml), used by both the `ingress-nginx` and `okteto-nginx` keys, and [Reloader](https://github.com/stakater/Reloader#parameters).
+
+For a worked example on ARM node pools, which are tainted by the cloud provider, see [ARM Support](self-hosted/manage/arm-support.mdx).
+
 #### ingress-nginx & okteto-nginx default values
 
 Okteto sets specific values on the embedded ingress-nginx chart to enable features dependent on the ingress-controller. The values can be checked with the following command: