From c1206d7b5398eca1c3b036deff0adee29403a708 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Sat, 4 Jun 2016 10:23:57 -0700 Subject: [PATCH 1/3] First commit of network policy user guide --- docs/user-guide/networkpolicies.md | 82 ++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/user-guide/networkpolicies.md diff --git a/docs/user-guide/networkpolicies.md b/docs/user-guide/networkpolicies.md new file mode 100644 index 0000000000..06824c692c --- /dev/null +++ b/docs/user-guide/networkpolicies.md @@ -0,0 +1,82 @@ +--- +--- + +* TOC +{:toc} + +## What is a _Network Policy_? + +A Network Policy is a specification of how groupings 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 ingress isolation policy for a given namespace. + +## Prerequisites +Before you start using the NetworkPolicy resource, there are a few things to understand. The NetworkPolicy resource is a beta resource and is +not available in any Kubernetes release prior to 1.3. + +You must enable the `extensions/v1beta/networkpolicies` runtime config in your apiserver to enable this resource. + +You must also be using a networking solution which supports Network Policy - simply creating the +resource without a controller to implement it will have no effect. + +## Configuring Namespace Isolation Policy +Ingress isolation can be configured on a per-namespace basis. Once ingress isolation is configured on a namespace it will be applied to all pods in that namespace. + +Currently the following ingress isolation types are supported: + +- _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" + } + } +``` + +To configure the annotation via `kubectl`: + +``` +kubectl annotate ns "net.beta.kubernetes.io/networkpolicy={\"ingress\": {\"isolation\": \"DefaultDeny\"}}" +``` + +## The NetworkPolicy Resource +A minimal `NetworkPolicy` might look like this: + +```yaml +01. apiVersion: extensions/v1beta1 +02. kind: NetworkPolicy +03. metadata: +04. name: test-network-policy +05. spec: +06. podSelector: +07. matchLabels: +08. role: db +09. ingress: +10. - from: +11. podSelector: +12. matchLabels: +13. role: frontend +14. ports: +15. - protocol: tcp +16. port: 6379 +``` + +*POSTing this to the API server will have no effect unless your chosen networking solution supports network policy.* + +__Lines 1-4__: 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). + +__Lines 5-9__: NetworkPolicy [spec](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) has all the information needed to configure a loadbalancer or proxy server. Most importantly, it contains a list of rules matched against all incoming requests. Currently the Ingress resource only supports http rules. + +__Lines 6-8__: Each NetworkPolicy includes a `podSelector` which selects the grouping of pods to which the `ingress` rules in the policy apply. + +__Lines 9-16__: Each NetworkPolicy includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. + +__Complete Specification__: See the [api-reference](https://kubernetes.github.io/docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_networkpolicy) for a full definition of the resource. From cb6f85b484f88308300a191c93bdaa857beb96c7 Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Mon, 27 Jun 2016 15:58:08 -0700 Subject: [PATCH 2/3] Code review comments --- _data/reference.yml | 2 + docs/user-guide/networkpolicies.md | 68 +++++++++++++++--------------- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/_data/reference.yml b/_data/reference.yml index e2439cc78b..f337e158b1 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -226,6 +226,8 @@ toc: path: /docs/user-guide/replicasets/ - title: Pet Sets path: /docs/user-guide/petset/ + - title: NetworkPolicy Resources + path: /docs/user-guide/networkpolicies/ - title: Kubernetes Design Docs section: diff --git a/docs/user-guide/networkpolicies.md b/docs/user-guide/networkpolicies.md index 06824c692c..7050b9df81 100644 --- a/docs/user-guide/networkpolicies.md +++ b/docs/user-guide/networkpolicies.md @@ -4,27 +4,24 @@ * TOC {:toc} -## What is a _Network Policy_? +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 groupings 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 ingress isolation policy for a given namespace. +`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 -Before you start using the NetworkPolicy resource, there are a few things to understand. The NetworkPolicy resource is a beta resource and is -not available in any Kubernetes release prior to 1.3. You must enable the `extensions/v1beta/networkpolicies` runtime config in your apiserver to enable this resource. -You must also be using a networking solution which supports Network Policy - simply creating the +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 Policy -Ingress isolation can be configured on a per-namespace basis. Once ingress isolation is configured on a namespace it will be applied to all pods in that namespace. -Currently the following ingress isolation types are supported: +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. -- _DefaultDeny_: Pods in the namespace will be inaccessible from any source except the pod's local node. +The following ingress isolation types being supported: + +- `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. @@ -43,40 +40,41 @@ metadata: To configure the annotation via `kubectl`: -``` +```shell{% raw %} kubectl annotate ns "net.beta.kubernetes.io/networkpolicy={\"ingress\": {\"isolation\": \"DefaultDeny\"}}" -``` +{% endraw %}``` + +## The `NetworkPolicy` Resource + +See the [api-reference](docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_networkpolicy) for a full definition of the resource. -## The NetworkPolicy Resource A minimal `NetworkPolicy` might look like this: ```yaml -01. apiVersion: extensions/v1beta1 -02. kind: NetworkPolicy -03. metadata: -04. name: test-network-policy -05. spec: -06. podSelector: -07. matchLabels: -08. role: db -09. ingress: -10. - from: -11. podSelector: -12. matchLabels: -13. role: frontend -14. ports: -15. - protocol: tcp -16. port: 6379 +apiVersion: extensions/v1beta1 +kind: NetworkPolicy +metadata: + name: test-network-policy +spec: + podSelector: + matchLabels: + role: db + ingress: + - from: + podSelector: + matchLabels: + role: frontend + ports: + - protocol: tcp + port: 6379 ``` *POSTing this to the API server will have no effect unless your chosen networking solution supports network policy.* -__Lines 1-4__: 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). +__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). -__Lines 5-9__: NetworkPolicy [spec](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status) has all the information needed to configure a loadbalancer or proxy server. Most importantly, it contains a list of rules matched against all incoming requests. Currently the Ingress resource only supports http rules. +__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. -__Lines 6-8__: 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. -__Lines 9-16__: Each NetworkPolicy includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. - -__Complete Specification__: See the [api-reference](https://kubernetes.github.io/docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_networkpolicy) for a full definition of the resource. +__ingress__: Each `NetworkPolicy` includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. From ad53cd7423f5f98f1ee3a4fd4f404b58345cd6bf Mon Sep 17 00:00:00 2001 From: Casey Davenport Date: Tue, 28 Jun 2016 13:23:30 -0700 Subject: [PATCH 3/3] Fix title --- _data/reference.yml | 2 +- docs/user-guide/networkpolicies.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_data/reference.yml b/_data/reference.yml index f337e158b1..a11214565a 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -226,7 +226,7 @@ toc: path: /docs/user-guide/replicasets/ - title: Pet Sets path: /docs/user-guide/petset/ - - title: NetworkPolicy Resources + - title: Network Policies path: /docs/user-guide/networkpolicies/ - title: Kubernetes Design Docs diff --git a/docs/user-guide/networkpolicies.md b/docs/user-guide/networkpolicies.md index 7050b9df81..e550657df6 100644 --- a/docs/user-guide/networkpolicies.md +++ b/docs/user-guide/networkpolicies.md @@ -46,7 +46,7 @@ kubectl annotate ns "net.beta.kubernetes.io/networkpolicy={\"ingress ## 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/extensions/v1beta1/definitions/#_v1beta1_networkpolicy) for a full definition of the resource. A minimal `NetworkPolicy` might look like this: