NetworkPolicy selectors — pods, namespaces, and IP blocks

NetworkPolicy selectors are the building blocks of the policy. The podSelector matches Pods by labels; the namespaceSelector matches namespaces by labels; the ipBlock matches IP blocks. This lesson walks the selectors, the combination rules, and the operational discipline.

The podSelector

The podSelector matches Pods by labels:

podSelector:
  matchLabels:
    app: billing
    tier: backend

The podSelector is in the NetworkPolicy’s spec to select the Pods the policy applies to:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: billing-policy
  namespace: prod-app
spec:
  podSelector:
    matchLabels:
      app: billing
  policyTypes:
    - Ingress

The podSelector also appears in the policy’s from or to to select the source or destination Pods:

ingress:
  - from:
      - podSelector:
          matchLabels:
            app: api-gateway

The podSelector matches Pods in the same namespace (for ingress sources) or in the policy’s namespace (for egress destinations).

The namespaceSelector

The namespaceSelector matches namespaces by labels:

namespaceSelector:
  matchLabels:
    kubernetes.io/metadata.name: monitoring

The namespaceSelector is used in the from or to to select namespaces:

ingress:
  - from:
      - namespaceSelector:
          matchLabels:
            kubernetes.io/metadata.name: monitoring
        podSelector:
          matchLabels:
            k8s-app: prometheus

The namespaceSelector matches Pods in any namespace with the matching labels.

The ipBlock

The ipBlock matches IP blocks:

ipBlock:
  cidr: 192.0.2.0/24
  except:
    - 192.0.2.10/32

The ipBlock is used in the from or to to select IP blocks:

ingress:
  - from:
      - ipBlock:
          cidr: 192.0.2.0/24
    ports:
      - protocol: TCP
        port: 8080

The ipBlock matches external IPs. The use case is allowing external traffic from a specific IP block.

The combination rules

The combination rules are:

• Within a single entry: selectors are AND-combined.
• Across entries: selectors are OR-combined.

flowchart LR
    A[within entry 1] --> B[AND]
    C[within entry 2] --> D[AND]
    A --> E[OR]
    C --> E

Example:

ingress:
  - from:
      - podSelector:           # AND
          matchLabels:
            app: api-gateway
        namespaceSelector:
          matchLabels:
            kubernetes.io/metadata.name: prod-app
  - from:
      - podSelector:           # OR
          matchLabels:
            app: admin

The first entry matches Pods with app: api-gateway in namespaces with the metadata name prod-app. The second entry matches Pods with app: admin in any namespace. The result is the union of the two entries.

The failure modes

The selectors’ failure modes:

• Pod selector mismatch: the selector does not match the intended Pods. The fix is to verify the labels.
• Namespace selector mismatch: the selector does not match the intended namespaces. The fix is to verify the namespace labels.
• ipBlock mismatch: the IP block does not match the intended IPs. The fix is to verify the CIDR.
• Combination rule misunderstood: the operator expects OR but the rule is AND. The fix is to read the NetworkPolicy documentation.

The operational discipline

The selectors’ operational discipline:

• Document the selectors. The selectors are the cluster’s firewall configuration.
• Audit the selectors at every change. The selectors are critical security configuration.
• Test the selectors in staging. The selectors must work for the workload.
• Verify the namespace labels. The namespace labels must be set for the namespaceSelector.
• Use the combination rules correctly. The AND/OR combination is the basis of the policy.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The selectors are the cluster’s firewall configuration. The cluster operator must treat them as critical security configuration.
• Document the selectors. The selectors are the cluster’s firewall configuration.
• Audit the selectors at every change. The selectors are critical security configuration.
• Test the selectors in staging. The selectors must work for the workload.
• Verify the namespace labels. The namespace labels must be set for the namespaceSelector.
• Use the combination rules correctly. The AND/OR combination is the basis of the policy.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the security team on the selectors. The selectors are the basis of the cluster’s security.
• Use a CI check for the selectors. The CI check can catch the selector error at every change.