From 026d37e6ae301b51a57028ce1398cce84f32e561 Mon Sep 17 00:00:00 2001 From: Joe Stringer Date: Wed, 17 Jun 2020 21:01:38 -0700 Subject: [PATCH 1/3] docs: Reorder/expand L7 visibility title This just makes the index a bit more consistent and frames the ordering nicely in a progressive manner from the high level through the policy examples including visibility, then to the extra information like endpoint lifecycle and ending with troubleshooting which makes troubleshooting easier to see at the end. Signed-off-by: Joe Stringer --- Documentation/policy/index.rst | 2 +- Documentation/policy/visibility.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/policy/index.rst b/Documentation/policy/index.rst index 43b27f8038d4..e61fa0048ff6 100644 --- a/Documentation/policy/index.rst +++ b/Documentation/policy/index.rst @@ -29,6 +29,6 @@ mechanisms: intro language + visibility lifecycle troubleshooting - visibility diff --git a/Documentation/policy/visibility.rst b/Documentation/policy/visibility.rst index fae2e5ba1e7a..55cf5318105e 100644 --- a/Documentation/policy/visibility.rst +++ b/Documentation/policy/visibility.rst @@ -6,12 +6,12 @@ .. _proxy_visibility: -********************** -L7 Protocol Visibility -********************** +*************************** +Layer 7 Protocol Visibility +*************************** While :ref:`monitor` provides introspection into datapath state, by default it -will only provide visibility into L3/L4 packet events. If :ref:`l7_policy` is +will only provide visibility into L3/L4 packet events. If :ref:`l7_policy` are configured, one can get visibility into L7 protocols, but this requires the full policy for each selected endpoint to be written. To get more visibility into the application without configuring a full policy, Cilium provides a means of From 32bcc40f701869484d67b87ff2b7ddae4815ab96 Mon Sep 17 00:00:00 2001 From: Joe Stringer Date: Wed, 17 Jun 2020 21:08:57 -0700 Subject: [PATCH 2/3] docs: Shift k8s policy constructs to dedicated page Signed-off-by: Joe Stringer --- Documentation/policy/index.rst | 1 + Documentation/policy/kubernetes.rst | 204 ++++++++++++++++++++++++++++ Documentation/policy/language.rst | 199 --------------------------- 3 files changed, 205 insertions(+), 199 deletions(-) create mode 100644 Documentation/policy/kubernetes.rst diff --git a/Documentation/policy/index.rst b/Documentation/policy/index.rst index e61fa0048ff6..16c4dfe25f65 100644 --- a/Documentation/policy/index.rst +++ b/Documentation/policy/index.rst @@ -30,5 +30,6 @@ mechanisms: intro language visibility + kubernetes lifecycle troubleshooting diff --git a/Documentation/policy/kubernetes.rst b/Documentation/policy/kubernetes.rst new file mode 100644 index 000000000000..f1bf12fa2c17 --- /dev/null +++ b/Documentation/policy/kubernetes.rst @@ -0,0 +1,204 @@ +.. only:: not (epub or latex or html) + + WARNING: You are looking at unreleased Cilium documentation. + Please use the official rendered version released here: + https://docs.cilium.io + +Using Kubernetes constructs in policy +===================================== + +This section covers Kubernetes specific network policy aspects. + +.. _k8s_namespaces: + +Namespaces +---------- + +`Namespaces `_ +are used to create virtual clusters within a Kubernetes cluster. All Kubernetes objects +including NetworkPolicy and CiliumNetworkPolicy belong to a particular +namespace. Depending on how a policy is being defined and created, Kubernetes +namespaces are automatically being taken into account: + +* Network policies created and imported as `CiliumNetworkPolicy` CRD and + `NetworkPolicy` apply within the namespace, i.e. the policy only applies + to pods within that namespace. It is however possible to grant access to and + from pods in other namespaces as described below. + +* Network policies imported directly via the :ref:`api_ref` apply to all + namespaces unless a namespace selector is specified as described below. + +.. note:: While specification of the namespace via the label + ``k8s:io.kubernetes.pod.namespace`` in the ``fromEndpoints`` and + ``toEndpoints`` fields is deliberately supported. Specification of the + namespace in the ``endpointSelector`` is prohibited as it would + violate the namespace isolation principle of Kubernetes. The + ``endpointSelector`` always applies to pods of the namespace which is + associated with the CiliumNetworkPolicy resource itself. + +Example: Enforce namespace boundaries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This example demonstrates how to enforce Kubernetes namespace-based boundaries +for the namespaces ``ns1`` and ``ns2`` by enabling default-deny on all pods of +either namespace and then allowing communication from all pods within the same +namespace. + +.. note:: The example locks down ingress of the pods in ``ns1`` and ``ns2``. + This means that the pods can still communicate egress to anywhere + unless the destination is in either ``ns1`` or ``ns2`` in which case + both source and destination have to be in the same namespace. In + order to enforce namespace boundaries at egress, the same example can + be used by specifying the rules at egress in addition to ingress. + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.yaml + .. group-tab:: JSON + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.json + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.json + +Example: Expose pods across namespaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example exposes all pods with the label ``name=leia`` in the +namespace ``ns1`` to all pods with the label ``name=luke`` in the namespace +``ns2``. + +Refer to the :git-tree:`example YAML files ` +for a fully functional example including pods deployed to different namespaces. + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.yaml + .. group-tab:: JSON + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.json + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.json + +Example: Allow egress to kube-dns in kube-system namespace +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following example allows all pods in the namespace in which the policy is +created to communicate with kube-dns on port 53/UDP in the ``kube-system`` +namespace. + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.yaml + .. group-tab:: JSON + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.json + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.json + + +ServiceAccounts +---------------- + +Kubernetes `Service Accounts +`_ are used +to associate an identity to a pod or process managed by Kubernetes and grant +identities access to Kubernetes resources and secrets. Cilium supports the +specification of network security policies based on the service account +identity of a pod. + +The service account of a pod is either defined via the `service account +admission controller +`_ +or can be directly specified in the Pod, Deployment, ReplicationController +resource like this: + +.. code:: bash + + apiVersion: v1 + kind: Pod + metadata: + name: my-pod + spec: + serviceAccountName: leia + ... + +Example +~~~~~~~ + +The following example grants any pod running under the service account of +"luke" to issue a ``HTTP GET /public`` request on TCP port 80 to all pods +running associated to the service account of "leia". + +Refer to the :git-tree:`example YAML files ` +for a fully functional example including deployment and service account +resources. + + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.yaml + .. group-tab:: JSON + + .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.json + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.json + +Multi-Cluster +------------- + +When operating multiple cluster with cluster mesh, the cluster name is exposed +via the label ``io.cilium.k8s.policy.cluster`` and can be used to restrict +policies to a particular cluster. + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/clustermesh/cross-cluster-policy.yaml + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/clustermesh/cross-cluster-policy.yaml + +Clusterwide Policies +-------------------- + +`CiliumNetworkPolicy` only allows to bind a policy restricted to a particular namespace. There can be situations +where one wants to have a cluster-scoped effect of the policy, which can be done using Cilium's +`CiliumClusterwideNetworkPolicy` Kubernetes custom resource. The specification of the policy is same as that +of `CiliumNetworkPolicy` except that it is not namespaced. + +In the cluster, this policy will allow ingress traffic from pods matching the label ``name=luke`` from any +namespace to pods matching the labels ``name=leia`` in any namespace. + +.. only:: html + + .. tabs:: + .. group-tab:: k8s YAML + + .. literalinclude:: ../../examples/policies/kubernetes/clusterwide/clusterscope-policy.yaml + +.. only:: epub or latex + + .. literalinclude:: ../../examples/policies/kubernetes/clusterwide/clusterscope-policy.yaml diff --git a/Documentation/policy/language.rst b/Documentation/policy/language.rst index 4b0154be2ce0..2de255f752bb 100644 --- a/Documentation/policy/language.rst +++ b/Documentation/policy/language.rst @@ -1056,202 +1056,3 @@ A more pod-specific solution is to configure ``ndots`` appropriately for each Pod, via ``dnsConfig``, so that the search list is not used for DNS lookups that do not need it. See the `Kubernetes documentation `_ for instructions. - -Kubernetes -========== - -This section covers Kubernetes specific network policy aspects. - -.. _k8s_namespaces: - -Namespaces ----------- - -`Namespaces `_ -are used to create virtual clusters within a Kubernetes cluster. All Kubernetes objects -including NetworkPolicy and CiliumNetworkPolicy belong to a particular -namespace. Depending on how a policy is being defined and created, Kubernetes -namespaces are automatically being taken into account: - -* Network policies created and imported as `CiliumNetworkPolicy` CRD and - `NetworkPolicy` apply within the namespace, i.e. the policy only applies - to pods within that namespace. It is however possible to grant access to and - from pods in other namespaces as described below. - -* Network policies imported directly via the :ref:`api_ref` apply to all - namespaces unless a namespace selector is specified as described below. - -.. note:: While specification of the namespace via the label - ``k8s:io.kubernetes.pod.namespace`` in the ``fromEndpoints`` and - ``toEndpoints`` fields is deliberately supported. Specification of the - namespace in the ``endpointSelector`` is prohibited as it would - violate the namespace isolation principle of Kubernetes. The - ``endpointSelector`` always applies to pods of the namespace which is - associated with the CiliumNetworkPolicy resource itself. - -Example: Enforce namespace boundaries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This example demonstrates how to enforce Kubernetes namespace-based boundaries -for the namespaces ``ns1`` and ``ns2`` by enabling default-deny on all pods of -either namespace and then allowing communication from all pods within the same -namespace. - -.. note:: The example locks down ingress of the pods in ``ns1`` and ``ns2``. - This means that the pods can still communicate egress to anywhere - unless the destination is in either ``ns1`` or ``ns2`` in which case - both source and destination have to be in the same namespace. In - order to enforce namespace boundaries at egress, the same example can - be used by specifying the rules at egress in addition to ingress. - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.yaml - .. group-tab:: JSON - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.json - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/isolate-namespaces.json - -Example: Expose pods across namespaces -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following example exposes all pods with the label ``name=leia`` in the -namespace ``ns1`` to all pods with the label ``name=luke`` in the namespace -``ns2``. - -Refer to the :git-tree:`example YAML files ` -for a fully functional example including pods deployed to different namespaces. - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.yaml - .. group-tab:: JSON - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.json - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/namespace-policy.json - -Example: Allow egress to kube-dns in kube-system namespace -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following example allows all pods in the namespace in which the policy is -created to communicate with kube-dns on port 53/UDP in the ``kube-system`` -namespace. - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.yaml - .. group-tab:: JSON - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.json - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/namespace/kubedns-policy.json - - -ServiceAccounts ----------------- - -Kubernetes `Service Accounts -`_ are used -to associate an identity to a pod or process managed by Kubernetes and grant -identities access to Kubernetes resources and secrets. Cilium supports the -specification of network security policies based on the service account -identity of a pod. - -The service account of a pod is either defined via the `service account -admission controller -`_ -or can be directly specified in the Pod, Deployment, ReplicationController -resource like this: - -.. code:: bash - - apiVersion: v1 - kind: Pod - metadata: - name: my-pod - spec: - serviceAccountName: leia - ... - -Example -~~~~~~~ - -The following example grants any pod running under the service account of -"luke" to issue a ``HTTP GET /public`` request on TCP port 80 to all pods -running associated to the service account of "leia". - -Refer to the :git-tree:`example YAML files ` -for a fully functional example including deployment and service account -resources. - - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.yaml - .. group-tab:: JSON - - .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.json - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/serviceaccount/serviceaccount-policy.json - -Multi-Cluster -------------- - -When operating multiple cluster with cluster mesh, the cluster name is exposed -via the label ``io.cilium.k8s.policy.cluster`` and can be used to restrict -policies to a particular cluster. - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/clustermesh/cross-cluster-policy.yaml - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/clustermesh/cross-cluster-policy.yaml - -Clusterwide Policies --------------------- - -`CiliumNetworkPolicy` only allows to bind a policy restricted to a particular namespace. There can be situations -where one wants to have a cluster-scoped effect of the policy, which can be done using Cilium's -`CiliumClusterwideNetworkPolicy` Kubernetes custom resource. The specification of the policy is same as that -of `CiliumNetworkPolicy` except that it is not namespaced. - -In the cluster, this policy will allow ingress traffic from pods matching the label ``name=luke`` from any -namespace to pods matching the labels ``name=leia`` in any namespace. - -.. only:: html - - .. tabs:: - .. group-tab:: k8s YAML - - .. literalinclude:: ../../examples/policies/kubernetes/clusterwide/clusterscope-policy.yaml - -.. only:: epub or latex - - .. literalinclude:: ../../examples/policies/kubernetes/clusterwide/clusterscope-policy.yaml From e430e9d38aa04b6c987ff70f99b60d024f903e3b Mon Sep 17 00:00:00 2001 From: Joe Stringer Date: Wed, 17 Jun 2020 21:16:35 -0700 Subject: [PATCH 3/3] docs: Expand policy to describe NodeSelector Signed-off-by: Joe Stringer --- Documentation/policy/intro.rst | 35 +++++++++++++++++++++++------ Documentation/spelling_wordlist.txt | 1 + 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/Documentation/policy/intro.rst b/Documentation/policy/intro.rst index 02141ee37cdd..63d83f22c9d7 100644 --- a/Documentation/policy/intro.rst +++ b/Documentation/policy/intro.rst @@ -83,8 +83,18 @@ provided. If both ingress and egress are omitted, the rule has no effect. type Rule struct { // EndpointSelector selects all endpoints which should be subject to - // this rule. Cannot be empty. - EndpointSelector EndpointSelector `json:"endpointSelector"` + // this rule. EndpointSelector and NodeSelector cannot be both empty and + // are mutually exclusive. + // + // +optional + EndpointSelector EndpointSelector `json:"endpointSelector,omitempty"` + + // NodeSelector selects all nodes which should be subject to this rule. + // EndpointSelector and NodeSelector cannot be both empty and are mutually + // exclusive. + // + // +optional + NodeSelector EndpointSelector `json:"nodeSelector,omitempty"` // Ingress is a list of IngressRule which are enforced at ingress. // If omitted or empty, this rule does not apply at ingress. @@ -116,10 +126,11 @@ provided. If both ingress and egress are omitted, the rule has no effect. ---- -endpointSelector - Selects the endpoints which the policy rules apply to. The policy rules - will be applied to all endpoints which match the labels specified in the - `endpointSelector`. See the `LabelSelector` section for additional details. +endpointSelector / nodeSelector + Selects the endpoints or nodes which the policy rules apply to. The policy + rules will be applied to all endpoints which match the labels specified in + the selector. See the `LabelSelector` and :ref:`NodeSelector` sections for + additional details. ingress List of rules which must apply at ingress of the endpoint, i.e. to all @@ -150,4 +161,14 @@ Endpoint Selector The Endpoint Selector is based on the `Kubernetes LabelSelector `_. It is called Endpoint Selector because it only applies to labels associated -with `endpoints`. +with an `endpoints`. + +.. _NodeSelector: + +Node Selector +------------- + +The Node Selector is also based on the `LabelSelector`, however rather than +matching on labels associated with an `endpoints`, it instead applies to labels +associated with a node in the cluster. Node Selectors can only be used in +`CiliumClusterwideNetworkPolicy`. diff --git a/Documentation/spelling_wordlist.txt b/Documentation/spelling_wordlist.txt index 0f2d1cf88a2d..2007a92dce66 100644 --- a/Documentation/spelling_wordlist.txt +++ b/Documentation/spelling_wordlist.txt @@ -505,6 +505,7 @@ nfsd nftables ng nginx +nodeSelector nodeX nodegroup observability