From a93877deeca74197ed24eb00603a88aa6de3ce19 Mon Sep 17 00:00:00 2001 From: Jakub Dyszkiewicz Date: Tue, 14 Nov 2023 15:24:38 +0100 Subject: [PATCH 1/3] docs(tproxy): improve tproxy instructions Signed-off-by: Jakub Dyszkiewicz --- .../dp-config/transparent-proxying.md | 60 +++++++++++++++---- 1 file changed, 47 insertions(+), 13 deletions(-) diff --git a/app/_src/production/dp-config/transparent-proxying.md b/app/_src/production/dp-config/transparent-proxying.md index 4fe13ece4..5f5be5ef3 100644 --- a/app/_src/production/dp-config/transparent-proxying.md +++ b/app/_src/production/dp-config/transparent-proxying.md @@ -36,26 +36,45 @@ Prerequisites: {{site.mesh_product_name}} comes with [`kumactl` executable](/docs/{{ page.version }}/explore/cli) which can help us to prepare the host. Due to the wide variety of Linux setup options, these steps may vary and may need to be adjusted for the specifics of the particular deployment. The host that will run the `kuma-dp` process in transparent proxying mode needs to be prepared with the following steps executed as `root`: -1. Create a new dedicated user on the machine. +1. Use proper version of iptables + + {{site.mesh_product_name}} [is not yet compatible](https://github.com/kumahq/kuma/issues/8293) with `nf_tables`. You can check the version of iptables with the following command + ```sh + $ iptables --version + iptables v1.8.7 (nf_tables) + ``` + + On the recent versions of Ubuntu, you need to change default `iptables`. + + ```sh + $ update-alternatives --set iptables /usr/sbin/iptables-legacy + $ update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy + $ iptables --version + iptables v1.8.7 (legacy) +``` + +2. Create a new dedicated user on the machine. ```sh useradd -u 5678 -U kuma-dp ``` -2. Redirect all the relevant inbound, outbound and DNS traffic to the {{site.mesh_product_name}} data plane proxy. +3. Redirect all the relevant inbound, outbound and DNS traffic to the {{site.mesh_product_name}} data plane proxy. ```sh kumactl install transparent-proxy \ --kuma-dp-user kuma-dp \ - --skip-resolv-conf \ - --redirect-dns + --redirect-dns \ + --exclude-inbound-ports 22 ``` {% warning %} Please note that this command **will change** the host `iptables` rules. + +We exclude port 22, so we can SSH to the machine without `kuma-dp` running. {% endwarning %} -The changes will persist over restarts, so this command is needed only once. Reverting to the original state of the host can be done by issuing `kumactl uninstall transparent-proxy`. +The changes will not persist over restarts. You need to either add this command to your start scripts or use firewalld. ### Data plane proxy resource @@ -64,11 +83,11 @@ In transparent proxying mode, the `Dataplane` resource should omit the `networki ```yaml type: Dataplane mesh: default -name: {{ name }} +name: {% raw %}{{ name }}{% endraw %} networking: - address: {{ address }} + address: {% raw %}{{ address }}{% endraw %} inbound: - - port: {{ port }} + - port: {% raw %}{{ port }}{% endraw %} tags: kuma.io/service: demo-client transparentProxying: @@ -82,6 +101,7 @@ The ports illustrated above are the default ones that `kumactl install transpare {% warning %} It is important that the `kuma-dp` process runs with the same system user that was passed to `kumactl install transparent-proxy --kuma-dp-user`. +The service itself should run with any other user than `kuma-dp`. Otherwise, it won't be able to leverage transparent proxying. {% endwarning %} When systemd is used, this can be done with an entry `User=kuma-dp` in the `[Service]` section of the service file. @@ -109,8 +129,22 @@ If you run `firewalld` to manage firewalls and wrap iptables, add the `--store-f ### Upgrades -Before upgrading to the next version of {{site.mesh_product_name}}, make sure to run `kumactl uninstall transparent-proxy` and only then replace the `kumactl` binary. -This will ensure smooth upgrade and no leftovers from the previous installations. +Before upgrading to the next version of {{site.mesh_product_name}}, it's best to clean existing `iptables` rules and only then replace the `kumactl` binary. + +You can clean the rules either by restarting the host or by running following commands +```sh +iptables -t nat -F +iptables -t nat -X +iptables -t raw -F +iptables -t raw -X +ip6tables -t nat -F +ip6tables -t nat -X +ip6tables -t raw -F +ip6tables -t raw -X +``` +Be aware that the command above with remove all iptables rules, not only created by {{site.mesh_product_name}}. + +In the future release, `kumactl` [will ship](https://github.com/kumahq/kuma/issues/8071) with `uninstall` command. ## Configuration @@ -188,11 +222,11 @@ spec: ```yaml type: Dataplane mesh: default -name: {{ name }} +name: {% raw %}{{ name }}{% endraw %} networking: - address: {{ address }} + address: {% raw %}{{ address }}{% endraw %} inbound: - - port: {{ port }} + - port: {% raw %}{{ port }}{% endraw %} tags: kuma.io/service: demo-client transparentProxying: From d0672facebe1e44c16c277a20970d9ea4e740452 Mon Sep 17 00:00:00 2001 From: Jakub Dyszkiewicz Date: Tue, 14 Nov 2023 15:44:30 +0100 Subject: [PATCH 2/3] fix vale Signed-off-by: Jakub Dyszkiewicz --- .github/styles/Vocab/Base/accept.txt | 1 + app/_src/production/dp-config/transparent-proxying.md | 8 ++++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/styles/Vocab/Base/accept.txt b/.github/styles/Vocab/Base/accept.txt index 45bd22903..080c39010 100644 --- a/.github/styles/Vocab/Base/accept.txt +++ b/.github/styles/Vocab/Base/accept.txt @@ -49,6 +49,7 @@ endunless endwarning etcd Fargate +firewalld GAMMA Gateway API GitHub diff --git a/app/_src/production/dp-config/transparent-proxying.md b/app/_src/production/dp-config/transparent-proxying.md index 5f5be5ef3..56fda5306 100644 --- a/app/_src/production/dp-config/transparent-proxying.md +++ b/app/_src/production/dp-config/transparent-proxying.md @@ -38,7 +38,7 @@ The host that will run the `kuma-dp` process in transparent proxying mode needs 1. Use proper version of iptables - {{site.mesh_product_name}} [is not yet compatible](https://github.com/kumahq/kuma/issues/8293) with `nf_tables`. You can check the version of iptables with the following command + {{site.mesh_product_name}} [isn't yet compatible](https://github.com/kumahq/kuma/issues/8293) with `nf_tables`. You can check the version of iptables with the following command ```sh $ iptables --version iptables v1.8.7 (nf_tables) @@ -71,10 +71,10 @@ The host that will run the `kuma-dp` process in transparent proxying mode needs {% warning %} Please note that this command **will change** the host `iptables` rules. -We exclude port 22, so we can SSH to the machine without `kuma-dp` running. +The command excludes port 22, so you can SSH to the machine without `kuma-dp` running. {% endwarning %} -The changes will not persist over restarts. You need to either add this command to your start scripts or use firewalld. +The changes won't persist over restarts. You need to either add this command to your start scripts or use firewalld. ### Data plane proxy resource @@ -142,7 +142,7 @@ ip6tables -t nat -X ip6tables -t raw -F ip6tables -t raw -X ``` -Be aware that the command above with remove all iptables rules, not only created by {{site.mesh_product_name}}. +Be aware that this command removes all iptables rules, not only created by {{site.mesh_product_name}}. In the future release, `kumactl` [will ship](https://github.com/kumahq/kuma/issues/8071) with `uninstall` command. From 1ddba832efc109df02623c2b2ca4606324a95c07 Mon Sep 17 00:00:00 2001 From: Jakub Dyszkiewicz Date: Wed, 15 Nov 2023 10:25:43 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Bart Smykla Signed-off-by: Jakub Dyszkiewicz --- .../dp-config/transparent-proxying.md | 37 ++++++++++--------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/app/_src/production/dp-config/transparent-proxying.md b/app/_src/production/dp-config/transparent-proxying.md index 56fda5306..71b05bdc6 100644 --- a/app/_src/production/dp-config/transparent-proxying.md +++ b/app/_src/production/dp-config/transparent-proxying.md @@ -40,18 +40,18 @@ The host that will run the `kuma-dp` process in transparent proxying mode needs {{site.mesh_product_name}} [isn't yet compatible](https://github.com/kumahq/kuma/issues/8293) with `nf_tables`. You can check the version of iptables with the following command ```sh - $ iptables --version - iptables v1.8.7 (nf_tables) + iptables --version + # iptables v1.8.7 (nf_tables) ``` On the recent versions of Ubuntu, you need to change default `iptables`. ```sh - $ update-alternatives --set iptables /usr/sbin/iptables-legacy - $ update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy - $ iptables --version - iptables v1.8.7 (legacy) -``` + update-alternatives --set iptables /usr/sbin/iptables-legacy + update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy + iptables --version + # iptables v1.8.7 (legacy) + ``` 2. Create a new dedicated user on the machine. @@ -132,17 +132,20 @@ If you run `firewalld` to manage firewalls and wrap iptables, add the `--store-f Before upgrading to the next version of {{site.mesh_product_name}}, it's best to clean existing `iptables` rules and only then replace the `kumactl` binary. You can clean the rules either by restarting the host or by running following commands + +{% warning %} +Executing these commands will remove all iptables rules, including those created by {{site.mesh_product_name}} and any other applications or services. +{% endwarning %} + ```sh -iptables -t nat -F -iptables -t nat -X -iptables -t raw -F -iptables -t raw -X -ip6tables -t nat -F -ip6tables -t nat -X -ip6tables -t raw -F -ip6tables -t raw -X -``` -Be aware that this command removes all iptables rules, not only created by {{site.mesh_product_name}}. +iptables --table nat --flush +iptables --table raw --flush +ip6tables --table nat --flush +ip6tables --table raw --flush +iptables --table nat --delete-chain +iptables --table raw --delete-chain +ip6tables --table nat --delete-chain +ip6tables --table raw --delete-chain In the future release, `kumactl` [will ship](https://github.com/kumahq/kuma/issues/8071) with `uninstall` command.