{"id":14470635,"url":"https://github.com/istio/ztunnel","last_synced_at":"2025-04-05T15:09:16.029Z","repository":{"id":61818997,"uuid":"554381526","full_name":"istio/ztunnel","owner":"istio","description":"The `ztunnel` component of ambient mesh","archived":false,"fork":false,"pushed_at":"2024-04-13T04:39:44.000Z","size":26388,"stargazers_count":240,"open_issues_count":89,"forks_count":84,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-04-13T21:47:03.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/istio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":".github/SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-10-19T18:09:13.000Z","updated_at":"2024-04-15T09:59:14.810Z","dependencies_parsed_at":"2023-02-18T02:01:13.334Z","dependency_job_id":"cc0363cf-5d23-4ff8-8c12-c94d702abca9","html_url":"https://github.com/istio/ztunnel","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istio%2Fztunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istio%2Fztunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istio%2Fztunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istio%2Fztunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/istio","download_url":"https://codeload.github.com/istio/ztunnel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353746,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-02T04:01:40.069Z","updated_at":"2025-04-05T15:09:16.016Z","avatar_url":"https://github.com/istio.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Ztunnel\n\nZtunnel provides an implementation of the ztunnel component of\n[ambient mesh](https://istio.io/latest/blog/2022/introducing-ambient-mesh/).\n\n## Feature Scope\n\nZtunnel is intended to be a purpose built implementation of the node proxy in [ambient mesh](https://istio.io/latest/blog/2022/introducing-ambient-mesh/).\nPart of the goals of this included keeping a narrow feature set, implementing only the bare minimum requirements for ambient.\nThis ensures the project remains simple and high performance.\n\nExplicitly out of scope for ztunnel include:\n* Terminating user HTTP traffic\n* Terminating user HTTP traffic (its worth repeating)\n* Generic extensibility such as `ext_authz`, WASM, linked-in extensions, Lua, etc.\n\nIn general, ztunnel does not aim to be a generic extensible proxy; Envoy is better suited for that task.\nIf a feature is not directly used to implement the node proxy component in ambient mesh, it is unlikely to be accepted.\n\nThe details of architecture is [here](./ARCHITECTURE.md).\n\n## Building\n\nPlease use the same Rust version as the [`build-tools`](https://github.com/istio/tools/tree/master/docker/build-tools) image.\nYou can determine the version that the `build-tools` image uses by running the below command:\n\n```shell\n$ BUILD_WITH_CONTAINER=1 make rust-version\n```\n\n### TLS/Crypto provider\n\nZtunnel's TLS is built on [rustls](https://github.com/rustls/rustls).\n\nRustls has support for plugging in various crypto providers to meet various needs (compliance, performance, etc).\n\n| Name                                               | How To Enable                                  |\n|----------------------------------------------------|------------------------------------------------|\n| [aws-lc]https://github.com/aws/aws-lc-rs)          | Default (or `--features tls-aws-lc`)           |\n| [ring](https://github.com/briansmith/ring/)        | `--features tls-ring --no-default-features`    |\n| [boring](https://github.com/cloudflare/boring)     | `--features tls-boring --no-default-features`  |\n| [openssl](https://github.com/tofay/rustls-openssl) | `--features tls-openssl --no-default-features` |\n\nIn all options, only TLS 1.3 with cipher suites `TLS13_AES_256_GCM_SHA384` and `TLS13_AES_128_GCM_SHA256` is used.\n\n#### `boring` FIPS\n\nWith the `boring` option, the FIPS version is used.\nPlease note this only implies the specific version of the library is used; FIPS compliance requires more than *just* using a specific library.\n\nFIPS has\n[strict requirements](https://csrc.nist.gov/CSRC/media/projects/cryptographic-module-validation-program/documents/security-policies/140sp4407.pdf)\nto ensure that compliance is granted only to the exact binary tested.\nFIPS compliance was [granted](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4407)\nto an old version of BoringSSL that was tested with `Clang 12.0.0`.\n\nGiven that FIPS support will always have special environmental build requirements, we currently we work around this by vendoring OS/arch specific FIPS-compliant binary builds of `boringssl` in [](vendor/boringssl-fips/)\n\nWe vendor FIPS boringssl binaries for\n\n- `linux/x86_64`\n- `linux/arm64`\n\nTo use these vendored libraries and build ztunnel for either of these OS/arch combos, for the moment you must manually edit\n[.cargo/config.toml](.cargo/config.toml) and change the values of BORING_BSSL_PATH and BORING_BSSL_INCLUDE_PATH under the `[env]` key to match the path to the vendored libraries for your platform, e.g:\n\n##### For linux/x86_64\n\n``` toml\nBORING_BSSL_FIPS_PATH = { value = \"vendor/boringssl-fips/linux_x86_64\", force = true, relative = true }\nBORING_BSSL_FIPS_INCLUDE_PATH = { value = \"vendor/boringssl-fips/include/\", force = true, relative = true }\n```\n\n##### For linux/arm64\n\n``` toml\nBORING_BSSL_FIPS_PATH = { value = \"vendor/boringssl-fips/linux_arm64\", force = true, relative = true }\nBORING_BSSL_FIPS_INCLUDE_PATH = { value = \"vendor/boringssl-fips/include/\", force = true, relative = true }\n```\n\nOnce that's done, you should be able to build:\n\n``` shell\ncargo build\n```\n\nThis manual twiddling of environment vars is not ideal but given that the alternative is prefixing `cargo build` with these envs on every `cargo build/run`, for now we have chosen to hardcode these in `config.toml` - that may be revisited in the future depending on local pain and/or evolving `boring` upstream build flows.\n\nNote that the Dockerfiles used to build these vendored `boringssl` builds may be found in the respective vendor directories, and can serve as a reference for the build environment needed to generate FIPS-compliant ztunnel builds.\n\nA release build with this option can be built with `TLS_MODE=boring ./scripts/release.sh`.\n\n## Development\n\nPlease refer to [this](./Development.md).\n\n## Metrics\n\nZtunnel exposes a variety of metrics, at varying levels of stability.  They are\naccessible by making an HTTP request to either \"/stats/prometheus\" or \"/metrics\" on port 15020.\n\n**Core** metrics are considered stable APIs.\n\n**Unstable** metrics may be changed. This includes removal, semantic changes, and label changes.\n\n### Core metrics\n\n#### Traffic metrics\n\n- Tcp Bytes Sent (`istio_tcp_sent_bytes_total`): This is a `COUNTER` which measures the size of total bytes sent during response in case of a TCP connection.\n- Tcp Bytes Received (`istio_tcp_received_bytes_total`): This is a `COUNTER` which measures the size of total bytes received during request in case of a TCP connection.\n- Tcp Connections Opened (`istio_tcp_connections_opened_total`): This is a `COUNTER` incremented for every opened connection.\n- Tcp Connections Closed (`istio_tcp_connections_closed_total`): This is a `COUNTER` incremented for every closed connection.\n\n#### Meta metrics\n\n- Istio build information (`istio_build`)\n\n### Unstable metrics\n\n#### DNS metrics\n\n- DNS Requests (`istio_dns_requests_total`)\n- DNS Upstream Requests (`istio_dns_upstream_requests_total`)\n- DNS Upstream Failures (`istio_dns_upstream_failures_total`)\n- DNS Upstream Request Duration (`istio_dns_upstream_request_duration_seconds`)\n- On Demand DNS Requests (`istio_on_demand_dns_total`)\n\n#### In-Pod metrics\n\n- Active proxy count (`istio_active_proxy_count_total`)\n- Pending proxy count (`istio_pending_proxy_count_total`)\n- Proxies started (`istio_proxies_started_total`)\n- Proxies stopped (`istio_proxies_stopped_total`)\n\n#### XDS metrics\n\n- XDS Connection terminations (`istio_xds_connection_terminations_total`)\n\n## Logging\n\nZtunnel exposes a variety of logs, both operational and \"access logs\".\n\nLogs are controlled by the `RUST_LOG` variable.\nThis can set all levels, or a specific target. For instance, `RUST_LOG=error,ztunnel::proxy=warn`.\nLogs can be emitted in JSON format with `LOG_FORMAT=json`.\nAccess logs are under the `access` target.\n\nAn example access log looks like (with newlines for readability; the real logs are on one line):\n\n```text\n2024-04-11T15:38:42.182974Z  INFO access: connection complete\n    src.addr=10.244.0.24:46238 src.workload=\"shell-6d8bcd654d-t88gp\" src.namespace=\"default\" src.identity=\"spiffe://cluster.local/ns/default/sa/default\"\n    dst.addr=10.244.0.42:15008 dst.hbone_addr=10.96.108.116:80 dst.service=\"echo.default.svc.cluster.local\"\n    direction=\"outbound\" bytes_sent=67 bytes_recv=490 duration=\"13ms\"\n```\n\nAccess logs are emitted upon _completion_ of each connection.\nLogs for connect _establishment_ are also logged (with less information) at `debug` level.\n\nCurrently, the access log format is considered unstable and subject to changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fistio%2Fztunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fistio%2Fztunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fistio%2Fztunnel/lists"}