diff --git a/_data/concepts.yml b/_data/concepts.yml index 514ed250ed..d8067398a2 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -70,6 +70,7 @@ toc: - docs/concepts/services-networking/dns-pod-service.md - docs/concepts/services-networking/connect-applications-service.md - docs/concepts/services-networking/ingress.md + - docs/concepts/services-networking/networkpolicies.md - title: Configuration section: diff --git a/docs/concepts/services-networking/networkpolicies.md b/docs/concepts/services-networking/networkpolicies.md new file mode 100644 index 0000000000..1c8575d4ab --- /dev/null +++ b/docs/concepts/services-networking/networkpolicies.md @@ -0,0 +1,98 @@ +--- +assignees: +- thockin +- caseydavenport +title: Network Policies +--- + +* TOC +{:toc} + +A network policy is a specification of how selections 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. + +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 + +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. + +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. + +```yaml +kind: Namespace +apiVersion: v1 +metadata: + annotations: + net.beta.kubernetes.io/network-policy: | + { + "ingress": { + "isolation": "DefaultDeny" + } + } +``` + +To configure the annotation via `kubectl`: + +```shell +{% raw %} +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/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. + +A minimal `NetworkPolicy` might look like this: + +```yaml +apiVersion: extensions/v1beta1 +kind: NetworkPolicy +metadata: + name: test-network-policy + namespace: default +spec: + podSelector: + matchLabels: + role: db + ingress: + - from: + - namespaceSelector: + matchLabels: + project: myproject + - 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.* + +__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. + +__podSelector__: Each `NetworkPolicy` includes a `podSelector` which selects the grouping of pods to which the `ingress` rules in the policy apply. + +__ingress__: Each `NetworkPolicy` includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. + +This example NetworkPolicy has the following characteristics: + +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/user-guide/networkpolicies.md b/docs/user-guide/networkpolicies.md index 1c8575d4ab..ab5ff86c86 100644 --- a/docs/user-guide/networkpolicies.md +++ b/docs/user-guide/networkpolicies.md @@ -5,94 +5,6 @@ assignees: title: Network Policies --- -* TOC -{:toc} +{% include user-guide-content-moved.md %} -A network policy is a specification of how selections 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. - -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 - -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. - -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. - -```yaml -kind: Namespace -apiVersion: v1 -metadata: - annotations: - net.beta.kubernetes.io/network-policy: | - { - "ingress": { - "isolation": "DefaultDeny" - } - } -``` - -To configure the annotation via `kubectl`: - -```shell -{% raw %} -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/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. - -A minimal `NetworkPolicy` might look like this: - -```yaml -apiVersion: extensions/v1beta1 -kind: NetworkPolicy -metadata: - name: test-network-policy - namespace: default -spec: - podSelector: - matchLabels: - role: db - ingress: - - from: - - namespaceSelector: - matchLabels: - project: myproject - - 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.* - -__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. - -__podSelector__: Each `NetworkPolicy` includes a `podSelector` which selects the grouping of pods to which the `ingress` rules in the policy apply. - -__ingress__: Each `NetworkPolicy` includes a list of whitelist `ingress` rules. Each rule allows traffic which matches both the `from` and `ports` sections. - -This example NetworkPolicy has the following characteristics: - -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) +[Network Policies](/docs/concepts/services-networking/networkpolicies/)