# Istio: sidecars, and the two repositories that are stable

> A service mesh that puts an Envoy sidecar next every service, a control plane that translates your rules into proxy config, and now a Rust proxy called ztunnel for sidecar-free workloads. The stability note in the repository is the part to read first.

**istio/istio** — Connect, secure, control, and observe services.

- Repository: https://github.com/istio/istio
- Website: https://istio.io
- Stars: 38,420 · Forks: 8,381
- Language: Go
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/istio-istio

## The sidecar is the unit, and the mesh is not an overlay network

Istio describes itself as a service mesh that layers transparently onto existing distributed applications, providing load balancing, service-to-service authentication and monitoring with few or no changes to the service code. The mechanism is Envoy. Each microservice gets sidecar proxies handling ingress and egress, both between services in the cluster and out to external services, and those proxies are where discovery, layer-7 routing, circuit breakers, policy enforcement and telemetry recording happen. One clarification in the project's own text is worth keeping, because it is the thing people get wrong: the service mesh is not an overlay network. It does not draw a new network across your cluster. It changes how the services already in your application talk to each other over the network the platform provides. Which also fixes the cost model. The overhead is per service, so a mesh earns its keep when you run enough services that hand-rolled policy in each one is the bigger risk.

## Istiod translates your rules, you never write proxy config

`istiod` is the control plane, and its job list is short: service discovery, configuration and certificate management. The directory that does the work is `pilot/`, and its description in the project is the most useful sentence in the repository for anyone writing configuration. It contains platform-specific code that populates an abstract service model, dynamically reconfigures the proxies when the application topology changes, and translates routing rules into proxy specific configuration. Hold on to that last clause. What you write is not proxy configuration. It is input to a translation step, and what Envoy runs is the output. The consequence shows up the first time a route behaves oddly: you cannot debug it by reading a file on the proxy, because the file the proxy reads was generated by the control plane from a model that has no one-to-one representation in what you wrote. The model and the translation have to be read together.

## Ambient mode puts a Rust proxy where the sidecar used to be

There are two data plane shapes now, and choosing between them is a real decision. The sidecar arrangement is the older one, an Envoy proxy beside every microservice. Ambient mode does without it: `ztunnel` is a lightweight data plane proxy written in Rust, used in Ambient mesh mode to provide secure connectivity and observability for workloads without sidecar proxies. Its implementation lives in its own repository, `istio/ztunnel`, separate from `istio/proxy`, which holds the Envoy filters extending the proxy with authentication, authorization and telemetry collection. That split is the shape of the project, not a packaging detail. On the sidecar path you extend a C++ proxy with filters. On the ambient path you run a separate Rust binary that is not a proxy you configure. Both appear in the samples tree, with `ambient-argo` next to sidecar-oriented entries like `helloworld` and `bookinfo`, so the choice you make in a proof of concept is visible in the examples too.

## Only two of the six repositories promise a stable interface

The project is spread across six GitHub repositories, and one note decides how you are allowed to consume it. Only `istio/api` and `istio/client-go` expose stable interfaces intended for direct usage as libraries. `istio/api` holds component-level APIs and common configuration formats, `istio/client-go` holds auto-generated Kubernetes clients for interacting with Istio resources programmatically, and the rest, `istio/istio` included, is code you can read but not depend on. The main repository contains `istioctl/`, `pilot/` and `security/`, and its default branch is `master`. Write a controller that imports Go packages from `istio.io/istio` and you have bound yourself to a moving branch with no compatibility promise attached. The supported route is the generated client or the API types. That distinction is cheap to observe once and expensive to discover after you have built on top of the wrong one.

## The Makefile is a copy, and BUILD_WITH_CONTAINER is the shortcut

Building from source opens with a warning. The top of the Makefile says not to edit it, because the file is probably a copy whose original lives in the `istio/common-files` repository, and a change belongs there followed by `make update-common` back in this repository. There is a `Makefile.overrides.mk` included optionally, which is the supported place for local changes. The second decision is how to build at all. `BUILD_WITH_CONTAINER` defaults to 0, and setting it to 1 makes make and docker the only dependencies, with every target forwarded through `./common/scripts/run.sh` and `make shell` dropping you into a bash shell inside that script. Leave it at 0 and the comment says plainly that you have to work out all the tools your environment needs. The Go side is not light either:

```go
module istio.io/istio

go 1.27.0
```

A toolchain at 1.27.0 plus pinned dependencies including the Envoy xDS libraries, the CNI plugins and `cel-go` is what a local build is signing up for.

## Three patch releases on one day is the support model

Three patch releases were published on the same date, 2026-09-21: 1.31.1, 1.30.5 and 1.29.8. That is not three fixes landing at once. It is three maintenance lines receiving patches on the same day, which tells you the project runs parallel minor versions and expects you to choose one. A `RELEASE_BRANCHES.md` file at the top of the repository is where that policy lives, and the README says nothing about how long a line is supported or how to move between lines, so that file is the one to read before you commit to a version. Choose badly and you are the person maintaining a line nobody patches. The same pattern shows in the issue tracker, where every issue carries an epic, a milestone of 0.1, 0.2 and onward or the literal string 'Nebulous Future', and a priority of P0, P1, P2 or above P2, with P0 meaning the milestone is not achieved until the issue closes. A workable triage system, and it also means your own issue gets no date.

## operator/, manifests/ and samples/ are three doors the README leaves shut

Count the ways into the top level and the shape of the repository becomes clear. There is `operator/`, `manifests/`, `cni/`, `bin/`, `release/`, `releasenotes/`, `prow/`, `architecture/`, `docker/`, `tools/` and `tests/`, and then a `samples/` directory with more than twenty entries, running from `helloworld` and `bookinfo` through `extauthz`, `mtls-echo`, `ratelimit`, `multicluster`, `open-telemetry` and `proxy-coredump`. Not one of those directories is explained in the README. What the README does instead is point you at istio.io for using the product, at GitHub Discussions for questions, and at a wiki for a development environment, project conventions and performance advice. So the repository is a map of where the code sits, not a manual for deploying it. Someone looking for the install step finds a documentation site, an operator directory and a samples tree, and the distance between those three is where a first afternoon goes. The last push to the master branch was on 2026-09-29, so none of this is a stale checkout.

## Conclusion

Istio fits a cluster running many services that call each other and where one policy has to hold everywhere, and it fits a team willing to work through a control plane rather than a config file. It does not fit a codebase that wants to import its Go packages, because only istio/api and istio/client-go carry a stability promise. Before you commit, open RELEASE_BRANCHES.md and pick the minor line you will ride, since three lines were patched on 2026-09-21 and nothing in the README tells you which one is still supported.

## FAQ

### What is Istio used for?

It is a service mesh that layers onto existing distributed applications to give load balancing, service-to-service authentication and monitoring with few or no service code changes. Each service gets an Envoy sidecar that handles traffic to other services and to external ones.

### What is an Istio mesh?

It is the set of sidecar proxies forming a secure microservice mesh, providing discovery, layer-7 routing, circuit breakers, policy enforcement and telemetry. The project is explicit that it is not an overlay network but a way to change how services talk over the network the platform already provides.

### What does Istio do in Kubernetes?

The control plane provides an abstraction layer over the underlying cluster management platform, handling service discovery, configuration and certificate management. Code in the pilot/ directory populates an abstract service model and translates routing rules into proxy specific configuration.

### how to install istio

The README gives no install command and sends you to istio.io instead. The repository holds the pieces a deployment uses, with operator/, manifests/, cni/ and bin/ at the top level and istioctl/ holding the command line utility's code.

### how does istio work

Envoy sidecars carry the traffic, ztunnel covers workloads that have no sidecar in Ambient mode, and istiod sits above both as the control plane for discovery, configuration and certificates. Configuration you write is translated by the control plane into proxy specific config rather than read directly by the proxy.

## Sources

- [Official documentation](https://istio.io)
- [Official README](https://github.com/istio/istio#readme)
- [Project repository](https://github.com/istio/istio)
- [Release notes](https://github.com/istio/istio/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/istio-istio