istio/istio

Operator (manifest renderer)

Active contributors: zirain, hzxuzhonghu, keithmattix, costinm, ramaraochavali

Purpose

The "operator" is the install/render layer of Istio. Today it is a client-side library invoked through istioctl install, istioctl manifest generate, and istioctl upgrade. It takes an IstioOperator resource (plus profiles, Helm overlays, and --set flags) and renders the install manifest.

Historically there was also an in-cluster controller mode that reconciled an installed mesh; that was deprecated and removed (see Lore). The image gcr.io/istio-release/operator still ships for legacy users, but new installs go through istioctl install.

The on-disk root is operator/, originally merged from the standalone istio/operator repo on 2020-01-12.

Directory layout

operator/
├── README.md              # User-facing intro; cross-links to architecture/environments/operator.md
├── cmd/
│   └── mesh/              # The cobra commands wired into istioctl: install, upgrade, manifest, uninstall
│       ├── install.go
│       ├── manifest.go
│       ├── upgrade.go
│       └── uninstall.go
├── pkg/
│   ├── apis/              # IstioOperator types (Helm-values + KubernetesResourceSpec)
│   │   └── istio/v1alpha1/values_types.pb.go   # 6,300+ generated lines
│   ├── helm/              # Helm chart loading and value merging
│   ├── render/            # The actual manifest renderer
│   ├── manifest/          # Diff / apply / load helpers
│   ├── component/         # Per-component metadata
│   ├── values/            # Profile + overlay value merging
│   ├── tpath/             # Pathed YAML editing (used by --set)
│   ├── install/           # Apply manifests to a cluster
│   ├── uninstall/         # Removal helpers
│   ├── webhook/           # Mutating webhook helpers (validation hooks)
│   ├── version/           # Version probing
│   ├── util/              # Shared utilities
│   └── test/              # Integration test fixtures
├── version/
└── images/                # Image manifests used by tests

Key abstractions

Symbol	File	Role
`IstioOperator`	`operator/pkg/apis/istio/v1alpha1/values_types.pb.go`	The CR users author
`Renderer`	`operator/pkg/render/render.go`	Turns merged values + profile + charts into manifests
`Manifest`	`operator/pkg/manifest/`	Loaded / applied manifest representation
`ComponentSpec`	`operator/pkg/component/`	Per-component (Pilot, IngressGateway, etc.) metadata
`installCmd`, `manifestGenerateCmd`, `upgradeCmd`	`operator/cmd/mesh/*.go`	The CLI verbs

How it works

graph LR
    user[User input:<br/>-f overlay.yaml<br/>--set foo=bar<br/>--profile demo] --> merge[Profile + overlay merge<br/>operator/pkg/values]
    chart[manifests/charts] --> render[Render<br/>operator/pkg/render]
    profile[manifests/profiles<br/>default, demo, minimal,<br/>ambient, openshift, ...] --> merge
    merge --> render
    render --> manifest[Manifest<br/>operator/pkg/manifest]
    manifest -->|generate| stdout[Stdout YAML]
    manifest -->|install| diff[Diff against cluster]
    diff --> apply[Server-side apply<br/>operator/pkg/install]

Profiles

Profiles in manifests/profiles/:

default — sidecar mode, ingress gateway on, demo features off.
demo — everything on, larger resource requests, suitable for the bookinfo demo.
minimal — istiod only, no gateway.
empty — nothing; used as a base for --set-only installs.
remote — for joining a primary cluster from a secondary in multi-cluster.
external — for an external istiod controlling a remote dataplane cluster.
ambient — Ambient mode (ztunnel + istio-cni + istiod with Ambient flags).
openshift — OpenShift-specific overrides (SCC labels, etc.).
preview — opt-in preview features.

Profile YAML is just an IstioOperator overlay. Users pass --profile <name> to start from one, then -f and --set to layer on more.

Chart layout

The charts under manifests/charts/ are the actual Helm templates the renderer expands:

Chart	Component
`base/`	CRDs and cluster-scoped resources
`istio-control/istio-discovery/`	istiod
`gateway/`	A single gateway (Kubernetes Gateway API)
`gateways/istio-ingress/`	Classic istio-ingressgateway
`gateways/istio-egress/`	Classic istio-egressgateway (auto-derived from ingress)
`istio-cni/`	CNI DaemonSet
`ztunnel/`	Ztunnel DaemonSet

manifests/zzz_profile.yaml is a template-stub that every chart includes to consume profile defaults at render time.

Upgrade and revisions

istioctl upgrade and istioctl tag use the revision concept: each install is tagged with a revision label, and Kubernetes mutating webhooks include the revision in their selector. Operators can install a new revision side-by-side, switch the default tag, and redeploy workloads at their own pace.

Revision plumbing lives in pkg/revisions/ (consumed by the operator) and the tag command in istioctl/pkg/tag/.

Validation

The operator API has its own validation layer at operator/pkg/apis/istio/v1alpha1/validation/. It runs ahead of Helm rendering to give users early errors. The operator manifests are also re-validated after rendering by the istiod admission webhook (pkg/webhooks/validation/).

Integration points

Reads from: manifests/charts/, manifests/profiles/, the user-supplied YAML/CLI flags, and (for upgrade/diff) the live cluster.
Writes to: stdout for manifest generate, the Kubernetes API for install / upgrade. Never writes back to source files.
Used by: istioctl install, istioctl manifest generate, istioctl upgrade, istioctl uninstall. The cobra commands are registered in istioctl/cmd/root.go.

Entry points for modification

New profile → add a YAML under manifests/profiles/<name>.yaml. Add to manifests/charts/*/files/profile-<name>.yaml via make copy-templates.
New --set path → most paths are auto-derived from the IstioOperator schema. If you need a synthetic path, see operator/pkg/tpath/.
Chart edits → standard Helm; remember to run make gen-check to refresh derived files (the egress chart auto-syncs from ingress).
New component → add a ComponentSpec entry in operator/pkg/component/, a chart under manifests/charts/, and wire into the render pipeline.

Key source files

File	Purpose
`operator/cmd/mesh/install.go`	The install command
`operator/cmd/mesh/manifest.go`	manifest generate / diff
`operator/cmd/mesh/upgrade.go`	Upgrade flow
`operator/pkg/render/render.go`	Helm rendering
`operator/pkg/manifest/manifest.go`	Manifest representation
`operator/pkg/component/component.go`	Per-component metadata
`operator/pkg/values/values.go`	Profile + overlay merging
`operator/pkg/install/install.go`	Apply manifests to cluster
`manifests/zzz_profile.yaml`	Profile template stub used by every chart
`manifests/charts/UPDATING-CHARTS.md`	The doc to read before changing charts