********************* Managing Networking ********************* The Robin platform extends Kubernetes networking via both Calico and SR-IOV/Open vSwitch-based CNI (Container Network Interface) drivers. This dual support offers flexibility in using either overlay networks to create non-rigid L3 subnets that span multiple data centers/cloud environments, or bridged networking to get wire-speed network access for high-performance applications. In either mode, Robin enhances the CNI driver to retain the IP address of the Pod when it is restarted or relocated. This provides additional flexibility during the application lifecycle management process for operations such as scaling and migration, as well as ensuring high availability. IP-Pool Management =================== An IP-Pool is a construct in Robin that groups together a set of IP addresses. The main properties of an IP-Pool is the aforementioned range of addresses specified, the netmask and the backing network driver. The netmask assigned indicates the number of IP addresses that can be used from the specified range. In addition Robin supports a multitude of network drivers through which the container networking is orchestrated and enabled. The supported drivers include: Calico, OVS, and SR-IOV. For more information on considerations when selecting a driver please review the below section on CNI plugins. .. Note:: Calico is the default Container Network Interface (CNI) for Pods to use. If any other CNI (SRIOV, MACVLAN, etc.) are used as the default CNI, Pod deployment fails. As part of the installation process, Robin creates two Calico backed IP-Pools named ``robin-default`` and ``nonrobin-default`` respectively for the users convenience. The former uses the range 172.21.0-15.0-255 whilst the later is assigned the range 172.21.16-31.0-255. As the name suggests the ``nonrobin-default`` is used by Kubernetes when the applications are deployed using native Kubernetes tools. Its counter-part can be used for the applications deployed via Robin Bundles. .. note:: The ``nonrobin-default`` IP-Pool is hidden by default as Robin does not utilize it directly. When creating an application, one can specify an IP-Pool to be used at the Vnode level. As a result, the IP Address assigned to a container can be easily controlled and managed by the user. Moreover, in situations where a container needs multiple IP addresses, one can specify a set of IP-Pools and the number IP Addresses that need to be assigned from each of them in order to satisfy the requirement. However in the aforementioned situation if there are multiple IP-Pools containing default gateways, all of the gateways will programmed as source based routes except for the first. Along with additional details, the following commands are described in this section: ====================================== ================================================================================= ``robin ip-pool add`` Add an IP-Pool ``robin ip-pool add-certs`` Add certificates to an existing IP-Pool ``robin ip-pool add-ranges`` Add additional IP ranges to an existing IP-Pool ``robin ip-pool add-blacklist-ips`` Blacklist IP addresses within an existing IP-Pool ``robin ip-pool add-reserved-ips`` Reserve IP addresses within an existing IP-Pool ``robin ip-pool add-routes`` Add IP routes to an existing IP-Pool ``robin ip-pool list`` List IP-Pools ``robin ip-pool info`` Display detailed information about an IP-Pool ``robin ip-pool remove`` Remove an IP-Pool ``robin ip-pool remove-ranges`` Remove a range of IP addresses from an existing IP-Pool ``robin ip-pool remove-blacklist-ips`` Unblacklist IP addresses within an existing IP-Pool ``robin ip-pool remove-reserved-ips`` Unreserve IP addresses within an existing IP-Pool ``robin ip-pool remove-routes`` Remove IP routes from an existing IP-Pool ``robin ip-pool rename`` Rename an existing IP-Pool ====================================== ================================================================================= ================== Adding an IP-Pool ================== .. tabs:: .. tab:: CLI To add an IP-Pool for Robin to utilize during application deployment, issue the following command: .. code-block:: text # robin ip-pool add --ranges --network --netmask --prefix --zone --tenant --vlan --driver --gateway --nameserver --dns-search --nictags --ifcount --routes --vfdriver --master-interface --macvlan-mode --blacklist-ips --reserved-ip --mtu --trusted --spoofchk-disabled ============================================ ============================================================================================== ``name`` IP-Pool Name ``--ranges `` Comma separated list of IP ranges to assign to IP-Pool. Each range can also be specified in CIDR format ``--network `` IP network without ranges to be used for static IP allocations ``--netmask `` Mask indicating number of IP addresses that can be used from given range ``--prefix `` CIDR prefix to be used with the IP-Pool ``--zone `` Name of zone in which to create this IP-Pool ``--tenant `` Name of Tenant to which this IP-Pool belongs to ``--vlan `` VLAN to be associated with this IP-Pool. Note this option is only valid for OVS and SR-IOV driver backed IP-Pools ``--driver `` Driver to back this IP-Pool. Valid choices include: OVS, Calico, Secondary, Isolated, MACVLAN and SR-IOV ``--gateway `` Default gateway to be used for this IP-Pool ``--nameserver `` Comma separated list of DNS name servers to be used for Pods deployed using this IP-Pool ``--dns-search `` Comma separated list of DNS search strings to be used for Pods deployed using this IP-Pool ``--nictags `` Comma separated NIC tags to select when assigning interfaces from this network. Each tag must be specified as key/value pair in the format key=value. Only keys "name" and "pci_addr" are supported ``--ifcount `` Preset the interface count when using this network. Applicable only for the SR-IOV driver ``--routes `` Comma separated list of routes to associated with this network ``--vfdriver `` Kernel driver to bind to when attaching an SR-IOV virtual function. Applicable only for the SR-IOV driver ``--master-interface `` Master interface to be used for the MACVLAN plugin. Applicable only for the MACVLAN driver ``--macvlan-mode `` Mode for the MACVLAN plugin in order to configure the traffic visibility on the virtual network. Applicable only for the MACVLAN driver. Valid choices include: Private, Vepa and Bridge. The default value is Bridge when the MACVLAN driver is used ``--blacklist-ips `` Comma separated list of IP Addresses that cannot be used for any IP allocation(s) from this IP-Pool. Note any IP addresses specified here cannot also be specified with the ``--reserved-ips`` parameter ``--reserved-ips `` Comma separated list of IP Addresses that cannot be used for any non-static IP allocation(s) from this IP-Pool. Note any IP addresses specified here cannot also be specified with the ``--blacklist-ips`` parameter ``--mtu `` Set the maximum transmission unit (MTU) value for the interfaces within the IP-Pool. Note that if MTU is not specified, the MTU of the underlying physical interfaces will be used ``--trusted`` Enable trusted mode by default for Virtual Functions assigned as part of allocations from this IP-Pool. Note this option is only valid for SR-IOV driver backed IP-Pools ``--spoofchk-disabled`` Disable spoof checking by default for Virtual Functions assigned as part of allocations from this IP-Pool. Note this option is only valid for SR-IOV driver backed IP-Pools ============================================ ============================================================================================== .. Note:: At least one of the ``--network`` or ``--ranges`` options must be given when creating an IP-Pool however both cannot be used. Similarly either one of the ``--prefix`` or ``--netmask`` parameters must be utilized but both cannot be specified. If an IP-Pool is created without ranges, it can only be used for static IP Address allocations. **Example 1 (Creating a basic OVS IP-Pool):** .. code-block:: text # robin ip-pool add demo --ranges 10.9.106.1-255 --netmask 255.255.0.0 --driver ovs Registered IP pool demo. **Example 2 (Creating an SR-IOV IP-Pool with VLAN):** .. code-block:: text # robin ip-pool add demo --ranges 10.9.106.1-255 --netmask 255.255.0.0 --driver sriov --vlan 500 Registered IP pool demo. With the above IP-Pool Robin will select VF's based on the VLANs allowed for a particular NIC. **Example 3 (Creating an SR-IOV IP-Pool with NIC tags using the pci_address parameter):** .. code-block:: text # robin ip-pool add demo --ranges 10.9.106.1-255 --netmask 255.255.0.0 --driver sriov --vlan 500 --nictags pci_addr=0000:3b:00.0 Registered IP pool demo. With the above IP-Pool Robin will select VF's only from NICs with the pci address "0000:3b:00.0". **Example 5 (Creating an SR-IOV IP-Pool with NIC tags using the name parameter):** .. code-block:: text # robin ip-pool add demo --ranges 10.9.106.1-255 --netmask 255.255.0.0 --driver sriov --vlan 500 --nictags name=sriov0 Registered IP pool demo. With the above IP-Pool Robin will select VF's only from NICs with the name "sriov0". **Example 6 (Creating an SR-IOV IP-Pool with Bonded VFs):** .. code-block:: text # robin ip-pool add demo --ranges 192.168.1.101-110 --netmask 255.255.255.0 --driver sriov --vlan 500 --ifcount 2 --nictags name=sriov0,name=sriov2 Registered IP pool demo. With the above IP-Pool Robin will select one VF from a NIC named sriov0, one VF from a NIC named sriov2 and bond them together. **Example 7 (Creating an SR-IOV IP-Pool with Bonded VFs based on VLAN):** .. code-block:: text # robin ip-pool add demo --ranges 192.168.1.101-110 --netmask 255.255.255.0 --driver sriov --vlan 500 --ifcount 2 Registered IP pool demo. With the above IP-Pool Robin will select two VFs from two NICs (one from each) where VLAN 500 is allowed and bond them together. **Example 8 (Creating an SR-IOV IP-Pool with Bonded VFs from the same NIC):** .. code-block:: text # robin ip-pool add demo --ranges 192.168.1.101-110 --netmask 255.255.255.0 --driver sriov --vlan 500 --ifcount 2 --nictags name=sriov0,name=sriov0 Registered IP pool demo. With the above IP-Pool Robin will select two VFs from a NIC named sriov0 and bond them together. **Example 9 (Creating an SR-IOV IP-Pool with VF Driver):** .. code-block:: text # robin ip-pool add demo --ranges 192.168.1.101-110 --netmask 255.255.255.0 --driver sriov --vlan 500 --nictags name=sriov0 --vfdriver igb_uio Registered IP pool demo. With the above IP-Pool Robin will select one VF from a NIC named sriov0 and bind it with the specified driver. **Example 10 (Creating an IP-Pool by specifying IP ranges in network/CIDR format):** .. code-block:: text # robin ip-pool add demo --ranges 192.10.88.0/24 --netmask 255.255.0.0 --driver ovs Registered IP pool demo. With the above IP-Pool Robin will configure its ranges utilizing the CIDR format i.e (/24, /16, /26 etc) with which the ranges were represented. **Example 11 (Creating an MACVLAN based IP-Pool):** .. code-block:: text # robin ip-pool add demo --driver macvlan --ranges 192.168.10.21-30 --prefix 24 --gateway 192.168.10.1 --master-interface=ens18f1 --macvlan-mode bridge Registered IP pool demo. With the above IP-Pool Robin will configure the MACVLAN CNI as the primary network driver with the primary master interface as ens18f1 operating in bridge mode. **Example 12 (Creating an IP-Pool for assigning secondary IP Addresses):** .. code-block:: text # robin ip-pool add demo --driver secondary --ranges 192.168.10.21-30 --prefix 24 Registered IP pool demo. With the above IP-Pool defined Robin will construct a standard IP-Pool with the additional caveat that it can only used in conjunction with another IP-Pool (known as the primary IP-Pool) in order to enable the assignment of multiple IP Addresses to a single interface. The aforementioned primary IP-Pool must be SRIOV or OVS based. **Example 13 (Creating an isolated IP-Pool):** .. code-block:: text # robin ip-pool add demo --driver isolated --ranges 192.168.10.21-30 --prefix 24 Registered IP pool demo. With the above IP-Pool Robin will utilize the custom ``robin-isolated`` CNI plugin in order to configure an additional IP Address on a Pod's loopback ``lo`` interface. **Example 14 (Creating an IP-Pool with blacklisted IP addresses):** .. code-block:: text # robin ip-pool add demo --ranges 192.0.2.101-150 --netmask 255.255.0.0 --driver ovs --blacklist-ips 192.0.2.101-110 Registered IP pool demo. With the above IP-Pool Robin will ensure IP Addresses in the range 192.0.2.101-110 will not be used for any IP allocations when this IP-Pool is used. **Example 15 (Creating an IP-Pool with reserved IP addresses):** .. code-block:: text # robin ip-pool add demo --ranges 192.0.2.151-199 --netmask 255.255.0.0 --driver ovs --reserved-ips 192.0.2.151-160 Registered IP pool demo. With the above IP-Pool Robin will ensure IP Addresses in the range 192.0.2.151-160 will not be used for any non-static IP allocations when this IP-Pool is used. .. Note:: In all the above examples for SR-IOV backed IP-Pools, when the ``--vlan`` option is specified independently of any other parameters it acts as a constraining factor whilst also tagging outgoing packets. In every other scenario only the latter holds true. As a result when options such as the ``--nictags`` option is passed alongside the ``--vlan`` option, the latter stops becoming a constraining factor. .. tab:: API Adds an IP-Pool for Robin to utilize during application deployment. **End Point:** /api/v3/robin_server/ip-pools **Method:** POST **URL Parameters:** None **Data Parameters:** - ``ip_pool: `` -- - ``name: `` - This mandatory field within the payload specifies the name of the IP-Pool to be created. - ``driver: `` - This mandatory field within the payload specifies the network driver to be associated with the IP-Pool. Valid options include: 'ovs', 'sriov', 'secondary', 'isolated', 'macvlan' and 'calico'. - ``zoneid: `` - This mandatory field within the payload specifies the name of the zone in which the IP-Pool should be created. - ``ranges: `` - Utilizing this parameter within the payload, by specifying a list containing dictionaries in the form ``{'range': }`` for each range, results in the specified ranges being assigned to this IP-Pool. - ``network: `` - Utilizing this parameter within the payload, by specifying an IP network without ranges, results in the specified network being used for IP allocations when utilizing this network. - ``netmask: `` - Utilizing this parameter within the payload, by specifying an appropriate mask, results in aforementioned mask being applied to the specified ranges and thus indicating the number of IP addresses that can be used. - ``prefix: `` - Utilizing this parameter within the payload, by specifying a CIDR prefix, results in the aforementioned prefix being associated with the IP-Pool. - ``tenant: `` - Utilizing this parameter within the payload, by specifying a tenant name, results in the IP-Pool being associated with the aforementioned tenant. - ``vlan_number: `` - Utilizing this parameter within the payload, by specifying a VLAN number, results in the IP-Pool being associated with the aforementioned VLAN number. Note this option is only valid for OVS and SR-IOV driver backed IP-Pools. - ``gateway: `` - Utilizing this parameter within the payload, by specifying a gateway, results aforementioned gateway being set as the default gateway for the IP-Pool. - ``nameserver: `` - Utilizing this parameter within the payload, by specifying a string of DNS name servers which are comma seperated, results in the aforementioned name servers being used for Pods deployed using this IP-Pool. - ``dns_search: `` - Utilizing this parameter within the payload, by specifying a string of DNS search strings which are comma seperated, results in the aforementioned search strings being used for Pods deployed using this IP-Pool. - ``nictags: `` - Utilizing this parameter within the payload, by specifying a list containing dictionaries in the form ``{: }`` for each NIC tag, results in only interfaces associated with the aforementioned tags being utilized when using this IP-Pool. Note only keys "name" and "pci_address" are supported. - ``ifcount: `` - Utilizing this parameter within the payload presets the interface count for allocations to the integer specified when using this network. Valid values include 1 and 2. Note this option is only valid for SR-IOV driver backed IP-Pools. - ``routes: `` - Utilizing this parameter within the payload, by specifying a list containing dictionaries in the form ``{'dest': , 'gateway': }`` for each route, results in the specified routes being associated with this IP-Pool. - ``vfdriver: `` - Utilizing this parameter within the payload, by specifying the name of a kernel driver, results in the aforementioned driver being bound to when attaching an SR-IOV virtual function. Valid options include: 'igb_uio', 'vfio-pci', and 'uio_pci_generic'. Note this option is only valid for SR-IOV driver backed IP-Pools. - ``master_interface: `` - Utilizing this parameter within the payload, by specifying the name of a valid interface, results in the aforementioned interface being used as the master interface for the MACVLAN plugin. Note this option is only valid for MACVLAN driver backed IP-Pools. - ``macvlan_mode: `` - Utilizing this parameter within the payload, by specifying the name of a valid mode, results in the MACVLAN plugin being configured with the aforementioned mode which in turn determines the traffic visibility on the virtual network. Valid options include: 'private', 'vepa', and 'bridge'. Note this option is only valid for MACVLAN driver backed IP-Pools and the default value is 'bridge'. - ``blacklist_ips: `` - Utilizing this parameter within the payload, by specifying a string of IP Addresses which are comma seperated, results in the aforementioned IP Addresses not being used for any IP allocation(s) from this IP pool. - ``reserved_ips: `` - Utilizing this parameter within the payload, by specifying a string of IP Addresses which are comma seperated, results in the aforementioned IP Addresses not being used for any non-static IP allocation(s) from this IP pool. - ``qos: `` - Utilizing this parameter within the payload, by specifying an integer between 0 and 7, results in the associated quality of service being assigned to this IP-Pool. - ``min_tx_rate: `` - Utilizing this parameter within the payload, by specifying an integer, results in the minimum transmit bandwidth being set to the given value for any SR-IOV virtual function assigned using this IP-Pool. Note this option is only valid for SR-IOV driver backed IP-Pools. - ``min_tx_rate: `` - Utilizing this parameter within the payload, by specifying an integer, results in the maxiumum transmit bandwidth being set to the given value for any SR-IOV virtual function assigned using this IP-Pool. Note this option is only valid for SR-IOV driver backed IP-Pools. - ``trusted: 'on'`` - Utilizing this parameter within the payload results in trusted mode being enabled by default for Virtual Functions assigned as part of allocations from this IP pool. Note this option is only valid for SR-IOV driver backed IP-Pools. - ``spoofchk: 'off'`` - Utilizing this parameter within the payload results in spoof checking being disabled by default for Virtual Functions assigned as part of allocations from this IP pool. Note this option is only valid for SR-IOV driver backed IP-Pools. .. Note:: At least one of the ``network`` or ``ranges`` properties must be given when creating an IP-Pool however both cannot be used. Similarly either one of the ``prefix`` or ``netmask`` properties must be utilized but both cannot be specified. If an IP-Pool is created without ranges, it can only be used for static IP Address allocations. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error), 409 (Duplicate Resource Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Registered IP pool demo. \n" } .. raw:: html
.. Important:: The default limit of IP addresses per IP range is eight thousand IPs. If you need to increase or decrease the default limit, you must update the ``max_ips_per_range`` config attribute in the Cluster-wide Attributes. For more information, see `Cluster wide Attributes `__. ================================== Adding certificates to an IP-Pool ================================== .. tabs:: .. tab:: CLI To add certificates to an IP-Pool in order to make certain addresses accessible in a secure manner, issue the following command: .. code-block:: text # robin ip-pool add-certs --keypass --is_hostnames --no_multinode ======================== ============================================================================================================================ ``name`` IP-Pool Name ``certificates`` Path to SSL certificates file ``--keypass `` Passphrase of the key ``--is_hostnames`` Indicates that the filename specified contains the hostname and its format is . ``--no_multinode`` Indicates that the certificate can be used for multiple hosts ======================== ============================================================================================================================ **Example:** .. code-block:: text # robin ip-pool add-cert demo ~/ssl/demo-cert Added certificates. .. tab:: API Adds certificates to an IP-Pool in order to make certain addresses accessible in a secure manner. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_certs`` - This mandatory field within the payload specifies that the add certificates operation is to be performed. - ``cert_info: `` -- - ``filename: `` - This mandatory field within the payload specifies the base file name of the certificate file. - ``certificate: `` - This mandatory field within the payload specifies the base64 decoded details within the specified file. - ``multinode: [true|false]`` - Utilizing this parameter within the payload indicates whether or not this certificate can be used for multiple hosts. - ``is_hostnames: [true|false]`` - Utilizing this parameter within the payload indicates whether or not the specified certificate filename contains the hostname and is in the format .. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Added certificates.\n" } .. raw:: html
================================== Adding ranges to an IP-Pool ================================== .. tabs:: .. tab:: CLI To add additional ranges to an IP-Pool in order to expand the number of IP Addresses available, issue the following command: .. code-block:: text # robin ip-pool add-ranges ====================== ============================================================================================================================ ``name`` IP-Pool Name ``ranges`` Comma separated list of additional IP ranges to assign to IP-Pool ====================== ============================================================================================================================ **Example:** .. code-block:: text # robin ip-pool add-ranges demo 10.9.107.1-255 Added range. .. tab:: API Adds IP ranges that are currently assigned to an IP-Pool in order to expand the number of available IP ranges. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_ranges`` - This mandatory field within the payload specifies that the add ranges operation is to be performed. - ``ranges: `` - This mandatory field within the payload specifies a list of comma seperated ranges to be added from the given IP-Pool. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Added range.\n" } .. raw:: html
====================================================== Adding blacklisted IP addresses to an existing IP-Pool ====================================================== .. tabs:: .. tab:: CLI To blacklist an individual IP address, a set of IP addresses or a range of IP addresses such that they cannot be used for any IP allocation(s) from the given IP-Pool, run the following command: .. Important:: When one or more IP address ranges exist in an IP-Pool, a set of IP addresses that are part of multiple ranges cannot be blacklisted. Instead only IP addresses within a singular range or an entire range itself can be blacklisted. .. code-block:: text # robin ip-pool add-blacklist-ips ================== ============================================================================================================================ ``name`` IP-Pool Name. ``blacklist_ips`` Comma separated list of the IP addresses to blacklist ================== ============================================================================================================================ .. Note:: An IP Address or a range of IP addresses cannot be blacklisted and reserved simultaneously. **Example:** .. code-block:: text # robin ip-pool add-blacklist-ips demo 192.0.2.101-110,192.0.2.114,192.0.2.120-125 Added blacklist IPs. .. tab:: API Blacklists an individual IP address, a set of IP addresses or a range of IP addresses such that they cannot be used for any IP allocation(s) from the given IP-Pool. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_blacklist_ips`` - This mandatory field within the payload specifies that the add blacklisted IPs operation is to be performed. - ``blacklist_ips: `` - This mandatory field within the payload specifies the set of IP Addresses and or range(s) to be blacklisted via a string containing the comma seperated addresses. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Added blacklist IPs.\n" } .. raw:: html
====================================================== Adding reserved IP addresses to an existing IP-Pool ====================================================== .. tabs:: .. tab:: CLI To reserve an individual IP address, a set of IP addresses or a range of IP addresses such that they cannot be used for any non-static IP allocation(s) from the given IP-Pool, run the following command: .. Important:: When one or more IP address ranges exist in an IP-Pool, a set of IP addresses that are part of multiple ranges cannot be reserved. Instead only IP addresses within a singular range or an entire range itself can be reserved. .. code-block:: text # robin ip-pool add-reserved-ips ================== ============================================================================================================================ ``name`` IP-Pool Name. ``reserved_ips`` Comma separated list of the IP addresses to reserve ================== ============================================================================================================================ .. Note:: An IP Address or a range of IP addresses cannot be blacklisted and reserved simultaneously. **Example:** .. code-block:: text # robin ip-pool add-reserved-ips demo 192.0.2.101-110,192.0.2.114,192.0.2.120-125 Added reserved IPs. .. tab:: API Reserves an individual IP address, a set of IP addresses or a range of IP addresses such that they cannot be used for any non-static IP allocation(s) from the given IP-Pool. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_reserved_ips`` - This mandatory field within the payload specifies that the add reserved IPs operation is to be performed. - ``reserved_ips: `` - This mandatory field within the payload specifies the set of IP Addresses or range(s) to be reserved via a string containing the comma seperated addresses. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Added reserved IPs.\n" } .. raw:: html
==================================== Adding routes to an existing IP-Pool ==================================== .. tabs:: .. tab:: CLI Robin enables users to add IP routes to an existing IP-Pool in order to modify the VNF network routing in-place whilst not impacting running applications with the following command: .. Note:: After adding routes to an existing IP Pool, you must restart the Pods for them to start using the new routes. .. code-block:: text # robin ip-pool add-routes =========== ============================================== ``name`` IP-Pool Name ``routes`` Comma separated list of IP routes to be added =========== ============================================== **Example:** .. code-block:: text # robin ip-pool add-routes ovs-mgmt-2 2001:db8:3a09:868f:0010:0009:0150:0001/64@2001:db8:3a09:868c:0010:0009:0150:0001 Added routes. ================================== Listing registered IP-Pools ================================== .. tabs:: .. tab:: CLI To list registered IP-Pools alongside details such as the associated driver and network ranges contained within each pool, issue the following command: .. code-block:: text # robin ip-pool list --all --full --json ====================== ============================================================================================================================ ``--all`` Display all registered IP-Pools including hidden ones ``--full`` Display additional information for listed IP-Pools ``--json`` Output in JSON ====================== ============================================================================================================================ **Example:** .. code-block:: text # robin ip-pool list --all Name | Driver | Network | VLAN | Total | Used | Free -----------------+--------+---------------+------+-------+------+------ nonrobin-default | calico | 172.21.0.0/16 | - | 4096 | 2 | 4094 robin-default | calico | 172.21.0.0/16 | - | 4096 | 0 | 4096 demo | ovs | 10.9.0.0/16 | - | 255 | 0 | 255 .. tab:: API Returns all registered IP-Pools alongside details such as the associated driver and network ranges contained within each pool. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** GET **URL Parameters:** None **Data Parameters:** - ``all: true`` - Utilizing this parameter within the payload results in details of hidden IP-Pools being returned as well. **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) **Example Response:** .. raw:: html
Output .. code-block:: text { "items":[ { "name":"nonrobin-default", "description":null, "available":null, "used":null, "total":null, "blacklisted":null, "blacklist_ips":null, "reserved":null, "reserved_ips":null, "zone":"default", "zone_id":1, "tenants":[ ], "driver":"calico", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"172.21.64-127.0-255" } ], "netmask":"255.255.192.0", "subnet":"172.21.64.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null }, { "name":"robin-default", "description":null, "available":"4096", "used":"0", "total":"4096", "blacklisted":"0", "blacklist_ips":"None", "reserved":"0", "reserved_ips":"None", "zone":"default", "zone_id":1, "tenants":[ "Administrators" ], "driver":"calico", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"172.21.16-31.0-255" } ], "netmask":"255.255.192.0", "subnet":"172.21.0.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null }, { "name":"ovs-1", "description":null, "available":"2", "used":"3", "total":"5", "blacklisted":"0", "blacklist_ips":"", "reserved":"3", "reserved_ips":"10.9.86.17-19", "zone":"default", "zone_id":1, "tenants":[ "Administrators" ], "driver":"ovs", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"10.9.86.16-20" } ], "netmask":"255.255.0.0", "subnet":"10.9.0.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null }, { "name":"ovs-2", "description":null, "available":"5", "used":"0", "total":"5", "blacklisted":"0", "blacklist_ips":"", "reserved":"5", "reserved_ips":"10.9.86.21-25", "zone":"default", "zone_id":1, "tenants":[ "Administrators" ], "driver":"ovs", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"10.9.86.21-25" } ], "netmask":"255.255.0.0", "subnet":"10.9.0.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null }, { "name":"demo", "description":null, "available":"39", "used":"0", "total":"50", "blacklisted":"11", "blacklist_ips":"192.0.2.101-110,192.0.2.112", "reserved":"0", "reserved_ips":"", "zone":"default", "zone_id":1, "tenants":[ "Administrators" ], "driver":"ovs", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"192.0.2.101-150" } ], "netmask":"255.255.0.0", "subnet":"192.0.0.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null } ] } .. raw:: html
.. tab:: Kubernetes To list registered IP-Pools via the ``robinippool`` custom resource alongside details such as the associated driver, network ranges, VLANs and bonded NICs contained within each pool, issue the following command: .. code-block:: text # kubectl get robinippool **Example:** .. code-block:: text [root@qct-05 ~]# kubectl get robinippool NAME NETMASK NETWORK IPPREFIX SUBNET GATEWAY NAMESERVER DRIVER VFDRIVER RANGE(S) VLAN BONDED TRUST SPOOFCHK robin-default 255.255.0.0 172.21.0.0 calico ["172.21.16-31.0-255"] 1 sec-1 255.255.255.0 24 192.168.1.0 secondary ["192.168.1.11-20"] 1 sec-2 255.255.255.0 24 192.168.2.0 secondary ["192.168.2.11-20"] 1 sriov-b1 255.255.255.0 192.168.110.0 sriov ["192.168.110.165-170"] 20 2 off on sriov-b2 255.255.255.0 192.168.111.0 sriov ["192.168.111.165-170"] 20 2 off on sriov1 255.255.255.0 192.168.10.0 sriov igb_uio ["192.168.10.101-164"] 20 1 off on sriov10 255.255.255.0 192.168.100.0 sriov native ["192.168.100.101-164"] 20 1 off on sriov2 255.255.255.0 192.168.20.0 sriov igb_uio ["192.168.20.101-164"] 20 1 off on sriov3 255.255.255.0 192.168.30.0 sriov igb_uio ["192.168.30.101-164"] 20 1 off on sriov4 255.255.255.0 192.168.40.0 sriov igb_uio ["192.168.40.101-164"] 20 1 off on sriov5 255.255.255.0 192.168.50.0 sriov native ["192.168.50.101-164"] 20 2 off on sriov6 255.255.255.0 192.168.60.0 sriov native ["192.168.60.101-164"] 20 2 off on sriov7 255.255.255.0 192.168.70.0 sriov native ["192.168.70.101-164"] 20 1 off on sriov8 255.255.255.0 192.168.80.0 sriov native ["192.168.80.101-164"] 20 1 off on sriov9 255.255.255.0 192.168.90.0 sriov native ["192.168.90.101-164"] 20 1 off on sriov98 255.255.255.0 192.168.98.0 sriov igb_uio ["192.168.98.101-164"] 20 1 off on sriov99 255.255.255.0 192.168.99.0 sriov igb_uio ["192.168.99.101-164"] ============================================= Show information about a specific IP-Pool ============================================= .. tabs:: .. tab:: CLI To view details about a particular IP-Pool including its utilization, associated driver, and the network range(s) it covers, issue the following command: .. code-block:: text # robin ip-pool info --ip-allocations --instance-ips --json --page_size --page_num --mac-allocations ====================== ============================================================================================================================ ``name`` Name of IP-Pool ``--ip-allocations`` Display IP allocations of each pod created using helm or kubectl within the specified IP-Pool ``--instance-ips`` Display IP allocations of each pod created using a Robin bundle within the specified IP-Pool ``--json`` Output in JSON ``--page_size (-n)`` Number of IP addresses for each page ``--page_num (-p)`` Page number starting from index 1 ``--mac-allocations`` Display MAC allocations for each Pod resource in the Robin IP-Pool ====================== ============================================================================================================================ **Example:** .. code-block:: text # robin ip-pool info sriovpool --mac-allocations IPPool: sriovpool Driver: sriov Trust Mode: off Spoof Check: on Gateway: 10.10.0.1 Subnet: 10.10.0.0 Netmask: 255.255.0.0 Range: 192.0.2.100-191 Blacklisted IPs: No Blacklist IPs configured Reserved IPs: No Reserved IPs configured Pool Utilization: 8/84/0/0/92 (Used/Available/Blacklisted/Reserved/Total) MAC Allocations: default-pod-pktgen-s9-69d6888d7-jhdlw : 04:05:05:07:08:09 default-pod-pktgen-s9-69d6888d7-4zkjr : 04:03:06:07:08:09 default-pod-pktgen-s9-69d6888d7-lwrw5 : 04:04:06:07:08:09 default-pod-pktgen-s9-69d6888d7-hprkv : 04:08:06:07:08:09 default-pod-pktgen-s9-69d6888d7-mpknb : 04:06:06:07:08:09 default-pod-pktgen-s9-69d6888d7-2mfqs : 04:07:06:07:08:09 default-pod-pktgen-s9-69d6888d7-6gbkq : 04:10:06:07:08:09 default-pod-pktgen-s9-69d6888d7-m7nfl : 04:09:06:07:08:09 .. tab:: API Returns details about a particular IP-Pool including its utilization, associated driver, and the network range(s) it covers. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** GET **URL Parameters:** None **Data Parameters:** - ``name: `` - This mandatory parameter within the payload specifies which IP-Pool actually needs to be queried. **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), 404 (Not Found Error), 401 (Unauthorized Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "items":[ { "name":"demo", "description":null, "available":"39", "used":"0", "total":"50", "blacklisted":"11", "blacklist_ips":"192.0.2.101-110,192.0.2.112", "reserved":"0", "reserved_ips":"", "zone":"default", "zone_id":1, "tenants":[ "Administrators" ], "driver":"ovs", "gateway":null, "nameserver":null, "vfdriver":null, "dns_search":null, "ranges":[ { "range":"192.0.2.101-150" } ], "netmask":"255.255.0.0", "subnet":"192.0.0.0", "nictags":null, "ifcount":1, "routes":[ ], "qos":null } ] } .. raw:: html
===================== Removing an IP-Pool ===================== .. tabs:: .. tab:: CLI To remove an IP-Pool from Robin, issue the following command: .. code-block:: text # robin ip-pool remove --yes ====================== ============================================================================================== ``name`` IP-Pool Name ``--yes`` Do not prompt the user for confirmation of deletion ====================== ============================================================================================== **Example:** .. code-block:: text # robin ip-pool remove demo --yes Unregistered IP-Pool 'demo'. .. tab:: API Removes an IP-Pool from Robin. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** DELETE **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), 404 (Not Found Error), 401 (Unauthorized Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Unregistered IP pool demo.\n" } .. raw:: html
================================ Removing ranges from an IP-Pool ================================ .. tabs:: .. tab:: CLI To remove IP ranges that are currently assigned to an IP-Pool in order to reduce the number of available IP ranges, issue the following command: .. code-block:: text # robin ip-pool remove-ranges --yes ====================== ============================================================================================== ``name`` IP-Pool Name ``ranges`` Comma separated list of IP ranges to remove from an IP-Pool ``--yes`` Do not prompt the user for confirmation of removal ====================== ============================================================================================== **Example:** .. code-block:: text # robin ip-pool remove-ranges demo 10.9.107.1-255 --yes Removed range. .. tab:: API Removes IP ranges that are currently assigned to an IP-Pool in order to reduce the number of available IP ranges. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: remove_ranges`` - This mandatory field within the payload specifies that the remove ranges operation is to be performed. - ``ranges: `` - This mandatory field within the payload specifies a list of comma seperated ranges to be removed from the given IP-Pool. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Removed range.\n" } .. raw:: html
================================================= Removing blacklisted IP addresses from an IP-Pool ================================================= .. tabs:: .. tab:: CLI To remove the blacklisted IP addresses from an IP-Pool such that they are available for allocation again, run the following command: .. code-block:: text # robin ip-pool remove-blacklist-ips --yes ====================== ============================================================================================== ``name`` IP-Pool Name ``blacklist_ips`` Comma separated list of the blacklisted IP addresses to remove from an IP-Pool ``--yes`` Do not prompt the user for confirmation of deletion ====================== ============================================================================================== .. Note:: If a range of IP addresses were blacklisted, you cannot whitelist a single or multiple IP addresses from the previously blacklisted range of IP addresses. Instead the entire range of IP addresses must be specified as part of the above operation. **Example:** .. code-block:: text # robin ip-pool remove-blacklist-ips demo 192.0.2.101-110 --yes Removed blacklist IPs. .. tab:: API Removes blacklisted IP addresses from an IP-Pool such that they are available for allocation again. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: remove_blacklist_ips`` - This mandatory field within the payload specifies that the remove blacklisted IPs operation is to be performed. - ``blacklist_ips: `` - This mandatory field within the payload specifies the set of blacklisted IP Addresses or range(s) to be removed via a string containing the comma seperated addresses. .. Note:: If a range of IP addresses were blacklisted, you cannot whitelist a single or multiple IP addresses from the previously blacklisted range of IP addresses. Instead the entire range of IP addresses must be specified as part of the above operation. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Removed blacklist IPs.\n" } .. raw:: html
================================================= Removing reserved IP addresses from an IP-Pool ================================================= .. tabs:: .. tab:: CLI To remove the reserved IP addresses from an IP-Pool such that they are available for general allocation again, run the following command: .. code-block:: text # robin ip-pool remove-reserved-ips --yes ====================== ============================================================================================== ``name`` IP-Pool Name ``reserved_ips`` Comma separated list of the reserved IP addresses to remove from an IP-Pool ``--yes`` Do not prompt the user for confirmation of deletion ====================== ============================================================================================== .. Note:: If a range of IP addresses were reserved, you cannot unreserve a single or multiple IP addresses from the previously reserved range of IP addresses. Instead the entire range of IP addresses must be unreserved. **Example:** .. code-block:: text # robin ip-pool remove-reserved-ips demo 192.0.2.101-110 --yes Removed reserved IPs. .. tab:: API Removes reserved IP addresses from an IP-Pool such that they are available for general allocation again. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: remove_reserved_ips`` - This mandatory field within the payload specifies that the remove blacklisted IPs operation is to be performed. - ``reserved_ips: `` - This mandatory field within the payload specifies the set of reserved IP Addresses or range(s) to be removed via a string containing the comma seperated addresses. .. Note:: If a range of IP addresses were reserved, you cannot unreserve a single or multiple IP addresses from the previously reserved range of IP addresses. Instead the entire range of IP addresses must be unreserved. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"Removed reserved IPs.\n" } .. raw:: html
======================================== Removing routes from an existing IP-Pool ======================================== .. tabs:: .. tab:: CLI In order to remove IP routes from an existing IP-Pool such that they can no longer be used, issue the following command: .. code-block:: text # robin ip-pool remove-routes =========== ================================================ ``name`` IP-Pool Name ``routes`` Comma separated list of IP routes to be removed =========== ================================================ **Example:** .. code-block:: text # robin ip-pool remove-routes ovs-mgmt-2 2001:db8:3a09:868f:0010:0009:0150:0001/64@2001:db8:3a09:868c:0010:0009:0150:0001 Removed routes. ================================ Renaming an IP-Pool ================================ .. tabs:: .. tab:: CLI To rename an IP-Pool, issue the following command: .. code-block:: text # robin ip-pool rename ====================== ============================================================================================== ``name`` IP-Pool Name ``new_name`` New name of the specified IP-Pool ====================== ============================================================================================== **Example:** .. code-block:: text # robin ip-pool rename demo demo_change IP-Pool 'demo' renamed to 'demo_change'. .. tab:: API Renames an existing IP-Pool. **End Point:** /api/v3/robin_server/ip-pools/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: rename`` - This mandatory field within the payload specifies that the rename operation is to be performed. - ``new_name: `` - This mandatory field within the payload specifies the new name for the specified IP-Pool. **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"IP-Pool 'demo' renamed to 'demo_change'.\n" } .. raw:: html
VLAN Support =================== The VLAN (Virtual LAN) feature allows one to logically group a set of devices in the same L2 domain irrespective of how they are physically connected. Additionally one can carve out logical groups even if the devices are connected to the same L2 switch. Listed below are some of the advantages of using VLANs: - Performance - Broadcast traffic is sent to all the nodes in an L2 domain. VLANs allow creating groups or virtual L2 domains, thus containing the broadcast traffic to the created logical groups. - Isolation and Security - VLANs allow one to control the broadcast domain and enforce which logical groups can talk to one another - Flexibility - A device can be easily added/removed from a VLAN logical group without actually changing the physical connectivity - Cost Reduction - VLANs can be used to create broadcast domains without the need for expensive routers Along with additional details, the following commands are described in this section: =============================== ================================================================================= ``robin vlan add`` Register a VLAN ``robin vlan list`` List VLANs ``robin vlan remove`` Unregister a VLAN ``robin host add-vlan`` Configure a VLAN for an interface on a host ``robin host remove-vlan`` Remove a VLAN from an interface on a host =============================== ================================================================================= =================== Registering a VLAN =================== .. tabs:: .. tab:: CLI To register a VLAN with Robin so it can be configured for an interface, issue the following command: .. code-block:: text # robin vlan add --skip-vlan-interface --add-vlan-interface .. Note:: The Robin server might need to access pods deployed in a particular VLAN. As a result a VLAN interface needs to be created on the current Robin Master. This VLAN interface is created, when ``--add-vlan-interface`` is enabled, on the aforementioned node when an IP-Pool is created and has an associated VLAN. The IP address linked to the VLAN interface is picked from the addresses provided in the IP-Pool. In some deployments, VLAN routing could be provided in a different manner and thus a VLAN interface might not be needed on the Robin Master. If this is the case, you can create VLAN with ``--skip-vlan-interface`` option (this is the default behavior). ========================= ============================================================================================== ``vlan_number`` VLAN number/identifier ``--skip-vlan-interface`` Skips VLAN interface configuration on the Robin Master node ``--add-vlan-interface`` Configures the VLAN interface on the Robin Master node ========================= ============================================================================================== **Example:** .. code-block:: text # robin vlan add 9 --wait Job: 180 Name: VLANAdd State: PROCESSED Error: 0 Job: 180 Name: VLANAdd State: COMPLETED Error: 0 .. tab:: API Registers a VLAN with Robin so it can be configured for an interface. **End Point:** /api/v3/robin_server/vlans **Method:** POST **URL Parameters:** None **Data Parameters:** - ``vlan: `` - This mandatory field within the payload specifies the VLAN number for the VLAN to be registered. - ``skip_vlan_interface: [true|false]`` - This mandatory field within the payload is a boolean value that specifies whether or not the VLAN interface should be configured on the Robin Master node. **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:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error), 409 (Duplicate Resource Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":209 } .. raw:: html
====================== Listing all VLANs ====================== .. tabs:: .. tab:: CLI To list registered VLANs alongside details such as the IP-Pools it is assigned to and the number of NICs associated with it, issue the following command: .. code-block:: text # robin vlan list --json ====================== ============================================================================================================================ ``--json`` Output in JSON ====================== ============================================================================================================================ **Example:** .. code-block:: text # robin vlan list VLAN | IP Pools | Instance Count | Interface Count -----+----------+----------------+----------------- 9 | None | 0 | 0 .. tab:: API Returns all registered VLANs alongside details such as the IP-Pools it is assigned to and the number of NICs associated with it. **End Point:** /api/v3/robin_server/vlans/ **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) **Example Response:** .. raw:: html
Output .. code-block:: text { "items":[ { "skip_vlan_interface":true, "ip_pools":[ ], "instance_cnt":0, "number":9, "nic_cnt":0 } ] } .. raw:: html
============================= Configuring a VLAN on a host ============================= .. tabs:: .. tab:: CLI Before installing Robin on a VLAN based setup, it is expected that an administrator would have planned which VLANs are to be used for deploying applications and thus configured the installation appropriately. However in order to configure a VLAN post installation, issue the following command: .. code-block:: text # robin host add-vlan [] --vlans --interface --all --untagged =========================== ==================================================================================================== ``hosts`` A comma separated list of hosts to add VLANs to. If this isn't provided, then --all must be used ``--vlans `` Range of VLANs to be added (Use 'ALL' to enable all vlans) ``--interface `` Interface on host on which VLANs should be added ``--all`` VLANs will be added to every host in the cluster ``--untagged`` Network traffic will not be tagged with the VLAN number =========================== ==================================================================================================== **Example:** .. code-block:: text # robin host add-vlan vnode89.robinsystems.com --vlans 9 --interface br0 --untagged Job: 180 Name: HostVLANAdd State: PROCESSED Error: 0 Job: 180 Name: HostVLANAdd State: COMPLETED Error: 0 .. tab:: API Configures a VLAN on a host after Robin installation. **End Point:** /api/v3/robin_server/hosts/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_vlans`` - This mandatory field within the payload specifies that the add VLAN operation is to be performed. - ``vlans: `` - Utilizing this parameter in the payload, by specifying a range of VLANs, results in the aforementioned VLANs being configured on the host. - ``all_vlans: true`` - Utilizing this parameter in the payload results in all possible VLANs being configured on this host. The default value is False. - ``interface: `` - Utilizing this parameter in the payload, by specifying an interface name, results in the given VLANs being configured on the aforementioned interface. - ``untagged: true`` - Utilizing this parameter in the payload results in the VLAN being configured on SR-IOV interfaces as untagged. The default value is False. .. note:: Either the ``vlans`` or ``all_vlans`` parameter must be present in the request body. **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:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":217 } .. raw:: html
============================= Removing a VLAN from a host ============================= .. tabs:: .. tab:: CLI In order to remove a VLAN that is configured on an interface which is present on a host, issue the following command: .. code-block:: text # robin host remove-vlan [] --vlans --interface --all ============================ ======================================================================================================== ``hosts`` A comma separated list of hosts to remove VLANs from. If this isn't provided, then --all must be used ``--vlans `` Range of VLANs to be removed ``--interface `` Interface on host from which VLANs should be removed ``--all`` VLANs will be removed on every host in the cluster ============================ ======================================================================================================== **Example:** .. code-block:: text # robin host remove-vlan vnode89.robinsystems.com --vlans 9 --interface br0 Job: 180 Name: HostVLANRemove State: PROCESSED Error: 0 Job: 180 Name: HostVLANRemove State: COMPLETED Error: 0 .. tab:: API Removes a VLAN that is configured on an interface which is present on a host. **End Point:** /api/v3/robin_server/hosts/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: remove_vlans`` - This mandatory field within the payload specifies that the remove VLAN operation is to be performed. - ``vlans: `` - This mandatory field within the payload specifies the range of VLANs to be removed. - ``interface: `` - Utilizing this parameter in the payload indicates the interface on the specified host from which the VLAN(s) should be removed. **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:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":213 } .. raw:: html
====================== Unregistering a VLAN ====================== .. tabs:: .. tab:: CLI To unregister a VLAN from Robin, issue the following command: .. code-block:: text # robin vlan remove --yes .. Note:: The VLAN must be removed from all hosts it was configured on before it can be unregistered. ========================= ============================================================================================== ``vlan_number`` VLAN number/identifier ``--yes`` Do not prompt the user for confirmation of removal ========================= ============================================================================================== **Example:** .. code-block:: text # robin vlan remove 9 --wait --yes Job: 182 Name: VLANRemove State: PROCESSED Error: 0 Job: 182 Name: VLANRemove State: COMPLETED Error: 0 .. tab:: API Unregisters a VLAN from robin. **End Point:** /api/v3/robin_server/vlans/ **Method:** DELETE **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:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":83 } .. raw:: html
========================================== Assumptions made about VLAN Configurations ========================================== Below are a list of assumptions and/or rules that made with regards to VLAN integration with Robin: - Upstream ports are configured as trunk ports and the right VLANs are allowed on these ports. - On a single host with multiple ports, then same VLAN is not configured on different ports (an exception to this rule is SR-IOV ports). - Multiple IP subnets can be configured to be carried using the same VLAN. - The same IP subnet cannot be configured for two different VLANs. MACVLAN Support =================== With VLAN, you can create multiple sub-interfaces that uses the same MAC addresses, but the traffic is filtered based on the VLAN tag. With MACVLAN, each slave interface created on the top of the master interface is assigned a different MAC address. You can directly bound the MACVLAN slave interface to a namespace instead of relying on a tap or veth device along with a bridge to provide underlay network connectivity. To provide fault-tolerant connectivity to the workloads, Robin recommends using Bonded interfaces. You can also configure MACVLAN on Linux VLAN interfaces (eth0.) to provide tagging support for workloads. For more information, see `here `_. MACVLAN supports containers using MACVLAN CNI, and for KVM, MACVTAP interfaces are used. **Points to consider when using MACVLAN** - Robin supports the MACVLAN Bridge mode. - The MACVLAN design does not allow you to ping a workload (VM or container) from the host where the workload is deployed. - Due to the design constraint mentioned in the previous point, if you use MACVLAN as the default network for the workload, Kubernetes services may not work as expected. - It is recommended to have a dedicated interface on the node to provide MACVLAN based connectivity to the workloads. - OVS and MACVLAN provide similar kinds of connectivity, it is recommended not to use an OVS interface as the MACVLAN master interface. - By default, Robin installs OVS, but you can use the installer options ``—skip-ovs-cluster`` or ``—skip-ovs-node`` to disable OVS configuration at a cluster or node level. - If you are using MACVLAN as the primary CNI interface for a Pod, static routes including default gateway can be configured using the ``--routes`` option during IP-Pool creation. ====================== Configuring MACVLAN ====================== To configure the MACVLAN plugin via a Robin IP-Pool, review the example detailed `here `_. Managing PCI Resource Aliases ============================= Each PCI device present on a node that is discovered by Robin has the following attributes: PCI device ID, vendor ID, device type, and device driver. These attributes are collected because they uniquely identify each PCI device on a host. As a result, this also means anytime a PCI resource needs to be referred to for allocation purposes or simply for identification all of the aforementioned attributes must be specified. Given that this is particular cumbersome, Robin allows users to add a PCI Resource alias which associates a name with the given attributes and consequently links to the physical device they represent. These aliases can be used when deploying applications, both Helm and Robin bundle based, and allow for easier management of the PCI resource. Along with additional details, the following commands are described in this section: ===================================== ===================================================================== ``robin pci-resource add`` Used to add a PCI resource ``robin pci-resource remove`` Used to remove an existing pci resource ``robin pci-resource info`` Used to get pci resources info ``robin pci-resource list`` Used to all get pci resources ===================================== ===================================================================== ========================== Add a PCI Resource alias ========================== .. tabs:: .. tab:: CLI In order to add an alias of a PCI device that is currently present on the cluster, such that its identifying attributes like the device ID, driver type etc. dont have to be specified each time for every application deployment, run the following command: .. code-block:: text # robin pci-resource add --device-id --vendor-id --device-type --driver =============================== ================================================================================ ``name`` Name representing the alias of a PCI device ``-–device-id `` Device ID of the respective PCI device ``--vendor-id `` Vendor ID of the respective PCI device ``--device-type `` Device type of the respective PCI device ``--driver `` Associated driver of the respective PCI device =============================== ================================================================================ .. Note:: After the alias is successfully created, the name can simply be used to refer to the PCI resource for allocation within Robin bundle and helm application deployments. **Example** .. code-block:: text # robin pci-resource add pci-2 --device-id 0x0d90 --vendor-id 0x8086 --device-type fpga --driver vfio_pci Registered the pci-2 PCI resource ============================== View all PCI resource aliases ============================== .. tabs:: .. tab:: CLI In order to view all registered aliases for PCI devices alongside details of the physical PCI device they each represent, run the following command: .. code-block:: text # robin pci-resource list --json =============================== ================================================================================ ``--json`` Output in JSON =============================== ================================================================================ **Example** .. code-block:: text # robin pci-resource list Name | Device | Vendor | Type | Driver ------+--------+--------+------+---------- pci-1 | 0x0d90 | 0x8086 | fpga | vfio_pci .. tab:: API Returns all registered aliases for PCI devices alongside details of the physical PCI device they each represent. **End Point:** /api/v3/robin_server/pci-resources **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 .. raw:: html
===================================================== Show information about a specific PCI Resource alias ===================================================== .. tabs:: .. tab:: CLI To view details about a particular PCI resource alias and its respective PCI device, run the following command. .. code-block:: text # robin pci-resource info =============================== ================================================================================ ``name`` Name of alias to fetch details for =============================== ================================================================================ **Example** .. code-block:: text # robin pci-resource info pci-1 Name : pci-1 Device Id : 0x0d90 Vendor Id : 0x8086 Type : fpga Driver : vfio_pci .. tab:: API Returns details about a particular PCI resource alias and its respective PCI device. **End Point:** /api/v3/robin_server/pci-resources/ **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text .. raw:: html
===================== Remove PCI Resource ===================== .. tabs:: .. tab:: CLI To remove a PCI resource alias such that it can no longer be used to refer to a device, run the following command: .. code-block:: text # robin pci-resource remove =============================== ================================================================================ ``name`` Name of alias to fetch details for =============================== ================================================================================ **Example** .. code-block:: text # robin pci-resource remove pci-1 Unregistered the pci-1 PCI resource .. tab:: API Removes a PCI resource alias such that it can no longer be used to refer to a device. **End Point:** /api/v3/robin_server/pci-resources/ **Method:** DELETE **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text .. raw:: html
Advanced Compute and Networking Support ======================================= =================================================================================================== Supported Functionalities When Using Kubernetes YAML or Helm Chart for Deployment =================================================================================================== The following are the networking based functionalities that are supported: - Multiple interfaces support - OVS support - SR-IOV device allocation .. note:: Virtual Network Function deployment (including the networking components) is not currently supported via YAML/Helm Charts. ================================ Specifying Dedicated CPU Request ================================ If your Pod needs dedicated CPUs, then the Pod must be in guaranteed QoS class (requests = limits) and should ask for integer CPU requests. Also, Pods need to have CPU and memory specified in requests and limits. .. code-block:: text spec: containers: -name: nginx image: nginx resources: limits: memory: "200Mi" cpu: "2" requests: memory: "200Mi" cpu: "2 Check Pod’s QoS Class after deploying by following the example mentioned below: .. code-block:: text kubectl describe Pod Pod-l2fwd-78554948b7-zrfvj | grep -i qos QoS Class: Guaranteed =========================================== Prerequisites for Using Network Annotations =========================================== To use network annotations, you must meet the following prerequisites: - The namespace in which Helm Charts or YAML based objects are planned to be deployed in should be registered with Robin. Details on the command by which to achieve this can be found `here `_. - To ensure the allocation of Pods with IP addresses defined in the ``robin.io/networks`` annotation for a non-Robin namespace, you must register the non-Robin namespace with Robin. - All Kubernetes objects including controllers, Pods etc. that request network resources must meet one of the following conditions in order to have the appropriate network resources allocated to them by the Robin orchestrator: - Both ``app`` and ``release`` labels need to be present within the object definition. This is considered the old style of naming. - Both ``app.kubernetes.io/name`` and ``app.kubernetes.io/instance`` labels need to be present within the object definition. This is considered the new style of naming. For more information on updated naming conventions, see `Recommended Labels `_. .. note:: - Each controller including all StatefulSets, ReplicaSets, Deployments, and Daemonsets within a Kubernetes cluster must have a unique combination of ``app`` and ``release`` labels. =============================================== Assigning an interface via Network Annotations =============================================== In order to have an interface and consequently an IP Address from a registered IP-Pool assigned to a Pod, the ``robin.io/networks`` must first be utilized in the manner showcased in the example below. The value for this annotation must be a stringified list consisting of a dictionary containing the name of the IP-Pool from which the IP Address should be assigned from. .. note:: When using SRIOV IP-pools with Kubernetes Affinity or robinrpool as an annotation, you will notice the Pods going through these statuses before displaying the Running status: Pending --> Terminating --> Pending --> Running status. Due to this behavior, Pods deployment will take more time than normal. .. note:: A Pod that needs only a Calico interface does not require any annotations to be specified. .. code-block:: text robin.io/networks: '[{"ippool": "sriov99"}]' In order to have multiple interfaces assigned to a Pod, multiple IP-Pools can be specified in the aforemntioned annotation as shown below. This in turn inherently means that Robin supports allocating multiple IPv4 and/or IPv6 IP Addresses to a Pod. .. code-block:: text robin.io/networks: '[{"ippool": "ovs1"}, {"ippool": "sriov99"}]' The list of available IP-Pools from which an IP Address can be allocated from can be viewed via either the Robin CLI or native Kubernetes as detailed `here `_. In addition, several options can be specified within each interface request in order to customize the interface allocated. For more details review the section detailed `here `_. .. Note:: If Pod(s) utilizing the ``robin.io/networks`` annotation are provisioned when the Robin Server is unhealthy or unavailable, any networking resources that require additional planning by the orchestrator including static IP and MAC Addresses will not be allocated. The aforementioned Pod(s) that meet this criteria must be recreated or bounced when the Robin Server is recovered in order to guarantee the allocation of the requested network resources. ========================== Network Annotation options ========================== Described below are the options that can be utilized in order to customize the interface allocated via the ``robin.io/network`` annotation. Each of these options can be used once and in conjunction with one another within each IP-Pool requested in the aforementioned annotation. Enabling trusted mode ^^^^^^^^^^^^^^^^^^^^^^ In order to set the allocated interface into trusted mode in order to enable it to perform additional operations, specify the ``trust`` parameter as shown in the example below. By default this option is disabled. .. Note:: This is a L2 option for Virtual Functions. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "trust": "on"}]' Enabling spoof checking ^^^^^^^^^^^^^^^^^^^^^^^ In order to enable spoof checking for the allocated interface in order to improve network security, specify the ``spoofchk`` parameter as shown in the example below. By default this option is disabled. .. Note:: This is a L2 option for Virtual Functions. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "spoofchk": "on"}]' Setting the Bond mode ^^^^^^^^^^^^^^^^^^^^^^^ In order to configure the bond policy of the bonded interface via the Bond CNI, specify the ``bond_mode`` parameter as shown in the example below with the respective policy name. Currently Robin only supports the ``active-backup`` mode. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "bond_mode": "active-backup"}] Allocating an interface for a container ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to allocate an interface to a specific container when multiple are contained within the Pod to be deployed, specify the ``container`` parameter as shown in the example below with the respective name of the container to which the interface needs to be associated with. **Example:** .. code-block:: text annotations: robin.io/networks: {"ippool": "sriov99", "container": "container1"} Setting the MTU for an interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to configure the maximum transmission unit (MTU) size for an allocated Virtual Function, specify the ``mtu`` parameter as shown in the example below with the desired transmission size. .. Note:: This configuration only affects the Virtual Function assigned, the MTU for the backend switch port and Physical Function must be set manually beforehand. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "mtu": "9000"}]' Assigning an environment variable prefix ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to specify a prefix that should prepended to the environment variables related to the assigned interface within the Pod, specify the ``name`` parameter as shown in the example below with the desired text. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "name": "FRONTHAUL"}] Setting a custom interface name ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to specify a custom interface name of no more than 15 characters for easier internal identification, specify the ``interface_name`` parameter as shown in the example below with the desired name. In addition this feature allows users to meet the interface name requirements of a network function within a Pod if needed. If this parameter is not utilized, the default Robin interface naming scheme is used. .. Note:: Names such as ``eth0`` or ``lo`` should not be used as the Pod will not be created. However other common names such as ``net`` can be used if it available. Also, when providing custom network interface names, you must ensure the names are unique. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "interface_name": "sr1"}] Assigning static IP Addresses ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to specify a static IP Address that should be assigned to a Pod, utilize the ``static_ips`` parameter as shown in the example below with the list of possible static IP Addresses that can be assigned to the respective pod. .. Note:: A range of IP Addresses can also be specified instead of singular entries within the given list of allocatable IP Addresses. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "static_ips": ["192.168.96.10-15", "192.168.96.17"]}]' .. Note:: More details on the advantages and use cases for Static IP Addresses can be found `here `_. Specifying a static IP policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to specify a static IP policy that should be considered when allocating an IP Address to the a Pod, utilize the ``static_ip_policy`` parameter as shown in the example below with one of the following valid values: - ``range`` - This option should be used when the IP Address to be allocated needs to be within the range of viable static IP Addresses specified in the annotation. When no policy is specified this is the default option. - ``ippool`` - This option should be used when the IP Address to be allocated can be any available IP Address in the specified IP-Pool when the specified static IP Addresses in the annotation are in-use. .. Note:: The ``static_ip_policy`` parameter is only valid when static IP Addresses are specified within the same annotation via the ``static_ips`` parameter. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sriov99", "static_ip_policy": "ippool", "static_ips": ["192.168.96.10-15", "192.168.96.17"]}]' Assigning multiple IP Addresses to a single interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to allocate multiple IPv4 and/or IPv6 addresses to a single interface within a Pod, utilize the ``primary`` parameter as shown in the example below with the name of an OVS or SR-IOV based IP-Pool as the value alongside a ``secondary`` IP-Pool specified via the ``ippool`` parameter. **Example:** .. code-block:: text annotations: robin.io/networks: '[{"ippool": "sec-1", "primary": "sriov99"}]' .. Assigning static MAC Addresses Commented out as per Jira PP-34005) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. In order to specify a static MAC Address that should be assigned to a Pod, utilize the ``static_macs`` parameter as shown in the example below with the list of possible static MAC Addresses that can be assigned to the respective pod. .. **Example:** .. .. code-block:: text .. annotations: robin.io/networks: '[{"ippool": "sriov1", "static_macs": ["04:03:06:07:08:09", "04:04:06:07:08:09"]}]' .. Note:: More details on the advantages and use cases for Static MAC Addresses can be found `here `_. =========================================== Assigning a device via Annotations =========================================== In order to have a device assigned to a Pod and consequently allow its containers to take advantage of the accelerator functions and hardware, the ``robin.io/device`` annotation must first be utilized in the manner showcased in the example below. The value for this annotation must be a stringified list consisting of a dictionary containing the ``type``, ``devid``, ``driver`` and ``vendor`` attributes of the device to assign functions from. .. code-block:: text robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci"}]' In order to have a function from multiple devices assigned to a Pod, multiple devices can be specified in the aforemntioned annotation as shown below. .. code-block:: text robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci"}, {"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "igbuio"}]' The list of available devices from which a function can be allocated from can be viewed via the ``robin host list --devices`` command. More details on the command can be found `here `__. Alternatively if a PCI Resource alias has been created, details for which can be found `here `__, it can be used instead of specifying the each of the aforementioned device attributes as shown in the example below. .. code-block:: text robin.io/devices: '[{"name": "pci-1"}]' Similarly multiple aliases can be used in order for functions from multiple devices to be assigned to a Pod, as shown below. .. code-block:: text robin.io/devices: '[{"name": "pci-1"}, {"name": "pci-2"}]' The list of available aliases that can be used to represent a device can be viewed via the command ``robin pci-resource list`` command. More details on the command can be found `here `__. Lastly, several options can be specified within each device request in order to customize the function allocated regardless of which method is used to specify the device(s). For more details review the section detailed `here `__. ========================== Device Annotation options ========================== Described below are the options that can be utilized in order to customize the device allocated via the ``robin.io/device`` annotation. Each of these options can be used once and in conjunction with one another within each device requested in the aforementioned annotation. Requesting multiple functions from a single device ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to customize the number of accelerator functions allocated from a particular device, specify the ``count`` parameter as shown in the example below. If this option is not specified, only one function is allocated. **Example:** .. code-block:: text annotations: robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci", "count": 2}]' Allocating a function to a container ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to allocate a function to a specific container when multiple are contained within the Pod to be deployed, specify the ``container`` parameter as shown in the example below with the respective name of the container to which the function needs to be associated with. **Example:** .. code-block:: text annotations: robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci", "container": "container1"}]' Assigning an environment variable prefix ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to specify a prefix that should prepended to the environment variables related to the assigned functions within the Pod, specify the ``name`` parameter as shown in the example below with the desired text. **Example:** .. code-block:: text annotations: robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci", "name": "fec"}]' Specifying the class of a device ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the case where the manadatory parameters are not enough to distinguish the desired device, specify the ``class`` parameter as shown in the example below with the name of the class for the desired device **Example:** .. code-block:: text annotations: robin.io/devices: '[{"type": "fpga", "devid": "0x0d90", "vendor": "0x8086", "driver": "vfiopci", "class": "0x120000"}]' ============================== Getting CPU IDs Inside a Pod ============================== If you need allocating CPU IDs inside containers requesting guaranteed CPUs, you can access them in the :file:`/robinenv` file. **Example:** .. code-block:: text [root@Pod-l2fwd l2fwd]# cat /robinenv ROBIN_CPUSET=5,6,29,30 ROBIN_CPUSET_ORDERED=5:29,6:30 ROBIN_CPUSET_RANGE=5-6,29-30 ============================================= Environment Variables to use with Annotations ============================================= Robin exposes a set of environment variables prefixed with the phrase "ROBIN" within Pods deployed via YAML files. A subset of the aforementioned variables are displayed below and can be accessed via the ``env`` command from within the Pod. **Example:** .. code-block:: text [root@Pod-pktgen-5-668b9d6d5c-58822 pktgen]# env | grep ROBIN ROBIN_SRIOV5_SUBNET=fd74:ca9b:3a09:8685:0000:0000:0000:0000 ROBIN_NONROBIN_DEFAULT_IP_ADDRESS=fd74:ca9b:3a09:868c:0172:0018:0000:42af ROBIN_NONROBIN_DEFAULT_DRIVER=calico ROBIN_SRIOV5_VFIDS=9,7 ROBIN_SRIOV5_DRIVER=sriov ROBIN_NONROBIN_DEFAULT_NETMASK=ffff:ffff:ffff:ffff:ffff:ffff:ffff:c000 ROBIN_SRIOV5_IP_ADDRESS=fd74:ca9b:3a09:8685:00c0:00a8:0001:006f ROBIN_SRIOV5_PFNAMES=enp175s0f1,enp175s0f0 ROBIN_SRIOV5_PCI_ADDR=0000:af:0b.1,0000:af:02.7 ROBIN_NONROBIN_DEFAULT_SUBNET=fd74:ca9b:3a09:868c:0172:0018:0000:4000 ROBIN_SRIOV5_MTU=1500 ROBIN_SRIOV5_VFDRIVER=iavf ROBIN_MEMORY=209715200 ROBIN_SRIOV5_INTF_NAMES=eth1,eth2 ROBIN_SRIOV5_VLAN=20 ROBIN_SRIOV5_NETMASK=ffff:ffff:ffff:ffff:0000:0000:0000:0000 Network Policy Support ======================== Robin supports the Kubernetes concept of ``NetworkPolicies`` for Robin bundles and Helm applications based on the Calico network. These policies allow administrators to enforce rules that control traffic flow at the IP address or port level. More specifically they are an application-centric construct which determine how a pod is allowed to communicate with various network entities such as external network endpoints/services and other pods. For more information, view the official documentation `here `_. ============= How it works ============= By default, Pods are non-isolated, and they accept traffic from any source including other Pods present within the cluster. Pods become isolated by having a ``NetworkPolicy`` that selects them. Once there is any ``NetworkPolicy`` in a namespace selecting a particular pod, that pod will reject any connections that are not allowed by any ``NetworkPolicy``. Network policies affect only Pod-to-Pod communication and do not affect service-to-service traffic directly. Network policies use labels specified within the ``PodSelector`` attribute of their definition to select the Pods on which the associated traffic rules will be enforced. ====================== Robin network policies ====================== The following are the network policies supported by Robin: - **Allow-all:** Ingress/egress traffic is allowed to/from all application Pods in the cluster. - **Namespace application isolation:** Ingress/egress traffic is allowed to/from all application Pods within a namespace. - **Tenant application isolation:** Ingress/egress traffic is allowed to/from all application Pods within a tenant. - **User application isolation:** Ingress/egress traffic is allowed to/from all application Pods for a user. - **Application Pods isolation:** Ingress/egress traffic is allowed to/from all Pods of an application. - **Deny-all:** No ingress/egress traffic is allowed to/from all application Pods in the cluster. ======================== Cluster level attributes ======================== Robin supports two main configuration attributes, ``create_user_ns_tenant_isolation_nw_policies`` and ``network_policy_scope``, with regards to network policies and their configuration. Both attributes are at the cluster level and are described in the following sections. In addition the current status of each can be viewed via the ``robin config list`` command. Enable cluster level network policies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, Robin does not create any Kubernetes Ingress/Egress network policies when a user, namespace, or tenant is created within the cluster. In order to enable this behavior when one of the aforementioned entities is created, run the following command: .. code-block:: text # robin config cluster create_user_ns_tenant_isolation_nw_policies True The 'cluster' attribute 'create_user_ns_tenant_isolation_nw_policies' has been updated .. Note:: Robin creates the default isolation network policies for the user, namespace, or tenant created post-upgrade if the cluster level network policies are set to True. Disable cluster level network policies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To disable the creation of Kubernetes Ingress/Egress network policies when a user, namespace, or tenant is added such that no trafic is blocked or so custom network policies can be applied, run the following command: .. code-block:: text # robin config update cluster create_user_ns_tenant_isolation_nw_policies False The 'cluster' attribute 'create_user_ns_tenant_isolation_nw_policies' has been updated Configure Network Policy Scope attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Robin supports the automatic addition of network policy labels to pods which are created as part of an application deployment. The labels added are determined by the ``network_policy_scope`` attribute, which by default is set to ``allow-all``. In order to configure the ``network_policy_scope`` attribute at the cluster level, run the following command: .. code-block:: text # robin config update cluster network_policy_scope **Example** .. code-block:: text # robin config update cluster network_policy_scope namespace The 'cluster' attribute 'network_policy_scope' has been updated The following are the valid values: * allow-all * namespace * tenant * user * app * deny-all The above values all map to the respective policies detailed `here `_. ============================================ Create network policies for individual users ============================================ .. tabs:: .. tab:: CLI In order to create Kubernetes Ingress/Egress network policies for an individual Robin user or a set of users, run the following command: .. code-block:: text # robin networkpolicy create ========================= ========================================================================================= ``usernames`` Comma seperated list of Robin usernames for whom the network policies should be created. ========================= ========================================================================================= **Example** .. code-block:: text # robin networkpolicy create T2User Successfully added K8S network policies for user 'T2User' .. tab:: API Creates Kubernetes Ingress/Egress network policies for an individual Robin user or a set of users. **End Point:** /api/v3/robin_server/networkpolicies **Method:** POST **URL Parameters:** None **Data Parameters:** - ``user_info: `` -- - ``user_list: `` - This mandatory field within the dictionary specifies the names of the Robin users for which the Kubernetes network policies should be created for **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), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "message":"\nSuccessfully added K8S network policies for Robin User\/s '['robin']'\n" } .. raw:: html
==================================== Attach network policy to application ==================================== .. tabs:: .. tab:: CLI In order to associate either the default Robin network policies or any custom network policies with an application(s), issue the following command: .. code-block:: text # robin app attach-network-policy --roles ========================= ================================================================================================================================================================== ``appnames`` Comma separated list of one or more application names. ``policies`` Comma separated list of one or more Kubernetes Network Policy names to attach to specified applications. ``--roles `` Comma separated list of roles within an application to attach the specified network policies. If not specified it is attached to all roles within the application. ========================= ================================================================================================================================================================== **Example** .. code-block:: text # robin app attach-network-policy app-1-robinuser up-allow-intra-user-pods-t001-u000003-3 --wait Job: 127 Name: ApplicationAddPolicy State: VALIDATED Error: 0 Job: 127 Name: ApplicationAddPolicy State: COMPLETED Error: 0 ====================================== Detach network policy from application ====================================== .. tabs:: .. tab:: CLI In order to dissociate either default Robin network policies or any custom network policies from an application(s), issue the following command: .. code-block:: text # robin app detach-network-policy --roles ========================= ======================================================================================================================================================================= ``appnames`` Comma separated list of one or more application names. ``policies`` Comma separated list of one or more Kubernetes Network Policy names to detach from specified applications. ``--roles `` Comma separated list of roles within an application to detach the specified network policies from. If not specified it is attached to all roles within the application. ========================= ======================================================================================================================================================================= **Example** .. code-block:: text # robin app detach-network-policy app-1-robinuser up-allow-intra-user-pods-t001-u000003-3 --wait Job: 127 Name: ApplicationRemovePolicy State: VALIDATED Error: 0 Job: 127 Name: ApplicationRemovePolicy State: COMPLETED Error: 0 ================================================ View network policies attached to an application ================================================ In order to view the network policies currently associated with an application the ``robin app info`` command can be used with the ``--networkpolicies`` parameter. More details on this operation can be found `here `_. ================================ List available network policies ================================ .. tabs:: .. tab:: CLI To view all the network policies currently present in a cluster, run the following command: .. code-block:: text # network-policies [] ========================= ========================================================================================= ``namespace`` List only network policies present in the specified namespace. Note this is an optional parameter, and alternatively the ``robin namespace info`` command can be used to display network policies configured for a namespace. ========================= ========================================================================================= **Example 1 (Listing all network policies):** .. code-block:: text # network-policies NAMESPACE NAME POD-SELECTOR AGE sveta-custom np-allow-intra-ns-pods robin.io/networkpolicyns=np-allow-intra-ns-pods 105m sveta-custom np-deny-all-pods robin.io/networkpolicyns=np-deny-all-pods 105m sveta-custom tp-allow-intra-tenant-pods-1 robin.io/networkpolicytenant=tp-allow-intra-tenant-pods-1 105m sveta-custom up-allow-intra-user-pods-4 robin.io/networkpolicyuser=up-allow-intra-user-pods-4 105m t001-u000001 np-allow-intra-ns-pods robin.io/networkpolicyns=np-allow-intra-ns-pods 130m t001-u000001 np-deny-all-pods robin.io/networkpolicyns=np-deny-all-pods 130m t001-u000001 tp-allow-intra-tenant-pods-1 robin.io/networkpolicytenant=tp-allow-intra-tenant-pods-1 130m t001-u000001 up-allow-intra-user-pods-1 robin.io/networkpolicyuser=up-allow-intra-user-pods-1 130m t001-u000002 np-allow-intra-ns-pods robin.io/networkpolicyns=np-allow-intra-ns-pods 130m t001-u000002 np-deny-all-pods robin.io/networkpolicyns=np-deny-all-pods 130m **Example 2 (Filter etwork policies by namespace):** .. code-block:: text # network-policies t001-u000003 t001-u000003 np-allow-intra-ns-pods robin.io/networkpolicyns=np-allow-intra-ns-pods 132m t001-u000003 np-deny-all-pods robin.io/networkpolicyns=np-deny-all-pods 132m t001-u000003 tp-allow-intra-tenant-pods-1 robin.io/networkpolicytenant=tp-allow-intra-tenant-pods-1 132m t001-u000003 up-allow-intra-user-pods-3 robin.io/networkpolicyuser=up-allow-intra-user-pods-3 132m ============================================= Show Information About a Specific Namespace ============================================= .. tabs:: .. tab:: CLI To view detailed information regarding a network policy such as the time it was created, associated labels, annotations and spec, run the following command: .. code-block:: text # network-policy-info ========================= ========================================================================================= ``namespace`` Name of the namespace the specific network policy is associated to ``network_policy`` Name of the network policy to fetch details for ========================= ========================================================================================= **Example** .. code-block:: text # network-policy-info t001-u000003 np-allow-intra-ns-pods Name: np-allow-intra-ns-pods Namespace: t001-u000003 Created on: 2021-02-05 10:41:15 -0800 PST Labels: robin.io/domain=ROBIN robin.io/networkpolicyns=np-allow-intra-ns-pods Annotations: Spec: PodSelector: robin.io/networkpolicyns=np-allow-intra-ns-pods Allowing ingress traffic: To Port: (traffic allowed to all ports) From: NamespaceSelector: robin.io/namespace=t001-u000003 From: IPBlock: CIDR: 0.0.0.0/0 Except: 172.18.0.0/16, 172.21.0.0/16 Allowing egress traffic: To Port: (traffic allowed to all ports) To: NamespaceSelector: robin.io/namespace=t001-u000003 Policy Types: Egress, Ingress