Adding Your First Rancher Worker Host

The Rancher platform is split into two parts– the management server, and worker hosts. The management server hosts the UI for starting, stopping, and editing services, where the worker hosts actually run the Docker containers that compose the services.

For a production setup using cloud providers such as Digital Ocean or Amazon Web Services EC2, it’s easy to just use the UI to add hosts. You can do this through the administration panel by clicking “Infrastructure” in the menu bar at the top of the page, and then clicking “Hosts” in the submenu. From here, you can add a new host with the “Add Host” button.

Digital Ocean

Configuring a new host on Digital Ocean is quite easy. Before you can actually add the host, you should retrieve an API key from your APIĀ settings in Digital Ocean. Ensure you grant both read and write access to this new key.

Don’t have a Digital Ocean account? Get started with $10 in free credit— enough to run two 512 MB servers for a month!

Once you have this API key, you can enter it in the form and fill out the remaining information.

Add a Digital Ocean Host to Rancher

Also, make sure you enter a name for your server or Rancher will assign a name for you (the names Rancher assigns to servers do not look very pretty and are hard to distinguish from one another). I also recommend choosing an instance size of 1 GB or greater, along with enabling backups if applicable.

You may also want to consider distributing your hosts across different data center. Because Rancher’s inbuilt networking works across hosts and data centers, you can have one machine in NY 1, one in NY 2, and one in NY 3 to enable high availability for your infrastructure. That way, if a data center (or two, depending on how many redundant services you run) go down for whatever reason, your service will still be available.

You can also set labels for your host, which allow you to schedule different services to these hosts. For example, you may want to label one of your machines as “lb = true”. This would then allow you to launch a load balancer service on hosts labeled as “lb = true”. Or, you could consider labeling your machines with their drive type (e.g. “storage = ssd”) or, with physical servers, their rack name/number. All of these properties are optionally taken into account when scheduling your services to place them on the physical hosts desired.

Once you click “Create”, Rancher launches and adds the node to your cluster automatically. Just give it a few minutes to show up under the “Hosts” page, and then you can start some services.

Amazon Web Services EC2

From the Rancher UI, you can also add new hosts on Amazon EC2. To do so, you will need an IAM key pair that allows Rancher full access to EC2. You can generate this key pair from the IAM console on AWS. From the IAM console, navigate to the “Users” page and click the blue “Add New Users” button.

AWS IAM - Add New Users

Enter a username (or user names, if you wish to create more than one user), and enable the “Generate an access key for each user” check box. This will give you an AWS access key and AWS access secret that you will pass to Rancher.

An AWS access key pair is a set of tokens that act like a secondary username and password. These keys only provide the ability to perform certain actions that you define, so if they happened to be compromised the damage would be more limited than if an intruder leaks your username and password. You can create, revoke, and delete these key pairs at any time through the IAM console

After you’ve copied the access key and secret, you will need to apply a policy to the user. An IAM policy will allow for the access key pair to perform the actions defined in the policy. To do so, find the user you just created and click on it. Once you’re on the user’s information page, you can click “Attach Policy” under “Managed Policies”.

AWS IAM Attach Policy to User

Simply find the policy titled “AmazonEC2FullAccess”, check the box, and apply the policy. Now, you can go back to Rancher and enter your access key and secret you saved earlier into the Rancher UI.

Add an EC2 Host to Rancher

From this point, you simply need to fill out the required information– such as the name of the host and the instance size– to create the host. Any AWS instance size should work for Rancher, since the minimum amount of RAM included in a current generation AWS server is 1 GB.

Using Your Management Server as a Worker

So far, you have at least two servers running– one management server, which holds the UI for Rancher, and one or more worker hosts. However, for small clusters, the idle server manager host can be put to use as a worker host as well.

To do so, simply add a new host from the management panel as previously described, except choose “Custom” as the provider.

You’ll be provided with a set of instructions to add a Docker host to your Rancher cluster. These directions can also be used to add bare metal servers, non-cloud virtual servers, or cloud servers on providers not supported by the Rancher UI.

However, adding the management server as a Rancher worker is a special case and the instructions need to be modified– the command needs to have an environmental variable set to set the CATTLE_AGENT_IP to the current management server IP.

For example, consider if Rancher provided you with the following command:

You would need to modify this command to look like the following:

Notice the addition of the flagĀ  -e CATTLE_AGENT_IP=123.123.5.5. If you’re not familiar with Docker commands, this simply passes an environmental variable to the Docker container. Ensure you change the IP address in this environmental variable to the IP address of your management server.

Once you SSH into your management server and run the command, give Rancher a few minutes to discover the new agent. You should now see the Rancher management server in the dashboard as a host available to run Docker services.

Lesson tags: Infrastructure
Back to: Getting Started with Rancher, a self-hosted Docker PaaS > Installing and Configuring Rancher