---
# System prepended metadata

title: Sensedia Service Mesh v1.0.0.0

---

# Sensedia Service Mesh v1.0.0.0


![](https://i.imgur.com/pXaW7nx.jpg)


# Installation guide
> [time=Tue, Mar 23, 2021 4:24 PM]
> [TOC]
> 


## Requirements
* A Kubernetes cluster on AWS (EKS).
   * Version 1.17 is recommended, since it's the one Sensedia used for testing.
* Helm (version 3 or later).
* A namespace called sensedia-system.
   * `$ kubectl create ns sensedia-system`


### AWS

During the installation process you will have to interact with AWS multiple times, so it will be great if you have **AWS CLI** installed and configured. You can check the [**AWS CLI Docs**](https://aws.amazon.com/cli/) to help you with that.

Another thing to keep in mind is that you need to setup your Kubectl context to point to the EKS cluster that you have created before.

To add the cluster context to your local Kubectl, **AWS CLI** has this command: 

```shell=
$ aws eks update-kubeconfig --name example
```

You can check [this documentation](https://docs.aws.amazon.com/cli/latest/reference/eks/update-kubeconfig.html) to learn more about this command.

And a final tip: you can install Kubectx to switch quickly between cluster contexts. You can check it out by going to the [Kubectx Github repository](https://github.com/ahmetb/kubectx).


### Dependencies

Sensedia Mesh requires the following tools to be available in the cluster:
* **Istio**
   * Versions from 1.7.x to 1.9.x are supported.
   * The installation profile is totally open to the user's choice, but Istio doesn't recommend using the Demo profile in production.
* **Kiali**
   * Version 1.22 is required for Istio 1.7.x.
   * Version 1.26 is required for Istio 1.8.x.
   * Version 1.29 is required for Istio 1.9.x.
* **Jaeger**
   * Version 1.18 is required for Istio 1.7.x.
   * Version 1.20 is required for Istio 1.8.x and Istio 1.9.x.
* **Prometheus**
    * Version 11.16.2 is required for Istio 1.8.x and Istio 1.9.x.
    * Version 11.7.0 is required for Istio 1.7.x.

It's important to keep the required versions installed because we tested them for their respective Istio version. If you choose to use another version, keep in mind that we haven't tested it and, therefore, it's unsupported by Sensedia Mesh.

All the addons can be installed as a bundle with Istio. Please refer to the [official documentation](https://istio.io/latest/docs/ops/integrations/) for each tool to get detailed instructions on how to install them. 

You can also install other addons, such as Grafana, but Sensedia Mesh doesn't require them in order to work properly.

To install Istio you can follow the installation guides on [Istio Docs](https://istio.io/latest/docs/setup/install/). We believe it's easiest to follow the ***Istioctl*** installation type.


---


### Helm setup
Before installing Sensedia Mesh, add the Sensedia repo to your Helm installation using the following command:

`$ helm repo add sensedia http://sensedia-helm-charts-s3.s3.amazonaws.com`

To make sure the repo has been set up correctly, run the following command and look for sensedia in the list:

`$ helm repo list `

Now, verify if the charts are returned when using the `search repo` command:

```shell=
$ helm search repo

NAME                                    CHART VERSION   APP VERSION     DESCRIPTION
sensedia-dev/sensedia-mesh-init         1.0.0           1.0.0.0         A Helm chart for install Sensedia Mesh CRDs in ...
sensedia-dev/sensedia-mesh-manager      1.0.0           1.0.0.0         A Helm chart for install Sensedia Mesh manager ...
sensedia-dev/sensedia-mesh-operator     1.0.0           1.0.0.0         A Helm chart for install Sensedia Mesh operator...
```


# Sensedia Mesh CRDs
	
## Default install
Finally, we can simply install with the default values. For that, you just need to type the default Helm install passing the mesh-init chart name.


Install Sensedia Mesh Init containing the Custom Resource Definitions:


```shell=
$ helm install mesh-init sensedia/sensedia-mesh-init -n sensedia-system --version 1.0.0
```

### Verifying the installation

To make sure that the required Custom Resource Definitions are properly installed, you can run the command below and verify if all 5 Sensedia CRDs are installed:

```shell=
$ kubectl get crds | grep sensedia


apiauthentications.security.sensedia.com     2021-03-23T19:06:46Z
meshes.management.sensedia.com               2021-03-23T19:06:46Z
policies.security.sensedia.com               2021-03-23T19:06:46Z
releases.networking.sensedia.com             2021-03-23T19:06:46Z
shadowtraffics.networking.sensedia.com       2021-03-23T19:06:46Z
```
---


# Sensedia Mesh Operator

In order to install the Operator, as with the **Sensedia Mesh Init**, you can install with the default variables or modify them with your desired values.

## Default install

To install ***mesh-operator*** with the default values, type the command below into your terminal:


```shell=
$ helm install mesh-operator sensedia/sensedia-mesh-operator -n sensedia-system --version 1.0.0
```

## Custom install

For a custom installation, you can check the table below for the keys and their respective types and default values.

### Charts default values

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| pod.annotations | object | `{}` (The value is evaluated as a template) | Annotations to be added to pods |

```shell=
$ helm install mesh-operator -f values.yaml sensedia/sensedia-mesh-operator -n sensedia-system
```    

## Verifying the installation

To make sure that the Operator is correctly installed you can run the command bellow and verify the response. The result will show a deployment called **operator-controller-manager** and it must have the status `READY`.

```shell=
$ kubectl get deployment operator-controller-manager -n sensedia-system 

NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
operator-controller-manager   1/1     1            1           19h
```   

Also verify if there is an operator pod running:

```shell=
$ kubectl get pods -n sensedia-system                                   

NAME                                          READY   STATUS    RESTARTS   AGE
operator-controller-manager-6b9677d4f-9d7kd   2/2     Running   0          16h

```

---


# Sensedia Mesh Manager

To perform a custom installation, you can check the table below for the keys and their respective types and default values. In this case, we have to set up the **host** for **mesh-manager Ingress**, so you will need to overwrite some keys listed in the table.

## Charts default values

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| ingress.annotations | object | `{}` (The value is evaluated as a template) | Annotations to be added to ingress |
| ingress.host | string | `localhost` | Domain name where Sensedia Mesh will be exposed |
| manager.apiManagerUrl | string | `""` | Sensedia API Manager URL, required for Sensedia Authentication |
| manager.jaeger.scheme | string | `"http"` | Jaeger scheme |
| manager.jaeger.url | string | `"tracing.istio-system:80"` | Jaeger URL |
| manager.kiali.auth.passphrase | string | `"admin"` | Kiali password |
| manager.kiali.auth.strategy | string | `"anonymous"` | Kiali authentication strategy (anonymous or login) |
| manager.kiali.auth.username | string | `"admin"` | Kiali username (just if you are using Kiali login strategy) |
| manager.kiali.scheme | string | `"http"` | Kiali scheme |
| manager.kiali.url | string | `"kiali.istio-system:20001"` | Kiali URL |
| manager.logLevel | string | `"default"` | Log Level |
| manager.oauth.client.id | string | `"sensedia-mesh-manager"` | OAuth2 Client ID |
| manager.oauth.client.secret | string | `"sensedia-mesh-manager"` | OAuth2 Client Secret (for OpenID, if enabled) |
| manager.openid.baseUrl | string | `""` | OpenID Provider Issuer Base URL |
| manager.openid.enabled | bool | `false` | Specifies whether OpenID Authentication should be enabled |
| manager.openid.extraParams | string | `""` | Optional list of query params used in OpenID authentication URL, key=value space separated |
| manager.openid.scopes | string | `""` | Optional list of scopes, separated by semicolon |
| manager.pod.annotations | object | `{}` (The value is evaluated as a template) | Annotations to be added to manager pods |
| manager.replicaCount | int | `1` | Number of manager replicas desired |
| manager.sensediaAuth.enabled | bool | `true` | Specifies whether Sensedia Authentication should be enabled |
| manager.service.manager.annotations | object | `{}` (The value is evaluated as a template) | Annotations for manager service |
| webUI.pod.annotations | object | `{}` (The value is evaluated as a template) | Annotations to be added to web UI pods |
| webUI.replicaCount | int | `1` | Number of web UI replicas desired |
| webUI.service.annotations | object | `{}` (The value is evaluated as a template) | Annotations for web UI service |

## Create a host name for Ingress<br>

An important part when installing the mesh-manager chart is to set a host for Ingress. If it's not set, the Sensedia Mesh front-end will not be externalized from your cluster. In addition, you will probably want to use secure connection on Ingress, and for that you will need to set up the certificates for **HTTPS**.

The code example below shows a typical installation on an **EKS** cluster. That is, it works only on AWS. The values overwrite the host name and set up the certificates for secure connection.

```yaml=
ingress:
  host: sensedia-test.sensedia-eng.com
  tls: true
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/certificate-arn: <arn-pointing-to-your-acm-certificates>
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 443}]'

```

For this example, we choose a host name for Ingress and after the installation we set up **Route 53** to point to our new load balancer host, which is created after we run the install command.

![](https://i.imgur.com/FXYZNe5.png)


We recommend that you use AWS Certificate Manager to keep your HTTPS certificates and reference the ARN on Ingress annotations. If you want to learn more about the annotations we use in this example, you can check the [AWS Docs for Load Balancer Controller](https://kubernetes-sigs.github.io/aws-load-balancer-controller/guide/ingress/annotations/).


Note that Ingress customization is up to the user and the `values.yaml` file may differ from intallation to installation. It depends on the cluster environment and which customizations you will need for Ingress.


## Authentication 

Currently, the user has two authentication methods: 
1. if you are a Sensedia API Platform client, you can log in directly from the API Platform using the **Addons** button on the top header; 
2. you can enable **OpenID** integration on the **mesh-manager** Helm. This setup can be done in the `values.yaml` file during chart installation or by directly editing the **manager** ConfigMap after the installation.

### Sensedia Auth

In order to enable the Sensedia API Platform authentication, you need to overwrite the `manager.sensediaAuth.enabled` and `manager.apiManagerUrl` variable in `values.yaml`, ending up with something like this:

```yaml=
...

  sensediaAuth:
    enabled: true
  apiManagerUrl: "https://your-company-manager.sensedia.com"
...
```


---


### OpenID Connect

For OpenID Connect, you will need to gather these pieces of information from your provider:

* Client Secret
* Client Id
* Provider URL


With this informaton in hands, you can just override the OAuth and OpenID variables in `values.yaml`, ending up with something like this:

```yaml=
...

  oauth:
    client:
      # manager.oauth.client.id -- OAuth2 Client ID
      id: "your-app-client-id"
      # manager.oauth.client.secret -- OAuth2 Client Secret
      secret: "your-app-client-secret"

  openid:
    # manager.openid.enabled -- Specifies whether OpenID Authentication should be enabled
    enabled: true
    # manager.openid.baseUrl -- OpenID Provider Issuer Base URL
    baseUrl: "https://accounts.google.com"
    # manager.openid.scopes -- Optional list of scopes, space separated
    scopes: "profile;email"
    # manager.openid.extraParams -- Optional list of query params used in OpenID authentication URL, key=value space separated
    extraParams: "hd=sensedia.com"
    
...
```

Note that `scopes` and `extraParams` are optional, but we use `scopes` to provide for a better user experience and `extraParams` to restrict the users that are part of sensedia on Google Apps.



## Custom install

```shell=
$ helm install mesh-manager -f values.yaml sensedia/sensedia-mesh-manager -n sensedia-system --version 1.0.0
```


### Verifying the installation

After the `helm install` command, you need to check if the installation process was successful. To do that, check the deployments and the running pods, as in the Operator post-install check [above](#Verifying-the-installation1).

1. **Check the deployments**
   
```shell=
$ kubectl get deployments.apps -n sensedia-system 
NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
manager                       1/1     1            1           33m
operator-controller-manager   1/1     1            1           33m
web-ui                        1/1     1            1           33m
```

If everything is up and running, proceed to the next step; if not, try to repeat the process or get in touch with Sensedia support.

2. **Check the running pods**

```shell=
$ kubectl get pods -n sensedia-system     
k get pods -n sensedia-system     
NAME                                          READY   STATUS    RESTARTS   AGE
manager-6c4bb65584-bcmqf                      1/1     Running   0          35m
operator-controller-manager-6b9677d4f-8zlkt   2/2     Running   0          35m
web-ui-5cf8b66767-s56p9                       1/1     Running   0          35m 
```

Note that the status of `manager` and `web-ui` is `Running`.

3. **Access the web-ui**

Get the mesh-manager ingress with this command:

```shell=
$ kubectl get ingress sensedia-mesh-manager -n sensedia-system        
NAME                    HOSTS                                                         ADDRESS                                                                  PORTS     AGE
sensedia-mesh-manager   manager-sensedia-mesh-api-platform-testing.sensedia-eng.com   e1a0fd59-sensediasystem-se-6385-1406950746.us-east-1.elb.amazonaws.com   80, 443   43m
```

The host has to match the host that you configured previously when installing the manager. Then, you can access the web-ui through your browser.

![](https://i.imgur.com/GI6xUvl.png)

If all worked well, you will see all your meshes on the first page.

# Next steps

Now that you have installed Sensedia Mesh, you can check out the official Mesh user guide on [Sensedia Docs](https://docs.sensedia.com).

