From f899c7cb4ce616de942ba07f3ef7b922e190aded Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:26:23 +0100 Subject: [PATCH 01/40] docs(tproxy): restructure and expand transparent proxy documentation Transparent proxy docs are now consolidated under Using Kuma / Service Discovery & Networking / Transparent Proxy. The former "Kuma in Production" content is now "Introduction" in this group, and "Using Kuma / Transparent Proxying" is now "Technical Overview". Reachable Services, Reachable Backends, installation, and configuration are split into separate pages. Added a Transparent Proxy Configuration Reference. Signed-off-by: Bart Smykla --- app/_assets/entrypoints/application.js | 2 +- app/_data/docs_nav_kuma_2.9.x.yml | 32 +- app/_data/docs_nav_kuma_dev.yml | 32 +- app/_data/tproxy.yaml | 57 ++ .../tproxy/conf-field-table.html.liquid | 71 ++ ...ding-traffic-other-options-k8s.html.liquid | 48 ++ .../configuration-on-kubernetes.md | 421 ++++++++++ .../configuration-on-universal.md | 170 ++++ .../installing-on-universal.md | 267 +++++++ .../transparent-proxy/introduction.md | 129 +++ .../transparent-proxy/reachable-backends.md | 184 +++++ .../transparent-proxy/reachable-services.md | 62 ++ .../transparent-proxy/technical-overview.md | 188 +++++ .../upgrading-on-universal.md | 55 ++ .../transparent-proxy-configuration.md | 739 ++++++++++++++++++ 15 files changed, 2446 insertions(+), 11 deletions(-) create mode 100644 app/_data/tproxy.yaml create mode 100644 app/_includes/snippets/tproxy/conf-field-table.html.liquid create mode 100644 app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid create mode 100644 app/_src/networking/transparent-proxy/configuration-on-kubernetes.md create mode 100644 app/_src/networking/transparent-proxy/configuration-on-universal.md create mode 100644 app/_src/networking/transparent-proxy/installing-on-universal.md create mode 100644 app/_src/networking/transparent-proxy/introduction.md create mode 100644 app/_src/networking/transparent-proxy/reachable-backends.md create mode 100644 app/_src/networking/transparent-proxy/reachable-services.md create mode 100755 app/_src/networking/transparent-proxy/technical-overview.md create mode 100644 app/_src/networking/transparent-proxy/upgrading-on-universal.md create mode 100644 app/_src/reference/transparent-proxy-configuration.md diff --git a/app/_assets/entrypoints/application.js b/app/_assets/entrypoints/application.js index c1bd2efd3..5055b76da 100644 --- a/app/_assets/entrypoints/application.js +++ b/app/_assets/entrypoints/application.js @@ -39,5 +39,5 @@ document.addEventListener('DOMContentLoaded', (event) => { placement: 'left', icon: '#' }); - anchors.add('.doc h1, .doc h2, .doc h3, .doc h4, .doc h5, .doc h6'); + anchors.add('.doc h1:not(.no-anchor), .doc h2:not(.no-anchor), .doc h3:not(.no-anchor), .doc h4:not(.no-anchor), .doc h5:not(.no-anchor), .doc h6:not(.no-anchor)'); }); diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index ea352ecf2..dc4615958 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -102,10 +102,11 @@ items: url: /production/dp-config/dpp-on-universal/ - text: Configure the Kuma CNI url: /production/dp-config/cni/ - - text: Configure transparent proxying - url: /production/dp-config/transparent-proxying/ - text: IPv6 support url: /production/dp-config/ipv6/ + - text: Transparent Proxy + url: /networking/transparent-proxy/introduction + generate: false - title: Secure your deployment group: true items: @@ -273,8 +274,25 @@ items: url: "/networking/meshexternalservice/#configuration" - text: Examples url: "/networking/meshexternalservice/#examples" - - text: Transparent Proxying - url: /networking/transparent-proxying/ + - title: Transparent Proxy + group: true + items: + - text: Introduction + url: /networking/transparent-proxy/introduction/ + - text: Technical Overview + url: /networking/transparent-proxy/technical-overview/ + - text: Installing on Universal + url: /networking/transparent-proxy/installing-on-universal/ + - text: Configuration on Kubernetes + url: /networking/transparent-proxy/configuration-on-kubernetes/ + - text: Configuration on Universal + url: /networking/transparent-proxy/configuration-on-universal/ + - text: Upgrading on Universal + url: /networking/transparent-proxy/upgrading-on-universal/ + - text: Reachable Services + url: /networking/transparent-proxy/reachable-services/ + - text: Reachable Backends + url: /networking/transparent-proxy/reachable-backends/ - title: Policies group: true items: @@ -499,10 +517,12 @@ items: url: /guides/otel-metrics/ - text: Migration to the new policies url: /guides/migration-to-the-new-policies/ - - text: Progressively rolling in strict MTLS + - text: Progressively rolling in strict mTLS url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies + - text: Excluding Traffic From Transparent Proxy + url: /guides/excluding-traffic-from-transparent-proxy-redirection/ - title: Reference group: true items: @@ -516,6 +536,8 @@ items: url: /reference/kuma-cp - text: Envoy proxy template url: /reference/proxy-template/ + - text: Transparent Proxy Configuration + url: /reference/transparent-proxy-configuration/ - title: Community group: true items: diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index ea352ecf2..dc4615958 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -102,10 +102,11 @@ items: url: /production/dp-config/dpp-on-universal/ - text: Configure the Kuma CNI url: /production/dp-config/cni/ - - text: Configure transparent proxying - url: /production/dp-config/transparent-proxying/ - text: IPv6 support url: /production/dp-config/ipv6/ + - text: Transparent Proxy + url: /networking/transparent-proxy/introduction + generate: false - title: Secure your deployment group: true items: @@ -273,8 +274,25 @@ items: url: "/networking/meshexternalservice/#configuration" - text: Examples url: "/networking/meshexternalservice/#examples" - - text: Transparent Proxying - url: /networking/transparent-proxying/ + - title: Transparent Proxy + group: true + items: + - text: Introduction + url: /networking/transparent-proxy/introduction/ + - text: Technical Overview + url: /networking/transparent-proxy/technical-overview/ + - text: Installing on Universal + url: /networking/transparent-proxy/installing-on-universal/ + - text: Configuration on Kubernetes + url: /networking/transparent-proxy/configuration-on-kubernetes/ + - text: Configuration on Universal + url: /networking/transparent-proxy/configuration-on-universal/ + - text: Upgrading on Universal + url: /networking/transparent-proxy/upgrading-on-universal/ + - text: Reachable Services + url: /networking/transparent-proxy/reachable-services/ + - text: Reachable Backends + url: /networking/transparent-proxy/reachable-backends/ - title: Policies group: true items: @@ -499,10 +517,12 @@ items: url: /guides/otel-metrics/ - text: Migration to the new policies url: /guides/migration-to-the-new-policies/ - - text: Progressively rolling in strict MTLS + - text: Progressively rolling in strict mTLS url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies + - text: Excluding Traffic From Transparent Proxy + url: /guides/excluding-traffic-from-transparent-proxy-redirection/ - title: Reference group: true items: @@ -516,6 +536,8 @@ items: url: /reference/kuma-cp - text: Envoy proxy template url: /reference/proxy-template/ + - text: Transparent Proxy Configuration + url: /reference/transparent-proxy-configuration/ - title: Community group: true items: diff --git a/app/_data/tproxy.yaml b/app/_data/tproxy.yaml new file mode 100644 index 000000000..889f6964a --- /dev/null +++ b/app/_data/tproxy.yaml @@ -0,0 +1,57 @@ +config: + redirect: + inbound: + excludePorts: &excludePortsInbound + path: redirect.inbound.excludePorts + flag: --exclude-inbound-ports + env: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS + runtime: + path: runtime.kubernetes.injector.sidecarTraffic.excludeInboundPorts + env: KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS + excludePortsForIPs: &excludePortsForIPsInbound + path: redirect.inbound.excludePortsForIPs + flag: --exclude-inbound-ips + env: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS + runtime: + path: runtime.kubernetes.injector.sidecarTraffic.excludeInboundIPs + env: KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS + outbound: + excludePorts: &excludePortsOutbound + path: redirect.outbound.excludePorts + flag: --exclude-outbound-ports + env: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS + runtime: + path: runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts + env: KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS + excludePortsForIPs: &excludePortsForIPsOutbound + path: redirect.outbound.excludePortsForIPs + flag: --exclude-outbound-ips + env: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS + runtime: + path: runtime.kubernetes.injector.sidecarTraffic.excludeOutboundIPs + env: KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS + +defaults: + redirect: + inbound: + port: 15006 + outbound: + port: 15001 + dns: + port: 15053 + kuma-dp: + username: kuma-dp + uid: 5678 + resolv: + conf: + path: /etc/resolv.conf + +data: + guides: + exclude-traffic: + excludePorts: + - *excludePortsInbound + - *excludePortsOutbound + excludeIPs: + - *excludePortsForIPsInbound + - *excludePortsForIPsOutbound diff --git a/app/_includes/snippets/tproxy/conf-field-table.html.liquid b/app/_includes/snippets/tproxy/conf-field-table.html.liquid new file mode 100644 index 000000000..0ac7d257d --- /dev/null +++ b/app/_includes/snippets/tproxy/conf-field-table.html.liquid @@ -0,0 +1,71 @@ +{%- assign values = include.values | split: "," -%} +{%- capture snippet-tproxy-field-table -%} + + + + + + + {% if include.default %} + + + + + {% endif %} + {% if include.values %} + + + + + {% endif %} + {% if include.format %} + + + + + {% endif %} + {% if include.flag %} + + + + + {% endif %} + {% if_version gte:2.9.x %} + {% if include.env %} + + + + + {% endif %} + {% endif_version %} + {% if include.annotation %} + + + + + {% endif %} + {% if include.runtime %} + + + + + + + + {% if include.runtimeEnv %} + + + + + {% endif %} + {% endif %} + +
Type{{ include.type }}
Default Value{{ include.default }}
Values + {% for value in values %} + {% if forloop.length > 0 %} + {{ value }}{% unless forloop.last %}, {% endunless %} + {% endif %} + {% endfor %} +
Format{{ include.format }}
CLI Flag{{ include.flag }}
Environment VariableKUMA_TRANSPARENT_PROXY_{{ include.env }}
Kubernetes Annotation{{ include.annotation }}
Control Plane Runtime Configuration
Fieldruntime.kubernetes.injector.{{ include.runtime }}
Environment VariableKUMA_RUNTIME_KUBERNETES_INJECTOR_{{ include.runtimeEnv }}
+{%- endcapture -%} +{{ snippet-tproxy-field-table | normalize_whitespace }} \ No newline at end of file diff --git a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid new file mode 100644 index 000000000..483e1ebf2 --- /dev/null +++ b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid @@ -0,0 +1,48 @@ +

Other configuration options

+ + + + + + + + + + + + + {% for field in include.data %} + + + + + {% endfor %} + +
+ + Configuration in ConfigMap + +
FieldEnvironment Variable
{{ field.path }}{{ field.env }}
+ + + + + + + + + + + + {% for field in include.data %} + + + + + {% endfor %} + +
+ + Control Plane Runtime Configuration + +
FieldEnvironment Variable
{{ field.runtime.path }}{{ field.runtime.env }}
diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md new file mode 100644 index 000000000..a5d9aaa25 --- /dev/null +++ b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md @@ -0,0 +1,421 @@ +--- +title: Adjusting Transparent Proxy Configuration on Kubernetes +content_type: how-to +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} +{% assign kuma-system = site.mesh_namespace %} +{% assign controlPlane = site.set_flag_values_prefix | append: "controlPlane" %} +{% assign transparentProxy = site.set_flag_values_prefix | append: "transparentProxy" %} +{% assign kuma-control-plane = site.mesh_cp_name %} +{% assign kuma-control-plane-config = kuma-control-plane | append: "-config" %} + +{% assign configuration-in-configmap = "Configuration in ConfigMap (experimental)" %} + +The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This guide explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one. While these methods can be used individually, they can also be combined when necessary. + +{% warning %} +It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. +{% endwarning %} + +## Terminology overview + +- **Workload**: In this guide, **workload** refers to an application running in a Kubernetes cluster, usually represented by a [**Pod**](https://kubernetes.io/docs/concepts/workloads/pods/). Kubernetes resources like [**Deployment**](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [**ReplicaSet**](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), and [**StatefulSet**](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) are used to define and manage these workloads, resulting in one or more **Pods** where the application actually runs. + +- **ConfigMap**: In this guide, **ConfigMap** refers to the Kubernetes [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/) resource. It’s used to store configuration data as key-value pairs that can be easily accessed by other resources in the cluster, such as Pods, Deployments, and StatefulSets. + +## Method 1: Control plane runtime configuration + +The control plane runtime configuration is a section of {{ Kuma }}'s configuration that contains important settings for how the control plane operates, including options for the transparent proxy and other key components. + +{% tip %} +For more details, see the [Control Plane Configuration Reference]({{ docs }}/reference/kuma-cp/) under `runtime.kubernetes`. +{% endtip %} + +Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. + +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all workloads. In the future, once the [{{ configuration-in-configmap }}](#method-1-control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. + +Below is a subset of the configuration focused on transparent proxy settings, with default values and corresponding environment variables for each field. For further details, see the [Modifying control plane runtime configuration](#modifying-control-plane-runtime-configuration) section. + +```yaml +runtime: + kubernetes: + injector: + cniEnabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_CNI_ENABLED + applicationProbeProxyPort: 9001 # KUMA_RUNTIME_KUBERNETES_APPLICATION_PROBE_PROXY_PORT + sidecarContainer: + uid: 5678 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_UID + ipFamilyMode: dualstack # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_IP_FAMILY_MODE + redirectPortInbound: 15006 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_INBOUND + redirectPortOutbound: 15001 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_OUTBOUND + sidecarTraffic: + excludeInboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS + excludeOutboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS + excludeInboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS + excludeOutboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS + builtinDNS: + enabled: true # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED + port: 15053 # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_PORT + ebpf: + enabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_ENABLED + instanceIPEnvVarName: INSTANCE_IP # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_INSTANCE_IP_ENV_VAR_NAME + bpffsPath: /sys/fs/bpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_BPFFS_PATH + cgroupPath: /sys/fs/cgroup # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_CGROUP_PATH + tcAttachIface: "" # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_TC_ATTACH_IFACE + programsSourcePath: /tmp/kuma-ebpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_PROGRAMS_SOURCE_PATH +``` + +### Settings restricted to control plane runtime configuration + +Some transparent proxy settings **can only be changed through the control plane’s runtime configuration** because they are shared with other {{ Kuma }} components. These settings handle essential tasks like creating [`Dataplane` resources]({{ docs }}/production/dp-config/dpp/) for workloads and setting up the [`kuma-dp` sidecar container]({{ docs }}/production/dp-config/dpp-on-kubernetes/) alongside them. For example, the DNS port used to redirect traffic is shared between the transparent proxy and the `kuma-dp run` command in the sidecar container. Keeping these settings consistent across workloads prevents misconfigurations. These settings are: + +- `runtime.kubernetes.injector.sidecarContainer.redirectPortInbound` +- `runtime.kubernetes.injector.sidecarContainer.redirectPortOutbound` +- `runtime.kubernetes.injector.sidecarContainer.uid` +- `runtime.kubernetes.injector.builtinDNS.enabled` +- `runtime.kubernetes.injector.builtinDNS.port` + +{% capture behavior-difference-danger %} +{% danger %} +⚠️ This behavior differs from that of other settings. Ensure you're aware of this distinction and **never** attempt to modify these settings using the mentioned annotations. +{% enddanger %} +{% endcapture %} + +If you try to change these settings with methods described later in this guide, but with values different from the runtime configuration, the effects will vary: + +- **`runtime.kubernetes.injector.sidecarContainer.redirectPortInbound` and `runtime.kubernetes.injector.sidecarContainer.redirectPortOutbound`** + + Attempts to change these settings using `kuma.io/transparent-proxying-inbound-port` and `kuma.io/transparent-proxying-outbound-port` annotations, or by updating `redirect.inbound.port` and `redirect.outbound.port` in the ConfigMap, will trigger warnings in the control plane logs, but the values will be ignored. + +- **`runtime.kubernetes.injector.sidecarContainer.uid`** + + Attempts to modify this setting using the `kuma.io/sidecar-uid` annotation or `kumaDPUser` in the ConfigMap will result in: + + - A warning in control plane logs if the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is **enabled**, and the values will be ignored. + - Silent ignoring of the change without warnings if the feature is **disabled**. + +- **`runtime.kubernetes.injector.builtinDNS.enabled` and `runtime.kubernetes.injector.builtinDNS.port`** + + Attempts to modify these settings using deprecated annotations `kuma.io/builtin-dns` and `kuma.io/builtin-dns-port`, or `redirect.dns.enabled` and `redirect.dns.port` in the ConfigMap, will have the following effects: + + - If the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is **enabled**, warnings will appear in the control plane logs, and values will be ignored. + - If the feature is **disabled**, changes through annotations **will still apply**, possibly leading to broken DNS redirection. This can result in `kuma-dp` not starting the DNS server or listening on the wrong port, which may create issues in the environment. + + {{ behavior-difference-danger | indent | indent }} + +### Modifying control plane runtime configuration + +{% capture modify-runtime-conf-configmap %} +{% capture runtime-conf-in-values-file-create-a-values-file %} +{% helmvalues %} +```yaml +controlPlane: + config: | + runtime: + kubernetes: + injector: + sidecarTraffic: + excludeOutboundIPs: [10.1.0.254, 172.10.1.254] +``` +{% endhelmvalues %} + +{% warning %} +Make sure the content under `{{ controlPlane }}.config` is a string representation of the [control plane configuration]({{ docs }}/reference/kuma-cp/). +{% endwarning %} +{% endcapture %} + +{% capture runtime-conf-in-values-file-install-kuma %} +{% cpinstallfile modify-runtime-config-complete %} +{% endcapture %} + +{% tip %} +This method is **recommended** because it simplifies future modifications. Rather than reinstalling {{ Kuma }} or manually updating its Deployment to change environment variables, you can just update the ConfigMap and restart the `{{ kuma-control-plane }}` Pod to apply the changes. +{% endtip %} + +You can provide the full runtime configuration in the `{{ kuma-control-plane-config }}` ConfigMap within the `{{ kuma-system }}` namespace. + +Here’s an example that excludes specific outbound IPs from transparent proxy redirection: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ kuma-control-plane-config }} + namespace: {{ kuma-system }} +data: + config.yaml: | + runtime: + kubernetes: + injector: + sidecarTraffic: + excludeOutboundIPs: [10.1.0.254, 172.10.1.254] +``` + +Instead of manually updating the ConfigMap in the cluster, you can specify the configuration it will store during the {{ Kuma }} installation. Follow these steps: + +1. Create a `values.yaml` file with the following content: + + {{ runtime-conf-in-values-file-create-a-values-file | indent }} + +2. Install {{ Kuma }} using `kumactl` or Helm: + + {{ runtime-conf-in-values-file-install-kuma | indent }} + +{% tip %} +If you're deploying {{ Kuma }} using Helm, you can place the configuration in a separate file and pass it during installation with the `--set-file` flag. + +For example, create a `cp-conf.yaml` file with the following content: + +```yaml +runtime: + kubernetes: + injector: + sidecarTraffic: + excludeOutboundIPs: [10.1.0.254, 172.10.1.254] +``` + +Then, during Helm installation, run: + +```sh +helm install \ + --create-namespace \ + --namespace {{ kuma-system }} \ + --set-file "{{ controlPlane }}.config=cp-conf.yaml" \ + {{ site.mesh_helm_install_name }} {{ site.mesh_helm_repo }} +``` + +This will have the same effect as using `--values values.yaml`, as described earlier. +{% endtip %} +{% endcapture %} + +{% capture modify-runtime-conf-env-var %} +You can also set individual configuration values using environment variables. For example, to exclude specific outbound IPs from the transparent proxy, update the `{{ kuma-control-plane }}` Deployment by setting the environment variable `KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS` with the desired IP addresses, separated by commas. For instance: `10.1.0.254,172.10.1.254`. + +{% danger %} +Manually editing Kubernetes manifests for {{ Kuma }} **is strongly discouraged** and should **only be done for testing in non-production environments**. Making manual changes can increase the risk of misconfiguration and may cause unexpected issues. For dynamic configuration updates without reinstalling {{ Kuma }}, use the `{{ kuma-control-plane-config }}` ConfigMap as described above. + +Setting environment variables during the initial installation, as shown below, is safe for any environment. While the ConfigMap is the preferred method, environment variables are also a reliable option for setup. +{% enddanger %} + +To apply environment variables to {{ Kuma }}'s control plane automatically, configure them during installation using the `{{ controlPlane }}.envVars` setting. For example: + + +{% cpinstall modify-runtime-config-env-var %} +controlPlane.envVars.KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS=10\.1\.0\.254\,172\.10\.1.254 +{% endcpinstall %} + +{% endcapture %} + +To modify the configuration, you have two main options: + +1. **Store the desired settings in the `{{ kuma-control-plane-config }}` ConfigMap:** + + {{ modify-runtime-conf-configmap | indent }} + +2. **Configure specific settings through environment variables:** + + {{ modify-runtime-conf-env-var | indent }} + +### Overriding list-based configuration settings + +For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`, only the value from the highest-precedence method will be applied, and values from other methods will not be combined. + +For example, if `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is applied to a specific workload, the annotation will override the control plane setting. This means the transparent proxy will exclude only the ports specified in the annotation. + +See the [**Order of Precedence**](#order-of-precedence) section to understand how different methods affect the final configuration applied. + +## Method 2: Configuration in ConfigMap (experimental) +{:#method-2-configuration-in-configmap} + +{% warning %} +Because this feature impacts multiple underlying components, it is considered experimental. Use it with caution. {% if site.mesh_product_name == "Kuma" %} If you encounter any unexpected behavior or issues, please [**contact us**](/community) and [**submit an issue on GitHub**](https://github.com/kumahq/kuma/issues/new/choose). Your feedback is essential in helping us improve this feature. {% endif %} +{% endwarning %} + +Until {{ Kuma }} 2.9, transparent proxy settings could only be modified through the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration) and [Kubernetes Annotations](#method-3-kubernetes-annotations), which had several limitations: + +- Not all settings were available through both methods; some could only be adjusted with annotations, while others were limited to the runtime configuration. +- Control plane runtime settings were applied globally to all workloads with injected data planes, making it hard to customize settings for specific groups of workloads. +- Annotation-based settings had to be added to each workload individually, making it difficult to manage the same configuration across multiple workloads. + +To address these issues, {{ Kuma }} now supports storing transparent proxy settings in dedicated ConfigMaps. These ConfigMaps can be applied at the namespace or individual workload level, offering greater flexibility and easier configuration. + +To enable this feature, set `{{ transparentProxy }}.configMap.enabled` during installation: + +{% cpinstall transparent-proxy-config-configmap-enabling %} +{{ transparentProxy }}.configMap.enabled=true +{% endcpinstall %} + +{% warning %} +If you set `{{ transparentProxy }}.configMap.config` to an empty value, it will override `{{ transparentProxy }}.configMap.enabled` and disable the feature, even if `{{ transparentProxy }}.configMap.enabled` is set to `true`. +{% endwarning %} + + +### ConfigMap auto-creation and configuration + + +During installation, {{ Kuma }} will automatically create a ConfigMap in the `{{ kuma-system }}` namespace. The ConfigMap will be named based on the `{{ transparentProxy }}.configMap.name` setting, and its content will come from the YAML configuration defined in `{{ transparentProxy }}.configMap.config`, which holds the transparent proxy settings. + +Here is an example of how to modify parts of this configuration during installation: + +{% cpinstall transparent-proxy-config-configmap-auto-creation-examples %} +{{ transparentProxy }}.configMap.config.enabled=true +{{ transparentProxy }}.configMap.config.redirect.outbound.excludePortsForIPs=10\.1\.0\.254\,172\.10\.1.254 +{{ transparentProxy }}.configMap.config.redirect.verbose=false +{% endcpinstall %} + +You can apply the same method of providing these values as explained in the **Store the desired settings in the `{{ kuma-control-plane-config }}` ConfigMap** option in the [**Modifying Control Plane Runtime Configuration**](#modifying-control-plane-runtime-configuration) section. + +{% tip %} +For more information about the structure of this configuration, see the [Kuma Control Plane Helm Values]({{ docs }}/reference/kuma-cp/#helm-valuesyaml) documentation, particularly under the `{{ transparentProxy }}.configMap.config` path. You can also refer to the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) for additional details. +{% endtip %} + + +### ConfigMap lookup strategy + + +{{ Kuma }} follows a specific order when searching for the ConfigMap: + +- If the workload is annotated with `traffic.kuma.io/transparent-proxy-configmap-name`, {{ Kuma }} first looks for the resource with the specified name in the workload’s namespace. If not found, it will then check the `{{ kuma-system }}` namespace for the same ConfigMap. + +- If the workload is not annotated, or the ConfigMap specified in the annotation is not found, {{ Kuma }} will search for the resource named in the `{{ transparentProxy }}.configMap.name` setting. It first looks in the workload's namespace, and if not found, it checks the `{{ kuma-system }}` namespace. + +{% warning %} +The ConfigMap in the `{{ kuma-system }}` namespace is required for proper operation, so it must be present even if custom ones are used in all individual workload namespaces. +{% endwarning %} + + +### Custom ConfigMap name + + +The name of the ConfigMap is defined by the `{{ transparentProxy }}.configMap.name` setting. By default, this name is set to `kuma-transparent-proxy-config`. + +To apply a custom name for all workloads, you can modify the `{{ transparentProxy }}.configMap.name` setting during installation: + +{% cpinstall transparent-proxy-config-configmap-custom-name-globally %} +{{ transparentProxy }}.configMap.name=custom-name +{% endcpinstall %} + +To use a different resource for specific workloads, apply the `traffic.kuma.io/transparent-proxy-configmap-name` annotation to those workloads. For example: + +```sh +kubectl annotate pods "traffic.kuma.io/transparent-proxy-configmap-name=custom-name" +``` + +This allows flexibility, enabling different workloads to use distinct ConfigMap settings while maintaining a global default. + +## Method 3: Kubernetes annotations + +Kubernetes annotations can be applied to individual workloads to modify the transparent proxy configuration. These annotations allow fine-tuning of specific behaviors for a single workload without affecting others. + +{% tip %} +Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. +{% endtip %} + +Below you can find a list of annotations that can be used to configure specific transparent proxy settings. + +- `traffic.kuma.io/exclude-inbound-ips` + +- `traffic.kuma.io/exclude-inbound-ports` + +- `traffic.kuma.io/exclude-outbound-ips` + +- `traffic.kuma.io/exclude-outbound-ports` + +- `traffic.kuma.io/exclude-outbound-ports-for-uids` + +- `traffic.kuma.io/drop-invalid-packets` + +- `traffic.kuma.io/iptables-logs` + +- `kuma.io/transparent-proxying-ebpf` + +- `kuma.io/transparent-proxying-ebpf-bpf-fs-path` + +- `kuma.io/transparent-proxying-ebpf-cgroup-path` + +- `kuma.io/transparent-proxying-ebpf-tc-attach-iface` + +- `kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name` + +- `kuma.io/transparent-proxying-ebpf-programs-source-path` + +- `kuma.io/transparent-proxying-ip-family-mode` + +The following annotations also affect the configuration, but their values are automatically managed by {{ Kuma }} and cannot be manually adjusted. Values of these annotations will always match those specified in the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration). For more details, refer to [Settings restricted to control plane runtime configuration](#settings-restricted-to-control-plane-runtime-configuration). + +- `kuma.io/sidecar-uid` + +- `kuma.io/transparent-proxying-inbound-port` + +- `kuma.io/transparent-proxying-outbound-port` + +{% warning %} +The following two annotations are deprecated and will be removed in future releases. They are provided here for reference only, and we **strongly advise against using them**. + +- `kuma.io/builtin-dns` + +- `kuma.io/builtin-dns-port` +{% endwarning %} + +The following annotation indirectly adjusts the transparent proxy configuration by configuring other components, resulting in changes to the transparent proxy behavior. While its value is automatically set by {{ Kuma }}, you can override it by manually providing a value. + +- `kuma.io/application-probe-proxy-port` + + This annotation defines the port (default: `9001`) to be excluded from incoming traffic redirection, similar to using the `traffic.kuma.io/exclude-inbound-ports` annotation or other configuration methods. + + For more information, refer to: + + - The [Kubernetes]({{ docs }}/policies/service-health-probes/#kubernetes) section in the [Service Health Probes]({{ docs }}/policies/service-health-probes/) documentation. + - The [Introduction to Application Probe Proxy and deprecation of Virtual Probes]({{ docs }}/production/upgrades-tuning/upgrade-notes/#introduction-to-application-probe-proxy-and-deprecation-of-virtual-probes) section in the [Upgrade Instructions]({{ docs }}/production/upgrades-tuning/upgrade-notes/). + +The following annotations differ from others mentioned earlier as they are related to the transparent proxy, but do not directly or indirectly configure specific individual settings. + +- `kuma.io/transparent-proxying` + + This annotation is automatically applied to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers). In Kubernetes environments, the transparent proxy is mandatory meaning you cannot disable it. Any attempt to explicitly disable it using this annotation will trigger a warning and have no effect. Therefore, the value of this annotation will always be set to `true`. + +- `traffic.kuma.io/transparent-proxy-config` + + This annotation is automatically applied in environments using [Kuma CNI]({{ docs }}/production/dp-config/cni/#configure-the-kuma-cni) instead of init containers. It contains the final configuration for installing the transparent proxy. Manually modifying or setting this annotation has no effect, regardless of whether Kuma CNI is used. Its primary purpose is to efficiently pass the transparent proxy configuration between Kubernetes workloads and the Kuma CNI, which handles the actual installation of the transparent proxy for those workloads. + +- `traffic.kuma.io/transparent-proxy-configmap-name` + + This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. + +### Automatically applied annotations + +Certain annotations are automatically added to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers), regardless of whether they are explicitly defined. These annotations reflect the final values used to configure the transparent proxy. For settings that can be manually specified, these annotations will still be applied, even if not explicitly provided, using values from the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration). + +The automatically applied annotations include: + +- `kuma.io/transparent-proxying` +- `kuma.io/sidecar-uid` +- `kuma.io/transparent-proxying-inbound-port` +- `kuma.io/transparent-proxying-outbound-port` +- `kuma.io/builtin-dns` +- `kuma.io/builtin-dns-port` +- `kuma.io/application-probe-proxy-port` +- `kuma.io/transparent-proxying-ebpf` +- `kuma.io/transparent-proxying-ebpf-bpf-fs-path` +- `kuma.io/transparent-proxying-ebpf-cgroup-path` +- `kuma.io/transparent-proxying-ebpf-tc-attach-iface` +- `kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name` +- `kuma.io/transparent-proxying-ebpf-programs-source-path` +- `kuma.io/transparent-proxying-ip-family-mode` +- `traffic.kuma.io/transparent-proxy-config` (only in environments using Kuma CNI) + +These annotations ensure that the proper configuration is automatically applied to each workload, aligning with the global and per-workload settings. + +## Order of precedence + +When using multiple configuration methods, it's important to understand the order in which they are applied to avoid conflicts and ensure the correct settings are used. + +1. Defaults (refer to [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) for exact values) + +2. [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration) + +3. [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) + +4. [Kubernetes Annotations](#method-3-kubernetes-annotations) diff --git a/app/_src/networking/transparent-proxy/configuration-on-universal.md b/app/_src/networking/transparent-proxy/configuration-on-universal.md new file mode 100644 index 000000000..845159cb5 --- /dev/null +++ b/app/_src/networking/transparent-proxy/configuration-on-universal.md @@ -0,0 +1,170 @@ +--- +title: Adjusting Transparent Proxy Configuration on Universal +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} + +{% assign tproxy = site.data.tproxy %} + +{% assign ref = docs | append: "/reference/transparent-proxy-configuration/" %} +{% assign ref-schema = ref | append: "#schema" %} +{% assign ref-env = ref | append: "#environment-variables" %} +{% assign ref-cli = ref | append: "#cli-flags" %} +{% assign ref-default = ref | append: "#default-values" %} +{% assign ref-full = ref | append: "#full-reference" %} + +The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This page explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one. + +## Configuration reference + +{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Full Reference]({{ ref-full }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). + +If you're only interested in specific parts of the reference, here are links to simplified sections: + +| Section | Description | +|:------------------------------------------------|:----------------------------------------------------------------------------------------| +| [**Schema**]({{ ref-schema }}) | A concise version of the configuration schema, including default values. | +| [**Environment Variables**]({{ ref-env }}) | A configuration structure showing fields and their corresponding environment variables. | +| [**CLI Flags**]({{ ref-cli }}) | A configuration structure showing fields and their corresponding CLI flags. | +| [**Default Values**]({{ ref-default }}) | A structure displaying only the fields with their default values. | + +## Methods of customizing the configuration + +In Universal environments, {{ Kuma }} provides three ways to adjust the transparent proxy configuration. Each method can be used on its own or combined with others if needed. + +{% warning %} +It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. +{% endwarning %} + +Here are the methods, listed by precedence, from lowest to highest. + + +### Method 1: YAML or JSON configuration + + +You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. + +{% tip %} +For the configuration schema in YAML format, refer to the [Schema]({{ ref-schema }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + +{% tip %} +For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs. +{% endtip %} + +Below are examples of using these flags in different ways: + +1. **Providing configuration via the `--config-file` flag** + + Assume you have a `config.yaml` file with the following content: + + ```yaml + kumaDPUser: dataplane + verbose: true + ``` + + You can install the transparent proxy using: + + ```sh + kumactl install transparent-proxy --config-file config.yaml + ``` + +2. **Passing configuration directly via the `--config` flag** + + To pass the configuration content directly: + + ```sh + kumactl install transparent-proxy --config "kumaDPUser: dataplane\nverbose: true" + ``` + + Alternatively: + + ```sh + kumactl install transparent-proxy --config "{ kumaDPUser: dataplane, verbose: true }" + ``` + + Both formats are valid YAML inputs. + +3. **Passing configuration via [STDIN](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin))** + + If you need to pass the configuration via STDIN, set `--config-file` to `-` as shown below: + + ```sh + echo " + kumaDPUser: dataplane + verbose: true + " | kumactl install transparent-proxy --config-file - + ``` + +### Method 2: Using environment variables + +You can customize configuration settings by using environment variables. For example: + +```sh +KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy +``` + +{% tip %} +To see all available environment variables, visit the [Environment Variables]({{ ref-env }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + +### Method 3: CLI flags + +Most configuration values can also be specified directly through CLI flags. For example: + +```sh +kumactl install transparent-proxy --kuma-dp-user dataplane --verbose +``` + +{% warning %} +The following settings cannot be modified directly via CLI flags (corresponding flags are not available): + +- `redirect.dns.resolvConfigPath` +- `redirect.inbound.includePorts` +- `redirect.inbound.excludePortsForUIDs` +- `redirect.outbound.enabled` +- `redirect.outbound.includePorts` +- `ebpf.instanceIPEnvVarName` +- `log.level` +- `cniMode` +{% endwarning %} + +{% tip %} +To see all available CLI flags, visit the [CLI Flags]({{ ref-cli }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + +## Order of precedence + +1. **Default Values** +2. **Values from** `--config` / `--config-file` **flags** +3. **Environment Variables** +4. **CLI Flags** + +To understand how the order of precedence works, consider this scenario: + +1. You have a `config.yaml` file with the following content: + + ```yaml + redirect: + dns: + port: 10001 + ``` + +2. You install the transparent proxy using this command: + + ```sh + KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT="10002" \ + kumactl install transparent-proxy \ + --config-file config.yaml \ + --redirect-dns-port 10003 + ``` + +3. In this situation, the possible values for `redirect.dns.port` are: + + - **`{{ tproxy.defaults.redirect.dns.port }}`** (Default Value) + - **`10001`** (From Config File) + - **`10002`** (From Environment Variable) + - **`10003`** (From CLI Flag) + +4. Since CLI flags have the highest precedence, the final value for `redirect.dns.port` will be **`10003`**. diff --git a/app/_src/networking/transparent-proxy/installing-on-universal.md b/app/_src/networking/transparent-proxy/installing-on-universal.md new file mode 100644 index 000000000..f1466573e --- /dev/null +++ b/app/_src/networking/transparent-proxy/installing-on-universal.md @@ -0,0 +1,267 @@ +--- +title: Installing Transparent Proxy on Universal +content_type: how-to +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +{% tip %} +These instructions apply to **Universal** mode, where {{ Kuma }} needs to be manually configured for each environment. In **Kubernetes** mode, the transparent proxy is set up automatically using the [`kuma-init` container]({{ docs }}/production/dp-config/dpp-on-kubernetes/) or [Kuma CNI]({{ docs }}/production/dp-config/cni/), so the steps below do not apply. +{% endtip %} + +This page provides instructions for setting up a transparent proxy in your service environment. A transparent proxy helps streamline service management and traffic routing within a mesh, directing all traffic through the data plane proxy without requiring changes to your application code. + +Once completed, your service will run under a transparent proxy, allowing you to use {{ Kuma }}'s service management features, like traffic control, observability, and security. + +Before starting, review the prerequisites below and adjust settings to fit your environment, including IP addresses, custom ports, and DNS configurations. + +## Terminology overview + +- **Service**: In this instruction, **service** refers to an application running in the environment where the transparent proxy is deployed. An exception is when we refer to [systemd](https://systemd.io/) services; in these cases, **service** specifically means a [systemd service unit](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html). + +## Prerequisites + +{%- capture control-plane-and-service-network-accessibility-warning %} +{% warning %} +For this instruction, the control plane **should not** be deployed in the same environment as the transparent proxy. This is because the transparent proxy redirects **all** traffic (unless specifically excluded) to `kuma-dp`, including traffic meant for the control plane. + +While it is technically possible to manually exclude control plane traffic during setup, this is complex and easy to misconfigure, as it requires excluding **all** necessary ports and routes. + +In real deployments, you can work around it by running the control plane and other components in separate network namespaces using systemd, which keeps control plane traffic separate from `kuma-dp` and the service. +{% endwarning %} +{%- endcapture %} + +{%- capture control-plane-and-service-network-accessibility-tip %} +{% tip %} +For deployment instructions, see [Deploy a single-zone control plane]({{ docs }}/production/cp-deployment/single-zone/). +{% endtip %} +{%- endcapture %} + +{%- capture data-plane-proxy-token-tip %} +{% tip %} +For instructions on generating this token, refer to the [Data plane proxy token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) section in the [Authentication with the data plane proxy]({{ docs }}/production/secure-deployment/dp-auth/#authentication-with-the-data-plane-proxy) documentation. +{% endtip %} +{%- endcapture %} + +{%- capture binary-availability-tip %} +{% tip %} +To easily download all necessary binaries, you can use the following script, which automatically detects your operating system and fetches the required binaries: + +```sh +curl -L {{ site.links.web }}{% if page.edition %}/{{ page.edition }}{% endif %}/installer.sh | VERSION={{ page.version_data.version }} sh - +``` +{:.no-line-numbers} + +Omitting the `VERSION` variable will install the latest version. +{% endtip %} +{% endcapture -%} + +1. **Control plane deployment and network accessibility**: Ensure {{ Kuma }}'s control plane is already deployed and accessible from the service via an IP address or DNS name. Adapt the steps below to reflect the correct address for your setup. + + {{ control-plane-and-service-network-accessibility-warning | indent }} + + {{ control-plane-and-service-network-accessibility-tip | indent }} + +2. **Service accessibility**: Ensure the environment with the transparent proxy and service is reachable by other services in the mesh via IP or DNS. Adjust the setup steps to match the appropriate address where the service is accessible. + +3. **Data plane proxy token**: Place the data plane proxy token at `/kuma/example-server-token` (or adjust the steps if stored elsewhere). + + {{ data-plane-proxy-token-tip | indent }} + +4. **Binary availability**: Ensure `kuma-dp`, `envoy`, and `coredns` binaries are accessible in `/usr/local/bin/`, and `kumactl` is in the system’s `PATH`. Adjust any subsequent commands if the binaries are located elsewhere. + + {{ binary-availability-tip | indent }} + +## Step 1: Create a dedicated user for kuma-dp + +For proper functionality, the service must run under a different user than the one designated for running `kuma-dp`. If both the service and `kuma-dp` are run by the same user, the transparent proxy will not work correctly, causing service traffic (inbound and outbound) to fail. To create a dedicated user for `kuma-dp`, use the following command: + +```sh +useradd -u {{ tproxy.defaults.kuma-dp.username }} -U {{ tproxy.defaults.kuma-dp.username }} +``` + +{% warning %} +In some Linux distributions, the `useradd` command may not be available. In such cases, follow the specific guidelines for your system to manually create a user with a `UID` of `{{ tproxy.defaults.kuma-dp.uid }}` and the username `{{ tproxy.defaults.kuma-dp.username }}`. +{% endwarning %} + + +## Step 2: Prepare the Dataplane resource + + +In transparent proxy mode, configure your `Dataplane` resource without the `networking.outbound` section. Instead, use `networking.transparentProxying` for handling traffic redirection. Here’s an example: + +If your `/kuma/example-server-dataplane.yaml` looks like this: + +```yaml +type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: example-server + outbound: + - port: 6379 + tags: + kuma.io/service: redis +``` + +After updating it for transparent proxy, it should look like this: + +```yaml +type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: example-server + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} +``` + +### Redirect ports + +In this example, `{{ tproxy.defaults.redirect.inbound.port }}` and `{{ tproxy.defaults.redirect.outbound.port }}` are the default ports for inbound and outbound traffic redirection. You can change these ports in the transparent proxy configuration during installation (`redirect.inbound.port` and `redirect.outbound.port`). For more details, see the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). + +{% warning %} +**Important:** If you use different ports, be sure to update all related configurations and steps to match the new values. +{% endwarning %} + +### Using variables in your configuration + +The placeholders `{% raw %}{{ name }}{% endraw %}`, `{% raw %}{{ address }}{% endraw %}`, and `{% raw %}{{ port }}{% endraw %}` are [Mustache templates](http://mustache.github.io/mustache.5.html), which will be dynamically filled using values passed via `--dataplane-var` CLI flags in a later step. + +In practice, if these values are static, you can simply hard-code them in your configuration. This feature is designed to allow more flexible and reusable resources, making it easier to dynamically adjust values when starting `kuma-dp`. + +### More resources + +For additional information on setting up the `Dataplane` resource, refer to the [Data Plane on Universal]({{ docs }}/production/dp-config/dpp-on-universal/#data-plane-on-universal) documentation. + +## Step 3: Start the service + +The service can be started in various ways depending on your environment and requirements. To keep this instruction simple, we’ll use Python 3’s built-in HTTP server. This server will listen on port `8080`, with both [STDOUT](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) and [STDERR](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) redirected to a `service.log` file in the current directory, running in the background. + +{% danger %} +**Remember that** the service must run under a **different** user than the one designated for `kuma-dp`. In the example below, the service will run as the user you're currently logged in as. **Ensure** that this is not the same user assigned to the `kuma-dp`. +{% enddanger %} + +To start the service: + +```sh +python3 -m http.server 8080 > service.log 2>&1 & +``` + +## Step 4: Start the kuma-dp + +If you are using `systemd` to manage processes, you can refer to the [Systemd documentation]({{ docs }}/production/cp-deployment/systemd/) for an example of a `systemd` resource that can be customized to run `kuma-dp` in your environment. + +Alternatively, if you're starting `kuma-dp` using a script or another form of automation, you can use `runuser` to run the process as the `{{ tproxy.defaults.kuma-dp.username }}` user. Below is an example of how to start `kuma-dp` with the necessary parameters: + +```sh +# Set the Control Plane address (IP or DNS) accessible by this environment +export CP_ADDRESS="..." + +# Set the Data Plane address (IP or DNS) for the current environment, accessible by +# other services +export DP_ADDRESS="..." + +runuser -u {{ tproxy.defaults.kuma-dp.username }} -- \ + /usr/local/bin/kuma-dp run \ + --cp-address="https://$CP_ADDRESS:5678" \ + --dataplane-token-file="/kuma/example-server-token" \ + --dataplane-file="/kuma/example-server-dataplane.yaml" \ + --dataplane-var="name=example-server-dataplane" \ + --dataplane-var="address=$DP_ADDRESS" \ + --dataplane-var="port=8080" \ + --binary-path="/usr/local/bin/envoy" \ + --dns-coredns-path="/usr/local/bin/coredns" +``` + +This command runs `kuma-dp` under the `{{ tproxy.defaults.kuma-dp.username }}` user, connects it to the control plane, and configures it with the necessary settings for the example server. Adjust the paths and values as needed for your specific setup. + +## Step 5: Install the transparent proxy + +Before proceeding with this step, please keep the following in mind: + +{% warning %} +`kumactl` will return an error if you attempt to install the transparent proxy without `root` privileges. Ensure that you run the command as `root`. +{% endwarning %} + +{% warning %} +Once the transparent proxy is installed, all traffic configured for redirection will be immediately routed to `kuma-dp`. Therefore, it's important to start `kuma-dp` **before** installing the transparent proxy. If `kuma-dp` is not running, redirected traffic will be dropped, leading to a potential loss of connectivity (including SSH connections if port `22` hasn't been excluded). + +We strongly recommend starting `kuma-dp` **before** installing the transparent proxy. However, if you choose to install the transparent proxy first, make sure to exclude SSH traffic, for example by configuring `redirect.inbound.excludePorts` with `--exclude-inbound-ports` flag: + +```sh +kumactl install transparent-proxy --redirect-dns --exclude-inbound-ports "22" +``` +{% endwarning %} + +{% danger %} +The transparent proxy **must** be configured to use **the same** user as the one running the `kuma-dp` process to function properly. +{% enddanger %} + +{% danger %} +The following command **will modify** the host's `iptables` rules. If your environment already has existing `iptables` rules, ensure that the changes made by `kumactl` are compatible with your setup. You can check compatibility by running the command in dry-run mode using the `--dry-run` flag. +{% enddanger %} + +To install the transparent proxy in your environment, run the following command: + +```sh +kumactl install transparent-proxy --redirect-dns +``` + +This will result in the following: + +- The transparent proxy will be set up to use the `{{ tproxy.defaults.kuma-dp.username }}` user as the designated user for running the `kuma-dp` process. + + {% capture default-kuma-dp-user-lookup-tip %} + {% tip %} + By default, `kumactl` searches for a user with UID `{{ tproxy.defaults.kuma-dp.uid }}` or the username `{{ tproxy.defaults.kuma-dp.username }}`. If you prefer to use a custom username or UID, you can specify it using the `--kuma-dp-user` flag. If the specified user cannot be found, the installation process will fail with an error. + {% endtip %} + {% endcapture %} + {{ default-kuma-dp-user-lookup-tip | indent }} + +- All **incoming traffic** will be redirected to `kuma-dp` on port `{{ tproxy.defaults.redirect.inbound.port }}`. + + {% capture default-redirect-port-inbound-tip %} + {% tip %} + Port `{{ tproxy.defaults.redirect.inbound.port }}` is the default for redirecting incoming traffic. If you used a different port in your `Dataplane` resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the `redirect.inbound.port` setting during installation, for example by using the `--redirect-inbound-port` flag. + {% endtip %} + {% endcapture %} + {{ default-redirect-port-inbound-tip | indent }} + +- All **outgoing traffic** will be redirected to `kuma-dp` on default port `{{ tproxy.defaults.redirect.outbound.port }}`. + + {% capture default-redirect-port-outbound-tip %} + {% tip %} + Port `{{ tproxy.defaults.redirect.outbound.port }}` is the default used for redirecting outgoing traffic. If you used a different port in your `Dataplane` resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the `redirect.outbound.port` setting during installation, for example by using the `--redirect-outbound-port` flag. + {% endtip %} + {% endcapture %} + {{ default-redirect-port-outbound-tip | indent }} + +- DNS traffic directed to the DNS servers configured in `{{ tproxy.defaults.resolv.conf.path }}` will be redirected to the `coredns` managed by `kuma-dp` on port `{{ tproxy.defaults.redirect.dns.port }}`. + + {% capture default-redirect-port-dns-tip %} + {% tip %} + Port `{{ tproxy.defaults.redirect.dns.port }}` is the default used for redirecting DNS traffic. If you wish to modify this port, it is crucial to ensure consistency between the transparent proxy and `kuma-dp`. In this case, you must update the `kuma-dp run` command to include the `--dns-coredns-port` flag with the desired custom port. To adjust it for the transparent proxy, modify the `redirect.dns.port` setting during installation, for example by using the `--redirect-dns-port` flag. + {% endtip %} + {% endcapture %} + {{ default-redirect-port-dns-tip | indent }} + + {% capture resolv-conf-tip %} + {% tip %} + `{{ tproxy.defaults.resolv.conf.path }}` is the file used by default to parse DNS servers for redirecting DNS traffic through the transparent proxy. This file is relevant only if you opt to redirect DNS traffic specifically to the DNS servers listed within it (for example, by using the `--redirect-dns` flag during installation). If you're redirecting **all** DNS traffic (for example, by using the `--redirect-all-dns-traffic` flag), this path becomes irrelevant. + + **We strongly recommend against** changing this path. However, if your environment uses a different file to specify DNS servers (which must follow the same format as `{{ tproxy.defaults.resolv.conf.path }}`), you can adjust it by modifying the `redirect.dns.resolvConfigPath` setting during installation. This can be done, for example, using the `KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH` environment variable. + {% endtip %} + {% endcapture %} + {{ resolv-conf-tip | indent }} diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md new file mode 100644 index 000000000..7509ee6a8 --- /dev/null +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -0,0 +1,129 @@ +--- +title: Transparent Proxy +content_type: how-to +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +{% capture tproxy-config-reference-info %} +For a full list of transparent proxy settings with examples and configuration options, see the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). +{% endcapture %} + +A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ Kuma }}, it captures this traffic and routes it to the [data plane proxy]({{ docs }}/production/dp-config/dpp/#data-plane-proxy), allowing [Mesh policies]({{ docs }}/policies/introduction/#policies) to be applied. + +{{ Kuma }} uses [iptables](https://linux.die.net/man/8/iptables) and also has experimental support for [`eBPF`](#transparent-proxy-with-ebpf-experimental) to make this possible. + +{% tip %} +For details on how the transparent proxy works in {{ Kuma }}, see the [Technical Overview]({{ docs }}/networking/transparent-proxy/technical-overview/). +{% endtip %} + +## Kubernetes + +In [Kubernetes mode]({{ docs }}/introduction/architecture/#kubernetes-mode), the transparent proxy is automatically set up through the `kuma-init` container or [Kuma CNI]({{ docs }}/production/dp-config/cni/). By default, it intercepts all incoming and outgoing traffic and routes it through the `kuma-dp` sidecar container, so no changes to the application code are needed. + +{{ Kuma }} works smoothly with [Kubernetes DNS for Services and Pods](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) and provides its own [Kuma DNS]({{ docs }}/networking/dns/), which is especially helpful in multi-zone setups for cross-zone service discovery. + +In this mode, {{ Kuma }} requires the transparent proxy to be enabled, so it **cannot be turned off**. + +### Configuration +{:#kubernetes-installation} + +If the default settings don’t fit your needs, see [Adjusting Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/) for ways to change settings and their recommended uses. + +{{ tproxy-config-reference-info }} + +## Universal + +Using the transparent proxy in [Universal mode]({{ docs }}/introduction/architecture/#universal-mode) makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: + +- **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. Here’s an example without outbound entries: + + ```yaml + type: Dataplane + name: {% raw %}{{ name }}{% endraw %} + networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: demo-client + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} + ``` + +- **Easier service naming**: Use the `.mesh` [DNS domain]({{ docs }}/networking/dns/) to connect to services, like `https://service-1.mesh`, without needing `localhost` and ports from the `Dataplane` resource. + +- **Flexible service naming with [VirtualOutbound]({{ docs }}/policies/virtual-outbound) policy**: It lets you: + + - Keep existing DNS names when moving to the service mesh. + - Assign multiple DNS names to a service for renaming or convenience. + - Create specific routes, like targeting individual StatefulSet Pods or service versions. + - Expose multiple inbounds for a service on different ports. + +- **Simpler security, tracing, and observability**: Transparent proxy makes managing these features easier, with no extra setup required. + +### Installation +{:#universal-installation} + +To learn how to integrate the transparent proxy with your existing services or set up a service environment from scratch, see [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/). + +### Configuration +{:#universal-configuration} + +If the default settings don’t fit your needs, see [Adjusting Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/configuration-on-universal/) for ways to modify settings and their recommended uses. + +{{ tproxy-config-reference-info }} + +### firewalld support + +{% tip %} +In **Kubernetes** mode, transparent proxy is automatically set up using the `kuma-init` container or [Kuma CNI]({{ docs }}/production/dp-config/cni/). Since the proxy is reinstalled each time your workload restarts, there is no need to persist it. This feature is specifically designed for **Universal** environments. +{% endtip %} + +The changes made by running `kumactl install transparent-proxy` **will not persist** after a reboot. To ensure persistence, you can either add this command to your system's start-up scripts or leverage `firewalld` for managing `iptables`. + +If you prefer using `firewalld`, you can include the `--store-firewalld` flag when installing the transparent proxy. This will store the `iptables` rules in `/etc/firewalld/direct.xml`, ensuring they persist across system reboots. Here's an example: + +```sh +kumactl install transparent-proxy --redirect-dns --store-firewalld +``` + +{% warning %} +**Important:** Currently, there is no uninstall command for this feature. If needed, you will have to manually clean up the `firewalld` configuration. +{% endwarning %} + + +### Transparent proxy with eBPF (experimental) + + +Starting from {{ Kuma }} 2.0 you can set up transparent proxy to use eBPF instead of iptables. + +{% warning %} +To use the transparent proxy with eBPF your environment has to use `Kernel >= 5.7` and have `cgroup2` available +{% endwarning %} + +{% tabs ebpf useUrlFragment=false %} +{% tab ebpf Kubernetes %} +```sh +kumactl install control-plane \ + --set "{{ site.set_flag_values_prefix }}experimental.ebpf.enabled=true" \ + | kubectl apply -f- +``` +{% endtab %} + +{% tab ebpf Universal %} +```sh +kumactl install transparent-proxy \ + --ebpf-enabled \ + --ebpf-instance-ip \ + --ebpf-programs-source-path +``` + +{% tip %} +If your environment contains more than one non-loopback network interface, and you want to specify explicitly which one should be used for transparent proxying you should provide it using `--ebpf-tc-attach-iface ` flag, during transparent proxy installation. +{% endtip %} +{% endtab %} +{% endtabs %} diff --git a/app/_src/networking/transparent-proxy/reachable-backends.md b/app/_src/networking/transparent-proxy/reachable-backends.md new file mode 100644 index 000000000..999a6ff33 --- /dev/null +++ b/app/_src/networking/transparent-proxy/reachable-backends.md @@ -0,0 +1,184 @@ +--- +title: Reachable Backends +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +{% warning %} +This feature works only when [MeshService]({{ docs }}/networking/meshservice) is enabled. +{% endwarning %} + +Reachable Backends provides similar functionality to [Reachable Services]({{ docs }}/networking/transparent-proxy/reachable-services/), but it applies to resources such as [MeshService]({{ docs }}/networking/meshservice), [MeshExternalService]({{ docs }}/networking/meshexternalservice), and [MeshMultiZoneService]({{ docs }}/networking/meshmultizoneservice). + +By default, each data plane proxy tracks all other data planes in the mesh, which can impact performance and use more resources. Configuring `reachableBackends` allows you to specify only the services your application actually needs to communicate with, improving efficiency. + +Unlike Reachable Services, Reachable Backends uses a structured model to define the resources. + +### Model + +- **refs**: Lists the resources your application needs to connect with, including: + - **kind**: Type of resource. Options include: + - **MeshService** + - **MeshExternalService** + - **MeshMultiZoneService** + - **name**: Name of the resource. + - **namespace**: (Kubernetes only) Namespace where the resource is located. Required if using `namespace`. + - **labels**: A list of labels to match resources. You can define either `labels` or `name`. + - **port**: (Optional) Port for the service, used with `MeshService` and `MeshMultiZoneService`. + +{% tabs reachable-backends-model useUrlFragment=false %} +{% tab reachable-backends-model Kubernetes %} +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: demo-client + namespace: kuma-demo + annotations: + kuma.io/reachable-backends: | + refs: + - kind: MeshService + name: redis + namespace: kuma-demo + port: 8080 + - kind: MeshMultiZoneService + labels: + kuma.io/display-name: test-server + - kind: MeshExternalService + name: mes-http + namespace: kuma-system +... +``` +{% endtab %} +{% tab reachable-backends-model Universal %} +```yaml +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: demo-client + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} + reachableBackends: + refs: + - kind: MeshService + name: redis + - kind: MeshMultiZoneService + labels: + kuma.io/display-name: test-server + - kind: MeshExternalService + name: mes-http +``` +{% endtab %} +{% endtabs %} + +### Examples + + +#### `demo-client` communicates only with `redis` on port 6379 + + +{% tabs reachable-backends useUrlFragment=false %} +{% tab reachable-backends Kubernetes %} +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: demo-client + namespace: kuma-demo + annotations: + kuma.io/reachable-backends: | + refs: + - kind: MeshService + name: redis + namespace: kuma-demo + port: 6379 +... +``` +{% endtab %} +{% tab reachable-backends Universal %} +```yaml +type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: demo-client + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} + reachableBackends: + refs: + - kind: MeshService + name: redis + port: 6379 +``` +{% endtab %} +{% endtabs %} + + +#### `demo-client` doesn’t need to communicate with any service + + +{% tabs reachable-backends-no-services useUrlFragment=false %} +{% tab reachable-backends-no-services Kubernetes %} +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: demo-client + namespace: kuma-demo + annotations: + kuma.io/reachable-backends: "" +... +``` +{% endtab %} +{% tab reachable-backends-no-services Universal %} +```yaml +type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: demo-client + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} + reachableBackends: {} +``` +{% endtab %} +{% endtabs %} + + +#### `demo-app` communicates with all MeshServices in the `kuma-demo` namespace + + +{% tabs reachable-backends-in-namespace useUrlFragment=false %} +{% tab reachable-backends-in-namespace Kubernetes %} +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: demo-app + namespace: kuma-demo + annotations: + kuma.io/reachable-backends: | + refs: + - kind: MeshService + labels: + k8s.kuma.io/namespace: kuma-demo +... +``` +{% endtab %} +{% endtabs %} diff --git a/app/_src/networking/transparent-proxy/reachable-services.md b/app/_src/networking/transparent-proxy/reachable-services.md new file mode 100644 index 000000000..fff3275f9 --- /dev/null +++ b/app/_src/networking/transparent-proxy/reachable-services.md @@ -0,0 +1,62 @@ +--- +title: Reachable Services +--- + +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +When the transparent proxy is enabled, {{ Kuma }} automatically configures each data plane proxy to connect with every other data plane proxy in the same mesh. This setup ensures broad service-to-service communication but can create issues in large service meshes: + +- **Increased Memory Usage**: The configuration for each data plane proxy can consume significant memory as the mesh grows. +- **Slower Propagation**: Even small configuration changes for one service must be propagated to all data planes, which can be slow and resource-intensive. +- **Excessive Traffic**: Frequent updates generate additional traffic between the control plane and data plane proxies, especially when services are added or changed often. + +In real-world scenarios, services usually need to communicate only with a few other services rather than all services in the mesh. To address these challenges, {{ Kuma }} offers the **Reachable Services** feature, allowing you to define only the services that each proxy should connect to. Specifying reachable services helps reduce memory usage, improves configuration propagation speed, and minimizes unnecessary traffic. + +Here’s how to configure reachable services: + +{% tabs reachable-services useUrlFragment=false %} +{% tab reachable-services Kubernetes %} +Specify the list of reachable services in the `kuma.io/transparent-proxying-reachable-services` annotation, separating each service with a comma. Your workload configuration could look like this: + +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: demo-client + annotations: + kuma.io/transparent-proxying-reachable-services: "redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200" +... +``` + +You can update your workload manifests manually or use a command like: + +```sh +kumactl annotate pods example-app \ + "kuma.io/transparent-proxying-reachable-services=redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200" +``` +{% endtab %} +{% tab reachable-services Universal %} +To specify reachable services in your `Dataplane` resource, add them under the `networking.transparentProxying.reachableServices` path. Here’s an example: + +```yaml +type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: demo-client + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} + reachableServices: + - redis_kuma-demo_svc_6379 + - elastic_kuma-demo_svc_9200 +``` +{% endtab %} +{% endtabs %} + +This configuration ensures that `example-app` only connects to `redis_kuma-demo_svc_6379` and `elastic_kuma-demo_svc_9200`, reducing the overhead associated with managing connections to all services in the mesh. diff --git a/app/_src/networking/transparent-proxy/technical-overview.md b/app/_src/networking/transparent-proxy/technical-overview.md new file mode 100755 index 000000000..701318f9d --- /dev/null +++ b/app/_src/networking/transparent-proxy/technical-overview.md @@ -0,0 +1,188 @@ +--- +title: Technical Overview +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} + +## What is transparent proxying? + +A transparent proxy is a type of server that can intercept network traffic to and from a service without changes to the client application code. In the case of {{ Kuma }} it is used to capture traffic and redirect it to `kuma-dp` so Mesh policies can be applied. + +To accomplish this, {{ Kuma }} utilizes [`iptables`](https://linux.die.net/man/8/iptables) and offers additional, experimental support for [`eBPF`]({{ docs }}/production/dp-config/cni/#merbridge-cni-with-ebpf). The examples provided in this section will concentrate on iptables to clearly illustrate the point. + +Below is a high level visualization of how transparent proxying works + + +{% mermaid %} + sequenceDiagram + autonumber + participant Browser as Client
(for example, mobile app) + participant Kernel as Kernel + participant ServiceMeshIn as kuma sidecar(15006) + participant Node as example.com:5000
(Front-end App) + participant ServiceMeshOut as kuma sidecar(15001) + Browser->>+Kernel: GET / HTTP1.1
Host: example.com:5000 + + rect rgb(233,233,233) + Note over Kernel,ServiceMeshOut: EXAMPLE.COM + Note over Node: (Optional)
Apply inbound policies + Note over ServiceMeshOut: (Optional)
Apply outbound policies + Kernel->>+ServiceMeshIn: Capture inbound TCP traffic
and Redirect to the sidecar
(listener port 15006) + ServiceMeshIn->>+Node: Redirect to the
original destination
(example.com:5000) + Node->>+Kernel: Send the
Front-end Response + Kernel->>+ServiceMeshOut: Capture outbound TCP traffic
and Redirect to the sidecar
(listener port 15001) + end + ServiceMeshOut->>+Browser: Response to Client + %% Note over Browser,ServiceMeshOut: Traffic Flow Sequence +{% endmermaid %} + + +## A life without transparent proxying + +If you choose to not use transparent proxying, or you are running on a platform where transparent proxying is not available, there are some additional considerations. + +- You will need to specify inbound and outbound ports to capture traffic on +- `.mesh` addresses are unavailable +- You may need to update your `application` code to use the new capture ports +- No support for [VirtualOutbound]({{ docs }}/policies/virtual-outbound) policies + +Without manipulating iptables to redirect traffic you will need to explicitly tell `kuma-dp` where to listen to capture it. As noted, this can require changes to your application code as seen below: + +Here we specify that we will listen on the address `10.119.249.39:15000` (line 7). This in turn creates an envoy listener for the port. When consuming a service over this `15000` it will cause traffic to redirect to `127.0.0.1:5000` (line 8) where our app is running. + +```yaml + type: Dataplane + mesh: default + name: demo-app + networking: + address: 10.119.249.39 + inbound: + - port: 15000 + servicePort: 5000 + serviceAddress: 127.0.0.1 + tags: + kuma.io/service: app + kuma.io/protocol: http +``` + +## How it works + + +### Inbound TCP traffic + + +The inbound port, `15006`, is the default for capturing requests to the system. This rule allows us to capture and redirect ALL TCP traffic to port `15006`. + +```sh +iptables --table nat --append KUMA_MESH_INBOUND_REDIRECT --protocol tcp --jump REDIRECT --to-ports 15006 +``` + +An envoy listener is also created for this port which we can see in the admin interface (`:9901/config_dump`). In the below example you can see the listener created on all interfaces (line 8) and port `15006` (line 9). + +```json + "name": "inbound:passthrough:ipv4", + "active_state": { + "listener": { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "inbound:passthrough:ipv4", + "address": { + "socket_address": { + "address": "0.0.0.0", + "port_value": 15006 + } + }, + ... + "use_original_dst": true, + "traffic_direction": "INBOUND", +``` + +Notice the setting [use_original_dst](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto) (line 13). This listener will send traffic to a special type of cluster, `ORIGINAL_DST`. This is important since we are redirecting traffic here based on the iptables rules, which means when this service was requested it was not likely it was requested over this port, `15006`, but rather whatever the target application is listening on (i.e. `demo-app` port `5000`). + +```json + "name": "inbound:10.244.0.6:5000", + "active_state": { + "version_info": "9dac7d53-3560-4ad4-ba42-c7e563db958e", + "listener": { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "inbound:10.244.0.6:5000", + "address": { + "socket_address": { + "address": "10.244.0.6", + "port_value": 5000 + } + } + } + } +``` + +Using the Kuma counter demo app as an example, when the client needs to talk to the node app, it does not do so over `15006`, but rather the actual application port, `5000`. This is the "transparent" part of the proxying as it is not expected that apps will need to be redesigned or changed in any way to utilize mesh. + +So, when the request comes into the system, the iptables rule grabs the traffic and sends it to envoy port `15006`. Once here, we check where the request was originally intended to go, in this case `5000` and forward it. + +A further review of the envoy config will show our Node app listener where the IP address, `10.244.0.6`, is that of the `demo-app` pod. Now that envoy is in control of the traffic we can now (optionally) apply filters/Mesh policies. + + +```json + "name": "inbound:10.244.0.6:5000", + "active_state": { + "version_info": "9dac7d53-3560-4ad4-ba42-c7e563db958e", + "listener": { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "inbound:10.244.0.6:5000", + "address": { + "socket_address": { + "address": "10.244.0.6", + "port_value": 5000 + } + }, + "filter_chains": [ + { + "filters": [ + { + "name": "envoy.filters.network.http_connection_manager", + "typed_config": { + "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager", + "stat_prefix": "localhost_5000", + "route_config": { + "http_filters": [ + { + "name": "envoy.filters.http.fault", + "typed_config": { + "@type": "type.googleapis.com/envoy.extensions.filters.http.fault.v3.HTTPFault", + "delay": { + "fixed_delay": "5s", + "percentage": { + "numerator": 50, + "denominator": "TEN_THOUSAND" +... +``` + + +### Outbound TCP traffic + + +The outbound port, `15001`, is the default for capturing outbound traffic from the system. That is, traffic leaving the mesh. This rule allow us to capture and redirect all TCP traffic to `15001`. + +```sh +iptables --table nat --append KUMA_MESH_OUTBOUND_REDIRECT --protocol tcp --jump REDIRECT --to-ports 15001 +``` + +An envoy listener is also created for this port which we can see in the admin interface (`:9901/config_dump`). In the below example you can see the listener created on all interfaces (line 8) and port `15001` (line 9). This will allow us to capture and outbound traffic policies. + +```json + "name": "outbound:passthrough:ipv4", + "active_state": { + "listener": { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "outbound:passthrough:ipv4", + "address": { + "socket_address": { + "address": "0.0.0.0", + "port_value": 15001 + } + }, + ... + "use_original_dst": true, + "traffic_direction": "OUTBOUND" +``` diff --git a/app/_src/networking/transparent-proxy/upgrading-on-universal.md b/app/_src/networking/transparent-proxy/upgrading-on-universal.md new file mode 100644 index 000000000..b3d112e13 --- /dev/null +++ b/app/_src/networking/transparent-proxy/upgrading-on-universal.md @@ -0,0 +1,55 @@ +--- +title: Upgrading Transparent Proxy on Universal +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} + +{% tip %} +In **Kubernetes** mode, transparent proxy automatically updates with the {{ Kuma }} version upgrade. No additional steps are required for workloads, as the transparent proxy aligns with the {{ Kuma }} version. The following guide applies only to **Universal** mode. +{% endtip %} + +The core `iptables` rules applied by {{ Kuma }}'s transparent proxy rarely change, but occasionally new features may require updates. To upgrade the transparent proxy on Universal environments, follow these steps: + +### Step 1: Cleanup existing iptables rules (conditional) + +{% warning %} +If you're upgrading from {{ Kuma }} version 2.9 or later, and you have **not** manually disabled the automatic addition of comments by setting `comments.disabled` to `true` in the transparent proxy configuration, **this step is unnecessary**. + +Starting with {{ Kuma }} 2.9, all `iptables` rules are tagged with comments, allowing {{ Kuma }} to track rule ownership. This enables `kumactl` to automatically clean up any existing `iptables` rules or custom chains created by previous versions of the transparent proxy. This process runs automatically at the start of the installation, eliminating the need for any manual cleanup beforehand. +{% endwarning %} + +To manually remove existing `iptables` rules, you can either restart the host (if the rules were not persisted using system start-up scripts or `firewalld`), or run the following commands: + +{% danger %} +These commands will remove **all** `iptables` rules and **all** custom chains in the specified tables, including those created by {{ Kuma }} as well as any other applications or services. +{% enddanger %} + +```sh +iptables --table nat --flush # Flush all rules in the nat table (IPv4) +ip6tables --table nat --flush # Flush all rules in the nat table (IPv6) +iptables --table nat --delete-chain # Delete all custom chains in the nat table (IPv4) +ip6tables --table nat --delete-chain # Delete all custom chains in the nat table (IPv6) + +# The raw table contains rules for DNS traffic redirection +iptables --table raw --flush # Flush all rules in the raw table (IPv4) +ip6tables --table raw --flush # Flush all rules in the raw table (IPv6) + +# The mangle table contains rules to drop invalid packets +iptables --table mangle --flush # Flush all rules in the mangle table (IPv4) +ip6tables --table mangle --flush # Flush all rules in the mangle table (IPv6) +``` + +### Step 2: Install new transparent proxy + +After clearing the `iptables` rules (if necessary), reinstall the transparent proxy by running: + +```sh +kumactl install transparent-proxy [...] +``` + +This command will install the new version of the transparent proxy with the specified configuration. Adjust the flags as needed to suit your environment. + +{% tip %} +For a comprehensive documentation of installing the transparent proxy in Universal mode, including details on preparing the environment, understanding any restrictions, and configuring `Dataplane` objects to work with the transparent proxy, refer to the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) guide. +{% endtip %} diff --git a/app/_src/reference/transparent-proxy-configuration.md b/app/_src/reference/transparent-proxy-configuration.md new file mode 100644 index 000000000..77fcfbd11 --- /dev/null +++ b/app/_src/reference/transparent-proxy-configuration.md @@ -0,0 +1,739 @@ +--- +title: Transparent Proxy Configuration +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} + +{% assign noflag = "# can't be modified via CLI flag" %} + +During transparent proxy installation {{ Kuma }} under the hood is using a common structure, which can be modified in multiple different ways. By modifying it you are able to for example exclude some ports or IPs from transparent proxy redirection, configure if it should handle both IPv4 and IPv6 or just IPv4 traffic and more. + +## Simplified reference + +This section provides a simplified version of the [Full Reference](#full-reference). It's useful when you want to view the entire configuration in context without diving into the specifics of each individual setting. + +### Schema + +Below is a concise schema of the transparent proxy configuration, including default values: + +```yaml +# The username or UID of the user that will run kuma-dp +kumaDPUser: string +# The IP family mode used for configuring traffic redirection in the transparent proxy +ipFamilyMode: enum # default: "dualstack" +redirect: + inbound: + # Enables inbound traffic redirection + enabled: bool # default: true + # Port used for redirecting inbound traffic + port: Port # default: 15006 + # List of ports to include in inbound traffic redirection + includePorts: []Port + # List of ports to exclude from inbound traffic redirection + excludePorts: []Port + # List of IP addresses to exclude from inbound traffic redirection for specific ports + excludePortsForIPs: []string + # List of UIDs to exclude from inbound traffic redirection for specific ports + excludePortsForUIDs: []string + # Inserts the redirection rule at the beginning of the chain instead of appending it + insertRedirectInsteadOfAppend: bool + outbound: + # Enables outbound traffic redirection + enabled: bool # default: true + # Port used for redirecting outbound traffic + port: Port # default: 15001 + # List of ports to include in outbound traffic redirection + includePorts: []Port + # List of ports to exclude from outbound traffic redirection + excludePorts: []Port + # List of IP addresses to exclude from outbound traffic redirection for specific ports + excludePortsForIPs: []string + # List of UIDs to exclude from outbound traffic redirection for specific ports + excludePortsForUIDs: []string + # Inserts the redirection rule at the beginning of the chain instead of appending it + insertRedirectInsteadOfAppend: bool + dns: + # Enables DNS redirection in the transparent proxy + enabled: bool + # The port on which the DNS server listens + port: Port # default: 15053 + # Redirect all DNS queries + captureAll: bool + # Disables conntrack zone splitting, which can prevent potential DNS issues + skipConntrackZoneSplit: bool + # Path to the system's resolv.conf file + resolvConfigPath: string # default: "/etc/resolv.conf" + vnet: + # Specifies virtual networks using the format interfaceName:CIDR + networks: []string +ebpf: + # Enables eBPF support for handling traffic redirection in the transparent proxy + enabled: bool + instanceIP: string + # The name of the environment variable containing the IP address of the instance (pod/vm) where transparent proxy will be installed + instanceIPEnvVarName: string + # The path of the BPF filesystem + bpffsPath: string # default: "/run/kuma/bpf" + # The path of cgroup2 + cgroupPath: string # default: "/sys/fs/cgroup" + # Path where compiled eBPF programs and other necessary files for eBPF mode can be found + programsSourcePath: string # default: "tmp/kuma-ebpf" + # The network interface for TC eBPF programs to bind to + tcAttachIface: string +retry: + # The maximum number of retry attempts for operations + maxRetries: uint # default: 4 + # The time duration to wait between retry attempts + sleepBetweenRetries: Duration # default: "2s" +iptablesExecutables: + # Custom path for the iptables executable (IPv4) + iptables: string + # Custom path for the iptables-save executable (IPv4) + iptables-save: string + # Custom path for the iptables-restore executable (IPv4) + iptables-restore: string + # Custom path for the ip6tables executable (IPv6) + ip6tables: string + # Custom path for the ip6tables-save executable (IPv6) + ip6tables-save: string + # Custom path for the ip6tables-restore executable (IPv6) + ip6tables-restore: string +log: + # Specifies the log level for iptables logging as defined by netfilter + level: enum # default: 7 + # Enables logging of iptables rules for diagnostics and monitoring + enabled: bool +comments: + # Disables comments in the generated iptables rules + disabled: bool +# Time in seconds to wait for acquiring the xtables lock before failing +wait: uint # default: 5 +# Time interval between retries to acquire the xtables lock in seconds +waitInterval: uint +# Drops invalid packets to avoid connection resets in high-throughput scenarios +dropInvalidPackets: bool +# Enables firewalld support to store iptables rules +storeFirewalld: bool +cniMode: bool +dryRun: bool +# Enables verbose mode with longer argument/flag names and additional comments +verbose: bool +``` + +**Custom Types** + +- `Port` - uint16 value greater than `0` +- `Duration` - string representation of time duration, that is `"10s"`, `"20m"`, `"1h"` etc. + +### Environment variables + +The following structure lists the settings along with their corresponding environment variables for customization: + +```yaml +kumaDPUser: KUMA_TRANSPARENT_PROXY_KUMA_DP_USER +ipFamilyMode: KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE +redirect: + inbound: + enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_ENABLED + port: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_PORT + includePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INCLUDE_PORTS + excludePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS + excludePortsForIPs: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS + excludePortsForUIDs: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_UIDS + insertRedirectInsteadOfAppend: KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND + outbound: + enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_ENABLED + port: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_PORT + includePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INCLUDE_PORTS + excludePorts: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS + excludePortsForIPs: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS + excludePortsForUIDs: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_UIDS + insertRedirectInsteadOfAppend: KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND + dns: + enabled: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_ENABLED + port: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT + captureAll: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_CAPTURE_ALL + skipConntrackZoneSplit: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_SKIP_CONNTRACK_ZONE_SPLIT + resolvConfigPath: KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH + vnet: + networks: KUMA_TRANSPARENT_PROXY_REDIRECT_VNET_NETWORKS +ebpf: + enabled: KUMA_TRANSPARENT_PROXY_EBPF_ENABLED + instanceIP: KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP + instanceIPEnvVarName: KUMA_TRANSPARENT_PROXY_EBPF_INSTANCE_IP_ENV_VAR_NAME + bpffsPath: KUMA_TRANSPARENT_PROXY_EBPF_BPFFS_PATH + cgroupPath: KUMA_TRANSPARENT_PROXY_EBPF_CGROUP_PATH + programsSourcePath: KUMA_TRANSPARENT_PROXY_EBPF_PROGRAMS_SOURCE_PATH + tcAttachIface: KUMA_TRANSPARENT_PROXY_EBPF_TC_ATTACH_IFACE +retry: + maxRetries: KUMA_TRANSPARENT_PROXY_RETRY_MAX_RETRIES + sleepBetweenRetries: KUMA_TRANSPARENT_PROXY_RETRY_SLEEP_BETWEEN_RETRIES +iptablesExecutables: KUMA_TRANSPARENT_PROXY_IPTABLES_EXECUTABLES +log: + enabled: KUMA_TRANSPARENT_PROXY_LOG_ENABLED + level: KUMA_TRANSPARENT_PROXY_LOG_LEVEL +comments: + disabled: KUMA_TRANSPARENT_PROXY_COMMENTS_DISABLED +wait: KUMA_TRANSPARENT_PROXY_WAIT +waitInterval: KUMA_TRANSPARENT_PROXY_WAIT_INTERVAL +dropInvalidPackets: KUMA_TRANSPARENT_PROXY_DROP_INVALID_PACKETS +storeFirewalld: KUMA_TRANSPARENT_PROXY_STORE_FIREWALLD +cniMode: KUMA_TRANSPARENT_PROXY_CNI_MODE +dryRun: KUMA_TRANSPARENT_PROXY_DRY_RUN +verbose: KUMA_TRANSPARENT_PROXY_VERBOSE +``` + +### CLI flags + +This structure outlines the settings and their associated CLI flags for modification: + +```yaml +kumaDPUser: --kuma-dp-user +ipFamilyMode: --ip-family-mode +redirect: + dns: + enabled: --redirect-dns + port: --redirect-dns-port + captureAll: --redirect-all-dns-traffic + skipConntrackZoneSplit: --skip-dns-conntrack-zone-split + resolvConfigPath: {{ noflag }} + inbound: + enabled: --redirect-inbound + port: --redirect-inbound-port + includePorts: {{ noflag }} + excludePorts: --exclude-inbound-ports + excludePortsForIPs: --exclude-inbound-ips + excludePortsForUIDs: {{ noflag }} + insertRedirectInsteadOfAppend: --redirect-inbound-insert-instead-of-append + outbound: + enabled: {{ noflag }} + port: --redirect-outbound-port + includePorts: {{ noflag }} + excludePorts: --exclude-outbound-ports + excludePortsForIPs: --exclude-outbound-ips + excludePortsForUIDs: --exclude-outbound-ports-for-uids + insertRedirectInsteadOfAppend: --redirect-outbound-insert-instead-of-append + vnet: + networks: --vnet +ebpf: + enabled: --ebpf-enabled + instanceIP: --ebpf-instance-ip + instanceIPEnvVarName: {{ noflag }} + bpffsPath: --ebpf-bpffs-path + cgroupPath: --ebpf-cgroup-path + programsSourcePath: --ebpf-programs-source-path + tcAttachIface: --ebpf-tc-attach-iface +retry: + maxRetries: --max-retries + sleepBetweenRetries: --sleep-between-retries +iptablesExecutables: --iptables-executables +log: + enabled: --iptables-logs + level: {{ noflag }} +comments: + disabled: --disable-comments +wait: --wait +waitInterval: --wait-interval +dropInvalidPackets: --drop-invalid-packets +storeFirewalld: --store-firewalld +cniMode: {{ noflag }} +dryRun: --dry-run +verbose: --verbose +``` + +### Default values + +Here is a configuration that only shows the settings with their default values: + +```yaml +ipFamilyMode: "dualstack" +redirect: + inbound: + enabled: true + port: 15006 + outbound: + enabled: true + port: 15001 + dns: + port: 15053 + resolvConfigPath: "/etc/resolv.conf" +ebpf: + bpffsPath: "/run/kuma/bpf" + cgroupPath: "/sys/fs/cgroup" + programsSourcePath: "/tmp/kuma-ebpf" +retry: + maxRetries: 4 + sleepBetweenRetries: "2s" +log: + level: 7 +wait: 5 +``` + +## Full reference + +- **`kumaDPUser`** + + The username or UID of the user that will run `kuma-dp` + + {% capture tip %} + {% tip %} + If this value is not provided, the system will default to using the UID `5678` or the username `kuma-dp` + {% endtip %} + {% endcapture %} + {{ tip | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" flag="--kuma-dp-user" env="KUMA_DP_USER" runtime="sidecarContainer.uid" runtimeEnv="SIDECAR_CONTAINER_UID" %} + + **Examples** + + ```sh + kumactl install transparent-proxy --kuma-dp-user bob + ``` + + ```sh + KUMA_TRANSPARENT_PROXY_KUMA_DP_USER="5679" kumactl install transparent-proxy + ``` + +- **`ipFamilyMode`** + + The IP family mode used for configuring traffic redirection in the transparent proxy + + {% include snippets/tproxy/conf-field-table.html.liquid type="enum" default="dualstack" values="dualstack,ipv4" flag="--ip-family-mode" env="IP_FAMILY_MODE" annotation="kuma.io/transparent-proxying-ip-family-mode" runtime="sidecarContainer.ipFamilyMode" runtimeEnv="SIDECAR_CONTAINER_IP_FAMILY_MODE" %} + +- **`redirect`** + + - **`inbound`** + + - **`enabled`** + + Enables inbound traffic redirection + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="true" flag="--redirect-inbound" env="REDIRECT_INBOUND_ENABLED" %} + + - **`port`** + + Port used for redirecting inbound traffic + + {% include snippets/tproxy/conf-field-table.html.liquid type="Port" default="15006" flag="--redirect-inbound-port" env="REDIRECT_INBOUND_PORT" runtime="sidecarContainer.redirectPortInbound" runtimeEnv="SIDECAR_CONTAINER_REDIRECT_PORT_INBOUND" %} + + - **`includePorts`** + + List of ports to include in inbound traffic redirection + + {% capture warning %} + {%- warning -%} + This option cannot be used together with `redirect.inbound.excludePorts`. If both are specified, `redirect.inbound.includePorts` will take precedence + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]Port" env="REDIRECT_INBOUND_INCLUDE_PORTS" %} + + - **`excludePorts`** + + List of ports to exclude from inbound traffic redirection + + {% capture warning %} + {%- warning -%} + This option cannot be used together with `redirect.inbound.includePorts`. If both are specified, `redirect.inbound.includePorts` will take precedence. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]Port" flag="--exclude-inbound-ports" env="REDIRECT_INBOUND_EXCLUDE_PORTS" annotation="traffic.kuma.io/exclude-inbound-ports" runtime="sidecarTraffic.excludeInboundPorts" runtimeEnv="SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS" %} + + - **`excludePortsForIPs`** + + List of IP addresses to exclude from inbound traffic redirection for specific ports + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]string" flag="--exclude-inbound-ips" env="REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_IPS" annotation="traffic.kuma.io/exclude-inbound-ips" runtime="sidecarTraffic.excludeInboundIPs" runtimeEnv="SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS" format="ip[,...]" %} + + This CLI flag can be repeated. For example: + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ips "10.0.0.1,172.1.0.0/24" \ + --exclude-outbound-ips "fe80::/10" + ``` + + - **`excludePortsForUIDs`** + + List of UIDs to exclude from inbound traffic redirection for specific ports + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]string" env="REDIRECT_INBOUND_EXCLUDE_PORTS_FOR_UIDS" %} + + - **`insertRedirectInsteadOfAppend`** + + Inserts the redirection rule at the beginning of the chain instead of appending it + + **Details**: For inbound traffic, by default, the last applied iptables rule in the `PREROUTING` chain of the `nat` table redirects traffic to our custom chain (`KUMA_MESH_INBOUND_REDIRECT`) for handling transparent proxying. If there is an existing rule in this chain that redirects traffic to another chain, our default behavior of appending the rule would cause it to be added after the existing one, making our rule ineffective. Specifying this flag changes the behavior to insert the rule at the beginning of the chain, ensuring our rule takes precedence + + {% capture tip %} + {%- tip -%} + Note that if the `redirect.vnet` setting is also specified, the default behavior is already to insert the rule, so using this setting will not change that behavior + {%- endtip -%} + {% endcapture %} + {{ tip | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--redirect-inbound-insert-instead-of-append" env="REDIRECT_INBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND" %} + + - **`outbound`** + + - **`enabled`** + + Enables outbound traffic redirection + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="true" env="REDIRECT_OUTBOUND_ENABLED" %} + + - **`port`** + + Port used for redirecting outbound traffic + + {% include snippets/tproxy/conf-field-table.html.liquid type="Port" default="15001" flag="--redirect-outbound-port" env="REDIRECT_OUTBOUND_PORT" runtime="sidecarContainer.redirectPortOutbound" runtimeEnv="SIDECAR_CONTAINER_REDIRECT_PORT_OUTBOUND" %} + + - **`includePorts`** + + List of ports to include in outbound traffic redirection + + {% capture warning %} + {%- warning -%} + This option cannot be used together with `redirect.outbound.excludePorts`. If both are specified, `redirect.outbound.includePorts` will take precedence. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]Port" env="REDIRECT_OUTBOUND_INCLUDE_PORTS" %} + + - **`excludePorts`** + + List of ports to exclude from outbound traffic redirection + + {% capture warning %} + {%- warning -%} + This option cannot be used together with `redirect.outbound.includePorts`. If both are specified, `redirect.outbound.includePorts` will take precedence. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]Port" flag="--exclude-outbound-ports" env="REDIRECT_OUTBOUND_EXCLUDE_PORTS" annotation="traffic.kuma.io/exclude-outbound-ports" runtime="sidecarTraffic.excludeOutboundPorts" runtimeEnv="SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS" %} + + - **`excludePortsForIPs`** + + List of IP addresses to exclude from outbound traffic redirection for specific ports. + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]string" flag="--exclude-outbound-ips" env="REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_IPS" annotation="traffic.kuma.io/exclude-outbound-ips" format="ip[,...]" runtime="sidecarTraffic.excludeOutboundIPs" runtimeEnv="SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS" %} + + - **`excludePortsForUIDs`** + + List of UIDs to exclude from outbound traffic redirection for specific ports + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]string" flag="--exclude-outbound-ports-for-uids" env="REDIRECT_OUTBOUND_EXCLUDE_PORTS_FOR_UIDS" annotation="traffic.kuma.io/exclude-outbound-ports-for-uids" format="[[protocol:][ports:]uids][;...]" %} + + **Examples** + + - Exclude outbound **TCP** and **UDP** traffic to all ports for processes owned by user with **UID** `1000`: + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ports-for-uids "1000" + ``` + + - Exclude outbound **UDP** traffic to all ports for processes owned by user with **UID** `1000`: + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ports-for-uids "udp:*:1000" + ``` + + - Exclude outbound **TCP** traffic to port `22` and ports `80–88` for processes owned by users with **UIDs** in the range `1000–1002`: + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ports-for-uids "tcp:22,80-88:1000-1002" + ``` + + - Exclude outbound **TCP** and **UDP** traffic to all ports for processes owned by users with **UIDs** in the range `1000–1100`, and exclude outbound **UDP** traffic to all ports for processes owned by user with **UID** `2000`: + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ports-for-uids "1000-1100;udp:*:2000" + ``` + + ```sh + kumactl install transparent-proxy \ + --exclude-outbound-ports-for-uids "1000-1100" \ + --exclude-outbound-ports-for-uids "udp:*:2000" + ``` + + - **`insertRedirectInsteadOfAppend`** + + Inserts the redirection rule at the beginning of the chain instead of appending it + + **Details**: For outbound traffic, by default, the last applied iptables rule in the `OUTPUT` chain of the `nat` table redirects traffic to our custom chain (`KUMA_MESH_OUTBOUND_REDIRECT`), where it is processed for transparent proxying. However, if there is an existing rule in this chain that already redirects traffic to another chain, our default behavior of appending the rule will cause our rule to be added after the existing one, effectively ignoring it. When this flag is specified, it changes the behavior from appending to inserting the rule at the beginning of the chain, ensuring that our iptables rule takes precedence + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--redirect-outbound-insert-instead-of-append" env="REDIRECT_OUTBOUND_INSERT_REDIRECT_INSTEAD_OF_APPEND" %} + +- **`dns`** + + - **`enabled`** + + Enables redirection of DNS queries to the DNS server managed by {{ Kuma }}, listening on the port specified in the `redirect.dns.port` setting + + {% capture tip %} + {%- tip -%} + When `redirect.dns.captureAll` is disabled, only queries directed to servers listed in the file specified via `redirect.dns.resolvConfigPath`) will be redirected. If `redirect.dns.captureAll` is enabled, all DNS queries will be redirected, regardless of the target DNS server + {%- endtip -%} + {% endcapture %} + {{ tip | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="true" env="REDIRECT_DNS_ENABLED" runtime="builtinDNS.enabled" runtimeEnv="BUILTIN_DNS_ENABLED" %} + + - **`port`** + + The port where the DNS server managed by {{ Kuma }} is listening + + {% include snippets/tproxy/conf-field-table.html.liquid type="Port" default="15053" flag="--redirect-dns-port" env="REDIRECT_DNS_PORT" runtime="builtinDNS.port" runtimeEnv="BUILTIN_DNS_PORT" %} + + - **`captureAll`** + + Redirect all DNS traffic to the DNS server managed by {{ Kuma }}, listening on the port specified in the `redirect.dns.port` setting + + {% capture warning %} + {%- warning -%} + This setting requires `redirect.dns.enabled`, which is disabled by default. However, using the `--redirect-all-dns-traffic` flag automatically enables it. Note that combining `--redirect-all-dns-traffic` with `--redirect-dns` is incorrect and will result in an error. In all other cases, ensure `redirect.dns.enabled` is explicitly enabled via the appropriate environment variable or in the `JSON` / `YAML` configuration. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--redirect-all-dns-traffic" env="REDIRECT_DNS_CAPTURE_ALL" %} + + - **`skipConntrackZoneSplit`** + + Disables conntrack zone splitting, which can prevent potential DNS issues + + **Details**: The conntrack zone splitting feature is used to avoid DNS resolution errors when applications make numerous DNS UDP requests. Normally, we separate conntrack zones to ensure proper handling of DNS traffic: Zone 2 handles DNS packets between the application and the local proxy, while Zone 1 manages packets between the proxy and upstream DNS resolvers. Disabling this feature should only be done if necessary, for example, in environments where custom iptables rules are already manipulating DNS traffic (for example, inside Docker containers in custom networks when redirecting all DNS traffic \[`redirect.dns.captureAll` is enabled\]) + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--skip-dns-conntrack-zone-split" env="REDIRECT_DNS_SKIP_CONNTRACK_ZONE_SPLIT" %} + + - **`resolvConfigPath`** + + Specifies the path to the `resolv.conf` file used to parse the DNS servers for redirecting DNS queries + + {% capture tip %} + {%- tip -%} + This setting is taken into account only when `redirect.dns.captureAll` is not enabled. + {%- endtip -%} + {% endcapture %} + {{ tip | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" default="/etc/resolv.conf" env="REDIRECT_DNS_RESOLV_CONFIG_PATH" %} + +- **`vnet`** + + - **`networks`** + + Specifies virtual networks using the format `interfaceName:CIDR` Allows matching traffic on specific network interfaces + + **Examples**: + + - `docker0:172.17.0.0/16` + - `br+:172.18.0.0/16` (matches any interface with name starting with `br`) + - `iface:::1/64` (for IPv6) + + {% include snippets/tproxy/conf-field-table.html.liquid type="[]string" flag="--vnet" env="REDIRECT_VNET_NETWORKS" %} + +- **`ebpf`** + + {% capture warning %} + {%- warning -%} + eBPF implementation is experimental. Use with caution + {%- endwarning -%} + {% endcapture %} + {{ warning | indent }} + + - **`enabled`** + + Enables eBPF support for handling traffic redirection in the transparent proxy + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--ebpf-enabled" env="EBPF_ENABLED" annotation="kuma.io/transparent-proxying-ebpf" runtime="ebpf.enabled" runtimeEnv="EBPF_ENABLED" %} + + - **`instanceIP`** + + IP address of the instance (pod/vm) where transparent proxy will be installed + + {% capture warning %} + {%- warning -%} + Mutually exclusive with `ebpf.instanceIPEnvVarName`. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" flag="--ebpf-instance-ip" env="EBPF_INSTANCE_IP" %} + + - **`instanceIPEnvVarName`** + + The name of the environment variable containing the IP address of the instance (pod/vm) where transparent proxy will be installed + + {% capture warning %} + {%- warning -%} + Mutually exclusive with `ebpf.instanceIP`. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" env="EBPF_INSTANCE_IP_ENV_VAR_NAME" annotation="kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name" runtime="ebpf.instanceIPEnvVarName" runtimeEnv="EBPF_INSTANCE_IP_ENV_VAR_NAME" %} + + - **`bpffsPath`** + + The path of the BPF filesystem + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" default="/run/kuma/bpf" flag="--ebpf-bpffs-path" env="EBPF_BPFFS_PATH" annotation="kuma.io/transparent-proxying-ebpf-bpf-fs-path" runtime="ebpf.bpffsPath" runtimeEnv="EBPF_BPFFS_PATH" %} + + - **`cgroupPath`** + + The path of cgroup2 + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" default="/sys/fs/cgroup" flag="--ebpf-cgroup-path" env="EBPF_CGROUP_PATH" annotation="kuma.io/transparent-proxying-ebpf-cgroup-path" runtime="ebpf.cgroupPath" runtimeEnv="EBPF_CGROUP_PATH" %} + + - **`programsSourcePath`** + + Path where compiled eBPF programs and other necessary files for eBPF mode can be found + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" default="/tmp/kuma-ebpf" flag="--ebpf-programs-source-path" env="EBPF_PROGRAMS_SOURCE_PATH" annotation="kuma.io/transparent-proxying-ebpf-programs-source-path" runtime="ebpf.programSourcePath" runtimeEnv="EBPF_PROGRAMS_SOURCE_PATH" %} + + - **`tcAttachIface`** + + The network interface for TC eBPF programs to bind to. If not provided, it will be automatically determined + + {% include snippets/tproxy/conf-field-table.html.liquid type="string" flag="--ebpf-tc-attach-iface" env="EBPF_TC_ATTACH_IFACE" annotation="kuma.io/transparent-proxying-ebpf-tc-attach-iface" runtime="ebpf.tcAttachIface" runtimeEnv="EBPF_TC_ATTACH_IFACE" %} + +- **`retry`** + + - **`maxRetries`** + + The maximum number of retry attempts for operations + + {% include snippets/tproxy/conf-field-table.html.liquid type="uint" default="4" flag="--max-retries" env="RETRY_MAX_RETRIES" %} + + - **`sleepBetweenRetries`** + + The time duration to wait between retry attempts + + {% include snippets/tproxy/conf-field-table.html.liquid type="Duration" default="2s" flag="--sleep-between-retries" env="RETRY_SLEEP_BETWEEN_RETRIES" %} + +- **`iptablesExecutables`** + + Specifies custom paths for iptables executables + + {% capture warning %} + {%- warning -%} + You must provide all three executables for each IP version you want to customize (IPv4 or IPv6), meaning if you configure one for IPv6 (for example, `ip6tables`), you must also specify `ip6tables-save` and `ip6tables-restore`. Partial configurations for either IPv4 or IPv6 are not allowed. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent }} + + {% capture warning %} + {%- warning -%} + Provided paths are not extensively validated, so ensure you specify correct paths and that the executables are actual iptables binaries to avoid misconfigurations and unexpected behavior. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent }} + + {% capture tip %} + {%- tip -%} + Configuration values can be set through a combination of sources: config file (via `--config` or `--config-file`), environment variables, and the `--iptables-executables` flag. For example, you can specify `ip6tables` in the config file, `ip6tables-save` as an environment variable, and `ip6tables-restore` via the `--iptables-executables` flag. + {%- endtip -%} + {% endcapture %} + {{ tip | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="object" allowedKeys="iptables,iptables-save,iptables-restore,ip6tables,ip6tables-save,ip6tables-restore" flag="--iptables-executables" env="IPTABLES_EXECUTABLES" %} + +- **`log`** + + - **`enabled`** + + Determines whether iptables rules logging is activated. When `true`, each packet matching an iptables rule will have its details logged, aiding in diagnostics and monitoring of packet flows + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--iptables-logs" env="LOG_ENABLED" annotation="traffic.kuma.io/iptables-logs" %} + + - **`level`** + + Specifies the log level for iptables logging as defined by netfilter. This level controls the verbosity and detail of the log entries for matching packets. Higher values increase the verbosity. The exact behavior can depend on the system's syslog configuration + + **Available log levels**: + + - `0` - emergency (system is unusable) + - `1` - alert (action must be taken immediately) + - `2` - critical (critical conditions) + - `3` - error (error conditions) + - `4` - warning (warning conditions) + - `5` - notice (normal but significant condition) + - `6` - info (informational) + - `7` - debug (debug-level messages) + + {% include snippets/tproxy/conf-field-table.html.liquid type="enum" default="7" values="0,1,2,3,4,5,6,7" env="LOG_LEVEL" %} + +- **`comments`** + + - **`disabled`** + + Disables the addition of comments to iptables rules + + {% capture warning %} + {%- warning -%} + Disabling comments is strongly discouraged, as they are essential for properly uninstalling the transparent proxy. If comments are disabled, the `kumactl uninstall transparent-proxy` command will not function, and you'll need to manually remove the related iptables rules when necessary. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--disable-comments" env="COMMENTS_DISABLED" %} + +- **`wait`** + + Time in seconds to wait for acquiring the xtables lock before failing. Value `0` means wait indefinitely + + {% include snippets/tproxy/conf-field-table.html.liquid type="uint" default="5" flag="--wait" env="WAIT" %} + +- **`waitInterval`** + + Time interval between retries to acquire the xtables lock in seconds + + {% include snippets/tproxy/conf-field-table.html.liquid type="uint" default="0" flag="--wait-interval" env="WAIT_INTERVAL" %} + +- **`dropInvalidPackets`** + + Drops invalid packets to avoid connection resets in high-throughput scenarios + + **Details**: This setting enables dropping of packets in invalid states, improving application stability by preventing them from reaching the backend. This is particularly beneficial during high-throughput requests where out-of-order packets might bypass DNAT + + {% capture warning %} + {%- warning -%} + Note that enabling this flag may introduce slight performance overhead. Weigh the trade-off between connection stability and performance before enabling it. + {%- endwarning -%} + {% endcapture %} + {{ warning | indent }} + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--drop-invalid-packets" env="DROP_INVALID_PACKETS" annotation="traffic.kuma.io/drop-invalid-packets" %} + +- **`storeFirewalld`** + + Enables firewalld support to store iptables rules + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--store-firewalld" env="STORE_FIREWALLD" %} + +- **`cniMode`** + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" env="CNI_MODE" %} + +- **`dryRun`** + + Enables dry-run mode + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--dry-run" env="DRY_RUN" %} + +- **`verbose`** + + Enables verbose mode with longer argument/flag names and additional comments + + {% include snippets/tproxy/conf-field-table.html.liquid type="bool" default="false" flag="--verbose" env="VERBOSE" %} From f7ec37b67e81065ad2248e7708bda3cef8cd5a68 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:27:11 +0100 Subject: [PATCH 02/40] feat(guide): add excluding traffic from transparent proxy guide Signed-off-by: Bart Smykla --- ...ffic-from-transparent-proxy-redirection.md | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md new file mode 100644 index 000000000..9c8786fd5 --- /dev/null +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -0,0 +1,192 @@ +--- +title: Excluding Traffic from Transparent Proxy +--- + +{% assign docs = "/docs/" | append: page.version %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +{% assign configuration-in-configmap = "Configuration in ConfigMap (experimental)" %} + +This guide will show you how to exclude specific types of traffic from being redirected by the transparent proxy. It includes instructions for both **Universal** and a **Kubernetes** modes and covers different types of traffic you might want to exclude, such as: + +- [Exclude traffic on certain ports (incoming & outgoing)](#exclude-traffic-on-certain-ports) +- [Exclude traffic to and from specific IP addresses](#exclude-traffic-to-and-from-specific-ip-addresses) + +Use this guide to control which traffic the transparent proxy intercepts and which it allows through directly. + +## Key information + +- This guide shows how to set up the transparent proxy to exclude certain types of traffic from redirection for selected workloads. We’ll cover some methods for both Kubernetes and Universal modes, but **not all possible scenarios are explained in detail**. For more information on options briefly mentioned here, check out: + + - [Adjusting Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/) + - [Adjusting Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/configuration-on-universal/) + - [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) + +- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#method-3-kubernetes-annotations), since the [{{ configuration-in-configmap }}]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#method-2-configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. + +## Terminology overview + +- **Workload**: In this guide, **workload** refers to an application running in a Kubernetes cluster, usually represented by a [**Pod**](https://kubernetes.io/docs/concepts/workloads/pods/). Kubernetes resources like [**Deployment**](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [**ReplicaSet**](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), and [**StatefulSet**](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) are used to define and manage these workloads, resulting in one or more **Pods** where the application actually runs. + +- **ConfigMap**: In this guide, **ConfigMap** refers to the Kubernetes [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/) resource. It’s used to store configuration data as key-value pairs that can be easily accessed by other resources in the cluster, such as Pods, Deployments, and StatefulSets. + +- **Service**: In this guide, **service** means the application running in a Universal mode environment where the transparent proxy will be installed. This term does not refer to Kubernetes [**Service**](https://kubernetes.io/docs/concepts/services-networking/service/) resources. + +## Prerequisites + +1. **Understand transparent proxy basics**: You should already be familiar with what a transparent proxy is, how to install it, and how to adjust its settings. This guide won’t cover those basics. The following resources can help: + + - For options to customize transparent proxy settings, check the resources listed in the [Key Information](#key-information) section. + + - For an in-depth look at how the transparent proxy works in {{ Kuma }} and its mechanisms, see the [Technical Overview]({{ docs }}/networking/transparent-proxy/technical-overview/) page from its documentation. + + - To install the transparent proxy on Universal, refer to [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/). + - For upgrade steps, see [Upgrading Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/upgrading-on-universal/). + +2. **Set up {{ Kuma }}**: Ensure {{ Kuma }} is installed and running. + + {% capture prerequisites-setup-kuma %} + {% tabs prerequisites-setup-kuma %} + {% tab prerequisites-setup-kuma Kubernetes %} + Follow the [Kubernetes Quickstart]({{ docs }}/quickstart/kubernetes-demo/) guide to set up a zone control plane and demo application. + {% endtab %} + {% tab prerequisites-setup-kuma Universal %} + Confirm that all necessary components are up and running. The following resources may be useful: + + - To set up a single-zone control plane, follow the [Single Zone Control Plane Deployment]({{ docs }}/production/cp-deployment/single-zone/) guide. + + - To generate a data plane proxy token (needed to authorize data plane proxies), refer to [Data Plane Proxy Token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) documentation. + + - To prepare your service environment and start the data plane proxy, follow the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) guide up to [Step 5: Install the transparent proxy]({{ docs }}/networking/transparent-proxy/installing-on-universal/#step-5-install-the-transparent-proxy). + {% endtab %} + {% endtabs %} + {% endcapture %} + {{ prerequisites-setup-kuma | indent }} + +## Exclude traffic on certain ports + +This example shows how to exclude incoming traffic on port `1234` and outgoing traffic on ports `5678` and `8900`. + +{% tabs excluding-incoming-traffic-to-specific-ports useUrlFragment=false %} +{% tab excluding-incoming-traffic-to-specific-ports Kubernetes %} +To exclude these ports in Kubernetes mode, add the `traffic.kuma.io/exclude-inbound-ports` annotation for incoming traffic and `traffic.kuma.io/exclude-outbound-ports` for outgoing traffic. For example, your Pod configuration could look like this: + +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: example-app + annotations: + traffic.kuma.io/exclude-inbound-ports: "1234" + traffic.kuma.io/exclude-outbound-ports: "5678,8900" +... +``` + +You can add these annotations manually in your Kubernetes manifests or by using this command: + +```sh +kubectl annotate pods example-app \ + "traffic.kuma.io/exclude-inbound-ports=1234" \ + "traffic.kuma.io/exclude-outbound-ports=5678,8900" +``` + +{% include snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid data=tproxy.data.guides.exclude-traffic.excludePorts %} +{% endtab %} + +{% tab excluding-incoming-traffic-to-specific-ports Universal %} +To exclude specific ports in Universal mode, configure the transparent proxy with `redirect.inbound.excludePorts` and `redirect.outbound.excludePorts` settings. Here’s an example: + +```sh +echo " +redirect: + inbound: + excludePorts: [1234] + outbound: + excludePorts: [5678, 8900] +" | kumactl install transparent-proxy --config-file - +``` + +### Other configuration options +{:.no-anchor#excluding-incoming-traffic-to-specific-ports-universal-other-options} + +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-2-using-environment-variables) + +```sh +KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS="1234" \ +KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS="5678,8900" \ +kumactl install transparent-proxy +``` + +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-3-cli-flags) + +```sh +kumactl install transparent-proxy \ + --exclude-inbound-ports "1234" \ + --exclude-outbound-ports "5678,8900" +```` +{% endtab %} +{% endtabs %} + +## Exclude traffic to and from specific IP addresses + +This example shows how to exclude incoming traffic coming from addresses in range `10.0.0.0/8` and outgoing traffic directed to address `192.168.10.1` or addresses in range `fd10::/16`. + +{% tabs exclude-traffic-to-and-from-specific-ip-addresses useUrlFragment=false %} +{% tab exclude-traffic-to-and-from-specific-ip-addresses Kubernetes %} +To exclude these addresses in Kubernetes mode, add the `traffic.kuma.io/exclude-inbound-ips` annotation for incoming traffic and `traffic.kuma.io/exclude-outbound-ips` for outgoing traffic. For example, your Pod configuration could look like this: + +```yaml +apiVersion: apps/v1 +kind: Pod +metadata: + name: example-app + annotations: + traffic.kuma.io/exclude-inbound-ips: "10.0.0.0/8" + traffic.kuma.io/exclude-outbound-ips: "192.168.10.1,fd10::/16" +... +``` + +You can add these annotations manually in your Kubernetes manifests or by using this command: + +```sh +kubectl annotate pods example-app \ + "traffic.kuma.io/exclude-inbound-ips=10.0.0.0/8" \ + "traffic.kuma.io/exclude-outbound-ips=192.168.10.1,fd10::/16" +``` + +{% include snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid data=tproxy.data.guides.exclude-traffic.excludeIPs %} +{% endtab %} +{% tab exclude-traffic-to-and-from-specific-ip-addresses Universal %} +To exclude these addresses in Universal mode, configure the transparent proxy with `redirect.inbound.excludePortsForIPs` and `redirect.outbound.excludePortsForIPs` settings. Here’s an example: + +```sh +echo " +redirect: + inbound: + excludePortsForIPs: [10.0.0.0/8] + outbound: + excludePortsForIPs: [192.168.10.1, fd10::/16] +" | kumactl install transparent-proxy --config-file - +``` + +### Other configuration options +{:.no-anchor#exclude-traffic-to-and-from-specific-ip-addresses-universal-other-options} + +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-2-using-environment-variables) + +```sh +KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS="10.0.0.0/8" \ +KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS="192.168.10.1,fd10::/16" \ +kumactl install transparent-proxy +``` + +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-3-cli-flags) + +```sh +kumactl install transparent-proxy \ + --exclude-inbound-ips "10.0.0.0/8" \ + --exclude-outbound-ips "192.168.10.1,fd10::/16" +```` +{% endtab %} +{% endtabs %} From fbfcf4b2bd2e4c8b3440b226e96672cbdf50fdfa Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:28:14 +0100 Subject: [PATCH 03/40] chore: make sure that links to tproxy docs are now correct for >= 2.9.x Signed-off-by: Bart Smykla --- app/_src/introduction/kuma-requirements.md | 2 +- app/_src/networking/dns.md | 4 +-- app/_src/networking/meshservice.md | 2 +- app/_src/networking/non-mesh-traffic.md | 2 +- app/_src/policies/external-services.md | 6 +++-- app/_src/policies/meshpassthrough.md | 2 +- app/_src/policies/traffic-permissions.md | 2 +- app/_src/policies/virtual-outbound.md | 2 +- .../production/cp-deployment/multi-zone.md | 2 +- app/_src/production/deployment/multi-zone.md | 2 +- app/_src/production/dp-config/cni.md | 2 +- app/_src/production/dp-config/dpp.md | 2 +- .../production/upgrades-tuning/fine-tuning.md | 26 ++++++++++--------- app/_src/reference/kubernetes-annotations.md | 16 +++++++----- 14 files changed, 40 insertions(+), 32 deletions(-) diff --git a/app/_src/introduction/kuma-requirements.md b/app/_src/introduction/kuma-requirements.md index a224e61eb..7142512eb 100644 --- a/app/_src/introduction/kuma-requirements.md +++ b/app/_src/introduction/kuma-requirements.md @@ -57,7 +57,7 @@ To see if you may need to increase your control-plane's spec, there are two main - propagation time (xds_delivery): this is the time it takes between a change in the mesh and the dataplane receiving its updated configuration. Think about it as the "reactivity of your mesh". - configuration generation time (xds_generation): this is the time it takes for the configuration to be generated. -For any large mesh using transparent-proxy it's highly recommended to use {% if_version lte:2.1.x %}[reachable-services](/docs/{{ page.version }}/networking/transparent-proxying#reachable-services){% endif_version %}{% if_version gte:2.2.x %}[reachable-services](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#reachable-services){% endif_version %}. +For any large mesh using transparent-proxy it's highly recommended to use [reachable-services](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/{% endif_version %}reachable-services). You can also find tuning configuration in the {% if_version lte:2.1.x %}[fine-tuning](/docs/{{ page.version }}/documentation/fine-tuning){% endif_version %}{% if_version gte:2.2.x %}[fine-tuning](/docs/{{ page.version }}/production/upgrades-tuning/fine-tuning/){% endif_version %} section of the docs. diff --git a/app/_src/networking/dns.md b/app/_src/networking/dns.md index 54729ed37..82a333a46 100644 --- a/app/_src/networking/dns.md +++ b/app/_src/networking/dns.md @@ -4,7 +4,7 @@ title: DNS {{site.mesh_product_name}} ships with DNS resolver to provide service naming - a mapping of hostname to Virtual IPs (VIPs) of services registered in {{site.mesh_product_name}}. -The usage of {{site.mesh_product_name}} DNS is only relevant when {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} is used. +The usage of {{site.mesh_product_name}} DNS is only relevant when [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) is used. ## How it works @@ -53,7 +53,7 @@ If you use [MeshService](/docs/{{ page.version }}/networking/meshservice), [Mesh {% endtab %} {% tab installation Universal %} -Follow the instruction in {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}. +Follow the instruction in {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}{% if_version gte:2.9.x %}[Installing Transparent Proxy on Universal](/docs/{{ page.version }}/networking/transparent-proxy/installing-on-universal/){% endif_version %}. {% endtab %} {% endtabs %} diff --git a/app/_src/networking/meshservice.md b/app/_src/networking/meshservice.md index ea1587aea..191eda1f8 100644 --- a/app/_src/networking/meshservice.md +++ b/app/_src/networking/meshservice.md @@ -297,7 +297,7 @@ described below. This enables automatic generation of the Kuma `MeshServices` resource but does not include the corresponding resources for every data plane proxy. The intention is for users to explicitly and gradually introduce -relevant `MeshServices` via [`reachableBackends`](/docs/{{ page.version }}/production/dp-config/transparent-proxying#reachable-backends). +relevant `MeshServices` via [`reachableBackends`](/docs/{{ page.version }}/networking/transparent-proxy/reachable-backends/). #### `Exclusive` diff --git a/app/_src/networking/non-mesh-traffic.md b/app/_src/networking/non-mesh-traffic.md index 3e6b99a32..213726b20 100644 --- a/app/_src/networking/non-mesh-traffic.md +++ b/app/_src/networking/non-mesh-traffic.md @@ -9,7 +9,7 @@ If you want to allow external clients to consume mesh services see the [Permissive mTLS](/docs/{{ page.version }}/policies/mutual-tls/#permissive-mtls) mode. {% warning %} -Without {% if_version lte:2.1.x %}[Transparent Proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[Transparent Proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} +Without [Transparent Proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) TLS check on Envoy can be bypassed. You should take action to secure the application ports. {% endwarning %} diff --git a/app/_src/policies/external-services.md b/app/_src/policies/external-services.md index 9d92ba5a5..661c07025 100644 --- a/app/_src/policies/external-services.md +++ b/app/_src/policies/external-services.md @@ -66,7 +66,9 @@ networking: Then apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). -Universal mode is best combined with {% if_version lte:2.1.x %}[transparent proxy](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version%}{% if_version gte:2.2.x %}[transparent proxy](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version%}. For backward compatibility only, you can consume an external service from within the mesh by filling the proper `outbound` section of the relevant data plane resource: +{% capture tproxy-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version%}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version%}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version%}{% endcapture %} + +Universal mode is best combined with [transparent proxy]({{ tproxy-link }}). For backward compatibility only, you can consume an external service from within the mesh by filling the proper `outbound` section of the relevant data plane resource: ```yaml type: Dataplane @@ -91,7 +93,7 @@ Then `httpbin.org` is accessible at `127.0.0.1:10000`. ### Accessing the External Service -Consuming the defined service from within the mesh for both Kubernetes and Universal deployments (assuming {% if_version lte:2.1.x %}[transparent proxy](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version%}{% if_version gte:2.2.x %}[transparent proxy](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version%}) can be done: +Consuming the defined service from within the mesh for both Kubernetes and Universal deployments (assuming [transparent proxy]({{ tproxy-link }})) can be done: * With the `.mesh` naming of the service `curl httpbin.mesh`. With this approach, specify port 80. * With the real name and port, in this case `curl httpbin.org:443`. This approach works only with [the data plane proxy builtin DNS](/docs/{{ page.version }}/networking/dns) name resolution. diff --git a/app/_src/policies/meshpassthrough.md b/app/_src/policies/meshpassthrough.md index d5c92370b..ca998f2e9 100644 --- a/app/_src/policies/meshpassthrough.md +++ b/app/_src/policies/meshpassthrough.md @@ -24,7 +24,7 @@ To learn more about the information in this table, see the [matching docs](/docs ## Configuration {% warning %} -This policy doesn't work with sidecars without [transparent-proxy](/docs/{{ page.version }}/networking/transparent-proxying/#what-is-transparent-proxying). +This policy doesn't work with sidecars without [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.8.x %}networking/transparent-proxying/#what-is-transparent-proxying{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). {% endwarning %} The following describes the default configuration settings of the `MeshPassthrough` policy: diff --git a/app/_src/policies/traffic-permissions.md b/app/_src/policies/traffic-permissions.md index a39a5163d..06a4f7df4 100644 --- a/app/_src/policies/traffic-permissions.md +++ b/app/_src/policies/traffic-permissions.md @@ -70,7 +70,7 @@ The `TrafficPermission` policy can also be used to restrict traffic to [services ### Prerequisites -* {{site.mesh_product_name}} deployed with {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} +* {{site.mesh_product_name}} deployed with [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) * `Mesh` configured to {% if_version lte:2.1.x %}[disable passthrough mode](/docs/{{ page.version }}/policies/mesh/#usage){% endif_version %}{% if_version gte:2.2.x %}[disable passthrough mode](/docs/{{ page.version }}/production/mesh/#usage){% endif_version %} These settings lock down traffic to and from the mesh, which means that requests to any unknown destination are not allowed. The mesh can't rely on mTLS, because there is no data plane proxy on the destination side. diff --git a/app/_src/policies/virtual-outbound.md b/app/_src/policies/virtual-outbound.md index 551f692e6..9f4f72185 100644 --- a/app/_src/policies/virtual-outbound.md +++ b/app/_src/policies/virtual-outbound.md @@ -95,7 +95,7 @@ produce the hostname: `v1.backend.mesh` with port: `1800`. Additional Requirements: -- {% if_version lte:2.1.x %}[Transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[Transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} must be enabled. +- [Transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) must be enabled. - Either: - [Data plane proxy DNS](/docs/{{ page.version }}/networking/dns) must be enabled. - Or, the value of `conf.host` must end with the value of `dns_server.domain`, which defaults to `.mesh`. diff --git a/app/_src/production/cp-deployment/multi-zone.md b/app/_src/production/cp-deployment/multi-zone.md index 9b107a347..c54cd84d4 100644 --- a/app/_src/production/cp-deployment/multi-zone.md +++ b/app/_src/production/cp-deployment/multi-zone.md @@ -449,7 +449,7 @@ outbound: From the data plane running you will now be able to reach the service using `localhost:20012`. -Alternatively, if you configure {% if_version lte:2.1.x %}[transparent proxy](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxy](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} you can just call `echo-server_echo-example_svc_1010.mesh` without defining an `outbound` section. +Alternatively, if you configure [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) you can just call `echo-server_echo-example_svc_1010.mesh` without defining an `outbound` section. {% endtab %} {% endtabs %} diff --git a/app/_src/production/deployment/multi-zone.md b/app/_src/production/deployment/multi-zone.md index 7e4de3210..f22c2c7e6 100644 --- a/app/_src/production/deployment/multi-zone.md +++ b/app/_src/production/deployment/multi-zone.md @@ -49,7 +49,7 @@ You can also favor local service instances with {% if_version lte:2.5.x %}[local In the presence of a {% if_version lte:2.1.x %}[zone egress](/docs/{{ page.version }}/explore/zoneegress){% endif_version %}{% if_version gte:2.2.x %}[zone egress](/docs/{{ page.version }}/production/cp-deployment/zoneegress/){% endif_version %}, the traffic is routed through the local zone egress before being sent to the remote zone ingress. -When using {% if_version lte:2.1.x %}[transparent proxy](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxy](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} (default in Kubernetes), +When using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) (default in Kubernetes), {{site.mesh_product_name}} generates a VIP, a DNS entry with the format `.mesh`, and will listen for traffic on port 80. The `.mesh:80` format is just a convention. [`VirtualOutbounds`](/docs/{{ page.version }}/policies/virtual-outbound)s enable you to customize the listening port and how the DNS name for these services looks. diff --git a/app/_src/production/dp-config/cni.md b/app/_src/production/dp-config/cni.md index 30a15dbc3..a2a5990a2 100644 --- a/app/_src/production/dp-config/cni.md +++ b/app/_src/production/dp-config/cni.md @@ -5,7 +5,7 @@ content_type: how-to In order for traffic to flow through the {{site.mesh_product_name}} data plane, all inbound and outbound traffic for a service needs to go through its data plane proxy. -The recommended way of accomplishing this is via {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}. +The recommended way of accomplishing this is via [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). On Kubernetes it's handled automatically by default with the `initContainer` `kuma-init`, but this container requires certain privileges. diff --git a/app/_src/production/dp-config/dpp.md b/app/_src/production/dp-config/dpp.md index bc83a57c0..b54f02a16 100644 --- a/app/_src/production/dp-config/dpp.md +++ b/app/_src/production/dp-config/dpp.md @@ -50,7 +50,7 @@ A service is a group of all DPP inbounds that have the same `kuma.io/service` ta ### Outbounds An outbound allows the workload to consume a service in the mesh using a local port. -This is only useful when not using {% if_version lte:2.1.x %}[transparent-proxy](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}(/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}. +This is only useful when not using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). ## `Dataplane` entity diff --git a/app/_src/production/upgrades-tuning/fine-tuning.md b/app/_src/production/upgrades-tuning/fine-tuning.md index d2f99620b..0b6a6afd9 100644 --- a/app/_src/production/upgrades-tuning/fine-tuning.md +++ b/app/_src/production/upgrades-tuning/fine-tuning.md @@ -3,18 +3,20 @@ title: Performance fine-tuning content_type: reference --- -## Reachable services - -By default, when transparent proxying is used, every data plane proxy follows every other data plane proxy in the mesh. -With large meshes, usually, a data plane proxy connects to just a couple of services in the mesh. -By defining the list of such services, we can dramatically improve the performance of {{site.mesh_product_name}}. - -The result is that: -* The control plane has to generate a much smaller XDS configuration (just a couple of Clusters/Listeners etc.) saving CPU and memory -* Smaller config is sent over a wire saving a lot of network bandwidth -* Envoy only has to keep a couple of Clusters/Listeners which means much fewer statistics and lower memory usage. - -Follow the {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %} docs on how to configure it. + +## Reachable Services + + +By default, with the transparent proxy enabled, each data plane proxy follows all other proxies in the mesh. In large meshes, a data plane proxy usually connects to only a few services. Defining this list of reachable services can significantly improve {{site.mesh_product_name}}'s performance. {% if_version lte:2.8.x %}Benefits include: +* The control plane generates a much smaller XDS configuration (fewer clusters/listeners), saving CPU and memory. +* Smaller configurations reduce network bandwidth. +* Envoy manages fewer clusters/listeners, reducing statistics and memory usage. +^ +See [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x %}production/dp-config/transparent-proxying/#reachable-services{% endif_version %}) for configuration details.{% endif_version %} + +{% if_version gte:2.9.x %} +For more details, including how to configure reachable services, refer to the [Reachable Services](/docs/{{ page.version }}/networking/transparent-proxy/reachable-services/) documentation. +{% endif_version %} {% if_version gte:2.5.x %} ## Config trimming by using MeshTrafficPermission diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index 452f16533..6a3598011 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -547,8 +547,10 @@ spec: ### `kuma.io/transparent-proxying-reachable-services` +{% capture reachable-services-docs-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/{% endif_version %}reachable-services{% endcapture %} + A comma separated list of `kuma.io/service` to indicate which services this communicates with. -For more details see the {% if_version lte:2.1.x %}[reachable services docs](/docs/{{ page.version }}/networking/transparent-proxying#reachable-services){% endif_version %}{% if_version gte:2.2.x %}[reachable services docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying#reachable-services){% endif_version %}. +For more details see the [reachable services docs]({{ reachable-services-docs-link }}). **Example** @@ -575,7 +577,9 @@ spec: When transparent proxy is installed with ebpf mode, you can disable it for particular workloads if necessary. -For more details see the {% if_version lte:2.1.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/networking/transparent-proxying#transparent-proxy-with-ebpf-experimental){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#transparent-proxy-with-ebpf-experimental){% endif_version %}. +{% capture tproxy-ebpf-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} + +For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). **Example** @@ -601,7 +605,7 @@ spec: Path to BPF FS if different than default (`/sys/fs/bpf`) -For more details see the {% if_version lte:2.1.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/networking/transparent-proxying#transparent-proxy-with-ebpf-experimental){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#transparent-proxy-with-ebpf-experimental){% endif_version %}. +For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). **Example** @@ -627,7 +631,7 @@ spec: cgroup2 path if different than default (`/sys/fs/cgroup`) -For more details see the {% if_version lte:2.1.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/networking/transparent-proxying#transparent-proxy-with-ebpf-experimental){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#transparent-proxy-with-ebpf-experimental){% endif_version %}. +For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). **Example** @@ -653,7 +657,7 @@ spec: Custom path for ebpf programs to be loaded when installing transparent proxy -For more details see the {% if_version lte:2.1.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/networking/transparent-proxying#transparent-proxy-with-ebpf-experimental){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#transparent-proxy-with-ebpf-experimental){% endif_version %}. +For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). **Example** @@ -681,7 +685,7 @@ Name of the network interface which should be used to attach to it TC-related eBPF programs. By default {{site.mesh_product_name}} will use first, non-loopback interface it'll find. -For more details see the {% if_version lte:2.1.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/networking/transparent-proxying#transparent-proxy-with-ebpf-experimental){% endif_version %}{% if_version gte:2.2.x %}[transparent proxying with ebpf docs](/docs/{{ page.version }}/production/dp-config/transparent-proxying/#transparent-proxy-with-ebpf-experimental){% endif_version %}. +For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). **Example** From 2134e452f32c6629d1e581c438b8b82db8049712 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:28:42 +0100 Subject: [PATCH 04/40] chore: add comments for legacy tproxy docs that these files are legacy Signed-off-by: Bart Smykla --- app/_src/networking/transparent-proxying.md | 4 + .../dp-config/transparent-proxying.md | 201 +----------------- 2 files changed, 8 insertions(+), 197 deletions(-) diff --git a/app/_src/networking/transparent-proxying.md b/app/_src/networking/transparent-proxying.md index d737a19a8..3f95fa931 100755 --- a/app/_src/networking/transparent-proxying.md +++ b/app/_src/networking/transparent-proxying.md @@ -2,6 +2,10 @@ title: Transparent Proxying --- +{% comment %} +This page is legacy and shown only for Kuma < 2.9.x. Only fix obvious bugs here; make other changes in app/_src/networking/transparent-proxy/ +{% endcomment %} + ## What is Transparent Proxying? A transparent proxy is a type of server that can intercept network traffic to and from a service without changes to the client application code. In the case of {{site.mesh_product_name}} it is used to capture traffic and redirect it to `kuma-dp` so Mesh policies can be applied. diff --git a/app/_src/production/dp-config/transparent-proxying.md b/app/_src/production/dp-config/transparent-proxying.md index a061c99fa..fb6c0a27b 100644 --- a/app/_src/production/dp-config/transparent-proxying.md +++ b/app/_src/production/dp-config/transparent-proxying.md @@ -3,6 +3,10 @@ title: Configure transparent proxying content_type: how-to --- +{% comment %} +This page is legacy and shown only for Kuma < 2.9.x. Only fix obvious bugs here; make other changes in app/_src/networking/transparent-proxy/ +{% endcomment %} + In order to automatically intercept traffic from and to a service through a `kuma-dp` data plane proxy instance, {{site.mesh_product_name}} utilizes a transparent proxying using [`iptables`](https://linux.die.net/man/8/iptables). Transparent proxying helps with a smoother rollout of a Service Mesh to a current deployment by preserving existing service naming and as the result - avoid changes to the application code. @@ -251,203 +255,6 @@ networking: {% endtab %} {% endtabs %} -{% if_version gte:2.9.x %} - -### Reachable Backends - -{% warning %} -This works only when [MeshService](/docs/{{ page.version }}/networking/meshservice) is enabled. -{% endwarning %} - -Reachable Backends provides similar functionality to [reachable services](/docs/{{ page.version }}/production/dp-config/transparent-proxying#reachable-services), but it applies to [MeshService](/docs/{{ page.version }}/networking/meshservice), [MeshExternalService](/docs/{{ page.version }}/networking/meshexternalservice), and [MeshMultiZoneService](/docs/{{ page.version }}/networking/meshmultizoneservice). - -By default, every data plane proxy in the mesh tracks every other data plane proxy. Configuring reachableBackends can improve performance and reduce resource utilization. - -Unlike reachable services, the model for providing data in Reachable Backends is more structured. - -#### Model - -- **refs**: A list of all resources your application wants to track and communicate with. - - **kind**: The type of resource. Possible values include: - - [**MeshService**](/docs/{{ page.version }}/networking/meshservice) - - [**MeshExternalService**](/docs/{{ page.version }}/networking/meshexternalservice) - - **MeshMultiZoneService** - - **name**: The name of the resource. - - **namespace**: (Kubernetes only) The namespace where the resource is located. When this is defined, the name is required. Only on kubernetes. - - **labels**: A list of labels to match on the resources (either `labels` or `name` can be defined). - - **port**: (Optional) The port of the service you want to communicate with. Works with `MeshService` and `MeshMultiZoneService` - -{% tabs reachable-backends-model useUrlFragment=false %} -{% tab reachable-backends-model Kubernetes %} - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: -... -spec: - ... - template: - metadata: - kuma.io/reachable-backends: | - refs: - - kind: MeshService - name: redis - namespace: kuma-demo - port: 8080 - - kind: MeshMulitZoneService - labels: - kuma.io/display-name: test-server - - kind: MeshExternalService - name: mes-http - namespace: kuma-system -``` -{% endtab %} -{% tab reachable-backends-model Universal %} -```yaml -type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - ... - transparentProxying: - redirectPortInbound: 15006 - redirectPortOutbound: 15001 - reachableBackends: - refs: - - kind: MeshService - name: redis - - kind: MeshMulitZoneService - labels: - kuma.io/display-name: test-server - - kind: MeshExternalService - name: mes-http -``` -{% endtab %} -{% endtabs %} - -#### Examples - -##### `demo-app` communicates only with `redis` on port 6379 - -{% tabs reachable-backends useUrlFragment=false %} -{% tab reachable-backends Kubernetes %} -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: demo-app - namespace: kuma-demo -spec: - ... - template: - metadata: - ... - annotations: - kuma.io/reachable-backends: | - refs: - - kind: MeshService - name: redis - namespace: kuma-demo - port: 6379 - spec: - containers: - ... -``` -{% endtab %} -{% tab reachable-backends Universal %} -```yaml -type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: demo-app - transparentProxying: - redirectPortInbound: 15006 - redirectPortOutbound: 15001 - reachableBackends: - refs: - - kind: MeshService - name: redis - port: 6379 -``` -{% endtab %} -{% endtabs %} - -##### `demo-app` doesn't need to communicate with any service - -{% tabs reachable-backends-no-services useUrlFragment=false %} -{% tab reachable-backends-no-services Kubernetes %} -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: demo-app - namespace: kuma-demo -spec: - ... - template: - metadata: - ... - annotations: - kuma.io/reachable-backends: "" - spec: - containers: - ... -``` -{% endtab %} -{% tab reachable-backends-no-services Universal %} -```yaml -type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: demo-app - transparentProxying: - redirectPortInbound: 15006 - redirectPortOutbound: 15001 - reachableBackends: {} -``` -{% endtab %} -{% endtabs %} - -##### `demo-app` wants to communicate with all MeshServices in `kuma-demo` namespace - -{% tabs reachable-backends-in-namespace useUrlFragment=false %} -{% tab reachable-backends-in-namespace Kubernetes %} -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: demo-app - namespace: kuma-demo -spec: - ... - template: - metadata: - ... - annotations: - kuma.io/reachable-backends: | - refs: - - kind: MeshService - labels: - k8s.kuma.io/namespace: kuma-demo - spec: - containers: - ... -``` -{% endtab %} -{% endtabs %} - -{% endif_version %} ### Transparent Proxy with eBPF (experimental) Starting from {{site.mesh_product_name}} 2.0 you can set up transparent proxy to use eBPF instead of iptables. From f30537b3b88ca5b63cc70e95e94ab4a8f60b9655 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:28:50 +0100 Subject: [PATCH 05/40] chore: make vale happy Signed-off-by: Bart Smykla --- .github/styles/config/vocabularies/Base/accept.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/styles/config/vocabularies/Base/accept.txt b/.github/styles/config/vocabularies/Base/accept.txt index eaa9ba9d2..a4d512d75 100644 --- a/.github/styles/config/vocabularies/Base/accept.txt +++ b/.github/styles/config/vocabularies/Base/accept.txt @@ -149,7 +149,7 @@ subcommand subgraph subproject sudo -Syslog +[sS]yslog target[Rr]ef tbl tcpdump @@ -173,8 +173,13 @@ Vuejs websockets? wireframes? workspace -yaml +yaml|YAML yml [xX]DS|xds Zipkin zsh +xtables +netfilter +UIDs? +use_original_dst +orin From a6e0d7abd6a56f15a8fc79ec48daef0af175307c Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:34:27 +0100 Subject: [PATCH 06/40] chore: make vale happy Signed-off-by: Bart Smykla --- app/_src/networking/non-mesh-traffic.md | 2 +- app/_src/reference/kubernetes-annotations.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/app/_src/networking/non-mesh-traffic.md b/app/_src/networking/non-mesh-traffic.md index 213726b20..3f4aad36b 100644 --- a/app/_src/networking/non-mesh-traffic.md +++ b/app/_src/networking/non-mesh-traffic.md @@ -9,7 +9,7 @@ If you want to allow external clients to consume mesh services see the [Permissive mTLS](/docs/{{ page.version }}/policies/mutual-tls/#permissive-mtls) mode. {% warning %} -Without [Transparent Proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) +Without [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) TLS check on Envoy can be bypassed. You should take action to secure the application ports. {% endwarning %} diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index 6a3598011..e6418c883 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -575,11 +575,11 @@ spec: ### `kuma.io/transparent-proxying-ebpf` -When transparent proxy is installed with ebpf mode, you can disable it for particular workloads if necessary. +When transparent proxy is installed with eBPF mode, you can disable it for particular workloads if necessary. {% capture tproxy-ebpf-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} -For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). +For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). **Example** @@ -605,7 +605,7 @@ spec: Path to BPF FS if different than default (`/sys/fs/bpf`) -For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). +For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). **Example** @@ -631,7 +631,7 @@ spec: cgroup2 path if different than default (`/sys/fs/cgroup`) -For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). +For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). **Example** @@ -655,9 +655,9 @@ spec: ### `kuma.io/transparent-proxying-ebpf-programs-source-path` -Custom path for ebpf programs to be loaded when installing transparent proxy +Custom path for eBPF programs to be loaded when installing transparent proxy -For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). +For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). **Example** @@ -685,7 +685,7 @@ Name of the network interface which should be used to attach to it TC-related eBPF programs. By default {{site.mesh_product_name}} will use first, non-loopback interface it'll find. -For more details see the [transparent proxying with ebpf docs]({{ tproxy-ebpf-link }}). +For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). **Example** From 7edba325ca32ca6c3ad46acdca9a5a222a76bc3d Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:36:02 +0100 Subject: [PATCH 07/40] chore: make vale happy #2 Signed-off-by: Bart Smykla --- app/_src/reference/kubernetes-annotations.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index e6418c883..823075b0a 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -577,7 +577,9 @@ spec: When transparent proxy is installed with eBPF mode, you can disable it for particular workloads if necessary. + {% capture tproxy-ebpf-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} + For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). From 62672e2c9dcb6a3358c684aeb5b974b44289e0c6 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 09:55:53 +0100 Subject: [PATCH 08/40] chore: add missing `inline:true` to if_versions + fix one more link Signed-off-by: Bart Smykla --- app/_src/introduction/kuma-requirements.md | 2 +- app/_src/networking/dns.md | 2 +- app/_src/networking/non-mesh-traffic.md | 2 +- app/_src/policies/external-services.md | 2 +- app/_src/policies/meshpassthrough.md | 2 +- app/_src/policies/traffic-permissions.md | 2 +- app/_src/policies/virtual-outbound.md | 2 +- app/_src/production/cp-deployment/multi-zone.md | 2 +- app/_src/production/deployment/multi-zone.md | 2 +- app/_src/production/dp-config/cni.md | 2 +- app/_src/production/dp-config/dpp-on-kubernetes.md | 2 +- app/_src/production/dp-config/dpp.md | 2 +- app/_src/production/upgrades-tuning/fine-tuning.md | 2 +- app/_src/reference/kubernetes-annotations.md | 4 ++-- 14 files changed, 15 insertions(+), 15 deletions(-) diff --git a/app/_src/introduction/kuma-requirements.md b/app/_src/introduction/kuma-requirements.md index 7142512eb..982d8f0f5 100644 --- a/app/_src/introduction/kuma-requirements.md +++ b/app/_src/introduction/kuma-requirements.md @@ -57,7 +57,7 @@ To see if you may need to increase your control-plane's spec, there are two main - propagation time (xds_delivery): this is the time it takes between a change in the mesh and the dataplane receiving its updated configuration. Think about it as the "reactivity of your mesh". - configuration generation time (xds_generation): this is the time it takes for the configuration to be generated. -For any large mesh using transparent-proxy it's highly recommended to use [reachable-services](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/{% endif_version %}reachable-services). +For any large mesh using transparent-proxy it's highly recommended to use [reachable services](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/{% endif_version %}reachable-services). You can also find tuning configuration in the {% if_version lte:2.1.x %}[fine-tuning](/docs/{{ page.version }}/documentation/fine-tuning){% endif_version %}{% if_version gte:2.2.x %}[fine-tuning](/docs/{{ page.version }}/production/upgrades-tuning/fine-tuning/){% endif_version %} section of the docs. diff --git a/app/_src/networking/dns.md b/app/_src/networking/dns.md index 82a333a46..4f4623fef 100644 --- a/app/_src/networking/dns.md +++ b/app/_src/networking/dns.md @@ -4,7 +4,7 @@ title: DNS {{site.mesh_product_name}} ships with DNS resolver to provide service naming - a mapping of hostname to Virtual IPs (VIPs) of services registered in {{site.mesh_product_name}}. -The usage of {{site.mesh_product_name}} DNS is only relevant when [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) is used. +The usage of {{site.mesh_product_name}} DNS is only relevant when [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) is used. ## How it works diff --git a/app/_src/networking/non-mesh-traffic.md b/app/_src/networking/non-mesh-traffic.md index 3f4aad36b..8296bc443 100644 --- a/app/_src/networking/non-mesh-traffic.md +++ b/app/_src/networking/non-mesh-traffic.md @@ -9,7 +9,7 @@ If you want to allow external clients to consume mesh services see the [Permissive mTLS](/docs/{{ page.version }}/policies/mutual-tls/#permissive-mtls) mode. {% warning %} -Without [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) +Without [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) TLS check on Envoy can be bypassed. You should take action to secure the application ports. {% endwarning %} diff --git a/app/_src/policies/external-services.md b/app/_src/policies/external-services.md index 661c07025..5467f228d 100644 --- a/app/_src/policies/external-services.md +++ b/app/_src/policies/external-services.md @@ -66,7 +66,7 @@ networking: Then apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](/docs/{{ page.version }}/reference/http-api). -{% capture tproxy-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version%}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version%}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version%}{% endcapture %} +{% capture tproxy-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version%}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version%}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version%}{% endcapture %} Universal mode is best combined with [transparent proxy]({{ tproxy-link }}). For backward compatibility only, you can consume an external service from within the mesh by filling the proper `outbound` section of the relevant data plane resource: diff --git a/app/_src/policies/meshpassthrough.md b/app/_src/policies/meshpassthrough.md index ca998f2e9..b96573344 100644 --- a/app/_src/policies/meshpassthrough.md +++ b/app/_src/policies/meshpassthrough.md @@ -24,7 +24,7 @@ To learn more about the information in this table, see the [matching docs](/docs ## Configuration {% warning %} -This policy doesn't work with sidecars without [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.8.x %}networking/transparent-proxying/#what-is-transparent-proxying{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). +This policy doesn't work with sidecars without [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.8.x inline:true %}networking/transparent-proxying/#what-is-transparent-proxying{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}). {% endwarning %} The following describes the default configuration settings of the `MeshPassthrough` policy: diff --git a/app/_src/policies/traffic-permissions.md b/app/_src/policies/traffic-permissions.md index 06a4f7df4..ead1928b0 100644 --- a/app/_src/policies/traffic-permissions.md +++ b/app/_src/policies/traffic-permissions.md @@ -70,7 +70,7 @@ The `TrafficPermission` policy can also be used to restrict traffic to [services ### Prerequisites -* {{site.mesh_product_name}} deployed with [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) +* {{site.mesh_product_name}} deployed with [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) * `Mesh` configured to {% if_version lte:2.1.x %}[disable passthrough mode](/docs/{{ page.version }}/policies/mesh/#usage){% endif_version %}{% if_version gte:2.2.x %}[disable passthrough mode](/docs/{{ page.version }}/production/mesh/#usage){% endif_version %} These settings lock down traffic to and from the mesh, which means that requests to any unknown destination are not allowed. The mesh can't rely on mTLS, because there is no data plane proxy on the destination side. diff --git a/app/_src/policies/virtual-outbound.md b/app/_src/policies/virtual-outbound.md index 9f4f72185..7ecd50fbd 100644 --- a/app/_src/policies/virtual-outbound.md +++ b/app/_src/policies/virtual-outbound.md @@ -95,7 +95,7 @@ produce the hostname: `v1.backend.mesh` with port: `1800`. Additional Requirements: -- [Transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) must be enabled. +- [Transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) must be enabled. - Either: - [Data plane proxy DNS](/docs/{{ page.version }}/networking/dns) must be enabled. - Or, the value of `conf.host` must end with the value of `dns_server.domain`, which defaults to `.mesh`. diff --git a/app/_src/production/cp-deployment/multi-zone.md b/app/_src/production/cp-deployment/multi-zone.md index c54cd84d4..856e26189 100644 --- a/app/_src/production/cp-deployment/multi-zone.md +++ b/app/_src/production/cp-deployment/multi-zone.md @@ -449,7 +449,7 @@ outbound: From the data plane running you will now be able to reach the service using `localhost:20012`. -Alternatively, if you configure [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) you can just call `echo-server_echo-example_svc_1010.mesh` without defining an `outbound` section. +Alternatively, if you configure [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) you can just call `echo-server_echo-example_svc_1010.mesh` without defining an `outbound` section. {% endtab %} {% endtabs %} diff --git a/app/_src/production/deployment/multi-zone.md b/app/_src/production/deployment/multi-zone.md index f22c2c7e6..08246a5df 100644 --- a/app/_src/production/deployment/multi-zone.md +++ b/app/_src/production/deployment/multi-zone.md @@ -49,7 +49,7 @@ You can also favor local service instances with {% if_version lte:2.5.x %}[local In the presence of a {% if_version lte:2.1.x %}[zone egress](/docs/{{ page.version }}/explore/zoneegress){% endif_version %}{% if_version gte:2.2.x %}[zone egress](/docs/{{ page.version }}/production/cp-deployment/zoneegress/){% endif_version %}, the traffic is routed through the local zone egress before being sent to the remote zone ingress. -When using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}) (default in Kubernetes), +When using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}) (default in Kubernetes), {{site.mesh_product_name}} generates a VIP, a DNS entry with the format `.mesh`, and will listen for traffic on port 80. The `.mesh:80` format is just a convention. [`VirtualOutbounds`](/docs/{{ page.version }}/policies/virtual-outbound)s enable you to customize the listening port and how the DNS name for these services looks. diff --git a/app/_src/production/dp-config/cni.md b/app/_src/production/dp-config/cni.md index a2a5990a2..602f79e5d 100644 --- a/app/_src/production/dp-config/cni.md +++ b/app/_src/production/dp-config/cni.md @@ -5,7 +5,7 @@ content_type: how-to In order for traffic to flow through the {{site.mesh_product_name}} data plane, all inbound and outbound traffic for a service needs to go through its data plane proxy. -The recommended way of accomplishing this is via [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). +The recommended way of accomplishing this is via [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}). On Kubernetes it's handled automatically by default with the `initContainer` `kuma-init`, but this container requires certain privileges. diff --git a/app/_src/production/dp-config/dpp-on-kubernetes.md b/app/_src/production/dp-config/dpp-on-kubernetes.md index 9545aabc8..5803451e2 100644 --- a/app/_src/production/dp-config/dpp-on-kubernetes.md +++ b/app/_src/production/dp-config/dpp-on-kubernetes.md @@ -7,7 +7,7 @@ On Kubernetes the {% if_version lte:2.1.x %}[`Dataplane`](/docs/{{ page.version The {{ site.mesh_product_name }} control plane injects a `kuma-sidecar` container into your `Pod`'s container. If you're not using the CNI, it also injects a `kuma-init` into `initContainers` to -setup [transparent proxying](../transparent-proxying). +setup [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version%}{% if_version gte:2.9.x inline:true %}/networking/transparent-proxy/introduction/{% endif_version%}). You can control whether {{site.mesh_product_name}} automatically injects the data plane proxy by **labeling** either the Namespace or the Pod with `kuma.io/sidecar-injection=enabled`, e.g. diff --git a/app/_src/production/dp-config/dpp.md b/app/_src/production/dp-config/dpp.md index b54f02a16..98835b2ff 100644 --- a/app/_src/production/dp-config/dpp.md +++ b/app/_src/production/dp-config/dpp.md @@ -50,7 +50,7 @@ A service is a group of all DPP inbounds that have the same `kuma.io/service` ta ### Outbounds An outbound allows the workload to consume a service in the mesh using a local port. -This is only useful when not using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}). +This is only useful when not using [transparent proxy](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}). ## `Dataplane` entity diff --git a/app/_src/production/upgrades-tuning/fine-tuning.md b/app/_src/production/upgrades-tuning/fine-tuning.md index 0b6a6afd9..a1d3f5d56 100644 --- a/app/_src/production/upgrades-tuning/fine-tuning.md +++ b/app/_src/production/upgrades-tuning/fine-tuning.md @@ -12,7 +12,7 @@ By default, with the transparent proxy enabled, each data plane proxy follows al * Smaller configurations reduce network bandwidth. * Envoy manages fewer clusters/listeners, reducing statistics and memory usage. ^ -See [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x %}production/dp-config/transparent-proxying/#reachable-services{% endif_version %}) for configuration details.{% endif_version %} +See [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x inline:true %}production/dp-config/transparent-proxying/#reachable-services{% endif_version %}) for configuration details.{% endif_version %} {% if_version gte:2.9.x %} For more details, including how to configure reachable services, refer to the [Reachable Services](/docs/{{ page.version }}/networking/transparent-proxy/reachable-services/) documentation. diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index 823075b0a..d548bc3b4 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -547,7 +547,7 @@ spec: ### `kuma.io/transparent-proxying-reachable-services` -{% capture reachable-services-docs-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/{% endif_version %}reachable-services{% endcapture %} +{% capture reachable-services-docs-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying#{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/#{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/{% endif_version %}reachable-services{% endcapture %} A comma separated list of `kuma.io/service` to indicate which services this communicates with. For more details see the [reachable services docs]({{ reachable-services-docs-link }}). @@ -578,7 +578,7 @@ spec: When transparent proxy is installed with eBPF mode, you can disable it for particular workloads if necessary. -{% capture tproxy-ebpf-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} +{% capture tproxy-ebpf-link %}/docs/{{ page.version }}/{% if_version lte:2.1.x inline:true %}networking/transparent-proxying/{% endif_version %}{% if_version gte:2.2.x lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}). From cb52e14d7a876cd9379d960d16dcc485a7a73f0c Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 10:06:34 +0100 Subject: [PATCH 09/40] chore: address first part of review comments Signed-off-by: Bart Smykla --- app/_src/introduction/concepts.md | 6 ++++++ app/_src/networking/transparent-proxy/introduction.md | 4 ++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/app/_src/introduction/concepts.md b/app/_src/introduction/concepts.md index 4733abc63..26e98ccd2 100644 --- a/app/_src/introduction/concepts.md +++ b/app/_src/introduction/concepts.md @@ -71,3 +71,9 @@ They can enable traffic management, security, observability and traffic reliabil Policies always have a clear specific area of impact and goal. To learn more about [policies checkout the in depth introduction](/docs/{{ page.version }}/policies/introduction). + +## Transparent Proxy + +A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ site.mesh_product_name}}, it captures this traffic and routes it to the [data plane proxy](#data-plane-proxy--sidecar), allowing [policies](#policy) to be applied. + +For more details, see the [Transparent Proxy](/docs/{{ page.version}}/{% if_version lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}/networking/transparent-proxy/introduction/{% endif_version %}) documentation. diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 7509ee6a8..13e80532a 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -13,7 +13,7 @@ For a full list of transparent proxy settings with examples and configuration op A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ Kuma }}, it captures this traffic and routes it to the [data plane proxy]({{ docs }}/production/dp-config/dpp/#data-plane-proxy), allowing [Mesh policies]({{ docs }}/policies/introduction/#policies) to be applied. -{{ Kuma }} uses [iptables](https://linux.die.net/man/8/iptables) and also has experimental support for [`eBPF`](#transparent-proxy-with-ebpf-experimental) to make this possible. +{{ Kuma }} uses [iptables](https://linux.die.net/man/8/iptables) and also has experimental support for [eBPF](#transparent-proxy-with-ebpf-experimental) to make this possible. {% tip %} For details on how the transparent proxy works in {{ Kuma }}, see the [Technical Overview]({{ docs }}/networking/transparent-proxy/technical-overview/). @@ -28,7 +28,7 @@ In [Kubernetes mode]({{ docs }}/introduction/architecture/#kubernetes-mode), the In this mode, {{ Kuma }} requires the transparent proxy to be enabled, so it **cannot be turned off**. ### Configuration -{:#kubernetes-installation} +{:#kubernetes-configuration} If the default settings don’t fit your needs, see [Adjusting Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/) for ways to change settings and their recommended uses. From e1ff19ba4b0c02222bf209df8ec390cec6785a71 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 10:07:33 +0100 Subject: [PATCH 10/40] chore: make vale happy again Signed-off-by: Bart Smykla --- app/_src/introduction/concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/introduction/concepts.md b/app/_src/introduction/concepts.md index 26e98ccd2..ef95e6564 100644 --- a/app/_src/introduction/concepts.md +++ b/app/_src/introduction/concepts.md @@ -72,7 +72,7 @@ They can enable traffic management, security, observability and traffic reliabil Policies always have a clear specific area of impact and goal. To learn more about [policies checkout the in depth introduction](/docs/{{ page.version }}/policies/introduction). -## Transparent Proxy +## Transparent proxy A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ site.mesh_product_name}}, it captures this traffic and routes it to the [data plane proxy](#data-plane-proxy--sidecar), allowing [policies](#policy) to be applied. From d603cf69f2aa2a703cab2c31ebf23a14454f31df Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 10:19:31 +0100 Subject: [PATCH 11/40] chore: improve one benefit item Signed-off-by: Bart Smykla --- app/_src/networking/transparent-proxy/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 13e80532a..0b24ea79e 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -54,7 +54,7 @@ Using the transparent proxy in [Universal mode]({{ docs }}/introduction/architec redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} ``` -- **Easier service naming**: Use the `.mesh` [DNS domain]({{ docs }}/networking/dns/) to connect to services, like `https://service-1.mesh`, without needing `localhost` and ports from the `Dataplane` resource. +- **Simplified service connectivity**: Take advantage of [Kuma DNS]({{ docs }}/networking/dns/) to use `.mesh` domain names, like `https://service-1.mesh`, for easy service connections without needing `localhost` and ports in the `Dataplane` resource. - **Flexible service naming with [VirtualOutbound]({{ docs }}/policies/virtual-outbound) policy**: It lets you: From dccb7fda0a83b496abf1455f97f6bbe777aadcf0 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 10:45:40 +0100 Subject: [PATCH 12/40] chore: add one more subsection for Universal tproxy docs Signed-off-by: Bart Smykla --- .../styles/vuepress-core/sidebar-group.scss | 14 ++++++-------- app/_data/docs_nav_kuma_2.9.x.yml | 15 +++++++++------ app/_data/docs_nav_kuma_dev.yml | 15 +++++++++------ 3 files changed, 24 insertions(+), 20 deletions(-) diff --git a/app/_assets/styles/vuepress-core/sidebar-group.scss b/app/_assets/styles/vuepress-core/sidebar-group.scss index 5954dcb83..e6cb09c1a 100644 --- a/app/_assets/styles/vuepress-core/sidebar-group.scss +++ b/app/_assets/styles/vuepress-core/sidebar-group.scss @@ -18,17 +18,15 @@ } & > .sidebar-group-items { padding-left: 1rem; - & > li > .sidebar-link { - font-size: 0.95em; - border-left: none; + + & > li { + & > .sidebar-link, .sidebar-group .sidebar-heading { + font-size: 0.95em; + border-left: none; + } } } } - &.depth-2 { - & > .sidebar-heading { - border-left: none; - } - } } .sidebar-heading { diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index dc4615958..c278f7c38 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -281,14 +281,17 @@ items: url: /networking/transparent-proxy/introduction/ - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ - - text: Installing on Universal - url: /networking/transparent-proxy/installing-on-universal/ + - title: Universal + group: true + items: + - text: Installation + url: /networking/transparent-proxy/installing-on-universal/ + - text: Configuration + url: /networking/transparent-proxy/configuration-on-universal/ + - text: Upgrading + url: /networking/transparent-proxy/upgrading-on-universal/ - text: Configuration on Kubernetes url: /networking/transparent-proxy/configuration-on-kubernetes/ - - text: Configuration on Universal - url: /networking/transparent-proxy/configuration-on-universal/ - - text: Upgrading on Universal - url: /networking/transparent-proxy/upgrading-on-universal/ - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index dc4615958..c278f7c38 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -281,14 +281,17 @@ items: url: /networking/transparent-proxy/introduction/ - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ - - text: Installing on Universal - url: /networking/transparent-proxy/installing-on-universal/ + - title: Universal + group: true + items: + - text: Installation + url: /networking/transparent-proxy/installing-on-universal/ + - text: Configuration + url: /networking/transparent-proxy/configuration-on-universal/ + - text: Upgrading + url: /networking/transparent-proxy/upgrading-on-universal/ - text: Configuration on Kubernetes url: /networking/transparent-proxy/configuration-on-kubernetes/ - - text: Configuration on Universal - url: /networking/transparent-proxy/configuration-on-universal/ - - text: Upgrading on Universal - url: /networking/transparent-proxy/upgrading-on-universal/ - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends From 06391d2f77c5e2ba921bb7a02fa203ec183d6d86 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 11:20:25 +0100 Subject: [PATCH 13/40] chore: add links to sections in sidebar and remove "method-#" prefixes Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_2.9.x.yml | 18 +++++++++-- app/_data/docs_nav_kuma_dev.yml | 18 +++++++++-- ...ding-traffic-other-options-k8s.html.liquid | 4 +-- ...ffic-from-transparent-proxy-redirection.md | 10 +++--- app/_src/introduction/concepts.md | 2 +- .../configuration-on-kubernetes.md | 32 ++++++++++--------- .../configuration-on-universal.md | 10 ++++-- 7 files changed, 64 insertions(+), 30 deletions(-) diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index c278f7c38..4815d14ec 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -281,6 +281,15 @@ items: url: /networking/transparent-proxy/introduction/ - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ + - text: Kubernetes + url: /networking/transparent-proxy/configuration-on-kubernetes/ + items: + - text: Control Plane Runtime Configuration + url: /networking/transparent-proxy/configuration-on-kubernetes/#control-plane-runtime-configuration + - text: Configuration in ConfigMap + url: /networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap + - text: Annotations + url: /networking/transparent-proxy/configuration-on-kubernetes/#annotations - title: Universal group: true items: @@ -288,10 +297,15 @@ items: url: /networking/transparent-proxy/installing-on-universal/ - text: Configuration url: /networking/transparent-proxy/configuration-on-universal/ + items: + - text: YAML or JSON Configuration + url: /networking/transparent-proxy/configuration-on-universal/#yaml-or-json-configuration + - text: Environment Variables + url: /networking/transparent-proxy/configuration-on-universal/#environment-variables + - text: CLI Flags + url: /networking/transparent-proxy/configuration-on-universal/#cli-flags - text: Upgrading url: /networking/transparent-proxy/upgrading-on-universal/ - - text: Configuration on Kubernetes - url: /networking/transparent-proxy/configuration-on-kubernetes/ - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index c278f7c38..4815d14ec 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -281,6 +281,15 @@ items: url: /networking/transparent-proxy/introduction/ - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ + - text: Kubernetes + url: /networking/transparent-proxy/configuration-on-kubernetes/ + items: + - text: Control Plane Runtime Configuration + url: /networking/transparent-proxy/configuration-on-kubernetes/#control-plane-runtime-configuration + - text: Configuration in ConfigMap + url: /networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap + - text: Annotations + url: /networking/transparent-proxy/configuration-on-kubernetes/#annotations - title: Universal group: true items: @@ -288,10 +297,15 @@ items: url: /networking/transparent-proxy/installing-on-universal/ - text: Configuration url: /networking/transparent-proxy/configuration-on-universal/ + items: + - text: YAML or JSON Configuration + url: /networking/transparent-proxy/configuration-on-universal/#yaml-or-json-configuration + - text: Environment Variables + url: /networking/transparent-proxy/configuration-on-universal/#environment-variables + - text: CLI Flags + url: /networking/transparent-proxy/configuration-on-universal/#cli-flags - text: Upgrading url: /networking/transparent-proxy/upgrading-on-universal/ - - text: Configuration on Kubernetes - url: /networking/transparent-proxy/configuration-on-kubernetes/ - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends diff --git a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid index 483e1ebf2..c06b75edc 100644 --- a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid +++ b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid @@ -4,7 +4,7 @@ - + Configuration in ConfigMap @@ -27,7 +27,7 @@ - + Control Plane Runtime Configuration diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md index 9c8786fd5..6f1a7386d 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -23,7 +23,7 @@ Use this guide to control which traffic the transparent proxy intercepts and whi - [Adjusting Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/configuration-on-universal/) - [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) -- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#method-3-kubernetes-annotations), since the [{{ configuration-in-configmap }}]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#method-2-configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. +- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#annotations), since the [{{ configuration-in-configmap }}]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. ## Terminology overview @@ -110,7 +110,7 @@ redirect: ### Other configuration options {:.no-anchor#excluding-incoming-traffic-to-specific-ports-universal-other-options} -[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-2-using-environment-variables) +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#environment-variables) ```sh KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS="1234" \ @@ -118,7 +118,7 @@ KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS="5678,8900" \ kumactl install transparent-proxy ``` -[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-3-cli-flags) +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#cli-flags) ```sh kumactl install transparent-proxy \ @@ -173,7 +173,7 @@ redirect: ### Other configuration options {:.no-anchor#exclude-traffic-to-and-from-specific-ip-addresses-universal-other-options} -[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-2-using-environment-variables) +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#environment-variables) ```sh KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS="10.0.0.0/8" \ @@ -181,7 +181,7 @@ KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS="192.168.10.1,fd1 kumactl install transparent-proxy ``` -[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#method-3-cli-flags) +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#cli-flags) ```sh kumactl install transparent-proxy \ diff --git a/app/_src/introduction/concepts.md b/app/_src/introduction/concepts.md index ef95e6564..7a60dc680 100644 --- a/app/_src/introduction/concepts.md +++ b/app/_src/introduction/concepts.md @@ -74,6 +74,6 @@ To learn more about [policies checkout the in depth introduction](/docs/{{ page. ## Transparent proxy -A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ site.mesh_product_name}}, it captures this traffic and routes it to the [data plane proxy](#data-plane-proxy--sidecar), allowing [policies](#policy) to be applied. +A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ site.mesh_product_name}}, it captures this traffic and routes it to the data plane proxy, allowing policies to be applied. For more details, see the [Transparent Proxy](/docs/{{ page.version}}/{% if_version lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}/networking/transparent-proxy/introduction/{% endif_version %}) documentation. diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md index a5d9aaa25..3723b597c 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md +++ b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md @@ -25,7 +25,9 @@ It’s best to stick to one method whenever possible. Using more than one can ma - **ConfigMap**: In this guide, **ConfigMap** refers to the Kubernetes [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/) resource. It’s used to store configuration data as key-value pairs that can be easily accessed by other resources in the cluster, such as Pods, Deployments, and StatefulSets. -## Method 1: Control plane runtime configuration + +## Control Plane Runtime Configuration + The control plane runtime configuration is a section of {{ Kuma }}'s configuration that contains important settings for how the control plane operates, including options for the transparent proxy and other key components. @@ -35,7 +37,7 @@ For more details, see the [Control Plane Configuration Reference]({{ docs }}/ref Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. -Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all workloads. In the future, once the [{{ configuration-in-configmap }}](#method-1-control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all workloads. In the future, once the [{{ configuration-in-configmap }}](#control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. Below is a subset of the configuration focused on transparent proxy settings, with default values and corresponding environment variables for each field. For further details, see the [Modifying control plane runtime configuration](#modifying-control-plane-runtime-configuration) section. @@ -93,14 +95,14 @@ If you try to change these settings with methods described later in this guide, Attempts to modify this setting using the `kuma.io/sidecar-uid` annotation or `kumaDPUser` in the ConfigMap will result in: - - A warning in control plane logs if the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is **enabled**, and the values will be ignored. + - A warning in control plane logs if the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is **enabled**, and the values will be ignored. - Silent ignoring of the change without warnings if the feature is **disabled**. - **`runtime.kubernetes.injector.builtinDNS.enabled` and `runtime.kubernetes.injector.builtinDNS.port`** Attempts to modify these settings using deprecated annotations `kuma.io/builtin-dns` and `kuma.io/builtin-dns-port`, or `redirect.dns.enabled` and `redirect.dns.port` in the ConfigMap, will have the following effects: - - If the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is **enabled**, warnings will appear in the control plane logs, and values will be ignored. + - If the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is **enabled**, warnings will appear in the control plane logs, and values will be ignored. - If the feature is **disabled**, changes through annotations **will still apply**, possibly leading to broken DNS redirection. This can result in `kuma-dp` not starting the DNS server or listening on the wrong port, which may create issues in the environment. {{ behavior-difference-danger | indent | indent }} @@ -226,14 +228,14 @@ For example, if `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts See the [**Order of Precedence**](#order-of-precedence) section to understand how different methods affect the final configuration applied. -## Method 2: Configuration in ConfigMap (experimental) -{:#method-2-configuration-in-configmap} +## Configuration in ConfigMap (experimental) +{:#configuration-in-configmap} {% warning %} Because this feature impacts multiple underlying components, it is considered experimental. Use it with caution. {% if site.mesh_product_name == "Kuma" %} If you encounter any unexpected behavior or issues, please [**contact us**](/community) and [**submit an issue on GitHub**](https://github.com/kumahq/kuma/issues/new/choose). Your feedback is essential in helping us improve this feature. {% endif %} {% endwarning %} -Until {{ Kuma }} 2.9, transparent proxy settings could only be modified through the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration) and [Kubernetes Annotations](#method-3-kubernetes-annotations), which had several limitations: +Until {{ Kuma }} 2.9, transparent proxy settings could only be modified through the [Control Plane Runtime Configuration](#control-plane-runtime-configuration) and [Annotations](#annotations), which had several limitations: - Not all settings were available through both methods; some could only be adjusted with annotations, while others were limited to the runtime configuration. - Control plane runtime settings were applied globally to all workloads with injected data planes, making it hard to customize settings for specific groups of workloads. @@ -305,12 +307,12 @@ kubectl annotate pods "traffic.kuma.io/transparent-proxy-configmap-na This allows flexibility, enabling different workloads to use distinct ConfigMap settings while maintaining a global default. -## Method 3: Kubernetes annotations +## Annotations Kubernetes annotations can be applied to individual workloads to modify the transparent proxy configuration. These annotations allow fine-tuning of specific behaviors for a single workload without affecting others. {% tip %} -Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. +Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. {% endtip %} Below you can find a list of annotations that can be used to configure specific transparent proxy settings. @@ -343,7 +345,7 @@ Below you can find a list of annotations that can be used to configure specific - `kuma.io/transparent-proxying-ip-family-mode` -The following annotations also affect the configuration, but their values are automatically managed by {{ Kuma }} and cannot be manually adjusted. Values of these annotations will always match those specified in the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration). For more details, refer to [Settings restricted to control plane runtime configuration](#settings-restricted-to-control-plane-runtime-configuration). +The following annotations also affect the configuration, but their values are automatically managed by {{ Kuma }} and cannot be manually adjusted. Values of these annotations will always match those specified in the [Control Plane Runtime Configuration](#control-plane-runtime-configuration). For more details, refer to [Settings restricted to control plane runtime configuration](#settings-restricted-to-control-plane-runtime-configuration). - `kuma.io/sidecar-uid` @@ -382,11 +384,11 @@ The following annotations differ from others mentioned earlier as they are relat - `traffic.kuma.io/transparent-proxy-configmap-name` - This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. + This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. ### Automatically applied annotations -Certain annotations are automatically added to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers), regardless of whether they are explicitly defined. These annotations reflect the final values used to configure the transparent proxy. For settings that can be manually specified, these annotations will still be applied, even if not explicitly provided, using values from the [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration). +Certain annotations are automatically added to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers), regardless of whether they are explicitly defined. These annotations reflect the final values used to configure the transparent proxy. For settings that can be manually specified, these annotations will still be applied, even if not explicitly provided, using values from the [Control Plane Runtime Configuration](#control-plane-runtime-configuration). The automatically applied annotations include: @@ -414,8 +416,8 @@ When using multiple configuration methods, it's important to understand the orde 1. Defaults (refer to [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) for exact values) -2. [Control Plane Runtime Configuration](#method-1-control-plane-runtime-configuration) +2. [Control Plane Runtime Configuration](#control-plane-runtime-configuration) -3. [{{ configuration-in-configmap }}](#method-2-configuration-in-configmap) +3. [{{ configuration-in-configmap }}](#configuration-in-configmap) -4. [Kubernetes Annotations](#method-3-kubernetes-annotations) +4. [Annotations](#annotations) diff --git a/app/_src/networking/transparent-proxy/configuration-on-universal.md b/app/_src/networking/transparent-proxy/configuration-on-universal.md index 845159cb5..dfc359a18 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-universal.md +++ b/app/_src/networking/transparent-proxy/configuration-on-universal.md @@ -40,7 +40,7 @@ It’s best to stick to one method whenever possible. Using more than one can ma Here are the methods, listed by precedence, from lowest to highest. -### Method 1: YAML or JSON configuration +### YAML or JSON Configuration You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. @@ -97,7 +97,9 @@ Below are examples of using these flags in different ways: " | kumactl install transparent-proxy --config-file - ``` -### Method 2: Using environment variables + +### Environment Variables + You can customize configuration settings by using environment variables. For example: @@ -109,7 +111,9 @@ KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy To see all available environment variables, visit the [Environment Variables]({{ ref-env }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). {% endtip %} -### Method 3: CLI flags + +### CLI Flags + Most configuration values can also be specified directly through CLI flags. For example: From 40672b77c3da9af9636aa1f8c1df6e4e5e49931b Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 11:35:43 +0100 Subject: [PATCH 14/40] address some of the review comments Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_2.9.x.yml | 4 ++-- app/_data/docs_nav_kuma_dev.yml | 4 ++-- .../transparent-proxy/configuration-on-kubernetes.md | 12 +++--------- .../transparent-proxy/configuration-on-universal.md | 2 +- .../transparent-proxy/installing-on-universal.md | 8 -------- 5 files changed, 8 insertions(+), 22 deletions(-) diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index 4815d14ec..dd2b8699f 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -298,8 +298,8 @@ items: - text: Configuration url: /networking/transparent-proxy/configuration-on-universal/ items: - - text: YAML or JSON Configuration - url: /networking/transparent-proxy/configuration-on-universal/#yaml-or-json-configuration + - text: YAML / JSON + url: /networking/transparent-proxy/configuration-on-universal/#yaml--json - text: Environment Variables url: /networking/transparent-proxy/configuration-on-universal/#environment-variables - text: CLI Flags diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index 4815d14ec..dd2b8699f 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -298,8 +298,8 @@ items: - text: Configuration url: /networking/transparent-proxy/configuration-on-universal/ items: - - text: YAML or JSON Configuration - url: /networking/transparent-proxy/configuration-on-universal/#yaml-or-json-configuration + - text: YAML / JSON + url: /networking/transparent-proxy/configuration-on-universal/#yaml--json - text: Environment Variables url: /networking/transparent-proxy/configuration-on-universal/#environment-variables - text: CLI Flags diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md index 3723b597c..5a878a249 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md +++ b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md @@ -16,15 +16,9 @@ content_type: how-to The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This guide explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one. While these methods can be used individually, they can also be combined when necessary. {% warning %} -It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. +It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence** section](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. {% endwarning %} -## Terminology overview - -- **Workload**: In this guide, **workload** refers to an application running in a Kubernetes cluster, usually represented by a [**Pod**](https://kubernetes.io/docs/concepts/workloads/pods/). Kubernetes resources like [**Deployment**](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [**ReplicaSet**](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), and [**StatefulSet**](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) are used to define and manage these workloads, resulting in one or more **Pods** where the application actually runs. - -- **ConfigMap**: In this guide, **ConfigMap** refers to the Kubernetes [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/) resource. It’s used to store configuration data as key-value pairs that can be easily accessed by other resources in the cluster, such as Pods, Deployments, and StatefulSets. - ## Control Plane Runtime Configuration @@ -37,7 +31,7 @@ For more details, see the [Control Plane Configuration Reference]({{ docs }}/ref Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. -Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all workloads. In the future, once the [{{ configuration-in-configmap }}](#control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [{{ configuration-in-configmap }}](#control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. Below is a subset of the configuration focused on transparent proxy settings, with default values and corresponding environment variables for each field. For further details, see the [Modifying control plane runtime configuration](#modifying-control-plane-runtime-configuration) section. @@ -414,7 +408,7 @@ These annotations ensure that the proper configuration is automatically applied When using multiple configuration methods, it's important to understand the order in which they are applied to avoid conflicts and ensure the correct settings are used. -1. Defaults (refer to [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) for exact values) +1. [Default values]({{ docs }}/reference/transparent-proxy-configuration/#default-values) 2. [Control Plane Runtime Configuration](#control-plane-runtime-configuration) diff --git a/app/_src/networking/transparent-proxy/configuration-on-universal.md b/app/_src/networking/transparent-proxy/configuration-on-universal.md index dfc359a18..2f11a38f1 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-universal.md +++ b/app/_src/networking/transparent-proxy/configuration-on-universal.md @@ -40,7 +40,7 @@ It’s best to stick to one method whenever possible. Using more than one can ma Here are the methods, listed by precedence, from lowest to highest. -### YAML or JSON Configuration +### YAML / JSON You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. diff --git a/app/_src/networking/transparent-proxy/installing-on-universal.md b/app/_src/networking/transparent-proxy/installing-on-universal.md index f1466573e..977353869 100644 --- a/app/_src/networking/transparent-proxy/installing-on-universal.md +++ b/app/_src/networking/transparent-proxy/installing-on-universal.md @@ -7,20 +7,12 @@ content_type: how-to {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} -{% tip %} -These instructions apply to **Universal** mode, where {{ Kuma }} needs to be manually configured for each environment. In **Kubernetes** mode, the transparent proxy is set up automatically using the [`kuma-init` container]({{ docs }}/production/dp-config/dpp-on-kubernetes/) or [Kuma CNI]({{ docs }}/production/dp-config/cni/), so the steps below do not apply. -{% endtip %} - This page provides instructions for setting up a transparent proxy in your service environment. A transparent proxy helps streamline service management and traffic routing within a mesh, directing all traffic through the data plane proxy without requiring changes to your application code. Once completed, your service will run under a transparent proxy, allowing you to use {{ Kuma }}'s service management features, like traffic control, observability, and security. Before starting, review the prerequisites below and adjust settings to fit your environment, including IP addresses, custom ports, and DNS configurations. -## Terminology overview - -- **Service**: In this instruction, **service** refers to an application running in the environment where the transparent proxy is deployed. An exception is when we refer to [systemd](https://systemd.io/) services; in these cases, **service** specifically means a [systemd service unit](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html). - ## Prerequisites {%- capture control-plane-and-service-network-accessibility-warning %} From a32985d658fc35b04703729c4dd90267a3e684fa Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 11:51:13 +0100 Subject: [PATCH 15/40] chore: make vale happy and change VirtualOutbount to MeshService+ Signed-off-by: Bart Smykla --- .../transparent-proxy/configuration-on-kubernetes.md | 2 ++ app/_src/networking/transparent-proxy/introduction.md | 10 +++++----- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md index 5a878a249..ea3222b97 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md +++ b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md @@ -222,8 +222,10 @@ For example, if `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts See the [**Order of Precedence**](#order-of-precedence) section to understand how different methods affect the final configuration applied. + ## Configuration in ConfigMap (experimental) {:#configuration-in-configmap} + {% warning %} Because this feature impacts multiple underlying components, it is considered experimental. Use it with caution. {% if site.mesh_product_name == "Kuma" %} If you encounter any unexpected behavior or issues, please [**contact us**](/community) and [**submit an issue on GitHub**](https://github.com/kumahq/kuma/issues/new/choose). Your feedback is essential in helping us improve this feature. {% endif %} diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 0b24ea79e..4e6cc5382 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -56,12 +56,12 @@ Using the transparent proxy in [Universal mode]({{ docs }}/introduction/architec - **Simplified service connectivity**: Take advantage of [Kuma DNS]({{ docs }}/networking/dns/) to use `.mesh` domain names, like `https://service-1.mesh`, for easy service connections without needing `localhost` and ports in the `Dataplane` resource. -- **Flexible service naming with [VirtualOutbound]({{ docs }}/policies/virtual-outbound) policy**: It lets you: +- **Flexible service naming**: With [MeshServices]({{ docs }}/networking/meshservice/) and [HostnameGenerators]({{ docs }}/networking/hostnamegenerator/), you can: - - Keep existing DNS names when moving to the service mesh. - - Assign multiple DNS names to a service for renaming or convenience. - - Create specific routes, like targeting individual StatefulSet Pods or service versions. - - Expose multiple inbounds for a service on different ports. + - Keep your existing DNS names when moving to the service mesh. + - Give a service multiple DNS names for easier access. + - Set up custom routes, like targeting specific StatefulSet Pods or service versions. + - Expose a service on multiple ports for different uses. - **Simpler security, tracing, and observability**: Transparent proxy makes managing these features easier, with no extra setup required. From 5850b72de9dfb43f9bebf6b68fec9342411d76ed Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 12:18:16 +0100 Subject: [PATCH 16/40] chore: small content fixes Signed-off-by: Bart Smykla --- .../networking/transparent-proxy/configuration-on-kubernetes.md | 2 +- app/_src/networking/transparent-proxy/upgrading-on-universal.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md index ea3222b97..c83a40975 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md +++ b/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md @@ -31,7 +31,7 @@ For more details, see the [Control Plane Configuration Reference]({{ docs }}/ref Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. -Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [{{ configuration-in-configmap }}](#control-plane-runtime-configuration) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. Below is a subset of the configuration focused on transparent proxy settings, with default values and corresponding environment variables for each field. For further details, see the [Modifying control plane runtime configuration](#modifying-control-plane-runtime-configuration) section. diff --git a/app/_src/networking/transparent-proxy/upgrading-on-universal.md b/app/_src/networking/transparent-proxy/upgrading-on-universal.md index b3d112e13..b76725488 100644 --- a/app/_src/networking/transparent-proxy/upgrading-on-universal.md +++ b/app/_src/networking/transparent-proxy/upgrading-on-universal.md @@ -51,5 +51,5 @@ kumactl install transparent-proxy [...] This command will install the new version of the transparent proxy with the specified configuration. Adjust the flags as needed to suit your environment. {% tip %} -For a comprehensive documentation of installing the transparent proxy in Universal mode, including details on preparing the environment, understanding any restrictions, and configuring `Dataplane` objects to work with the transparent proxy, refer to the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) guide. +For a comprehensive documentation of installing the transparent proxy in Universal mode, including details on preparing the environment, understanding any restrictions, and configuring `Dataplane` objects to work with the transparent proxy, refer to the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) page. {% endtip %} From d55b488885c603ba79b6763cbde3e65608f8b4ec Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 15:11:18 +0100 Subject: [PATCH 17/40] simplify the docs Signed-off-by: Bart Smykla --- app/_assets/styles/vuepress-core/index.scss | 4 + app/_data/docs_nav_kuma_2.9.x.yml | 31 +- app/_data/docs_nav_kuma_dev.yml | 31 +- ...ding-traffic-other-options-k8s.html.liquid | 4 +- ...ffic-from-transparent-proxy-redirection.md | 26 +- .../configuration-on-universal.md | 174 ------------ .../transparent-proxy/introduction.md | 61 +--- ...uration-on-kubernetes.md => kubernetes.md} | 234 +++------------ ...nstalling-on-universal.md => universal.md} | 268 ++++++++++++++++-- .../upgrading-on-universal.md | 55 ---- .../transparent-proxy-configuration.md | 32 +++ 11 files changed, 367 insertions(+), 553 deletions(-) delete mode 100644 app/_src/networking/transparent-proxy/configuration-on-universal.md rename app/_src/networking/transparent-proxy/{configuration-on-kubernetes.md => kubernetes.md} (54%) rename app/_src/networking/transparent-proxy/{installing-on-universal.md => universal.md} (54%) delete mode 100644 app/_src/networking/transparent-proxy/upgrading-on-universal.md diff --git a/app/_assets/styles/vuepress-core/index.scss b/app/_assets/styles/vuepress-core/index.scss index 3556aebbe..61d7c2c47 100644 --- a/app/_assets/styles/vuepress-core/index.scss +++ b/app/_assets/styles/vuepress-core/index.scss @@ -164,6 +164,10 @@ h3 { font-size: 1.35rem; } +h4 { + font-size: 1.15rem; +} + a.header-anchor { font-size: 0.85em; float: left; diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index dd2b8699f..2680adaff 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -282,30 +282,27 @@ items: - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ - text: Kubernetes - url: /networking/transparent-proxy/configuration-on-kubernetes/ + url: /networking/transparent-proxy/kubernetes/ items: + - text: Configuration + url: /networking/transparent-proxy/kubernetes/#configuration - text: Control Plane Runtime Configuration - url: /networking/transparent-proxy/configuration-on-kubernetes/#control-plane-runtime-configuration + url: /networking/transparent-proxy/kubernetes/#control-plane-runtime-configuration - text: Configuration in ConfigMap - url: /networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap + url: /networking/transparent-proxy/kubernetes/#configuration-in-configmap-experimental - text: Annotations - url: /networking/transparent-proxy/configuration-on-kubernetes/#annotations - - title: Universal - group: true + url: /networking/transparent-proxy/kubernetes/#annotations + - text: Universal + url: /networking/transparent-proxy/universal/ items: - text: Installation - url: /networking/transparent-proxy/installing-on-universal/ - - text: Configuration - url: /networking/transparent-proxy/configuration-on-universal/ - items: - - text: YAML / JSON - url: /networking/transparent-proxy/configuration-on-universal/#yaml--json - - text: Environment Variables - url: /networking/transparent-proxy/configuration-on-universal/#environment-variables - - text: CLI Flags - url: /networking/transparent-proxy/configuration-on-universal/#cli-flags + url: /networking/transparent-proxy/universal/#installation - text: Upgrading - url: /networking/transparent-proxy/upgrading-on-universal/ + url: /networking/transparent-proxy/universal/#upgrading + - text: Configuration + url: /networking/transparent-proxy/universal/#configuration + - text: firewalld support + url: /networking/transparent-proxy/universal/#firewalld-support - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index dd2b8699f..fc9fe5c7b 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -282,30 +282,27 @@ items: - text: Technical Overview url: /networking/transparent-proxy/technical-overview/ - text: Kubernetes - url: /networking/transparent-proxy/configuration-on-kubernetes/ + url: /networking/transparent-proxy/kubernetes/ items: + - text: Configuration + url: /networking/transparent-proxy/kubernetes/#configuration - text: Control Plane Runtime Configuration - url: /networking/transparent-proxy/configuration-on-kubernetes/#control-plane-runtime-configuration + url: /networking/transparent-proxy/kubernetes/#control-plane-runtime-configuration - text: Configuration in ConfigMap - url: /networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap + url: /networking/transparent-proxy/kubernetes/#configuration-in-configmap - text: Annotations - url: /networking/transparent-proxy/configuration-on-kubernetes/#annotations - - title: Universal - group: true + url: /networking/transparent-proxy/kubernetes/#annotations + - text: Universal + url: /networking/transparent-proxy/universal/ items: - text: Installation - url: /networking/transparent-proxy/installing-on-universal/ - - text: Configuration - url: /networking/transparent-proxy/configuration-on-universal/ - items: - - text: YAML / JSON - url: /networking/transparent-proxy/configuration-on-universal/#yaml--json - - text: Environment Variables - url: /networking/transparent-proxy/configuration-on-universal/#environment-variables - - text: CLI Flags - url: /networking/transparent-proxy/configuration-on-universal/#cli-flags + url: /networking/transparent-proxy/universal/#installation - text: Upgrading - url: /networking/transparent-proxy/upgrading-on-universal/ + url: /networking/transparent-proxy/universal/#upgrading + - text: Configuration + url: /networking/transparent-proxy/universal/#configuration + - text: firewalld support + url: /networking/transparent-proxy/universal/#firewalld-support - text: Reachable Services url: /networking/transparent-proxy/reachable-services/ - text: Reachable Backends diff --git a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid index c06b75edc..00cb6535e 100644 --- a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid +++ b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid @@ -4,7 +4,7 @@ - + Configuration in ConfigMap @@ -27,7 +27,7 @@ - + Control Plane Runtime Configuration diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md index 6f1a7386d..cd2b6a6a7 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -6,8 +6,6 @@ title: Excluding Traffic from Transparent Proxy {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} -{% assign configuration-in-configmap = "Configuration in ConfigMap (experimental)" %} - This guide will show you how to exclude specific types of traffic from being redirected by the transparent proxy. It includes instructions for both **Universal** and a **Kubernetes** modes and covers different types of traffic you might want to exclude, such as: - [Exclude traffic on certain ports (incoming & outgoing)](#exclude-traffic-on-certain-ports) @@ -19,11 +17,11 @@ Use this guide to control which traffic the transparent proxy intercepts and whi - This guide shows how to set up the transparent proxy to exclude certain types of traffic from redirection for selected workloads. We’ll cover some methods for both Kubernetes and Universal modes, but **not all possible scenarios are explained in detail**. For more information on options briefly mentioned here, check out: - - [Adjusting Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/) - - [Adjusting Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/configuration-on-universal/) + - [Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration) + - [Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/universal/#configuration) - [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) -- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#annotations), since the [{{ configuration-in-configmap }}]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/#configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. +- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/kubernetes/#annotations), since the [Configuration in ConfigMap]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. ## Terminology overview @@ -41,8 +39,8 @@ Use this guide to control which traffic the transparent proxy intercepts and whi - For an in-depth look at how the transparent proxy works in {{ Kuma }} and its mechanisms, see the [Technical Overview]({{ docs }}/networking/transparent-proxy/technical-overview/) page from its documentation. - - To install the transparent proxy on Universal, refer to [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/). - - For upgrade steps, see [Upgrading Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/upgrading-on-universal/). + - To install the transparent proxy on Universal, refer to [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/#installation). + - For upgrade steps, see [Upgrading Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/#upgrading). 2. **Set up {{ Kuma }}**: Ensure {{ Kuma }} is installed and running. @@ -54,11 +52,11 @@ Use this guide to control which traffic the transparent proxy intercepts and whi {% tab prerequisites-setup-kuma Universal %} Confirm that all necessary components are up and running. The following resources may be useful: - - To set up a single-zone control plane, follow the [Single Zone Control Plane Deployment]({{ docs }}/production/cp-deployment/single-zone/) guide. + - To set up a single-zone control plane, follow the [Single Zone Control Plane Deployment]({{ docs }}/production/cp-deployment/single-zone/) guide. - - To generate a data plane proxy token (needed to authorize data plane proxies), refer to [Data Plane Proxy Token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) documentation. + - To generate a data plane proxy token (needed to authorize data plane proxies), refer to [Data Plane Proxy Token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) documentation. - - To prepare your service environment and start the data plane proxy, follow the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) guide up to [Step 5: Install the transparent proxy]({{ docs }}/networking/transparent-proxy/installing-on-universal/#step-5-install-the-transparent-proxy). + - To set up your service environment and start the data plane proxy, follow the steps in the [Installing]({{ docs }}/networking/transparent-proxy/universal/#installation) section of the [Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/) documentation up to [Step 5: Install the Transparent Proxy]({{ docs }}/networking/transparent-proxy/universal/#step-5-install-the-transparent-proxy). {% endtab %} {% endtabs %} {% endcapture %} @@ -110,7 +108,7 @@ redirect: ### Other configuration options {:.no-anchor#excluding-incoming-traffic-to-specific-ports-universal-other-options} -[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#environment-variables) +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/universal/#environment-variables) ```sh KUMA_TRANSPARENT_PROXY_REDIRECT_INBOUND_EXCLUDE_PORTS="1234" \ @@ -118,7 +116,7 @@ KUMA_TRANSPARENT_PROXY_REDIRECT_OUTBOUND_EXCLUDE_PORTS="5678,8900" \ kumactl install transparent-proxy ``` -[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#cli-flags) +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/universal/#cli-flags) ```sh kumactl install transparent-proxy \ @@ -173,7 +171,7 @@ redirect: ### Other configuration options {:.no-anchor#exclude-traffic-to-and-from-specific-ip-addresses-universal-other-options} -[**Environment Variables**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#environment-variables) +[**Environment Variables**]({{ docs }}/networking/transparent-proxy/universal/#environment-variables) ```sh KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS="10.0.0.0/8" \ @@ -181,7 +179,7 @@ KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS="192.168.10.1,fd1 kumactl install transparent-proxy ``` -[**CLI Flags**]({{ docs }}/networking/transparent-proxy/configuration-on-universal/#cli-flags) +[**CLI Flags**]({{ docs }}/networking/transparent-proxy/universal/#cli-flags) ```sh kumactl install transparent-proxy \ diff --git a/app/_src/networking/transparent-proxy/configuration-on-universal.md b/app/_src/networking/transparent-proxy/configuration-on-universal.md deleted file mode 100644 index 2f11a38f1..000000000 --- a/app/_src/networking/transparent-proxy/configuration-on-universal.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Adjusting Transparent Proxy Configuration on Universal ---- - -{% assign docs = "/docs/" | append: page.version %} -{% assign Kuma = site.mesh_product_name %} - -{% assign tproxy = site.data.tproxy %} - -{% assign ref = docs | append: "/reference/transparent-proxy-configuration/" %} -{% assign ref-schema = ref | append: "#schema" %} -{% assign ref-env = ref | append: "#environment-variables" %} -{% assign ref-cli = ref | append: "#cli-flags" %} -{% assign ref-default = ref | append: "#default-values" %} -{% assign ref-full = ref | append: "#full-reference" %} - -The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This page explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one. - -## Configuration reference - -{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Full Reference]({{ ref-full }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). - -If you're only interested in specific parts of the reference, here are links to simplified sections: - -| Section | Description | -|:------------------------------------------------|:----------------------------------------------------------------------------------------| -| [**Schema**]({{ ref-schema }}) | A concise version of the configuration schema, including default values. | -| [**Environment Variables**]({{ ref-env }}) | A configuration structure showing fields and their corresponding environment variables. | -| [**CLI Flags**]({{ ref-cli }}) | A configuration structure showing fields and their corresponding CLI flags. | -| [**Default Values**]({{ ref-default }}) | A structure displaying only the fields with their default values. | - -## Methods of customizing the configuration - -In Universal environments, {{ Kuma }} provides three ways to adjust the transparent proxy configuration. Each method can be used on its own or combined with others if needed. - -{% warning %} -It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. -{% endwarning %} - -Here are the methods, listed by precedence, from lowest to highest. - - -### YAML / JSON - - -You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. - -{% tip %} -For the configuration schema in YAML format, refer to the [Schema]({{ ref-schema }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). -{% endtip %} - -{% tip %} -For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs. -{% endtip %} - -Below are examples of using these flags in different ways: - -1. **Providing configuration via the `--config-file` flag** - - Assume you have a `config.yaml` file with the following content: - - ```yaml - kumaDPUser: dataplane - verbose: true - ``` - - You can install the transparent proxy using: - - ```sh - kumactl install transparent-proxy --config-file config.yaml - ``` - -2. **Passing configuration directly via the `--config` flag** - - To pass the configuration content directly: - - ```sh - kumactl install transparent-proxy --config "kumaDPUser: dataplane\nverbose: true" - ``` - - Alternatively: - - ```sh - kumactl install transparent-proxy --config "{ kumaDPUser: dataplane, verbose: true }" - ``` - - Both formats are valid YAML inputs. - -3. **Passing configuration via [STDIN](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin))** - - If you need to pass the configuration via STDIN, set `--config-file` to `-` as shown below: - - ```sh - echo " - kumaDPUser: dataplane - verbose: true - " | kumactl install transparent-proxy --config-file - - ``` - - -### Environment Variables - - -You can customize configuration settings by using environment variables. For example: - -```sh -KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy -``` - -{% tip %} -To see all available environment variables, visit the [Environment Variables]({{ ref-env }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). -{% endtip %} - - -### CLI Flags - - -Most configuration values can also be specified directly through CLI flags. For example: - -```sh -kumactl install transparent-proxy --kuma-dp-user dataplane --verbose -``` - -{% warning %} -The following settings cannot be modified directly via CLI flags (corresponding flags are not available): - -- `redirect.dns.resolvConfigPath` -- `redirect.inbound.includePorts` -- `redirect.inbound.excludePortsForUIDs` -- `redirect.outbound.enabled` -- `redirect.outbound.includePorts` -- `ebpf.instanceIPEnvVarName` -- `log.level` -- `cniMode` -{% endwarning %} - -{% tip %} -To see all available CLI flags, visit the [CLI Flags]({{ ref-cli }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). -{% endtip %} - -## Order of precedence - -1. **Default Values** -2. **Values from** `--config` / `--config-file` **flags** -3. **Environment Variables** -4. **CLI Flags** - -To understand how the order of precedence works, consider this scenario: - -1. You have a `config.yaml` file with the following content: - - ```yaml - redirect: - dns: - port: 10001 - ``` - -2. You install the transparent proxy using this command: - - ```sh - KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT="10002" \ - kumactl install transparent-proxy \ - --config-file config.yaml \ - --redirect-dns-port 10003 - ``` - -3. In this situation, the possible values for `redirect.dns.port` are: - - - **`{{ tproxy.defaults.redirect.dns.port }}`** (Default Value) - - **`10001`** (From Config File) - - **`10002`** (From Environment Variable) - - **`10003`** (From CLI Flag) - -4. Since CLI flags have the highest precedence, the final value for `redirect.dns.port` will be **`10003`**. diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 4e6cc5382..f2593bb4b 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -5,11 +5,6 @@ content_type: how-to {% assign docs = "/docs/" | append: page.version %} {% assign Kuma = site.mesh_product_name %} -{% assign tproxy = site.data.tproxy %} - -{% capture tproxy-config-reference-info %} -For a full list of transparent proxy settings with examples and configuration options, see the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). -{% endcapture %} A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ Kuma }}, it captures this traffic and routes it to the [data plane proxy]({{ docs }}/production/dp-config/dpp/#data-plane-proxy), allowing [Mesh policies]({{ docs }}/policies/introduction/#policies) to be applied. @@ -27,32 +22,15 @@ In [Kubernetes mode]({{ docs }}/introduction/architecture/#kubernetes-mode), the In this mode, {{ Kuma }} requires the transparent proxy to be enabled, so it **cannot be turned off**. -### Configuration -{:#kubernetes-configuration} - -If the default settings don’t fit your needs, see [Adjusting Transparent Proxy Configuration on Kubernetes]({{ docs }}/networking/transparent-proxy/configuration-on-kubernetes/) for ways to change settings and their recommended uses. - -{{ tproxy-config-reference-info }} +{% tip %} +For more details on using the transparent proxy with Kubernetes, see [Transparent Proxy on Kubernetes]({{ docs }}/networking/transparent-proxy/kubernetes/). +{% endtip %} ## Universal -Using the transparent proxy in [Universal mode]({{ docs }}/introduction/architecture/#universal-mode) makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: +Using the transparent proxy in Universal mode makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: -- **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. Here’s an example without outbound entries: - - ```yaml - type: Dataplane - name: {% raw %}{{ name }}{% endraw %} - networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: demo-client - transparentProxying: - redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} - redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} - ``` +- **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. - **Simplified service connectivity**: Take advantage of [Kuma DNS]({{ docs }}/networking/dns/) to use `.mesh` domain names, like `https://service-1.mesh`, for easy service connections without needing `localhost` and ports in the `Dataplane` resource. @@ -64,37 +42,12 @@ Using the transparent proxy in [Universal mode]({{ docs }}/introduction/architec - Expose a service on multiple ports for different uses. - **Simpler security, tracing, and observability**: Transparent proxy makes managing these features easier, with no extra setup required. - -### Installation -{:#universal-installation} - -To learn how to integrate the transparent proxy with your existing services or set up a service environment from scratch, see [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/). - -### Configuration -{:#universal-configuration} - -If the default settings don’t fit your needs, see [Adjusting Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/configuration-on-universal/) for ways to modify settings and their recommended uses. - -{{ tproxy-config-reference-info }} - -### firewalld support + For more details related to transparent proxy on Universal refer to [Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/) {% tip %} -In **Kubernetes** mode, transparent proxy is automatically set up using the `kuma-init` container or [Kuma CNI]({{ docs }}/production/dp-config/cni/). Since the proxy is reinstalled each time your workload restarts, there is no need to persist it. This feature is specifically designed for **Universal** environments. +For more details on using the transparent proxy with Universal, see [Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/). {% endtip %} -The changes made by running `kumactl install transparent-proxy` **will not persist** after a reboot. To ensure persistence, you can either add this command to your system's start-up scripts or leverage `firewalld` for managing `iptables`. - -If you prefer using `firewalld`, you can include the `--store-firewalld` flag when installing the transparent proxy. This will store the `iptables` rules in `/etc/firewalld/direct.xml`, ensuring they persist across system reboots. Here's an example: - -```sh -kumactl install transparent-proxy --redirect-dns --store-firewalld -``` - -{% warning %} -**Important:** Currently, there is no uninstall command for this feature. If needed, you will have to manually clean up the `firewalld` configuration. -{% endwarning %} - ### Transparent proxy with eBPF (experimental) diff --git a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md b/app/_src/networking/transparent-proxy/kubernetes.md similarity index 54% rename from app/_src/networking/transparent-proxy/configuration-on-kubernetes.md rename to app/_src/networking/transparent-proxy/kubernetes.md index c83a40975..9fe2a990e 100644 --- a/app/_src/networking/transparent-proxy/configuration-on-kubernetes.md +++ b/app/_src/networking/transparent-proxy/kubernetes.md @@ -1,5 +1,5 @@ --- -title: Adjusting Transparent Proxy Configuration on Kubernetes +title: Transparent Proxy on Kubernetes content_type: how-to --- @@ -11,59 +11,37 @@ content_type: how-to {% assign kuma-control-plane = site.mesh_cp_name %} {% assign kuma-control-plane-config = kuma-control-plane | append: "-config" %} -{% assign configuration-in-configmap = "Configuration in ConfigMap (experimental)" %} +In Kubernetes mode, transparent proxy is automatically set up through the `kuma-init` container or [Kuma CNI]({{ docs }}/production/dp-config/cni/). By default, it intercepts all incoming and outgoing traffic and routes it through the `kuma-dp` sidecar container, so no changes to the application code are needed. -The default transparent proxy configuration works well for most scenarios, but there are cases where adjustments are needed. This guide explains the various methods available for modifying the configuration, along with their limitations and recommendations on when to use each one. While these methods can be used individually, they can also be combined when necessary. +{{ Kuma }} works smoothly with [Kubernetes DNS for Services and Pods](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) and provides its own [Kuma DNS]({{ docs }}/networking/dns/), which is especially helpful in multi-zone setups for cross-zone service discovery. + +In this mode, {{ Kuma }} requires the transparent proxy to be enabled, so it **cannot be turned off**. + +## Configuration + +The default configuration works well for most scenarios, but there are cases where adjustments are needed. + +In Kubernetes mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. {% warning %} It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence** section](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. {% endwarning %} -## Control Plane Runtime Configuration +### Control Plane Runtime Configuration The control plane runtime configuration is a section of {{ Kuma }}'s configuration that contains important settings for how the control plane operates, including options for the transparent proxy and other key components. -{% tip %} -For more details, see the [Control Plane Configuration Reference]({{ docs }}/reference/kuma-cp/) under `runtime.kubernetes`. -{% endtip %} - Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. -Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. - -Below is a subset of the configuration focused on transparent proxy settings, with default values and corresponding environment variables for each field. For further details, see the [Modifying control plane runtime configuration](#modifying-control-plane-runtime-configuration) section. - -```yaml -runtime: - kubernetes: - injector: - cniEnabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_CNI_ENABLED - applicationProbeProxyPort: 9001 # KUMA_RUNTIME_KUBERNETES_APPLICATION_PROBE_PROXY_PORT - sidecarContainer: - uid: 5678 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_UID - ipFamilyMode: dualstack # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_IP_FAMILY_MODE - redirectPortInbound: 15006 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_INBOUND - redirectPortOutbound: 15001 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_OUTBOUND - sidecarTraffic: - excludeInboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS - excludeOutboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS - excludeInboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS - excludeOutboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS - builtinDNS: - enabled: true # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED - port: 15053 # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_PORT - ebpf: - enabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_ENABLED - instanceIPEnvVarName: INSTANCE_IP # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_INSTANCE_IP_ENV_VAR_NAME - bpffsPath: /sys/fs/bpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_BPFFS_PATH - cgroupPath: /sys/fs/cgroup # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_CGROUP_PATH - tcAttachIface: "" # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_TC_ATTACH_IFACE - programsSourcePath: /tmp/kuma-ebpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_PROGRAMS_SOURCE_PATH -``` +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. -### Settings restricted to control plane runtime configuration +{% tip %} +For more details, see the [Control Plane Configuration Reference]({{ docs }}/reference/kuma-cp/) under `runtime.kubernetes`. You can also find transparent proxy-specific settings in the [Control Plane Runtime Configuration section]({{ docs }}/reference/transparent-proxy-configuration/#control-plane-runtime-configuration) of the Transparent Proxy Configuration reference. +{% endtip %} + +#### Settings restricted to control plane runtime configuration Some transparent proxy settings **can only be changed through the control plane’s runtime configuration** because they are shared with other {{ Kuma }} components. These settings handle essential tasks like creating [`Dataplane` resources]({{ docs }}/production/dp-config/dpp/) for workloads and setting up the [`kuma-dp` sidecar container]({{ docs }}/production/dp-config/dpp-on-kubernetes/) alongside them. For example, the DNS port used to redirect traffic is shared between the transparent proxy and the `kuma-dp run` command in the sidecar container. Keeping these settings consistent across workloads prevents misconfigurations. These settings are: @@ -73,158 +51,29 @@ Some transparent proxy settings **can only be changed through the control plane - `runtime.kubernetes.injector.builtinDNS.enabled` - `runtime.kubernetes.injector.builtinDNS.port` -{% capture behavior-difference-danger %} {% danger %} -⚠️ This behavior differs from that of other settings. Ensure you're aware of this distinction and **never** attempt to modify these settings using the mentioned annotations. -{% enddanger %} -{% endcapture %} - -If you try to change these settings with methods described later in this guide, but with values different from the runtime configuration, the effects will vary: - -- **`runtime.kubernetes.injector.sidecarContainer.redirectPortInbound` and `runtime.kubernetes.injector.sidecarContainer.redirectPortOutbound`** - - Attempts to change these settings using `kuma.io/transparent-proxying-inbound-port` and `kuma.io/transparent-proxying-outbound-port` annotations, or by updating `redirect.inbound.port` and `redirect.outbound.port` in the ConfigMap, will trigger warnings in the control plane logs, but the values will be ignored. - -- **`runtime.kubernetes.injector.sidecarContainer.uid`** - - Attempts to modify this setting using the `kuma.io/sidecar-uid` annotation or `kumaDPUser` in the ConfigMap will result in: - - - A warning in control plane logs if the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is **enabled**, and the values will be ignored. - - Silent ignoring of the change without warnings if the feature is **disabled**. - -- **`runtime.kubernetes.injector.builtinDNS.enabled` and `runtime.kubernetes.injector.builtinDNS.port`** - - Attempts to modify these settings using deprecated annotations `kuma.io/builtin-dns` and `kuma.io/builtin-dns-port`, or `redirect.dns.enabled` and `redirect.dns.port` in the ConfigMap, will have the following effects: - - - If the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is **enabled**, warnings will appear in the control plane logs, and values will be ignored. - - If the feature is **disabled**, changes through annotations **will still apply**, possibly leading to broken DNS redirection. This can result in `kuma-dp` not starting the DNS server or listening on the wrong port, which may create issues in the environment. - - {{ behavior-difference-danger | indent | indent }} - -### Modifying control plane runtime configuration - -{% capture modify-runtime-conf-configmap %} -{% capture runtime-conf-in-values-file-create-a-values-file %} -{% helmvalues %} -```yaml -controlPlane: - config: | - runtime: - kubernetes: - injector: - sidecarTraffic: - excludeOutboundIPs: [10.1.0.254, 172.10.1.254] -``` -{% endhelmvalues %} - -{% warning %} -Make sure the content under `{{ controlPlane }}.config` is a string representation of the [control plane configuration]({{ docs }}/reference/kuma-cp/). -{% endwarning %} -{% endcapture %} - -{% capture runtime-conf-in-values-file-install-kuma %} -{% cpinstallfile modify-runtime-config-complete %} -{% endcapture %} - -{% tip %} -This method is **recommended** because it simplifies future modifications. Rather than reinstalling {{ Kuma }} or manually updating its Deployment to change environment variables, you can just update the ConfigMap and restart the `{{ kuma-control-plane }}` Pod to apply the changes. -{% endtip %} - -You can provide the full runtime configuration in the `{{ kuma-control-plane-config }}` ConfigMap within the `{{ kuma-system }}` namespace. - -Here’s an example that excludes specific outbound IPs from transparent proxy redirection: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: {{ kuma-control-plane-config }} - namespace: {{ kuma-system }} -data: - config.yaml: | - runtime: - kubernetes: - injector: - sidecarTraffic: - excludeOutboundIPs: [10.1.0.254, 172.10.1.254] -``` - -Instead of manually updating the ConfigMap in the cluster, you can specify the configuration it will store during the {{ Kuma }} installation. Follow these steps: - -1. Create a `values.yaml` file with the following content: - - {{ runtime-conf-in-values-file-create-a-values-file | indent }} - -2. Install {{ Kuma }} using `kumactl` or Helm: - - {{ runtime-conf-in-values-file-install-kuma | indent }} +⚠️ IMPORTANT +{:.custom-block-title} -{% tip %} -If you're deploying {{ Kuma }} using Helm, you can place the configuration in a separate file and pass it during installation with the `--set-file` flag. - -For example, create a `cp-conf.yaml` file with the following content: - -```yaml -runtime: - kubernetes: - injector: - sidecarTraffic: - excludeOutboundIPs: [10.1.0.254, 172.10.1.254] -``` - -Then, during Helm installation, run: - -```sh -helm install \ - --create-namespace \ - --namespace {{ kuma-system }} \ - --set-file "{{ controlPlane }}.config=cp-conf.yaml" \ - {{ site.mesh_helm_install_name }} {{ site.mesh_helm_repo }} -``` +If you change these settings, but with values different from the runtime configuration, they will be ignored, and a warning will appear in the control plane logs (except for DNS-related settings). -This will have the same effect as using `--values values.yaml`, as described earlier. -{% endtip %} -{% endcapture %} - -{% capture modify-runtime-conf-env-var %} -You can also set individual configuration values using environment variables. For example, to exclude specific outbound IPs from the transparent proxy, update the `{{ kuma-control-plane }}` Deployment by setting the environment variable `KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS` with the desired IP addresses, separated by commas. For instance: `10.1.0.254,172.10.1.254`. - -{% danger %} -Manually editing Kubernetes manifests for {{ Kuma }} **is strongly discouraged** and should **only be done for testing in non-production environments**. Making manual changes can increase the risk of misconfiguration and may cause unexpected issues. For dynamic configuration updates without reinstalling {{ Kuma }}, use the `{{ kuma-control-plane-config }}` ConfigMap as described above. - -Setting environment variables during the initial installation, as shown below, is safe for any environment. While the ConfigMap is the preferred method, environment variables are also a reliable option for setup. +If `builtinDNS.enabled` or `builtinDNS.port` is updated using deprecated annotations while [Configuration in ConfigMap](#configuration-in-configmap-experimental) is disabled, the changes may still apply, potentially causing DNS redirection issues. This could prevent `kuma-dp` from starting the DNS server or listening on the correct port, leading to environment disruptions. {% enddanger %} -To apply environment variables to {{ Kuma }}'s control plane automatically, configure them during installation using the `{{ controlPlane }}.envVars` setting. For example: - - -{% cpinstall modify-runtime-config-env-var %} -controlPlane.envVars.KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS=10\.1\.0\.254\,172\.10\.1.254 -{% endcpinstall %} - -{% endcapture %} - -To modify the configuration, you have two main options: +#### Modifying control plane runtime configuration -1. **Store the desired settings in the `{{ kuma-control-plane-config }}` ConfigMap:** +For instructions on modifying the control plane configuration, see the [Modifying the Configuration]({{ docs }}/documentation/configuration/#modifying-the-configuration) section in the [Control Plane Configuration]({{ docs }}/documentation/configuration/) documentation. - {{ modify-runtime-conf-configmap | indent }} +#### Overriding list-based configuration settings -2. **Configure specific settings through environment variables:** +For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`, only the value from the highest-precedence method will be applied; values from other methods will not be combined. - {{ modify-runtime-conf-env-var | indent }} +For example, if `excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is used on a workload, the annotation will override the control plane setting, so only the ports in the annotation will be excluded. -### Overriding list-based configuration settings - -For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`, only the value from the highest-precedence method will be applied, and values from other methods will not be combined. - -For example, if `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is applied to a specific workload, the annotation will override the control plane setting. This means the transparent proxy will exclude only the ports specified in the annotation. - -See the [**Order of Precedence**](#order-of-precedence) section to understand how different methods affect the final configuration applied. +See the [**Order of Precedence**](#order-of-precedence) section for more details. -## Configuration in ConfigMap (experimental) -{:#configuration-in-configmap} +### Configuration in ConfigMap (experimental) {% warning %} @@ -250,7 +99,7 @@ If you set `{{ transparentProxy }}.configMap.config` to an empty value, it will {% endwarning %} -### ConfigMap auto-creation and configuration +#### ConfigMap auto-creation and configuration During installation, {{ Kuma }} will automatically create a ConfigMap in the `{{ kuma-system }}` namespace. The ConfigMap will be named based on the `{{ transparentProxy }}.configMap.name` setting, and its content will come from the YAML configuration defined in `{{ transparentProxy }}.configMap.config`, which holds the transparent proxy settings. @@ -270,7 +119,7 @@ For more information about the structure of this configuration, see the [Kuma Co {% endtip %} -### ConfigMap lookup strategy +#### ConfigMap lookup strategy {{ Kuma }} follows a specific order when searching for the ConfigMap: @@ -284,7 +133,7 @@ The ConfigMap in the `{{ kuma-system }}` namespace is required for proper operat {% endwarning %} -### Custom ConfigMap name +#### Custom ConfigMap name The name of the ConfigMap is defined by the `{{ transparentProxy }}.configMap.name` setting. By default, this name is set to `kuma-transparent-proxy-config`. @@ -303,12 +152,12 @@ kubectl annotate pods "traffic.kuma.io/transparent-proxy-configmap-na This allows flexibility, enabling different workloads to use distinct ConfigMap settings while maintaining a global default. -## Annotations +### Annotations Kubernetes annotations can be applied to individual workloads to modify the transparent proxy configuration. These annotations allow fine-tuning of specific behaviors for a single workload without affecting others. {% tip %} -Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. +Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. {% endtip %} Below you can find a list of annotations that can be used to configure specific transparent proxy settings. @@ -361,12 +210,7 @@ The following annotation indirectly adjusts the transparent proxy configuration - `kuma.io/application-probe-proxy-port` - This annotation defines the port (default: `9001`) to be excluded from incoming traffic redirection, similar to using the `traffic.kuma.io/exclude-inbound-ports` annotation or other configuration methods. - - For more information, refer to: - - - The [Kubernetes]({{ docs }}/policies/service-health-probes/#kubernetes) section in the [Service Health Probes]({{ docs }}/policies/service-health-probes/) documentation. - - The [Introduction to Application Probe Proxy and deprecation of Virtual Probes]({{ docs }}/production/upgrades-tuning/upgrade-notes/#introduction-to-application-probe-proxy-and-deprecation-of-virtual-probes) section in the [Upgrade Instructions]({{ docs }}/production/upgrades-tuning/upgrade-notes/). + This annotation defines the port (default: `9001`) to be excluded from incoming traffic redirection, similar to using the `traffic.kuma.io/exclude-inbound-ports` annotation or other configuration methods. For more information, refer to the [Kubernetes]({{ docs }}/policies/service-health-probes/#kubernetes) section in the [Service Health Probes]({{ docs }}/policies/service-health-probes/) documentation. The following annotations differ from others mentioned earlier as they are related to the transparent proxy, but do not directly or indirectly configure specific individual settings. @@ -380,7 +224,7 @@ The following annotations differ from others mentioned earlier as they are relat - `traffic.kuma.io/transparent-proxy-configmap-name` - This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [{{ configuration-in-configmap }}](#configuration-in-configmap) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. + This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. ### Automatically applied annotations @@ -406,7 +250,9 @@ The automatically applied annotations include: These annotations ensure that the proper configuration is automatically applied to each workload, aligning with the global and per-workload settings. -## Order of precedence + +### Order of Precedence + When using multiple configuration methods, it's important to understand the order in which they are applied to avoid conflicts and ensure the correct settings are used. @@ -414,6 +260,6 @@ When using multiple configuration methods, it's important to understand the orde 2. [Control Plane Runtime Configuration](#control-plane-runtime-configuration) -3. [{{ configuration-in-configmap }}](#configuration-in-configmap) +3. [Configuration in ConfigMap](#configuration-in-configmap-experimental) 4. [Annotations](#annotations) diff --git a/app/_src/networking/transparent-proxy/installing-on-universal.md b/app/_src/networking/transparent-proxy/universal.md similarity index 54% rename from app/_src/networking/transparent-proxy/installing-on-universal.md rename to app/_src/networking/transparent-proxy/universal.md index 977353869..d053ac432 100644 --- a/app/_src/networking/transparent-proxy/installing-on-universal.md +++ b/app/_src/networking/transparent-proxy/universal.md @@ -1,5 +1,5 @@ --- -title: Installing Transparent Proxy on Universal +title: Transparent Proxy on Universal content_type: how-to --- @@ -7,21 +7,39 @@ content_type: how-to {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} -This page provides instructions for setting up a transparent proxy in your service environment. A transparent proxy helps streamline service management and traffic routing within a mesh, directing all traffic through the data plane proxy without requiring changes to your application code. +{% assign ref = docs | append: "/reference/transparent-proxy-configuration/" %} +{% assign ref-schema = ref | append: "#schema" %} +{% assign ref-env = ref | append: "#environment-variables" %} +{% assign ref-cli = ref | append: "#cli-flags" %} +{% assign ref-default = ref | append: "#default-values" %} +{% assign ref-full = ref | append: "#full-reference" %} -Once completed, your service will run under a transparent proxy, allowing you to use {{ Kuma }}'s service management features, like traffic control, observability, and security. +Using the transparent proxy in Universal mode makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: -Before starting, review the prerequisites below and adjust settings to fit your environment, including IP addresses, custom ports, and DNS configurations. +- **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. -## Prerequisites +- **Simplified service connectivity**: Take advantage of [Kuma DNS]({{ docs }}/networking/dns/) to use `.mesh` domain names, like `https://service-1.mesh`, for easy service connections without needing `localhost` and ports in the `Dataplane` resource. -{%- capture control-plane-and-service-network-accessibility-warning %} -{% warning %} -For this instruction, the control plane **should not** be deployed in the same environment as the transparent proxy. This is because the transparent proxy redirects **all** traffic (unless specifically excluded) to `kuma-dp`, including traffic meant for the control plane. +- **Flexible service naming**: With [MeshServices]({{ docs }}/networking/meshservice/) and [HostnameGenerators]({{ docs }}/networking/hostnamegenerator/), you can: + + - Keep your existing DNS names when moving to the service mesh. + - Give a service multiple DNS names for easier access. + - Set up custom routes, like targeting specific StatefulSet Pods or service versions. + - Expose a service on multiple ports for different uses. + +- **Simpler security, tracing, and observability**: Transparent proxy makes managing these features easier, with no extra setup required. + +## Installation + +Here are the steps to set up a transparent proxy for your service. Once set up, your service will run with a transparent proxy, giving you access to {{ Kuma }}'s features like traffic control, observability, and security. + +Before you start, check the prerequisites below and adjust the settings for your environment, including IP addresses, custom ports, and DNS configurations. -While it is technically possible to manually exclude control plane traffic during setup, this is complex and easy to misconfigure, as it requires excluding **all** necessary ports and routes. +### Prerequisites -In real deployments, you can work around it by running the control plane and other components in separate network namespaces using systemd, which keeps control plane traffic separate from `kuma-dp` and the service. +{%- capture control-plane-and-service-network-accessibility-warning %} +{% warning %} +In a basic setup, the control plane **should not** be deployed in the same environment as the transparent proxy. This is because the transparent proxy redirects **all** traffic to `kuma-dp` (unless excluded), including traffic meant for the control plane. {% endwarning %} {%- endcapture %} @@ -39,14 +57,7 @@ For instructions on generating this token, refer to the [Data plane proxy token] {%- capture binary-availability-tip %} {% tip %} -To easily download all necessary binaries, you can use the following script, which automatically detects your operating system and fetches the required binaries: - -```sh -curl -L {{ site.links.web }}{% if page.edition %}/{{ page.edition }}{% endif %}/installer.sh | VERSION={{ page.version_data.version }} sh - -``` -{:.no-line-numbers} - -Omitting the `VERSION` variable will install the latest version. +To get the required binaries, see [Install Kuma]({{ docs }}/introduction/install-kuma/). {% endtip %} {% endcapture -%} @@ -66,7 +77,7 @@ Omitting the `VERSION` variable will install the latest version. {{ binary-availability-tip | indent }} -## Step 1: Create a dedicated user for kuma-dp +### Step 1: Create a dedicated user for kuma-dp For proper functionality, the service must run under a different user than the one designated for running `kuma-dp`. If both the service and `kuma-dp` are run by the same user, the transparent proxy will not work correctly, causing service traffic (inbound and outbound) to fail. To create a dedicated user for `kuma-dp`, use the following command: @@ -79,7 +90,7 @@ In some Linux distributions, the `useradd` command may not be available. In such {% endwarning %} -## Step 2: Prepare the Dataplane resource +### Step 2: Prepare the Dataplane resource In transparent proxy mode, configure your `Dataplane` resource without the `networking.outbound` section. Instead, use `networking.transparentProxying` for handling traffic redirection. Here’s an example: @@ -119,7 +130,7 @@ networking: redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} ``` -### Redirect ports +#### Redirect ports In this example, `{{ tproxy.defaults.redirect.inbound.port }}` and `{{ tproxy.defaults.redirect.outbound.port }}` are the default ports for inbound and outbound traffic redirection. You can change these ports in the transparent proxy configuration during installation (`redirect.inbound.port` and `redirect.outbound.port`). For more details, see the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). @@ -127,17 +138,17 @@ In this example, `{{ tproxy.defaults.redirect.inbound.port }}` and `{{ tproxy.de **Important:** If you use different ports, be sure to update all related configurations and steps to match the new values. {% endwarning %} -### Using variables in your configuration +#### Using variables in your configuration The placeholders `{% raw %}{{ name }}{% endraw %}`, `{% raw %}{{ address }}{% endraw %}`, and `{% raw %}{{ port }}{% endraw %}` are [Mustache templates](http://mustache.github.io/mustache.5.html), which will be dynamically filled using values passed via `--dataplane-var` CLI flags in a later step. In practice, if these values are static, you can simply hard-code them in your configuration. This feature is designed to allow more flexible and reusable resources, making it easier to dynamically adjust values when starting `kuma-dp`. -### More resources +#### More resources For additional information on setting up the `Dataplane` resource, refer to the [Data Plane on Universal]({{ docs }}/production/dp-config/dpp-on-universal/#data-plane-on-universal) documentation. -## Step 3: Start the service +### Step 3: Start the service The service can be started in various ways depending on your environment and requirements. To keep this instruction simple, we’ll use Python 3’s built-in HTTP server. This server will listen on port `8080`, with both [STDOUT](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) and [STDERR](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) redirected to a `service.log` file in the current directory, running in the background. @@ -151,7 +162,7 @@ To start the service: python3 -m http.server 8080 > service.log 2>&1 & ``` -## Step 4: Start the kuma-dp +### Step 4: Start the kuma-dp If you are using `systemd` to manage processes, you can refer to the [Systemd documentation]({{ docs }}/production/cp-deployment/systemd/) for an example of a `systemd` resource that can be customized to run `kuma-dp` in your environment. @@ -179,7 +190,7 @@ runuser -u {{ tproxy.defaults.kuma-dp.username }} -- \ This command runs `kuma-dp` under the `{{ tproxy.defaults.kuma-dp.username }}` user, connects it to the control plane, and configures it with the necessary settings for the example server. Adjust the paths and values as needed for your specific setup. -## Step 5: Install the transparent proxy +### Step 5: Install the transparent proxy Before proceeding with this step, please keep the following in mind: @@ -257,3 +268,208 @@ This will result in the following: {% endtip %} {% endcapture %} {{ resolv-conf-tip | indent }} + +## Upgrading + +The core `iptables` rules applied by {{ Kuma }}'s transparent proxy rarely change, but occasionally new features may require updates. To upgrade the transparent proxy on Universal environments, follow these steps: + +### Step 1: Cleanup existing iptables rules (conditional) + +{% warning %} +If you're upgrading from {{ Kuma }} version 2.9 or later, and you have **not** manually disabled the automatic addition of comments by setting `comments.disabled` to `true` in the transparent proxy configuration, **this step is unnecessary**. + +Starting with {{ Kuma }} 2.9, all `iptables` rules are tagged with comments, allowing {{ Kuma }} to track rule ownership. This enables `kumactl` to automatically clean up any existing `iptables` rules or custom chains created by previous versions of the transparent proxy. This process runs automatically at the start of the installation, eliminating the need for any manual cleanup beforehand. +{% endwarning %} + +To manually remove existing `iptables` rules, you can either restart the host (if the rules were not persisted using system start-up scripts or `firewalld`), or run the following commands: + +{% danger %} +These commands will remove **all** `iptables` rules and **all** custom chains in the specified tables, including those created by {{ Kuma }} as well as any other applications or services. +{% enddanger %} + +```sh +iptables --table nat --flush # Flush all rules in the nat table (IPv4) +ip6tables --table nat --flush # Flush all rules in the nat table (IPv6) +iptables --table nat --delete-chain # Delete all custom chains in the nat table (IPv4) +ip6tables --table nat --delete-chain # Delete all custom chains in the nat table (IPv6) + +# The raw table contains rules for DNS traffic redirection +iptables --table raw --flush # Flush all rules in the raw table (IPv4) +ip6tables --table raw --flush # Flush all rules in the raw table (IPv6) + +# The mangle table contains rules to drop invalid packets +iptables --table mangle --flush # Flush all rules in the mangle table (IPv4) +ip6tables --table mangle --flush # Flush all rules in the mangle table (IPv6) +``` + +### Step 2: Install new transparent proxy + +After clearing the `iptables` rules (if necessary), reinstall the transparent proxy by running: + +```sh +kumactl install transparent-proxy [...] +``` + +This command will install the new version of the transparent proxy with the specified configuration. Adjust the flags as needed to suit your environment. + +## Configuration + +The default configuration works well for most scenarios, but there are cases where adjustments are needed. + +{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Transparent Proxy Configuration Reference]({{ ref }}). + +In Universal mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. + +{% warning %} +It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) section to see what the final configuration will look like based on the priority of each setting. +{% endwarning %} + + +### YAML / JSON + + +You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. + +{% tip %} +For the configuration schema in YAML format, refer to the [Schema]({{ ref-schema }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + +{% tip %} +For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs. +{% endtip %} + +Below are examples of using these flags in different ways: + +1. **Providing configuration via the `--config-file` flag** + + Assume you have a `config.yaml` file with the following content: + + ```yaml + kumaDPUser: dataplane + verbose: true + ``` + + You can install the transparent proxy using: + + ```sh + kumactl install transparent-proxy --config-file config.yaml + ``` + +2. **Passing configuration directly via the `--config` flag** + + To pass the configuration content directly: + + ```sh + kumactl install transparent-proxy --config "kumaDPUser: dataplane\nverbose: true" + ``` + + Alternatively: + + ```sh + kumactl install transparent-proxy --config "{ kumaDPUser: dataplane, verbose: true }" + ``` + + Both formats are valid YAML inputs. + +3. **Passing configuration via [STDIN](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin))** + + If you need to pass the configuration via STDIN, set `--config-file` to `-` as shown below: + + ```sh + echo " + kumaDPUser: dataplane + verbose: true + " | kumactl install transparent-proxy --config-file - + ``` + + +### Environment Variables + + +You can customize configuration settings by using environment variables. For example: + +```sh +KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy +``` + +{% tip %} +To see all available environment variables, visit the [Environment Variables]({{ ref-env }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + + +### CLI Flags + + +Most configuration values can also be specified directly through CLI flags. For example: + +```sh +kumactl install transparent-proxy --kuma-dp-user dataplane --verbose +``` + +{% warning %} +The following settings cannot be modified directly via CLI flags (corresponding flags are not available): + +- `redirect.dns.resolvConfigPath` +- `redirect.inbound.includePorts` +- `redirect.inbound.excludePortsForUIDs` +- `redirect.outbound.enabled` +- `redirect.outbound.includePorts` +- `ebpf.instanceIPEnvVarName` +- `log.level` +- `cniMode` + {% endwarning %} + +{% tip %} +To see all available CLI flags, visit the [CLI Flags]({{ ref-cli }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +{% endtip %} + + +### Order of Precedence + + +1. **Default Values** +2. **Values from** `--config` / `--config-file` **flags** +3. **Environment Variables** +4. **CLI Flags** + +To understand how the order of precedence works, consider this scenario: + +1. You have a `config.yaml` file with the following content: + + ```yaml + redirect: + dns: + port: 10001 + ``` + +2. You install the transparent proxy using this command: + + ```sh + KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_PORT="10002" \ + kumactl install transparent-proxy \ + --config-file config.yaml \ + --redirect-dns-port 10003 + ``` + +3. In this situation, the possible values for `redirect.dns.port` are: + + - **`{{ tproxy.defaults.redirect.dns.port }}`** (Default Value) + - **`10001`** (From Config File) + - **`10002`** (From Environment Variable) + - **`10003`** (From CLI Flag) + +4. Since CLI flags have the highest precedence, the final value for `redirect.dns.port` will be **`10003`**. + +## firewalld support + +The changes made by running `kumactl install transparent-proxy` **will not persist** after a reboot. To ensure persistence, you can either add this command to your system's start-up scripts or leverage `firewalld` for managing `iptables`. + +If you prefer using `firewalld`, you can include the `--store-firewalld` flag when installing the transparent proxy. This will store the `iptables` rules in `/etc/firewalld/direct.xml`, ensuring they persist across system reboots. Here's an example: + +```sh +kumactl install transparent-proxy --redirect-dns --store-firewalld +``` + +{% warning %} +**Important:** Currently, there is no uninstall command for this feature. If needed, you will have to manually clean up the `firewalld` configuration. +{% endwarning %} \ No newline at end of file diff --git a/app/_src/networking/transparent-proxy/upgrading-on-universal.md b/app/_src/networking/transparent-proxy/upgrading-on-universal.md deleted file mode 100644 index b76725488..000000000 --- a/app/_src/networking/transparent-proxy/upgrading-on-universal.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Upgrading Transparent Proxy on Universal ---- - -{% assign docs = "/docs/" | append: page.version %} -{% assign Kuma = site.mesh_product_name %} - -{% tip %} -In **Kubernetes** mode, transparent proxy automatically updates with the {{ Kuma }} version upgrade. No additional steps are required for workloads, as the transparent proxy aligns with the {{ Kuma }} version. The following guide applies only to **Universal** mode. -{% endtip %} - -The core `iptables` rules applied by {{ Kuma }}'s transparent proxy rarely change, but occasionally new features may require updates. To upgrade the transparent proxy on Universal environments, follow these steps: - -### Step 1: Cleanup existing iptables rules (conditional) - -{% warning %} -If you're upgrading from {{ Kuma }} version 2.9 or later, and you have **not** manually disabled the automatic addition of comments by setting `comments.disabled` to `true` in the transparent proxy configuration, **this step is unnecessary**. - -Starting with {{ Kuma }} 2.9, all `iptables` rules are tagged with comments, allowing {{ Kuma }} to track rule ownership. This enables `kumactl` to automatically clean up any existing `iptables` rules or custom chains created by previous versions of the transparent proxy. This process runs automatically at the start of the installation, eliminating the need for any manual cleanup beforehand. -{% endwarning %} - -To manually remove existing `iptables` rules, you can either restart the host (if the rules were not persisted using system start-up scripts or `firewalld`), or run the following commands: - -{% danger %} -These commands will remove **all** `iptables` rules and **all** custom chains in the specified tables, including those created by {{ Kuma }} as well as any other applications or services. -{% enddanger %} - -```sh -iptables --table nat --flush # Flush all rules in the nat table (IPv4) -ip6tables --table nat --flush # Flush all rules in the nat table (IPv6) -iptables --table nat --delete-chain # Delete all custom chains in the nat table (IPv4) -ip6tables --table nat --delete-chain # Delete all custom chains in the nat table (IPv6) - -# The raw table contains rules for DNS traffic redirection -iptables --table raw --flush # Flush all rules in the raw table (IPv4) -ip6tables --table raw --flush # Flush all rules in the raw table (IPv6) - -# The mangle table contains rules to drop invalid packets -iptables --table mangle --flush # Flush all rules in the mangle table (IPv4) -ip6tables --table mangle --flush # Flush all rules in the mangle table (IPv6) -``` - -### Step 2: Install new transparent proxy - -After clearing the `iptables` rules (if necessary), reinstall the transparent proxy by running: - -```sh -kumactl install transparent-proxy [...] -``` - -This command will install the new version of the transparent proxy with the specified configuration. Adjust the flags as needed to suit your environment. - -{% tip %} -For a comprehensive documentation of installing the transparent proxy in Universal mode, including details on preparing the environment, understanding any restrictions, and configuring `Dataplane` objects to work with the transparent proxy, refer to the [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/installing-on-universal/) page. -{% endtip %} diff --git a/app/_src/reference/transparent-proxy-configuration.md b/app/_src/reference/transparent-proxy-configuration.md index 77fcfbd11..1bf4fa73b 100644 --- a/app/_src/reference/transparent-proxy-configuration.md +++ b/app/_src/reference/transparent-proxy-configuration.md @@ -270,6 +270,38 @@ log: wait: 5 ``` +### Control plane runtime configuration + +Below is a subset of the [control plane configuration]({{ docs }}/documentation/configuration/) focused on transparent proxy settings, with default values and corresponding environment variables for each field. + +```yaml +runtime: + kubernetes: + injector: + cniEnabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_CNI_ENABLED + applicationProbeProxyPort: 9001 # KUMA_RUNTIME_KUBERNETES_APPLICATION_PROBE_PROXY_PORT + sidecarContainer: + uid: 5678 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_UID + ipFamilyMode: dualstack # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_IP_FAMILY_MODE + redirectPortInbound: 15006 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_INBOUND + redirectPortOutbound: 15001 # KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_REDIRECT_PORT_OUTBOUND + sidecarTraffic: + excludeInboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_PORTS + excludeOutboundPorts: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_PORTS + excludeInboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_INBOUND_IPS + excludeOutboundIPs: [] # KUMA_RUNTIME_KUBERNETES_SIDECAR_TRAFFIC_EXCLUDE_OUTBOUND_IPS + builtinDNS: + enabled: true # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_ENABLED + port: 15053 # KUMA_RUNTIME_KUBERNETES_INJECTOR_BUILTIN_DNS_PORT + ebpf: + enabled: false # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_ENABLED + instanceIPEnvVarName: INSTANCE_IP # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_INSTANCE_IP_ENV_VAR_NAME + bpffsPath: /sys/fs/bpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_BPFFS_PATH + cgroupPath: /sys/fs/cgroup # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_CGROUP_PATH + tcAttachIface: "" # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_TC_ATTACH_IFACE + programsSourcePath: /tmp/kuma-ebpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_PROGRAMS_SOURCE_PATH +``` + ## Full reference - **`kumaDPUser`** From e2390c92774d39a9c35fd9becdb499b8b8f7fd37 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 15:17:54 +0100 Subject: [PATCH 18/40] add sublinks to tproxy config reference Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_2.9.x.yml | 13 +++++++++++++ app/_data/docs_nav_kuma_dev.yml | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index 2680adaff..dc8177173 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -552,6 +552,19 @@ items: url: /reference/proxy-template/ - text: Transparent Proxy Configuration url: /reference/transparent-proxy-configuration/ + items: + - text: Schema + url: /reference/transparent-proxy-configuration/#schema + - text: Environment Variables + url: /reference/transparent-proxy-configuration/#environment-variables + - text: CLI Flags + url: /reference/transparent-proxy-configuration/#cli-flags + - text: Default Values + url: /reference/transparent-proxy-configuration/#default-values + - text: Control Plane Runtime Configuration + url: /reference/transparent-proxy-configuration/#control-plane-runtime-configuration + - text: Full Reference + url: /reference/transparent-proxy-configuration/#full-reference - title: Community group: true items: diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index fc9fe5c7b..d4e71f88d 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -552,6 +552,19 @@ items: url: /reference/proxy-template/ - text: Transparent Proxy Configuration url: /reference/transparent-proxy-configuration/ + items: + - text: Schema + url: /reference/transparent-proxy-configuration/#schema + - text: Environment Variables + url: /reference/transparent-proxy-configuration/#environment-variables + - text: CLI Flags + url: /reference/transparent-proxy-configuration/#cli-flags + - text: Default Values + url: /reference/transparent-proxy-configuration/#default-values + - text: Control Plane Runtime Configuration + url: /reference/transparent-proxy-configuration/#control-plane-runtime-configuration + - text: Full Reference + url: /reference/transparent-proxy-configuration/#full-reference - title: Community group: true items: From 2ad4a327d8d9c9f6d77d495f4b08aca80f4ec235 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 15:20:21 +0100 Subject: [PATCH 19/40] fix broken links Signed-off-by: Bart Smykla --- .../excluding-traffic-from-transparent-proxy-redirection.md | 2 +- app/_src/networking/dns.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md index cd2b6a6a7..1c95a6cb2 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -21,7 +21,7 @@ Use this guide to control which traffic the transparent proxy intercepts and whi - [Transparent Proxy Configuration on Universal]({{ docs }}/networking/transparent-proxy/universal/#configuration) - [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) -- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/kubernetes/#annotations), since the [Configuration in ConfigMap]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration-in-configmap) option is still experimental. Once it’s stable, it will become the suggested method. +- Right now, the recommended way to adjust transparent proxy settings (and the one mostly shown in this guide) is with [Kubernetes Annotations]({{ docs }}/networking/transparent-proxy/kubernetes/#annotations), since the [Configuration in ConfigMap]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration-in-configmap-experimental) option is still experimental. Once it’s stable, it will become the suggested method. ## Terminology overview diff --git a/app/_src/networking/dns.md b/app/_src/networking/dns.md index 4f4623fef..85e508962 100644 --- a/app/_src/networking/dns.md +++ b/app/_src/networking/dns.md @@ -53,7 +53,7 @@ If you use [MeshService](/docs/{{ page.version }}/networking/meshservice), [Mesh {% endtab %} {% tab installation Universal %} -Follow the instruction in {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}{% if_version gte:2.9.x %}[Installing Transparent Proxy on Universal](/docs/{{ page.version }}/networking/transparent-proxy/installing-on-universal/){% endif_version %}. +Follow the instruction in {% if_version lte:2.1.x %}[transparent proxying](/docs/{{ page.version }}/networking/transparent-proxying){% endif_version %}{% if_version gte:2.2.x lte:2.8.x %}[transparent proxying](/docs/{{ page.version }}/production/dp-config/transparent-proxying/){% endif_version %}{% if_version gte:2.9.x %}[Installing Transparent Proxy on Universal](/docs/{{ page.version }}/networking/transparent-proxy/universal/#installation){% endif_version %}. {% endtab %} {% endtabs %} From ae2c4c8026323ed36e5545934cc8b8fe5d535a2f Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 5 Nov 2024 15:27:19 +0100 Subject: [PATCH 20/40] fix another broken link Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_dev.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index d4e71f88d..dc8177173 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -289,7 +289,7 @@ items: - text: Control Plane Runtime Configuration url: /networking/transparent-proxy/kubernetes/#control-plane-runtime-configuration - text: Configuration in ConfigMap - url: /networking/transparent-proxy/kubernetes/#configuration-in-configmap + url: /networking/transparent-proxy/kubernetes/#configuration-in-configmap-experimental - text: Annotations url: /networking/transparent-proxy/kubernetes/#annotations - text: Universal From 08729d1277d1328ec1220db0b273edcead6f6e4c Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Wed, 6 Nov 2024 06:57:03 +0100 Subject: [PATCH 21/40] chore: small improvements Signed-off-by: Bart Smykla --- ...-traffic-from-transparent-proxy-redirection.md | 3 +-- .../networking/transparent-proxy/introduction.md | 2 +- .../transparent-proxy/reachable-backends.md | 1 + .../transparent-proxy/reachable-services.md | 1 + .../transparent-proxy/technical-overview.md | 1 + .../networking/transparent-proxy/universal.md | 15 ++++----------- .../reference/transparent-proxy-configuration.md | 1 + 7 files changed, 10 insertions(+), 14 deletions(-) diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md index 1c95a6cb2..4285c557b 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -1,5 +1,6 @@ --- title: Excluding Traffic from Transparent Proxy +content_type: tutorial --- {% assign docs = "/docs/" | append: page.version %} @@ -36,9 +37,7 @@ Use this guide to control which traffic the transparent proxy intercepts and whi 1. **Understand transparent proxy basics**: You should already be familiar with what a transparent proxy is, how to install it, and how to adjust its settings. This guide won’t cover those basics. The following resources can help: - For options to customize transparent proxy settings, check the resources listed in the [Key Information](#key-information) section. - - For an in-depth look at how the transparent proxy works in {{ Kuma }} and its mechanisms, see the [Technical Overview]({{ docs }}/networking/transparent-proxy/technical-overview/) page from its documentation. - - To install the transparent proxy on Universal, refer to [Installing Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/#installation). - For upgrade steps, see [Upgrading Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/#upgrading). diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index f2593bb4b..4982037c5 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -1,6 +1,6 @@ --- title: Transparent Proxy -content_type: how-to +content_type: explanation --- {% assign docs = "/docs/" | append: page.version %} diff --git a/app/_src/networking/transparent-proxy/reachable-backends.md b/app/_src/networking/transparent-proxy/reachable-backends.md index 999a6ff33..cd021cd05 100644 --- a/app/_src/networking/transparent-proxy/reachable-backends.md +++ b/app/_src/networking/transparent-proxy/reachable-backends.md @@ -1,5 +1,6 @@ --- title: Reachable Backends +content_type: how-to --- {% assign docs = "/docs/" | append: page.version %} diff --git a/app/_src/networking/transparent-proxy/reachable-services.md b/app/_src/networking/transparent-proxy/reachable-services.md index fff3275f9..c763c32d5 100644 --- a/app/_src/networking/transparent-proxy/reachable-services.md +++ b/app/_src/networking/transparent-proxy/reachable-services.md @@ -1,5 +1,6 @@ --- title: Reachable Services +content_type: how-to --- {% assign Kuma = site.mesh_product_name %} diff --git a/app/_src/networking/transparent-proxy/technical-overview.md b/app/_src/networking/transparent-proxy/technical-overview.md index 701318f9d..f3f5235dc 100755 --- a/app/_src/networking/transparent-proxy/technical-overview.md +++ b/app/_src/networking/transparent-proxy/technical-overview.md @@ -1,5 +1,6 @@ --- title: Technical Overview +content_type: explanation --- {% assign docs = "/docs/" | append: page.version %} diff --git a/app/_src/networking/transparent-proxy/universal.md b/app/_src/networking/transparent-proxy/universal.md index d053ac432..e6037001f 100644 --- a/app/_src/networking/transparent-proxy/universal.md +++ b/app/_src/networking/transparent-proxy/universal.md @@ -7,13 +7,6 @@ content_type: how-to {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} -{% assign ref = docs | append: "/reference/transparent-proxy-configuration/" %} -{% assign ref-schema = ref | append: "#schema" %} -{% assign ref-env = ref | append: "#environment-variables" %} -{% assign ref-cli = ref | append: "#cli-flags" %} -{% assign ref-default = ref | append: "#default-values" %} -{% assign ref-full = ref | append: "#full-reference" %} - Using the transparent proxy in Universal mode makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: - **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. @@ -316,7 +309,7 @@ This command will install the new version of the transparent proxy with the spec The default configuration works well for most scenarios, but there are cases where adjustments are needed. -{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Transparent Proxy Configuration Reference]({{ ref }}). +{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). In Universal mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. @@ -331,7 +324,7 @@ It’s best to stick to one method whenever possible. Using more than one can ma You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. {% tip %} -For the configuration schema in YAML format, refer to the [Schema]({{ ref-schema }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +For the configuration schema in YAML format, refer to the [Schema]({{ docs }}/reference/transparent-proxy-configuration/#schema) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} {% tip %} @@ -393,7 +386,7 @@ KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy ``` {% tip %} -To see all available environment variables, visit the [Environment Variables]({{ ref-env }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +To see all available environment variables, visit the [Environment Variables]({{ docs }}/reference/transparent-proxy-configuration/#environment-variables) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} @@ -420,7 +413,7 @@ The following settings cannot be modified directly via CLI flags (corresponding {% endwarning %} {% tip %} -To see all available CLI flags, visit the [CLI Flags]({{ ref-cli }}) section in the [Transparent Proxy Configuration Reference]({{ ref }}). +To see all available CLI flags, visit the [CLI Flags]({{ docs }}/reference/transparent-proxy-configuration/#cli-flags) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} diff --git a/app/_src/reference/transparent-proxy-configuration.md b/app/_src/reference/transparent-proxy-configuration.md index 1bf4fa73b..fe92b6d40 100644 --- a/app/_src/reference/transparent-proxy-configuration.md +++ b/app/_src/reference/transparent-proxy-configuration.md @@ -1,5 +1,6 @@ --- title: Transparent Proxy Configuration +content_type: reference --- {% assign docs = "/docs/" | append: page.version %} From 441b3a63e6cb8c2fe268f5d80f18745930ecc250 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 7 Nov 2024 08:17:30 +0100 Subject: [PATCH 22/40] address review remarks Signed-off-by: Bart Smykla --- .../config/vocabularies/Base/accept.txt | 1 + .vale.ini | 5 +- app/_data/docs_nav_kuma_2.9.x.yml | 2 + app/_data/docs_nav_kuma_dev.yml | 2 + .../transparent-proxy/kubernetes.md | 136 ++++-------------- .../networking/transparent-proxy/universal.md | 2 +- .../transparent-proxy-configuration.md | 68 +++++++++ 7 files changed, 108 insertions(+), 108 deletions(-) diff --git a/.github/styles/config/vocabularies/Base/accept.txt b/.github/styles/config/vocabularies/Base/accept.txt index a4d512d75..9c000539a 100644 --- a/.github/styles/config/vocabularies/Base/accept.txt +++ b/.github/styles/config/vocabularies/Base/accept.txt @@ -183,3 +183,4 @@ netfilter UIDs? use_original_dst orin +ConfigMap diff --git a/.vale.ini b/.vale.ini index df65f06aa..3deb25b12 100644 --- a/.vale.ini +++ b/.vale.ini @@ -5,12 +5,13 @@ Vocab = Base Packages = Google SkippedScopes = code -IgnoredClasses=code +IgnoredClasses = code [*.md] BasedOnStyles = Vale, Google BlockIgnores = (\((http.*://|\.\/|\/).*?\)), \ -{\:.*?} +{\:.*?}, \ +(?s) *({% ?cpinstall.*?%}.*?{% ?endcpinstall ?%}) TokenIgnores = {%.*?%}, \ {{.*?}}, \ (?:)(/[(A-Za-z0-9)(\055/)(_)]*/), \ diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index dc8177173..f0d6b6756 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -563,6 +563,8 @@ items: url: /reference/transparent-proxy-configuration/#default-values - text: Control Plane Runtime Configuration url: /reference/transparent-proxy-configuration/#control-plane-runtime-configuration + - text: Annotations + url: /reference/transparent-proxy-configuration/#annotations - text: Full Reference url: /reference/transparent-proxy-configuration/#full-reference - title: Community diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index dc8177173..f0d6b6756 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -563,6 +563,8 @@ items: url: /reference/transparent-proxy-configuration/#default-values - text: Control Plane Runtime Configuration url: /reference/transparent-proxy-configuration/#control-plane-runtime-configuration + - text: Annotations + url: /reference/transparent-proxy-configuration/#annotations - text: Full Reference url: /reference/transparent-proxy-configuration/#full-reference - title: Community diff --git a/app/_src/networking/transparent-proxy/kubernetes.md b/app/_src/networking/transparent-proxy/kubernetes.md index 9fe2a990e..ae9803917 100644 --- a/app/_src/networking/transparent-proxy/kubernetes.md +++ b/app/_src/networking/transparent-proxy/kubernetes.md @@ -21,24 +21,22 @@ In this mode, {{ Kuma }} requires the transparent proxy to be enabled, so it **c The default configuration works well for most scenarios, but there are cases where adjustments are needed. -In Kubernetes mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. +In Kubernetes mode, {{ Kuma }} offers three methods to adjust the configuration. Each can be used on its own or combined with others if needed. {% warning %} -It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence** section](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. +It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of precedence** section](#order-of-precedence) to see what the final configuration will look like based on the priority of each setting. {% endwarning %} - -### Control Plane Runtime Configuration - +### Control plane runtime configuration The control plane runtime configuration is a section of {{ Kuma }}'s configuration that contains important settings for how the control plane operates, including options for the transparent proxy and other key components. Some transparent proxy settings can be adjusted here, and **for certain settings, this is the only place they can be modified**. -Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). In the future, once the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature is fully supported, we’ll recommend using ConfigMaps for these settings. However, a few restricted settings that are rarely customized will still need to be in the control plane’s runtime configuration. +Currently, it’s best to use the control plane runtime configuration as the main place to store transparent proxy settings that apply to all [workloads](https://kubernetes.io/docs/concepts/workloads/). {% tip %} -For more details, see the [Control Plane Configuration Reference]({{ docs }}/reference/kuma-cp/) under `runtime.kubernetes`. You can also find transparent proxy-specific settings in the [Control Plane Runtime Configuration section]({{ docs }}/reference/transparent-proxy-configuration/#control-plane-runtime-configuration) of the Transparent Proxy Configuration reference. +For more details, see the [control plane configuration reference]({{ docs }}/reference/kuma-cp/) under `runtime.kubernetes`. You can also find transparent proxy-specific settings in the [control plane runtime configuration section]({{ docs }}/reference/transparent-proxy-configuration/#control-plane-runtime-configuration) of the Transparent Proxy Configuration reference. {% endtip %} #### Settings restricted to control plane runtime configuration @@ -62,7 +60,7 @@ If `builtinDNS.enabled` or `builtinDNS.port` is updated using deprecated annotat #### Modifying control plane runtime configuration -For instructions on modifying the control plane configuration, see the [Modifying the Configuration]({{ docs }}/documentation/configuration/#modifying-the-configuration) section in the [Control Plane Configuration]({{ docs }}/documentation/configuration/) documentation. +For instructions on modifying the control plane configuration, see the [Modifying the configuration section]({{ docs }}/documentation/configuration/#modifying-the-configuration) section in the control plane configuration documentation. #### Overriding list-based configuration settings @@ -70,17 +68,15 @@ For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.exclude For example, if `excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is used on a workload, the annotation will override the control plane setting, so only the ports in the annotation will be excluded. -See the [**Order of Precedence**](#order-of-precedence) section for more details. +See the [**Order of precedence** section](#order-of-precedence) for more details. - ### Configuration in ConfigMap (experimental) - {% warning %} Because this feature impacts multiple underlying components, it is considered experimental. Use it with caution. {% if site.mesh_product_name == "Kuma" %} If you encounter any unexpected behavior or issues, please [**contact us**](/community) and [**submit an issue on GitHub**](https://github.com/kumahq/kuma/issues/new/choose). Your feedback is essential in helping us improve this feature. {% endif %} {% endwarning %} -Until {{ Kuma }} 2.9, transparent proxy settings could only be modified through the [Control Plane Runtime Configuration](#control-plane-runtime-configuration) and [Annotations](#annotations), which had several limitations: +Until {{ Kuma }} 2.9, transparent proxy settings could only be modified through the [control plane runtime configuration](#control-plane-runtime-configuration) and [annotations](#annotations), which had several limitations: - Not all settings were available through both methods; some could only be adjusted with annotations, while others were limited to the runtime configuration. - Control plane runtime settings were applied globally to all workloads with injected data planes, making it hard to customize settings for specific groups of workloads. @@ -98,9 +94,7 @@ To enable this feature, set `{{ transparentProxy }}.configMap.enabled` during in If you set `{{ transparentProxy }}.configMap.config` to an empty value, it will override `{{ transparentProxy }}.configMap.enabled` and disable the feature, even if `{{ transparentProxy }}.configMap.enabled` is set to `true`. {% endwarning %} - #### ConfigMap auto-creation and configuration - During installation, {{ Kuma }} will automatically create a ConfigMap in the `{{ kuma-system }}` namespace. The ConfigMap will be named based on the `{{ transparentProxy }}.configMap.name` setting, and its content will come from the YAML configuration defined in `{{ transparentProxy }}.configMap.config`, which holds the transparent proxy settings. @@ -112,29 +106,11 @@ Here is an example of how to modify parts of this configuration during installat {{ transparentProxy }}.configMap.config.redirect.verbose=false {% endcpinstall %} -You can apply the same method of providing these values as explained in the **Store the desired settings in the `{{ kuma-control-plane-config }}` ConfigMap** option in the [**Modifying Control Plane Runtime Configuration**](#modifying-control-plane-runtime-configuration) section. - {% tip %} -For more information about the structure of this configuration, see the [Kuma Control Plane Helm Values]({{ docs }}/reference/kuma-cp/#helm-valuesyaml) documentation, particularly under the `{{ transparentProxy }}.configMap.config` path. You can also refer to the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/) for additional details. +{{ Kuma }} uses a single configuration structure for transparent proxy settings across all components. For the full configuration schema, see the [Helm values.yaml reference]({{ docs }}/reference/kuma-cp/#helm-valuesyaml), particularly under the `{{ transparentProxy }}.configMap.config` path. More details on each setting are available in the [Transparent Proxy Configuration reference]({{ docs }}/reference/transparent-proxy-configuration/#full-reference). {% endtip %} - -#### ConfigMap lookup strategy - - -{{ Kuma }} follows a specific order when searching for the ConfigMap: - -- If the workload is annotated with `traffic.kuma.io/transparent-proxy-configmap-name`, {{ Kuma }} first looks for the resource with the specified name in the workload’s namespace. If not found, it will then check the `{{ kuma-system }}` namespace for the same ConfigMap. - -- If the workload is not annotated, or the ConfigMap specified in the annotation is not found, {{ Kuma }} will search for the resource named in the `{{ transparentProxy }}.configMap.name` setting. It first looks in the workload's namespace, and if not found, it checks the `{{ kuma-system }}` namespace. - -{% warning %} -The ConfigMap in the `{{ kuma-system }}` namespace is required for proper operation, so it must be present even if custom ones are used in all individual workload namespaces. -{% endwarning %} - - #### Custom ConfigMap name - The name of the ConfigMap is defined by the `{{ transparentProxy }}.configMap.name` setting. By default, this name is set to `kuma-transparent-proxy-config`. @@ -146,89 +122,41 @@ To apply a custom name for all workloads, you can modify the `{{ transparentProx To use a different resource for specific workloads, apply the `traffic.kuma.io/transparent-proxy-configmap-name` annotation to those workloads. For example: -```sh -kubectl annotate pods "traffic.kuma.io/transparent-proxy-configmap-name=custom-name" +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: demo-app + annotations: + traffic.kuma.io/transparent-proxy-configmap-name: custom-name +... ``` -This allows flexibility, enabling different workloads to use distinct ConfigMap settings while maintaining a global default. - -### Annotations - -Kubernetes annotations can be applied to individual workloads to modify the transparent proxy configuration. These annotations allow fine-tuning of specific behaviors for a single workload without affecting others. - -{% tip %} -Before {{ Kuma }} 2.9, annotations were the only way to modify the transparent proxy configuration on a per-workload basis. In {{ Kuma }} 2.9, the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature was introduced, offering a more efficient way to configure groups of workloads. When this feature is no longer experimental, it will become the recommended approach for managing transparent proxy settings across multiple workloads. Annotations will still be useful for fine-tuning specific configurations when you need an individual workload to behave differently from the others. -{% endtip %} - -Below you can find a list of annotations that can be used to configure specific transparent proxy settings. - -- `traffic.kuma.io/exclude-inbound-ips` - -- `traffic.kuma.io/exclude-inbound-ports` - -- `traffic.kuma.io/exclude-outbound-ips` - -- `traffic.kuma.io/exclude-outbound-ports` - -- `traffic.kuma.io/exclude-outbound-ports-for-uids` - -- `traffic.kuma.io/drop-invalid-packets` - -- `traffic.kuma.io/iptables-logs` - -- `kuma.io/transparent-proxying-ebpf` - -- `kuma.io/transparent-proxying-ebpf-bpf-fs-path` - -- `kuma.io/transparent-proxying-ebpf-cgroup-path` - -- `kuma.io/transparent-proxying-ebpf-tc-attach-iface` - -- `kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name` - -- `kuma.io/transparent-proxying-ebpf-programs-source-path` +#### ConfigMap lookup order -- `kuma.io/transparent-proxying-ip-family-mode` +{{ Kuma }} looks for the ConfigMap as follows: -The following annotations also affect the configuration, but their values are automatically managed by {{ Kuma }} and cannot be manually adjusted. Values of these annotations will always match those specified in the [Control Plane Runtime Configuration](#control-plane-runtime-configuration). For more details, refer to [Settings restricted to control plane runtime configuration](#settings-restricted-to-control-plane-runtime-configuration). +1. **If annotation is set**: Search the workload's namespace for the ConfigMap specified by `traffic.kuma.io/transparent-proxy-configmap-name`. -- `kuma.io/sidecar-uid` +2. **If annotation is set but ConfigMap not found**: Search the `{{ kuma-system }}` namespace for the same ConfigMap. -- `kuma.io/transparent-proxying-inbound-port` +3. **If no annotation or previous steps failed**: Look for the ConfigMap with the default name in the workload's namespace. -- `kuma.io/transparent-proxying-outbound-port` +4. **If still not found**: Search the `{{ kuma-system }}` namespace for the ConfigMap with the default name. {% warning %} -The following two annotations are deprecated and will be removed in future releases. They are provided here for reference only, and we **strongly advise against using them**. - -- `kuma.io/builtin-dns` - -- `kuma.io/builtin-dns-port` +The ConfigMap in the `{{ kuma-system }}` namespace is required for proper operation, so it must be present even if custom ones are used in all individual workload namespaces. {% endwarning %} -The following annotation indirectly adjusts the transparent proxy configuration by configuring other components, resulting in changes to the transparent proxy behavior. While its value is automatically set by {{ Kuma }}, you can override it by manually providing a value. - -- `kuma.io/application-probe-proxy-port` - - This annotation defines the port (default: `9001`) to be excluded from incoming traffic redirection, similar to using the `traffic.kuma.io/exclude-inbound-ports` annotation or other configuration methods. For more information, refer to the [Kubernetes]({{ docs }}/policies/service-health-probes/#kubernetes) section in the [Service Health Probes]({{ docs }}/policies/service-health-probes/) documentation. - -The following annotations differ from others mentioned earlier as they are related to the transparent proxy, but do not directly or indirectly configure specific individual settings. - -- `kuma.io/transparent-proxying` - - This annotation is automatically applied to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers). In Kubernetes environments, the transparent proxy is mandatory meaning you cannot disable it. Any attempt to explicitly disable it using this annotation will trigger a warning and have no effect. Therefore, the value of this annotation will always be set to `true`. - -- `traffic.kuma.io/transparent-proxy-config` - - This annotation is automatically applied in environments using [Kuma CNI]({{ docs }}/production/dp-config/cni/#configure-the-kuma-cni) instead of init containers. It contains the final configuration for installing the transparent proxy. Manually modifying or setting this annotation has no effect, regardless of whether Kuma CNI is used. Its primary purpose is to efficiently pass the transparent proxy configuration between Kubernetes workloads and the Kuma CNI, which handles the actual installation of the transparent proxy for those workloads. +### Annotations -- `traffic.kuma.io/transparent-proxy-configmap-name` +Kubernetes annotations can be applied to individual workloads to modify the transparent proxy configuration. These annotations allow fine-tuning of specific behaviors for a single workload without affecting others. - This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [Configuration in ConfigMap](#configuration-in-configmap-experimental) feature is enabled. For more details, refer to the [Custom ConfigMap name](#custom-configmap-name) section. +For the full list of annotations which affect the transparent proxy configuration refer to [Annotations section]({{ docs }}/reference/transparent-proxy-configuration/#annotations) in the transparent proxy configuration reference. -### Automatically applied annotations +#### Automatically applied annotations -Certain annotations are automatically added to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers), regardless of whether they are explicitly defined. These annotations reflect the final values used to configure the transparent proxy. For settings that can be manually specified, these annotations will still be applied, even if not explicitly provided, using values from the [Control Plane Runtime Configuration](#control-plane-runtime-configuration). +Certain annotations are automatically added to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers), regardless of whether they are explicitly defined. These annotations reflect the final values used to configure the transparent proxy. For settings that can be manually specified, these annotations will still be applied, even if not explicitly provided, using values from the [control plane runtime configuration](#control-plane-runtime-configuration). The automatically applied annotations include: @@ -250,15 +178,13 @@ The automatically applied annotations include: These annotations ensure that the proper configuration is automatically applied to each workload, aligning with the global and per-workload settings. - -### Order of Precedence - +### Order of precedence When using multiple configuration methods, it's important to understand the order in which they are applied to avoid conflicts and ensure the correct settings are used. 1. [Default values]({{ docs }}/reference/transparent-proxy-configuration/#default-values) -2. [Control Plane Runtime Configuration](#control-plane-runtime-configuration) +2. [Control plane runtime configuration](#control-plane-runtime-configuration) 3. [Configuration in ConfigMap](#configuration-in-configmap-experimental) diff --git a/app/_src/networking/transparent-proxy/universal.md b/app/_src/networking/transparent-proxy/universal.md index e6037001f..9161df13f 100644 --- a/app/_src/networking/transparent-proxy/universal.md +++ b/app/_src/networking/transparent-proxy/universal.md @@ -309,7 +309,7 @@ This command will install the new version of the transparent proxy with the spec The default configuration works well for most scenarios, but there are cases where adjustments are needed. -{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). +{{ Kuma }} uses a unified configuration structure for transparent proxy across all components. For a detailed breakdown of this structure, including examples, expected formats, and variations between configuration methods, refer to the [Transparent Proxy Configuration reference]({{ docs }}/reference/transparent-proxy-configuration/). In Universal mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. diff --git a/app/_src/reference/transparent-proxy-configuration.md b/app/_src/reference/transparent-proxy-configuration.md index fe92b6d40..f93518c4b 100644 --- a/app/_src/reference/transparent-proxy-configuration.md +++ b/app/_src/reference/transparent-proxy-configuration.md @@ -303,6 +303,74 @@ runtime: programsSourcePath: /tmp/kuma-ebpf # KUMA_RUNTIME_KUBERNETES_INJECTOR_EBPF_PROGRAMS_SOURCE_PATH ``` +### Annotations + +Below you can find a list of Kubernetes annotations that can be used to configure specific transparent proxy settings. + +- `traffic.kuma.io/exclude-inbound-ips` + +- `traffic.kuma.io/exclude-inbound-ports` + +- `traffic.kuma.io/exclude-outbound-ips` + +- `traffic.kuma.io/exclude-outbound-ports` + +- `traffic.kuma.io/exclude-outbound-ports-for-uids` + +- `traffic.kuma.io/drop-invalid-packets` + +- `traffic.kuma.io/iptables-logs` + +- `kuma.io/transparent-proxying-ebpf` + +- `kuma.io/transparent-proxying-ebpf-bpf-fs-path` + +- `kuma.io/transparent-proxying-ebpf-cgroup-path` + +- `kuma.io/transparent-proxying-ebpf-tc-attach-iface` + +- `kuma.io/transparent-proxying-ebpf-instance-ip-env-var-name` + +- `kuma.io/transparent-proxying-ebpf-programs-source-path` + +- `kuma.io/transparent-proxying-ip-family-mode` + +The following annotations also affect the configuration, but their values are automatically managed by {{ Kuma }} and cannot be manually adjusted. Values of these annotations will always match those specified in the [control plane runtime configuration]({{ docs }}/networking/transparent-proxy/kubernetes/#control-plane-runtime-configuration). For more details, refer to [Settings restricted to control plane runtime configuration]({{ docs }}/networking/transparent-proxy/kubernetes/#settings-restricted-to-control-plane-runtime-configuration) section. + +- `kuma.io/sidecar-uid` + +- `kuma.io/transparent-proxying-inbound-port` + +- `kuma.io/transparent-proxying-outbound-port` + +{% warning %} +The following two annotations are deprecated and will be removed in future releases. They are provided here for reference only, and we **strongly advise against using them**. + +- `kuma.io/builtin-dns` + +- `kuma.io/builtin-dns-port` + {% endwarning %} + +The following annotation indirectly adjusts the transparent proxy configuration by configuring other components, resulting in changes to the transparent proxy behavior. While its value is automatically set by {{ Kuma }}, you can override it by manually providing a value. + +- `kuma.io/application-probe-proxy-port` + + This annotation defines the port (default: `9001`) to be excluded from incoming traffic redirection, similar to using the `traffic.kuma.io/exclude-inbound-ports` annotation or other configuration methods. For more information, refer to the [Kubernetes]({{ docs }}/policies/service-health-probes/#kubernetes) section in the [Service Health Probes]({{ docs }}/policies/service-health-probes/) documentation. + +The following annotations differ from others mentioned earlier as they are related to the transparent proxy, but do not directly or indirectly configure specific individual settings. + +- `kuma.io/transparent-proxying` + + This annotation is automatically applied to workloads with [injected sidecar containers]({{ docs }}/production/dp-config/dpp-on-kubernetes/#kubernetes-sidecar-containers). In Kubernetes environments, the transparent proxy is mandatory meaning you cannot disable it. Any attempt to explicitly disable it using this annotation will trigger a warning and have no effect. Therefore, the value of this annotation will always be set to `true`. + +- `traffic.kuma.io/transparent-proxy-config` + + This annotation is automatically applied in environments using [Kuma CNI]({{ docs }}/production/dp-config/cni/#configure-the-kuma-cni) instead of init containers. It contains the final configuration for installing the transparent proxy. Manually modifying or setting this annotation has no effect, regardless of whether Kuma CNI is used. Its primary purpose is to efficiently pass the transparent proxy configuration between Kubernetes workloads and the Kuma CNI, which handles the actual installation of the transparent proxy for those workloads. + +- `traffic.kuma.io/transparent-proxy-configmap-name` + + This annotation lets you specify a custom name for the ConfigMap that holds the transparent proxy configuration when the [Configuration in ConfigMap]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration-in-configmap-experimental) feature is enabled. For more details, refer to the [Custom ConfigMap name]({{ docs }}/networking/transparent-proxy/kubernetes/#custom-configmap-name) section. + ## Full reference - **`kumaDPUser`** From 8c3d882926f1c60298bf320a27131ad0677c179b Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 7 Nov 2024 08:21:42 +0100 Subject: [PATCH 23/40] address review remarks Signed-off-by: Bart Smykla --- .../networking/transparent-proxy/introduction.md | 2 +- .../networking/transparent-proxy/kubernetes.md | 2 +- .../transparent-proxy/reachable-backends.md | 16 ++++++++-------- .../transparent-proxy/reachable-services.md | 4 ++-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 4982037c5..1ad55db75 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -34,7 +34,7 @@ Using the transparent proxy in Universal mode makes setup easier and enables fea - **Simplified service connectivity**: Take advantage of [Kuma DNS]({{ docs }}/networking/dns/) to use `.mesh` domain names, like `https://service-1.mesh`, for easy service connections without needing `localhost` and ports in the `Dataplane` resource. -- **Flexible service naming**: With [MeshServices]({{ docs }}/networking/meshservice/) and [HostnameGenerators]({{ docs }}/networking/hostnamegenerator/), you can: +- **Flexible service addressing**: With [MeshServices]({{ docs }}/networking/meshservice/) and [HostnameGenerators]({{ docs }}/networking/hostnamegenerator/), you can: - Keep your existing DNS names when moving to the service mesh. - Give a service multiple DNS names for easier access. diff --git a/app/_src/networking/transparent-proxy/kubernetes.md b/app/_src/networking/transparent-proxy/kubernetes.md index ae9803917..4971c1a27 100644 --- a/app/_src/networking/transparent-proxy/kubernetes.md +++ b/app/_src/networking/transparent-proxy/kubernetes.md @@ -60,7 +60,7 @@ If `builtinDNS.enabled` or `builtinDNS.port` is updated using deprecated annotat #### Modifying control plane runtime configuration -For instructions on modifying the control plane configuration, see the [Modifying the configuration section]({{ docs }}/documentation/configuration/#modifying-the-configuration) section in the control plane configuration documentation. +For instructions on modifying the control plane configuration, see the [Modifying the configuration section]({{ docs }}/documentation/configuration/#modifying-the-configuration) in the control plane configuration documentation. #### Overriding list-based configuration settings diff --git a/app/_src/networking/transparent-proxy/reachable-backends.md b/app/_src/networking/transparent-proxy/reachable-backends.md index cd021cd05..cf603ebc9 100644 --- a/app/_src/networking/transparent-proxy/reachable-backends.md +++ b/app/_src/networking/transparent-proxy/reachable-backends.md @@ -35,7 +35,7 @@ Unlike Reachable Services, Reachable Backends uses a structured model to define apiVersion: apps/v1 kind: Pod metadata: - name: demo-client + name: demo-app namespace: kuma-demo annotations: kuma.io/reachable-backends: | @@ -61,7 +61,7 @@ networking: inbound: - port: {% raw %}{{ port }}{% endraw %} tags: - kuma.io/service: demo-client + kuma.io/service: demo-app transparentProxying: redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} @@ -81,7 +81,7 @@ networking: ### Examples -#### `demo-client` communicates only with `redis` on port 6379 +#### `demo-app` communicates only with `redis` on port 6379 {% tabs reachable-backends useUrlFragment=false %} @@ -90,7 +90,7 @@ networking: apiVersion: apps/v1 kind: Pod metadata: - name: demo-client + name: demo-app namespace: kuma-demo annotations: kuma.io/reachable-backends: | @@ -112,7 +112,7 @@ networking: inbound: - port: {% raw %}{{ port }}{% endraw %} tags: - kuma.io/service: demo-client + kuma.io/service: demo-app transparentProxying: redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} @@ -126,7 +126,7 @@ networking: {% endtabs %} -#### `demo-client` doesn’t need to communicate with any service +#### `demo-app` doesn’t need to communicate with any service {% tabs reachable-backends-no-services useUrlFragment=false %} @@ -135,7 +135,7 @@ networking: apiVersion: apps/v1 kind: Pod metadata: - name: demo-client + name: demo-app namespace: kuma-demo annotations: kuma.io/reachable-backends: "" @@ -152,7 +152,7 @@ networking: inbound: - port: {% raw %}{{ port }}{% endraw %} tags: - kuma.io/service: demo-client + kuma.io/service: demo-app transparentProxying: redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} diff --git a/app/_src/networking/transparent-proxy/reachable-services.md b/app/_src/networking/transparent-proxy/reachable-services.md index c763c32d5..181f811d8 100644 --- a/app/_src/networking/transparent-proxy/reachable-services.md +++ b/app/_src/networking/transparent-proxy/reachable-services.md @@ -6,7 +6,7 @@ content_type: how-to {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} -When the transparent proxy is enabled, {{ Kuma }} automatically configures each data plane proxy to connect with every other data plane proxy in the same mesh. This setup ensures broad service-to-service communication but can create issues in large service meshes: +When the transparent proxy is enabled, {{ Kuma }} automatically configures each data plane proxy to connect with **every other** data plane proxy in the same mesh. This setup ensures broad service-to-service communication but can create issues in large meshes: - **Increased Memory Usage**: The configuration for each data plane proxy can consume significant memory as the mesh grows. - **Slower Propagation**: Even small configuration changes for one service must be propagated to all data planes, which can be slow and resource-intensive. @@ -33,7 +33,7 @@ metadata: You can update your workload manifests manually or use a command like: ```sh -kumactl annotate pods example-app \ +kubectl annotate pods example-app \ "kuma.io/transparent-proxying-reachable-services=redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200" ``` {% endtab %} From e760cc4d63bf40af7826aad36d8a54915a1c1ffd Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 7 Nov 2024 11:41:18 +0100 Subject: [PATCH 24/40] another round of review Signed-off-by: Bart Smykla --- app/_src/networking/transparent-proxy/kubernetes.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/app/_src/networking/transparent-proxy/kubernetes.md b/app/_src/networking/transparent-proxy/kubernetes.md index 4971c1a27..612c592df 100644 --- a/app/_src/networking/transparent-proxy/kubernetes.md +++ b/app/_src/networking/transparent-proxy/kubernetes.md @@ -53,9 +53,9 @@ Some transparent proxy settings **can only be changed through the control plane ⚠️ IMPORTANT {:.custom-block-title} -If you change these settings, but with values different from the runtime configuration, they will be ignored, and a warning will appear in the control plane logs (except for DNS-related settings). +When the [**Configuration in ConfigMap**](#configuration-in-configmap-experimental) feature is enabled, any changes to these settings, whether through annotations or ConfigMap, will be ignored, and a warning will be logged in the control plane. -If `builtinDNS.enabled` or `builtinDNS.port` is updated using deprecated annotations while [Configuration in ConfigMap](#configuration-in-configmap-experimental) is disabled, the changes may still apply, potentially causing DNS redirection issues. This could prevent `kuma-dp` from starting the DNS server or listening on the correct port, leading to environment disruptions. +**However**, if this feature is disabled, and you update `builtinDNS.enabled` or `builtinDNS.port` using deprecated annotations, the changes may still apply, potentially causing DNS redirection issues. This could prevent `kuma-dp` from starting the DNS server or listening on the correct port, leading to environment disruptions. {% enddanger %} #### Modifying control plane runtime configuration @@ -90,9 +90,11 @@ To enable this feature, set `{{ transparentProxy }}.configMap.enabled` during in {{ transparentProxy }}.configMap.enabled=true {% endcpinstall %} +{% if_version lte:2.9.x %} {% warning %} If you set `{{ transparentProxy }}.configMap.config` to an empty value, it will override `{{ transparentProxy }}.configMap.enabled` and disable the feature, even if `{{ transparentProxy }}.configMap.enabled` is set to `true`. {% endwarning %} +{% endif_version %} #### ConfigMap auto-creation and configuration @@ -144,9 +146,11 @@ metadata: 4. **If still not found**: Search the `{{ kuma-system }}` namespace for the ConfigMap with the default name. +{% if_version lte:2.9.x %} {% warning %} The ConfigMap in the `{{ kuma-system }}` namespace is required for proper operation, so it must be present even if custom ones are used in all individual workload namespaces. {% endwarning %} +{% endif_version %} ### Annotations From 6e2dde7823832afa489087c07358cd10ee0d50ad Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 7 Nov 2024 11:55:29 +0100 Subject: [PATCH 25/40] add warning to annotations reference Signed-off-by: Bart Smykla --- .../reference/transparent-proxy-configuration.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/app/_src/reference/transparent-proxy-configuration.md b/app/_src/reference/transparent-proxy-configuration.md index f93518c4b..0347dad21 100644 --- a/app/_src/reference/transparent-proxy-configuration.md +++ b/app/_src/reference/transparent-proxy-configuration.md @@ -343,13 +343,20 @@ The following annotations also affect the configuration, but their values are au - `kuma.io/transparent-proxying-outbound-port` -{% warning %} -The following two annotations are deprecated and will be removed in future releases. They are provided here for reference only, and we **strongly advise against using them**. +{% danger %} +⚠️ IMPORTANT +{:.custom-block-title} -- `kuma.io/builtin-dns` +The following two annotations are deprecated and will be removed in future releases. They are provided here for reference only and **should not be used**: +- `kuma.io/builtin-dns` - `kuma.io/builtin-dns-port` - {% endwarning %} + +If you use these annotations while the [**Configuration in ConfigMap**]({{ docs }}/networking/transparent-proxy/kubernetes/#configuration-in-configmap-experimental) feature is enabled, they will be ignored, and a warning will be logged in the control plane. + +**However**, if this feature is disabled, changes from these annotations may still apply, potentially causing DNS redirection issues. This happens because the transparent proxy will be configured with the values specified in the annotations, while the rest of the system will use values from the [**control plane runtime configuration**]({{ docs }}/networking/transparent-proxy/kubernetes/#control-plane-runtime-configuration). This mismatch could prevent `kuma-dp` from starting the DNS server or listening on the correct port, potentially disrupting the environment. +{% enddanger %} + The following annotation indirectly adjusts the transparent proxy configuration by configuring other components, resulting in changes to the transparent proxy behavior. While its value is automatically set by {{ Kuma }}, you can override it by manually providing a value. From 089970dbc83b252e6e49149d7e5aab911e7aa25a Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 7 Nov 2024 12:18:39 +0100 Subject: [PATCH 26/40] move one section from tproxy/k8s to kuma-cp configuration page Signed-off-by: Bart Smykla --- app/_src/documentation/configuration.md | 6 ++++++ app/_src/networking/transparent-proxy/kubernetes.md | 8 -------- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/app/_src/documentation/configuration.md b/app/_src/documentation/configuration.md index 8800877fc..679d89cd1 100644 --- a/app/_src/documentation/configuration.md +++ b/app/_src/documentation/configuration.md @@ -77,6 +77,12 @@ If you configure `kuma-cp` with a YAML file, make sure to provide only values th Otherwise, upgrading {{site.mesh_product_name}} might be harder, because you need to keep track of your changes when replacing this file on every upgrade. {% endtip %} +### Overriding list-based configuration settings + +For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`, only the value from the highest-precedence configuration method will be applied; values from other methods will not be combined. + +For example, if `excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is used on a workload, the annotation will override the control plane setting, so only the ports in the annotation will be excluded. + ## Inspecting the configuration There are many ways to see your control plane configuration: diff --git a/app/_src/networking/transparent-proxy/kubernetes.md b/app/_src/networking/transparent-proxy/kubernetes.md index 612c592df..dec291c3a 100644 --- a/app/_src/networking/transparent-proxy/kubernetes.md +++ b/app/_src/networking/transparent-proxy/kubernetes.md @@ -62,14 +62,6 @@ When the [**Configuration in ConfigMap**](#configuration-in-configmap-experiment For instructions on modifying the control plane configuration, see the [Modifying the configuration section]({{ docs }}/documentation/configuration/#modifying-the-configuration) in the control plane configuration documentation. -#### Overriding list-based configuration settings - -For list-based settings like `runtime.kubernetes.injector.sidecarTraffic.excludeOutboundPorts`, only the value from the highest-precedence method will be applied; values from other methods will not be combined. - -For example, if `excludeOutboundPorts` is set in the control plane runtime configuration but an annotation like `traffic.kuma.io/exclude-outbound-ports` is used on a workload, the annotation will override the control plane setting, so only the ports in the annotation will be excluded. - -See the [**Order of precedence** section](#order-of-precedence) for more details. - ### Configuration in ConfigMap (experimental) {% warning %} From b482610c9abc4cb2c625bbd6b8a706368563bd1c Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 8 Nov 2024 08:19:20 +0100 Subject: [PATCH 27/40] small fixes after merge Signed-off-by: Bart Smykla --- app/_includes/snippets/tproxy/conf-field-table.html.liquid | 2 +- .../guide-excluding-traffic-other-options-k8s.html.liquid | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/app/_includes/snippets/tproxy/conf-field-table.html.liquid b/app/_includes/snippets/tproxy/conf-field-table.html.liquid index 0ac7d257d..33212e1c8 100644 --- a/app/_includes/snippets/tproxy/conf-field-table.html.liquid +++ b/app/_includes/snippets/tproxy/conf-field-table.html.liquid @@ -68,4 +68,4 @@ {%- endcapture -%} -{{ snippet-tproxy-field-table | normalize_whitespace }} \ No newline at end of file +{{ snippet-tproxy-field-table | normalize_whitespace }} diff --git a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid index 00cb6535e..bb8447f34 100644 --- a/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid +++ b/app/_includes/snippets/tproxy/guide-excluding-traffic-other-options-k8s.html.liquid @@ -4,7 +4,7 @@ - + Configuration in ConfigMap @@ -27,7 +27,7 @@ - + Control Plane Runtime Configuration From 98022549b332af3c1874e1316859511a11f8dc3d Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 8 Nov 2024 08:20:39 +0100 Subject: [PATCH 28/40] remove unnecessary vale comment Signed-off-by: Bart Smykla --- app/_src/networking/transparent-proxy/introduction.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/app/_src/networking/transparent-proxy/introduction.md b/app/_src/networking/transparent-proxy/introduction.md index 0fcf9ab50..1a9b73376 100644 --- a/app/_src/networking/transparent-proxy/introduction.md +++ b/app/_src/networking/transparent-proxy/introduction.md @@ -48,9 +48,7 @@ Using the transparent proxy in Universal mode makes setup easier and enables fea For more details on using the transparent proxy with Universal, see [Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/). {% endtip %} - ### Transparent proxy with eBPF (experimental) - Starting from {{ Kuma }} 2.0 you can set up transparent proxy to use eBPF instead of iptables. From 385400aee1be946384544445e6036ea804d218a0 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 12 Nov 2024 17:27:15 +0100 Subject: [PATCH 29/40] work in progress of moving installing tproxy to guide Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_2.10.x.yml | 9 +- app/_data/docs_nav_kuma_2.9.x.yml | 9 +- .../excluding-traffic-from-redirection.md} | 2 +- .../guides/transparent-proxy/installing.md | 239 ++++++++++++++++++ 4 files changed, 254 insertions(+), 5 deletions(-) rename app/_src/guides/{excluding-traffic-from-transparent-proxy-redirection.md => transparent-proxy/excluding-traffic-from-redirection.md} (99%) create mode 100644 app/_src/guides/transparent-proxy/installing.md diff --git a/app/_data/docs_nav_kuma_2.10.x.yml b/app/_data/docs_nav_kuma_2.10.x.yml index f85439058..1cbe893e9 100644 --- a/app/_data/docs_nav_kuma_2.10.x.yml +++ b/app/_data/docs_nav_kuma_2.10.x.yml @@ -536,8 +536,13 @@ items: url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies - - text: Excluding Traffic From Transparent Proxy - url: /guides/excluding-traffic-from-transparent-proxy-redirection/ + - title: Transparent Proxy + group: true + items: + - text: Installing + url: /guides/transparent-proxy/installing/ + - text: Excluding Traffic from Redirection + url: /guides/transparent-proxy/excluding-traffic-from-redirection/ - title: Reference group: true items: diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index 82e218944..9a321c582 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -536,8 +536,13 @@ items: url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies - - text: Excluding Traffic From Transparent Proxy - url: /guides/excluding-traffic-from-transparent-proxy-redirection/ + - title: Transparent Proxy + group: true + items: + - text: Installing + url: /guides/transparent-proxy/installing/ + - text: Excluding Traffic from Redirection + url: /guides/transparent-proxy/excluding-traffic-from-redirection/ - title: Reference group: true items: diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/transparent-proxy/excluding-traffic-from-redirection.md similarity index 99% rename from app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md rename to app/_src/guides/transparent-proxy/excluding-traffic-from-redirection.md index 7aa827dc1..ba722e909 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/transparent-proxy/excluding-traffic-from-redirection.md @@ -1,5 +1,5 @@ --- -title: Excluding Traffic from Transparent Proxy +title: Excluding Traffic from Transparent Proxy Redirection content_type: tutorial --- diff --git a/app/_src/guides/transparent-proxy/installing.md b/app/_src/guides/transparent-proxy/installing.md new file mode 100644 index 000000000..ead2ca385 --- /dev/null +++ b/app/_src/guides/transparent-proxy/installing.md @@ -0,0 +1,239 @@ +--- +title: Installing Transparent Proxy +--- + +{% assign docs = "/docs/" | append: page.release %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +Here are the steps to set up a transparent proxy for your service. Once set up, your service will run with a transparent proxy, giving you access to {{ Kuma }}'s features like traffic control, observability, and security. + +## Prerequisites + +{% assign version = page.latest_version.version %} +{% assign ip_ab = "172.56" %} +{% assign ip_abc = ip_ab | append: ".78" %} +{% assign prefix = "kuma-demo" %} +{% assign tmp = "/tmp/" | append: prefix %} + +## Step 1: Prepare the environment + +1. Prepare temporary directories where we'll store resources like data plane tokens or our Dataplane resource template and where our containers will put logs + + ```sh + mkdir --parents {{ tmp }}/logs + ``` + + Control plane, data planes and application will use `{{ tmp }}/logs` directory to log, so whenever you'll like to see the logs, go to this directory and look at appropriate file + +2. Prepare the `Dataplane` resource which our services data plane proxies will later use and put it in our temporary directory created earlier + + ```sh + echo 'type: Dataplane + mesh: default + name: {% raw %}{{ name }}{% endraw %} + networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: {% raw %}{{ name }}{% endraw %} + kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > {{ tmp }}/dataplane.yaml + ``` + +3. Create separate docker network for our containers + + We picked addresses in the `{{ ip_abc }}.0/24` range, but you can use whatever ones you want, just remember to update addresses for following steps if you decide to use different one + + ```sh + docker network create \ + --subnet "{{ ip_ab }}.0.0/16" \ + --ip-range "{{ ip_abc }}.0/24" \ + --gateway "{{ ip_abc }}.254" \ + {{ prefix }} + ``` + +## Step 2: Prepare the control plane + +1. Start control plane + + ```sh + docker run \ + --detach \ + --name {{ prefix }}-cp \ + --hostname kuma-cp \ + --volume {{ tmp }}:/kuma \ + --network {{ prefix }} \ + --publish "25681:5681" \ + --ip "{{ ip_abc }}.1" \ + kumahq/kuma-cp:{{ version }} run --log-output-path "/kuma/logs/kuma-cp.log" + ``` + + You should be able to access GUI on address `https://localhost:25681/gui` + +2. Configure `kumactl` to use created earlier control plane + + ```sh + TOKEN=$(docker exec --tty --interactive {{ prefix }}-cp wget --quiet --output-document - http://localhost:5681/global-secrets/admin-user-token | jq --raw-output .data | base64 --decode) \ + kumactl config control-planes add \ + --name {{ prefix }}-cp \ + --address http://localhost:25681 \ + --auth-type tokens \ + --auth-conf "token=$TOKEN" \ + --skip-verify + ``` + +3. Configure our default mesh to use exclusively `MeshServices` to which later allow us to benefit from all benefits it brings + + ```sh + echo "type: Mesh + name: default + meshServices: + mode: Exclusive" | kumactl apply -f- + ``` + +## Step 3: Services + +### Redis + +1. Generate data plane token + + ```sh + kumactl generate dataplane-token \ + --tag "kuma.io/service=redis" \ + --valid-for "720h" \ + > {{ tmp }}/token-redis + ``` + +2. Start docker container + + ```sh + docker run \ + --detach \ + --name {{ prefix }}-redis \ + --hostname redis \ + --volume {{ tmp }}:/kuma \ + --network {{ prefix }} \ + --ip "{{ ip_abc }}.2" \ + redis:7.4.1 redis-server --protected-mode no --loglevel verbose + ``` + +3. Connect to the container + + ```sh + docker exec --tty --interactive --privileged {{ prefix }}-redis bash + ``` + +4. Prepare the environment + + ```sh + apt update && apt install -y curl iptables + curl --location https://kuma.io/installer.sh | VERSION="{{ version }}" sh - + mv kuma-{{ version }}/bin/* /usr/local/bin/ + useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} + ``` + +5. set zone + + ```sh + redis-cli set zone local + ``` + +6. Start data plane proxy + + ```sh + runuser --user kuma-dp -- \ + kuma-dp run \ + --cp-address="https://kuma-cp:5678" \ + --dataplane-token-file="/kuma/token-redis" \ + --dataplane-file="/kuma/dataplane.yaml" \ + --dataplane-var="name=redis" \ + --dataplane-var="address={{ ip_abc }}.2" \ + --dataplane-var="port=6379" \ + --dataplane-var="protocol=tcp" \ + > /kuma/logs/kuma-dp-redis.log 2>&1 & + ``` + +7. Install transparent proxy + + ```sh + kumactl install transparent-proxy \ + --verbose \ + --redirect-dns \ + 2>&1 | tee /kuma/logs/transparent-proxy-redis.log + ``` + +### Demo Application + +1. Generate data plane token + + ```sh + kumactl generate dataplane-token \ + --tag "kuma.io/service=demo-app" \ + --valid-for "720h" \ + > {{ tmp }}/token-demo-app + ``` + +2. Start docker container + + ```sh + docker run \ + --detach \ + --name {{ prefix }}-app \ + --hostname demo-app \ + --volume {{ tmp }}:/kuma \ + --network {{ prefix }} \ + --publish "25000:5000" \ + --ip "{{ ip_abc }}.3" \ + --env "REDIS_HOST=redis.svc.mesh.local" \ + kumahq/kuma-demo + ``` + + ```sh + docker exec --tty --interactive --privileged --workdir /root {{ prefix }}-app bash + ``` + +3. Prepare the environment + + ```sh + apt-get update && apt-get install -y iptables curl + curl --location https://kuma.io/installer.sh | VERSION="{{ version }}" sh - + mv kuma-{{ version }}/bin/* /usr/local/bin/ + useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} + ``` + +4. Start data plane proxy + + ```sh + runuser --user kuma-dp -- \ + kuma-dp run \ + --cp-address="https://kuma-cp:5678" \ + --dataplane-token-file="/kuma/token-demo-app" \ + --dataplane-file="/kuma/dataplane.yaml" \ + --dataplane-var="name=demo-app" \ + --dataplane-var="address={{ ip_abc }}.3" \ + --dataplane-var="port=5000" \ + --dataplane-var="protocol=http" \ + > /kuma/logs/kuma-dp-demo-app.log 2>&1 & + ``` + +5. Install transparent proxy + + ```sh + kumactl install transparent-proxy \ + --verbose \ + --redirect-dns \ + 2>&1 | tee /kuma/logs/transparent-proxy-demo-app.log + ``` + +### Cleanup + +```sh +docker rm -f kuma-demo-cp kuma-demo-redis kuma-demo-app +docker network rm kuma-demo +kumactl config control-planes remove --name kuma-demo-cp +rm -rf /tmp/kuma-demo/{logs,dataplane.yaml,token*} +``` From 7823edc4fd0a586d699ac04203bdef4c11e86fa1 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 12 Nov 2024 18:35:26 +0100 Subject: [PATCH 30/40] fix broken link for reachable backends Signed-off-by: Bart Smykla --- app/_src/networking/meshservice.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_src/networking/meshservice.md b/app/_src/networking/meshservice.md index 597ada4fd..929e0774d 100644 --- a/app/_src/networking/meshservice.md +++ b/app/_src/networking/meshservice.md @@ -297,7 +297,7 @@ described below. This enables automatic generation of the Kuma `MeshServices` resource but does not include the corresponding resources for every data plane proxy. The intention is for users to explicitly and gradually introduce -relevant `MeshServices` via [`reachableBackends`](/docs/{{ page.release }}/production/dp-config/transparent-proxying#reachable-backends). +relevant `MeshServices` via [`reachableBackends`](/docs/{{ page.release }}/{% if_version lte:2.8.x %}production/dp-config/transparent-proxying#reachable-backends{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/reachable-backends{% endif_version %}). #### `Exclusive` From 29bbc2567e61b36a76b312797e4e709c0289481a Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 12 Nov 2024 18:56:19 +0100 Subject: [PATCH 31/40] fix broken links Signed-off-by: Bart Smykla --- app/_src/introduction/concepts.md | 2 +- app/_src/production/dp-config/dpp-on-kubernetes.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/app/_src/introduction/concepts.md b/app/_src/introduction/concepts.md index ab36a6696..bc980cce2 100644 --- a/app/_src/introduction/concepts.md +++ b/app/_src/introduction/concepts.md @@ -76,4 +76,4 @@ To learn more about [policies checkout the in depth introduction](/docs/{{ page. A transparent proxy is a server that intercepts network traffic going to and from a service without requiring any changes to the application code. In {{ site.mesh_product_name}}, it captures this traffic and routes it to the data plane proxy, allowing policies to be applied. -For more details, see the [Transparent Proxy](/docs/{{ page.version}}/{% if_version lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x inline:true %}/networking/transparent-proxy/introduction/{% endif_version %}) documentation. +For more details, see the [Transparent Proxy](/docs/{{ page.release }}/{% if_version lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}/networking/transparent-proxy/introduction/{% endif_version %}) documentation. diff --git a/app/_src/production/dp-config/dpp-on-kubernetes.md b/app/_src/production/dp-config/dpp-on-kubernetes.md index acb302ee9..49e87d29d 100644 --- a/app/_src/production/dp-config/dpp-on-kubernetes.md +++ b/app/_src/production/dp-config/dpp-on-kubernetes.md @@ -7,7 +7,7 @@ On Kubernetes the {% if_version lte:2.1.x %}[`Dataplane`](/docs/{{ page.release The {{ site.mesh_product_name }} control plane injects a `kuma-sidecar` container into your `Pod`'s container. If you're not using the CNI, it also injects a `kuma-init` into `initContainers` to -setup [transparent proxying](/docs/{{ page.version }}/{% if_version lte:2.8.x inline:true %}production/dp-config/transparent-proxying/{% endif_version%}{% if_version gte:2.9.x inline:true %}/networking/transparent-proxy/introduction/{% endif_version%}). +setup [transparent proxying](/docs/{{ page.release }}/{% if_version lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}/networking/transparent-proxy/introduction/{% endif_version %}). You can control whether {{site.mesh_product_name}} automatically injects the data plane proxy by **labeling** either the Namespace or the Pod with `kuma.io/sidecar-injection=enabled`, e.g. From cc039bfe09b4793b7fe5424e298c0aa474ed48b3 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 19 Nov 2024 14:20:40 +0100 Subject: [PATCH 32/40] fix order of vale's accept.txt file Signed-off-by: Bart Smykla --- .github/styles/config/vocabularies/Base/accept.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/styles/config/vocabularies/Base/accept.txt b/.github/styles/config/vocabularies/Base/accept.txt index b522abe20..189dd43b3 100644 --- a/.github/styles/config/vocabularies/Base/accept.txt +++ b/.github/styles/config/vocabularies/Base/accept.txt @@ -25,6 +25,7 @@ CloudFormation CLI CNI|cni Cognito +ConfigMap configs? conntrack cors @@ -110,12 +111,14 @@ Multus NAD namespace[sd]? navtabs +netfilter Netlify Nginx ngrok observability Okta opa +orin [Oo]tel [Oo]utbounds? PascalCase @@ -159,6 +162,7 @@ TLS transcoder ttl txt +UIDs? uncheck uncomment Unicode @@ -167,6 +171,7 @@ unsecure upstreams? uri urls? +use_original_dst uuid Valero validators? @@ -178,11 +183,6 @@ workspace yaml|YAML yml [xX]DS|xds +xtables Zipkin zsh -xtables -netfilter -UIDs? -use_original_dst -orin -ConfigMap From b8ceef57753bd65656b63ca1456a117605956a69 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Thu, 21 Nov 2024 12:09:44 +0100 Subject: [PATCH 33/40] next temporary iteration of new quickstart guide for tproxy installing Signed-off-by: Bart Smykla --- .../guides/transparent-proxy/installing.md | 645 +++++++++++++----- 1 file changed, 477 insertions(+), 168 deletions(-) diff --git a/app/_src/guides/transparent-proxy/installing.md b/app/_src/guides/transparent-proxy/installing.md index ead2ca385..da9745467 100644 --- a/app/_src/guides/transparent-proxy/installing.md +++ b/app/_src/guides/transparent-proxy/installing.md @@ -6,234 +6,543 @@ title: Installing Transparent Proxy {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} +{% assign version = page.version %} +{% assign version = page.latest_version.version %} +{% capture version_image %}{% if version == "preview" %}0.0.0-preview.latest{% else %}{{ version }}{% endif %}{% endcapture %} +{% assign version_image = page.latest_version.version %} +{% assign ip_ab = "172.56" %} +{% assign ip_abc = ip_ab | append: ".78" %} +{% assign kuma = append: site.mesh_install_archive_name | default: "kuma" %} +{% assign kuma-demo = kuma | append: "-demo" %} +{% assign tmp-kuma-demo = "/tmp/" | append: kuma-demo %} +{% assign docker_org = site.mesh_docker_org | default: "kumahq" %} +{% assign gateway_name = kuma-demo | append: "-gateway" %} + +{% assign url_root = site.links.web | default: "https://kuma.io" %} +{% capture edition %}{% if page.edition and page.edition != "kuma" %}/{{ page.edition }}{% endif %}{% endcapture %} +{% assign url_installer = url_root | append: edition | append: "/installer.sh" %} + Here are the steps to set up a transparent proxy for your service. Once set up, your service will run with a transparent proxy, giving you access to {{ Kuma }}'s features like traffic control, observability, and security. ## Prerequisites -{% assign version = page.latest_version.version %} -{% assign ip_ab = "172.56" %} -{% assign ip_abc = ip_ab | append: ".78" %} -{% assign prefix = "kuma-demo" %} -{% assign tmp = "/tmp/" | append: prefix %} +Before starting, ensure you have the following tools installed: + +1. **Docker** +2. [**jq**](https://jqlang.github.io/jq/download/) +3. [**kumactl**]({{ docs }}/introduction/install-kuma/) ## Step 1: Prepare the environment -1. Prepare temporary directories where we'll store resources like data plane tokens or our Dataplane resource template and where our containers will put logs +### Install {{ Kuma }} - ```sh - mkdir --parents {{ tmp }}/logs - ``` +You can download and install {{ Kuma }} using the official installer. The installer automatically detects your operating system (Amazon Linux, CentOS, RedHat, Debian, Ubuntu, macOS) and downloads the appropriate binaries: + +```sh +curl --location {{ url_installer }} | VERSION="{{ version }}" sh - +``` - Control plane, data planes and application will use `{{ tmp }}/logs` directory to log, so whenever you'll like to see the logs, go to this directory and look at appropriate file +{% if version != "preview" %} +To finalize the installation add the {{ Kuma }} binaries to your system’s [$PATH](https://en.wikipedia.org/wiki/PATH_(variable)) so the commands are easily accessible: -2. Prepare the `Dataplane` resource which our services data plane proxies will later use and put it in our temporary directory created earlier +```sh +export PATH=$PATH:$(pwd)/{{ kuma }}-{{ version }}/bin +``` +{% else %} +To finalize the installation move the {{ Kuma }} binaries to a directory that is already in your system’s [$PATH](https://en.wikipedia.org/wiki/PATH_(variable)). In this case, use `/usr/local/bin/`: - ```sh - echo 'type: Dataplane - mesh: default - name: {% raw %}{{ name }}{% endraw %} - networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: {% raw %}{{ name }}{% endraw %} - kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} - transparentProxying: - redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} - redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > {{ tmp }}/dataplane.yaml - ``` +```sh +mv {{ kuma }}-*/bin/* /usr/local/bin/ +``` +{% endif %} -3. Create separate docker network for our containers +### Create temporary directories - We picked addresses in the `{{ ip_abc }}.0/24` range, but you can use whatever ones you want, just remember to update addresses for following steps if you decide to use different one - - ```sh - docker network create \ - --subnet "{{ ip_ab }}.0.0/16" \ - --ip-range "{{ ip_abc }}.0/24" \ - --gateway "{{ ip_abc }}.254" \ - {{ prefix }} - ``` +Set up a temporary directory to store resources like data plane tokens, `Dataplane` templates, and logs: -## Step 2: Prepare the control plane +```sh +mkdir -p {{ tmp-kuma-demo }}/logs +``` -1. Start control plane +### Prepare a `Dataplane` resource template + +Create a reusable `Dataplane` resource template for services: + +```sh +echo 'type: Dataplane +mesh: default +name: {% raw %}{{ name }}{% endraw %} +networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: {% raw %}{{ name }}{% endraw %} + kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > {{ tmp-kuma-demo }}/dataplane.yaml +``` + +This template simplifies creating Dataplane configurations for different services by replacing dynamic values during deployment. + +### Create a Docker network + +Set up a separate Docker network for the containers. Use IP addresses in the `{{ ip_abc }}.0/24` range or customize as needed: + +```sh +docker network create \ + --subnet "{{ ip_ab }}.0.0/16" \ + --ip-range "{{ ip_abc }}.0/24" \ + --gateway "{{ ip_abc }}.254" \ + {{ kuma-demo }} +``` + +## Step 2: Set up the control plane + +### Start the control plane + +Run the Kuma control plane in a Docker container: + +```sh +docker run \ + --detach \ + --name {{ kuma-demo }}-control-plane \ + --hostname {{ kuma }}-control-plane \ + --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ + --network {{ kuma-demo }} \ + --publish "25681:5681" \ + --ip "{{ ip_abc }}.1" \ + {{ docker_org }}/kuma-cp:{{ version_image }} run +``` + +Access the GUI at `http://localhost:25681/gui`. + +### Configure `kumactl` + +Link `kumactl` to the control plane: + +1. Retrieve the admin token: ```sh - docker run \ - --detach \ - --name {{ prefix }}-cp \ - --hostname kuma-cp \ - --volume {{ tmp }}:/kuma \ - --network {{ prefix }} \ - --publish "25681:5681" \ - --ip "{{ ip_abc }}.1" \ - kumahq/kuma-cp:{{ version }} run --log-output-path "/kuma/logs/kuma-cp.log" + docker exec --tty --interactive {{ kuma-demo }}-control-plane \ + wget --quiet --output-document - http://localhost:5681/global-secrets/admin-user-token \ + | jq --raw-output .data \ + | base64 --decode \ + > {{ tmp-kuma-demo }}/user-token-admin ``` - - You should be able to access GUI on address `https://localhost:25681/gui` -2. Configure `kumactl` to use created earlier control plane +2. Configure `kumactl`: ```sh - TOKEN=$(docker exec --tty --interactive {{ prefix }}-cp wget --quiet --output-document - http://localhost:5681/global-secrets/admin-user-token | jq --raw-output .data | base64 --decode) \ kumactl config control-planes add \ - --name {{ prefix }}-cp \ + --name {{ kuma-demo }}-control-plane \ --address http://localhost:25681 \ --auth-type tokens \ - --auth-conf "token=$TOKEN" \ + --auth-conf "token=$(cat {{ tmp-kuma-demo }}/user-token-admin)" \ --skip-verify ``` -3. Configure our default mesh to use exclusively `MeshServices` to which later allow us to benefit from all benefits it brings +To test it you can run - ```sh - echo "type: Mesh - name: default - meshServices: - mode: Exclusive" | kumactl apply -f- - ``` +```sh +kumactl get meshes +``` + +which should result in message similar to: + +``` +NAME mTLS METRICS LOGGING TRACING LOCALITY ZONEEGRESS AGE +default off off off off off off 1m +``` +{:.no-line-numbers} + +### Configure the default mesh -## Step 3: Services +Enable the exclusive use of `MeshServices` in the default mesh: + +```sh +echo "type: Mesh +name: default +meshServices: + mode: Exclusive" | kumactl apply -f- +``` + +## Step 3: Set up services ### Redis -1. Generate data plane token +#### Generate a data plane token - ```sh - kumactl generate dataplane-token \ - --tag "kuma.io/service=redis" \ - --valid-for "720h" \ - > {{ tmp }}/token-redis - ``` +Generate a token that the Redis data plane proxy will use to authenticate with the control plane. -2. Start docker container +```sh +kumactl generate dataplane-token \ + --tag "kuma.io/service=redis" \ + --valid-for "720h" \ + > {{ tmp-kuma-demo }}/data-plane-token-redis +``` - ```sh - docker run \ - --detach \ - --name {{ prefix }}-redis \ - --hostname redis \ - --volume {{ tmp }}:/kuma \ - --network {{ prefix }} \ - --ip "{{ ip_abc }}.2" \ - redis:7.4.1 redis-server --protected-mode no --loglevel verbose - ``` +#### Start the Redis container -3. Connect to the container +```sh +docker run \ + --detach \ + --name {{ kuma-demo }}-redis \ + --hostname redis \ + --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ + --network {{ kuma-demo }} \ + --ip "{{ ip_abc }}.2" \ + redis:7.4.1 redis-server --protected-mode no +``` - ```sh - docker exec --tty --interactive --privileged {{ prefix }}-redis bash - ``` +#### Prepare the Redis container -4. Prepare the environment +Enter the Redis container to run further commands. - ```sh - apt update && apt install -y curl iptables - curl --location https://kuma.io/installer.sh | VERSION="{{ version }}" sh - - mv kuma-{{ version }}/bin/* /usr/local/bin/ - useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} - ``` +```sh +docker exec --tty --interactive --privileged {{ kuma-demo }}-redis bash` +``` -5. set zone +{% warning %} +The following steps must be executed inside the Redis containe`r. +{% endwarning %} - ```sh - redis-cli set zone local - ``` - -6. Start data plane proxy +##### Install required tools - ```sh - runuser --user kuma-dp -- \ - kuma-dp run \ - --cp-address="https://kuma-cp:5678" \ - --dataplane-token-file="/kuma/token-redis" \ - --dataplane-file="/kuma/dataplane.yaml" \ - --dataplane-var="name=redis" \ - --dataplane-var="address={{ ip_abc }}.2" \ - --dataplane-var="port=6379" \ - --dataplane-var="protocol=tcp" \ - > /kuma/logs/kuma-dp-redis.log 2>&1 & - ``` - -7. Install transparent proxy +```sh +apt update && apt install -y curl iptables +curl --location {{ url_installer }} | VERSION="{{ version }}" sh - +mv {{ kuma }}-*/bin/* /usr/local/bin/ +``` - ```sh - kumactl install transparent-proxy \ - --verbose \ - --redirect-dns \ - 2>&1 | tee /kuma/logs/transparent-proxy-redis.log - ``` +##### Set a zone name + +Assign a zone name for Redis. This name will be displayed by the demo application to indicate the Redis instance being used. + +```sh +redis-cli set zone local-{{ kuma-demo }}-zone +``` + +##### Create a separate user for the data plane proxy + +```sh +useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} +``` + +##### Start the data plane proxy + +```sh +runuser --user kuma-dp -- \ + /usr/local/bin/kuma-dp run \ + --cp-address="https://{{ kuma }}-control-plane:5678" \ + --dataplane-token-file="/{{ kuma }}/data-plane-token-redis" \ + --dataplane-file="/{{ kuma }}/dataplane.yaml" \ + --dataplane-var="name=redis" \ + --dataplane-var="address={{ ip_abc }}.2" \ + --dataplane-var="port=6379" \ + --dataplane-var="protocol=tcp" \ + >/{{ kuma }}/logs/data-plane-redis.log 2>&1 & +``` + +##### Install the transparent proxy + +```sh +kumactl install transparent-proxy \ + --verbose \ + --redirect-dns \ + 2>&1 | tee /{{ kuma }}/logs/transparent-proxy-redis.log +``` + +##### Exit the Redis container + +```sh +exit +``` ### Demo Application -1. Generate data plane token +#### Generate a data plane token - ```sh - kumactl generate dataplane-token \ - --tag "kuma.io/service=demo-app" \ - --valid-for "720h" \ - > {{ tmp }}/token-demo-app - ``` +```sh +kumactl generate dataplane-token \ + --tag "kuma.io/service=demo-app" \ + --valid-for "720h" \ + > {{ tmp-kuma-demo }}/data-plane-token-demo-app +``` -2. Start docker container +#### Start the application container + +```sh +docker run \ + --detach \ + --name {{ kuma-demo }}-app \ + --hostname demo-app \ + --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ + --network {{ kuma-demo }} \ + --publish "25000:5000" \ + --ip "{{ ip_abc }}.3" \ + --env "REDIS_HOST=redis.svc.mesh.local" \ + kumahq/kuma-demo +``` + +#### Prepare the application container + +1. Access the container: ```sh - docker run \ - --detach \ - --name {{ prefix }}-app \ - --hostname demo-app \ - --volume {{ tmp }}:/kuma \ - --network {{ prefix }} \ - --publish "25000:5000" \ - --ip "{{ ip_abc }}.3" \ - --env "REDIS_HOST=redis.svc.mesh.local" \ - kumahq/kuma-demo - ``` - - ```sh - docker exec --tty --interactive --privileged --workdir /root {{ prefix }}-app bash + docker exec --tty --interactive --privileged --workdir /root {{ kuma-demo }}-app bash ``` -3. Prepare the environment +2. Install required tools: ```sh apt-get update && apt-get install -y iptables curl - curl --location https://kuma.io/installer.sh | VERSION="{{ version }}" sh - - mv kuma-{{ version }}/bin/* /usr/local/bin/ + curl --location {{ url_installer }} | VERSION="{{ version }}" sh - + mv {{ kuma }}-*/bin/* /usr/local/bin/ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} ``` - -4. Start data plane proxy - ```sh - runuser --user kuma-dp -- \ - kuma-dp run \ - --cp-address="https://kuma-cp:5678" \ - --dataplane-token-file="/kuma/token-demo-app" \ - --dataplane-file="/kuma/dataplane.yaml" \ - --dataplane-var="name=demo-app" \ - --dataplane-var="address={{ ip_abc }}.3" \ - --dataplane-var="port=5000" \ - --dataplane-var="protocol=http" \ - > /kuma/logs/kuma-dp-demo-app.log 2>&1 & - ``` - -5. Install transparent proxy +#### Start the data plane proxy - ```sh - kumactl install transparent-proxy \ - --verbose \ - --redirect-dns \ - 2>&1 | tee /kuma/logs/transparent-proxy-demo-app.log - ``` +```sh +runuser --user kuma-dp -- \ + /usr/local/bin/kuma-dp run \ + --cp-address="https://{{ kuma }}-control-plane:5678" \ + --dataplane-token-file="/{{ kuma }}/data-plane-token-demo-app" \ + --dataplane-file="/{{ kuma }}/dataplane.yaml" \ + --dataplane-var="name=demo-app" \ + --dataplane-var="address={{ ip_abc }}.3" \ + --dataplane-var="port=5000" \ + --dataplane-var="protocol=http" \ + > /{{ kuma }}/logs/data-plane-demo-app.log 2>&1 & +``` + +#### Install the transparent proxy + +```sh +kumactl install transparent-proxy \ + --verbose \ + --redirect-dns \ + 2>&1 | tee /{{ kuma }}/logs/transparent-proxy-demo-app.log +``` + +## Introduction to zero-trust security + +By default, the network is **insecure and unencrypted**. With {{ Kuma }}, you can enable the [Mutual TLS (mTLS)](/docs/{{ page.release }}/policies/mutual-tls/) policy to secure the network. This works by setting up a Certificate Authority (CA) that automatically provides TLS certificates to your services (specifically to the data plane proxies running next to each service). + +To enable Mutual TLS using a `builtin` CA backend, run the following command: + +```sh +echo 'type: Mesh +name: default +meshServices: + mode: Exclusive +mtls: + enabledBackend: ca-1 + backends: + - name: ca-1 + type: builtin' | kumactl apply -f - +``` + +After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly. This happens for two reasons: + +1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a [MeshTrafficPermission]({{ docs }}/policies/meshtrafficpermission/) policy to allow `demo-app` to communicate with `redis`. + +2. When you try to call `demo-app` using a browser or other HTTP client, you are essentially acting as an external client without a valid TLS certificate. Since all services are now required to present a certificate signed by the `ca-1` Certificate Authority, the connection is rejected. Only services within the `default` mesh, which are assigned valid certificates, can communicate with each other. + +To address the first issue, you need to apply an appropriate `MeshTrafficPermission` policy: + +```sh +echo 'type: MeshTrafficPermission +name: allow-redis-from-demo-app +mesh: default +spec: + targetRef: + kind: MeshSubset + tags: + kuma.io/service: redis + from: + - targetRef: + kind: MeshSubset + tags: + kuma.io/service: demo-app + default: + action: Allow' | kumactl apply -f - +``` + +The second issue is a bit more challenging. You can’t just get the necessary certificate and set up your web browser to act as part of the mesh. To handle traffic from outside the mesh, you need a _gateway proxy_. You can use tools like [Kong](https://github.com/Kong/kong), or you can use the [Built-in Gateway]({{ docs }}/using-mesh/managing-ingress-traffic/builtin/) that {{ Kuma }} provides. + +{% tip %} +For more information, see the [Managing incoming traffic with gateways]({{ docs }}/using-mesh/managing-ingress-traffic/overview/) section in the documentation. +{% endtip %} + +In this guide, we’ll use the built-in gateway. It allows you to configure a data plane proxy to act as a gateway and manage external traffic securely. + +### Setting up the built-in gateway + +The built-in gateway works like the data plane proxy for a regular service, but it requires its own configuration. Here’s how to set it up step by step. + +#### Step 1: Create a `Dataplane` resource + +For regular services, we reused a single Dataplane configuration file and provided dynamic values (like names and addresses) when starting the data plane proxy. This made it easier to scale or deploy multiple instances. However, since we’re deploying only one instance of the gateway, we can simplify things by hardcoding all the values directly into the file, as shown below: + +```sh +echo 'type: Dataplane +mesh: default +name: {{ gateway_name }}-instance-1 +networking: + address: {{ ip_abc }}.4 + gateway: + type: BUILTIN + tags: + kuma.io/service: {{ gateway_name }}' > {{ tmp-kuma-demo }}/dataplane-gateway.yaml +``` + +If you prefer to keep the flexibility of dynamic values, you can use the same template mechanisms for the gateway's `Dataplane` configuration as you did for regular services. + +#### Step 2: Generate a data plane token + +The gateway proxy requires a data plane token to securely register with the control plane. You can generate the token using the following command: + +```sh +kumactl generate dataplane-token \ + --tag "kuma.io/service={{ kuma-demo }}-gateway" \ + --valid-for "720h" \ + > {{ tmp-kuma-demo }}/data-plane-token-gateway +``` + +#### Step 3: Start the gateway container + +With the configuration and token in place, you can start the gateway proxy as a container: + +```sh +docker run \ + --detach \ + --name {{ gateway_name }} \ + --hostname gateway \ + --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ + --network {{ kuma-demo }} \ + --publish "25001:5000" \ + --ip "{{ ip_abc }}.4" \ + {{ docker_org }}/kuma-dp:{{ version_image }} run \ + --dns-enabled="false" \ + --cp-address="https://{{ kuma }}-control-plane:5678/" \ + --dataplane-token-file="/{{ kuma }}/data-plane-token-gateway" \ + --dataplane-file="/{{ kuma }}/dataplane-gateway.yaml" +``` + +This command starts the gateway proxy and registers it with the control plane. However, the gateway is not yet ready to route traffic. + +#### Step 4: Configure the gateway with `MeshGateway` -### Cleanup +To enable the gateway to accept external traffic, configure it with a `MeshGateway`. This setup defines listeners that specify the port, protocol, and tags for incoming traffic, allowing policies like `MeshHTTPRoute` or `MeshTCPRoute` to route traffic to services. + +Apply the configuration: ```sh -docker rm -f kuma-demo-cp kuma-demo-redis kuma-demo-app -docker network rm kuma-demo -kumactl config control-planes remove --name kuma-demo-cp -rm -rf /tmp/kuma-demo/{logs,dataplane.yaml,token*} +echo 'type: MeshGateway +mesh: default +name: {{ gateway_name }} +selectors: +- match: + kuma.io/service: {{ gateway_name }} +conf: + listeners: + - port: 5000 + protocol: HTTP + tags: + port: http-5000' | kumactl apply -f- +``` + +This configures the gateway to listen on port `5000` with the HTTP protocol and adds a tag (`port: http-5000`) to target this listener in routing policies. + +You can now test the gateway by sending a request to `http://localhost:25001/`. You should see a response like: + +``` +This is a {{ Kuma }} MeshGateway. No routes match this MeshGateway! +``` +{:.no-line-numbers} + +This confirms the gateway is running, but no routes have been configured yet to handle traffic. + +#### Step 5: Create a route to connect the gateway to `demo-app` + +To route traffic from the gateway to the `demo-app` service, create a `MeshHTTPRoute` policy: + +```sh +echo 'type: MeshHTTPRoute +name: gateway-demo-app-route +mesh: default +spec: + targetRef: + kind: MeshGateway + name: {{ gateway_name }} + tags: + port: http-5000 + to: + - targetRef: + kind: Mesh + rules: + - matches: + - path: + type: PathPrefix + value: "/" + default: + backendRefs: + - kind: MeshService + name: demo-app' | kumactl apply -f- +``` + +This route links the gateway (`{{ gateway_name }}`) and its listener (`port: http-5000`) to the `demo-app` service. It forwards requests matching the path prefix `/` to `demo-app`. + +After applying this route, the gateway will attempt to redirect traffic to `demo-app`. However, if you test it by accessing `http://localhost:25001`, you’ll see: + +``` +RBAC: access denied +``` +{:.no-line-numbers} + +This happens because no `MeshTrafficPermission` exists to allow traffic from the gateway to `demo-app`. You'll need to create one in the next step. + +#### Step 6: Allow traffic from the gateway to `demo-app` + +To fix the `RBAC: access denied` error, create a `MeshTrafficPermission` policy to allow the gateway to send traffic to `demo-app`: + +```sh +echo 'type: MeshTrafficPermission +name: allow-demo-app-from-gateway +mesh: default +spec: + targetRef: + kind: MeshSubset + tags: + kuma.io/service: demo-app + from: + - targetRef: + kind: MeshSubset + tags: + kuma.io/service: {{ gateway_name }} + default: + action: Allow' | kumactl apply -f - +``` + +This policy allows traffic from the gateway (`{{ gateway_name }}`) to `demo-app`. After applying it, you can access `http://localhost:25001`, and the traffic will reach the `demo-app` service successfully. + +## Cleanup + +To clean up your environment, remove the Docker containers, network, temporary directory, and the control plane configuration from `kumactl`. Run the following commands: + +```sh +kumactl config control-planes remove --name {{ kuma-demo }}-control-plane + +docker rm -f \ + {{ kuma-demo }}-control-plane \ + {{ kuma-demo }}-redis \ + {{ kuma-demo }}-app \ + {{ kuma-demo }}-gateway + +docker network rm {{ kuma-demo }} + +rm -rf {{ tmp-kuma-demo }} ``` From a2cf2b9afe5774051130e66e9267e41be4f10750 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Mon, 25 Nov 2024 10:09:48 +0100 Subject: [PATCH 34/40] another temporary commit with work on new quick guide Signed-off-by: Bart Smykla --- app/_data/docs_nav_kuma_2.10.x.yml | 11 +- app/_data/docs_nav_kuma_2.9.x.yml | 11 +- ...fic-from-transparent-proxy-redirection.md} | 0 .../guides/transparent-proxy/installing.md | 548 -------------- app/_src/quickstart/docker-demo.md | 709 ++++++++++++++++++ 5 files changed, 717 insertions(+), 562 deletions(-) rename app/_src/guides/{transparent-proxy/excluding-traffic-from-redirection.md => excluding-traffic-from-transparent-proxy-redirection.md} (100%) delete mode 100644 app/_src/guides/transparent-proxy/installing.md create mode 100644 app/_src/quickstart/docker-demo.md diff --git a/app/_data/docs_nav_kuma_2.10.x.yml b/app/_data/docs_nav_kuma_2.10.x.yml index 1cbe893e9..56cb77e63 100644 --- a/app/_data/docs_nav_kuma_2.10.x.yml +++ b/app/_data/docs_nav_kuma_2.10.x.yml @@ -52,6 +52,8 @@ items: url: "/quickstart/kubernetes-demo/#next-steps" - text: Deploy Kuma on Universal url: /quickstart/universal-demo + - text: Deploy Kuma on Docker + url: /quickstart/docker-demo/ - title: Kuma in Production group: true items: @@ -536,13 +538,8 @@ items: url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies - - title: Transparent Proxy - group: true - items: - - text: Installing - url: /guides/transparent-proxy/installing/ - - text: Excluding Traffic from Redirection - url: /guides/transparent-proxy/excluding-traffic-from-redirection/ + - text: Excluding Traffic from Transparent Proxy Redirection + url: /guides/excluding-traffic-from-transparent-proxy-redirection/ - title: Reference group: true items: diff --git a/app/_data/docs_nav_kuma_2.9.x.yml b/app/_data/docs_nav_kuma_2.9.x.yml index 9a321c582..f2e6eb3f9 100644 --- a/app/_data/docs_nav_kuma_2.9.x.yml +++ b/app/_data/docs_nav_kuma_2.9.x.yml @@ -52,6 +52,8 @@ items: url: "/quickstart/kubernetes-demo/#next-steps" - text: Deploy Kuma on Universal url: /quickstart/universal-demo + - text: Deploy Kuma on Docker + url: /quickstart/docker-demo/ - title: Kuma in Production group: true items: @@ -536,13 +538,8 @@ items: url: /guides/progressively-rolling-in-strict-mtls/ - text: Producer and consumer policies url: /guides/consumer-producer-policies - - title: Transparent Proxy - group: true - items: - - text: Installing - url: /guides/transparent-proxy/installing/ - - text: Excluding Traffic from Redirection - url: /guides/transparent-proxy/excluding-traffic-from-redirection/ + - text: Excluding Traffic from Transparent Proxy Redirection + url: /guides/excluding-traffic-from-transparent-proxy-redirection/ - title: Reference group: true items: diff --git a/app/_src/guides/transparent-proxy/excluding-traffic-from-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md similarity index 100% rename from app/_src/guides/transparent-proxy/excluding-traffic-from-redirection.md rename to app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md diff --git a/app/_src/guides/transparent-proxy/installing.md b/app/_src/guides/transparent-proxy/installing.md deleted file mode 100644 index da9745467..000000000 --- a/app/_src/guides/transparent-proxy/installing.md +++ /dev/null @@ -1,548 +0,0 @@ ---- -title: Installing Transparent Proxy ---- - -{% assign docs = "/docs/" | append: page.release %} -{% assign Kuma = site.mesh_product_name %} -{% assign tproxy = site.data.tproxy %} - -{% assign version = page.version %} -{% assign version = page.latest_version.version %} -{% capture version_image %}{% if version == "preview" %}0.0.0-preview.latest{% else %}{{ version }}{% endif %}{% endcapture %} -{% assign version_image = page.latest_version.version %} -{% assign ip_ab = "172.56" %} -{% assign ip_abc = ip_ab | append: ".78" %} -{% assign kuma = append: site.mesh_install_archive_name | default: "kuma" %} -{% assign kuma-demo = kuma | append: "-demo" %} -{% assign tmp-kuma-demo = "/tmp/" | append: kuma-demo %} -{% assign docker_org = site.mesh_docker_org | default: "kumahq" %} -{% assign gateway_name = kuma-demo | append: "-gateway" %} - -{% assign url_root = site.links.web | default: "https://kuma.io" %} -{% capture edition %}{% if page.edition and page.edition != "kuma" %}/{{ page.edition }}{% endif %}{% endcapture %} -{% assign url_installer = url_root | append: edition | append: "/installer.sh" %} - -Here are the steps to set up a transparent proxy for your service. Once set up, your service will run with a transparent proxy, giving you access to {{ Kuma }}'s features like traffic control, observability, and security. - -## Prerequisites - -Before starting, ensure you have the following tools installed: - -1. **Docker** -2. [**jq**](https://jqlang.github.io/jq/download/) -3. [**kumactl**]({{ docs }}/introduction/install-kuma/) - -## Step 1: Prepare the environment - -### Install {{ Kuma }} - -You can download and install {{ Kuma }} using the official installer. The installer automatically detects your operating system (Amazon Linux, CentOS, RedHat, Debian, Ubuntu, macOS) and downloads the appropriate binaries: - -```sh -curl --location {{ url_installer }} | VERSION="{{ version }}" sh - -``` - -{% if version != "preview" %} -To finalize the installation add the {{ Kuma }} binaries to your system’s [$PATH](https://en.wikipedia.org/wiki/PATH_(variable)) so the commands are easily accessible: - -```sh -export PATH=$PATH:$(pwd)/{{ kuma }}-{{ version }}/bin -``` -{% else %} -To finalize the installation move the {{ Kuma }} binaries to a directory that is already in your system’s [$PATH](https://en.wikipedia.org/wiki/PATH_(variable)). In this case, use `/usr/local/bin/`: - -```sh -mv {{ kuma }}-*/bin/* /usr/local/bin/ -``` -{% endif %} - -### Create temporary directories - -Set up a temporary directory to store resources like data plane tokens, `Dataplane` templates, and logs: - -```sh -mkdir -p {{ tmp-kuma-demo }}/logs -``` - -### Prepare a `Dataplane` resource template - -Create a reusable `Dataplane` resource template for services: - -```sh -echo 'type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: {% raw %}{{ name }}{% endraw %} - kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} - transparentProxying: - redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} - redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > {{ tmp-kuma-demo }}/dataplane.yaml -``` - -This template simplifies creating Dataplane configurations for different services by replacing dynamic values during deployment. - -### Create a Docker network - -Set up a separate Docker network for the containers. Use IP addresses in the `{{ ip_abc }}.0/24` range or customize as needed: - -```sh -docker network create \ - --subnet "{{ ip_ab }}.0.0/16" \ - --ip-range "{{ ip_abc }}.0/24" \ - --gateway "{{ ip_abc }}.254" \ - {{ kuma-demo }} -``` - -## Step 2: Set up the control plane - -### Start the control plane - -Run the Kuma control plane in a Docker container: - -```sh -docker run \ - --detach \ - --name {{ kuma-demo }}-control-plane \ - --hostname {{ kuma }}-control-plane \ - --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ - --network {{ kuma-demo }} \ - --publish "25681:5681" \ - --ip "{{ ip_abc }}.1" \ - {{ docker_org }}/kuma-cp:{{ version_image }} run -``` - -Access the GUI at `http://localhost:25681/gui`. - -### Configure `kumactl` - -Link `kumactl` to the control plane: - -1. Retrieve the admin token: - - ```sh - docker exec --tty --interactive {{ kuma-demo }}-control-plane \ - wget --quiet --output-document - http://localhost:5681/global-secrets/admin-user-token \ - | jq --raw-output .data \ - | base64 --decode \ - > {{ tmp-kuma-demo }}/user-token-admin - ``` - -2. Configure `kumactl`: - - ```sh - kumactl config control-planes add \ - --name {{ kuma-demo }}-control-plane \ - --address http://localhost:25681 \ - --auth-type tokens \ - --auth-conf "token=$(cat {{ tmp-kuma-demo }}/user-token-admin)" \ - --skip-verify - ``` - -To test it you can run - -```sh -kumactl get meshes -``` - -which should result in message similar to: - -``` -NAME mTLS METRICS LOGGING TRACING LOCALITY ZONEEGRESS AGE -default off off off off off off 1m -``` -{:.no-line-numbers} - -### Configure the default mesh - -Enable the exclusive use of `MeshServices` in the default mesh: - -```sh -echo "type: Mesh -name: default -meshServices: - mode: Exclusive" | kumactl apply -f- -``` - -## Step 3: Set up services - -### Redis - -#### Generate a data plane token - -Generate a token that the Redis data plane proxy will use to authenticate with the control plane. - -```sh -kumactl generate dataplane-token \ - --tag "kuma.io/service=redis" \ - --valid-for "720h" \ - > {{ tmp-kuma-demo }}/data-plane-token-redis -``` - -#### Start the Redis container - -```sh -docker run \ - --detach \ - --name {{ kuma-demo }}-redis \ - --hostname redis \ - --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ - --network {{ kuma-demo }} \ - --ip "{{ ip_abc }}.2" \ - redis:7.4.1 redis-server --protected-mode no -``` - -#### Prepare the Redis container - -Enter the Redis container to run further commands. - -```sh -docker exec --tty --interactive --privileged {{ kuma-demo }}-redis bash` -``` - -{% warning %} -The following steps must be executed inside the Redis containe`r. -{% endwarning %} - -##### Install required tools - -```sh -apt update && apt install -y curl iptables -curl --location {{ url_installer }} | VERSION="{{ version }}" sh - -mv {{ kuma }}-*/bin/* /usr/local/bin/ -``` - -##### Set a zone name - -Assign a zone name for Redis. This name will be displayed by the demo application to indicate the Redis instance being used. - -```sh -redis-cli set zone local-{{ kuma-demo }}-zone -``` - -##### Create a separate user for the data plane proxy - -```sh -useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} -``` - -##### Start the data plane proxy - -```sh -runuser --user kuma-dp -- \ - /usr/local/bin/kuma-dp run \ - --cp-address="https://{{ kuma }}-control-plane:5678" \ - --dataplane-token-file="/{{ kuma }}/data-plane-token-redis" \ - --dataplane-file="/{{ kuma }}/dataplane.yaml" \ - --dataplane-var="name=redis" \ - --dataplane-var="address={{ ip_abc }}.2" \ - --dataplane-var="port=6379" \ - --dataplane-var="protocol=tcp" \ - >/{{ kuma }}/logs/data-plane-redis.log 2>&1 & -``` - -##### Install the transparent proxy - -```sh -kumactl install transparent-proxy \ - --verbose \ - --redirect-dns \ - 2>&1 | tee /{{ kuma }}/logs/transparent-proxy-redis.log -``` - -##### Exit the Redis container - -```sh -exit -``` - -### Demo Application - -#### Generate a data plane token - -```sh -kumactl generate dataplane-token \ - --tag "kuma.io/service=demo-app" \ - --valid-for "720h" \ - > {{ tmp-kuma-demo }}/data-plane-token-demo-app -``` - -#### Start the application container - -```sh -docker run \ - --detach \ - --name {{ kuma-demo }}-app \ - --hostname demo-app \ - --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ - --network {{ kuma-demo }} \ - --publish "25000:5000" \ - --ip "{{ ip_abc }}.3" \ - --env "REDIS_HOST=redis.svc.mesh.local" \ - kumahq/kuma-demo -``` - -#### Prepare the application container - -1. Access the container: - - ```sh - docker exec --tty --interactive --privileged --workdir /root {{ kuma-demo }}-app bash - ``` - -2. Install required tools: - - ```sh - apt-get update && apt-get install -y iptables curl - curl --location {{ url_installer }} | VERSION="{{ version }}" sh - - mv {{ kuma }}-*/bin/* /usr/local/bin/ - useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ tproxy.defaults.kuma-dp.username }} - ``` - -#### Start the data plane proxy - -```sh -runuser --user kuma-dp -- \ - /usr/local/bin/kuma-dp run \ - --cp-address="https://{{ kuma }}-control-plane:5678" \ - --dataplane-token-file="/{{ kuma }}/data-plane-token-demo-app" \ - --dataplane-file="/{{ kuma }}/dataplane.yaml" \ - --dataplane-var="name=demo-app" \ - --dataplane-var="address={{ ip_abc }}.3" \ - --dataplane-var="port=5000" \ - --dataplane-var="protocol=http" \ - > /{{ kuma }}/logs/data-plane-demo-app.log 2>&1 & -``` - -#### Install the transparent proxy - -```sh -kumactl install transparent-proxy \ - --verbose \ - --redirect-dns \ - 2>&1 | tee /{{ kuma }}/logs/transparent-proxy-demo-app.log -``` - -## Introduction to zero-trust security - -By default, the network is **insecure and unencrypted**. With {{ Kuma }}, you can enable the [Mutual TLS (mTLS)](/docs/{{ page.release }}/policies/mutual-tls/) policy to secure the network. This works by setting up a Certificate Authority (CA) that automatically provides TLS certificates to your services (specifically to the data plane proxies running next to each service). - -To enable Mutual TLS using a `builtin` CA backend, run the following command: - -```sh -echo 'type: Mesh -name: default -meshServices: - mode: Exclusive -mtls: - enabledBackend: ca-1 - backends: - - name: ca-1 - type: builtin' | kumactl apply -f - -``` - -After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly. This happens for two reasons: - -1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a [MeshTrafficPermission]({{ docs }}/policies/meshtrafficpermission/) policy to allow `demo-app` to communicate with `redis`. - -2. When you try to call `demo-app` using a browser or other HTTP client, you are essentially acting as an external client without a valid TLS certificate. Since all services are now required to present a certificate signed by the `ca-1` Certificate Authority, the connection is rejected. Only services within the `default` mesh, which are assigned valid certificates, can communicate with each other. - -To address the first issue, you need to apply an appropriate `MeshTrafficPermission` policy: - -```sh -echo 'type: MeshTrafficPermission -name: allow-redis-from-demo-app -mesh: default -spec: - targetRef: - kind: MeshSubset - tags: - kuma.io/service: redis - from: - - targetRef: - kind: MeshSubset - tags: - kuma.io/service: demo-app - default: - action: Allow' | kumactl apply -f - -``` - -The second issue is a bit more challenging. You can’t just get the necessary certificate and set up your web browser to act as part of the mesh. To handle traffic from outside the mesh, you need a _gateway proxy_. You can use tools like [Kong](https://github.com/Kong/kong), or you can use the [Built-in Gateway]({{ docs }}/using-mesh/managing-ingress-traffic/builtin/) that {{ Kuma }} provides. - -{% tip %} -For more information, see the [Managing incoming traffic with gateways]({{ docs }}/using-mesh/managing-ingress-traffic/overview/) section in the documentation. -{% endtip %} - -In this guide, we’ll use the built-in gateway. It allows you to configure a data plane proxy to act as a gateway and manage external traffic securely. - -### Setting up the built-in gateway - -The built-in gateway works like the data plane proxy for a regular service, but it requires its own configuration. Here’s how to set it up step by step. - -#### Step 1: Create a `Dataplane` resource - -For regular services, we reused a single Dataplane configuration file and provided dynamic values (like names and addresses) when starting the data plane proxy. This made it easier to scale or deploy multiple instances. However, since we’re deploying only one instance of the gateway, we can simplify things by hardcoding all the values directly into the file, as shown below: - -```sh -echo 'type: Dataplane -mesh: default -name: {{ gateway_name }}-instance-1 -networking: - address: {{ ip_abc }}.4 - gateway: - type: BUILTIN - tags: - kuma.io/service: {{ gateway_name }}' > {{ tmp-kuma-demo }}/dataplane-gateway.yaml -``` - -If you prefer to keep the flexibility of dynamic values, you can use the same template mechanisms for the gateway's `Dataplane` configuration as you did for regular services. - -#### Step 2: Generate a data plane token - -The gateway proxy requires a data plane token to securely register with the control plane. You can generate the token using the following command: - -```sh -kumactl generate dataplane-token \ - --tag "kuma.io/service={{ kuma-demo }}-gateway" \ - --valid-for "720h" \ - > {{ tmp-kuma-demo }}/data-plane-token-gateway -``` - -#### Step 3: Start the gateway container - -With the configuration and token in place, you can start the gateway proxy as a container: - -```sh -docker run \ - --detach \ - --name {{ gateway_name }} \ - --hostname gateway \ - --volume {{ tmp-kuma-demo }}:/{{ kuma }} \ - --network {{ kuma-demo }} \ - --publish "25001:5000" \ - --ip "{{ ip_abc }}.4" \ - {{ docker_org }}/kuma-dp:{{ version_image }} run \ - --dns-enabled="false" \ - --cp-address="https://{{ kuma }}-control-plane:5678/" \ - --dataplane-token-file="/{{ kuma }}/data-plane-token-gateway" \ - --dataplane-file="/{{ kuma }}/dataplane-gateway.yaml" -``` - -This command starts the gateway proxy and registers it with the control plane. However, the gateway is not yet ready to route traffic. - -#### Step 4: Configure the gateway with `MeshGateway` - -To enable the gateway to accept external traffic, configure it with a `MeshGateway`. This setup defines listeners that specify the port, protocol, and tags for incoming traffic, allowing policies like `MeshHTTPRoute` or `MeshTCPRoute` to route traffic to services. - -Apply the configuration: - -```sh -echo 'type: MeshGateway -mesh: default -name: {{ gateway_name }} -selectors: -- match: - kuma.io/service: {{ gateway_name }} -conf: - listeners: - - port: 5000 - protocol: HTTP - tags: - port: http-5000' | kumactl apply -f- -``` - -This configures the gateway to listen on port `5000` with the HTTP protocol and adds a tag (`port: http-5000`) to target this listener in routing policies. - -You can now test the gateway by sending a request to `http://localhost:25001/`. You should see a response like: - -``` -This is a {{ Kuma }} MeshGateway. No routes match this MeshGateway! -``` -{:.no-line-numbers} - -This confirms the gateway is running, but no routes have been configured yet to handle traffic. - -#### Step 5: Create a route to connect the gateway to `demo-app` - -To route traffic from the gateway to the `demo-app` service, create a `MeshHTTPRoute` policy: - -```sh -echo 'type: MeshHTTPRoute -name: gateway-demo-app-route -mesh: default -spec: - targetRef: - kind: MeshGateway - name: {{ gateway_name }} - tags: - port: http-5000 - to: - - targetRef: - kind: Mesh - rules: - - matches: - - path: - type: PathPrefix - value: "/" - default: - backendRefs: - - kind: MeshService - name: demo-app' | kumactl apply -f- -``` - -This route links the gateway (`{{ gateway_name }}`) and its listener (`port: http-5000`) to the `demo-app` service. It forwards requests matching the path prefix `/` to `demo-app`. - -After applying this route, the gateway will attempt to redirect traffic to `demo-app`. However, if you test it by accessing `http://localhost:25001`, you’ll see: - -``` -RBAC: access denied -``` -{:.no-line-numbers} - -This happens because no `MeshTrafficPermission` exists to allow traffic from the gateway to `demo-app`. You'll need to create one in the next step. - -#### Step 6: Allow traffic from the gateway to `demo-app` - -To fix the `RBAC: access denied` error, create a `MeshTrafficPermission` policy to allow the gateway to send traffic to `demo-app`: - -```sh -echo 'type: MeshTrafficPermission -name: allow-demo-app-from-gateway -mesh: default -spec: - targetRef: - kind: MeshSubset - tags: - kuma.io/service: demo-app - from: - - targetRef: - kind: MeshSubset - tags: - kuma.io/service: {{ gateway_name }} - default: - action: Allow' | kumactl apply -f - -``` - -This policy allows traffic from the gateway (`{{ gateway_name }}`) to `demo-app`. After applying it, you can access `http://localhost:25001`, and the traffic will reach the `demo-app` service successfully. - -## Cleanup - -To clean up your environment, remove the Docker containers, network, temporary directory, and the control plane configuration from `kumactl`. Run the following commands: - -```sh -kumactl config control-planes remove --name {{ kuma-demo }}-control-plane - -docker rm -f \ - {{ kuma-demo }}-control-plane \ - {{ kuma-demo }}-redis \ - {{ kuma-demo }}-app \ - {{ kuma-demo }}-gateway - -docker network rm {{ kuma-demo }} - -rm -rf {{ tmp-kuma-demo }} -``` diff --git a/app/_src/quickstart/docker-demo.md b/app/_src/quickstart/docker-demo.md new file mode 100644 index 000000000..6d1d91f68 --- /dev/null +++ b/app/_src/quickstart/docker-demo.md @@ -0,0 +1,709 @@ +--- +title: Deploy Kuma on Docker +--- + +{% capture docs %}/docs/{{ page.release }}{% endcapture %} +{% assign Kuma = site.mesh_product_name %} +{% assign tproxy = site.data.tproxy %} + +{% assign KUMA = Kuma | upcase | replace: " ", "_" %} +{% assign KUMA_PREVIEW_VERSION = KUMA | append: "_PREVIEW_VERSION" %} +{% assign KUMA_DEMO_TMP = KUMA | append: "_DEMO_TMP" %} +{% assign KUMA_DEMO_ADMIN_TOKEN = KUMA | append: "_DEMO_ADMIN_TOKEN" %} +{% assign version = page.version %} +{% capture version_full %}{% if version == "preview" %}${{ KUMA_PREVIEW_VERSION }}{% else %}{{ version }}{% endif %}{% endcapture %} +{% assign ip_ab = "172.56" %} +{% assign ip_abc = ip_ab | append: ".78" %} +{% assign kuma = site.mesh_install_archive_name | default: "kuma" %} +{% assign kuma-demo = kuma | append: "-demo" %} +{% assign docker_org = site.mesh_docker_org | default: "kumahq" %} +{% assign kuma-dp = kuma | append: "-data-plane-proxy" %} + +{% capture edition %}{% if page.edition and page.edition != "kuma" %}/{{ page.edition }}{% endif %}{% endcapture %} +{% assign url_installer = site.links.web | default: "https://kuma.io" | append: edition | append: "/installer.sh" %} +{% assign url_installer_external = site.links.share | default: "https://kuma.io" | append: edition | append: "/installer.sh" %} + + +{%- comment -%} local docs links {%- endcomment -%} + +{% capture MeshTrafficPermission %}[MeshTrafficPermission]({{ docs }}/policies/meshtrafficpermission/){% endcapture %} +{% capture MeshGateway %}[MeshGateway]({{ docs }}//using-mesh/managing-ingress-traffic/builtin-listeners/){% endcapture %} +{% capture MeshHTTPRoute %}[MeshHTTPRoute]({{ docs }}/policies/meshhttproute/){% endcapture %} +{% capture MeshTCPRoute %}[MeshTCPRoute]({{ docs }}/policies/meshtcproute/){% endcapture %} +{% capture kumactl %}[kumactl]({{ docs }}/explore/cli/#kumactl){% endcapture %} +{% capture Dataplane %}[Dataplane]({{ docs }}/production/dp-config/dpp/#dataplane-entity){% endcapture %} +{% capture Dataplanes %}[Dataplanes]({{ docs }}/production/dp-config/dpp/#dataplane-entity){% endcapture %} +{% capture MeshServices %}[MeshServices]({{ docs }}/networking/meshservice/){% endcapture %} + +This quick start guide demonstrates how to run {{ Kuma }} in Universal mode using Docker containers. + +You'll set up and secure a simple demo application to explore how {{ Kuma }} works. The application consists of two services: + +- `demo-app`: A web application that lets you increment a numeric counter. +- `redis`: A data store that keeps the counter's value. + +## Prerequisites + +{% capture note-docker-engine %} +{% tip %} +**Note:** This guide has been tested with [Docker Engine](https://docs.docker.com/engine/), [Docker Desktop](https://docs.docker.com/desktop/), [OrbStack](https://orbstack.dev/), and [Colima](https://github.com/abiosoft/colima). For Colima, a small adjustment is required (explained later). +{% endtip %} +{% endcapture %} + +1. Make sure the following tools are installed and ready to use: + + - `docker` + - `curl` + - `jq` + - `base64` + + {{ note-docker-engine | indent }} + +2. If you previously followed the [Deploy {{ Kuma }} on Universal quickstart]({{ docs }}/quickstart/universal-demo/) on the same machine, we recommend cleaning up your environment to ensure no control plane, Redis, demo-app, or their data plane proxies are still running. + + This isn’t mandatory, but it’s easy to accidentally mix up ports when typing commands manually, leading to unexpected results. If you copy the commands from this guide exactly or know what you’re doing and want to compare results between guides, you can skip this step. + +## Prepare the environment + +{% if version == "preview" %} +1. **Retrieve the latest preview version of {{ Kuma }}** + + To use the latest preview version of {{ Kuma }}, retrieve it and export it as an environment variable for later steps: + + ```sh + export {{ KUMA_PREVIEW_VERSION }}="$( + curl --silent --location {{ url_installer }} \ + | VERSION="preview" sh -s - --print-version 2> /dev/null + )" + + echo "${{ KUMA_PREVIEW_VERSION }}" + ``` + + You should see output similar to this: + + ``` + 0.0.0-preview.vabc123def + ``` + {:.no-line-numbers} + + {% capture warning-env-var %} + {% danger %} + **Warning:** If no output is shown or it looks incorrect, set the `{{ KUMA_PREVIEW_VERSION }}` variable to the correct version manually. Do not continue without this value, as it is needed for later steps. Using the wrong version may cause errors or unexpected problems. + {% enddanger %} + {% endcapture %} + {{ warning-env-var | indent }} +{% endif %} + +2. **Install {{ Kuma }}** + + You can download and install {{ Kuma }} using the official installer. The installer automatically detects your operating system (Amazon Linux, CentOS, RedHat, Debian, Ubuntu, macOS) and downloads the appropriate binaries: + + ```sh + curl --location {{ url_installer }} {% if version == "preview" or page.edition and page.edition != "kuma" -%}\ + {% endif %}| VERSION="{{ version_full }}" sh - + ``` + + To finalize the installation add the {{ Kuma }} binaries to your system’s [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) so the commands are easily accessible: + + ```sh + export PATH="$(pwd)/{{ kuma }}-{{ version_full }}/bin:$PATH" + ``` + +3. **Prepare a temporary directory** + + Set up a temporary directory to store resources like data plane tokens, {{ Dataplane }} templates, and logs. Export its path to the `{{ KUMA_DEMO_TMP }}` environment variable for use in later steps. Ensure the path does not end with a trailing `/`. + + {% capture warning-colima-adjust-path %} + {% warning %} + **Important:** If you are using **Colima**, you need to adjust the path. Colima only allows sharing paths from the `HOME` directory or `/tmp/colima/`. Instead of `/tmp/{{ kuma-demo }}`, you can use `/tmp/colima/{{ kuma-demo }}`. + {% endwarning %} + {% endcapture %} + {{ warning-colima-adjust-path | indent }} + + ```sh + export {{ KUMA_DEMO_TMP }}="/tmp/{{ kuma-demo }}" + ``` + + Check if the directory exists and is empty, and create it if necessary: + + ```sh + mkdir -p "${{ KUMA_DEMO_TMP }}" + ``` + +4. **Prepare a Dataplane resource template** + + Create a reusable {{ Dataplane }} resource template for services: + + ```sh + echo 'type: Dataplane + mesh: default + name: {% raw %}{{ name }}{% endraw %} + networking: + address: {% raw %}{{ address }}{% endraw %} + inbound: + - port: {% raw %}{{ port }}{% endraw %} + tags: + kuma.io/service: {% raw %}{{ name }}{% endraw %} + kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} + transparentProxying: + redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > ${{ KUMA_DEMO_TMP }}/dataplane.yaml + ``` + + This template simplifies creating Dataplane configurations for different services by replacing dynamic values during deployment. + +5. **Prepare a transparent proxy configuration file** + + ```sh + echo 'kumaDPUser: {{ kuma-dp }} + redirect: + dns: + enabled: true + verbose: true' > ${{ KUMA_DEMO_TMP }}/config-transparent-proxy.yaml + ``` + +6. **Create a Docker network** + + Set up a separate Docker network for the containers. Use IP addresses in the `{{ ip_abc }}.0/24` range or customize as needed: + + ```sh + docker network create \ + --subnet {{ ip_ab }}.0.0/16 \ + --ip-range {{ ip_abc }}.0/24 \ + --gateway {{ ip_abc }}.254 \ + {{ kuma-demo }} + ``` + +## Set up the control plane + +1. **Start the control plane** + + Run the Kuma control plane in a Docker container: + + ```sh + docker run \ + --detach \ + --name {{ kuma-demo }}-control-plane \ + --hostname control-plane \ + --network {{ kuma-demo }} \ + --ip {{ ip_abc }}.1 \ + --publish 25681:5681 \ + --volume ${{ KUMA_DEMO_TMP }}:/demo \ + {{ docker_org }}/kuma-cp:{{ version_full }} run + ``` + + You can now access the [{{ Kuma }} user interface (GUI)]({{ docs }}/production/gui/) at + +2. **Configure kumactl** + + To use {{ kumactl }} with our {{ Kuma }} deployment, we need to connect it to the control plane we set up earlier. + + 1. **Retrieve the admin token** + + Run the following command to get the admin token from the control plane: + + ```sh + export {{ KUMA_DEMO_ADMIN_TOKEN }}="$( + docker exec --tty --interactive {{ kuma-demo }}-control-plane \ + wget --quiet --output-document - \ + http://localhost:5681/global-secrets/admin-user-token \ + | jq --raw-output .data \ + | base64 --decode + )" + ``` + + 2. **Connect to the control plane** + + Use the retrieved token to link {{ kumactl }} to the control plane: + + ```sh + kumactl config control-planes add \ + --name {{ kuma-demo }} \ + --address http://localhost:25681 \ + --auth-type tokens \ + --auth-conf "token=${{ KUMA_DEMO_ADMIN_TOKEN }}" \ + --skip-verify + ``` + + 3. **Verify the connection** + + Run this command to check if the connection is working: + + ```sh + kumactl get meshes + ``` + + You should see a list of meshes with one entry: `default`. This confirms the configuration is successful. + +3. **Configure the default mesh** + + Set the default mesh to use {{ MeshServices }} in [exclusive mode]({{ docs }}/networking/meshservice/#options). MeshServices are explicit resources that represent destinations for traffic in the mesh. They define which {{ Dataplanes }} serve the traffic, as well as the available ports, IPs, and hostnames. This configuration ensures a clearer and more precise way to manage services and traffic routing in the mesh. + + ```sh + echo 'type: Mesh + name: default + meshServices: + mode: Exclusive' | kumactl apply --file - + ``` + +## Set up services + +{% capture code-block-install-required-tools %} +```sh +apt-get update && \ + apt-get install --yes curl iptables +``` +{% endcapture %} +{% capture code-block-install-kuma %} +```sh +curl --location {{ url_installer_external }} {% if version == "preview" or page.edition and page.edition != "kuma" %}\ + {% endif %}| VERSION="{{ version_full }}" sh - + +mv {{ kuma }}-{{ version_full }}/bin/* /usr/local/bin/ +``` +{% endcapture %} +{% capture code-block-add-kuma-dp-user %} +```sh +useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} +``` +{% endcapture %} +{% capture warning-run-inside-container %} +{%- capture warning-run-inside-container-msg -%} +**Important:** The following steps must be executed inside the container. +{%- endcapture -%} +{% if page.edition and page.edition != "kuma" %} +{:.important.no-icon} +> {{ warning-run-inside-container-msg }} + +{% else %} +{% warning %}{{ warning-run-inside-container-msg }}{% endwarning %} +{% endif %} +{% endcapture %} +{% capture warning-tproxy-command-run-inside-container %} +{% warning %} +**Important:** Make sure this command is executed **inside the container**. It changes iptables rules to redirect all traffic to the data plane proxy. Running it on your computer or a virtual machine without the data plane proxy can disrupt network connectivity. On a virtual machine, this might lock you out until you restart it. +{% endwarning %} +{% endcapture %} + +### Redis + +1. **Generate a data plane token** + + Generate a token that the Redis data plane proxy will use to authenticate with the control plane. + + ```sh + kumactl generate dataplane-token \ + --tag "kuma.io/service=redis" \ + --valid-for 720h \ + > ${{ KUMA_DEMO_TMP }}/token-redis + ``` + +2. **Start the Redis container** + + ```sh + docker run \ + --detach \ + --name {{ kuma-demo }}-redis \ + --hostname redis \ + --network {{ kuma-demo }} \ + --ip {{ ip_abc }}.2 \ + --volume ${{ KUMA_DEMO_TMP }}:/demo \ + redis:7.4.1 redis-server --protected-mode no + ``` + +3. **Prepare the Redis container** + + Enter the container to run further commands. + + {% if version != "preview" %} + ```sh + docker exec --tty --interactive --privileged {{ kuma-demo }}-redis bash + ``` + {% else %} + ```sh + docker exec \ + --tty \ + --interactive \ + --privileged \ + --env {{ KUMA_PREVIEW_VERSION }} \ + {{ kuma-demo }}-redis bash + ``` + {% endif %} + + {{ warning-run-inside-container | indent }} + + 1. **Set a zone name** + + Give the Redis instance a zone name. The demo application will use this name to show which Redis instance is being accessed. + + ```sh + redis-cli set zone local-demo-zone + ``` + + 2. **Install required tools** + + Install the necessary tools for downloading {{ Kuma }} binaries and setting up the [transparent proxy]({{ docs }}/networking/transparent-proxy/introduction/): + + - `curl`: Needed to download the {{ Kuma }} binaries. + - `iptables`: Required to configure the transparent proxy. + + Run the following command: + + {{ code-block-install-required-tools | indent | indent }} + + 3. **Install {{ Kuma }}** + + Now, install {{ Kuma }} and move its binaries to `/usr/local/bin/` so they are accessible to all users: + + {{ code-block-install-kuma | indent | indent }} + + 4. **Create a separate user for the data plane proxy** + + {{ code-block-add-kuma-dp-user | indent | indent }} + + 5. **Start the data plane proxy** + + ```sh + runuser --user {{ kuma-dp }} -- \ + /usr/local/bin/kuma-dp run \ + --cp-address https://control-plane:5678 \ + --dataplane-token-file /demo/token-redis \ + --dataplane-file /demo/dataplane.yaml \ + --dataplane-var "name=redis" \ + --dataplane-var "address={{ ip_abc }}.2" \ + --dataplane-var "port=6379" \ + --dataplane-var "protocol=tcp" \ + > /demo/logs-data-plane-proxy-redis.log 2>&1 & + ``` + + 6. **Install the transparent proxy** + + {{ warning-tproxy-command-run-inside-container | indent | indent }} + + ```sh + kumactl install transparent-proxy \ + --config-file /demo/config-transparent-proxy.yaml \ + > /demo/logs-transparent-proxy-install-redis.log 2>&1 + ``` + + 7. **Exit the container** + + Redis is now set up and running. You can safely exit the container as the configuration is complete: + + ```sh + exit + ``` + +4. **Check if service is running** + + To confirm the service is set up correctly and running, use the {{ kumactl }} to inspect the services: + + ```sh + kumactl inspect services + ``` + + The output should show a single service, `redis`, with the status `Online`. + + You can also open the [{{ Kuma }} GUI]({{ docs }}/production/gui/) at . Look for the `redis` service, and verify that its state is `Available`. + +### Demo Application + +The steps are the same as those explained earlier, with only the names changed. We won’t repeat the explanations here, but you can refer to the [Redis service](#redis) instructions if needed. + +1. **Generate a data plane token** + + ```sh + kumactl generate dataplane-token \ + --tag "kuma.io/service=demo-app" \ + --valid-for 720h \ + > ${{ KUMA_DEMO_TMP }}/token-demo-app + ``` + +2. **Start the application container** + + ```sh + docker run \ + --detach \ + --name {{ kuma-demo }}-app \ + --hostname demo-app \ + --network {{ kuma-demo }} \ + --ip {{ ip_abc }}.3 \ + --publish 25000:5000 \ + --volume ${{ KUMA_DEMO_TMP }}:/demo \ + --env "REDIS_HOST=redis.svc.mesh.local" \ + kumahq/kuma-demo + ``` + +3. **Prepare the application container** + + Enter the container to run further commands. + + ```sh + docker exec \ + --tty \ + --interactive \ + --privileged \ + --workdir /root \{% if version == "preview" %} + --env {{ KUMA_PREVIEW_VERSION }} \{% endif %} + {{ kuma-demo }}-app bash + ``` + + {{ warning-run-inside-container | indent }} + + 1. **Install required tools** + + {{ code-block-install-required-tools | indent | indent }} + + 2. **Install {{ Kuma }}** + + {{ code-block-install-kuma | indent | indent }} + + 3. **Create a separate user for the data plane proxy** + + {{ code-block-add-kuma-dp-user | indent | indent }} + + 4. **Start the data plane proxy** + + ```sh + runuser --user {{ kuma-dp }} -- \ + /usr/local/bin/kuma-dp run \ + --cp-address https://control-plane:5678 \ + --dataplane-token-file /demo/token-demo-app \ + --dataplane-file /demo/dataplane.yaml \ + --dataplane-var "name=demo-app" \ + --dataplane-var "address={{ ip_abc }}.3" \ + --dataplane-var "port=5000" \ + --dataplane-var "protocol=http" \ + > /demo/logs-data-plane-proxy-demo-app.log 2>&1 & + ``` + + 5. **Install the transparent proxy** + + {{ warning-tproxy-command-run-inside-container | indent | indent }} + + ```sh + kumactl install transparent-proxy \ + --config-file /demo/config-transparent-proxy.yaml \ + > /demo/logs-transparent-proxy-install-demo-app.log 2>&1 + ``` + + 6. **Exit the container** + + Demo application is now set up and running. You can safely exit the container as the configuration is complete: + + ```sh + exit + ``` + +## Introduction to zero-trust security + +By default, the network is **insecure and unencrypted**. With {{ Kuma }}, you can enable the [Mutual TLS (mTLS)]({{ docs }}/policies/mutual-tls/) policy to secure the network. This works by setting up a Certificate Authority (CA) that automatically provides TLS certificates to your services (specifically to the data plane proxies running next to each service). + +To enable Mutual TLS using a `builtin` CA backend, run the following command: + +```sh +echo 'type: Mesh +name: default +meshServices: + mode: Exclusive +mtls: + enabledBackend: ca-1 + backends: + - name: ca-1 + type: builtin' | kumactl apply --file - +``` + +After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly, meaning will no longer work. This happens for two reasons: + +1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a {{ MeshTrafficPermission }} policy to allow `demo-app` to communicate with `redis`. + +2. When you try to call `demo-app` using a browser or other HTTP client, you are essentially acting as an external client without a valid TLS certificate. Since all services are now required to present a certificate signed by the `ca-1` Certificate Authority, the connection is rejected. Only services within the `default` mesh, which are assigned valid certificates, can communicate with each other. + +To address the first issue, you need to apply an appropriate {{ MeshTrafficPermission }} policy: + +```sh +echo 'type: MeshTrafficPermission +name: allow-redis-from-demo-app +mesh: default +spec: + targetRef: + kind: MeshSubset + tags: + kuma.io/service: redis + from: + - targetRef: + kind: MeshSubset + tags: + kuma.io/service: demo-app + default: + action: Allow' | kumactl apply --file - +``` + +The second issue is a bit more challenging. You can’t just get the necessary certificate and set up your web browser to act as part of the mesh. To handle traffic from outside the mesh, you need a _gateway proxy_. You can use tools like [Kong](https://github.com/Kong/kong), or you can use the [Built-in Gateway]({{ docs }}/using-mesh/managing-ingress-traffic/builtin/) that {{ Kuma }} provides. + +{% tip %} +**Note:** For more information, see the [Managing incoming traffic with gateways]({{ docs }}/using-mesh/managing-ingress-traffic/overview/) section in the documentation. +{% endtip %} + +In this guide, we’ll use the built-in gateway. It allows you to configure a data plane proxy to act as a gateway and manage external traffic securely. + +### Setting up the built-in gateway + +The built-in gateway works like the data plane proxy for a regular service, but it requires its own configuration. Here’s how to set it up step by step. + +1. **Create a Dataplane resource** + + For regular services, we reused a single {{ Dataplane }} configuration file and provided dynamic values (like names and addresses) when starting the data plane proxy. This made it easier to scale or deploy multiple instances. However, since we’re deploying only one instance of the gateway, we can simplify things by hardcoding all the values directly into the file, as shown below: + + ```sh + echo 'type: Dataplane + mesh: default + name: gateway-instance-1 + networking: + address: {{ ip_abc }}.4 + gateway: + type: BUILTIN + tags: + kuma.io/service: gateway' > ${{ KUMA_DEMO_TMP }}/dataplane-gateway.yaml + ``` + + If you prefer to keep the flexibility of dynamic values, you can use the same template mechanisms for the gateway's {{ Dataplane }} configuration as you did for regular services. + +2. **Generate a data plane token** + + The gateway proxy requires a data plane token to securely register with the control plane. You can generate the token using the following command: + + ```sh + kumactl generate dataplane-token \ + --tag "kuma.io/service=gateway" \ + --valid-for 720h \ + > ${{ KUMA_DEMO_TMP }}/token-gateway + ``` + +3. **Start the gateway container** + + With the configuration and token in place, you can start the gateway proxy as a container: + + ```sh + docker run \ + --detach \ + --name {{ kuma-demo }}-gateway \ + --hostname gateway \ + --network {{ kuma-demo }} \ + --ip {{ ip_abc }}.4 \ + --publish 25001:5000 \ + --volume ${{ KUMA_DEMO_TMP }}:/demo \ + {{ docker_org }}/kuma-dp:{{ version_full }} run \ + --cp-address https://control-plane:5678 \ + --dataplane-token-file /demo/token-gateway \ + --dataplane-file /demo/dataplane-gateway.yaml \ + --dns-enabled="false" + ``` + + This command starts the gateway proxy and registers it with the control plane. However, the gateway is not yet ready to route traffic. + +4. **Configure the gateway with {{ MeshGateway }}** + + To enable the gateway to accept external traffic, configure it with a {{ MeshGateway }}. This setup defines listeners that specify the port, protocol, and tags for incoming traffic, allowing policies like {{ MeshHTTPRoute }} or {{ MeshTCPRoute }} to route traffic to services. + + Apply the configuration: + + ```sh + echo 'type: MeshGateway + mesh: default + name: gateway + selectors: + - match: + kuma.io/service: gateway + conf: + listeners: + - port: 5000 + protocol: HTTP + tags: + port: http-5000' | kumactl apply --file - + ``` + + This sets up the gateway to listen on port `5000` using the HTTP protocol and adds a tag (`port: http-5000`) to identify this listener in routing policies. + + You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. + +5. **Create a route to connect the gateway to `demo-app`** + + To route traffic from the gateway to the service, create a {{ MeshHTTPRoute }} policy: + + ```sh + echo 'type: MeshHTTPRoute + name: gateway-demo-app-route + mesh: default + spec: + targetRef: + kind: MeshGateway + name: gateway + tags: + port: http-5000 + to: + - targetRef: + kind: Mesh + rules: + - matches: + - path: + type: PathPrefix + value: "/" + default: + backendRefs: + - kind: MeshService + name: demo-app' | kumactl apply --file - + ``` + + This route connects the gateway and its listener (`port: http-5000`) to the `demo-app` service. It forwards any requests with the path prefix `/` to `demo-app`. + + After setting up this route, the gateway will try to send traffic to `demo-app`. However, if you test it by visiting , you’ll see: + + ``` + RBAC: access denied + ``` + {:.no-line-numbers} + + This happens because there is no {{ MeshTrafficPermission }} policy allowing traffic from the gateway to `demo-app`. You’ll need to create one in the next step. + +6. **Allow traffic from the gateway to `demo-app`** + + To fix the `RBAC: access denied` error, create a {{ MeshTrafficPermission }} policy to allow the gateway to send traffic to `demo-app`: + + ```sh + echo 'type: MeshTrafficPermission + name: allow-demo-app-from-gateway + mesh: default + spec: + targetRef: + kind: MeshSubset + tags: + kuma.io/service: demo-app + from: + - targetRef: + kind: MeshSubset + tags: + kuma.io/service: gateway + default: + action: Allow' | kumactl apply --file - + ``` + + This policy allows traffic from the gateway to `demo-app`. After applying it, you can access , and the traffic will reach the `demo-app` service successfully. + +## Cleanup + +To clean up your environment, remove the Docker containers, network, temporary directory, and the control plane configuration from {{ kumactl }}. Run the following commands: + +```sh +kumactl config control-planes remove --name {{ kuma-demo }} + +docker rm --force \ + {{ kuma-demo }}-control-plane \ + {{ kuma-demo }}-redis \ + {{ kuma-demo }}-app \ + {{ kuma-demo }}-gateway + +docker network rm {{ kuma-demo }} + +rm -rf "${{ KUMA_DEMO_TMP }}" +``` From c3ee3e7cea6bc8241044ff3fa739c15c46107c21 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 26 Nov 2024 07:57:38 +0100 Subject: [PATCH 35/40] add missing step + add margin-top for last steps Signed-off-by: Bart Smykla --- app/_src/quickstart/universal-demo.md | 63 ++++++++++++++++++--------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/app/_src/quickstart/universal-demo.md b/app/_src/quickstart/universal-demo.md index f476f6e62..fe39697bb 100644 --- a/app/_src/quickstart/universal-demo.md +++ b/app/_src/quickstart/universal-demo.md @@ -28,7 +28,7 @@ demo-app --> redis To download {{site.mesh_product_name}} we will use official installer, it will automatically detect the operating system (Amazon Linux, CentOS, RedHat, Debian, Ubuntu, and macOS) and download {{site.mesh_product_name}}: ```sh -curl -L {{site.links.web}}{% if page.edition %}/{{page.edition}}{% endif %}/installer.sh | VERSION={{ page.version_data.version }} sh - +curl -L {{site.links.web}}{% if page.edition and page.edition != "kuma" %}/{{page.edition}}{% endif %}/installer.sh | VERSION={% if page.version_data.label == "dev" %}preview{% else %}{{ page.version_data.version }}{% endif %} sh - ``` To finish installation we need to add {{site.mesh_product_name}} binaries to path: @@ -59,8 +59,9 @@ On Universal we need to manually create tokens for [data plane proxies](/docs/{{ for 30 days): ```sh -kumactl generate dataplane-token --tag kuma.io/service=redis --valid-for=720h > /tmp/kuma-token-redis -kumactl generate dataplane-token --tag kuma.io/service=demo-app --valid-for=720h > /tmp/kuma-token-demo-app +mkdir /tmp/kuma +kumactl generate dataplane-token --tag kuma.io/service=redis --valid-for=720h > /tmp/kuma/token-redis +kumactl generate dataplane-token --tag kuma.io/service=demo-app --valid-for=720h > /tmp/kuma/token-demo-app ``` After generating tokens we can start the data plane proxies that will be used for proxying traffic between `demo-app` and `redis`. @@ -82,8 +83,16 @@ This isn't related to mTLS between services. First we can start the data plane proxy for `redis`. On Universal we need to manually create Dataplane [resources](/docs/{{ page.release }}/introduction/concepts#resource) for data plane proxies, and run kuma-dp manually, to do this run: +{% capture env-vars-redis -%} +KUMA_READINESS_PORT=9901 +{%- if_version gte:2.9.x %} \ +KUMA_APPLICATION_PROBE_PROXY_PORT=9902 +{%- endif_version -%} +{% endcapture %} + ```sh -KUMA_READINESS_PORT=9901 \{% if_version gte:2.9.x %}KUMA_APPLICATION_PROBE_PROXY_PORT=9902 \{% endif_version %} kuma-dp run \ +{{ env-vars-redis }} \ +kuma-dp run \ --cp-address=https://localhost:5678/ \ --dns-enabled=false \ --dataplane-token-file=/tmp/kuma-token-redis \ @@ -117,8 +126,16 @@ export PATH=$PATH:$(pwd)/{{site.mesh_product_name_path}}-{{ page.version_data.ve Now we can start the data plane proxy for our demo-app, we can do this by running: +{% capture env-vars-demo-app -%} +KUMA_READINESS_PORT=9904 +{%- if_version gte:2.9.x %} \ +KUMA_APPLICATION_PROBE_PROXY_PORT=9905 +{%- endif_version -%} +{% endcapture %} + ```sh -KUMA_READINESS_PORT=9904 \{% if_version gte:2.9.x %}KUMA_APPLICATION_PROBE_PROXY_PORT=9905 \{% endif_version %} kuma-dp run \ +{{ env-vars-demo-app }} \ +kuma-dp run \ --cp-address=https://localhost:5678/ \ --dns-enabled=false \ --dataplane-token-file=/tmp/kuma-token-demo-app \ @@ -148,26 +165,32 @@ KUMA_READINESS_PORT=9904 \{% if_version gte:2.9.x %}KUMA_APPLICATION_PROBE_PROXY We will start the kuma-counter-demo in a new terminal window: 1. With the data plane proxies running, we can start our apps, first we will start and configure `Redis`: -```sh -redis-server --port 26379 --daemonize yes && redis-cli -p 26379 set zone local -``` -You should see message `OK` from `Redis` if this operation was successful. + + ```sh + redis-server --port 26379 --daemonize yes && redis-cli -p 26379 set zone local + ``` + + You should see message `OK` from `Redis` if this operation was successful. 2. Now we can start our `demo-app`. To do this we need to download repository with its source code: -```sh -git clone https://github.com/kumahq/kuma-counter-demo.git && cd kuma-counter-demo -``` + + ```sh + git clone https://github.com/kumahq/kuma-counter-demo.git && cd kuma-counter-demo + ``` 3. Now we need to run: -```sh -npm install --prefix=app/ && npm start --prefix=app/ -``` -If `demo-app` was started correctly you will see message: -``` -Server running on port 5000 -``` -In a browser, go to [127.0.0.1:5000](http://127.0.0.1:5000) and increment the counter. `demo-app` GUI should work without issues now. + ```sh + npm install --prefix=app/ && npm start --prefix=app/ + ``` + + If `demo-app` was started correctly you will see message: + + ``` + Server running on port 5000 + ``` + + In a browser, go to [127.0.0.1:5000](http://127.0.0.1:5000) and increment the counter. `demo-app` GUI should work without issues now. ## Explore {{site.mesh_product_name}} GUI From 2dc8e5713d26d514a31db62e704496dcab269698 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Tue, 26 Nov 2024 08:00:09 +0100 Subject: [PATCH 36/40] add missing step + add margin-top for last steps Signed-off-by: Bart Smykla --- app/_src/quickstart/docker-demo.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/app/_src/quickstart/docker-demo.md b/app/_src/quickstart/docker-demo.md index 6d1d91f68..7e996658a 100644 --- a/app/_src/quickstart/docker-demo.md +++ b/app/_src/quickstart/docker-demo.md @@ -23,9 +23,6 @@ title: Deploy Kuma on Docker {% assign url_installer = site.links.web | default: "https://kuma.io" | append: edition | append: "/installer.sh" %} {% assign url_installer_external = site.links.share | default: "https://kuma.io" | append: edition | append: "/installer.sh" %} - -{%- comment -%} local docs links {%- endcomment -%} - {% capture MeshTrafficPermission %}[MeshTrafficPermission]({{ docs }}/policies/meshtrafficpermission/){% endcapture %} {% capture MeshGateway %}[MeshGateway]({{ docs }}//using-mesh/managing-ingress-traffic/builtin-listeners/){% endcapture %} {% capture MeshHTTPRoute %}[MeshHTTPRoute]({{ docs }}/policies/meshhttproute/){% endcapture %} @@ -42,6 +39,16 @@ You'll set up and secure a simple demo application to explore how {{ Kuma }} wor - `demo-app`: A web application that lets you increment a numeric counter. - `redis`: A data store that keeps the counter's value. +{% mermaid %} +--- +title: service graph of the demo app +--- +flowchart LR +demo-app(demo-app :5000) +redis(redis :6379) +demo-app --> redis +{% endmermaid %} + ## Prerequisites {% capture note-docker-engine %} @@ -394,7 +401,7 @@ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} exit ``` -4. **Check if service is running** +4. {% if page.edition and page.edition == "kuma" %}{:.margin-top-1-5-rem}{% endif %}**Check if service is running** To confirm the service is set up correctly and running, use the {{ kumactl }} to inspect the services: @@ -495,6 +502,10 @@ The steps are the same as those explained earlier, with only the names changed. exit ``` +4. {% if page.edition and page.edition == "kuma" %}{:.margin-top-1-5-rem}{% endif %}**Verify the application** + + Open in your browser and use the demo application to increment the counter. The demo application is now fully set up and running. + ## Introduction to zero-trust security By default, the network is **insecure and unencrypted**. With {{ Kuma }}, you can enable the [Mutual TLS (mTLS)]({{ docs }}/policies/mutual-tls/) policy to secure the network. This works by setting up a Certificate Authority (CA) that automatically provides TLS certificates to your services (specifically to the data plane proxies running next to each service). @@ -625,7 +636,7 @@ The built-in gateway works like the data plane proxy for a regular service, but This sets up the gateway to listen on port `5000` using the HTTP protocol and adds a tag (`port: http-5000`) to identify this listener in routing policies. - You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. + You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. 5. **Create a route to connect the gateway to `demo-app`** From cfc50e86b42f6040f1ac80b7002e75aa8b255c8e Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 29 Nov 2024 11:07:21 +0100 Subject: [PATCH 37/40] modify docker-demo to use kuma-counter-demo v2 Signed-off-by: Bart Smykla --- app/_src/quickstart/docker-demo.md | 271 ++++++++++++++--------------- 1 file changed, 132 insertions(+), 139 deletions(-) diff --git a/app/_src/quickstart/docker-demo.md b/app/_src/quickstart/docker-demo.md index 7e996658a..d586f8420 100644 --- a/app/_src/quickstart/docker-demo.md +++ b/app/_src/quickstart/docker-demo.md @@ -17,7 +17,9 @@ title: Deploy Kuma on Docker {% assign kuma = site.mesh_install_archive_name | default: "kuma" %} {% assign kuma-demo = kuma | append: "-demo" %} {% assign docker_org = site.mesh_docker_org | default: "kumahq" %} -{% assign kuma-dp = kuma | append: "-data-plane-proxy" %} +{% assign kuma-data-plane-proxy = kuma | append: "-data-plane-proxy" %} +{% assign tmp = "/tmp/" | append: kuma-demo %} +{% assign tmp-colima = "/tmp/colima/" | append: kuma-demo %} {% capture edition %}{% if page.edition and page.edition != "kuma" %}/{{ page.edition }}{% endif %}{% endcapture %} {% assign url_installer = site.links.web | default: "https://kuma.io" | append: edition | append: "/installer.sh" %} @@ -37,16 +39,23 @@ This quick start guide demonstrates how to run {{ Kuma }} in Universal mode usin You'll set up and secure a simple demo application to explore how {{ Kuma }} works. The application consists of two services: - `demo-app`: A web application that lets you increment a numeric counter. -- `redis`: A data store that keeps the counter's value. +- `kv`: A data store that keeps the counter's value. {% mermaid %} --- title: service graph of the demo app --- flowchart LR -demo-app(demo-app :5000) -redis(redis :6379) -demo-app --> redis +browser(browser) + +subgraph mesh +edge-gateway(edge-gateway) +demo-app(demo-app :5050) +kv(kv :5050) +end +edge-gateway --> demo-app +demo-app --> kv +browser --> edge-gateway {% endmermaid %} ## Prerequisites @@ -66,7 +75,7 @@ demo-app --> redis {{ note-docker-engine | indent }} -2. If you previously followed the [Deploy {{ Kuma }} on Universal quickstart]({{ docs }}/quickstart/universal-demo/) on the same machine, we recommend cleaning up your environment to ensure no control plane, Redis, demo-app, or their data plane proxies are still running. +2. If you previously followed the [Deploy {{ Kuma }} on Universal quickstart]({{ docs }}/quickstart/universal-demo/) on the same machine, we recommend cleaning up your environment to ensure no control plane, application services, or their data plane proxies are still running. This isn’t mandatory, but it’s easy to accidentally mix up ports when typing commands manually, leading to unexpected results. If you copy the commands from this guide exactly or know what you’re doing and want to compare results between guides, you can skip this step. @@ -118,23 +127,19 @@ demo-app --> redis 3. **Prepare a temporary directory** - Set up a temporary directory to store resources like data plane tokens, {{ Dataplane }} templates, and logs. Export its path to the `{{ KUMA_DEMO_TMP }}` environment variable for use in later steps. Ensure the path does not end with a trailing `/`. + Set up a temporary directory to store resources like data plane tokens, {{ Dataplane }} templates, and logs. Ensure the path does not end with a trailing `/`. {% capture warning-colima-adjust-path %} {% warning %} - **Important:** If you are using **Colima**, you need to adjust the path. Colima only allows sharing paths from the `HOME` directory or `/tmp/colima/`. Instead of `/tmp/{{ kuma-demo }}`, you can use `/tmp/colima/{{ kuma-demo }}`. + **Important:** If you are using **Colima**, make sure to adjust the path in the steps of this guide. Colima only allows shared paths from the `HOME` directory or `/tmp/colima/`. Instead of `{{ tmp }}`, you can use `{{ tmp-colima }}`. {% endwarning %} {% endcapture %} {{ warning-colima-adjust-path | indent }} - ```sh - export {{ KUMA_DEMO_TMP }}="/tmp/{{ kuma-demo }}" - ``` - Check if the directory exists and is empty, and create it if necessary: ```sh - mkdir -p "${{ KUMA_DEMO_TMP }}" + mkdir -p {{ tmp }} ``` 4. **Prepare a Dataplane resource template** @@ -151,10 +156,10 @@ demo-app --> redis - port: {% raw %}{{ port }}{% endraw %} tags: kuma.io/service: {% raw %}{{ name }}{% endraw %} - kuma.io/protocol: {% raw %}{{ protocol }}{% endraw %} + kuma.io/protocol: http transparentProxying: redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} - redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > ${{ KUMA_DEMO_TMP }}/dataplane.yaml + redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }}' > {{ tmp }}/dataplane.yaml ``` This template simplifies creating Dataplane configurations for different services by replacing dynamic values during deployment. @@ -162,11 +167,11 @@ demo-app --> redis 5. **Prepare a transparent proxy configuration file** ```sh - echo 'kumaDPUser: {{ kuma-dp }} + echo 'kumaDPUser: {{ kuma-data-plane-proxy }} redirect: dns: enabled: true - verbose: true' > ${{ KUMA_DEMO_TMP }}/config-transparent-proxy.yaml + verbose: true' > {{ tmp }}/config-transparent-proxy.yaml ``` 6. **Create a Docker network** @@ -185,8 +190,8 @@ demo-app --> redis 1. **Start the control plane** - Run the Kuma control plane in a Docker container: - + Use the official Docker image to run the {{ Kuma }} control plane. This image starts the control plane binary automatically, so no extra flags or configurations are needed for this guide. Simply use the `run` command: + ```sh docker run \ --detach \ @@ -195,11 +200,11 @@ demo-app --> redis --network {{ kuma-demo }} \ --ip {{ ip_abc }}.1 \ --publish 25681:5681 \ - --volume ${{ KUMA_DEMO_TMP }}:/demo \ + --volume {{ tmp }}:/demo \ {{ docker_org }}/kuma-cp:{{ version_full }} run - ``` - - You can now access the [{{ Kuma }} user interface (GUI)]({{ docs }}/production/gui/) at + ``` + + You can now access the [{{ Kuma }} user interface (GUI)]({{ docs }}/production/gui/) at . 2. **Configure kumactl** @@ -255,23 +260,21 @@ demo-app --> redis ## Set up services -{% capture code-block-install-required-tools %} +{% capture code-block-install-tools-create-user %} ```sh +# install necessary packages apt-get update && \ apt-get install --yes curl iptables -``` -{% endcapture %} -{% capture code-block-install-kuma %} -```sh + +# download and install {{ Kuma }} curl --location {{ url_installer_external }} {% if version == "preview" or page.edition and page.edition != "kuma" %}\ {% endif %}| VERSION="{{ version_full }}" sh - +# move {{ Kuma }} binaries to /usr/local/bin/ for global availability mv {{ kuma }}-{{ version_full }}/bin/* /usr/local/bin/ -``` -{% endcapture %} -{% capture code-block-add-kuma-dp-user %} -```sh -useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} + +# create a dedicated user for the data plane proxy +useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-data-plane-proxy }} ``` {% endcapture %} {% capture warning-run-inside-container %} @@ -292,39 +295,41 @@ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} {% endwarning %} {% endcapture %} -### Redis +### Key/Value Store + +This section explains how to start the `kv` service, which mimics key/value store database. 1. **Generate a data plane token** - Generate a token that the Redis data plane proxy will use to authenticate with the control plane. - + Create a token for the `kv` data plane proxy to authenticate with the control plane: + ```sh kumactl generate dataplane-token \ - --tag "kuma.io/service=redis" \ + --tag kuma.io/service=kv \ --valid-for 720h \ - > ${{ KUMA_DEMO_TMP }}/token-redis + > {{ tmp }}/token-kv ``` -2. **Start the Redis container** +2. **Start the container** ```sh docker run \ --detach \ - --name {{ kuma-demo }}-redis \ - --hostname redis \ + --name {{ kuma-demo }}-kv \ + --hostname kv \ --network {{ kuma-demo }} \ --ip {{ ip_abc }}.2 \ - --volume ${{ KUMA_DEMO_TMP }}:/demo \ - redis:7.4.1 redis-server --protected-mode no + --volume {{ tmp }}:/demo \ + ghcr.io/kumahq/kuma-counter-demo:debian-slim ``` -3. **Prepare the Redis container** +3. **Prepare the container** Enter the container to run further commands. {% if version != "preview" %} ```sh - docker exec --tty --interactive --privileged {{ kuma-demo }}-redis bash + docker exec --tty --interactive --privileged {{ kuma-demo }}-kv bash ``` {% else %} ```sh @@ -333,69 +338,60 @@ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} --interactive \ --privileged \ --env {{ KUMA_PREVIEW_VERSION }} \ - {{ kuma-demo }}-redis bash + {{ kuma-demo }}-kv bash ``` {% endif %} {{ warning-run-inside-container | indent }} - 1. **Set a zone name** + 1. **Install tools and create data plane proxy user** - Give the Redis instance a zone name. The demo application will use this name to show which Redis instance is being accessed. - - ```sh - redis-cli set zone local-demo-zone - ``` - - 2. **Install required tools** - - Install the necessary tools for downloading {{ Kuma }} binaries and setting up the [transparent proxy]({{ docs }}/networking/transparent-proxy/introduction/): + Install the required tools for downloading {{ Kuma }} binaries, setting up the [transparent proxy]({{ docs }}/networking/transparent-proxy/introduction/), and create a dedicated user for the data plane proxy: - `curl`: Needed to download the {{ Kuma }} binaries. - `iptables`: Required to configure the transparent proxy. - Run the following command: + Run the following commands: - {{ code-block-install-required-tools | indent | indent }} + {{ code-block-install-tools-create-user | indent | indent }} - 3. **Install {{ Kuma }}** + 2. **Set the zone name** - Now, install {{ Kuma }} and move its binaries to `/usr/local/bin/` so they are accessible to all users: + Give the `kv` instance a name. The demo application will use this name to show which `kv` instance is being accessed. - {{ code-block-install-kuma | indent | indent }} - - 4. **Create a separate user for the data plane proxy** - - {{ code-block-add-kuma-dp-user | indent | indent }} + ```sh + curl localhost:5050/api/key-value/zone \ + --header 'Content-Type: application/json' \ + --data '{"value":"local-demo-zone"}' + ``` - 5. **Start the data plane proxy** + 3. **Start the data plane proxy** ```sh - runuser --user {{ kuma-dp }} -- \ + runuser --user {{ kuma-data-plane-proxy }} -- \ /usr/local/bin/kuma-dp run \ --cp-address https://control-plane:5678 \ - --dataplane-token-file /demo/token-redis \ + --dataplane-token-file /demo/token-kv \ --dataplane-file /demo/dataplane.yaml \ - --dataplane-var "name=redis" \ - --dataplane-var "address={{ ip_abc }}.2" \ - --dataplane-var "port=6379" \ - --dataplane-var "protocol=tcp" \ - > /demo/logs-data-plane-proxy-redis.log 2>&1 & + --dataplane-var name=kv \ + --dataplane-var address={{ ip_abc }}.2 \ + --dataplane-var port=5050 \ + > /demo/logs-data-plane-proxy-kv.log 2>&1 & ``` - 6. **Install the transparent proxy** + 4. **Install the transparent proxy** {{ warning-tproxy-command-run-inside-container | indent | indent }} ```sh kumactl install transparent-proxy \ --config-file /demo/config-transparent-proxy.yaml \ - > /demo/logs-transparent-proxy-install-redis.log 2>&1 + > /demo/logs-transparent-proxy-install-kv.log 2>&1 ``` - 7. **Exit the container** + 5. **Exit the container** - Redis is now set up and running. You can safely exit the container as the configuration is complete: + Key/Value Store is now set up and running. You can safely exit the container as the configuration is complete: ```sh exit @@ -409,21 +405,21 @@ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-dp }} kumactl inspect services ``` - The output should show a single service, `redis`, with the status `Online`. + The output should show a single service, `kv`, with the status `Online`. - You can also open the [{{ Kuma }} GUI]({{ docs }}/production/gui/) at . Look for the `redis` service, and verify that its state is `Available`. + You can also open the [{{ Kuma }} GUI]({{ docs }}/production/gui/) at . Look for the `kv` service, and verify that its state is `Available`. ### Demo Application -The steps are the same as those explained earlier, with only the names changed. We won’t repeat the explanations here, but you can refer to the [Redis service](#redis) instructions if needed. +The steps are the same as those explained earlier, with only the names changed. We won’t repeat the explanations here, but you can refer to the [Key/Value Store service](#keyvalue-store) instructions if needed. 1. **Generate a data plane token** ```sh kumactl generate dataplane-token \ - --tag "kuma.io/service=demo-app" \ + --tag kuma.io/service=demo-app \ --valid-for 720h \ - > ${{ KUMA_DEMO_TMP }}/token-demo-app + > {{ tmp }}/token-demo-app ``` 2. **Start the application container** @@ -435,56 +431,53 @@ The steps are the same as those explained earlier, with only the names changed. --hostname demo-app \ --network {{ kuma-demo }} \ --ip {{ ip_abc }}.3 \ - --publish 25000:5000 \ - --volume ${{ KUMA_DEMO_TMP }}:/demo \ - --env "REDIS_HOST=redis.svc.mesh.local" \ - kumahq/kuma-demo + --publish 25050:5050 \ + --volume {{ tmp }}:/demo \ + --env KV_URL=http://kv.svc.mesh.local:5050 \ + --env APP_VERSION=v1 \ + ghcr.io/kumahq/kuma-counter-demo:debian-slim ``` 3. **Prepare the application container** Enter the container to run further commands. + {% if version == "preview" %} ```sh docker exec \ --tty \ --interactive \ --privileged \ - --workdir /root \{% if version == "preview" %} - --env {{ KUMA_PREVIEW_VERSION }} \{% endif %} + --env {{ KUMA_PREVIEW_VERSION }} \ {{ kuma-demo }}-app bash ``` + {% else %} + ```sh + docker exec --tty --interactive --privileged {{ kuma-demo }}-app bash + ``` + {% endif %} {{ warning-run-inside-container | indent }} - 1. **Install required tools** - - {{ code-block-install-required-tools | indent | indent }} - - 2. **Install {{ Kuma }}** - - {{ code-block-install-kuma | indent | indent }} - - 3. **Create a separate user for the data plane proxy** + 1. **Install tools and create data plane proxy user** - {{ code-block-add-kuma-dp-user | indent | indent }} + {{ code-block-install-tools-create-user | indent | indent }} - 4. **Start the data plane proxy** + 2. **Start the data plane proxy** ```sh - runuser --user {{ kuma-dp }} -- \ + runuser --user {{ kuma-data-plane-proxy }} -- \ /usr/local/bin/kuma-dp run \ --cp-address https://control-plane:5678 \ --dataplane-token-file /demo/token-demo-app \ --dataplane-file /demo/dataplane.yaml \ - --dataplane-var "name=demo-app" \ - --dataplane-var "address={{ ip_abc }}.3" \ - --dataplane-var "port=5000" \ - --dataplane-var "protocol=http" \ + --dataplane-var name=demo-app \ + --dataplane-var address={{ ip_abc }}.3 \ + --dataplane-var port=5050 \ > /demo/logs-data-plane-proxy-demo-app.log 2>&1 & ``` - 5. **Install the transparent proxy** + 3. **Install the transparent proxy** {{ warning-tproxy-command-run-inside-container | indent | indent }} @@ -494,7 +487,7 @@ The steps are the same as those explained earlier, with only the names changed. > /demo/logs-transparent-proxy-install-demo-app.log 2>&1 ``` - 6. **Exit the container** + 4. **Exit the container** Demo application is now set up and running. You can safely exit the container as the configuration is complete: @@ -504,7 +497,7 @@ The steps are the same as those explained earlier, with only the names changed. 4. {% if page.edition and page.edition == "kuma" %}{:.margin-top-1-5-rem}{% endif %}**Verify the application** - Open in your browser and use the demo application to increment the counter. The demo application is now fully set up and running. + Open in your browser and use the demo application to increment the counter. The demo application is now fully set up and running. ## Introduction to zero-trust security @@ -524,9 +517,9 @@ mtls: type: builtin' | kumactl apply --file - ``` -After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly, meaning will no longer work. This happens for two reasons: +After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly, meaning will no longer work. This happens for two reasons: -1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a {{ MeshTrafficPermission }} policy to allow `demo-app` to communicate with `redis`. +1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a {{ MeshTrafficPermission }} policy to allow `demo-app` to communicate with `kv`. 2. When you try to call `demo-app` using a browser or other HTTP client, you are essentially acting as an external client without a valid TLS certificate. Since all services are now required to present a certificate signed by the `ca-1` Certificate Authority, the connection is rejected. Only services within the `default` mesh, which are assigned valid certificates, can communicate with each other. @@ -534,13 +527,13 @@ To address the first issue, you need to apply an appropriate {{ MeshTrafficPermi ```sh echo 'type: MeshTrafficPermission -name: allow-redis-from-demo-app +name: allow-kv-from-demo-app mesh: default spec: targetRef: kind: MeshSubset tags: - kuma.io/service: redis + kuma.io/service: kv from: - targetRef: kind: MeshSubset @@ -569,13 +562,13 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh echo 'type: Dataplane mesh: default - name: gateway-instance-1 + name: edge-gateway-instance-1 networking: - address: {{ ip_abc }}.4 gateway: type: BUILTIN tags: - kuma.io/service: gateway' > ${{ KUMA_DEMO_TMP }}/dataplane-gateway.yaml + kuma.io/service: edge-gateway + address: {{ ip_abc }}.4' > {{ tmp }}/dataplane-edge-gateway.yaml ``` If you prefer to keep the flexibility of dynamic values, you can use the same template mechanisms for the gateway's {{ Dataplane }} configuration as you did for regular services. @@ -586,9 +579,9 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh kumactl generate dataplane-token \ - --tag "kuma.io/service=gateway" \ + --tag kuma.io/service=edge-gateway \ --valid-for 720h \ - > ${{ KUMA_DEMO_TMP }}/token-gateway + > {{ tmp }}/token-edge-gateway ``` 3. **Start the gateway container** @@ -598,17 +591,17 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh docker run \ --detach \ - --name {{ kuma-demo }}-gateway \ + --name {{ kuma-demo }}-edge-gateway \ --hostname gateway \ --network {{ kuma-demo }} \ --ip {{ ip_abc }}.4 \ - --publish 25001:5000 \ - --volume ${{ KUMA_DEMO_TMP }}:/demo \ + --publish 28080:8080 \ + --volume {{ tmp }}:/demo \ {{ docker_org }}/kuma-dp:{{ version_full }} run \ --cp-address https://control-plane:5678 \ - --dataplane-token-file /demo/token-gateway \ - --dataplane-file /demo/dataplane-gateway.yaml \ - --dns-enabled="false" + --dataplane-token-file /demo/token-edge-gateway \ + --dataplane-file /demo/dataplane-edge-gateway.yaml \ + --dns-enabled=false ``` This command starts the gateway proxy and registers it with the control plane. However, the gateway is not yet ready to route traffic. @@ -622,21 +615,21 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh echo 'type: MeshGateway mesh: default - name: gateway + name: edge-gateway selectors: - match: - kuma.io/service: gateway + kuma.io/service: edge-gateway conf: listeners: - - port: 5000 + - port: 8080 protocol: HTTP tags: - port: http-5000' | kumactl apply --file - + port: http-8080' | kumactl apply --file - ``` - This sets up the gateway to listen on port `5000` using the HTTP protocol and adds a tag (`port: http-5000`) to identify this listener in routing policies. + This sets up the gateway to listen on port `8080` using the HTTP protocol and adds a tag (`port: http-8080`) to identify this listener in routing policies. - You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. + You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. 5. **Create a route to connect the gateway to `demo-app`** @@ -644,14 +637,14 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh echo 'type: MeshHTTPRoute - name: gateway-demo-app-route + name: edge-gateway-demo-app-route mesh: default spec: targetRef: kind: MeshGateway - name: gateway + name: edge-gateway tags: - port: http-5000 + port: http-8080 to: - targetRef: kind: Mesh @@ -666,9 +659,9 @@ The built-in gateway works like the data plane proxy for a regular service, but name: demo-app' | kumactl apply --file - ``` - This route connects the gateway and its listener (`port: http-5000`) to the `demo-app` service. It forwards any requests with the path prefix `/` to `demo-app`. + This route connects the gateway and its listener (`port: http-8080`) to the `demo-app` service. It forwards any requests with the path prefix `/` to `demo-app`. - After setting up this route, the gateway will try to send traffic to `demo-app`. However, if you test it by visiting , you’ll see: + After setting up this route, the gateway will try to send traffic to `demo-app`. However, if you test it by visiting , you’ll see: ``` RBAC: access denied @@ -683,7 +676,7 @@ The built-in gateway works like the data plane proxy for a regular service, but ```sh echo 'type: MeshTrafficPermission - name: allow-demo-app-from-gateway + name: allow-demo-app-from-edge-gateway mesh: default spec: targetRef: @@ -694,12 +687,12 @@ The built-in gateway works like the data plane proxy for a regular service, but - targetRef: kind: MeshSubset tags: - kuma.io/service: gateway + kuma.io/service: edge-gateway default: action: Allow' | kumactl apply --file - ``` - This policy allows traffic from the gateway to `demo-app`. After applying it, you can access , and the traffic will reach the `demo-app` service successfully. + This policy allows traffic from the gateway to `demo-app`. After applying it, you can access , and the traffic will reach the `demo-app` service successfully. ## Cleanup @@ -710,11 +703,11 @@ kumactl config control-planes remove --name {{ kuma-demo }} docker rm --force \ {{ kuma-demo }}-control-plane \ - {{ kuma-demo }}-redis \ + {{ kuma-demo }}-kv \ {{ kuma-demo }}-app \ - {{ kuma-demo }}-gateway + {{ kuma-demo }}-edge-gateway docker network rm {{ kuma-demo }} -rm -rf "${{ KUMA_DEMO_TMP }}" +rm -rf {{ tmp }} ``` From 6360bfbc9983fcc45d793b34c40981a21d5cd0c7 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 29 Nov 2024 11:27:37 +0100 Subject: [PATCH 38/40] replace localhost with 127.0.0.1 Signed-off-by: Bart Smykla --- app/_src/quickstart/docker-demo.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/app/_src/quickstart/docker-demo.md b/app/_src/quickstart/docker-demo.md index d586f8420..37d234687 100644 --- a/app/_src/quickstart/docker-demo.md +++ b/app/_src/quickstart/docker-demo.md @@ -204,7 +204,7 @@ browser --> edge-gateway {{ docker_org }}/kuma-cp:{{ version_full }} run ``` - You can now access the [{{ Kuma }} user interface (GUI)]({{ docs }}/production/gui/) at . + You can now access the [{{ Kuma }} user interface (GUI)]({{ docs }}/production/gui/) at . 2. **Configure kumactl** @@ -218,7 +218,7 @@ browser --> edge-gateway export {{ KUMA_DEMO_ADMIN_TOKEN }}="$( docker exec --tty --interactive {{ kuma-demo }}-control-plane \ wget --quiet --output-document - \ - http://localhost:5681/global-secrets/admin-user-token \ + http://127.0.0.1:5681/global-secrets/admin-user-token \ | jq --raw-output .data \ | base64 --decode )" @@ -231,7 +231,7 @@ browser --> edge-gateway ```sh kumactl config control-planes add \ --name {{ kuma-demo }} \ - --address http://localhost:25681 \ + --address http://127.0.0.1:25681 \ --auth-type tokens \ --auth-conf "token=${{ KUMA_DEMO_ADMIN_TOKEN }}" \ --skip-verify @@ -407,7 +407,7 @@ This section explains how to start the `kv` service, which mimics key/value stor The output should show a single service, `kv`, with the status `Online`. - You can also open the [{{ Kuma }} GUI]({{ docs }}/production/gui/) at . Look for the `kv` service, and verify that its state is `Available`. + You can also open the [{{ Kuma }} GUI]({{ docs }}/production/gui/) at . Look for the `kv` service, and verify that its state is `Available`. ### Demo Application @@ -497,7 +497,7 @@ The steps are the same as those explained earlier, with only the names changed. 4. {% if page.edition and page.edition == "kuma" %}{:.margin-top-1-5-rem}{% endif %}**Verify the application** - Open in your browser and use the demo application to increment the counter. The demo application is now fully set up and running. + Open in your browser and use the demo application to increment the counter. The demo application is now fully set up and running. ## Introduction to zero-trust security @@ -517,7 +517,7 @@ mtls: type: builtin' | kumactl apply --file - ``` -After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly, meaning will no longer work. This happens for two reasons: +After enabling mTLS, all traffic is **encrypted and secure**. However, you can no longer access the `demo-app` directly, meaning will no longer work. This happens for two reasons: 1. When mTLS is enabled, {{ Kuma }} doesn’t create traffic permissions by default. This means no traffic will flow until you define a {{ MeshTrafficPermission }} policy to allow `demo-app` to communicate with `kv`. @@ -629,7 +629,7 @@ The built-in gateway works like the data plane proxy for a regular service, but This sets up the gateway to listen on port `8080` using the HTTP protocol and adds a tag (`port: http-8080`) to identify this listener in routing policies. - You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. + You can test the gateway by visiting . You should see a message saying no routes match this {{ MeshGateway }}. This means the gateway is running, but no routes are set up yet to handle traffic. 5. **Create a route to connect the gateway to `demo-app`** @@ -661,7 +661,7 @@ The built-in gateway works like the data plane proxy for a regular service, but This route connects the gateway and its listener (`port: http-8080`) to the `demo-app` service. It forwards any requests with the path prefix `/` to `demo-app`. - After setting up this route, the gateway will try to send traffic to `demo-app`. However, if you test it by visiting , you’ll see: + After setting up this route, the gateway will try to send traffic to `demo-app`. However, if you test it by visiting , you’ll see: ``` RBAC: access denied @@ -692,7 +692,7 @@ The built-in gateway works like the data plane proxy for a regular service, but action: Allow' | kumactl apply --file - ``` - This policy allows traffic from the gateway to `demo-app`. After applying it, you can access , and the traffic will reach the `demo-app` service successfully. + This policy allows traffic from the gateway to `demo-app`. After applying it, you can access , and the traffic will reach the `demo-app` service successfully. ## Cleanup From af271e79fc7ac2f314f491fc4e8e712feb04b237 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 29 Nov 2024 11:45:19 +0100 Subject: [PATCH 39/40] remove installation steps from transparent proxy universal docs Signed-off-by: Bart Smykla --- .../networking/transparent-proxy/universal.md | 262 +----------------- 1 file changed, 15 insertions(+), 247 deletions(-) diff --git a/app/_src/networking/transparent-proxy/universal.md b/app/_src/networking/transparent-proxy/universal.md index 1f7f488c0..6e6e132d6 100644 --- a/app/_src/networking/transparent-proxy/universal.md +++ b/app/_src/networking/transparent-proxy/universal.md @@ -7,6 +7,11 @@ content_type: how-to {% assign Kuma = site.mesh_product_name %} {% assign tproxy = site.data.tproxy %} +{% capture Warning %}{% if page.edition and page.edition != "kuma" %}**Warning:** {% endif %}{% endcapture %} +{% capture Important %}{% if page.edition and page.edition != "kuma" %}**Important:** {% endif %}{% endcapture %} +{% capture Note %}{% if page.edition and page.edition != "kuma" %}**Note:** {% endif %}{% endcapture %} +{% capture brbr %}{% if page.edition and page.edition != "kuma" %}

{% endif %}{% endcapture %} + Using the transparent proxy in Universal mode makes setup easier and enables features that wouldn’t be possible otherwise. Key benefits include: - **Simplified `Dataplane` resources**: You can skip the `networking.outbound` section, so you don’t have to list each service your application connects to manually. @@ -24,243 +29,6 @@ Using the transparent proxy in Universal mode makes setup easier and enables fea ## Installation -Here are the steps to set up a transparent proxy for your service. Once set up, your service will run with a transparent proxy, giving you access to {{ Kuma }}'s features like traffic control, observability, and security. - -Before you start, check the prerequisites below and adjust the settings for your environment, including IP addresses, custom ports, and DNS configurations. - -### Prerequisites - -{%- capture control-plane-and-service-network-accessibility-warning %} -{% warning %} -In a basic setup, the control plane **should not** be deployed in the same environment as the transparent proxy. This is because the transparent proxy redirects **all** traffic to `kuma-dp` (unless excluded), including traffic meant for the control plane. -{% endwarning %} -{%- endcapture %} - -{%- capture control-plane-and-service-network-accessibility-tip %} -{% tip %} -For deployment instructions, see [Deploy a single-zone control plane]({{ docs }}/production/cp-deployment/single-zone/). -{% endtip %} -{%- endcapture %} - -{%- capture data-plane-proxy-token-tip %} -{% tip %} -For instructions on generating this token, refer to the [Data plane proxy token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) section in the [Authentication with the data plane proxy]({{ docs }}/production/secure-deployment/dp-auth/#authentication-with-the-data-plane-proxy) documentation. -{% endtip %} -{%- endcapture %} - -{%- capture binary-availability-tip %} -{% tip %} -To get the required binaries, see [Install Kuma]({{ docs }}/introduction/install-kuma/). -{% endtip %} -{% endcapture -%} - -1. **Control plane deployment and network accessibility**: Ensure {{ Kuma }}'s control plane is already deployed and accessible from the service via an IP address or DNS name. Adapt the steps below to reflect the correct address for your setup. - - {{ control-plane-and-service-network-accessibility-warning | indent }} - - {{ control-plane-and-service-network-accessibility-tip | indent }} - -2. **Service accessibility**: Ensure the environment with the transparent proxy and service is reachable by other services in the mesh via IP or DNS. Adjust the setup steps to match the appropriate address where the service is accessible. - -3. **Data plane proxy token**: Place the data plane proxy token at `/kuma/example-server-token` (or adjust the steps if stored elsewhere). - - {{ data-plane-proxy-token-tip | indent }} - -4. **Binary availability**: Ensure `kuma-dp`, `envoy`, and `coredns` binaries are accessible in `/usr/local/bin/`, and `kumactl` is in the system’s `PATH`. Adjust any subsequent commands if the binaries are located elsewhere. - - {{ binary-availability-tip | indent }} - -### Step 1: Create a dedicated user for kuma-dp - -For proper functionality, the service must run under a different user than the one designated for running `kuma-dp`. If both the service and `kuma-dp` are run by the same user, the transparent proxy will not work correctly, causing service traffic (inbound and outbound) to fail. To create a dedicated user for `kuma-dp`, use the following command: - -```sh -useradd -u {{ tproxy.defaults.kuma-dp.username }} -U {{ tproxy.defaults.kuma-dp.username }} -``` - -{% warning %} -In some Linux distributions, the `useradd` command may not be available. In such cases, follow the specific guidelines for your system to manually create a user with a `UID` of `{{ tproxy.defaults.kuma-dp.uid }}` and the username `{{ tproxy.defaults.kuma-dp.username }}`. -{% endwarning %} - - -### Step 2: Prepare the Dataplane resource - - -In transparent proxy mode, configure your `Dataplane` resource without the `networking.outbound` section. Instead, use `networking.transparentProxying` for handling traffic redirection. Here’s an example: - -If your `/kuma/example-server-dataplane.yaml` looks like this: - -```yaml -type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: example-server - outbound: - - port: 6379 - tags: - kuma.io/service: redis -``` - -After updating it for transparent proxy, it should look like this: - -```yaml -type: Dataplane -mesh: default -name: {% raw %}{{ name }}{% endraw %} -networking: - address: {% raw %}{{ address }}{% endraw %} - inbound: - - port: {% raw %}{{ port }}{% endraw %} - tags: - kuma.io/service: example-server - transparentProxying: - redirectPortInbound: {{ tproxy.defaults.redirect.inbound.port }} - redirectPortOutbound: {{ tproxy.defaults.redirect.outbound.port }} -``` - -#### Redirect ports - -In this example, `{{ tproxy.defaults.redirect.inbound.port }}` and `{{ tproxy.defaults.redirect.outbound.port }}` are the default ports for inbound and outbound traffic redirection. You can change these ports in the transparent proxy configuration during installation (`redirect.inbound.port` and `redirect.outbound.port`). For more details, see the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). - -{% warning %} -**Important:** If you use different ports, be sure to update all related configurations and steps to match the new values. -{% endwarning %} - -#### Using variables in your configuration - -The placeholders `{% raw %}{{ name }}{% endraw %}`, `{% raw %}{{ address }}{% endraw %}`, and `{% raw %}{{ port }}{% endraw %}` are [Mustache templates](http://mustache.github.io/mustache.5.html), which will be dynamically filled using values passed via `--dataplane-var` CLI flags in a later step. - -In practice, if these values are static, you can simply hard-code them in your configuration. This feature is designed to allow more flexible and reusable resources, making it easier to dynamically adjust values when starting `kuma-dp`. - -#### More resources - -For additional information on setting up the `Dataplane` resource, refer to the [Data Plane on Universal]({{ docs }}/production/dp-config/dpp-on-universal/#data-plane-on-universal) documentation. - -### Step 3: Start the service - -The service can be started in various ways depending on your environment and requirements. To keep this instruction simple, we’ll use Python 3’s built-in HTTP server. This server will listen on port `8080`, with both [STDOUT](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) and [STDERR](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) redirected to a `service.log` file in the current directory, running in the background. - -{% danger %} -**Remember that** the service must run under a **different** user than the one designated for `kuma-dp`. In the example below, the service will run as the user you're currently logged in as. **Ensure** that this is not the same user assigned to the `kuma-dp`. -{% enddanger %} - -To start the service: - -```sh -python3 -m http.server 8080 > service.log 2>&1 & -``` - -### Step 4: Start the kuma-dp - -If you are using `systemd` to manage processes, you can refer to the [Systemd documentation]({{ docs }}/production/cp-deployment/systemd/) for an example of a `systemd` resource that can be customized to run `kuma-dp` in your environment. - -Alternatively, if you're starting `kuma-dp` using a script or another form of automation, you can use `runuser` to run the process as the `{{ tproxy.defaults.kuma-dp.username }}` user. Below is an example of how to start `kuma-dp` with the necessary parameters: - -```sh -# Set the Control Plane address (IP or DNS) accessible by this environment -export CP_ADDRESS="..." - -# Set the Data Plane address (IP or DNS) for the current environment, accessible by -# other services -export DP_ADDRESS="..." - -runuser -u {{ tproxy.defaults.kuma-dp.username }} -- \ - /usr/local/bin/kuma-dp run \ - --cp-address="https://$CP_ADDRESS:5678" \ - --dataplane-token-file="/kuma/example-server-token" \ - --dataplane-file="/kuma/example-server-dataplane.yaml" \ - --dataplane-var="name=example-server-dataplane" \ - --dataplane-var="address=$DP_ADDRESS" \ - --dataplane-var="port=8080" \ - --binary-path="/usr/local/bin/envoy" \ - --dns-coredns-path="/usr/local/bin/coredns" -``` - -This command runs `kuma-dp` under the `{{ tproxy.defaults.kuma-dp.username }}` user, connects it to the control plane, and configures it with the necessary settings for the example server. Adjust the paths and values as needed for your specific setup. - -### Step 5: Install the transparent proxy - -Before proceeding with this step, please keep the following in mind: - -{% warning %} -`kumactl` will return an error if you attempt to install the transparent proxy without `root` privileges. Ensure that you run the command as `root`. -{% endwarning %} - -{% warning %} -Once the transparent proxy is installed, all traffic configured for redirection will be immediately routed to `kuma-dp`. Therefore, it's important to start `kuma-dp` **before** installing the transparent proxy. If `kuma-dp` is not running, redirected traffic will be dropped, leading to a potential loss of connectivity (including SSH connections if port `22` hasn't been excluded). - -We strongly recommend starting `kuma-dp` **before** installing the transparent proxy. However, if you choose to install the transparent proxy first, make sure to exclude SSH traffic, for example by configuring `redirect.inbound.excludePorts` with `--exclude-inbound-ports` flag: - -```sh -kumactl install transparent-proxy --redirect-dns --exclude-inbound-ports "22" -``` -{% endwarning %} - -{% danger %} -The transparent proxy **must** be configured to use **the same** user as the one running the `kuma-dp` process to function properly. -{% enddanger %} - -{% danger %} -The following command **will modify** the host's `iptables` rules. If your environment already has existing `iptables` rules, ensure that the changes made by `kumactl` are compatible with your setup. You can check compatibility by running the command in dry-run mode using the `--dry-run` flag. -{% enddanger %} - -To install the transparent proxy in your environment, run the following command: - -```sh -kumactl install transparent-proxy --redirect-dns -``` - -This will result in the following: - -- The transparent proxy will be set up to use the `{{ tproxy.defaults.kuma-dp.username }}` user as the designated user for running the `kuma-dp` process. - - {% capture default-kuma-dp-user-lookup-tip %} - {% tip %} - By default, `kumactl` searches for a user with UID `{{ tproxy.defaults.kuma-dp.uid }}` or the username `{{ tproxy.defaults.kuma-dp.username }}`. If you prefer to use a custom username or UID, you can specify it using the `--kuma-dp-user` flag. If the specified user cannot be found, the installation process will fail with an error. - {% endtip %} - {% endcapture %} - {{ default-kuma-dp-user-lookup-tip | indent }} - -- All **incoming traffic** will be redirected to `kuma-dp` on port `{{ tproxy.defaults.redirect.inbound.port }}`. - - {% capture default-redirect-port-inbound-tip %} - {% tip %} - Port `{{ tproxy.defaults.redirect.inbound.port }}` is the default for redirecting incoming traffic. If you used a different port in your `Dataplane` resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the `redirect.inbound.port` setting during installation, for example by using the `--redirect-inbound-port` flag. - {% endtip %} - {% endcapture %} - {{ default-redirect-port-inbound-tip | indent }} - -- All **outgoing traffic** will be redirected to `kuma-dp` on default port `{{ tproxy.defaults.redirect.outbound.port }}`. - - {% capture default-redirect-port-outbound-tip %} - {% tip %} - Port `{{ tproxy.defaults.redirect.outbound.port }}` is the default used for redirecting outgoing traffic. If you used a different port in your `Dataplane` resource definition, ensure it aligns with the transparent proxy configuration. To update it, modify the `redirect.outbound.port` setting during installation, for example by using the `--redirect-outbound-port` flag. - {% endtip %} - {% endcapture %} - {{ default-redirect-port-outbound-tip | indent }} - -- DNS traffic directed to the DNS servers configured in `{{ tproxy.defaults.resolv.conf.path }}` will be redirected to the `coredns` managed by `kuma-dp` on port `{{ tproxy.defaults.redirect.dns.port }}`. - - {% capture default-redirect-port-dns-tip %} - {% tip %} - Port `{{ tproxy.defaults.redirect.dns.port }}` is the default used for redirecting DNS traffic. If you wish to modify this port, it is crucial to ensure consistency between the transparent proxy and `kuma-dp`. In this case, you must update the `kuma-dp run` command to include the `--dns-coredns-port` flag with the desired custom port. To adjust it for the transparent proxy, modify the `redirect.dns.port` setting during installation, for example by using the `--redirect-dns-port` flag. - {% endtip %} - {% endcapture %} - {{ default-redirect-port-dns-tip | indent }} - - {% capture resolv-conf-tip %} - {% tip %} - `{{ tproxy.defaults.resolv.conf.path }}` is the file used by default to parse DNS servers for redirecting DNS traffic through the transparent proxy. This file is relevant only if you opt to redirect DNS traffic specifically to the DNS servers listed within it (for example, by using the `--redirect-dns` flag during installation). If you're redirecting **all** DNS traffic (for example, by using the `--redirect-all-dns-traffic` flag), this path becomes irrelevant. - - **We strongly recommend against** changing this path. However, if your environment uses a different file to specify DNS servers (which must follow the same format as `{{ tproxy.defaults.resolv.conf.path }}`), you can adjust it by modifying the `redirect.dns.resolvConfigPath` setting during installation. This can be done, for example, using the `KUMA_TRANSPARENT_PROXY_REDIRECT_DNS_RESOLV_CONFIG_PATH` environment variable. - {% endtip %} - {% endcapture %} - {{ resolv-conf-tip | indent }} ## Upgrading @@ -269,15 +37,15 @@ The core `iptables` rules applied by {{ Kuma }}'s transparent proxy rarely chang ### Step 1: Cleanup existing iptables rules (conditional) {% warning %} -If you're upgrading from {{ Kuma }} version 2.9 or later, and you have **not** manually disabled the automatic addition of comments by setting `comments.disabled` to `true` in the transparent proxy configuration, **this step is unnecessary**. - +{{ Important }}If you're upgrading from {{ Kuma }} version 2.9 or later, and you have **not** manually disabled the automatic addition of comments by setting `comments.disabled` to `true` in the transparent proxy configuration, **this step is unnecessary**. +{{ brbr }} Starting with {{ Kuma }} 2.9, all `iptables` rules are tagged with comments, allowing {{ Kuma }} to track rule ownership. This enables `kumactl` to automatically clean up any existing `iptables` rules or custom chains created by previous versions of the transparent proxy. This process runs automatically at the start of the installation, eliminating the need for any manual cleanup beforehand. {% endwarning %} To manually remove existing `iptables` rules, you can either restart the host (if the rules were not persisted using system start-up scripts or `firewalld`), or run the following commands: {% danger %} -These commands will remove **all** `iptables` rules and **all** custom chains in the specified tables, including those created by {{ Kuma }} as well as any other applications or services. +{{ Warning }}These commands will remove **all** `iptables` rules and **all** custom chains in the specified tables, including those created by {{ Kuma }} as well as any other applications or services. {% enddanger %} ```sh @@ -314,7 +82,7 @@ The default configuration works well for most scenarios, but there are cases whe In Universal mode, {{ Kuma }} there are three methods to adjust the configuration. Each can be used on its own or combined with others if needed. {% warning %} -It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) section to see what the final configuration will look like based on the priority of each setting. +{{ Important }}It’s best to stick to one method whenever possible. Using more than one can make things more complicated and harder to troubleshoot, as it may not be clear where each setting comes from. If you need to combine methods, check the [**Order of Precedence**](#order-of-precedence) section to see what the final configuration will look like based on the priority of each setting. {% endwarning %} @@ -324,11 +92,11 @@ It’s best to stick to one method whenever possible. Using more than one can ma You can provide the configuration in either `YAML` or `JSON` format by using the `--config` or `--config-file` flags. {% tip %} -For the configuration schema in YAML format, refer to the [Schema]({{ docs }}/reference/transparent-proxy-configuration/#schema) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). +{{ Note }}For the configuration schema in YAML format, refer to the [Schema]({{ docs }}/reference/transparent-proxy-configuration/#schema) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} {% tip %} -For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs. +{{ Note }}For simplicity, the following examples use YAML format, but you can easily convert them to JSON if preferred. Both formats work exactly the same, so feel free to choose the one that best suits your needs. {% endtip %} Below are examples of using these flags in different ways: @@ -386,7 +154,7 @@ KUMA_TRANSPARENT_PROXY_IP_FAMILY_MODE="ipv4" kumactl install transparent-proxy ``` {% tip %} -To see all available environment variables, visit the [Environment Variables]({{ docs }}/reference/transparent-proxy-configuration/#environment-variables) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). +{{ Note }}To see all available environment variables, visit the [Environment Variables]({{ docs }}/reference/transparent-proxy-configuration/#environment-variables) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} @@ -400,7 +168,7 @@ kumactl install transparent-proxy --kuma-dp-user dataplane --verbose ``` {% warning %} -The following settings cannot be modified directly via CLI flags (corresponding flags are not available): +{{ Important }}The following settings cannot be modified directly via CLI flags (corresponding flags are not available): - `redirect.dns.resolvConfigPath` - `redirect.inbound.includePorts` @@ -410,10 +178,10 @@ The following settings cannot be modified directly via CLI flags (corresponding - `ebpf.instanceIPEnvVarName` - `log.level` - `cniMode` - {% endwarning %} +{% endwarning %} {% tip %} -To see all available CLI flags, visit the [CLI Flags]({{ docs }}/reference/transparent-proxy-configuration/#cli-flags) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). +{{ Note }}To see all available CLI flags, visit the [CLI Flags]({{ docs }}/reference/transparent-proxy-configuration/#cli-flags) section in the [Transparent Proxy Configuration Reference]({{ docs }}/reference/transparent-proxy-configuration/). {% endtip %} From 63277ecbba0453fbdf6b1b77b2ba890e9b215191 Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Fri, 29 Nov 2024 12:00:20 +0100 Subject: [PATCH 40/40] make vale happy Signed-off-by: Bart Smykla --- .github/styles/config/vocabularies/Base/accept.txt | 3 ++- ...excluding-traffic-from-transparent-proxy-redirection.md | 2 +- app/_src/quickstart/docker-demo.md | 7 ++++--- app/_src/reference/kubernetes-annotations.md | 2 ++ 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/styles/config/vocabularies/Base/accept.txt b/.github/styles/config/vocabularies/Base/accept.txt index 189dd43b3..2749bf7e5 100644 --- a/.github/styles/config/vocabularies/Base/accept.txt +++ b/.github/styles/config/vocabularies/Base/accept.txt @@ -64,7 +64,7 @@ GKE|gke Goroutine Grafana grpcs? -hardcoded +hardcod(?:ing|ed) hostnames? httpbin HTTPie @@ -165,6 +165,7 @@ txt UIDs? uncheck uncomment +unencrypted Unicode unix unsecure diff --git a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md index ba722e909..607caf3c0 100644 --- a/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md +++ b/app/_src/guides/excluding-traffic-from-transparent-proxy-redirection.md @@ -55,7 +55,7 @@ Use this guide to control which traffic the transparent proxy intercepts and whi - To generate a data plane proxy token (needed to authorize data plane proxies), refer to [Data Plane Proxy Token]({{ docs }}/production/secure-deployment/dp-auth/#data-plane-proxy-token) documentation. - - To set up your service environment and start the data plane proxy, follow the steps in the [Installing]({{ docs }}/networking/transparent-proxy/universal/#installation) section of the [Transparent Proxy on Universal]({{ docs }}/networking/transparent-proxy/universal/) documentation up to [Step 5: Install the Transparent Proxy]({{ docs }}/networking/transparent-proxy/universal/#step-5-install-the-transparent-proxy). + - To set up your service environment and start the data plane proxy, follow the steps in the quickstart guide. {% endtab %} {% endtabs %} {% endcapture %} diff --git a/app/_src/quickstart/docker-demo.md b/app/_src/quickstart/docker-demo.md index 37d234687..4e5433373 100644 --- a/app/_src/quickstart/docker-demo.md +++ b/app/_src/quickstart/docker-demo.md @@ -41,10 +41,8 @@ You'll set up and secure a simple demo application to explore how {{ Kuma }} wor - `demo-app`: A web application that lets you increment a numeric counter. - `kv`: A data store that keeps the counter's value. + {% mermaid %} ---- -title: service graph of the demo app ---- flowchart LR browser(browser) @@ -57,6 +55,7 @@ edge-gateway --> demo-app demo-app --> kv browser --> edge-gateway {% endmermaid %} + ## Prerequisites @@ -295,7 +294,9 @@ useradd --uid {{ tproxy.defaults.kuma-dp.uid }} --user-group {{ kuma-data-plane- {% endwarning %} {% endcapture %} + ### Key/Value Store + This section explains how to start the `kv` service, which mimics key/value store database. diff --git a/app/_src/reference/kubernetes-annotations.md b/app/_src/reference/kubernetes-annotations.md index bc34a3f80..fdc706af1 100644 --- a/app/_src/reference/kubernetes-annotations.md +++ b/app/_src/reference/kubernetes-annotations.md @@ -554,7 +554,9 @@ spec: When transparent proxy is installed with eBPF mode, you can disable it for particular workloads if necessary. + {% capture tproxy-ebpf-link %}/docs/{{ page.release }}/{% if_version lte:2.8.x %}production/dp-config/transparent-proxying/{% endif_version %}{% if_version gte:2.9.x %}networking/transparent-proxy/introduction/{% endif_version %}#transparent-proxy-with-ebpf-experimental{% endcapture %} + For more details see the [transparent proxying with eBPF docs]({{ tproxy-ebpf-link }}).