If you already have Linux machines deployed and just want to add them into Rancher, click the Custom icon. In the UI, you will be provided a docker command to run on any host. The docker
command launches the rancher/agent
container on the host.
If you are using different environments, the command provided through the UI will be unique to whatever environment that you are in.
Ensure that you are in the environment that you want to add hosts to. The environment is displayed in the upper left corner. When you first log in to the Rancher instance, you are in the Default environment.
Once your hosts are added to Rancher, they are available for adding services.
Note: Ensure that the time stamp of your host on your server and hosts are the same and you have the access to the containers on the host. For more information, see Rancher accesses the shell/logs of a container.
With each host, you have the ability to add labels to help you organize your hosts. The labels are added as an environment variable when launching the rancher/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’ll take the last inputted value to use as the key/value pair.
By adding labels to hosts, you can use these labels when schedule services/load balancers and create a whitelist or blacklist of hosts for your services to run on.
When adding a custom host, you can add the labels using the UI and it will automatically add the environment variable (CATTLE_HOST_LABELS
) with the key/value pair into the command on the UI screen.
Example
# Adding one host label to the rancher/agent command
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar' -d --privileged \
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \
http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
# Adding more than one host label requires joining the additional host labels with an `&`
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar&hello=world' -d --privileged \
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \
http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
For any hosts that are added, ensure that any security groups or firewalls allow traffic. If these are not enabled, the Rancher functionality will be limited.
500
and 4500
4789
kubectl
: 10250
and 10255
. To access any exposed services, the ports used for the NodePort will also need to be opened. The default ports used by NodePort are TCP ports 30000
- 32767
.If you are adding an agent host on the same machine as Rancher server, you must edit the command provided from the UI. In the UI, you can specify the IP that you want the Rancher agent container to use to comminicate to your Rancher server. It will automatically add in an environment variable to the command.
$ sudo docker run -d -e CATTLE_AGENT_IP=<IP_OF_RANCHER_SERVER> -v /var/run/docker....
If you have added a host onto the same host as Rancher server, note that you will not be able to create any containers on the host that binds to port 8080
. Since the UI of the Rancher server relies on the 8080
port, there will be a port conflict and Rancher will stop working. If you require using port 8080
for your containers, you could launch Rancher server using a different port.
In order to add hosts behind an HTTP proxy, the docker daemon will need to be configured to point to the proxy. Before you run the custom command to add the Rancher agent, edit the /etc/default/docker
file to point to your proxy and restart docker.
$ sudo vi /etc/default/docker
Within the file, edit the #export http_proxy="http://127.0.0.1:3128/"
to have it point to your proxy. Save your changes and then restart docker. Restarting docker is different on every OS.
Note: If running docker with systemd, follow docker instructions on how to configure the HTTP proxy.
In order for the Rancher agent to run behind the proxy, no specific environment variables related to the proxy need to be added to the command. You only need to ensure that your docker daemon is configured correctly.
If you want the proxy to be inside the Rancher agent container, you will need to edit the custom command to add the environment variables.
By default, the IP of a VM with a private IP and public IP will be set to match the IP specified in the registration URL. For example, if a private IP is used in the registration URL, then the host’s private IP will be used. If you wanted to change the host’s IP address, you’ll need to edit the command provided from the UI. In order for the Rancher agent container to be launched correctly, set the CATTLE_AGENT_IP
environment variable to the desired IP address. All the hosts within Rancher will need to be on the same network as Rancher server.
$ sudo docker run -d -e CATTLE_AGENT_IP=<PRIVATE_IP> -v /var/run/docker....
If you need to correct the IP of your host after the agent has connected, re-run the custom command.
Note: When setting the private IP address, any existing containers in Rancher will not be part of the same managed network.