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.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
Activate your license by visiting https://get.robin.io/activate
That’s it! No other steps required.
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.
Lastly activate your ROBIN license by visiting https://get.robin.io/activate
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 MarketplaceOnly 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.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