Rancher is deployed as a set of Docker containers. Running Rancher is as simple as launching two containers. One container as the management server and another container on a node as an agent.
Note: You can get all help options for the Rancher server container by running
docker run rancher/server --help.
Note: Currently, Docker for Mac is not supported in Rancher.
ntpd)COMPACTROW_FORMAT is Dynamicmax_allowed_packet >= 32M (default is usually 16M)innodb_log_file_size >= 256M (If you have an existing DB, please make sure to appropriate plan how to change this setting.)innodb_file_per_table=1innodb_buffer_pool_size >= 1GB (For larger installs, 4-8G pools on dedicated MySQL servers)Note: Currently, MariaDB 10.3 and MySQL 8.x are not supported.
Rancher server has 2 different tags. For each major release tag, we will provide documentation for the specific version.
rancher/server:latest tag will be our latest development builds. These builds will have been validated through our CI automation framework. These releases are not meant for deployment in production.rancher/server:stable tag will be our latest stable release builds. This tag is the version that we recommend for production.Please do not use any release with a rc{n} suffix. These rc builds are meant for the Rancher team to test out builds.
On the Linux machine with Docker installed, the command to start a single instance of Rancher is simple.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 rancher/server
The UI and API will be available on the exposed port 8080. After the docker image is downloaded, it will take a minute or two before Rancher has successfully started and is available to view.
Navigate to the following URL: http://<SERVER_IP>:8080. The <SERVER_IP> is the public IP address of the host that is running Rancher server.
Once the UI is up and running, you can start by adding hosts or select a container orchestration from the Infrastructure catalog. By default, if a different container orchestration type is not selected, the environment will be using cattle. After the hosts are added into Rancher, you can start adding services or launch templates from the Rancher catalog.
Instead of using the internal database that comes with Rancher server, you can start Rancher server pointing to an external database. The command would be the same, but appending in additional arguments to direct how to connect to your external database.
Note: Your database, name and user of the database will already need to be created, but no schemas will need to be created. Rancher will automatically create all the schemas related to Rancher.
Here is an example of a SQL command to create a database and users.
> CREATE DATABASE IF NOT EXISTS cattle COLLATE = 'utf8_general_ci' CHARACTER SET = 'utf8';
> GRANT ALL ON cattle.* TO 'cattle'@'%' IDENTIFIED BY 'cattle';
> GRANT ALL ON cattle.* TO 'cattle'@'localhost' IDENTIFIED BY 'cattle';
To start Rancher connecting to an external database, you pass in additional arguments as part of the command for the container.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 rancher/server \
--db-host myhost.example.com --db-port 3306 --db-user username --db-pass password --db-name cattle
Note: When you connect to an external database cluster which requires a primary key on the tables, you can add
--db-strict-enforcingas a parameter to the command. Available as of v1.6.11
Most of the options to pass in also have default values and are not required. Only the location of the MySQL server is required.
--db-host IP or hostname of MySQL server
--db-port port of MySQL server (default: 3306)
--db-user username for MySQL login (default: cattle)
--db-pass password for MySQL login (default: cattle)
--db-name MySQL database name to use (default: cattle)
--db-strict-enforcing Ensures table has primary key (default: false), available as of v1.6.11
Note: In previous versions of Rancher server, we had connected to an external database using environment variables, those environment variables will continue to work, but Rancher recommends using the arguments instead.
Note: When using a proxy between the database server and the
rancher/servercontainer, make sure you configure the timeout parameters correctly. Please see the FAQ for more information.
If you would like to persist the database inside your container to a volume on your host, launch Rancher server by bind mounting the MySQL volume.
$ sudo docker run -d -v <host_vol>:/var/lib/mysql --restart=unless-stopped -p 8080:8080 rancher/server
With this command, the database will persist on the host. If you have an existing Rancher container and would like to bind mount the MySQL volume, the instructions are located in our upgrading documentation.
Running Rancher server in High Availability (HA) is as easy as running Rancher server using an external database, exposing an additional port, and adding in an additional argument to the command for the external load balancer. Setting up HA requires a minimum of 3 nodes.
9345, 8080Note: Currently, Docker for Mac is not supported in Rancher.
COMPACTROW_FORMAT is DynamicNote: Currently, MariaDB 10.3 and MySQL 8.x are not supported.
8080On each of your nodes that you want to add into the HA setup, run the following command:
# Launch on each node in your HA cluster
$ docker run -d --restart=unless-stopped -p 8080:8080 -p 9345:9345 rancher/server \
--db-host myhost.example.com --db-port 3306 --db-user username --db-pass password --db-name cattle \
--advertise-address <IP_of_the_Node>
For each node, the <IP_of_the_Node> will be unique to each node, as it will be the IP of each specific node that is being added into the HA setup.
If you change -p 8080:8080 to expose the HTTP port to a different port on the host, you will need to add --advertise-http-port <host_port> to the command.
Note: You can get the help for the commands by running
docker run rancher/server --help
Configure an external load balancer that will balance traffic on ports 80 and 443 across a pool of nodes that will be running Rancher server and target the nodes on port 8080. Your load balancer must support websockets and forwarded-for headers, in order for Rancher to function properly. See SSL settings page for example configuration settings.
| Option | Example | Description |
|---|---|---|
| IP address | --advertise-address 192.168.100.100 |
Uses the give IP address |
| Interface | --advertise-address eth0 |
Retrieves the IP of the given interface |
| awslocal | --advertise-address awslocal |
Retrieves the IP from http://169.254.169.254/latest/meta-data/local-ipv4 |
| ipify | --advertise-address ipify |
Retrieves the IP from https://api.ipify.org |
If the IP of your Rancher server node changes, your node will no longer be part of the Rancher HA cluster. You must stop the old Rancher server container using the incorrect IP for --advertise-address and start a new Rancher server with the correct IP for --advertise-address.
We recommend using an ELB in AWS in front of your Rancher servers. In order for ELB to work correctly with Rancher’s websockets, you will need to enable proxy protocol mode and ensure HTTP support is disabled. By default, ELB is enabled in HTTP/HTTPS mode, which does not support websockets. Special attention must be paid to listener configuration.
If you have issues with ELB setup, we recommend trying the terraform version as this reduces the opportunity to miss a setting.
Note: If you are using a self signed certificate, please read more about how to configure your ELB in AWS under our SSL section.
For simple, unencrypted load balancing purposes, the following listener configuration is required:
| Configuration Type | Load Balancer Protocol | Load Balancer Port | Instance Protocol | Instance Port |
|---|---|---|---|---|
| Plaintext | TCP | 80 | TCP | 8080 (or the port used with --advertise-http-port when launching Rancher server) |
In order for websockets to function properly, the ELB proxy protocol policy must be applied.
$ aws elb create-load-balancer-policy --load-balancer-name <LB_NAME> --policy-name <POLICY_NAME> --policy-type-name ProxyProtocolPolicyType --policy-attributes AttributeName=ProxyProtocol,AttributeValue=true
$ aws elb set-load-balancer-policies-for-backend-server --load-balancer-name <LB_NAME> --instance-port 443 --policy-names <POLICY_NAME>
$ aws elb set-load-balancer-policies-for-backend-server --load-balancer-name <LB_NAME> --instance-port 8080 --policy-names <POLICY_NAME>
/ping as your path.The following can be used as an example for configuring with Terraform:
resource "aws_elb" "lb" {
name = "<LB_NAME>"
availability_zones = ["us-west-2a","us-west-2b","us-west-2c"]
security_groups = ["<SG_ID>"]
listener {
instance_port = 8080
instance_protocol = "tcp"
lb_port = 443
lb_protocol = "ssl"
ssl_certificate_id = "<IAM_PATH_TO_CERT>"
}
}
resource "aws_proxy_protocol_policy" "websockets" {
load_balancer = "${aws_elb.lb.name}"
instance_ports = ["8080"]
}
We no longer recommend Application Load Balancer (ALB) in AWS over using the Elastic/Classic Load Balancer (ELB). If you still choose to use an ALB, you will need to direct the traffic to the HTTP port on the nodes, which is 8080 by default.
In order to enable Active Directory or OpenLDAP for Rancher server with TLS, the Rancher server container will need to be started with the LDAP certificate, provided by your LDAP setup. On the Linux machine that you want to launch Rancher server on, save the certificate.
Start Rancher by bind mounting the volume that has the certificate. The certificate must be called ca.crt inside the container.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 \
-v /some/dir/cert.crt:/var/lib/rancher/etc/ssl/ca.crt rancher/server
You can check that the ca.crt was passed to Rancher server container successfully by checking the logs of the rancher server container.
$ docker logs <SERVER_CONTAINER_ID>
In the beginning of the logs, there will be confirmation that the certificate was added correctly.
Adding ca.crt to Certs.
Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....done.
Certificate was added to keystore
In order to set up an HTTP proxy, the Docker daemon will need to be modified to point to the proxy. Before starting Rancher server, edit the /etc/default/docker file to point to your proxy and restart Docker.
$ sudo vi /etc/default/docker
In 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 you are running Docker with systemd, please follow Docker’s instructions on how to configure the HTTP proxy.
In order for the Rancher catalog to load, the proxy will need to be configured and Rancher server will need to be launched with environment variables to pass in the proxy information.
$ sudo docker run -d \
-e http_proxy=<proxyURL> \
-e https_proxy=<proxyURL> \
-e no_proxy="localhost,127.0.0.1" \
-e NO_PROXY="localhost,127.0.0.1" \
--restart=unless-stopped -p 8080:8080 rancher/server
If the Rancher catalog will not be used, run the Rancher server command as you normally would.
When adding hosts to Rancher, there is no additional requirements behind an HTTP proxy.
Note: Currently, supported in Rancher 1.6.3+
If you are using a LDAP/AD authentication backend with Rancher whose certificate is signed by a different CA then that of the MySQL server, then this guide will not work for you!
rancher/server container you will have to mount that certificate to /var/lib/rancher/etc/ssl/ca.crt.jdbc:mysql://<DB_HOST>:<DB_PORT>/<DB_NAME>?useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&prepStmtCacheSize=517&cachePrepStmts=true&prepStmtCacheSqlLimit=4096&socketTimeout=60000&connectTimeout=60000&sslServerCert=/var/lib/rancher/etc/ssl/ca.crt&useSSL=true
CATTLE_DB_CATTLE_MYSQL_URL and CATTLE_DB_LIQUIBASE_MYSQL_URL environment variablesCATTLE_DB_CATTLE_GO_PARAMS="tls=true" to the container. If the subject field of the server’s certificate does not match the server’s hostname, you will need to use CATTLE_DB_CATTLE_GO_PARAMS="tls=skip-verify" instead.
export DB_HOST="1.2.3.4"
export DB_PORT=3306
export DB_NAME="rancherdb"
export DB_USER="root"
export DB_PASS="123456"
export JDBC_URL="jdbc:mysql://$DB_HOST:$DB_PORT/$DB_NAME?useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&prepStmtCacheSize=517&cachePrepStmts=true&prepStmtCacheSqlLimit=4096&socketTimeout=60000&connectTimeout=60000&sslServerCert=/var/lib/rancher/etc/ssl/ca.crt&useSSL=true"
cat <<EOF > docker-compose.yml
version: '2'
services:
rancher-server:
image: rancher/server:stable
restart: unless-stopped
command: --db-host $DB_HOST --db-port $DB_PORT --db-name $DB_NAME --db-user $DB_USER --db-pass $DB_PASS
environment:
CATTLE_DB_LIQUIBASE_MYSQL_URL: $JDBC_URL
CATTLE_DB_CATTLE_MYSQL_URL: $JDBC_URL
CATTLE_DB_CATTLE_GO_PARAMS: "tls=true"
volumes:
- /path/to/mysql/ca.crt:/var/lib/rancher/etc/ssl/ca.crt
ports:
- "8080:8080"
EOF
docker-compose up -d
Important: You have to specify your database parameters both in the JDBC URL as well as in the --db-xxx command arguments!