2 Setting up a Service Mesh
Important:
The software described in this documentation is either in Extended Support or Sustaining Support. See Oracle Open Source Support Policies for more information.
We recommend that you upgrade the software described by this documentation as soon as possible.
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. If you want to customize an Istio module installation, you can use a custom Istio profile. This allows you to 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. If you want to deploy multiple Istio modules, you should 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 upstream documentation for the IstioOperator resource, at:
https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/
Do not include a full IstioOperator file in the configuration file, only use the options
available below the spec
section. That is, do not include the
following lines in your configuration file:
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
profile: myistio
hub: myhub.example
components:
egressGateways:
- name: istio-egressgateway
enabled: true
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 module(s).
Example 2-1 Simple 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 should look 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 is not the default Istio
namespace of istio-system
. If you are installing the gateway service into a
non-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 should look 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 is in the pending
state). This is the
default service that is 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 should look 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
if you want 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 allows you to 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 are 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 respectively to enable monitoring and visualization of the Kubernetes cluster. You do not need to provide any information for these modules when you install the Istio module.
To deploy an Istio module:
-
If you do not already have an environment set up, create one into which the modules can be deployed. For information on setting up an environment, see Getting Started. The name of the environment in this example is
myenvironment
. -
If you do not already have a Kubernetes module set up or deployed, set one up. For information on adding a Kubernetes module to an environment, see Container Orchestration. The name of the Kubernetes module in this example is
mycluster
. -
If you do not already have a Helm module created and installed, create one. The Helm module in this example is named
myhelm
and is associated with the Kubernetes module namedmycluster
using the--helm-kubernetes-module
option.olcnectl module create \ --environment-name myenvironment \ --module helm \ --name myhelm \ --helm-kubernetes-module mycluster
-
If you are deploying a new Helm module, use the
olcnectl module install
command to install the Helm module. For example:olcnectl module install \ --environment-name myenvironment \ --name myhelm
The Helm software packages are installed on the control plane nodes, and the Helm module is deployed into the Kubernetes cluster.
-
Create an Istio module and associate it with the Helm module named
myhelm
using the--istio-helm-module
option. In this example, the Istio module is namedmyistio
.olcnectl module create \ --environment-name myenvironment \ --module istio \ --name myistio \ --helm-kubernetes-module mycluster \ --istio-helm-module myhelm
The
--module
option sets the module type to create, which isistio
. You define the name of the Istio module using the--name
option, which in this case ismyistio
.As the Istio module requires Kubernetes and Helm, you must also provide the options for those modules.
The
--helm-kubernetes-module
option sets the name of the Kubernetes module to use. The Kubernetes module should 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 allows you to deploy Kubernetes at the same time as a service mesh.The
--istio-helm-module
option sets the name of the Helm module to deploy.If you are 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 do not include all the required options when adding the modules you are 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
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
If you want to deploy multiple Istio modules, you should 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. Do not 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 \ --helm-kubernetes-module mycluster \ --istio-helm-module myhelm \ --istio-parent myistio \ --istio-profile mycustomistio.yaml
The
--name
option sets the name of this second Istio module. In this example it is set tomycustomistio
.The
--istio-parent
option sets the name of the parent Istio module. In this example, the parent Istio module is namedmyistio
, 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
Container Orchestration.
To verify the required containers are running, on a control plan
node, list the containers running in the
istio-system
namespace. You should see similar
results to those shown here:
kubectl get deployment -n istio-system 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.
Removing the Istio Module
You can remove a deployment of a service mesh and leave the Kubernetes cluster in place. To do this, you remove the Istio module from the environment.
Use the olcnectl module uninstall
command to
remove the Istio module. For example, to uninstall
the Istio module named myistio
in
the environment named myenvironment
:
olcnectl module uninstall \ --environment-name myenvironment \ --name myistio
The Istio module and its supporting Prometheus and Grafana modules are removed from the environment.
You can confirm the Istio, Prometheus and Grafana modules are
removed using the olcnectl module instances
command. These three modules are no longer listed as modules in
the environment.
You can also confirm the Istio components are removed using the
kubectl
command on a control plane node to
query all deployments running in the
istio-system
namespace. You should see there
are no deployments returned.
kubectl get deployment -n istio-system No resources found in istio-system namespace.