Common Options

Option Default Value Description
hostname " " string - the Fully Qualified Domain Name for your Rancher Server
ingress.tls.source "rancher" string - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret"
letsEncrypt.email " " string - Your email address
letsEncrypt.environment "production" string - Valid options: "staging, production"
privateCA false bool - Set to true if your cert is signed by a private CA


Advanced Options

Option Default Value Description
additionalTrustedCAs false bool - See Additional Trusted CAs
addLocal "auto" string - Have Rancher detect and import the "local" Rancher server cluster Import "local Cluster
auditLog.destination "sidecar" string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
auditLog.hostPath "/var/log/rancher/audit" string - log file destination on host
auditLog.level 0 int - set the API Audit Log level. 0 is off. [0-3]
auditLog.maxAge 1 int - maximum number of days to retain old audit log files
auditLog.maxBackups 1 int - maximum number of audit log files to retain
auditLog.maxSize 100 int - maximum size in megabytes of the audit log file before it gets rotated
debug false bool - set debug flag on rancher server
imagePullSecrets [] list - list of names of Secret resource containing private registry credentials
ingress.extraAnnotations {} map - additional annotations to customize the ingress
proxy "" string - HTTP[S] proxy server for Rancher
noProxy "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16" string - comma separated list of hostnames or ip address not to use the proxy
resources {} map - rancher pod resource requests & limits
rancherImage "rancher/rancher" string - rancher image source
rancherImageTag same as chart version string - rancher/rancher image tag
tls "ingress" string - See External TLS Termination for details. - "ingress, external"


API Audit Log

Enabling the API Audit Log.

You can collect this log as you would any container log. Enable the Logging service under Rancher Tools for the System Project on the Rancher server cluster.

--set auditLog.level=1

By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (rancher-audit-log) will stream the log to stdout. You can collect this log as you would any container log. Enable the Logging service under Rancher Tools for the Rancher server cluster or System Project.

Set the auditLog.destination to hostPath to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to hostPath you may want to adjust the other auditLog parameters for log rotation.

Import local Cluster

By default Rancher server will detect and import the local cluster it's running on. User with access to the local cluster will essentially have "root" access to all the clusters managed by Rancher server.

If this is a concern in your environment you can set this option to "false" on your initial install.

Note: This option is only effective on the initial Rancher install. See Issue 16522 for more information.

--set addLocal="false"

Customizing your Ingress

To customize or use a different ingress with Rancher server you can set your own Ingress annotations.

Example on setting a custom certificate issuer:

 --set ingress.extraAnnotations.'certmanager\.k8s\.io/cluster-issuer'=ca-key-pair

HTTP Proxy

Rancher requires internet access for some functionality (helm charts). Use proxy to set your proxy server.

Add your IP exceptions to the noProxy list. Make sure you add the Service cluster IP range (default: 10.43.0.1/16) and any worker cluster controlplane nodes. Rancher supports CIDR notation ranges in this list.

--set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
--set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16"

Additional Trusted CAs

If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.

--set additionalTrustedCAs=true

Once the Rancher deployment is created, copy your CA certs in pem format into a file named ca-additional.pem and use kubectl to create the tls-ca-additional secret in the cattle-system namespace.

kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem

Private Registry and Air Gap Installs

For details on installing Rancher with a private registry, see:

External TLS Termination

We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the --set tls=external option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.

Note: If you are using a Private CA signed certificate, add --set privateCA=true and see Adding TLS Secrets - Using a Private CA Signed Certificate to add the CA cert for Rancher.

Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

Required Headers

Health Checks

Rancher will respond 200 to health checks on the /healthz endpoint.

Example NGINX config

upstream rancher {
    server IP_NODE_1:80;
    server IP_NODE_2:80;
    server IP_NODE_3:80;
}

map $http_upgrade $connection_upgrade {
    default Upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name FQDN;
    ssl_certificate /certs/fullchain.pem;
    ssl_certificate_key /certs/privkey.pem;

    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;
        proxy_buffering off;
   }
}

server {
    listen 80;
    server_name FQDN;
    return 301 https://$server_name$request_uri;
}