3. Setting Up Your Robin Cluster¶
Before your cluster becomes fully operational, there are additional steps that need to be performed in order to configure Robin correctly.
Note
If your Robin cluster was created by GoROBIN, many of these steps will not apply.
3.1. Robin license activation¶
After installing Robin software on any platform, whenever you run a command a notice will appear stating that the Robin license is not currently activated. This is an indication that no license has currently been applied to the cluster and thus certain commands will not be usable. In order to utilize the cluster to its full capability you can activate it via one of the following methods.
If the license is not activated, the Robin cluster will be locked after the allocated time.
3.1.1. Web license activation¶
Activate your Robin license by following the instructions detailed here. Once complete, the license should be activated and the cluster will be ready for 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>.
3.1.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 is ready to use.
Example:
# robin license activate demo1234
License has been applied successfully
3.2. Resource pool assignment¶
Resource pools are a construct in Robin which allow you to group nodes in the cluster together for allocation purposes. Pools provide resource isolation. More details on resource pools and commands to manage them can be found here.
Upon installation, a resource pool named default is created. If you wish to create a custom resource pool run this command:
# robin rpool add <name>
Example:
# robin rpool add demo
Added resource pool demo.
In order to add nodes to a resource pool run this command:
# robin host assign-rpool <hostnames> <rpool_name> --wait
Example:
# robin host assign-rpool centos-60-212,centos-60-214 demo --wait
Job: 11 Name: HostAddResourcePoolMulti State: VALIDATED Error: 0
Job: 11 Name: HostAddResourcePoolMulti State: WAITING Error: 0
Job: 11 Name: HostAddResourcePoolMulti State: COMPLETED Error: 0
Note
The default resource pool is not assigned to any nodes upon installation. Thus, if you want to utilize the precreated resource pool you still have to explicitly assign it.
3.3. Role assignment¶
There are three Robin roles that can be assigned to hosts: Manager, Compute and Storage. Depending on the resources present on a node you can initialize it to have one or more of these roles. This allows for a more granular control over what resources a node can provide for allocation. More details on the specific roles, what they entail, and how to manage them can be found here.
Note
Upon installation, nodes which that installed as masters will have the Manager role already assigned to them.
To add a role, run this command:
# robin host add-role <hostnames> <roles> --wait
Example:
# robin host add-role centos-60-212,centos-60-214 Compute,Storage --wait
Job: 18 Name: HostAddRoles State: VALIDATED Error: 0
Job: 18 Name: HostAddRoles State: WAITING Error: 0
Job: 18 Name: HostAddRoles State: COMPLETED Error: 0
To verify the roles were appropriately added, run this command:
# robin host list
Id | Hostname | Version | Status | State | Resource Pool | Roles | Cores | GPUs | Memory | HDD(Alloc/Total) | SSD(Alloc/Total) | Instances | Joined Time
-------------+----------------------------------+-----------+--------+--------+---------------+--------+-------+------+-------------------+------------------+------------------+-----------+----------------------
1539379146:1 | centos-60-212.robinsystems.com | 5.0.5-548 | Ready | ONLINE | demo | M*,S,C | 1/6 | 0/0 | 7.76 GB/15.5 GB | 396 GB/43.66 TB | 0 GB/111.79 GB | 0 | 12 Oct 2019 14:19:32
1539379146:2 | centos-60-214.robinsystems.com | 5.0.5-548 | Ready | ONLINE | demo | C,S | 1/24 | 0/0 | 22.81 GB/94.25 GB | 0 GB/0 B | 50 GB/894.25 GB | 0 | 12 Oct 2019 14:27:07
3.4. IP-Pool addition¶
An IP-Pool is a construct in Robin that groups together a set of IP addresses. Given that these IP addresses are then allocated by Robin during the application creation process, an IP-Pool allows you to have some control over what IP addresses are assigned to application containers. More details on IP-pools and commands to manage them can be found here.
Upon installation, an IP-Pool named default is created. If you wish to create a custom IP-Pool run this command:
# robin ip-pool add <name> --driver=<driver> --ranges <ip_range> --netmask <netmask>
Example:
# robin ip-pool add ovs-p1 --driver=ovs 10.10.1.82-128 255.255.255.0
Registered IP pool ovs-p1.
Note
The subnet for the IP-Pool is required to be present on at least one of the nodes with the compute role.
3.5. File collection addition¶
A file collection is an NFS like server that is backed by a volume allocated from Robin managed storage. Bundles and images used to create applications will be stored on File Collections, in addition to any logs that are collected. More details on File Collections and commands to manage them can be found here.
3.5.1. Considerations for file collection creation¶
Here are some factors that should be taken into account when creating a new File Collection:
The size of the collection. This will vary per use case and will be dependent on the number and size of the images that will be used for application creation.
The replication factor of the volumes backing the collection. This is vital as it helps ensure the collection is recoverable after failovers.
The collection type, which can be either log or file. This depends on the use case.
The resource pool from which to draw storage for the allocated volume.
The media type for the volume which will provide storage for the collection (either HDD or SSD). This will depend on the cluster.
File Collections will only be created on Robin nodes with the Manager role.
Moreover additional planning is required to ensure that there is sufficient capacity should a Master node fail. Operators should either:
Ensure that the replication factor on the File Collection is N-1 where N is the number of Master nodes
Ensure that there is sufficient space available on the Master nodes to allow the creation of a temporary File Collection should one of the master nodes fail in such a way that
The entire server has to be replaced
The operating system has to be reinstalled.
Note
The considerations regarding node failures also apply to Robin volumes in a situation where the number of replicas is equal to the number of hard drives available for Storage. For example a situation where they apply is a three node cluster, wherein which there is one hard drive available for storage on each node.
3.5.2. File collection creation¶
To create a file collection run this command:
# robin collection create <media_type> <rpool_name> --collection_type <type> --replicas <count> --size <size>
Example:
# robin collection create HDD demo --collection_type FILE_COLLECTION --replicas 3 --size 50G
Job: 189 Name: CollectionAdd State: VALIDATED Error: 0
Job: 189 Name: CollectionAdd State: PROCESSED Error: 0
Job: 189 Name: CollectionAdd State: WAITING Error: 0
Job: 189 Name: CollectionAdd State: FINALIZED Error: 0
Job: 189 Name: CollectionAdd State: COMPLETED Error: 0
3.6. Enabling metrics¶
Robin provides metrics collection for both nodes and applications via Prometheus. Statistics such as CPU usage, disk utilization, memory etc. are collected for these entities. Robin uses Prometheus for three main reasons:
Given its affinity for recording numeric time series, it is an excellent tool for machine-centric monitoring as all the data that is exposed is numeric.
Prometheus supports multidimensional data collection for microservices making it very easy to leverage for Robin application monitoring.
Resilience: each Prometheus server can be run completely independent of network storage or remote services.
The data collected is stored on disk in Prometheus’s local time series database. The time series data is stored in a custom format and is retained for a variable number of days. The amount of storage needed for the created PVC is dependent on the retention policy. More details on how the scraped data is stored are available here.
3.6.1. Considerations for setting up metrics¶
Here are some factors that should be taken into account when enabling metrics collection:
The retention time period. This will depend on the amount of historical data you wish to keep. The default is 7 days.
The size of the storage volume. This will be automatically calculated by multiplying the retention period by 1.5Gi but can be overridden. It is important to create a volume large enough to cover the whole retention period.
The replication factor of the volumes backing the collection. We recommend 3 to ensure the data previously collected is always available even after failure.
The fault domain for replicas. This will be cluster dependent and can be disk, host, or rack.
The resource pool from which to draw storage for the allocated volume.
The media type for the volume that will provide storage for the collection (either HDD or SSD). This will be cluster dependent.
3.6.2. Starting metrics¶
Robin brings up the Prometheus server and node exporter alongisde Grafana via Helm. In order to deploy the Prometheus Helm chart, run the following command:
# robin metrics start --media <media_type> --resource-pool <rpool_name> --faultdomain <fault_domain> --replicas <count> --retention-period <period>
Example:
# robin metrics start --media HDD --resource-pool demo --faultdomain disk --replicas 3 --retention-period 2
Job: 192 Name: MetricsStartCollect State: PREPARED Error: 0
Job: 192 Name: MetricsStartCollect State: DONE Error: 0
Job: 192 Name: MetricsStartCollect State: AGENT_WAIT Error: 0
Job: 192 Name: MetricsStartCollect State: NOTIFIED Error: 0
Job: 192 Name: MetricsStartCollect State: COMPLETED Error: 0
Note
The default username and password needed to access the Grafana dashboard is admin/admin.
3.7. Robin client¶
You can download the Robin client on your Linux or macOS machine to access your Robin cluster remotely. To retrieve the client binary, issue the following command:
# curl -k 'https://<master_ip>:<port>/api/v3/robin_server/download?file=robincli&os=<os>' -o robin
Note
The possiible values for the os URL parameter include: linux and mac. Please select the appropriate value for your desired operating system when retrieving the client.
Example:
# curl -k 'https://vnode42:29442/api/v3/robin_server/download?file=robincli&os=linux' -o robin
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 10.1M 100 10.1M 0 0 1421k 0 0:00:07 0:00:07 --:--:-- 1483k
# ls -lart
-rw-r--r-- 1 demo staff 10655536 Mar 26 14:12 robin
After running the curl command a file should have been downloaded to your current working directory. Make it an executable and setup the appropriate context based on the type of installation:
Non-HA Deployments:
# chmod +x robin
# robin client add-context <master_ip> --set-current
HA deployments:
Before setting up the context for highly available clusters make sure the robincp_mode config attribute is enabled by logging into the appropriate node and issuing the following command:
# robin config list | grep "robincp_mode"
manager | robincp_mode | False
If the aformentioned attribute is not enabled, issue the following command:
# robin config update manager robincp_mode True --wait
Job: 163 Name: HostConfigUpdateMulti State: VALIDATED Error: 0
Job: 163 Name: HostConfigUpdateMulti State: COMPLETED Error: 0
# robin config list | grep "robincp_mode"
manager | robincp_mode | True
Once this step is complete, finish setting up the client by issuing the following commands:
# chmod +x robin
# ./robin client add-context <cluster_vip> --port 29465 --file-port 29465 --event-port 29465 --set-current
Note
The examples above for client context configurations assume default port usage. For custom port deployments please set the custom port for each respective service explicitly. More information about client contexts please refer to the documentation here.
Before you can use the CLI you will have to login with the username and password (by default it is admin/Robin123):
# ./robin login <username>
Enter the password when prompted.
3.8. Robin Auth Utility¶
Before downloading and configuring the Kubernetes client (see below),
you first must download the robin-auth utility. The
robin-auth utility returns the credentials of the currently
logged in Robin user. The credentials are passed to the Kubernetes
API server when sending requests using the Kubernetes client. You can download the robin-auth
utility on your Linux or macOS machine by issuing the following command:
# curl -k 'https://<master_ip>:<port>/api/v3/robin_server/download?file=robinauth&os=<os>' -o robin-auth
Note
The possiible values for the os URL parameter include: linux and mac. Please select the appropriate value for your desired operating system when retrieving the client.
Example:
# curl -k 'https://vnode42:29442/api/v3/robin_server/download?file=robinauth&os=linux' -o robin-auth
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 46.8M 100 46.8M 0 0 36.1M 0 0:00:01 0:00:01 --:--:-- 36.1M
# ls -lart robin-auth
-rw-r--r-- 1 root root 6145568 Sep 1 14:58 robin-auth
After running the curl command a file should have been downloaded to your current working directory. Make it an executable and move it to a directory that is in your current PATH.
# chmod +x robin-auth
Check if a bin directory is present by running the ls command. If the directory is not present, create the bin directory.
# mkdir ~/bin
# mv robin-auth ~/bin
# robin login user1
Password:
User user1 is logged into t1 tenant
# robin-auth
{"kind": "ExecCredential", "status": {"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0ZW5hbnRfaWQiOjIsImV4cCI6MTU5OTA4NjI1MiwidXNlcl9pZCI6NX0._fN7JSEdRvNqHtdHJiMog5USAiTEnD4xiAMRdOy_NLw"}, "apiVersion": "client.authentication.k8s.io/v1beta1"}
Note
The robin-auth utility works in conjunction with the Robin client (see above).
The robin-auth utility must be located in your current PATH.
3.9. Kubernetes client¶
You can download the Kubernetes client on your Linux or macOS machine and setup the configuration via Robin in order to access the Kubernetes cluster externally. To retrieve the Kubernetes client, issue the following command:
# curl -k 'https://<master_ip>:<port>/api/v3/robin_server/download?file=kubectl&os=<os>' -o kubectl
Example:
# curl -k 'https://vnode31:29442/api/v3/robin_server/download?file=kubectl&os=linux' -o kubectl
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 44.5M 100 44.5M 0 0 28.9M 0 0:00:01 0:00:01 --:--:-- 28.9M
# ls -lart kubectl
-rw-r--r-- 1 demo staff 46682408 Apr 18 23:43 kubectl
After running the curl command a file should have been downloaded to your current working directory. Make it an executable and configure the client by issuing the following commands:
# chmod +x kubectl
# mkdir ~/.kube
# ./robin k8s get-kube-config --save-as-file --dest-dir ~/.kube
# kubectl get nodes
NAME STATUS ROLES AGE VERSION
vnode31.robinsystems.com Ready master 9d v1.16.3
vnode35.robinsystems.com Ready <none> 9d v1.16.3
vnode52.robinsystems.com Ready <none> 9d v1.16.3
Note
The above steps assume that the Robin client and robin-auth utility have already been downloaded and setup correctly on the remote machine. More details on how to setup your Robin client can be found in the above section.
The downloaded kubeconfig file contains an entry for the currently logged in Robin user, which is set as the default. The credentials for the currently logged in Robin user will be used when accessing the Kubernetes API server.
3.10. Helm client¶
You can download the Helm client on your Linux or macOS machine by issuing the following command:
# curl -k 'https://<master_ip>:<port>/api/v3/robin_server/download?file=helm&os=<os>' -o helm
Example:
# curl -k 'https://vnode31:29442/api/v3/robin_server/download?file=helm&os=linux' -o helm
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 38.5M 100 38.5M 0 0 29.3M 0 0:00:01 0:00:01 --:--:-- 29.4M
# ls -lart
-rw-r--r-- 1 demo staff 40460288 Apr 18 23:48 helm
After running the curl command, a file should have been downloaded to your current working directory. Make the file an executable by issuing the following commands:
# chmod +x helm
3.11. Helm 2 client¶
Note
Support for Helm 2 and Tiller is deprecated and will be removed in the next release.
You can download the Helm 2 client on your Linux or macOS machine and configure the necessary Helm/Tiller objects via Robin in order to utilize Helm to deploy charts to be managed by the platform. To retrieve the Helm 2 client, issue the following comman:
# curl -k 'https://<master_ip>:<port>/api/v3/robin_server/download?file=helm2&os=<os>' -o helm2
Example:
# curl -k 'https://vnode31:29442/api/v3/robin_server/download?file=helm2&os=linux' -o helm2
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 38.5M 100 38.5M 0 0 29.3M 0 0:00:01 0:00:01 --:--:-- 29.4M
# ls -lart
-rw-r--r-- 1 demo staff 40460288 Apr 18 23:48 helm2
After running the curl command a file should have been downloaded to your current working directory. Make it an executable, configure the necessary files and deploy the appropriate Tiller objects by issuing the following commands:
# chmod +x helm2
# ./robin whoami
username: robin
tenant: Administrators
tenants: ['Administrators']
namespace: t001-u000003
session_expires: 2020-04-19T23:13:10
# ./robin k8s deploy-tiller t001-u000003
Tiller objects were successfully deployed for namespace 't001-u000003'
# robin k8s helm-setup t001-u000003
Helm initialized successfully
Note
The above steps assume that the Robin client has already been
setup correctly on the remote machine. More details on how to
setup your Robin client can be found in the above section. In
addition when running the final two commands ensure the Robin
namespace displayed in the output of the whoami command is
passed as parameter.