Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fix WireGuard spelling #16293

Merged
merged 1 commit into from
May 25, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
35 changes: 20 additions & 15 deletions Documentation/gettingstarted/encryption-wireguard.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@
.. _encryption_wg:

********************************
Wireguard Transparent Encryption
WireGuard Transparent Encryption
********************************

This guide explains how to configure Cilium with transparent encryption of
traffic between Cilium-managed endpoints using `Wireguard <https://www.wireguard.com/>`_.
traffic between Cilium-managed endpoints using `WireGuard® <https://www.wireguard.com/>`_.

When Wireguard is enabled in Cilium, the agent running on each cluster node
will establish a secure Wireguard tunnel between it and all other known nodes
When WireGuard is enabled in Cilium, the agent running on each cluster node
will establish a secure WireGuard tunnel between it and all other known nodes
in the cluster. Each node automatically creates its own encryption key-pair and
distributes its public key via the ``io.cilium.network.wg-pub-key`` annotation
in the Kubernetes ``CiliumNode`` custom resource object. Each node's public key
Expand All @@ -25,25 +25,25 @@ Packets are not encrypted when they are destined to the same node from which
they were sent. This behavior is intended. Encryption would provide no benefits
in that case, given that the raw traffic can be observed on the node anyway.

The Wireguard tunnel endpoint is exposed on UDP port ``51871`` on each node. If
The WireGuard tunnel endpoint is exposed on UDP port ``51871`` on each node. If
you run Cilium in an environment that requires firewall rules to enable
connectivity, you will have to ensure that all Cilium cluster nodes can reach
each other via that port.

.. note::

When running in the tunneling mode (i.e. with VXLAN or Geneve), pod to pod
traffic will be sent only over the Wireguard tunnel which means that the
traffic will be sent only over the WireGuard tunnel which means that the
packets will bypass the other tunnel, and thus they will be encapsulated
only once.

Enable Wireguard in Cilium
Enable WireGuard in Cilium
==========================

Before you enable Wireguard in Cilium, please ensure that the Linux distribution
running on your cluster nodes has support for Wireguard in kernel mode
Before you enable WireGuard in Cilium, please ensure that the Linux distribution
running on your cluster nodes has support for WireGuard in kernel mode
(i.e. ``CONFIG_WIREGUARD=m`` on Linux 5.6 and newer, or via the out-of-tree
Wireguard module on older kernels).
WireGuard module on older kernels).

.. tabs::

Expand All @@ -69,7 +69,7 @@ Wireguard module on older kernels).
--set encryption.enabled=true \\
--set encryption.type=wireguard

Wireguard may also be enabled manually by setting setting the
WireGuard may also be enabled manually by setting setting the
``enable-wireguard: true`` option in the Cilium ``ConfigMap`` and restarting
each Cilium agent instance.

Expand All @@ -80,7 +80,7 @@ Run a ``bash`` shell in one of the Cilium pods with
``kubectl -n kube-system exec -ti ds/cilium -- bash`` and execute the following
commands:

1. Check that Wireguard has been enabled (number of peers should correspond to
1. Check that WireGuard has been enabled (number of peers should correspond to
a number of nodes subtracted by one):

.. code-block:: shell-session
Expand Down Expand Up @@ -179,7 +179,7 @@ commands can be helpful:
For pod to pod packets to be successfully encrypted and decrypted, the following
must hold:

- Wireguard public key of a remote node in the ``peers[*].public-key`` section
- WireGuard public key of a remote node in the ``peers[*].public-key`` section
matches the actual public key of the remote node (``public-key`` retrieved via
the same command on the remote node).
- ``peers[*].allowed-ips`` should contain a list of pod IP addresses running
Expand All @@ -188,7 +188,7 @@ must hold:
Limitations
===========

Wireguard support in Cilium currently lacks the following features,
WireGuard support in Cilium currently lacks the following features,
which may be resolved in upcoming Cilium releases:

- Host-level encryption. Only traffic between two Cilium-managed endpoints
Expand All @@ -197,6 +197,11 @@ which may be resolved in upcoming Cilium releases:
agent will currently not be encrypted.
- L7 policy enforcement and visibility
- eBPF-based host routing
- Support for older kernels via user-mode Wireguard
- Support for older kernels via user-mode WireGuard

The current status of these limitations is tracked in :gh-issue:`15462`.

Legal
=====

"WireGuard" is a registered trademark of Jason A. Donenfeld.
2 changes: 1 addition & 1 deletion Documentation/gettingstarted/encryption.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Transparent Encryption
************************************

Cilium supports the transparent encryption of Cilium-managed host traffic and
traffic between Cilium-managed endpoints either using IPsec or Wireguard:
traffic between Cilium-managed endpoints either using IPsec or WireGuard®:

.. toctree::
:maxdepth: 1
Expand Down
36 changes: 18 additions & 18 deletions Documentation/operations/performance/benchmark.rst
Original file line number Diff line number Diff line change
Expand Up @@ -218,15 +218,15 @@ while running the benchmark:

.. image:: images/bench_tcp_crr_32_processes_cpu.png

Encryption (Wireguard/IPsec)
Encryption (WireGuard/IPsec)
============================

Cilium supports encryption via Wireguard and IPsec. This first section will
look at Wireguard and compare it against using Calico for Wireguard encryption.
If you are interested in IPsec performance and how it compares to Wireguard,
Cilium supports encryption via WireGuard® and IPsec. This first section will
look at WireGuard and compare it against using Calico for WireGuard encryption.
If you are interested in IPsec performance and how it compares to WireGuard,
please see :ref:`performance_wireguard_ipsec`.

Wireguard Throughput
WireGuard Throughput
--------------------

Looking at TCP throughput first, the following graph shows results for both
Expand All @@ -236,55 +236,55 @@ Looking at TCP throughput first, the following graph shows results for both

.. note::

The Cilium eBPF kube-proxy replacement combined with Wireguard is currently
The Cilium eBPF kube-proxy replacement combined with WireGuard is currently
slightly slower than Cilium eBPF + kube-proxy. We have identified the
problem and will be resolving this deficit in one of the next releases.

The following graph shows the total CPU consumption across the entire system
while running the Wireguard encryption benchmark:
while running the WireGuard encryption benchmark:

.. image:: images/bench_wireguard_tcp_1_stream_cpu.png

Wireguard Request/Response
WireGuard Request/Response
--------------------------

The next benchmark measures the request/response rate while encrypting with
Wireguard. See :ref:`request_response` for details on what this test actually
WireGuard. See :ref:`request_response` for details on what this test actually
entails.

.. image:: images/bench_wireguard_rr_1_process.png

All tested configurations performed more or less the same. The following graph
shows the total CPU consumption across the entire system while running the
Wireguard encryption benchmark:
WireGuard encryption benchmark:

.. image:: images/bench_wireguard_rr_1_process_cpu.png

.. _performance_wireguard_ipsec:

Wireguard vs IPsec
WireGuard vs IPsec
------------------

In this section, we compare Cilium encryption using Wireguard and IPsec.
Wireguard is able to achieve a higher maximum throughput:
In this section, we compare Cilium encryption using WireGuard and IPsec.
WireGuard is able to achieve a higher maximum throughput:

.. image:: images/bench_wireguard_ipsec_tcp_stream_1_stream.png

However, looking at the CPU resources required to achieve 10Gbit/s of
throughput, Wireguard is less efficient at achieving the same throughput:
throughput, WireGuard is less efficient at achieving the same throughput:

.. image:: images/bench_wireguard_ipsec_tcp_stream_1_stream_cpu.png

.. tip::

IPsec performing better than Wireguard in in this test is unexpected in some
IPsec performing better than WireGuard in in this test is unexpected in some
ways. A possible explanation is that the IPsec encryption is making use of
AES-NI instructions whereas the Wireguard implementation is not. This would
AES-NI instructions whereas the WireGuard implementation is not. This would
typically lead to IPsec being more efficient when AES-NI offload is
available and Wireguard being more efficient if the instruction set is not
available and WireGuard being more efficient if the instruction set is not
available.

Looking at the request/response rate, IPsec is outperforming Wireguard in our
Looking at the request/response rate, IPsec is outperforming WireGuard in our
tests. Unlike for the throughput tests, the MTU does not have any effect as the
packet sizes remain small:

Expand Down
2 changes: 1 addition & 1 deletion Documentation/operations/system_requirements.rst
Original file line number Diff line number Diff line change
Expand Up @@ -329,7 +329,7 @@ Port Range / Protocol Description
9891/tcp operator gops server (listening on 127.0.0.1)
9892/tcp clustermesh-apiserver gops server (listening on 127.0.0.1)
9893/tcp Hubble Relay gops server (listening on 127.0.0.1)
51871/udp Wireguard encryption tunnel endpoint
51871/udp WireGuard encryption tunnel endpoint
======================== ===========================================================

.. _admin_mount_bpffs:
Expand Down
3 changes: 2 additions & 1 deletion Documentation/spelling_wordlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Deathstar
Dinan
Dockerfile
Dockerfiles
Donenfeld
Elasticsearch
FIt
Facebook
Expand Down Expand Up @@ -189,7 +190,7 @@ Viljoen
Virtualization
Wakeup
Wendlandt
Wireguard
WireGuard
Wireshark
XDP
Xenial
Expand Down