Configure a pod to use the host network (hostNetwork) - Container Service for Kubernetes

By default, a pod's network traffic is forwarded through the node kernel. This process can cause performance loss. To achieve higher network performance, you can configure the pod to use host network mode (hostNetwork). This mode allows the pod to share the node's network namespace and is suitable for high-performance Container Network Interface (CNI) plug-ins and node-level monitoring.

Important

In a production environment, configure host network mode only for pods that absolutely require it. A pod in host network mode uses the network namespace of its node. This increases the potential impact of an attack. The pod is no longer restricted by network policies. Instead, it is restricted by the rules of the cluster security group.

Usage

To enable host network mode, set hostNetwork to true. Then, set dnsPolicy to ClusterFirstWithHostNet to ensure that the pod can resolve domain names in the cluster. Finally, declare a containerPort that matches the listening port of the process in the container.

apiVersion: v1
kind: Pod
metadata:
  ...
spec:
  hostNetwork: true # Enable host network mode.
  dnsPolicy: ClusterFirstWithHostNet # Ensure the pod can resolve domain names in the cluster.
  containers:
  - ...
    ports:
      - containerPort: 12000 # The port on which the container listens. This must match the port configured for the process in the container. The port 12000 is an example.
  ...

Scope

You can configure host network mode only when you create a workload. You cannot change an existing pod to use host network mode.

Procedure

The following example deploys a DaemonSet that uses pods with host network mode enabled to perform node-level monitoring with node-exporter.

Replace the <REGION_ID> variable with the ID of the region where your cluster is deployed. Then, create and save a file named node-exporter.yaml.

For more information about region IDs, see Regions and zones.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: node-exporter-demo
  labels:
    app: node-exporter-demo
spec:
  selector:
    matchLabels:
      app: node-exporter-demo
  template:
    metadata:
      labels:
        app: node-exporter-demo
    spec:
      hostNetwork: true # Enable host network mode.
      hostPID: true 
      dnsPolicy: ClusterFirstWithHostNet # Ensure the pod can resolve domain names in the cluster.
      containers:
      - name: node-exporter-demo
        image: registry-<REGION_ID>-vpc.ack.aliyuncs.com/acs/node-exporter:v0.17.0-slim # Replace <REGION_ID> with the region ID of the cluster.
        args:
        - '--path.procfs=/host/proc'
        - '--path.sysfs=/host/sys'
        - '--web.listen-address=0.0.0.0:20000'
        ports:
        - name: metrics
          containerPort: 20000
        volumeMounts:
        - name: proc
          mountPath: /host/proc
          readOnly: true
        - name: sys
          mountPath: /host/sys
          readOnly: true
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "200m"
      volumes:
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys

spec.hostNetwork: Set this parameter to true to enable host network mode for the pod.
spec.dnsPolicy: Set this parameter to ClusterFirstWithHostNet to ensure that the pod can resolve domain names in the cluster.
spec.containers.ports: Specifies the listening port. This port number must match the port on which the application in the container listens.

Create the DaemonSet.

kubectl apply -f node-exporter.yaml

Expected output:

daemonset/node-exporter created

Check the pod information. If a pod's IP address is the same as its node's IP address, host network mode is enabled.

kubectl get pod -o wide

The following output shows that the pod IP address is the same as the node IP address.

NAME                       READY   STATUS    RESTARTS   AGE     IP               NODE                      NOMINATED NODE   READINESS GATES
node-exporter-demo-49v**   1/1     Running   0          15h     10.***.8.109     xx-xxxx.10.***.8.109      <none>           <none>
node-exporter-demo-jdx**   1/1     Running   0          15h     10.***.203.146   xx-xxxx.10.***.203.146    <none>           <none>
node-exporter-demo-krg**   1/1     Running   0          15h     10.***.105.151   xx-xxxx.10.***.105.151    <none>           <none>

Log on to the node. The pod listens directly on port 20000 of the node. To verify the configuration, access the service from the node at localhost:20000. If the command returns node metrics data, the configuration is successful.
```
curl localhost:20000/metrics
```

FAQ

Why is my pod in the Pending state?

A pod may remain in the Pending state for a long time for the following reasons:

The port declared by the pod is already in use on the node. The process in the container cannot bind to the port, which causes the pod to fail to start. Do not select the following ports:
- Ports for core cluster components: 6443, 9890, 9099, 10250, 10256, and 30000 to 32767.
- Standard service ports: 22, 53, 80, and 443.
- Custom ports used by other services.
If you use Pod Security Admission (PSA) configurations, the deployment of pods in host network mode may be blocked. When you use PSA configurations, make sure that the namespace uses the following label:
Important
Setting this label grants the pod permissions to perform all privileged operations. Use this label with caution.
```
apiVersion: v1
kind: Namespace
metadata:
  name: my-privileged-ns
  labels:
    pod-security.kubernetes.io/enforce: privileged
```
For more information about the configuration details of pod-security.kubernetes.io, see Pod Security Admission.
If you use a container security policy, make sure that the policy allows pods to use the host network and the pod port is within the allowed range.

Why can't my pod resolve cluster domain names?

To resolve domain names in the cluster, a pod in host network mode must be configured with spec.dnsPolicy: ClusterFirstWithHostNet. For an example of how to configure the pod, see the Procedure section.