mirror of https://github.com/istio/istio.io.git
188 lines
8.4 KiB
Markdown
188 lines
8.4 KiB
Markdown
---
|
||
title: Introducing the Istio Operator
|
||
description: Introduction to Istio's new operator-based installation and control plane management feature.
|
||
publishdate: 2019-11-14
|
||
subtitle:
|
||
attribution: Martin Ostrowski (Google), Frank Budinsky (IBM)
|
||
keywords: [install,configuration,istioctl,operator]
|
||
target_release: 1.4
|
||
---
|
||
|
||
Kubernetes [operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) provide
|
||
a pattern for encoding human operational knowledge in software and are a popular way to simplify
|
||
the administration of software infrastructure components. Istio is a natural candidate for an automated
|
||
operator as it is challenging to administer.
|
||
|
||
Up until now, [Helm](https://github.com/helm/helm) has been the primary tool to install and upgrade Istio.
|
||
Istio 1.4 introduces a new method of [installation using {{< istioctl >}}](/docs/setup/install/istioctl/).
|
||
This new installation method builds on the strengths of Helm with the addition of the
|
||
following:
|
||
|
||
- Users only need to install one tool: `istioctl`
|
||
- All API fields are validated
|
||
- Small customizations not in the API don't require chart or API changes
|
||
- Version specific upgrade hooks can be easily and robustly implemented
|
||
|
||
The [Helm installation](https://archive.istio.io/1.4/docs/setup/install/helm/) method is in the process of deprecation. Upgrading from Istio
|
||
1.4 with a version not initially installed with Helm will also be replaced by a new
|
||
[{{< istioctl >}} upgrade feature](https://archive.istio.io/v1.4/docs/setup/upgrade/istioctl-upgrade/).
|
||
|
||
The new `istioctl` installation commands use a
|
||
[custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
|
||
to configure the installation. The custom resource is part of a new Istio operator
|
||
implementation intended to simplify the common administrative tasks of installation, upgrade,
|
||
and complex configuration changes for Istio. Validation and checking for installation and upgrade
|
||
is tightly integrated with the tools to prevent common errors and simplify troubleshooting.
|
||
|
||
## The Operator API
|
||
|
||
Every operator implementation requires a
|
||
[custom resource definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
|
||
to define its custom resource, that is, its API. Istio's operator API is defined by the
|
||
[`IstioControlPlane` CRD](https://archive.istio.io/v1.4/docs/reference/config/istio.operator.v1alpha12.pb/),
|
||
which is generated from an
|
||
[`IstioControlPlane` proto](https://github.com/istio/operator/blob/release-1.4/pkg/apis/istio/v1alpha2/istiocontrolplane_types.proto).
|
||
The API supports all of Istio's current [configuration profiles](/docs/setup/additional-setup/config-profiles/)
|
||
using a single field to select the profile. For example, the following `IstioControlPlane` resource
|
||
configures Istio using the `demo` profile:
|
||
|
||
{{< text yaml >}}
|
||
apiVersion: install.istio.io/v1alpha2
|
||
kind: IstioControlPlane
|
||
metadata:
|
||
namespace: istio-operator
|
||
name: example-istiocontrolplane
|
||
spec:
|
||
profile: demo
|
||
{{< /text >}}
|
||
|
||
You can then customize the configuration with additional settings. For example, to disable telemetry:
|
||
|
||
{{< text yaml >}}
|
||
apiVersion: install.istio.io/v1alpha2
|
||
kind: IstioControlPlane
|
||
metadata:
|
||
namespace: istio-operator
|
||
name: example-istiocontrolplane
|
||
spec:
|
||
profile: demo
|
||
telemetry:
|
||
enabled: false
|
||
{{< /text >}}
|
||
|
||
## Installing with {{< istioctl >}}
|
||
|
||
The recommended way to use the Istio operator API is through a new set of `istioctl` commands.
|
||
For example, to install Istio into a cluster:
|
||
|
||
{{< text bash >}}
|
||
$ istioctl manifest apply -f <your-istiocontrolplane-customresource>
|
||
{{< /text >}}
|
||
|
||
Make changes to the installation configuration by editing the configuration file and executing
|
||
`istioctl manifest apply` again.
|
||
|
||
To upgrade to a new version of Istio:
|
||
|
||
{{< text bash >}}
|
||
$ istioctl x upgrade -f <your-istiocontrolplane-config-changes>
|
||
{{< /text >}}
|
||
|
||
In addition to specifying the complete configuration in an `IstioControlPlane` resource,
|
||
the `istioctl` commands can also be passed individual settings using a `--set` flag:
|
||
|
||
{{< text bash >}}
|
||
$ istioctl manifest apply --set telemetry.enabled=false
|
||
{{< /text >}}
|
||
|
||
There are also a number of other `istioctl` commands that, for example, help you list, display,
|
||
and compare configuration profiles and manifests.
|
||
|
||
Refer to the Istio [install instructions](/docs/setup/install/istioctl) for more details.
|
||
|
||
## Istio Controller (alpha)
|
||
|
||
Operator implementations use a Kubernetes controller to continuously monitor their custom resource
|
||
and apply the corresponding configuration changes. The Istio controller monitors an `IstioControlPlane`
|
||
resource and reacts to changes by updating the Istio installation configuration in the corresponding cluster.
|
||
|
||
In the 1.4 release, the Istio controller is in the alpha phase of development and not fully
|
||
integrated with `istioctl`. It is, however,
|
||
[available for experimentation](https://archive.istio.io/v1.23/docs/setup/install/operator/) using `kubectl` commands.
|
||
For example, to install the controller and a default version of Istio into your cluster,
|
||
run the following command:
|
||
|
||
{{< text bash >}}
|
||
$ kubectl apply -f https://<repo URL>/operator.yaml
|
||
$ kubectl apply -f https://<repo URL>/default-cr.yaml
|
||
{{< /text >}}
|
||
|
||
You can then make changes to the Istio installation configuration:
|
||
|
||
{{< text bash >}}
|
||
$ kubectl edit istiocontrolplane example-istiocontrolplane -n istio-system
|
||
{{< /text >}}
|
||
|
||
As soon as the resource is updated, the controller will detect the changes and respond by updating
|
||
the Istio installation correspondingly.
|
||
|
||
Both the operator controller and `istioctl` commands share the same implementation. The significant
|
||
difference is the execution context. In the `istioctl` case, the operation runs in the admin user’s
|
||
command execution and security context. In the controller case, a pod in the cluster runs the code
|
||
in its security context. In both cases, configuration is validated against a schema and the same correctness
|
||
checks are performed.
|
||
|
||
## Migration from Helm
|
||
|
||
To help ease the transition from previous configurations using Helm,
|
||
`istioctl` and the controller support pass-through access for the full Helm installation API.
|
||
|
||
You can pass Helm configuration options using `istioctl --set` by prepending the string `values.` to the option name.
|
||
For example, instead of this Helm command:
|
||
|
||
{{< text bash >}}
|
||
$ helm template ... --set global.mtls.enabled=true
|
||
{{< /text >}}
|
||
|
||
You can use this `istioctl` command:
|
||
|
||
{{< text bash >}}
|
||
$ istioctl manifest generate ... --set values.global.mtls.enabled=true
|
||
{{< /text >}}
|
||
|
||
You can also set Helm configuration values in an `IstioControlPlane` custom resource.
|
||
See [Customize Istio settings using Helm](/docs/setup/install/istioctl/#customize-istio-settings-using-the-helm-api)
|
||
for details.
|
||
|
||
Another feature to help with the transition from Helm is the alpha
|
||
[{{< istioctl >}} manifest migrate](/docs/reference/commands/istioctl/#istioctl-manifest-migrate) command.
|
||
This command can be used to automatically convert a Helm `values.yaml` file to a corresponding
|
||
`IstioControlPlane` configuration.
|
||
|
||
## Implementation
|
||
|
||
Several frameworks have been created to help implement operators by generating stubs for some or all of
|
||
the components. The Istio operator was created with the help of a combination of
|
||
[kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) and
|
||
[operator framework](https://github.com/operator-framework). Istio's installation now uses a proto to
|
||
describe the API such that runtime validation can be executed against a schema.
|
||
|
||
More information about the implementation can be found in the README and ARCHITECTURE documents
|
||
in the [Istio operator repository](https://github.com/istio/operator).
|
||
|
||
## Summary
|
||
|
||
Starting in Istio 1.4, Helm installation is being replaced by new `istioctl` commands using
|
||
a new operator custom resource definition, `IstioControlPlane`, for the configuration API.
|
||
An alpha controller is also available for early experimentation with the operator.
|
||
|
||
The new `istioctl` commands and operator controller both validate configuration schemas and perform a range of
|
||
checks for installation change or upgrade. These checks are tightly integrated with the tools to prevent
|
||
common errors and simplify troubleshooting.
|
||
|
||
The Istio maintainers expect that this new approach will improve the user experience during Istio
|
||
installation and upgrade, better stabilize the installation API, and help users better manage and
|
||
monitor their Istio installations.
|
||
|
||
We welcome your feedback about the new installation approach at [discuss.istio.io](https://discuss.istio.io/).
|