Blogs

Hosts in Rancher

Posted on by admin

Hosts are

the

most basic resource unit within Rancher and are represented as any Linux server, virtual or physical, with the following minimum requirements:

  • x86 CPU architecture
  • Any modern Linux distribution with a supported version of Docker. RancherOS, Ubuntu, RHEL/CentOS 7 are more tested.
    • For RHEL/CentOS, Docker does not recommend the default storage driver, i.e. loopback devicemapper. See the Docker documentation on how to change it.
    • For RHEL/CentOS, if you want to enable SELinux, you will need to install an additional SELinux module.
    • For RHEL/CentOS, use kernel version 3.10.0-514.2.2.el7.x86_64 or higher. Includes when using version 7.3 or higher.

      • For the host running a local caching name server

    • (for example, Ubuntu 18.04 Bionic Beaver), see Hosts running a local caching name

    • server

  • 1GB RAM
  • CPU recommended with AES-NI
  • Ability to communicate with a Rancher server over http or https through the preconfigured port. The default value is 8080.
  • Ability to route to any other host in the same environment to take advantage of Rancher’s cross-host network for Docker containers.

Rancher also supports Docker Machine and allows you to add your host through any of its supported drivers

.

On the Infrastructure -> Hosts tab, click Add Host.

Supported

Docker versions Supported

version? Compatible with Kubernetes? Compatible with Windows? Install Script 1.9.x and earlier No 1.10.0 – 1.10.2 No 1.10.3 (and higher) No

(Yes in v1.6.5 and earlier)

No No curl https://releases.rancher.com/install-docker/1.10.sh | sh 1.11.x Without curl https://releases.rancher.com/install-docker/1.11.sh | sh 1.12.0 – 1.12.2 No 1.12.3 (and above) Yes Yes No curl https://releases.rancher.com/install-docker/1.12.sh | sh 1.13.x Yes Yes

(Kubernetes version 1.8, 1.9, 1.10, 1.11)

No ripple https://releases.rancher.com/install-docker/1.13.sh | sh 17.03.x-ce Yes Yes(

Kubernetes version 1.8, 1.9, 1.10, 1.11)

No curl https://releases.rancher.com/install-docker/17.03.sh | sh 17.03.x-ee Yes Yes(

Kubernetes version 1.8, 1.9, 1.10, 1.11)

No n/a 17.04.x-ce No No No curl https://releases.rancher.com/install-docker/17.04.sh | sh 17.05.x-ce No No No No curl https://releases.rancher.com/install-docker/17.05.sh | sh 17.06.x-ce Yes

(v1.6.3 and above)

No I curl https://releases.rancher.com/install-docker/17.06.sh | sh 17.06.x-ee Yes(v1.6.3 and above) No Yes(v1.6.13 and above) n/a 17.09.x-ce Yes

(v1.6.11 and

above)

No No Curl https://releases.rancher.com/install-docker/17.09.sh |

sh 17.09.x-ee Yes

(v1.6.11 and above)

No No n/a 17.10.x-ce No No curl https://releases.rancher.com/install-docker/17.10.sh | sh 17.11.x-ce No No n/a 17.12.x-ce Yes

(v1.6.14 and above)

No No curl https://releases.rancher.com/install-docker/17.12.sh | sh 17.12.x-ee Yes(v1.6.14 and above) No No n/a 18.01.x-ce No No n/a 18.02.x-ce No No n/a 18.03.x-ce Yes

(v1.6.17 and above)

No No curl https://releases.rancher.com/install-docker/18.03.sh |

sh 18.03.x-ee Yes(v1.6.17 and above) No No n/a 18.06.x-ce Yes(

v1.6.20 and above

) Yes

(Kubernetes version 1.12)

No curl https://releases.rancher.com/install-docker/18.06.sh |

sh 18.06.x-ee Yes (v1.6.20 and above) Yes (Kubernetes version 1.12) No n/a 18.09.x-ce Yes(

v1.6.26 and above

) Yes

(Kubernetes version 1.12

)

No curl https://releases.rancher.com/install-docker/18.09.sh |

sh 18.09.x-ee Yes (

v1.6.26 and above

) Yes

(Kubernetes version 1.12)

No n/a

Note: We will not support Docker trial/night/edge, but we will support stable versions of Docker

. Installing a specific version of Docker The standard ripple https://get.docker.com | sh always installs the latest

version of Docker

available at that time and may not be compatible with your installed Rancher version. Instead, we recommend that you use the scripts above to install a specific version. These are a slightly modified version of the standard script and anchor the installation to a specific version of the Docker engine. Exact patch versions are also available as 1.<x>.<y>.sh, for example, 1.12.6.sh.

Note: If you are booting a host from the UI, you can select which version of Docker you want to install on the host. In the Advanced section, there is a Docker installation URL.

How do hosts work?

A host

connects to the Rancher server when the Rancher agent container is started on the host. The registration token, which is the long URL on the Add Custom Host -> screen, is used by the Rancher agent to connect to the server for the first time. After connection, it generates an agent account and API key pair on the Rancher server. The key pair is then used for all subsequent communications using the same authentication and authorization logic as for other types of accounts, such as environment API keys.

The design is that the agent is untrusted because it runs on external hardware and potentially hostile (to the server). Agent accounts only have access to the resources they need in the API, event responses are checked for indicating that the event was actually sent to that agent, and so on. There is not so much in the opposite direction for the agent to verify the host, so you can also configure TLS and the certificate will be verified.

The registration token is per environment. It is generated on the server, stored in the database, and sent to the host as part of the agent registry with the API key pair. Connections are point-to-point between hosts and encrypted AES, which is accelerated by most modern CPUs.

Add

a host

The first time you add a host, you might need to configure the host registration URL. This setting determines which DNS name or IP address, and the port that your hosts will be connected to the Rancher API. By default, we have selected the IP of the management server and port 8080. If you choose to change the address, be sure to specify the port to use to connect to the Rancher API. At any time, you can update the Host Registry. After you set up your host record, click Save.

We support adding hosts directly from cloud providers or adding a host that has already been provisioned. For cloud providers, we provision using docker-machine and support any image that docker-machine supports.

Select the type of host

you want to add:

Adding custom hosts Adding

  • Amazon EC2

    • hosts Add Azure hosts Add

  • DigitalOcean

    • hosts Add Exoscale hosts Add package hosts Add

  • Rackspace

  • hosts

  • Add hosts

    • from

  • other cloud providers

When adding a host

a Rancher, a rancher agent container is started on the host. Rancher will automatically extract the correct image version tag for the rancher/agent and run the required version. The agent version is labeled specifically for each version of the Rancher server.

Host

tags

With each host, you have the ability to add tags to help you organize your hosts. Tags are added as an environment variable when you start the farmer/agent container. The host label in the UI will be a key/value pair and the keys must be unique identifiers. If you added two keys with different values, we will take the last value entered to use as a key/value pair.

When adding tags to hosts, you can use these tags when scheduling services/load balancers and creating a whitelist or blacklist of hosts for your services to run.

If you plan to use an external DNS service and need to schedule DNS records using an IP other than the host IP, you must include the io.rancher.host.external_dns_ip=<IP_TO_BE_USED_FOR_EXTERNAL_DNS> tag on the host. The host tag can be added when registering the host or after the host has been added to Rancher, but it must be added to the host before the external DNS service starts. The value of this tag will be used when programming rules for external DNS services.

When you use the UI to add hosts with the

different cloud providers, the rancher/agent command starts

automatically with the host tags that are added in the UI. When you add

a custom host, you can add the tags using the UI and it will automatically add the environment variable (CATTLE_HOST_LABELS) with the key/value pair in the command on the interface screen of the user.

Example Note

: The rancher/agent version is mapped to the Rancher server version. You will need to check the custom command to get the appropriate label for the version to be used.

Automatically

applied host tags

Rancher automatically creates host tags related to the Linux kernel version and the host Docker engine version.

Description of the io.rancher.host.linux_kernel_version key value Linux kernel version on the host (for example, 3.19) Version of the Linux kernel running on the host io.rancher.host.docker_version Docker version on the host (for example, 1.10) Docker engine version on the host io.rancher.host.provider Cloud provider information Cloud provider name (currently only applies to AWS) io.rancher.host.region Cloud provider region Provider Region cloud (currently only applies to AWS) io.rancher.host.zone Cloud provider zone Cloud provider zone (currently only applies to AWS)

Developer

IP

To enable the ability to publish ports to multiple IPs, the host must be configured so that Rancher knows which IPs they are available for scheduling. The method for adding scheduler IP for a host depends on whether the host is already in Rancher (that is, the Rancher agent has already been launched) versus a new host (that is, the Rancher agent has not yet been launched).

Add

scheduler

IP addresses to existing hosts

For any existing host in an environment, additional IP addresses can be added for scheduling by adding a specific host tag (io.rancher.scheduler.ips to the host. In the user interface, click Edit Host for the host and add a developer IP. If you want to update the host details through the API, you must add the host tag io.rancher.scheduler.ips and list the IPs as the value in a comma-separated list (that is, 1.2.3.4, 2.3.4.5).

Note: If ports are published for services on a host before scheduler IPs are added, those ports are published to 0.0.0.0, which means that they are consumed on all IPs, including scheduler IPs added after the service has started.

Add

Scheduler

IP for a New

Host For any custom host that has not been added to Rancher, an environment variable (that is, CATTLE_SCHEDULER_IPS) can be added to the Rancher agent command to list the available IPs on the host.

Hosts behind an HTTP proxy If you are

behind an HTTP

proxy, to

add hosts to the Rancher server, you must edit the host’s Docker daemon to point to the proxy. Detailed instructions are listed on our custom host addition page.

Hosts running

a local caching name server

Some Linux distributions run a local caching name server by default. This means that the name server configured in /etc/resolv.conf points to the address in the loopback range (127.0.0.0/8). While this will work well on the host itself, containers cannot reach this address (unless running with the host in network mode). Our infrastructure services must be able to resolve DNS for it to work, so a change to the system is required before adding the host to a Rancher environment. This involves two steps:

Disable the

  • local caching

    • name server.

  • Modify the contents of /etc/resolv.conf to point to correct name servers.

For Ubuntu 18.04, you can run the following commands to modify

the system: If /run/systemd/resolve/resolv.conf is

not present on the system, you can create your own /etc/resolv.conf as shown below:

Accessing hosts from cloud providers

If you choose to select to launch a host through Rancher, Rancher is making a call to Docker Machine to access the cloud provider. We provide all the certificates generated when starting the machine in an easy to download file. Click Machine Configuration from the host drop-down menu. It will download a tar.gz file that has all the certificates.

For SSH on your host, go to your terminal/command prompt. Navigate to the folder of all certificates and ssh in using the certificate id_rsa.

Cloning a

host Since

launching hosts on cloud providers requires the use of an access key, you may want to easily create another host without needing to re-enter all credentials. Rancher provides the ability to clone these credentials to create a new host. Select Clone from the host drop-down menu. An Add Host page appears with the cloned host’s credentials populated.

Editing hosts

The options for what you can do with a host are located in the host’s drop-down menu. From the Infrastructure -> Hosts page, the drop-down icon will appear when you hover over the host. If you click the host name to view more details for a host, the drop-down icon is located in the upper-right corner of the page. It is located next to the host status.

If you select Edit, you can update the host name, description, or tags.

Deactivating/activating hosts Deactivating

the host will put the host in an Inactive state. In this state, no new containers can be deployed. All active containers on the host will remain active and you will still have the ability to perform actions on these containers (start/stop/restart). The host will remain connected to the Rancher server. Select Deactivate from the host drop-down menu.

When a host is in

an Inactive state, you can return the host to an Active state by clicking Activate in the host’s drop-down menu

. Note: If a host is down in Rancher

(that is, in a reconnecting or downcast state), you will need to implement a health check for Rancher to start your service’s containers on a different host.

Deleting hosts

To remove a host from the server, you’ll need to perform a couple of steps from the drop-down menu

.

Select Disable. When the host has completed deactivation, the host will display an Inactive status. Select Delete. The server will initiate the process of removing the host from the Rancher server instance. The first status that will be displayed after you have finished deleting it will be Deleted. It will continue to finish the removal process and will go into a Purge state before immediately disappearing from the user interface.

If the host was

created at a cloud provider using Rancher, the host will be removed from the cloud provider. If the host was added using the custom command, the host will remain with the cloud provider.

Notes: For custom hosts, all containers, including the Rancher agent, will continue to remain on the host. In addition, the IP set on the docker0 interface by the Rancher network controller will remain.

Deleting hosts

outside of Rancher If your host is deleted outside of Rancher, the

Rancher server will continue to display the host until it is deleted. After retrying the connection (Reconnecting), the host will appear in a Disconnected state. You can delete the host to remove it from the user interface. You can also set a delay in seconds, after which the host will be automatically deleted. This setting is called host.remove.delay.seconds and can be found in Admin -> Settings -> Advanced Settings.

admin