***************** Install and Setup ***************** ========================= 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. ----------------------------------- 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 `_. ---------------------------------- Environment Specific Prerequisites ---------------------------------- - Prerequisites for installing ROBIN on a GKE cluster can be found `here `_. .. |br| raw:: html - Prerequisites for installing ROBIN on an OpenShift cluster can be found `here `_. ======================================== 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: .. code-block:: console $ /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-.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: .. code-block:: console $ kubectl describe robinclusters -n robinio Under the Status section there should be a field labelled Phase, its value should be "Ready". .. |br| raw:: html - Set the environment variable ROBIN_SERVER to the IP Address of your master node by running the command: .. code-block:: console $ source ~/robinenv - Activate your ROBIN cluster license by running the following commands: .. code-block:: console $ robin login admin --password Robin123 $ robin license activate .. 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 '. - To get started check out the example workflow located `here `_. - To uninstall ROBIN run the following command: .. code-block:: console $ /bin/bash install-robin.sh --uninstall ======================================== 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. -------------- 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: .. code-block:: console $ 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" ------------- Installation ------------- After the prerequisites product installation is as simple as running the following command: .. code-block:: console $ 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 ========================= 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. -------------- 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. --------------------- 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: .. code-block:: console $ 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. --------------------- 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 .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 .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 .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 .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 .yaml This should successfully deploy the ROBIN operator on your OpenShift cluster. .. |br| raw:: html
- Lastly activate your ROBIN license by visiting https://get.robin.io/activate =================================== Install Options =================================== .. code-block:: yaml apiVersion: robin.io/v1alpha1 kind: RobinCluster metadata: name: robin namespace: robinio spec: image_version: k8s_provider: gke|openshift|eks|aks|pks|robin|opensource host_type: gcp|physical|aws|azure node_selector: image_provisoner: source: # kms: robin/google # kms_keyring: # options: # access_key: # secret_key: # tenant_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: | 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. =================== Verify Installation =================== Once the installation is complete, you can get details about robin cluster by running .. code-block:: console $ 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. .. code-block:: console $ kubectl get sc Use the "Connect Command" value from the above output to connect to ROBIN pod. For example, .. code-block:: console $ kubectl exec -it robin-rnnnd -n robinio bash After logging into ROBIN container you can login as "admin" user. Default password is 'Robin123' .. code-block:: console $ robin login admin You can verify the installation by running .. code-block:: console $ robin host list ============ ROBIN Client ============ You can also download ROBIN client on your Linux or macOS machine. You can run following command .. code-block:: console $ kubectl describe robinclusters -n robinio The output will have command to get robin client. The output will look like following .. code-block:: console $ 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: .. code-block:: console $ chmod +x robin Set the ROBIN_SERVER environment variable with the value of "Master IP" .. code-block:: console $ 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: .. code-block:: console $ robin login Followed by entering the password when prompted. ======================== 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. ------------------------ 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 '. ------------------------ 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: .. code-block:: console $ robin license activate This will activate your ROBIN license and ensure your cluster ready to use. =================================== 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. =============== 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. .. code-block:: console $ robin host probe [|--all] --rediscover To verify new disks are discovered, run following command .. code-block:: console $ robin disk list To add new disks to Robin storage, run .. code-block:: console $ robin host add-role storage [--disks ] hostnames: List of comma seperated list of hostnames disks : List of comma seperated wwn of disks . 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. ------------------------ 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 .. code-block:: console $ robin disk create --type --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. -------------------------------- 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. ------------------------ 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 .. code-block:: console $ robin disk create --type --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. =============== 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 :ref:`UserManagement` section. ================== Uninstalling ROBIN ================== For Uninstalling ROBIN from Kubernetes cluster, run following command: .. code-block:: console $ kubectl delete -f robin.yaml ------------------------------- 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: .. code-block:: console $ oc delete namespace robinio -------------------------------------- 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: .. code-block:: console $ ./intall-robin --uninstall .. Note:: The ``install-robin`` script is shipped within the QuickStart tar file. ====================== 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: .. code-block:: console $ robin config update cluster enable_telemetry False