User Stories¶

ALL Network Policy API resources and future API developments should start with a well-defined and intentional user story(s).

ClusterNetworkPolicy (CNP)¶

User Stories¶

The following user stories drive the concepts for ClusterNetworkPolicy resources. Discussions on the user stories can be found here:

Story 1: Deny traffic at a cluster level¶

As a cluster admin, I want to apply non-overridable deny rules to certain pod(s) and(or) Namespace(s) that isolate the selected resources from all other cluster internal traffic.

For Example: In this diagram there is a ClusterNetworkPolicy in the Admin tier applied to the sensitive-ns denying ingress from all other in-cluster resources for all ports and protocols.

Alt text

Equivalent API Object

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: cluster-wide-deny-example
spec:
  tier: Admin
  priority: 10
  subject:
    namespaces:
      matchLabels:
        kubernetes.io/metadata.name: sensitive-ns
  ingress:
    - action: Deny
      from:
      - namespaces:
          matchLabels: {} # Match all namespaces.
      name: select-all-deny-all

Story 2: Allow traffic at a cluster level¶

As a cluster admin, I want to apply non-overridable allow rules to certain pods(s) and(or) Namespace(s) that enable the selected resources to communicate with all other cluster internal entities.

For Example: In this diagram there is a ClusterNetworkPolicy in the Admin tier applied to every namespace in the cluster allowing egress traffic to kube-dns pods, and ingress traffic from pods in monitoring-ns for all ports and protocols.

Alt text

Equivalent API Object

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: cluster-wide-allow-example
spec:
  tier: Admin
  priority: 30
  subject:
    namespaces: {}
  ingress:
    - action: Accept
      name: allow-monitoring-ns-ingress
      from:
      - namespaces:
          matchLabels:
            kubernetes.io/metadata.name: monitoring-ns
  egress:
  - action: Accept
    name: allow-kube-dns-egress
    to:
    - pods:
        namespaceSelector:
          matchLabels:
            kubernetes.io/metadata.name: kube-system
        podSelector:
          matchLabels:
            app: kube-dns

Story 3: Explicitly Delegate traffic to existing K8s Network Policy¶

As a cluster admin, I want to explicitly delegate traffic so that it skips any remaining cluster network policies and is handled by standard namespace scoped network policies.

For Example: In the diagram below egress traffic destined for the service svc-pub in namespace bar-ns-1 on TCP port 8080 is delegated to the k8s network policies implemented in foo-ns-1 and foo-ns-2. If no k8s network policies match the delegated traffic, the traffic will be allowed.

Alt text

Equivalent API Object

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: pub-svc-delegate-example
spec:
  tier: Admin
  priority: 20
  subject:
    namespaces: {}
  egress:
  - action: Pass # to be handled by NetworkPolicy.
    to:
    - pods:
        namespaceSelector:
          matchLabels:
            kubernetes.io/metadata.name: bar-ns-1
        podSelector:
          matchLabels:
            app: svc-pub
    ports:
    - portNumber:
        protocol: TCP
        port: 8080

Story 4: Create and Isolate multiple tenants in a cluster¶

(Currently not implementable)

As a cluster admin, I want to build tenants in my cluster that are isolated from each other by default. Tenancy may be modeled as 1:1, where 1 tenant is mapped to a single Namespace, or 1:n, where a single tenant may own more than 1 Namespace.

For Example: In the diagram below two tenants (Foo and Bar) are defined such that all ingress traffic is denied to either tenant.

Alt text

Equivalent API Object

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: tenant-creation-example
spec:
  tier: Admin
  priority: 50
  subject:
    namespaces:
      matchExpressions: {key: "tenant"; operator: Exists}
  ingress:
    - action: Deny
      from:
      - namespaces:
          # This user story is currently not implementable.
          # See https://network-policy-api.sigs.k8s.io/npeps/npep-122/ for more details.

This can also be expressed in the following way:

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: tenant-creation-example
spec:
  tier: Admin
  priority: 50
  subject:
    namespaces:
      matchExpressions: {key: "tenant"; operator: Exists}
  ingress:
    - action: Pass # Pass inter-tenant traffic to any defined NetworkPolicies
      from:
      - namespaces:
          # This user story is currently not implementable.
          # See https://network-policy-api.sigs.k8s.io/npeps/npep-122/ for more details.
    - action: Deny   # Deny everything else other than same tenant traffic
      from:
      - namespaces: {}

Story 5: Cluster Wide Default Guardrails¶

As a cluster admin I want to change the default security model for my cluster, so that all intra-cluster traffic (except for certain essential traffic) is blocked by default. Namespace owners will need to use NetworkPolicies to explicitly allow known traffic. This follows a whitelist model which is familiar to many security administrators, and similar to how kubernetes suggests network policy be used.

For Example: In the following diagram all Ingress traffic to every cluster resource is denied by a baseline deny rule.

Alt text

Equivalent API Object

apiVersion: policy.networking.k8s.io/v1alpha2
kind: ClusterNetworkPolicy
metadata:
  name: default
spec:
  tier: Baseline
  priority: 10
  subject:
    namespaces: {}
  ingress:
    - action: Deny   # zero-trust cluster default security posture
      from:
      - namespaces: {}