In order to run Rancher server from an https
URL, you will need to terminate SSL with a proxy that is capable of setting headers. We’ve provided an example of how it could be set up with NGINX, HAProxy, or Apache, but other tools could be used.
Besides the typical Rancher server requirements, you will also need:
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.
In our example configuration, all traffic will pass through the proxy and be sent over a Docker link to the Rancher server container. There are alternative approaches that could be followed, but this example is simple and translates well.
Start Rancher server. We have added in --name=rancher-server
to this command in order to link the proxy container to the Rancher server container.
$ sudo docker run -d --restart=unless-stopped --name=rancher-server rancher/server
Note: In our example, we have assumed the proxy will be running in another container. If you are planning to run a proxy from the host, you will need to expose port
8080
locally by adding-p 127.0.0.1:8080:8080
to thedocker run
command.
If you are converting an existing Rancher instance, the upgrade to the new Rancher instance will depend on how you launched your original Rancher instance.
--volumes-from=<data_container>
when launching your new Rancher server instance.Here is the minimum NGINX configuration that will need to be configured. You should customize your configuration to meet your needs. Ensure that you use nginx version >= 1.9.5.
rancher-server
is the name of your rancher server container. When starting your rancher server container, the command must include --name=rancher-server
. When starting your nginx container, the command must include --link=rancher-server
for this exact configuration to work.<server>
can be any arbitrary name, but the same name should be used for both the http and https servers.upstream rancher {
server rancher-server:8080;
}
map $http_upgrade $connection_upgrade {
default Upgrade;
'' close;
}
server {
listen 443 ssl spdy;
server_name <server>;
ssl_certificate <cert_file>;
ssl_certificate_key <key_file>;
location / {
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://rancher;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
proxy_read_timeout 900s;
}
}
server {
listen 80;
server_name <server>;
return 301 https://$server_name$request_uri;
}
Here is an Apache configuration.
<server_name>
is the name of your rancher server container. When starting your Apache container, the command must include --link=<server_name>
for this exact configuration to work.rancher
for your configuration.proxy_wstunnel
is enabled (websocket support).<VirtualHost *:80>
ServerName <server_name>
Redirect / https://<server_name>/
</VirtualHost>
<VirtualHost *:443>
ServerName <server_name>
SSLEngine on
SSLCertificateFile </path/to/ssl/cert_file>
SSLCertificateKeyFile </path/to/ssl/key_file>
ProxyRequests Off
ProxyPreserveHost On
RewriteEngine On
RewriteCond %{HTTP:Connection} Upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /(.*) ws://rancher:8080/$1 [P,L]
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
<Location />
ProxyPass "http://rancher:8080/"
ProxyPassReverse "http://rancher:8080/"
</Location>
</VirtualHost>
Here is the minimum HAProxy configuration that will need to be configured. You should customize your configuration to meet your needs.
<rancher_server_X_IP>
is the IP address for your rancher servers.global
maxconn 4096
ssl-server-verify none
defaults
mode http
balance roundrobin
option redispatch
option forwardfor
timeout connect 5s
timeout queue 5s
timeout client 36000s
timeout server 36000s
frontend http-in
mode http
bind *:443 ssl crt /etc/haproxy/certificate.pem
default_backend rancher_servers
# Add headers for SSL offloading
http-request set-header X-Forwarded-Proto https if { ssl_fc }
http-request set-header X-Forwarded-Ssl on if { ssl_fc }
acl is_websocket hdr(Upgrade) -i WebSocket
acl is_websocket hdr_beg(Host) -i ws
use_backend rancher_servers if is_websocket
backend rancher_servers
server websrv1 <rancher_server_1_IP>:8080 weight 1 maxconn 1024
server websrv2 <rancher_server_2_IP>:8080 weight 1 maxconn 1024
server websrv3 <rancher_server_3_IP>:8080 weight 1 maxconn 1024
The following iRule configuration can be applied to make Rancher Server accessible behind a F5 BIG-IP appliance.
when HTTP_REQUEST {
HTTP::header insert "X-Forwarded-Proto" "https";
HTTP::header insert "X-Forwarded-Port" "443";
HTTP::header insert "X-Forwarded-For" [IP::client_addr];
}
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.
For SSL termination at the ELB, the listener configuration should look like this:
Configuration Type | Load Balancer Protocol | Load Balancer Port | Instance Protocol | Instance Port |
---|---|---|---|---|
SSL-Terminated | SSL (Secure TCP) | 443 | 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.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.
Note: If you use an ALB with Kubernetes,
kubectl exec
will not work and for that functionality, you will need to use an ELB.
After Rancher is launched with these settings, the UI will be up and running at https://<your domain>/
.
Before adding hosts, you’ll need to properly configure Host Registration for SSL.
This configuration will work for the ‘core’ services in Rancher running in a standalone mode (Non-HA setup). Currently, none of the certified Rancher templates from the Rancher catalog are supported.
Rancher Compose CLI will require the CA certificate as part of the default store for the operating system. See Golang root_*.
Launch the Rancher server container with the modified Docker command. The certificate must be located and called /var/lib/rancher/etc/ssl/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
Note: If you are running NGINX or Apache in a container, you can directly link the instance and not publish the Rancher UI 8080 port.
The command will configure the server’s ca-certificate bundle so that the Rancher services for machine provisioning, catalog and compose executor can communicate with the Rancher server.
If you are using a container with NGINX or Apache to terminate SSL, launch the container and include the `–link=
Access Rancher over the https
address, i.e. https://rancher.server.domain
.
Update the Host Registration for SSL.
Note: Unless the machine running your web browser trusts the CA certificate used to sign the Rancher server certificate, the browser will give an untrusted site warning whenever you visit the web page.
On the host that you want to add into Rancher, save the CA certificate, which must be in pem format, into the directory /var/lib/rancher/etc/ssl
with the file name ca.crt
.
Add the custom host, which is just copying and pasting the command from the UI. The command will already include -v /var/lib/rancher:/var/lib/rancher
, so the file will automatically be copied onto your host.