From a32d30c107a339d78c81262f2f869912e69f01b3 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Thu, 11 May 2017 16:26:32 -0400 Subject: [PATCH] NetworkPolicy updates for v1 (#3721) * NetworkPolicy clarifications - For clarity, only use the word "policy" in reference to NetworkPolicies, not in reference to the isolation annotation. - Drop a bunch of text related to the isolation annotation since there's only one interesting value so there's no reason to complicate things. - Fix bad YAML indentation - Misc rewording * Update NetworkPolicy docs for v1 --- .../services-networking/networkpolicies.md | 91 +++++++++---------- .../declare-network-policy.md | 33 +++++-- 2 files changed, 67 insertions(+), 57 deletions(-) diff --git a/docs/concepts/services-networking/networkpolicies.md b/docs/concepts/services-networking/networkpolicies.md index 998bca3651..2f6c77bcbe 100644 --- a/docs/concepts/services-networking/networkpolicies.md +++ b/docs/concepts/services-networking/networkpolicies.md @@ -2,6 +2,7 @@ assignees: - thockin - caseydavenport +- danwinship title: Network Policies redirect_from: - "/docs/user-guide/networkpolicies/" @@ -11,41 +12,37 @@ redirect_from: * TOC {:toc} -A network policy is a specification of how selections of pods are allowed to communicate with each other and other network endpoints. +A network policy is a specification of how groups of pods are allowed to communicate with each other and other network endpoints. `NetworkPolicy` resources use labels to select pods and define whitelist rules which allow traffic to the selected pods in addition to what is allowed by the isolation policy for a given namespace. ## Prerequisites -You must enable the `extensions/v1beta1/networkpolicies` runtime config in your apiserver to enable this resource. +Network policies are implemented by the network plugin, so you must be using a networking solution which supports `NetworkPolicy` - simply creating the resource without a controller to implement it will have no effect. -You must also be using a networking solution which supports `NetworkPolicy` - simply creating the -resource without a controller to implement it will have no effect. +## Configuring Namespace Isolation -## Configuring Namespace Isolation Policy +By default, all traffic is allowed between all pods (and `NetworkPolicy` resources have no effect). -Isolation can be configured on a per-namespace basis. Once isolation is configured on a namespace it will be applied to all pods in that namespace. Currently, only isolation policy on inbound traffic (ingress) can be defined. +Isolation can be configured on a per-namespace basis. Currently, only isolation on inbound traffic (ingress) can be defined. When a namespace has been configured to isolate inbound traffic, all traffic to pods in that namespace (even from other pods in the same namespace) will be blocked. `NetworkPolicy` objects can then be added to the isolated namespace to specify what traffic should be allowed. -The following ingress isolation types being supported: +Isolation is enabled via the `NetworkPolicy` field of the `Namespace` object. To enable isolation via `kubectl`: -- `DefaultDeny`: Pods in the namespace will be inaccessible from any source except the pod's local node. - -Ingress isolation can be enabled using an annotation on the Namespace. - -```yaml -kind: Namespace -apiVersion: v1 -metadata: - annotations: - net.beta.kubernetes.io/network-policy: | - { - "ingress": { - "isolation": "DefaultDeny" - } - } +```shell +{% raw %} +kubectl patch ns -p '{"spec": {"networkPolicy": {"ingress": {"isolation": "DefaultDeny"}}}}' +{% endraw %} ``` -To configure the annotation via `kubectl`: +To disable it: + +```shell +{% raw %} +kubectl patch ns -p '{"spec": {"networkPolicy": null}}' +{% endraw %} +``` + +NOTE: older network plugins may instead require the v1beta1 syntax, using an annotation: ```shell {% raw %} @@ -53,49 +50,49 @@ kubectl annotate ns "net.beta.kubernetes.io/network-policy={\"ingres {% endraw %} ``` -See the [NetworkPolicy getting started guide](/docs/getting-started-guides/network-policy/walkthrough) for an example. - ## The `NetworkPolicy` Resource -See the [api-reference](/docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_networkpolicy) for a full definition of the resource. +See the [api-reference](/docs/api-reference/networking/v1/definitions/#_v1_networkpolicy) for a full definition of the resource. -A minimal `NetworkPolicy` might look like this: +An example `NetworkPolicy` might look like this: ```yaml -apiVersion: extensions/v1beta1 +apiVersion: networking/v1 kind: NetworkPolicy metadata: - name: test-network-policy - namespace: default + name: test-network-policy + namespace: default spec: - podSelector: - matchLabels: - role: db - ingress: + podSelector: + matchLabels: + role: db + ingress: - from: - - namespaceSelector: + - namespaceSelector: matchLabels: - project: myproject - - podSelector: + project: myproject + - podSelector: matchLabels: - role: frontend + role: frontend ports: - - protocol: tcp - port: 6379 + - protocol: tcp + port: 6379 ``` *POSTing this to the API server 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 [here](/docs/user-guide/simple-yaml), [here](/docs/user-guide/configuring-containers), and [here](/docs/user-guide/working-with-resources). -__spec__: `NetworkPolicy` [spec](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) has all the information needed to define a network isolation policy in the deployed controller. +__spec__: `NetworkPolicy` [spec](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/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 `ingress` rules in the policy apply. +__podSelector__: Each `NetworkPolicy` includes a `podSelector` which selects the grouping of pods to which the `ingress` rules in the policy apply. The example policy selects pods with the label "role=db". -__ingress__: Each `NetworkPolicy` includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. +__ingress__: Each `NetworkPolicy` includes a list of whitelist `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 either of two sources, the first specified via a `namespaceSelector` and the second specified via a `podSelector`. -This example NetworkPolicy has the following characteristics: +So, the example NetworkPolicy: + +1. allows connections to tcp port 6379 of "role=db" pods in the "default" namespace from any pod in the "default" namespace with the label "role=frontend" +2. allows connections to tcp port 6379 of "role=db" pods in the "default" namespace from any pod in a namespace with the label "project=myproject" + +See the [NetworkPolicy getting started guide](/docs/getting-started-guides/network-policy/walkthrough) for further examples. -1. applies to all pods in the default namespace with the label "role=db" -2. allows tcp/6379 ingress traffic to the "role=db" pods from any pod in the current namespace with the label "role=frontend" (due to the podSelector list element) -3. allows tcp/6379 ingress traffic to the "role=db" pods from any pod in the namespace "myproject" (due to the namespaceSelector list element) diff --git a/docs/tasks/administer-cluster/declare-network-policy.md b/docs/tasks/administer-cluster/declare-network-policy.md index ae0b210a07..9ed10b4cec 100644 --- a/docs/tasks/administer-cluster/declare-network-policy.md +++ b/docs/tasks/administer-cluster/declare-network-policy.md @@ -1,6 +1,7 @@ --- assignees: - caseydavenport +- danwinship title: Declaring Network Policy redirect_from: - "/docs/getting-started-guides/network-policy/walkthrough/" @@ -46,7 +47,7 @@ po/nginx-701339712-o00ef 1/1 Running 0 35s ``` We should be able to access our new nginx Service from other Pods. Let's try to access it from another Pod -in the default namespace. We haven't put any network policy in place, so this should just work. Start a +in the default namespace. We haven't enabled isolation on the namespace, so this should just work. Start a busybox container, and use `wget` to hit the nginx Service: ```console @@ -64,16 +65,28 @@ Let's say we want to limit access to our nginx Service so that only pods with th enable ingress isolation on the `default` Namespace. This will prevent _any_ pods from accessing the nginx Service. ```console -$ kubectl annotate ns default "net.beta.kubernetes.io/network-policy={\"ingress\": {\"isolation\": \"DefaultDeny\"}}" +$ kubectl patch ns default -p '{"spec": {"networkPolicy": {"ingress": {"isolation": "DefaultDeny"}}}}' ``` -With ingress isolation in place, we should no longer be able to access the nginx Service like we were able to before. +With ingress isolation in place, we should no longer be able to access the nginx Service like we were able to before: + +```console +$ kubectl run busybox --rm -ti --image=busybox /bin/sh +Waiting for pod default/busybox-472357175-y0m47 to be running, status is Pending, pod ready: false + +Hit enter for command prompt + +/ # wget --spider --timeout=1 nginx +Connecting to nginx (10.100.0.16:80) +wget: download timed out +/ # +``` Let's now create a `NetworkPolicy` which allows connections from pods with the label `access: true`. ```yaml kind: NetworkPolicy -apiVersion: extensions/v1beta1 +apiVersion: networking/v1 metadata: name: access-nginx spec: @@ -81,19 +94,19 @@ spec: matchLabels: run: nginx ingress: - - from: - - podSelector: - matchLabels: - access: "true" + - from: + - podSelector: + matchLabels: + access: "true" ``` -Use kubectl to create the above nginx-policy.yaml file: +Use kubectl to create a NetworkPolicy from the above nginx-policy.yaml file: ```console $ kubectl create -f nginx-policy.yaml networkpolicy "access-nginx" created ``` -If we attempt to access the nginx Service from a pod without the correct labels, the request will timeout: +If we attempt to access the nginx Service from a pod without the correct labels, the request will still time out: ```console $ kubectl run busybox --rm -ti --image=busybox /bin/sh