Cloud Manager » Install On-Premises

Cloud Manager can be easily installed in on-premises Kubernetes clusters (e.g. your datacenter or your laptop), or in clusters hosted on public cloud providers other than EInnovator. In this page, we describe several approaches to perform the installation.

If you find issues or need guidance in following the instructions below, feel free to reach out and ask for help at EInnovator Support {support@einnovator.org}.

Installing Modes

Cloud Manager can run in two alternative modes:

• Single User Mode — A single admin user is supported. In this mode, all the functionality is bundled in a single docker image and deployed as a single service.

• Multi-User/Enterprise Mode – Support for multiple users, access control and collaborator management. This is full fledged deployment with several support services (dependencies) being run in addition to the Cloud Manager app. Minimal dependency is a SSO Gateway.

In both modes, Cloud Manager can be run with an embedded data-base or with an external DB (mariaDB).

Quick Install with Docker

SingleUser Mode: Linux/iOS

Simplest mode of running Cloud Manager is in single user mode with an embedded database.

To start using docker in your local machine run command:

docker run -p5005:2500 einnovator/einnovator-devops cm -d

This make Cloud Manager readily available in your machine in URL: http://localhost:5005. When you first open the browser on you need register the admin user by providing a username — password, and email to recover password. Alternatively, you can specify a password when you execute the run command with env variable DB_PASSWORD. In this case the username will be admin and the password the one you specify. No registration is required.

docker run -e DB_PASSWORD=admin123 -p5005:2500 einnovator/einnovator-devops cm -d

The command above run Cloud Manager using an embedded database HSQLDB for local persistence. This is used to store cluster access credentials, catalogs info, and other data. To preserve the state of the database after you shutdown and restart the Cloud Manager with docker a volume needs to be provided from a host directory, as follows:

docker run -v /data/devops:/data -e DB_PASSWORD=admin123 -p5005:2500 einnovator/einnovator-devops cm -d

An alternative, you can run an external DB (such as MySql or MariaDB).

Install MySql:

docker run --name mysql -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=devops -d mysql

(MySQL root password is set as pass, if you want to change that modify accordingly.)

Get IP of MySQL container and assign it to environment var:

export MYSQL_IP="$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' mysql)"

Optionally, check MySql connection:

docker run -it  --rm mysql mysql -h$MYSQL_IP  -uroot -ppass

Start Cloud Manager container in single user mode and setting the environment variable DB_HOST to MySQL local IP:

docker run DB_HOST=$MYSQL_IP -e DB_PASSWORD=pass -p2510:2500  einnovator/einnovator-devops cm -d

If you want to run a specific version of Cloud Manager rather than the latest version, using the corresponding image:

docker run -p5005:2500 einnovator/einnovator-devops:1.0 cm -d

SingleUser Mode: MS-Windows

To run Cloud Manager with Docker on WindowsOS is about the same as in Linux/MacOS. The difference is only in the syntax of some of the shell commands. For the embedded DB case, is actually the same. For external DB, use commands below:

Install MySql:

docker run --name mysql -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=devops -d mysql

Get IP of MySQL container and assign it to environment var:

set /p MYSQL_IP=<docker inspect -f "{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}" mysql

Optionally, check MySql connection:

docker run -it  --rm mysql mysql -h%MYSQL_IP%  -uroot -ppass

Start Cloud Manager container in single user mode (latest version):

docker run einnovator/einnovator-devops:latest cm -e DB_HOST=%MYSQL_IP% -e DB_PASSWORD=pass

Multi-User/Enterprise Dependencies

Cloud Manager is packaged in a single self-contained docker image. When running in single-user this the only image needed. When running in multi-user/enterprise model, Cloud Manager requires other services to be deployed as well. Namely, a set of 4 core reusable middleware (micro-)services part of EInnovator suite are deployed. Specifically:

• SSO Gateway — used to authenticate users and perform parts of the access control. This is done in complement with K8s cluster and space level access-control (e.g RBAC).
• Notification Hub — used to relay notifications to users, via email, sms, and web-UI.
• Document Store — used to store miscellaneous files saved by Cloud Manager and other service (e.g. databases snapshot, icons/avatars, etc.)
• Social Hub — use to store and manage (optional) social comments/discussion channels for Spaces collaborators.
• MySql/MariaDB — like in a single-user mode, a external DB can also be used to save local persistence state, in complement to Kubernetes etdc persistence. This include set of managed clusters, catalogs, managed spaces and deployments, etc.

This dependencies are automatically setup with some installation approaches described below.

Approaches to Installation

The approaches supported to install Cloud Manager and its dependencies include:

• Ytt — Use kubectl and ytt tool, with provided YAML/YTT Manifest files
• Helm — Use helm package manager, with the provided charts
• Manual — Use kubectl, with provided YAML Manifest files and manually edit the files

The resource files needed to install with Ytt and/or manually install are bundled in a common archive file. For Helm, the carts files are downloaded directly by the tool. We describe the Ytt approach first, and Helm approach next, and Manual approach later.

All the approaches have similar end-result. Namely, a set of services and deployments is installed in a new namespace in your cluster. The installed services should made accessible to a web browser (except backing services, like DBs).

There are several ways in Kubernetes to make services accessible. We provide out-of-the-box scripts and configuration files to easily setup most/all of the approaches. Namely:

• Ingresses – assigns DNS host.domain names for each of the services.
• NodePorts – use a common node public IP for all services, and assign a well-defined port to each of the services.
• Port-Forwarding — localhost ports are setup to forward to the K8s service ports, which would otherwise be unreachable.
• LoadBalancer — assigns a public IP to each of the services. Requires cluster support for dynamic provisioning of public IPs.

Download Installation Package

Start by downloading a bundled archive file (.tgz) containing the required installation resources and available in the URL below. You can use a web browser or command-line tool such as wget for this.

Download from URL:

https:://cdn.einnovator.org/solutions/einnovator-install.tgz

Or with wget tool:

wget -O einnovator-install.tgz https:://cdn.einnovator.org/solutions/einnovator-install.tgz

Uncompress the archive and cd to the created folder:

tar -xvf einnovator-install.tgz
cd einnovator/solutions

In WindowsOS, you can use the 7Zip program to expand the compressed tar achive (.tgz) rather than tar. Or you can install a tar for WindowsOS.

Tooling

This installation instructions assume that you have installed some Kubernetes basic tooling. If not, use the links indicated below to install:

• kubectl — K8s main/official command-line tool.
  You can find the instructions to download and install in K8s docs website: https://kubernetes.io/docs/tasks/tools/install-kubectl/
• ytt YAML templates tool. If using a YTT based approach.
  Available for download at https://github.com/k14s/ytt/releases (Linux/MacOS & WinOS). Project page is https://get-ytt.io/.
• Helm package manager. If using the Helm charts approach.
  Project page is https://github.com/k14s/ytt/releases. Instructions to install in Linux/MacOS & WinOS are described in the documentation.

We also assume that you have the default config file for kubectl setup to connect and authenticate with your cluster.

Install with Manifest files & YTT

Start by creating a new namespace named devops. All resource for Cloud Manager and dependencies will be created in this namespace:

kubectl create namespace devops

Below, we describe the scripts that you should run to perform the installation.

Services accessible via Ingresses

To make services accessible via ingresses you need to have DNS configured to route traffic to your cluster. In the instructions below, we represent the domain name for your cluster as *.mydomain.com. If this is not the case, you can opt for one of the other approach such as NodePort, Port-Forward, or LoadBalancer described further below.

Edit configuration file devops-values.yaml with your favorite text editor, and replace all occurrences of the pre-configured default domain devops.nativex.cloud by your domain mydomain.com.

Then run the script that performs the installation:

Linux/MacOS:

./install-devops-with-ingress-ytt.sh

WindowsOS:

install-devops-with-ingress-ytt.bat

You should see the following output:

service/mysql created
deployment.apps/mysql created

service/sso created
deployment.apps/sso created
ingress/sso created

service/notifications created
deployment.apps/notifications created
ingress/notifications created

service/documents created
statefulset.apps/documents created
ingress/documents created

service/social created
deployment.apps/social created
ingress/social created

service/devops created
deployment.apps/devops created
ingress/devops created

all services ready and accessible with ingresses:

NAME            HOST
devops          devops.mydomain.com
documents       documents.mydomain.com
notifications   notifications.mydomain.com
social          social.mydomain.com
sso             sso.mydomain.com

Services accessible via NodePorts

If you don’t have DNS setup to support ingresses, you can opt for using the NodePort approach. In this approach all service will share same IP, but with different ports.

Assuming that node ports 32100, 32101, 32102, 32103, 32104 are available in your cluster not configuration changes are required. Otherwise, edit configuration file devops-values.yaml, and replace the value of the nodeport property for the different serices.

Then run the script that performs the installation:

Linux/MacOS:

./install-devops-nodeport-ytt.sh

WindowsOS:

install-devops-nodeport-ytt.bat

You should see the following output:

service/mysql created
deployment.apps/mysql created

service/sso created
deployment.apps/sso created
ingress/sso created

service/notifications created
deployment.apps/notifications created
ingress/notifications created

service/documents created
statefulset.apps/documents created
ingress/documents created

service/social created
deployment.apps/social created
ingress/social created

service/devops created
deployment.apps/devops created
ingress/devops created

all services ready and accessible in node IP: xx.xx.xx.xx and ports:

NAME            PORT
devops          32104
documents       32102
mysql           <none>
notifications   32101
social          32103
sso             32100

Services accessible via Port-Forward

A simple approach to setup the installation and make services accessible is via “port-forwarding”. In this approach, the services running in the cluster are not accessible directly to the outside world. Rather, the command kubectl port-forward is used to create an HTTP proxy/tunnel that maps selected ports in localhost to service port in cluster.

This approach is most useful if you are running kubernetes in your own laptop, or if for some reason you prefer not to make cluster services accessible to users that don’t have access to your cluster via kubectl. We provide a script to make it easy to setup the port-forward for all the services.

Linux/MacOS:

./install-devops-port-forward-ytt.sh

WindowsOS:

install-devops-port-forward-ytt.bat

You should see the following output:

service/mysql created
deployment.apps/mysql created

service/sso created
deployment.apps/sso created
ingress/sso created

service/notifications created
deployment.apps/notifications created
ingress/notifications created

service/documents created
statefulset.apps/documents created
ingress/documents created

service/social created
deployment.apps/social created
ingress/social created

service/devops created
deployment.apps/devops created
ingress/devops created


all services ready...

NAME            PORT
devops          2500
documents       2020
mysql           3306
notifications   2010
social          2050
sso             2000

to make services accessible via port-fowarding run: devops-port-forward.sh/bat

Next, run the requested script to setup port-forwarding:

Linux/MacOS:

./devops-port-forward.sh

WindowsOS:

devops-port-forward.bat

With the default settings services should be accessible in: `

devops          http://localhost:2510
documents       http://localhost:2120
notifications   http://localhost:2110
social          http://localhost:2150
sso       	   http://localhost:2100

Notice that Cloud Manager UI/API performs user authentication via the SSO Gateway service. So you have an additional security layer, to control access to your cluster. In an organizational context, requiring dev(ops) personal to always run the port-forward script might to provide the best work experience. As such, you might prefer to use one of the other approaches.

Services accessible via LoadBalancer

If your cluster is setup to support dynamic provisioning of (semi-)public IPs, you can use the LoadBalancer approach.

Linux/MacOS:

./install-devops-loadbalancer-ytt.sh

WindowsOS:

install-devops-loadbalancer-ytt.bat

You should see the following output:

service/mysql created
deployment.apps/mysql created

service/sso created
deployment.apps/sso created
ingress/sso created

service/notifications created
deployment.apps/notifications created
ingress/notifications created

service/documents created
statefulset.apps/documents created
ingress/documents created

service/social created
deployment.apps/social created
ingress/social created

service/devops created
deployment.apps/devops created
ingress/devops created


echo sso ready in URL: http://xx.xx.xx.xx
echo notifications ready in URL: http://xx.xx.xx.xx
echo documents ready in URL: http://xx.xx.xx.xx
echo social ready in URL: http://xx.xx.xx.xx
echo devops ready in URL: http://xx.xx.xx.xx

Installed Resources and Customization

All installation approaches install the same services and about the same set set of resources in namespace devops. Namely:

• A single mysql service/deployment that is shared across all services that required a DB. A separate database is created for each service using a mysql startup script. By default, the deployment requests 1Gi of memory, and allocates a 5G volume for permanent storage.
• The core/support services needed by Cloud Manager (sso, notifications, documents, social). By default, each deployment is configured to request 1Gi of memory. Service documents additionally allocates a 5Gi volume for permanent storage.
• The Cloud Manager service, installed with under name devops. By default, requests 3Gi of memory.

You can change any of the setting by editing further file devops-value.yaml.

Verifying installation

To confirm that all resources have been created successfully (deployments, statefulsets, services, pods, persistent volumes, configmaps, etc.), you can run the command:

kubectl -n devops get all

You should see an output similar to the one below (omitting pre-existing cluster-level resources, if any):

NAME                                 READY   STATUS    RESTARTS   AGE
pod/devops-8fb9444fb-rfl9t           1/1     Running   0          20m
pod/documents-0                      1/1     Running   0          11h
pod/mysql-6d7db4d5b9-w56mc           1/1     Running   0          24m
pod/notifications-5dd7869b8d-rpg6k   1/1     Running   0          21m
pod/social-94f5cc48-pt82h            1/1     Running   0          20m
pod/sso-6d8898f98-2fhtb              1/1     Running   0          21m

NAME                    TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
service/devops          ClusterIP   10.245.185.123   <none>        2500/TCP   11h
service/documents       ClusterIP   10.245.12.222    <none>        2020/TCP   11h
service/mysql           ClusterIP   10.245.84.240    <none>        3306/TCP   14h
service/notifications   ClusterIP   10.245.58.215    <none>        2010/TCP   12h
service/social          ClusterIP   10.245.163.134   <none>        2050/TCP   12h
service/sso             ClusterIP   10.245.96.52     <none>        2000/TCP   12h

NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/devops          1/1     1            1           20m
deployment.apps/mysql           1/1     1            1           24m
deployment.apps/notifications   1/1     1            1           21m
deployment.apps/social          1/1     1            1           20m
deployment.apps/sso             1/1     1            1           21m

NAME                                       DESIRED   CURRENT   READY   AGE
replicaset.apps/devops-8fb9444fb           1         1         1       20m
replicaset.apps/mysql-6d7db4d5b9           1         1         1       24m
replicaset.apps/notifications-5dd7869b8d   1         1         1       21m
replicaset.apps/social-94f5cc48            1         1         1       20m
replicaset.apps/sso-6d8898f98              1         1         1       21m

NAME                         READY   AGE
statefulset.apps/documents   1/1     11h

Setup services after Installation

Once installation is completed you should open the SSO service in the web-browser and start by register the administrator user.

The installation script output show you the URLs of the installed services. For example, if are using ingresses, should be of the form http(s)://sso.mydomain.com. Once the admin user is setup, the profile page is shown.

Click on Cloud Manager icon on the left-side toolbar or tray. This navigates to the Cloud Manager UI. You need to perform one more step before starting to use Cloud Manager to deploy app and services in your cluster. Configure the first cluster. Click on button Add Cluster, and follow the instructions on adding cluster in the Cloud Manager documentation page: Cluster Administration

Installation with Helm Charts

To install Cloud Manager using Helm, start by defining a Helm repository where the charts can be download from. Use the command below for this.

helm repo add ei https://cdn.einnovator.org/charts

The added helm repository was named ei (any other name could be used), and charts are pulled from https://cdn.einnovator.org/charts.

You can also run the command below to make sure you have all locally cached charts updated:

helm repo update

Next, create a namespace where you want the installation to be done (if you have not have done that yet). The command below create a namespace named devops (any other name could be used as well).

kubectl create ns devops

Install in Single-User Mode

To install Cloud Manager in single-user mode (less footprint), run the chart installation with command:

helm -ndevops install cm ei/einnovator-devops

This create a new Helm release with name cm (you can selected another name, if you want). The name of the chart being installed is einnovator-devops and the ei/ prefix is simply the name of the helm repository where the image is pulled. Installation is done in namespace devops.

To expose the installed service, there are several possibilities. The simplest one to get started is to use kubectl port-forward.

Linux/MacOS:

export POD_NAME=$(kubectl get pods -ndevops -l "app.kubernetes.io/name=einnovator-sso,app.kubernetes.io/instance=sso" -o jsonpath="{.items[0].metadata.name}")
kubectl --namespace test port-forward $POD_NAME 5000:80

WindowsOS:

kubectl get pods -ndevops -l "app.kubernetes.io/name=einnovator-sso,app.kubernetes.io/instance=sso" -o jsonpath="{.items[0].metadata.name}" > sso-pod.txt
set /p POD_NAME = < sso-pod.txt
kubectl -ndevops port-forward $POD_NAME 5000:80

By default, Cloud Manager uses an embedded database to store configuration data, such as cluster meta-data. If you want to preserve data across shutdowns and restarts of Cloud Manager, you should enable the creation and mounting of a persitent volume. This can be done by setting the chart option persistence.data.enabled to true at installtion time. As follows:

helm -ndevops install cm ei/einnovator-devops --set persistence.data.enabled=true

A persistence volume of 1Gi of storage is created. For a larger storage use setting persistence.data.size=5.

Alternatively, Cloud Manager can run using a MySQL/MariaDB database for data-storage. To install with MariaDB use the following:

helm -ndevops install cm ei/einnovator-devops --set mariadb.enabled=true

Install in Multi-User/Enterprise Mode

Running Cloud Manager in multi-user/enterprise mode offers some extra functionality, such as collaboration, invitations, simplified access-control, and social comments / discussion in space channels. This requires however the installation of some extra services as dependencies, and the installation footprint is necessarily larger.

Install SSO Gateway Dependency

Start by installing the main dependency for Cloud Manager — the SSO Gateway – using a helm chart:

Install SSO Gateway:

helm -ndevops install sso ei/einnovator-sso

Next make the SSO Gateway reachable from outside the cluster. The simplest way is to used kubectl port port-forward:

Linux/MacOS:

export POD_NAME=$(kubectl get pods -ndevops -l "app.kubernetes.io/name=einnovator-sso,app.kubernetes.io/instance=sso" -o jsonpath="{.items[0].metadata.name}")
kubectl --namespace test port-forward $POD_NAME 5000:80

WindowsOS:

kubectl get pods -ndevops -l "app.kubernetes.io/name=einnovator-sso,app.kubernetes.io/instance=sso" -o jsonpath="{.items[0].metadata.name}" > sso-pod.txt
set /p POD_NAME = < sso-pod.txt
kubectl -ndevops port-forward $POD_NAME 5000:80

Install Cloud Manager

To install Cloud Manager in multi-user/enterprise mode with an helm chart run:

helm -ndevops install cm-ee ei/einnovator-devops --set sso.server=http://localhost:5000

Notice that Cloud Manager needs a web url for the SSO Gateway to perform OAuth2 browser based user authentication. This is done be setting the chart variable sso.server. In the example above, we assume localhost:5000 via port-forwarding. If you setup an ingress that the url needs to be changed accordingly. The setting sso.server also makes Cloud Manager to run automatically in multi-user mode.

Install Other Dependencies

In addition to the SSO Gateway, three other dependencies can be installed (as described above in this page). You can use a similar approach as done above with the SSO Gateway, to install these other dependencies as Helm charts. The commands are summarized below. Alternatively, you might prefer to use the YTT + bash/bat scripts approach described above to install Cloud Manager in multiuser mode, rather than with helm.

helm -ndevops install notifications ei/einnovator-notifications
kubectl -ndevops port-forward pod-xxx 5001:80

helm -ndevops install documents ei/einnovator-documents
kubectl -ndevops port-forward pod-xxx 5002:80

helm -ndevops install social ei/einnovator-social
kubectl -ndevops port-forward pod-xxx 5003:80

In the above, pod-xxx should be replaced with the corresponding pod name.

helm -ndevops install cm-ee ei/einnovator-devops --set sso.server=http://localhost:5000, notifications.server=http://localhost:5001, 
documents.server=http://localhost:5002, social.server=http://localhost:5003

The above command installs Cloud Manager configured with the full set of dependencies, including the SSO Gateway, the Notification Hub, the Document Store, and the Social Hub.

Manual Install from Manifest files

If for whatever reason you can’t or don’t want to use YTT tool, you can perform the installation od Cloud Manager and each of its dependencies by relying only on the plan K8s manifest files, your text editor, and kubectl.

We provide manifest files to configure resources for each services and scripts to apply them. Review this manifest files and modify them with your favorite text editor. For example, for the ingresses based approach you should change the domain name, and replace all occurrences in all YAML manifest files of the pre-configured default domain native.cloud by your domain mydomain.com.