***************************** 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 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 a license must be applied to it. Described below are the types of licenses that can be activated in order to enable your cluster to function completely and how to acquire/activate each one. .. Note:: You must renew your license within 15 days after it expires. If you do not renew it, your cluster is locked after 15 days from the license expiry. ----------------- Types of Licence ----------------- Robin offers the following types of license for the Robin CNP: * **Robin Enterprise trial license** - This license is an evaluation license with unlimited capacity, 24x7 enterprise support, and a 30-day free trial. * **Robin Express license** - This license is a community license, free for a lifetime with limited capacity (only five nodes with five TB of storage within a cluster) and community support. * **Robin Production license** - This license is a custom production license for built specifically for customers that have a paid contract with Robin.io. --------------------------------------- Activate Robin Enterprise trial license --------------------------------------- The Robin Enterprise trial license is an evaluation license that offers unlimited capacity, 24x7 enterprise support, and a 30-day free trial. It allows full access to all the features of the Robin platform and enables users to experience the product fully. After the successful installation of a Robin cluster, the Robin Enterprise trial license can be activated in the following two ways: * Using an auto-generated User ID * Using a license key Method 1: Using a User ID ----------------------------------------------------- Complete the following steps to activate the Robin Enterprise trial license using a User ID: #. Sign into the `get.robin.io `_ website by following the appropriate instructions. #. After logging in, hover over the user icon in the upper righthand corner and copy the displayed User ID. #. Login to your Robin CNP cluster and run the ``robin license activate`` command with copied User ID as shown in the example below: .. code-block:: text # robin license activate --userid 3D87AHGE License has been applied successfully Method 2: Using a License Key -------------------------------------------------------- The Robin Enterprise trial license can also be activated using a license key. In order to generate a license key on `get.robin.io `_ the cluster license ID must be provided. The complete steps are outlined below: #. Login to your Robin CNP cluster and save the output of the following command: .. code-block:: text # robin license id #. Sign into the `get.robin.io `_ website by following the appropriate instructions. #. After logging in, click the **ACTIVATE** tab and navigate to the **Activate entering your license ID** section. #. In the **ROBIN LICENSE ID** field, enter the license ID from step 1 and select **Robin Enterprise trial** for the license type. #. Click **Activate** in order to generate a license key and copy it. #. Login to your Robin CNP cluster and run the ``robin license apply`` command with copied license key as shown in the example below: .. code-block:: text # robin license apply lg48ugNqMOnHTelEE7KrnaY1IlGFeFlowPkXt6MQkoK3zJ4ULZvNZEKsq34gS5x6B7CrCEPP8t78xkya2xfj6XlVWHGo5/zFt6gEKGeugHef0r3RbJC4zMuGdiucREHMCbAFyZ/dYHGPSnod2I8pG5/adxdOtEFUwReYBIPgNBJ3Sh7WCt8d3xW/jLPVUUPfyqToAv2m6C8SZwlI1QDhp0/NQD8cJ5CJoI4bCJpOM6pNgfbMhY9nTjORLNERujdrYhrWojs/kasySwH4uOnIFzF9GVLD/HgYR8viZOrUs1yq72V0MP7CLAsxtjnMiNeIKxgnXSrHzJIgLZvqEm80Q5ZImTREtJU53KHv5xJ7EvflFzWa8JBzXhrOXywuI/CJpbFCPA+s7BbWEneG/7aw0M6zxFR6s7ItYAmXryEW3cXnyM19o5oHswrHY9WX/67sMXBmdhzUa/zVugJmDUSvtuKV6X8aXpp/hPFzMOTzkOfk/4/ACMNZB2wWPl9Wg9hyFfx1+JitUeKhuUmqMt7grLrCY2SP9wHAUXOwPUnrpmk88sJHWDpBKeVrSApaTHuH5lJFIMw7iatxQT7nw8hsJ5sz4sRoq0iyV/EFA1k+UjVyvP+oLRgUJur6VqalpoEo0oTlJ4pZX1g7iM5dhLn5lLn7RMpzylqs2/Lo2j8dQexE7kbFV34vSlL0/oqg6YjsjpC1SVd/L3X72PXydBM9eCv6P82Zj8nARVEMq0yGGUTkjPervGcNg0VAFyeL1mA3K0KeduzRKuM5cyixrfB3M7BdxJyJ3Ob0YHoHwKzGRCY0w9yhtUhR/mGMklXomjgjFdc+L92qi2QA/fZz4qbhSFTUxY/fzOdPZKZvEXYXR9oSOAOqDjfuOk8GPDAE2H6RDN5AJk3nn3ViNI8JGW3Tf+dLiFWHxfieIVMlpT45Fy5/24K1QfoSv4HQ/p5qaOdq8Ygw5kXmoQw8fujXdqRA8dnIEcxk9fgXoAVOjSSGe9tllqy1mzMGEpQxMC4REH4qNwQMJDk6TOjEKijwpHHLDvsirJoyx6wm65geBTUxJVjmQrh568fou2BuCJhkKLfKiRd0Pj+yjkDqtCjw21v8yh1H+gkIJIshBrAz3jQJ2O6DV0g3ka/akaVvmBhk8vUxyDFC2d6ixurmdGz44Cz3cDA1JHG3D4iciiErA+K+/Iz1RavVmwp/FGrI2W2QMOSzMRqJKTsq2zoGOYWWEdIIvYRaISAEmsKa4eSHnl5vjlf/4lhTLP/Il12nV1cG3zUXUlMiadEww4//NWhet91LInGr+R1Pjb1yYFPmx2 License has been applied successfully ------------------------------ Activate Robin Express license ------------------------------ The Robin Express license is a free-for-life license that offers a maximum of 5 nodes and a total of 5 TB of storage within a Robin cluster with community support. It allows users to have a small Robin cluster running for an unlimited period of time. After the successful installation of a Robin cluster, the Robin Express license can be activated using a license key by completing the following steps: #. Login to your Robin CNP cluster and save the output of the following command: .. code-block:: text # robin license id #. Sign into the `get.robin.io `_ website by following the appropriate instructions. #. After logging in, click the **ACTIVATE** tab and navigate to the **Activate entering your license ID** section. #. In the **ROBIN LICENSE ID** field, enter the license ID from step 1 and select **Robin Express** for the license type. #. Click **Activate** in order to generate a license key and copy it. #. Login to your Robin CNP cluster and run the ``robin license apply`` command with copied license key as shown in the example below: .. code-block:: text # robin license apply lg48ugNqMOnHTelEE7KrnaY1IlGFeFlowPkXt6MQkoK3zJ4ULZvNZEKsq34gS5x6B7CrCEPP8t78xkya2xfj6XlVWHGo5/zFt6gEKGeugHef0r3RbJC4zMuGdiucREHMCbAFyZ/dYHGPSnod2I8pG5/adxdOtEFUwReYBIPgNBJ3Sh7WCt8d3xW/jLPVUUPfyqToAv2m6C8SZwlI1QDhp0/NQD8cJ5CJoI4bCJpOM6pNgfbMhY9nTjORLNERujdrYhrWojs/kasySwH4uOnIFzF9GVLD/HgYR8viZOrUs1yq72V0MP7CLAsxtjnMiNeIKxgnXSrHzJIgLZvqEm80Q5ZImTREtJU53KHv5xJ7EvflFzWa8JBzXhrOXywuI/CJpbFCPA+s7BbWEneG/7aw0M6zxFR6s7ItYAmXryEW3cXnyM19o5oHswrHY9WX/67sMXBmdhzUa/zVugJmDUSvtuKV6X8aXpp/hPFzMOTzkOfk/4/ACMNZB2wWPl9Wg9hyFfx1+JitUeKhuUmqMt7grLrCY2SP9wHAUXOwPUnrpmk88sJHWDpBKeVrSApaTHuH5lJFIMw7iatxQT7nw8hsJ5sz4sRoq0iyV/EFA1k+UjVyvP+oLRgUJur6VqalpoEo0oTlJ4pZX1g7iM5dhLn5lLn7RMpzylqs2/Lo2j8dQexE7kbFV34vSlL0/oqg6YjsjpC1SVd/L3X72PXydBM9eCv6P82Zj8nARVEMq0yGGUTkjPervGcNg0VAFyeL1mA3K0KeduzRKuM5cyixrfB3M7BdxJyJ3Ob0YHoHwKzGRCY0w9yhtUhR/mGMklXomjgjFdc+L92qi2QA/fZz4qbhSFTUxY/fzOdPZKZvEXYXR9oSOAOqDjfuOk8GPDAE2H6RDN5AJk3nn3ViNI8JGW3Tf+dLiFWHxfieIVMlpT45Fy5/24K1QfoSv4HQ/p5qaOdq8Ygw5kXmoQw8fujXdqRA8dnIEcxk9fgXoAVOjSSGe9tllqy1mzMGEpQxMC4REH4qNwQMJDk6TOjEKijwpHHLDvsirJoyx6wm65geBTUxJVjmQrh568fou2BuCJhkKLfKiRd0Pj+yjkDqtCjw21v8yh1H+gkIJIshBrAz3jQJ2O6DV0g3ka/akaVvmBhk8vUxyDFC2d6ixurmdGz44Cz3cDA1JHG3D4iciiErA+K+/Iz1RavVmwp/FGrI2W2QMOSzMRqJKTsq2zoGOYWWEdIIvYRaISAEmsKa4eSHnl5vjlf/4lhTLP/Il12nV1cG3zUXUlMiadEww4//NWhet91LInGr+R1Pjb1yYFPmx2 License has been applied successfully ----------------------------------- Activate Robin Production license ----------------------------------- When you purchase the production license for Robin CNP from Robin.io, a custom license contract is created based on the sales agreement made. This contract acts a template from which production licenses are generated. It contains the following details: * Authorized users * Owners * Contract end date * Maximum number of nodes * Renewal period, and so on. Each contract is saved on `get.robin.io `_ which in turn is where all production licenses are created. Once the production license is generated, it can be activated in the following ways: * **License proxy server** - As the name suggests this option entails the usage of a stateful proxy server that contacts the `get.robin.io `_ website on behalf of Robin clusters that are otherwise on isolated networks. It can be setup on a low resource machine with Kuberentes installed and can be connected to multiple Robin clusters through the usage of a config variable. It enables the intial license activation of the aforementioned Robin clusters whilst also introducing the possibility of automatic renewal. Details on how to setup the proxy server are given below. * **Manually** - A production license can also be applied manually after it is generated on `get.robin.io `_. Details on how to do so are described below. Note the same process can be utilized when the license needs to be renewed. Method 1: Using a License Proxy server ----------------------------------------------------- Prerequisites ^^^^^^^^^^^^^ Before deploying a proxy server to be used as the primary method by which licenses will be activated (and renewed if applicable) for a set of Robin clusters, the below points should be considered: * Each proxy server can handle multiple Robin clusters but can only be associated with one license contract. * The proxy server is made known to each Robin cluster through the use of config variables. * There must be constant connectivity between each respective Robin cluster and the proxy server. If there is a drop in connectivity, alerts will be generated on the Robin cluster until the issue is resolved. * In order to ensure the activation and renewal of licenses for all associated Robin clusters, there must be constant connectivity between the proxy server and the `get.robin.io `_ website. * It is highly recommended that the proxy server be deployed and setup before the installation of the Robin clusters that will be associated with it wherever applicable. * Although not mandatory it is highly recommended that the proxy server is host on a machine that is not part of any of the Robin clusters to be associated with it. In addition, the below prerequisites must also be met: * Kubernetes v1.8 or above must be deployed on the machine where the proxy server will be deployed. * A request must be submitted to the Robin.io Customer Success team for access to the ``license_proxy.tar`` and ``license_deployment.yaml`` files which contain the image and object spec for the proxy server. * The contract to be associated with the proxy server must already be created. This can be confirmed with the Robin.io Customer Success team. Deployment and setup of the License Proxy server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following steps outline the process by which the License Proxy server can be deployed, activated and linked to the relevant Robin clusters: #. Using the ``license_proxy.tar`` file, load the docker image for the proxy server by running the following command: .. code-block:: text # docker load -i license-proxy.tar #. To deploy the Kubernetes objects needed for the proxy server, including the Pod, PVC etc. run the following command: .. code-block:: text # kubectl apply -f license-deployment.yaml #. Ensure the license proxy pod is in a running state by issuing the following command: .. code-block:: text # kubectl describe pod -n default license-proxy #. After confirming the license proxy is in a healthy state, execute into the main container and fetch the ID associated with it as shown in the example below. This will be used to activate the proxy server thus allowing it to serve activation and renewal requests. .. code-block:: text # kubectl exec -ti -n default license-proxy -- robin proxy id #. Sign into the `get.robin.io `_ website by following the appropriate instructions. #. After logging in, click the **ACTIVATE PROXY** tab on the **Activate** page and navigate to the **Link a proxy to a contract** section. #. Within the section, select the contract to associate with the proxy, enter a name to help easily identify the proxy and input the proxy ID from Step 4. #. Click **Activate** in order to generate a proxy key and copy it. #. Activate the proxy with the generated key as shown in the example below. .. code-block:: text # kubectl exec -ti -n default license-proxy -- bash # robin proxy activate U7oF1y9WMpPRubRvFRDThbqIrel1TrflAkqsXqrRNmn3l6PH5BMQoNC2CyO1dwQqh8HpdWeAEeY3Wl8a0b6inU6nSEzya7KiTYftcfyryCX1vLEz9Eg20AJNMICOurbrQuENhMYxnAXfDotKhg6yAM8BZ51HpiVZq3P6WyHz00JnlzcPR+DAB4JN9rTkttn64CBApT6tUCpTzCqODfZqk55o3RnXCTMnuC4clRKJw6Ro1obQEpQiOMWTx0IC8RI1m1sik+ANESG4ap6Sn0xN9wFZZGgK6xqlI+GW8Ftr9Z5VFa+cD0L7tuVMSCNQihFV3jVk9KF77Ok7meCT1cbeAY1SHxW/l9ArcT4crieFzIXi1VeU8vjejFpPYO/6znmEPIKjlYgUDQFYojFvJXBoW2uTyNoPZIFgFCq3EWxs9jxM5o9KXCiFGZvDZpBrWJ9FWAUV6E+FeunEAcmPASqKYn2X0RCq5Y7MumgL+3OHdD5BL//koUWl/yS+ioi04IjXt+p/wbpYoqRF4tWgONLJhnvg9xQi/mCqGRhioL4DHuuvWSjCCb9T8F50ZszLTF15qMQMArSRhvAh3N/t3r56DnjBZbgc+ebKsnvlJT5SSE0+lrnfTPhl8tqQMhw3GaNTASjON4PuYVBD= Successfully activated Robin Proxy #. After setting up and activating the proxy server, it can be linked to the respective Robin cluster by updating the ``license_server_url`` config variable to the url of the proxy server as in the following example: .. code-block:: text # robin config update cluster license_server_url http://192.0.2.55:31123 The 'cluster' attribute 'license_server_url' has been updated .. Note:: If the standard deployment YAMLs are used for the License Proxy server, the url through which it can be contacted is: :. The default NodePort used is 31123. #. Once the ``license_server_url`` attribute is set, the cluster license will be automatically activated (or renewed) once the license schedule, which is scheduled to run everyday at midnight, executes. Optionally to activate/renew the cluster license on demand, run the following command: .. code-block:: text # robin license activate License has been activated successfully .. Note:: Further details on the config variables, namely the ``license_server_url`` and ``license_renew_period`` attributes, that control the behavior of the license proxy server from the prespective of the Robin cluster can be found `here `__. .. Important:: If the License Proxy server is deployed before the Robin cluster is installed as is recommended, then the ``--license-server-url`` option can be utilized as part of the installation process in order to pass the License Proxy server URL and avoid any post-installation configuration. If the proxy is setup and running correctly then the Robin cluster will be automatically activated after a successful installation with the aforementioned parameter. However, if the License Proxy server cannot be reached at the time of installation due to any unforseen issues such as the URL specified being incorrect or a network outage, the installation will not fail instead the cluster will simply remain in a unactivated state with the possibility of a manual reconfiguration of the ``license_server_url`` config parameter being needed. Method 2: Apply a Production license manaully --------------------------------------------- If a license proxy server cannot be setup in the given environment, the Production license can also be generated and applied manually with the use of an authorization token. In order to generate a token on `get.robin.io `_ a contract must be available for use by the given user. The complete steps are outlined below: #. Sign into the `get.robin.io `_ website by following the appropriate instructions. #. After logging in, hover over the user icon in the upper right corner and click the **Generate Token** link. #. Within the presented section, select the contract to associate with the token, and enter the number of days the token should be valid for. #. Click **Generate Token** in order to generate a token and copy it. #. Login to your Robin CNP cluster and run the ``robin license renew`` command with copied token as shown in the example below: .. code-block:: text # robin license renew --token vF6KtruI1mdDhm6ASbAMhMiuhHaR9J/iMUR/FtyMnXbDmkOyZr+Zu4Fb6BdnRLNyPtliHteH/I1+s51h/AWeQ== License has been renewed successfully ======================== License management ======================== --------------- View License ID --------------- .. tabs:: .. tab:: CLI Each Robin cluster has a unique, auto-generated identification number associated with it that enables license keys to be created specifically for the given cluster. In order to view the license ID of a cluster run the following command: .. code-block:: text # robin license id --json ================= ========================== ``--json`` Output in JSON ================= ========================== **Example:** .. code-block:: text # robin license id License Id: YGVkYWBjYGFiZWkhZ00lZk0gX1NcYWkDQDM5P0wENjNHNjNcQzAyOi75QF0ERyRcND0GREU1Q0z8QDQxPWjg.S_ .. tab:: API Returns the unique, auto-generated identification number associated with a cluster that enables license keys to be created specifically for the given cluster. **End Point:** /api/v3/robin_server/license **Method:** GET **URL Parameters:** - ``id=true`` : This mandatory parameter specifies that the License ID of the cluster should be returned. **Data Parameters:** None **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 200 **Error Response Code:** 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "license_id": "YGVkZ1BjZlFlX1khZ00lZk0gX1NcYWkDQDM5P0wENjNHNjNcQzAyOi75QF0ERyRcND0GREU1Q0z8\r\nQDQxPWjg.SFoI1kjXWNcYFwiZWk3" } .. raw:: html
------------------------ View license information ------------------------ .. tabs:: .. tab:: CLI To view additional details about the current applied license, run the following command: .. code-block:: text # robin license info --usage =================== =========================== ``--usage`` View cluster usage with regard to license restrictions =================== =========================== **Example:** .. code-block:: text # robin license info ROBIN License Information: ID ......................... YGVkYWBjYGFiZWkhZ00lZk0gX1NcYWkDQDM5P0wENjNHNjNcQzAyOi75QF0ERyRcND0GREU1Q0z8\r\nQDQxPWjg.S_ Type ....................... Evaluation Created on ................. 2022-09-14T10:38:30 UTC ROBIN Type ................. Platform Host Type .................. PHYSICAL Version .................... 5.4.1-4998 K8S Provider ............... ROBIN Deployment Source .......... Installer Expires on ................. 2022-10-14T10:38:30 UTC (18 day(s) remaining) Status ..................... OK .. tab:: API Returns additional details about the license currently applied on a cluster. **End Point:** /api/v3/robin_server/license **Method:** GET **URL Parameters:** None **Data Parameters:** None **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 200 **Error Response Code:** 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "license_info": { "license": { "sku": "platform", "features": { "snapshot": true, "clone": true, "backup": true }, "expireson": "2022-12-11T09:06:15", "creator": "Robin", "issuedto": { "name": "", "email": "internal_robin@robin.io" }, "pernode": { "disks": 72, "storage": 1266637395197952, "cpu_cores": 96, "containers": 128, "memory": 2199023255552 }, "percluster": { "gpu_cores": 120000, "users": 1000, "apps": 10000, "disks": 360000, "storage": 6333186975989760000, "snapshots": 2560000, "cpu_cores": 480000, "memory": 10995116277760000, "clones": 10000, "nodes": 5000, "tenants": 1000, "containers": 50000 }, "activated": true, "createtime": "2022-11-11T09:06:15", "version": "5.4.1-46", "installkey": "385e43c7-bf16-4768-9b77-0e09ddb7263c", "host_type": "physical", "k8s_provider": "robin", "type": "Evaluation", "id": "YGVkZ1BjZlFlX1khZ00lZk0gX1NcYWkDQDM5P0wENjNHNjNcQzAyOi75QF0ERyRcND0GREU1Q0z8\r\nQDQxPWjg.SFoI1kjXWNcYFwiZWk3", "deployment_source": "installer", "robin_type": "platform", "num_days_expire": 12, "num_days_lockdown": 27 }, "profile": { "apps": 0, "snapshots": 0, "clones": 0, "containers": 0, "users": 3, "tenants": 1, "disks": 3, "nodes": 3, "node_def": { "3": { "primary_hostname": "vnode-109-179.robinsystems.com", "disks": 1, "storage": 85899345920, "cpu_cores": 8, "memory": 16655675392 }, "1": { "primary_hostname": "vnode-109-177.robinsystems.com", "disks": 1, "storage": 85899345920, "cpu_cores": 8, "memory": 16655675392 }, "2": { "primary_hostname": "vnode-109-178.robinsystems.com", "disks": 1, "storage": 85899345920, "cpu_cores": 8, "memory": 16655675392 } }, "cpu_cores": 24, "gpu_cores": 0, "memory": 49967026176, "storage": 257698037760 }, "status": "OK", "status_message": "License is in a good state." } } .. raw:: html
------------------------ Activate a license ------------------------ .. tabs:: .. tab:: CLI In order to activate a license and thus allow a cluster to be fully operational, run the following command: .. code-block:: text # robin license activate --userid ======================= =========================== ``--userid `` Custom User ID generated after logging into the get.robin.io website. Note this parameter is mandatory whenn the ``license_server_url`` parameter is not set to the URL for a Robin License Proxy server ======================= =========================== **Example:** .. code-block:: text # robin license activate --userid 3D87AHGE License has been applied successfully .. tab:: API Returns a URL which can be used to activate a license in order to allow the cluster to become fully operational. **End Point:** /api/v3/robin_server/license **Method:** GET **URL Parameters:** - ``url=activate`` : This mandatory parameter specifies that the URL for activation should be returned. - ``userid=`` : Utilizing this parameter results in the URL returned pointing directly to get.robin.io. It is mandatory when the ``license_server_url`` parameter is not set to the URL for a Robin License Proxy server. **Data Parameters:** None **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 200 **Error Response Code:** 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text .. raw:: html
------------------------ Apply a license key ------------------------ .. tabs:: .. tab:: CLI In order to apply a generated license key manually, run the following command: .. code-block:: text # robin license apply --desc --force ======================= =========================== ``license_key`` Raw license key to be used or path to file containing license key ``--desc `` Description to associate with license being applied ``--force`` Override inferior license check ======================= =========================== **Example:** .. code-block:: text # robin license apply lg48ugNqMOnHTelEE7KrnaY1IlGFeFlowPkXt6MQkoK3zJ4ULZvNZEKsq34gS5x6B7CrCEPP8t78xkya2xfj6XlVWHGo5/zFt6gEKGeugHef0r3RbJC4zMuGdiucREHMCbAFyZ/dYHGPSnod2I8pG5/adxdOtEFUwReYBIPgNBJ3Sh7WCt8d3xW/jLPVUUPfyqToAv2m6C8SZwlI1QDhp0/NQD8cJ5CJoI4bCJpOM6pNgfbMhY9nTjORLNERujdrYhrWojs/kasySwH4uOnIFzF9GVLD/HgYR8viZOrUs1yq72V0MP7CLAsxtjnMiNeIKxgnXSrHzJIgLZvqEm80Q5ZImTREtJU53KHv5xJ7EvflFzWa8JBzXhrOXywuI/CJpbFCPA+s7BbWEneG/7aw0M6zxFR6s7ItYAmXryEW3cXnyM19o5oHswrHY9WX/67sMXBmdhzUa/zVugJmDUSvtuKV6X8aXpp/hPFzMOTzkOfk/4/ACMNZB2wWPl9Wg9hyFfx1+JitUeKhuUmqMt7grLrCY2SP9wHAUXOwPUnrpmk88sJHWDpBKeVrSApaTHuH5lJFIMw7iatxQT7nw8hsJ5sz4sRoq0iyV/EFA1k+UjVyvP+oLRgUJur6VqalpoEo0oTlJ4pZX1g7iM5dhLn5lLn7RMpzylqs2/Lo2j8dQexE7kbFV34vSlL0/oqg6YjsjpC1SVd/L3X72PXydBM9eCv6P82Zj8nARVEMq0yGGUTkjPervGcNg0VAFyeL1mA3K0KeduzRKuM5cyixrfB3M7BdxJyJ3Ob0YHoHwKzGRCY0w9yhtUhR/mGMklXomjgjFdc+L92qi2QA/fZz4qbhSFTUxY/fzOdPZKZvEXYXR9oSOAOqDjfuOk8GPDAE2H6RDN5AJk3nn3ViNI8JGW3Tf+dLiFWHxfieIVMlpT45Fy5/24K1QfoSv4HQ/p5qaOdq8Ygw5kXmoQw8fujXdqRA8dnIEcxk9fgXoAVOjSSGe9tllqy1mzMGEpQxMC4REH4qNwQMJDk6TOjEKijwpHHLDvsirJoyx6wm65geBTUxJVjmQrh568fou2BuCJhkKLfKiRd0Pj+yjkDqtCjw21v8yh1H+gkIJIshBrAz3jQJ2O6DV0g3ka/akaVvmBhk8vUxyDFC2d6ixurmdGz44Cz3cDA1JHG3D4iciiErA+K+/Iz1RavVmwp/FGrI2W2QMOSzMRqJKTsq2zoGOYWWEdIIvYRaISAEmsKa4eSHnl5vjlf/4lhTLP/Il12nV1cG3zUXUlMiadEww4//NWhet91LInGr+R1Pjb1yYFPmx2 License has been applied successfully .. tab:: API Applies a specified license key to the cluster. **End Point:** /api/v3/robin_server/license **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``license: `` - This mandatory field within the payload specifies the license key to apply. - ``desc: `` - Utilizing this parameter within the payload, by specifying by specifying a string, results in the description for the applied license being set to the string given. - ``force: [true|false]`` - Utilizing this parameter within the payload, by specifying a boolean value, determines whether or not the inferior license check is overriden. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 200 **Error Response Code:** 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text .. raw:: html
------------------------ Renew a license ------------------------ .. tabs:: .. tab:: CLI In order to renew a license such that its expiration date is extended, run the following command: .. code-block:: text # robin license renew --token ======================= =========================== ``--token `` Authorization token generated on the get.robin.io website. Note this parameter is mandatory whenn the ``license_server_url`` parameter is not set to the URL for a Robin License Proxy server ======================= =========================== **Example:** .. code-block:: text # robin license renew License has been renewed successfully .. tab:: API Returns a URL which can be used to renew a license in order to extend the expiration date for a license. **End Point:** /api/v3/robin_server/license **Method:** GET **URL Parameters:** - ``url=renew`` : This mandatory parameter specifies that the URL for renewal should be returned. - ``token=`` : Utilizing this parameter results in the URL returned utilizing the specified authorization token and its associated contract. It is mandatory when the ``license_server_url`` parameter is not set to the URL for a Robin License Proxy server. **Data Parameters:** None **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 200 **Error Response Code:** 500 (Internal Server Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text .. raw:: html
======================== 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. 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. -------------------------- 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 .. 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**: .. 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 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 `__. ----------------------------------- Access using Whitelisted IP address ----------------------------------- You can access your Robin CNP cluster remotely by adding the IP address of the machine from which you want to access your cluster as whitelisted IP address. Prerequisites ------------- - You must install your Robin CNP cluster with the ``zero-trust=true`` option. Perform the following steps to access your Robin CNP cluster using the whitelisted IP address: 1. Login to your Robin CNP cluster using your username and password. 2. Add the whitelisted IP address to the ``robin-iptables-cfg`` in the ``/bin`` directory. .. code-block:: text # cd bin/ # vi robin-iptables-cfg ZEROTRUST=1 #Robin Control Ports CONTROLPORTS="6443,29442,29443,29445,29449" #Application Ports APPPORTS="" IP_VERSION=4 HAINSTALL=0 #Comma separated list of IPs or subnets that are whitelisted WHITELIST_IPS="" 3. Run the ``robin-k8s-iptables`` script: .. code-block:: text # ./robin-k8s-iptables 4. Create a network policy yaml with the whitelisted IP addresses. .. code-block:: yaml apiVersion: crd.projectcalico.org/v1 kind: NetworkPolicy metadata: name: allow-ingress-external namespace: robinio spec: selector: app == 'robin-master' types: - Ingress - Egress ingress: action: Allow protocol: TCP source: nets: - - egress: action: Allow 5. Run the following command to apply the network policy yaml to your Robin CNP cluster: .. code-block:: text # kubectl apply -f .yaml 6. Run the robin-k8s-iptables script again: .. code-block:: text # ./robin-k8s-iptables 7. Access the machine where you have already downloaded the Robin client’s binary. 8. Run the following command to make the Robin client executable: .. code-block:: text # chmod +x robin 9. Run the following command to add context to the Robin client: .. code-block:: text # robin client add-context --set-current .. Note:: **Example** .. code-block:: text # ./robincli-5.4.3-83 client add-context 192:0:2:24 --set-current Context robin-cluster-192:0:2:24 updated successfully and set as the current context .. Note:: * To know the IP address of node where Robin master Pod is running, run the ``kubectl get pod -n robinio -o wide | grep robin-master`` command. * When the Robin master Pod moves from one node to another node, ``robin client add-context`` must be added with the new node again. 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 .. 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**: .. 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.