Installing with Ansible

The Ansible scenario defined within this project will allow you to :

• Deploy Istio on Kubernetes or Openshift by specifying different parameters (version, enable auth, deploy bookinfo, …)
• Specify the addons to be deployed such as Grafana, Prometheus, Servicegraph, Zipkin or Jaeger

Prerequisites

• Ansible 2.4

Refer to the Ansible Installation Doc on how to install Ansible on your machine. To use Minishift or Minikube for local clusters, please refer to their respective documentation.

Furthermore, the following requirements must be met for the respective clusters

• Kubernetes:
  • Minimum Version: 1.7.2
  • kubectl configured to be able to access the cluster
• 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 the Openshift platform

Execution

Important: All invocations of the Ansible playbooks need to take place at the install/ansible path of the project. Failing to do so will result in unexpected errors

The simplest execution command looks like the following:

ansible-playbook main.yml

Remarks:

• This Ansible playbook is idempotent. If you find examples of lacking idempotency please file a bug.
• The default parameters that apply to this role can be found in istio/defaults/main.yml.

The full list of configurable parameters is as follows:

An example of an invocation where we want to deploy Jaeger instead of Zipkin would be:

ansible-playbook main.yml -e '{"istio": {"jaeger": true}}'

This playbook will take care of downloading and installing Istio locally on your machine, before deploying the necessary Kubernetes / Openshift pods, services etc. on to the cluster.

Note on istio.delete_resources

Activating the istio.delete_resources flag will result in any Istio related resources being deleted from the cluster before Istio is reinstalled.

In order to avoid any inconsistency issues, this flag should only be used to reinstall the same version of Istio on a cluster. If a new version of Istio need to be reinstalled, then it is advisable to delete the istio-system namespace before executing the playbook (in which case the istio.delete_resources flag does not need to be activated)

Typical use cases

The following commands are some examples of how a user could install Istio using this Ansible role:

• User executes installs Istio accepting all defaults

  ansible-playbook main.yml
  

• User installs Istio on to a Kubernetes cluster

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

• User installs Istio on to a Kubernetes cluster and the path to kubectl is expicitly set (perhaps it’s not on the PATH)

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

• User wants to install Istio on Openshift with settings other than the default

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

• User wants to install Istio on Openshift but with custom add-on settings

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

• User wants to install Istio on Openshift and additionally wants to deploy some of the samples

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

The list of available addons can be found at istio/vars.main.yml under the name istio_all_addons. Jaeger is not installed using the addons property, but can be installed by enabling "jaeger": true like in one of the previous examples. It should be noted that when Jaeger is enabled, Zipkin is disabled whether or not it’s been selected in the addons section.

Adding istioctl to PATH

After executing the playbook if it is desired that the istioctl command line tool be added to the PATH, search for Add Istio to PATH in the output and execute the commands that are outputted