2. Install and Setup

2.1. Minimum Node Requirements

  • All Kubernetes nodes should be DNS resolvable.

  • All Kuberenetes node should have minimum 4GB memory.

  • Make sure Kubernetes cluster nodes have 40GB storage available for ROBIN in the /home/robinds folder.

2.1.1. Port Requirments on Cloud Platforms

If you are deploying the ROBIN operator on any Cloud Platform, the following ports are required to be accessible on the target hosts for the installation to succeed and for the ROBIN to operate correctly:

Ports

Description

29451 - 29463

ROBIN Services

8300 - 8301

Consul Ports

5432

Postgres

Note

When creating each rule to make the port accessible ensure that the protocol is TCP. In addition the cloud nodes should be able to communicate with one another on all ports via the IPv4 protocol.

  • Ports can be made accessible via security groups on AWS. Details on how to create security groups can be found here.

  • Ports can be made accessible via firewall rules on GCP. Details on how to create appropriate firewall rules can be found here.

  • Ports can be made accessible via network security groups on Azure. Details on how to create network groups can be found here.

2.1.2. Environment Specific Prerequisites

  • Prerequisites for installing ROBIN on a GKE cluster can be found here.

  • Prerequisites for installing ROBIN on an OpenShift cluster can be found here.

2.2. QuickStart Installation

A QuickStart tar file can be found at https://get.robin.io/download in order to deploy the ROBIN operator and custom resource on an existing Kubernetes installation. Detailed below are the steps to utilize the file:

  • Download the appropriate tar file for your environment and extract the contents onto the machine where ROBIN is to be installed.

  • Ensure all ROBIN prerequisites are met for the environment you are installing in. Detailed information on these prerequisites can be found here.

  • Install ROBIN by running the following:

    $ /bin/bash install-robin.sh
    

    This will first validate that your environment is ready for ROBIN. After this check is successful, it will deploy the ROBIN operator as well as launching the ROBIN custom resource.

    Note

    Based on your environment you might be prompted for additional information whilst running the script such as your Access key when deploying on AWS. To avoid this edit the appropriate robin-<env>.yaml with values for the necessary options. For more details check the list of installation options documented here.

  • Verify the ROBIN pods are running and ready by running the command:

    $ kubectl describe robinclusters -n robinio
    

    Under the Status section there should be a field labelled Phase, its value should be “Ready”.

  • Set the environment variable ROBIN_SERVER to the IP Address of your master node by running the command:

    $ source ~/robinenv
    
  • Activate your ROBIN cluster license by running the following commands:

    $ robin login admin --password Robin123
    
    $ robin license activate <USERID>
    

    Note

    You can get your User ID after registering on https://get.robin.io. The second command will only work if the host on which the ROBIN client is running on has an internet connection. If this is not the case please retrieve the license key by following the instructions at https://get.robin.io/activate and apply it using the command ‘robin license apply <key>’.

  • To get started check out the example workflow located here.

  • To uninstall ROBIN run the following command:

    $ /bin/bash install-robin.sh --uninstall
    

2.3. Installation on Google Kubernetes Engine

The instructions in this section only apply if you want to do a custom installation on GKE and have not already installed ROBIN using the QuickStart installation method (detailed here). Skip this section if you have installed using the QuickStart method.

2.3.1. Prerequisites

  • Ensure the User installing ROBIN Storage is the Cluster Administrator in kubernetes cluster.

    For GKE/CSP installation, run following commands to add user as Cluster Administrator:

    $ account=$(gcloud info | grep Account  | awk -F'[\\[\\]]' '{print $2}')
    
    $ kubectl create clusterrolebinding robin-cluster-admin-binding --clusterrole=cluster-admin --user=$account
    

    Note

    For GKE installations, ROBIN needs nodes with Ubuntu image and cluster with “Compute Engine: Read Write” and “Storage: Full” API being enabled. Compute Engine API access is required to make sure disks are always accessible and easy way to provision disks within ROBIN. Storage API access is required for backing up applications in GCS. You can select “Access scope” as one of the following while creating GKE cluster.

    • “Set access for each API” and select individual permissions OR

    • “Allow full access to all Cloud APIs”

2.3.2. Installation

After the prerequisites product installation is as simple as running the following command:

$ kubectl create -f robin.yaml

Note

ROBIN Storage software installs natively on any Kubernetes distribution through the use of the command detailed in step 2. Distribution-specific differences are incorporated into the installer so as to deliver a smooth and frictionless install experience.

To complete your installation activate your license by visiting https://get.robin.io/activate

2.4. Installation on OpenShift

The instructions in this section only apply if you want to do a custom installation on an OpenShift cluster and have not already installed ROBIN using the QuickStart installation method (detailed here). Skip this section if you have installed using the QuickStart method.

Below are the steps for deploying the ROBIN operator on Openshift using two methods

  • Using a single yaml file to deploy all necessary objects.

  • Using the Operator Lifecycle Manager to deploy the operator with the sourceType being a ConfigMap.

Note

Throughout the documentation below the ‘oc’ command is equivalent to the ‘kubectl’ command.

2.4.1. Prerequisites

The only prerequisite for deploying ROBIN on an existing OpenShift Cluster is that the Kubernetes user who is running the kubectl or oc commands detailed below must have the cluster-admin role.

2.4.2. Installation via Yaml

With all the prerequisites met product installation is as simple as:

  • Create the complete ROBIN Openshift yaml file using content from here.

  • Run the following command:

$ oc create -f robin.yaml

Note

Please see the install options detailed below and edit the custom resource section of yaml file appropriately to adjust your deployment.

2.4.3. Installation via OLM

Outlined below are the steps required to install the ROBIN operator via the OLM (Operator Lifecycle Manager).

  • Create a new namespace to deploy the necessary objects by running the following command:

    $ oc create namespace robinio
    
  • Construct a ConfigMap manifest that follows the structure, content and formatting of the example showcased here.

    Using this create the ConfigMap object by running the command:

    $ oc create -f <robin-config-map>.yaml
    

    You can verify that it exists by running:

    $ oc get configmap
    
  • Construct a CatalogSource manifest that follows the structure, content and formatting of the example showcased here. It should point to the ConfigMap created previously.

    Using this create the CatalogSource object by running the following command:

    $ oc create -f <robin-catalog-source>.yaml
    

    You can verify that it was successfully created by running:

    $ oc get catalogsource
    

    You can also verify that the OLM has created the ROBIN registry pod and that it is successfully running via the command:

    $ oc get pods
    
  • Construct a OperatorGroup manifest that follows the structure, content and formatting of the example showcased here.

    Using this create the OperatorGroup object by running the following command:

    $ oc create -f <robin-operator-group>.yaml
    

    You can verify that it was successfully created by running:

    $ oc get operatorgroup
    

    Note

    An OperatorGroup must exist within the namespace prior to creating the Operator Subscription. List all target namespaces the ROBIN operator should watch. If you want the ROBIN operator to watch all namespaces, completely omit the spec section from the OperatorGroup manifest.

  • Construct a Subscription manifest that follows the structure, content and formatting of the example showcased here.

    Using this create the Subscription object by the running the following command:

    $ oc create -f <robin-operator-subscription>.yaml
    

    Verify that it has been created by running:

    $ oc get sub
    

    In addition verify that OLM has also created the CSV and Operator pod via the following commands:

    $ oc get csv
    $ oc get pods
    
  • Create a CustomResource manifest that follows the structure, content and formatting of the example showcased here.

    Using this create the CustomResource object by the running the following command:

    $ oc create -f <robin-custom-resource>.yaml
    

    This should successfully deploy the ROBIN operator on your OpenShift cluster.

2.5. Install Options

apiVersion: robin.io/v1alpha1
kind: RobinCluster
metadata:
  name: robin
  namespace: robinio
spec:
  image_version: <docker-image-name-version>
  k8s_provider: gke|openshift|eks|aks|pks|robin|opensource
  host_type: gcp|physical|aws|azure
  node_selector: <node selector>
  image_provisoner: <robin-storage-app-version>
  source: <operatorhub|gcpmarketplace>
  # kms: robin/google
  # kms_keyring: <keyring_name>
  # options:
    # access_key: <access_key>
    # secret_key: <secret_key>
    # tenant_id: <tenant_id>
    # app_id: <app_id>

image_version

required

Image name/version in your docker registry

k8s_provider

required

Kubernetes Distribution name. One of the following values are
supported :
- gke: Google Kubernetes Engine
- openshift: Redhat Openshift
- aks: Azure Kubernetes Service

host_type

required

The type of host on which the Kubernetes distribution
is running. One the following values is supported
- gcp: Google Cloud Platform
- physical: Running in private on-prem datacenter
- aws: aws
- azure: azure

node_selector

optional

Specify a selector to pick the nodes on which ROBIN Storage should be installed. For example:
- For OpenShift v3, “node-role.kubernetes.io/compute=true”
- For OpenShift v4, “node-role.kubernetes.io/master=’‘”

image_provisoner

required

Version of the ROBIN Storage application in the form of robinsys/csi-provisioner:<version>
where version is:
- v0.4.1_robin if the Kubernetes version is in between v1.11-12
- v1.0.0_robin if the Kubernetes version is newer than or equal to v1.13

kms

optional

If external key management needs to be provided. Valid values
robin/google.

kms_keyring

optional

Keyring name if google KMS is selected

source

optional

Source of deployment yaml. Valid values are:
- operatorhub: OperatorHub.io
- gcpmarketplace: Google Cloud Platform Marketplace
Only specify this value if ROBIN is deployed through one of these portals.

access_key

optional

Access key linked to your user account (if applicable), necessary when deploying ROBIN on a Cloud Platform.

secret_key

optional

Secret key linked to your user account (if applicable), necessary when deploying ROBIN on a Cloud Platform.

app_id

optional

Azure application id. Necesary when depolying ROBIN on Azure.

tenant_id

optional

Azure tenant id. Necesary when depolying ROBIN on Azure.

Note

If deploying on EC2 hosts, the access_key and secret_key variables are not mandatory if the aforementioned hosts are configured with the appropriate IAM Profiles.

2.6. Verify Installation

Once the installation is complete, you can get details about robin cluster by running

$ kubectl describe robinclusters -n robinio

You should see the status of all the ROBIN Nodes as “Ready”.

Note

If you have deployed ROBIN in different namespace then use that namespace in above command and in all the commands in this document which has “robinio” namespace in it.

You can also see ROBIN Storage class is added.

$ kubectl get sc

Use the “Connect Command” value from the above output to connect to ROBIN pod. For example,

$ kubectl exec -it robin-rnnnd -n robinio bash

After logging into ROBIN container you can login as “admin” user. Default password is ‘Robin123’

$ robin login admin

You can verify the installation by running

$ robin host list

2.7. ROBIN Client

You can also download ROBIN client on your Linux or macOS machine. You can run following command

$ kubectl describe robinclusters -n robinio

The output will have command to get robin client. The output will look like following

$ curl -k https://1.2.3.4:29451/api/v3/robin_server/client/linux -o robin

You can also get the IP of the master server from the output:

Master IP:    35.233.222.105

Run the curl command as mentioned above. After the file has been downloaded to your current working directory, make it an executable via the command:

$ chmod +x robin

Set the ROBIN_SERVER environment variable with the value of “Master IP”

$ export ROBIN_SERVER=35.233.222.105

Before you can use the CLI you will have to login with the username and password (by default it is admin/Robin123). To log in run the following command:

$ robin login <username>

Followed by entering the password when prompted.

2.8. ROBIN License Activation

After installing ROBIN software on any platform, a notice will appear stating that the ROBIN license will expire in approximately two days whenever a command is run. This is an indication that the license is yet to be activated. In order to avoid a cluster lockdown you can activate your ROBIN cluster via one of the following methods.

If the license is not activated your ROBIN cluster will be locked after the allocated time.

2.8.1. Web License Activation

Activate your ROBIN license by clicking the following link: https://get.robin.io/activate. After following the instructions detailed on the website your ROBIN license should be activated and your cluster ready to use.

Note

You will be asked to provide the ROBIN cluster id when activating your license. This can be discovered by running the ‘robin license id’ command via the client or when you are connected to the ROBIN pod. In addition you can apply the generated key via the command ‘robin license apply <key>’.

2.8.2. CLI License Activation

In order to activate your license via the CLI, first register here and retrieve your User ID. Next run the following command:

$ robin license activate <USERID>

This will activate your ROBIN license and ensure your cluster ready to use.

2.9. High Availability of ROBIN Services

ROBIN manages High Availability of all management services that are deployed as part of ROBIN installation. ROBIN pods are deployed as part of a daemonset. Some pods are designated to run master services. ROBIN configures 3 of these pods as manager pods which can host these master services.

  • If one of the kubernetes node goes down, ROBIN seamlessly starts master services on other manager pods.

  • If pod hosting ROBIN master services is removed from kuberenetes cluster, ROBIN will automatically designate another pod as manager pod so that it always has 3 master pods.

2.10. Disk Management

ROBIN discovers the disks attached to the kuberenetes nodes and uses them for providing storage to the application.

To discover new disks attached to the hosts, run following command.

$ robin host probe [<hostname>|--all] --rediscover

To verify new disks are discovered, run following command

$ robin disk list

To add new disks to Robin storage, run

$ robin host add-role <hostnames> storage [--disks <disks>]

hostnames: List of comma seperated list of hostnames <Required> disks : List of comma seperated wwn of disks <Optional>. WWNs are listed as part of “robin disk list” output.

If no “–disks” parameters provided, robin will use all the newly discovered disks.

In addition ROBIN makes sure that re-attachable disks (Disks which can be attached to any host eg. SAN/EBS/GCP disks) are always accessible even in the event of kubernetes node failure. When a kuberenetes node goes down, ROBIN detaches the disk from failed node and attaches it to a healthy node so that application data remains accessible.

2.10.1. Disk Management On GKE

ROBIN can provision disks in GKE to use for ROBIN Storage. eg. To create 100 GB disk in GKE, run following command

$ robin disk create <hostname> --type <pd-standard | pd-ssd> --size 100

These disks will be attached automatically and auto discovered by ROBIN so they will be ready to use straightaway.

Note

Due to ROBIN’s advanced feature to make sure disks are always accessible, it needs disks permission to be selected while deploying cluster on GKE.

2.10.2. Disk Management On Google Anthos

On the Google Anthos platform, you can add disks to cluster VMs from vSphere and ROBIN will automatically use them for storage.

2.10.3. Disk Management On AWS

ROBIN can provision disks in AWS to use for ROBIN Storage. eg. To create 100 GB disk in AWS, run following command

$ robin disk create <hostname> --type <gp2 | io1 | st1> --size 100

These disks will be attached automatically to the EC2 instances and auto discovered by ROBIN so they will be ready to use straightaway.

Note

Due to ROBIN’s advanced feature to make sure disks are always accessible, IAM Profiles associated with the host (or permissions granted to a user) must contain all Volume write and list actions.

2.11. User Management

You must be logged into the ROBIN cluster to take advantage of ROBIN Storage data management capabilities. You can log in as the cluster administrator (an admin account is created during installation), or you can log in as a regular user (after the cluster administrator creates a user account for you). This is explained in more detail in the User Management section.

2.12. Uninstalling ROBIN

For Uninstalling ROBIN from Kubernetes cluster, run following command:

$ kubectl delete -f robin.yaml

2.12.1. Deleting objects created by OLM

If the ROBIN operator was deployed on an OpenShift cluster via the OLM method described above, run the following command to delete all the objects created within the ‘robinio’ namespace:

$ oc delete namespace robinio

2.12.2. Deleting objects created by QuickStart

If the ROBIN operator was deployed on an existing Kubernetes cluster via the QuickStart method described previously, one can run the following command to uninstall:

$ ./intall-robin --uninstall

Note

The install-robin script is shipped within the QuickStart tar file.

2.13. Disabling Telemetry

With every installation ROBIN collects usage statistics to improve overall user experience with the product. The telemetry data collected is strictly anonymous and does not contain any hostnames or application names.

Details such as the number of hosts in the ROBIN cluster and their individual configurations (CPU, memory and storage space statistics) are aggregated and collected. In addition information about the PVs and storage classes available on the cluster is saved. In order to disable telemetry data collection, run the following command:

$ robin config update cluster enable_telemetry False