Skip to content
Istio operator provides user friendly options to operate the Istio service mesh
Go Shell Makefile
Branch: master
Clone or download
ostromart and istio-testing Move gateway and coredns enablement in sample config (#588)
* Move gateway and coredns enablement in sample config

* Update assets
Latest commit 20450ed Nov 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
build Operator/common files (#340) Oct 9, 2019
cmd Turn on control plane security for sds (#584) Nov 11, 2019
common-protos Fix the gen-check target. (#316) Oct 3, 2019
common Updates to dependencies (#574) Nov 10, 2019
data Move gateway and coredns enablement in sample config (#588) Nov 12, 2019
deploy Remove unnecessary metadata validation part (#571) Nov 9, 2019
hack update build output path. (#334) Oct 9, 2019
images Initial architecture doc (#64) Jul 18, 2019
licenses Updates to dependencies (#574) Nov 10, 2019
pkg Move gateway and coredns enablement in sample config (#588) Nov 12, 2019
prow replace --yes with --skip-confirmation flag for better user experience ( Oct 21, 2019
python/istio_api/pkg/apis/istio Add fields to values schema (#565) Nov 10, 2019
release Sync to installer (#557) Nov 8, 2019
samples add toleration in k8s overlay settings (#269) Sep 9, 2019
scripts Sync to installer (#557) Nov 8, 2019
tests Turn on control plane security for sds (#584) Nov 11, 2019
version Make versions.yaml also compiled-in (#395) Oct 17, 2019
.codecov.yml Set up some baseline stuff for this repo. (#13) May 13, 2019
.gitattributes Update common files. (#270) Sep 9, 2019
.gitignore address incorrect affinity spec (#440) Oct 23, 2019 Add upgrade short description in ARCHITECTURE. (#433) Oct 23, 2019 Update common files. (#39) Jun 17, 2019
CODEOWNERS Update CODEOWNERS (#243) Sep 1, 2019 Set up some baseline stuff for this repo. (#13) May 13, 2019
LICENSE Update common files. (#39) Jun 17, 2019
Makefile Updates to dependencies (#574) Nov 10, 2019 Updates to dependencies (#574) Nov 10, 2019 cross-repo e2e gating for the operator (#379) Oct 17, 2019 Update binary output path (#541) Nov 7, 2019 Update to 2019-08-16 commonfiles (#207) Aug 16, 2019
codecov.skip Add local codecov check script (#23) Jun 11, 2019
codecov.threshold Add local codecov check script (#23) Jun 11, 2019
go.mod use hub and tag from istio/pkg DockerBuildInfo (#475) Oct 30, 2019
go.sum use hub and tag from istio/pkg DockerBuildInfo (#475) Oct 30, 2019
installer.sha Updates to dependencies (#574) Nov 10, 2019

Go Report Card GolangCI

Istio Operator

The Istio operator CLI is beta and the controller is alpha for 1.4. You can contribute by picking an unassigned open issue, creating a bug or feature request, or just coming to the weekly Environments Working Group meeting to share your ideas.

This document is an overview of how the operator works from a user perspective. For more details about the design and architecture and a code overview, see

The operator CLI is distributed to users as part of istioctl. The mesh command in this repo is simply a wrapper to speed up development - the subcommands are the same code that is incorporated into istioctl. Making changes to any mesh subcommand will be reflected in istioctl after one of the regular syncs to istio/operator.


This repo reorganizes the current Helm installation parameters into two groups:

Some parameters will temporarily exist in both APIs - for example, setting K8s resources currently can be done through either API above. However, the Istio community recommends using the first API as it is more consistent, is validated, and will naturally follow the graduation process for APIs while the same parameters in the configuration API are planned for deprecation.

This repo currently provides pre-configured Helm values sets for different scenarios as configuration profiles, which act as a starting point for an Istio install and can be customized by creating customization overlay files or passing parameters when calling Helm. Similarly, the operator API uses the same profiles (expressed internally through the new API), which can be selected as a starting point for the installation. For comparison, the following example shows the command needed to install Istio using the SDS configuration profile using Helm:

helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
    --values install/kubernetes/helm/istio/values-istio-sds-auth.yaml | kubectl apply -f -

In the new API, the same profile would be selected through a CustomResource (CR):

# sds.yaml

kind: IstioControlPlane
  profile: sds

See Select a specific configuration_profile for more information.

If you don't specify a configuration profile, Istio is installed using the default configuration profile. All profiles listed in are available by default, or profile: can point to a local file path to reference a custom profile base to use as a starting point for customization. See the API reference for details.

Developer quick start

The quick start describes how to install and use the operator mesh CLI command and/or controller.


If you're trying to do a local build that bypasses the build container, you'll need to to execute the following step one time.

GO111MODULE=on go get

Clone the repo

git clone
cd operator


To build the operator CLI, simply:

make mesh

This will create a binary called mesh either in ${GOPATH}/bin or ${GOPATH}/go/src/, depending on your platform. Ensure this is in your PATH to run the examples below.

Controller (in cluster)

Building a custom controller requires a Dockerhub (or similar) account. To build using the container based build:<your-account> TAG=latest make docker.all

This builds the controller binary and docker file, and pushes the image to the specified hub with the latest tag. Once the images are pushed, configure kubectl to point to your cluster and install the controller. You should edit the file deploy/operator.yaml to point to your docker hub:


Install the controller manifest and example IstioControlResource CR:

kubectl apply -k deploy/
kubectl apply -f deploy/crds/istio_v1alpha2_istiocontrolplane_cr.yaml 

This installs the controller into the cluster in the istio-operator namespace. The controller in turns installs the Istio control plane into the istio-system namespace by default.

Controller (running locally)

  1. Set env $WATCH_NAMESPACE and $LEADER_ELECTION_NAMESPACE (default value is "istio-operator")

  2. From the operator repo root directory, run go run ./cmd/manager/*.go server

To use Remote debugging with IntelliJ, replace above step 2 with following:

  1. From ./cmd/manager path run dlv debug --headless --listen=:2345 --api-version=2 -- server.

  2. In IntelliJ, create a new Go Remote debug configuration with default settings.

  3. Start debugging process and verify it is working. For example, try adding a breakpoint at Reconcile logic and apply a new CR.

Relationship between the CLI and controller

The CLI and controller share the same API and codebase for generating manifests from the API. You can think of the controller as the CLI command mesh manifest apply running in a loop in a pod in the cluster and using the config from the in-cluster IstioControlPlane CustomResource (CR). There are two major differences:

  1. The controller does not accept any dynamic user config through flags. All user interaction is through the IstioControlPlane CR.
  2. The controller has additional logic that mirrors istioctl commands like upgrade, but is driven from the declarative API rather than command line.

Quick tour of CLI commands


The mesh command supports the following flags:

  • logtostderr: log to console (by default logs go to ./mesh-cli.log).
  • dry-run: console output only, nothing applied to cluster or written to files.
  • verbose: display entire manifest contents and other debug info (default is false).

Basic default manifest

The following command generates a manifest with the compiled-in default profile and charts:

mesh manifest generate

You can see these sources for the compiled-in profiles and charts in the repo under data/. These profiles and charts are also included in the Istio release tar.

Output to dirs

The output of the manifest is concatenated into a single file. To generate a directory hierarchy with subdirectory levels representing a child dependency, use the following command:

mesh manifest generate -o istio_manifests

Use depth first search to traverse the created directory hierarchy when applying your YAML files. This is needed for correct sequencing of dependencies. Child manifest directories must wait for their parent directory to be fully applied, but not their sibling manifest directories.

Just apply it for me

The following command generates the manifests and applies them in the correct dependency order, waiting for the dependencies to have the needed CRDs available:

mesh manifest apply

Review the values of a configuration profile

The following commands show the values of a configuration profile:

# show available profiles
mesh profile list

# show the values in demo profile
mesh profile dump demo

# show the values after a customization file is applied
mesh profile dump -f samples/policy-off.yaml

# show differences between the default and demo profiles
mesh profile dump default > 1.yaml
mesh profile dump demo > 2.yaml
mesh profile diff 1.yaml 2.yaml

# show the differences in the generated manifests between the default profile and a customized install
mesh manifest generate > 1.yaml
mesh manifest generate -f samples/pilot-k8s.yaml > 2.yaml
mesh manifest diff 1.yam1 2.yaml

The profile dump sub-command supports a couple of useful flags:

  • config-path: select the root for the configuration subtree you want to see e.g. just show Pilot:
mesh profile dump --config-path trafficManagement.components.pilot
  • set: set a value in the configuration before dumping the resulting profile e.g. show the minimal profile:
mesh profile dump --set profile=minimal

Select a specific configuration profile

The simplest customization is to select a profile different to default e.g. sds. See samples/sds.yaml:

# sds-install.yaml
kind: IstioControlPlane
  profile: sds

Use the Istio operator mesh binary to generate the manifests for the new configuration profile:

mesh manifest generate -f samples/sds.yaml

After running the command, the Helm charts are rendered using data/profiles/sds.yaml.

Install from file path

The compiled in charts and profiles are used by default, but you can specify a file path, for example:

kind: IstioControlPlane
  profile: /usr/home/bob/go/src/
  installPackagePath: /usr/home/bob/go/src/

You can mix and match these approaches. For example, you can use a compiled-in configuration profile with charts in your local file system.

Migration from values.yaml

The following command takes helm values.yaml files and output the new IstioControlPlaneSpec:

mesh manifest migrate /usr/home/bob/go/src/

If a directory is specified, all files called "values.yaml" under the directory will be converted into a single combined IstioControlPlaneSpec:

mesh manifest migrate /usr/home/bob/go/src/

If no file is specified, the IstioControlPlane CR in the kube config cluster is used as an input:

mesh manifest migrate

Check diffs of manifests

The following command takes two manifests and output the differences in a readable way. It can be used to compare between the manifests generated by operator API and helm directly:

mesh manifest diff ./out/helm-template/manifest.yaml ./out/mesh-manifest/manifest.yaml

New API customization

The new platform level installation API defines install time parameters like feature and component enablement and namespace, and K8s settings like resources, HPA spec etc. in a structured way. The simplest customization is to turn features and components on and off. For example, to turn off all policy (samples/sds-policy-off.yaml):

kind: IstioControlPlane
  profile: sds
    enabled: false

The operator validates the configuration and automatically detects syntax errors. Helm lacks this capability. If you are using Helm values that are incompatible, the schema validation used in the operator may reject input that is valid for Helm. Another customization is to define custom namespaces for features (samples/trafficManagement-namespace.yaml):

kind: IstioControlPlane
      namespace: istio-control-custom

The traffic management feature comprises Pilot and Proxy components. Each of these components has K8s settings, and these can be overridden from the defaults using official K8s APIs rather than Istio defined schemas (samples/pilot-k8s.yaml):

kind: IstioControlPlane
              cpu: 1000m # override from default 500m
              memory: 4096Mi # ... default 2048Mi
            maxReplicas: 10 # ... default 5
            minReplicas: 2  # ... default 1
          nodeSelector: # ... default empty
            master: "true"
          tolerations: # ... default empty
          - key: dedicated
            operator: Exists
            effect: NoSchedule
          - key: CriticalAddonsOnly
            operator: Exists

The K8s settings are defined in detail in the operator API. The settings are the same for all components, so a user can configure pilot K8s settings in exactly the same, consistent way as galley settings. Supported K8s settings currently include:

All of these K8s settings use the K8s API definitions, so K8s documentation can be used for reference. All K8s overlay values are also validated in the operator.

Customizing the old values.yaml API

The new platform install API above deals with K8s level settings. The remaining values.yaml parameters deal with Istio control plane operation rather than installation. For the time being, the operator just passes these through to the Helm charts unmodified (but validated through a schema). Values.yaml settings are overridden the same way as the new API, though a customized CR overlaid over default values for the selected profile. Here's an example of overriding some global level default values (samples/values-global.yaml):

kind: IstioControlPlane
  profile: sds
        level: "default:warning" # override from info

Values overrides can also be specified for a particular component (samples/values-pilot.yaml):

kind: IstioControlPlane
          latencyThreshold: 200ms  

Advanced K8s resource overlays

Advanced users may occasionally have the need to customize parameters (like container command line flags) which are not exposed through either of the installation or configuration APIs described in this document. For such cases, it's possible to overlay the generated K8s resources before they are applied with user-defined overlays. For example, to override some container level values in the Pilot container (samples/pilot-advanced-override.yaml):

kind: IstioControlPlane
    enabled: true
        enabled: false
          - kind: Deployment
            name: istio-pilot
            - path: spec.template.spec.containers.[name:discovery].args.[30m]
              value: "60m" # OVERRIDDEN
            - path: spec.template.spec.containers.[name:discovery].ports.[containerPort:8080].containerPort
              value: 8090 # OVERRIDDEN
          - kind: Service
            name: istio-pilot
            - path: spec.ports.[name:grpc-xds].port
              value: 15099 # OVERRIDDEN

The user-defined overlay uses a path spec that includes the ability to select list items by key. In the example above, the container with the key-value "name: discovery" is selected from the list of containers, and the command line parameter with value "30m" is selected to be modified. The advanced overlay capability is described in more detail in the spec.

Interaction with controller

The controller shares the same API as the operator CLI, so it's possible to install any of the above examples as a CR in the cluster in the istio-operator namespace and the controller will react to it with the same outcome as running mesh manifest apply -f <path-to-custom-resource-file>.



You can’t perform that action at this time.