Istio Operator Install
Instead of manually installing, upgrading, and uninstalling Istio,
you can instead let the Istio operator
manage the installation for you.
This relieves you of the burden of managing different istioctl
versions.
Simply update the operator custom resource (CR) and the
operator controller will apply the corresponding configuration changes for you.
The same IstioOperator
API is used
to install Istio with the operator as when using the istioctl install instructions.
In both cases, configuration is validated against a schema and the same correctness
checks are performed.
Prerequisites
Perform any necessary platform-specific setup.
Check the Requirements for Pods and Services.
Install the istioctl command.
Install
Deploy the Istio operator
The istioctl
command can be used to automatically deploy the Istio operator:
$ istioctl operator init
This command runs the operator by creating the following resources in the istio-operator
namespace:
- The operator custom resource definition
- The operator controller deployment
- A service to access operator metrics
- Necessary Istio operator RBAC rules
You can configure which namespace the operator controller is installed in, the namespace(s) the operator watches, the installed Istio image sources and versions, and more. For example, you can pass one or more namespaces to watch using the --watchedNamespaces
flag:
$ istioctl operator init --watchedNamespaces=istio-namespace1,istio-namespace2
See the istioctl operator init
command reference for details.
Install Istio with the operator
With the operator installed, you can now create a mesh by deploying an IstioOperator
resource.
To install the Istio demo
configuration profile
using the operator, run the following command:
$ kubectl apply -f - <<EOF
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
namespace: istio-system
name: example-istiocontrolplane
spec:
profile: demo
EOF
The controller will detect the IstioOperator
resource and then install the Istio
components corresponding to the specified (demo
) configuration.
The Istio control plane (istiod) will be installed in the istio-system
namespace by default. To install it in a different location, specify the namespace using the values.global.istioNamespace
field as follows:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
...
spec:
profile: demo
values:
global:
istioNamespace: istio-namespace1
You can confirm the Istio control plane services have been deployed with the following commands:
$ kubectl get services -n istio-system
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istio-egressgateway ClusterIP 10.96.65.145 <none> ... 30s
istio-ingressgateway LoadBalancer 10.96.189.244 192.168.11.156 ... 30s
istiod ClusterIP 10.96.189.20 <none> ... 37s
$ kubectl get pods -n istio-system
NAME READY STATUS RESTARTS AGE
istio-egressgateway-696cccb5-m8ndk 1/1 Running 0 68s
istio-ingressgateway-86cb4b6795-9jlrk 1/1 Running 0 68s
istiod-b47586647-sf6sw 1/1 Running 0 74s
Update
Now, with the controller running, you can change the Istio configuration by editing or replacing
the IstioOperator
resource. The controller will detect the change and respond by updating
the Istio installation correspondingly.
For example, you can switch the installation to the default
profile with the following command:
$ kubectl apply -f - <<EOF
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
namespace: istio-system
name: example-istiocontrolplane
spec:
profile: default
EOF
You can also enable or disable components and modify resource settings.
For example, to enable the istio-egressgateway
component and increase istiod memory requests:
$ kubectl apply -f - <<EOF
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
namespace: istio-system
name: example-istiocontrolplane
spec:
profile: default
components:
pilot:
k8s:
resources:
requests:
memory: 3072Mi
egressGateways:
- name: istio-egressgateway
enabled: true
EOF
You can observe the changes that the controller makes in the cluster in response to IstioOperator
CR updates by
checking the operator controller logs:
$ kubectl logs -f -n istio-operator "$(kubectl get pods -n istio-operator -lname=istio-operator -o jsonpath='{.items[0].metadata.name}')"
Refer to the IstioOperator
API
for the complete set of configuration settings.
In-place Upgrade
Download and extract the istioctl
corresponding to the version of Istio you wish to upgrade to. Reinstall the operator
at the target Istio version:
$ <extracted-dir>/bin/istioctl operator init
You should see that the istio-operator
pod has restarted and its version has changed to the target version:
$ kubectl get pods --namespace istio-operator \
-o=jsonpath='{range .items[*]}{.metadata.name}{":\t"}{range .spec.containers[*]}{.image}{", "}{end}{"\n"}{end}'
After a minute or two, the Istio control plane components should also be restarted at the new version:
$ kubectl get pods --namespace istio-system \
-o=jsonpath='{range .items[*]}{"\n"}{.metadata.name}{":\t"}{range .spec.containers[*]}{.image}{", "}{end}{"\n"}{end}'
Canary Upgrade
The process for canary upgrade is similar to the canary upgrade with istioctl
.
For example, to upgrade Istio 1.21.0 to 1.22.3, first install 1.21.0 :
$ curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.21.0 sh -
Deploy the operator using Istio version 1.21.0:
$ istio-1.21.0/bin/istioctl operator init
Install Istio control plane demo profile:
$ kubectl apply -f - <<EOF
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
namespace: istio-system
name: example-istiocontrolplane-1-21-0
spec:
profile: default
EOF
Verify that the IstioOperator
CR named example-istiocontrolplane
exists in your cluster:
$ kubectl get iop --all-namespaces
NAMESPACE NAME REVISION STATUS AGE
istio-system example-istiocontrolplane1-21-0 HEALTHY 11m
Download and extract the istioctl
corresponding to the version of Istio you wish to upgrade to.
Then, run the following command to install the new target revision of the Istio control plane based on the in-cluster
IstioOperator
CR (here, we assume the target revision is 1-22-3):
$ istio-1.22.3/bin/istioctl operator init --revision 1-22-3
Make a copy of the example-istiocontrolplane
CR and save it in a file named example-istiocontrolplane-1-22-3.yaml
.
Change the name to example-istiocontrolplane-1-22-3
and add revision: 1-22-3
to the CR.
Your updated IstioOperator
CR should look something like this:
$ cat example-istiocontrolplane-1-22-3.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
namespace: istio-system
name: example-istiocontrolplane-1-22-3
spec:
revision: 1-22-3
profile: default
Apply the updated IstioOperator
CR to the cluster. After that, you will have two control plane deployments and services running side-by-side:
$ kubectl get pod -n istio-system -l app=istiod
NAME READY STATUS RESTARTS AGE
istiod-1-22-3-597475f4f6-bgtcz 1/1 Running 0 64s
istiod-6ffcc65b96-bxzv5 1/1 Running 0 2m11s
$ kubectl get services -n istio-system -l app=istiod
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istiod ClusterIP 10.104.129.150 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP,853/TCP 2m35s
istiod-1-22-3 ClusterIP 10.111.17.49 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 88s
To complete the upgrade, label the workload namespaces with istio.io/rev=1-22-3
and restart the workloads, as
explained in the Data plane upgrade documentation.
Uninstall
If you used the operator to perform a canary upgrade of the control plane, you can uninstall the old control plane and keep the new one by deleting the old in-cluster IstioOperator
CR, which will uninstall the old revision of Istio:
$ kubectl delete istiooperators.install.istio.io -n istio-system example-istiocontrolplane
Wait until Istio is uninstalled - this may take some time.
Then you can remove the Istio operator for the old revision by running the following command:
$ istioctl operator remove --revision <revision>
If you omit the revision
flag, then all revisions of Istio operator will be removed.
Note that deleting the operator before the IstioOperator
CR and corresponding Istio revision are fully removed may result in leftover Istio resources.
To clean up anything not removed by the operator:
$ istioctl uninstall -y --purge
$ kubectl delete ns istio-system istio-operator