***************************** 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. ======================== Robin license activation ======================== After installing Robin software on any platform, whenever you run a command a notice will appear stating that the Robin license will expire in approximately two days. 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, the Robin cluster will be locked after the allocated time. ---------------------- 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 ``. ---------------------- 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:: text # robin license activate This will activate your Robin license and ensure your cluster is ready to use. **Example**: .. code-block:: text # robin license activate demo1234 License has been applied successfully ======================== 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: .. code-block:: text # robin rpool add **Example**: .. code-block:: text # robin rpool add demo Added resource pool demo. In order to add nodes to a resource pool run this command: .. code-block:: text # robin host assign-rpool --wait **Example**: .. code-block:: text # 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. ================ 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: .. code-block:: text # robin host add-role --wait **Example**: .. code-block:: text # 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: .. code-block:: text # 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 ================ 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: .. code-block:: text # robin ip-pool add --driver= --ranges --netmask **Example**: .. code-block:: text # 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. ======================== 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 `_. -------------------------------------------- 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. In HA deployments, we recommend a factor of 3 to 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. -------------------------- File collection creation -------------------------- To create a file collection run this command: .. code-block:: text # robin collection create --collection_type --replicas --size **Example**: .. code-block:: text # 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 ================ 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 `_. ------------------------------------- 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. ---------------- 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: .. code-block:: text # robin metrics start --media --resource-pool --faultdomain --replicas --retention-period **Example**: .. code-block:: text # 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**. ============ 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: .. code-block:: text # curl -k 'https://:/api/v3/robin_server/download?file=robincli&os=' -o robin **Example**: .. code-block:: text # 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:** .. code-block:: text # chmod +x robin # robin client add-context --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: .. code-block:: text # robin config list | grep "robincp_mode" manager | robincp_mode | False If the aformentioned attribute is not enabled, issue the following command: .. code-block:: text # 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: .. code-block:: text # chmod +x robin # ./robin client add-context --port 29465 --file-port 29465 --event-port 29465 --set-current .. Note:: The variable ``master_ip`` can either be the IP address of your Robin master node or the VIP for HA installations. For 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): .. code-block:: text # ./robin login Enter the password when prompted. ================== 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: .. code-block:: text # curl -k 'https://:/api/v3/robin_server/download?file=robinauth&os=' -o robin-auth **Example**: .. code-block:: text # 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. .. code-block:: text # 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. ================= 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: .. code-block:: text # curl -k 'https://:/api/v3/robin_server/download?file=kubectl&os=' -o kubectl **Example**: .. code-block:: text # 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: .. code-block:: text # 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 9d v1.16.3 vnode52.robinsystems.com Ready 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. =========== Helm client =========== You can download the Helm client on your Linux or macOS machine by issuing the following command: .. code-block:: text # curl -k 'https://:/api/v3/robin_server/download?file=helm&os=' -o helm **Example**: .. code-block:: text # 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: .. code-block:: text # chmod +x helm ============= 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: .. code-block:: text # curl -k 'https://:/api/v3/robin_server/download?file=helm2&os=' -o helm2 **Example**: .. code-block:: text # 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: .. code-block:: text # 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.