Installing the Istio Module

2 Installing the Istio Module

This chapter discusses how to install the Istio module to set up a service mesh, and the components deployed when you do this.

The Istio module is installed using a mostly empty profile. The default Istio module profile contains the profile name, the container image hub, and container image tags. To customize an Istio module installation, you can use a custom Istio profile. This lets you set Kubernetes resource settings, enable, or disable individual Istio components, and configure their settings.

To customize these components, you write a YAML configuration file for these settings, and use it when you deploy an Istio module. You can deploy multiple Istio modules, with different configurations, all using the same Istio control plane.

You can deploy a single custom Istio module using a configuration file, or you can deploy multiple Istio modules. To deploy multiple Istio modules, you must have an initial module set up as the default module, which acts as the Istio control plane. This default module is considered the parent Istio module. The parent Istio module is installed using the default profile.

Creating a Configuration File

To install a customized Istio module, you need to write a YAML configuration file to specify the configuration options. You use the spec section of an IstioOperator resource file to set the configuration. For information on the options available to use in the configuration file, see the IstioOperator resource in the upstream Istio documentation.

Don't include a full IstioOperator file in the configuration file, only use the options available that follow the spec section. So do not include the following lines in a configuration file:

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:

The configuration file includes the IstioOperator configuration you want to set, for example:

profile: myistio
hub: myhub.example
components:
  egressGateways:
  - name: istio-egressgateway
    enabled: true

Or you could provide only the IstioOperator components you want to customize, for example:

components:
  egressGateways:
  - name: istio-egressgateway
    enabled: true

The YAML configuration file is used with the olcnectl module create command when you create the Istio modules.

Example 2-1 Configuration file to set up a load balancer for the Istio ingress gateway

This example Istio configuration file uses the Oracle Cloud Infrastructure Cloud Controller Manager module to provision an Oracle Cloud Infrastructure load balancer for the Istio ingress gateway by applying the appropriate annotations to the istio-ingressgateway service to set this up.

Note:

To try this example, you must have the Oracle Cloud Infrastructure Cloud Controller Manager module installed.

The YAML configuration file contains:

components:
  ingressGateways:
  - name: istio-ingressgateway
    k8s:
      serviceAnnotations:
        service.beta.kubernetes.io/oci-load-balancer-security-list-management-mode: "None"
        service.beta.kubernetes.io/oci-load-balancer-internal: "true"
        service.beta.kubernetes.io/oci-load-balancer-shape: "flexible"
        service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "10"
        service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "10"

For the full list of Oracle Cloud Infrastructure Cloud Controller Manager annotations you can include, see the upstream documentation at:

https://github.com/oracle/oci-cloud-controller-manager/blob/master/docs/load-balancer-annotations.md

After you deploy the Istio module using this configuration file, you would see the following Kubernetes services deployed to the istio-system namespace. On a control plane node, show the services in the istio-system namespace.

kubectl --namespace istio-system get svc

The output looks similar to:

NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP       PORT(S)            ...
grafana                ClusterIP      10.97.12.24      <none>            3000/TCP           ...
istio-egressgateway    ClusterIP      10.106.217.129   <none>            80/TCP,443/TCP,1544...
istio-ingressgateway   LoadBalancer   10.103.9.119     100.102.106.171   15021:30762/TCP,80:...
istiod                 ClusterIP      10.106.101.205   <none>            15010/TCP,15012/TCP...
prometheus-server      ClusterIP      10.107.228.56    <none>            9090/TCP           ...

You can see the istio-ingressgateway service is of type LoadBalancer and has an externalIP associated with it.

Example 2-2 Detailed configuration file to set up a load balancer for the Istio ingress gateway

This example configuration file creates an Istio module with a profile that creates an Istio ingress gateway named my-istio-ingressgateway in a namespace named myistio. This example also uses the Oracle Cloud Infrastructure Cloud Controller Manager module to provision an Oracle Cloud Infrastructure load balancer for the Istio ingress gateway, and includes more detail on how to configure the gateway.

Note:

To try this example, you must have the Oracle Cloud Infrastructure Cloud Controller Manager module installed.

The YAML configuration file contains:

components:
  ingressGateways:
  - enabled: true
    k8s:
      hpaSpec:
        maxReplicas: 5
        minReplicas: 2
        scaleTargetRef:
          apiVersion: apps/v1
          kind: Deployment
          name: my-istio-ingressgateway
      resources:
        limits:
          cpu: 2000m
          memory: 1024Mi
        requests:
          cpu: 100m
          memory: 128Mi
      serviceAnnotations:
        service.beta.kubernetes.io/oci-load-balancer-security-list-management-mode: "None"
        service.beta.kubernetes.io/oci-load-balancer-internal: "true"
        service.beta.kubernetes.io/oci-load-balancer-shape: "flexible"
        service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "10"
        service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "10"
      service:
        ports:
        - name: status-port
          port: 15021
          protocol: TCP
          targetPort: 15021
        - name: http2
          port: 80
          protocol: TCP
          targetPort: 8080
        - name: https
          port: 443
          protocol: TCP
          targetPort: 8443
        - name: tcp-istiod
          port: 15012
          protocol: TCP
          targetPort: 15012
        - name: tls
          port: 15443
          protocol: TCP
          targetPort: 15443
      strategy:
        rollingUpdate:
          maxSurge: 100%
          maxUnavailable: 25%
    name: my-istio-ingressgateway
    namespace: myistio
values:
  gateways:
    istio-ingressgateway:
      autoscaleEnabled: true
      env: {}
      name: istio-ingressgateway
      secretVolumes:
      - mountPath: /etc/istio/ingressgateway-certs
        name: ingressgateway-certs
        secretName: istio-ingressgateway-certs
      - mountPath: /etc/istio/ingressgateway-ca-certs
        name: ingressgateway-ca-certs
        secretName: istio-ingressgateway-ca-certs
      type: LoadBalancer

In this example, the Istio ingress gateway named my-istio-ingressgateway is in a namespace named myistio. This namespace isn't the default Istio namespace of istio-system. If you install the gateway service into a namespace other than the default namespace, as shown in this example, you must first create the namespace. Create the new namespace with the kubectl create namespace command on a control plane node. For example, on a control plane node:

kubectl create namespace myistio

After you deploy the Istio module using this configuration file, you would see the following Kubernetes services deployed to the default istio-system namespace. On a control plane node, show the services in the istio-system namespace.

kubectl --namespace istio-system get svc

The output looks similar to:

NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                ...
grafana                ClusterIP      10.103.216.188   <none>        3000/TCP               ...
istio-egressgateway    ClusterIP      10.111.113.121   <none>        80/TCP,443/TCP,15443/TC...
istio-ingressgateway   LoadBalancer   10.106.116.57    <pending>     15021:30210/TCP,80:3193...
istiod                 ClusterIP      10.99.54.66      <none>        15010/TCP,15012/TCP,443...
prometheus-server      ClusterIP      10.110.20.110    <none>        9090/TCP               ...

The istio-ingressgateway service is of type LoadBalancer and has no externalIP associated with it (it's in the pending state). This is the default service that's deployed, and is set up using the default Istio configuration.

To show the ingress gateway service named my-isitio-ingressgateway, get the services running in the myistio namespace. On a control plane node, show the services in the myistio namespace.

kubectl --namespace myistio get svc

The output looks similar to:

NAME                      TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)             ...
my-istio-ingressgateway   LoadBalancer   10.96.174.73   100.102.107.82   15021:30292/TCP,80:3...

You can see the my-istio-ingressgateway service is of type LoadBalancer and has an externalIP associated with it. This is the service created using the configuration file.

Deploying the Istio Module

You can deploy all the modules required to create a service mesh and a Kubernetes cluster using a single olcnectl module create command. This method might be useful to deploy a service mesh at the same time as deploying a Kubernetes cluster.

If you have an existing deployment of the Kubernetes module, you can specify that instance when deploying a service mesh.

You can create a custom Istio module using a configuration file. This lets you set Kubernetes resource settings, enable, or disable individual Istio components, and configure their settings. For information on creating custom profiles for Istio modules, see Creating a Configuration File.

If you're installing multiple custom Istio modules using configuration files, see Deploying Multiple Custom Istio Modules.

For the full list of the options available when creating modules, see the olcnectl module create command in Platform Command-Line Interface.

Note:

The Istio module installs two other modules, the Prometheus module, and the Grafana module. These two modules install Prometheus and Grafana to enable monitoring and visualization of the Kubernetes cluster. You don't need to provide any information for these modules when you install the Istio module.

To deploy an Istio module:

If you don't already have an environment set up, create one into which the modules can be deployed. For information on setting up an environment, see Installation. The name of the environment in this example is myenvironment.
If you don't already have a Kubernetes module set up or deployed, set one up. For information on adding a Kubernetes module to an environment, see Kubernetes Module. The name of the Kubernetes module in this example is mycluster.
Create an Istio module and associate it with the Kubernetes module named mycluster using the --istio-kubernetes-module option. In this example, the Istio module is named myistio.
```
olcnectl module create \
--environment-name myenvironment \
--module istio \
--name myistio \
--istio-kubernetes-module mycluster
```
The --module option sets the module type to create, which is istio. You define the name of the Istio module using the --name option, which in this case is myistio.

As the Istio module requires Kubernetes, you must also provide the option for that module.

The --istio-kubernetes-module option sets the name of the Kubernetes module to use. The Kubernetes module must already be set up or deployed. If you have an existing Kubernetes module deployed, you can specify the name of the module using this option. If no Kubernetes module is deployed with the name you provide, a new module is deployed which lets you deploy Kubernetes at the same time as a service mesh.

If you're installing an Istio module using a custom profile, include the --istio-profile option to specify the location of the YAML configuration file. The Platform API Server configures the Istio module using the settings in the configuration file.

If you don't include all the required options when adding the modules you're prompted to provide them.
Use the olcnectl module install command to install the Istio module. For example:
```
olcnectl module install \
--environment-name myenvironment \
--name myistio
```
You can optionally use the --log-level option to set the level of logging displayed in the command output. By default, error messages are displayed. For example, you can set the logging level to show all messages when you include:
```
--log-level debug
```
The log messages are also saved as an operation log. You can view operation logs as commands are running, or when they've completed. For more information using operation logs, see Platform Command-Line Interface.

The Istio software packages are installed on the control plane nodes, and the Istio module is deployed into the Kubernetes cluster.

Deploying Multiple Custom Istio Modules

To deploy multiple Istio modules, create an Istio module as the parent module with a default profile. This creates a single Istio control plane to manage the custom Istio modules. You can do this by deploying an Istio module without a profile configuration file. You then deploy any further Istio modules with their respective profile configuration files and set the parent module using the --istio-parent option.

To deploy multiple Istio modules:

Follow the steps in Deploying the Istio Module to set up a default Istio module to act as the parent module. Don't include a custom profile configuration file when you create the Istio module.
Create a second Istio module with a YAML configuration file. Use the olcnectl module create command to create the module.
```
olcnectl module create \
--environment-name myenvironment \
--module istio \
--name mycustomistio \
--istio-kubernetes-module mycluster \
--istio-parent myistio \
--istio-profile mycustomistio.yaml
```
The --name option sets the name of this second Istio module. In this example it's set to mycustomistio.

The --istio-parent option sets the name of the parent Istio module. In this example, the parent Istio module is named myistio, which is also the name of the Istio module used in the example in Deploying the Istio Module.

The --istio-profile option sets the location of the YAML configuration file.
Install the Istio module, using the olcnectl module install command. For example:
```
olcnectl module install \
--environment-name myenvironment \
--name mycustomistio 
```
To add more custom Istio modules to the parent Istio control plane, create more Istio modules, using different module names, configuration files, and specify the parent module.

Verifying the Istio Module Deployment

You can verify the Istio module is deployed and the required containers are running in the istio-system namespace. To verify the containers are deployed, you need to use the kubectl command. For information on setting up the kubectl command, see Kubernetes Module.

To verify the required containers are running, on a control plan node, list the containers running in the istio-system namespace.

kubectl get deployment --namespace istio-system

The output looks similar to:

NAME                   READY   UP-TO-DATE   AVAILABLE   AGE
grafana                2/2     2            2           2m44s
istio-egressgateway    2/2     2            2           2m48s
istio-ingressgateway   2/2     2            2           2m48s
istiod                 2/2     2            2           3m2s
prometheus-server      2/2     2            2           2m44s

You can also review information about the Istio module and its properties.

On the operator node, use the olcnectl module report command to review information about the module. For example, use the following command to review the Istio module named myistio in myenvironment:

olcnectl module report \
--environment-name myenvironment \
--name myistio \
--children

For more information on the syntax for the olcnectl module report command, see Platform Command-Line Interface.