From 5ce89f84f33d32a7ff0c3f83c668053bdcf33b29 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Tue, 6 Sep 2016 18:53:53 -0700 Subject: [PATCH] Getting started guide which walks through using NetworkPolicy --- _data/guides.yml | 2 + .../calico-network-policy.md | 131 ++++++++++++++++++ docs/user-guide/networkpolicies.md | 3 + 3 files changed, 136 insertions(+) create mode 100644 docs/getting-started-guides/calico-network-policy.md diff --git a/_data/guides.yml b/_data/guides.yml index 3f076b7af9..47039275ca 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -60,6 +60,8 @@ toc: path: /docs/user-guide/working-with-resources/ - title: Garbage collection path: /docs/user-guide/garbage-collector/ + - title: Using Calico NetworkPolicy + path: /docs/getting-started-guides/calico-network-policy/ - title: Batch Jobs section: diff --git a/docs/getting-started-guides/calico-network-policy.md b/docs/getting-started-guides/calico-network-policy.md new file mode 100644 index 0000000000..8617cbe13f --- /dev/null +++ b/docs/getting-started-guides/calico-network-policy.md @@ -0,0 +1,131 @@ +--- +assignees: +- caseydavenport + +--- + +Kubernetes can be used to declare network policies which govern how Pods can communicate with each other. This document helps you get started using the Kubernetes [NetworkPolicy API](/docs/user-guide/networkpolicies), and provides a demonstration thereof. + +In this article we assume that that a Kubernetes cluster has been created with network policy support. It's easy to create such a cluster using the [GCE guide](/docs/getting-started-guides/gce), setting the `NETWORK_POLICY_PROVIDER=calico` environment variable. + +e.g + +```shell +export NETWORK_POLICY_PROVIDER=calico +curl -sS https://get.k8s.io | bash +``` + +## Using NetworkPolicy + +Once your cluster is started, you should see a collection of pods running in the `kube-system` Namespace that support Kubernetes NetworkPolicy. + +```console +$ kubectl get pods --namespace=kube-system +NAME READY STATUS RESTARTS AGE +calico-node-kubernetes-minion-group-jck6 1/1 Running 0 46m +calico-node-kubernetes-minion-group-k9jy 1/1 Running 0 46m +calico-node-kubernetes-minion-group-szgr 1/1 Running 0 46m +calico-policy-controller-65rw1 1/1 Running 0 46m +... +``` + +There are two main components to be aware of: + +- One `calico-node` Pod runs on each node in your cluster, and enforces network policy on the traffic to/from Pods on that machine by configuring iptables. +- The `calico-policy-controller` Pod reads policy and label information from the Kubernetes API and configures Calico appropriately. + +To explain how Kubernetes network policy works let's start off by creating an `nginx` Deployment and expose it via a Service. + +```console +$ kubectl run nginx --image=nginx --replicas=2 +deployment "nginx" created +$ kubectl expose deployment nginx --port=80 +service "nginx" exposed +``` + +This will run two nginx Pods in the default Namespace, and expose them through a Service called `nginx`. + +```console +$ kubectl get svc,pod +NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE +kubernetes 10.100.0.1 443/TCP 46m +nginx 10.100.0.16 80/TCP 33s +NAME READY STATUS RESTARTS AGE +nginx-701339712-e0qfq 1/1 Running 0 35s +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 +busybox container, and use `wget` to hit the nginx Service: + +```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 -s --timeout=1 nginx +Connecting to nginx (10.100.0.16:80) +/ # +``` + +Let's say we want to limit access to our nginx Service so that only pods with the label `access: true` can query it. First, we'll +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\"}}" +``` + +With ingress isolation in place, we should no longer be able to access the nginx Service like we were able to before. + +Let's now create a `NetworkPolicy` which allows connections from pods with the label `access: true`. + +```yaml +kind: NetworkPolicy +apiVersion: extensions/v1beta1 +metadata: + name: access-nginx +spec: + podSelector: + matchLabels: + run: nginx + ingress: + - from: + - podSelector: + matchLabels: + access: "true" +``` + +Use kubectl to create 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: + +```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 -s --timeout=1 nginx +Connecting to nginx (10.100.0.16:80) +wget: download timed out +/ # +``` + +However, if we create a Pod with the correct labels, the request will be allowed: + +```console +$ kubectl run busybox --rm -ti --labels="access=true" --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 -s --timeout=1 nginx +Connecting to nginx (10.100.0.16:80) +/ # +``` diff --git a/docs/user-guide/networkpolicies.md b/docs/user-guide/networkpolicies.md index eb4bbe1b74..982d3bbbac 100644 --- a/docs/user-guide/networkpolicies.md +++ b/docs/user-guide/networkpolicies.md @@ -1,6 +1,7 @@ --- assignees: - thockin +- caseydavenport --- @@ -47,6 +48,8 @@ To configure the annotation via `kubectl`: kubectl annotate ns "net.beta.kubernetes.io/network-policy={\"ingress\": {\"isolation\": \"DefaultDeny\"}}" {% endraw %}``` +See the [NetworkPolicy getting started guide](/docs/getting-started-guides/network-policy) 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.