Installation with Ansible

Instructions for the installation and configuration of Istio using Ansible.

Prerequisites

The following instructions require Ansible 2.4. Additionally Kubernetes 1.7.3 or newer is required.

The following prerequisites must be met if using OpenShift.

  • Minimum Version: 3.7.0
  • oc configured to be able to access the cluster
  • User has logged in to the cluster
  • User has admin role on OpenShift

Deploy with Ansible

Important: All execution of the Ansible playbooks must take place in the install/ansible path of Istio.

This playbook will download and install Istio locally on your machine. To deploy the default settings of Istio on OpenShift, the following command may be used:

$ ansible-playbook main.yml

Customization with Ansible

The Ansible playbook ships with reasonable defaults.

The currently exposed options are:

ParameterDescriptionValuesDefault
cluster_flavourDefine the target cluster typek8s or ocpocp
github_api_tokenA valid GitHub API authentication token used for authenticating with GitHubA valid GitHub API tokenempty
cmd_pathOverride the path to kubectl or ocA valid path to a kubectl or oc binary$PATH/oc
istio.release_tag_nameIstio release version to installAny valid Istio release versionthe latest Istio release version
istio.destThe directory of the target machine where Istio will be installedAny directory with read+write permissions~/.istio
istio.authInstall with mutual TLStrue or falsefalse
istio.namespaceKubernetes namespace where Istio will be installedany namespace may be specifiedistio-system
istio.addonIstio addons to installarray containing any of grafana, prometheus, zipkin, jaeger, or servicegraphall addons are enabled by default
istio.delete_resourcesDelete resources created under Istio namespacetrue or falsefalse
istio.samplesArray containing the names of the samples that should be installedbookinfo, helloworld, httpbin, sleepnone

Default installation

Operator installs Istio using all defaults on OpenShift:

$ ansible-playbook main.yml

Operational overrides

There may be circumstances in which defaults require overrides.

The following commands describe how an operator could use overrides with this Ansible playbook:

Operator installs Istio on Kubernetes:

$ ansible-playbook main.yml -e '{"cluster_flavour": "k8s"}'

Operator installs Istio on Kubernetes and the path to kubectl is explicitly set:

$ ansible-playbook main.yml -e '{"cluster_flavour": "k8s", "cmd_path": "~/kubectl"}'

Operator installs Istio on OpenShift with settings other than the default:

$ ansible-playbook main.yml -e '{"istio": {"release_tag_name": "0.6.0", "auth": true, "delete_resources": true}}'

Operator installs Istio on OpenShift with customized addons:

$ ansible-playbook main.yml -e '{"istio": {"delete_resources": true, "addon": ["grafana", "prometheus", "jaeger"]}}'

Operator installs Istio on OpenShift and additionally wants to deploy some of the samples:

$ ansible-playbook main.yml -e '{"istio": {"samples": ["helloworld", "bookinfo"]}}'

When Jaeger is enabled, Zipkin is disabled even when Zipkin is selected in the addons.

Uninstalling

If a different version of Istio is desired, delete the istio-system namespace before executing the playbook. In this case, the istio.delete_resources flag does not need to be set.

Setting istio.delete_resources to true will delete the Istio control plane from the cluster.

In order to avoid any inconsistencies, this flag should only be used to reinstall the same version of Istio on a cluster.