github.com/cilium/cilium@v1.16.2/Documentation/security/host-firewall.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _host_firewall:
     8  
     9  *************
    10  Host Firewall
    11  *************
    12  
    13  This document serves as an introduction to Cilium's host firewall, to enforce
    14  security policies for Kubernetes nodes.
    15  
    16  .. admonition:: Video
    17    :class: attention
    18  
    19    You can also watch a video of Cilium's host firewall in action on
    20    `eCHO Episode 40: Cilium Host Firewall <https://www.youtube.com/watch?v=GLLLcz398K0&t=288s>`__.
    21  
    22  Enable the Host Firewall in Cilium
    23  ==================================
    24  
    25  .. include:: /installation/k8s-install-download-release.rst
    26  
    27  Deploy Cilium release via Helm:
    28  
    29  .. parsed-literal::
    30  
    31      helm install cilium |CHART_RELEASE|        \\
    32        --namespace kube-system                  \\
    33        --set hostFirewall.enabled=true          \\
    34        --set devices='{ethX,ethY}'
    35  
    36  The ``devices`` flag refers to the network devices Cilium is configured on,
    37  such as ``eth0``. If you omit this option, Cilium auto-detects what interfaces
    38  the host firewall applies to.
    39  
    40  At this point, the Cilium-managed nodes are ready to enforce network policies.
    41  
    42  
    43  Attach a Label to the Node
    44  ==========================
    45  
    46  In this guide, host policies only apply to nodes with the label
    47  ``node-access=ssh``. Therefore, you first need to attach this label to a node
    48  in the cluster:
    49  
    50  .. code-block:: shell-session
    51  
    52      $ export NODE_NAME=k8s1
    53      $ kubectl label node $NODE_NAME node-access=ssh
    54      node/k8s1 labeled
    55  
    56  
    57  Enable Policy Audit Mode for the Host Endpoint
    58  ==============================================
    59  
    60  `HostPolicies` enforce access control over connectivity to and from nodes.
    61  Particular care must be taken to ensure that when host policies are imported,
    62  Cilium does not block access to the nodes or break the cluster's normal
    63  behavior (for example by blocking communication with ``kube-apiserver``).
    64  
    65  To avoid such issues, switch the host firewall in audit mode and validate the
    66  impact of host policies before enforcing them.
    67  
    68  .. warning::
    69  
    70     When Policy Audit Mode is enabled, no network policy is enforced so this
    71     setting is not recommended for production deployment.
    72  
    73  Enable and check status for the Policy Audit Mode on the host endpoint for a
    74  given node with the following commands:
    75  
    76  .. code-block:: shell-session
    77  
    78      $ CILIUM_NAMESPACE=kube-system
    79      $ CILIUM_POD_NAME=$(kubectl -n $CILIUM_NAMESPACE get pods -l "k8s-app=cilium" -o jsonpath="{.items[?(@.spec.nodeName=='$NODE_NAME')].metadata.name}")
    80      $ alias kexec="kubectl -n $CILIUM_NAMESPACE exec $CILIUM_POD_NAME --"
    81      $ HOST_EP_ID=$(kexec cilium-dbg endpoint list -o jsonpath='{[?(@.status.identity.id==1)].id}')
    82      $ kexec cilium-dbg endpoint config $HOST_EP_ID PolicyAuditMode=Enabled
    83      Endpoint 3353 configuration updated successfully
    84      $ kexec cilium-dbg endpoint config $HOST_EP_ID | grep PolicyAuditMode
    85      PolicyAuditMode        : Enabled
    86  
    87  
    88  Apply a Host Network Policy
    89  ===========================
    90  
    91  :ref:`HostPolicies` match on node labels using a :ref:`NodeSelector` to
    92  identify the nodes to which the policies applies. They apply only to the host
    93  namespace, including host-networking pods. They don't apply to communications
    94  between pods or between pods and the outside of the cluster, except if those
    95  pods are host-networking pods.
    96  
    97  The following policy applies to all nodes with the ``node-access=ssh`` label.
    98  It allows communications from outside the cluster only for TCP/22 and for ICMP
    99  (ping) echo requests. All communications from the cluster to the hosts are
   100  allowed.
   101  
   102  .. literalinclude:: ../../examples/policies/host/demo-host-policy.yaml
   103  
   104  To apply this policy, run:
   105  
   106  .. parsed-literal::
   107  
   108      $ kubectl create -f \ |SCM_WEB|\/examples/policies/host/demo-host-policy.yaml
   109      ciliumclusterwidenetworkpolicy.cilium.io/demo-host-policy created
   110  
   111  The host is represented as a special endpoint, with label ``reserved:host``, in
   112  the output of command ``cilium-dbg endpoint list``. Use this command to inspect
   113  the status of host policies:
   114  
   115  .. code-block:: shell-session
   116  
   117      $ kexec cilium-dbg endpoint list
   118      ENDPOINT   POLICY (ingress)   POLICY (egress)   IDENTITY   LABELS (source:key[=value])                       IPv6                 IPv4           STATUS
   119                 ENFORCEMENT        ENFORCEMENT
   120      266        Disabled           Disabled          104        k8s:io.cilium.k8s.policy.cluster=default          f00d::a0b:0:0:ef4e   10.16.172.63   ready
   121                                                                 k8s:io.cilium.k8s.policy.serviceaccount=coredns
   122                                                                 k8s:io.kubernetes.pod.namespace=kube-system
   123                                                                 k8s:k8s-app=kube-dns
   124      1687       Disabled (Audit)   Disabled          1          k8s:node-access=ssh                                                                   ready
   125                                                                 reserved:host
   126      3362       Disabled           Disabled          4          reserved:health                                   f00d::a0b:0:0:49cf   10.16.87.66    ready
   127  
   128  In this example, one can observe that policy enforcement on the host endpoint
   129  is in audit mode for ingress traffic, and disabled for egress traffic.
   130  
   131  
   132  Adjust the Host Policy to Your Environment
   133  ==========================================
   134  
   135  As long as the host endpoint runs in audit mode, communications disallowed by
   136  the policy are not dropped. Nevertheless, they are reported by ``cilium-dbg
   137  monitor``, as ``action audit``. With these reports, the audit mode allows you
   138  to adjust the host policy to your environment in order to avoid unexpected
   139  connection breakages.
   140  
   141  .. code-block:: shell-session
   142  
   143      $ kexec cilium-dbg monitor -t policy-verdict --related-to $HOST_EP_ID
   144      Policy verdict log: flow 0x0 local EP ID 1687, remote ID 6, proto 1, ingress, action allow, match L3-Only, 192.168.60.12 -> 192.168.60.11 EchoRequest
   145      Policy verdict log: flow 0x0 local EP ID 1687, remote ID 6, proto 6, ingress, action allow, match L3-Only, 192.168.60.12:37278 -> 192.168.60.11:2379 tcp SYN
   146      Policy verdict log: flow 0x0 local EP ID 1687, remote ID 2, proto 6, ingress, action audit, match none, 10.0.2.2:47500 -> 10.0.2.15:6443 tcp SYN
   147  
   148  For details on deriving the network policies from the output of ``cilium
   149  monitor``, refer to `observe_policy_verdicts` and `create_network_policy` in
   150  the `policy_verdicts` guide.
   151  
   152  Note that `Entities based` rules are convenient when combined with host
   153  policies, for example to allow communication to entire classes of destinations,
   154  such as all remotes nodes (``remote-node``) or the entire cluster
   155  (``cluster``).
   156  
   157  .. warning::
   158  
   159      Make sure that none of the communications required to access the cluster or
   160      for the cluster to work properly are denied. Ensure they all appear as
   161      ``action allow`` before disabling the audit mode.
   162  
   163  .. _disable_policy_audit_mode:
   164  
   165  Disable Policy Audit Mode
   166  =========================
   167  
   168  Once you are confident all required communications to the host from outside the
   169  cluster are allowed, disable the policy audit mode to enforce the host policy:
   170  
   171  .. code-block:: shell-session
   172  
   173      $ kexec cilium-dbg endpoint config $HOST_EP_ID PolicyAuditMode=Disabled
   174      Endpoint 3353 configuration updated successfully
   175  
   176  Ingress host policies should now appear as enforced:
   177  
   178  .. code-block:: shell-session
   179  
   180      $ kexec cilium-dbg endpoint list
   181      ENDPOINT   POLICY (ingress)   POLICY (egress)   IDENTITY   LABELS (source:key[=value])                       IPv6                 IPv4           STATUS
   182                 ENFORCEMENT        ENFORCEMENT
   183      266        Disabled           Disabled          104        k8s:io.cilium.k8s.policy.cluster=default          f00d::a0b:0:0:ef4e   10.16.172.63   ready
   184                                                                 k8s:io.cilium.k8s.policy.serviceaccount=coredns
   185                                                                 k8s:io.kubernetes.pod.namespace=kube-system
   186                                                                 k8s:k8s-app=kube-dns
   187      1687       Enabled            Disabled          1          k8s:node-access=ssh                                                                   ready
   188                                                                 reserved:host
   189      3362       Disabled           Disabled          4          reserved:health                                   f00d::a0b:0:0:49cf   10.16.87.66    ready
   190  
   191  
   192  Communications that are not explicitly allowed by the host policy are now
   193  dropped:
   194  
   195  .. code-block:: shell-session
   196  
   197      $ kexec cilium-dbg monitor -t policy-verdict --related-to $HOST_EP_ID
   198      Policy verdict log: flow 0x0 local EP ID 1687, remote ID 2, proto 6, ingress, action deny, match none, 10.0.2.2:49038 -> 10.0.2.15:21 tcp SYN
   199  
   200  
   201  Clean up
   202  ========
   203  
   204  .. code-block:: shell-session
   205  
   206     $ kubectl delete ccnp demo-host-policy
   207     $ kubectl label node $NODE_NAME node-access-
   208  
   209  Further Reading
   210  ===============
   211  
   212  Read the documentation on :ref:`HostPolicies` for additional details on how to
   213  use the policies. In particular, refer to the :ref:`Troubleshooting Host
   214  Policies <troubleshooting_host_policies>` subsection to understand how to debug
   215  issues with Host Policies, or to the section on :ref:`Host Policies known
   216  issues <host_policies_known_issues>` to understand the current limitations of
   217  the feature.