Rancher Kubernetes Management Platform on AWS User Guide
Overview
Rancher is an open source Kubernetes management platform. It gives you one console, one API and one authentication and RBAC model across every Kubernetes cluster you run - hosted, on premises, or provisioned by Rancher itself. From the dashboard you browse and edit workloads, namespaces, nodes and Helm applications, manage users and role bindings, drive Fleet GitOps, and open a shell or kubectl session into any managed cluster without handing kubeconfig files around.
This cloudimg AMI delivers Rancher 2.14.3 fully installed and running. The web console answers on HTTPS within minutes of launch.
How it is installed, and why
Rancher can be run as a single container with docker run. Upstream's own documentation carries a danger admonition on that page reading, verbatim: "Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only."
Shipping a paid Marketplace image whose only install path is one the vendor tells you not to run in production would not be honest, so this image does not use it. Instead it installs the official rancher-stable Helm chart onto an embedded single node K3s cluster, with cert-manager issuing the Rancher generated certificate. That is the route the project documents for a Rancher server, and K3s brings its own Traefik ingress controller, so ports 80 and 443 are served with no extra wiring.
What is actually in the image
| Component | Version | Role |
|---|---|---|
| Rancher | 2.14.3 | the management server, a Deployment in namespace cattle-system |
| K3s | v1.35.5+k3s1 | the embedded Kubernetes cluster Rancher runs on and manages as local |
| cert-manager | v1.19.2 | issues the Rancher generated TLS certificate |
| Traefik | v3.6.x | the K3s bundled ingress controller that serves ports 80 and 443 |
| CoreDNS, metrics-server, local-path-provisioner | K3s bundled | cluster DNS, metrics and default storage class |
| Helm | v3.20.0 | on PATH for you to use |
There is no Docker on this image. K3s runs its own containerd.
One instance, one cluster - read this before you size it
This is a single node, non highly available Rancher server. Upstream recommends a three node cluster for a highly available control plane, and one AMI cannot provide that. The Kubernetes cluster embedded here exists to run Rancher itself; the downstream clusters you register or provision with Rancher are of course as large as you like.
No shared administrator password ships
Rancher's bootstrap password is generated once and then persisted inside the cluster datastore - it is not regenerated on every start - and upstream's own examples set it to a well known value. Either behaviour would hand every customer of a shared image the same administrator login.
Neither happens here. Before the image was captured, the build destroyed the entire cluster identity: the etcd datastore, the cluster certificate authority private key, every node and agent join token, and the admin kubeconfig. On your first boot a one shot service starts K3s on that wiped state, so a brand new certificate authority, brand new join tokens and an empty datastore are generated on your instance, installs Rancher with a freshly generated 24 character administrator password, proves that password authenticates, and writes it to a root only file.
Launching the instance
Launch the AMI from the AWS Marketplace listing. Recommended settings:
| Setting | Value |
|---|---|
| Instance type | m5.large is the listing's priced type. Upstream's smallest endorsed spec for any Rancher server node is 4 vCPU and 16 GB, so choose m5.xlarge or larger for production and before you register downstream clusters. |
| Root volume | 50 GiB gp3 (the default in the listing) |
| Data volume | 100 GiB gp3, attached automatically, mounted at /var/lib/rancher |
| Security group | inbound TCP 22 (SSH), 80 (redirects to HTTPS), 443 (the Rancher console and API) |
| Key pair | your own EC2 key pair - it is what you use for the operating system login |
| Outbound | allow outbound HTTPS on first boot (see "About the first boot" below) |
Restrict the security group to your own address ranges wherever you can. Do not open ports 6443 or 10250 - the Kubernetes API server and the kubelet. The listing security group does not open them, and they should stay closed to the internet.
First boot takes several minutes: a one shot service starts a freshly initialised Kubernetes cluster, installs cert-manager and Rancher from locally staged Helm charts, generates your administrator password, and waits for a real login round trip to succeed before it finishes.
About the first boot and outbound access
The Rancher and cert-manager container images, the Kubernetes system images and both Helm charts are staged inside the AMI, so the management server itself comes up from local content rather than waiting on a registry.
Rancher then installs its own additional system components - Fleet, the Fleet agent, the admission webhook, the system upgrade controller and Rancher Turtles - after its deployment is ready, and those do pull their images from Docker Hub. Give the instance outbound HTTPS on first boot. The first boot service does not depend on them: it gates on the Rancher deployment, the health endpoint and a login round trip, all of which are local.
Connecting to your instance
SSH to the operating system with your own EC2 key pair, as the login user for your AMI variant:
| OS variant | SSH login user | Example |
|---|---|---|
| Ubuntu 24.04 LTS | ubuntu |
ssh -i your-key.pem ubuntu@<public-ip> |
Everything below is run over that SSH session. Rancher's own components run as containers in the embedded cluster, so you drive them with the bundled k3s kubectl.
Retrieving your administrator credentials
The credentials file is written by the first boot service and is readable only by root.
sudo grep -oE '^[A-Za-z0-9._]+=' /root/rancher-credentials.txt
rancher.url=
rancher.admin.user=
rancher.admin.pass=
RANCHER_BOOTSTRAP_PASSWORD=
That lists the key names only. To read the password itself:
sudo grep '^RANCHER_BOOTSTRAP_PASSWORD=' /root/rancher-credentials.txt | cut -d= -f2-
Keep it somewhere safe. Rancher will ask you to confirm your server URL and accept its licence terms at your first sign in, and you can change the administrator password from the console afterwards - this file is not updated when you do.
Checking the service is up
The whole appliance is one systemd unit, k3s.service, plus the one shot first boot unit.
systemctl is-active k3s.service
systemctl is-enabled k3s.service rancher-firstboot.service
active
enabled
enabled
The Kubernetes node Rancher runs on:
sudo k3s kubectl get nodes -o wide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
ip-172-31-92-252 Ready control-plane 9m13s v1.35.5+k3s1 172.31.92.252 <none> Ubuntu 24.04.4 LTS 6.17.0-1019-aws containerd://2.2.3-k3s1
Rancher itself, and cert-manager:
sudo k3s kubectl -n cattle-system get deploy
sudo k3s kubectl -n cert-manager get deploy
NAME READY UP-TO-DATE AVAILABLE AGE
rancher 1/1 1 1 8m52s
rancher-webhook 1/1 1 1 5m27s
system-upgrade-controller 1/1 1 1 5m7s
NAME READY UP-TO-DATE AVAILABLE AGE
cert-manager 1/1 1 1 9m9s
cert-manager-cainjector 1/1 1 1 9m9s
cert-manager-webhook 1/1 1 1 9m9s
Every Helm release on the box, which is the clearest single view of what is installed:
sudo helm list -A --kubeconfig /etc/rancher/k3s/k3s.yaml
NAME NAMESPACE REVISION STATUS CHART APP VERSION
cert-manager cert-manager 1 deployed cert-manager-v1.19.2 v1.19.2
fleet cattle-fleet-system 1 deployed fleet-109.0.4+up0.15.4 0.15.4
fleet-agent-local cattle-fleet-local-system 1 deployed fleet-agent-local-v0.0.0
fleet-crd cattle-fleet-system 1 deployed fleet-crd-109.0.4+up0.15.4 0.15.4
rancher cattle-system 1 deployed rancher-2.14.3 v2.14.3
rancher-turtles cattle-turtles-system 1 deployed rancher-turtles-109.0.3+up0.26.3 0.26.3
rancher-webhook cattle-system 2 deployed rancher-webhook-109.0.3+up0.10.7 0.10.7
system-upgrade-controller cattle-system 1 deployed system-upgrade-controller-109.0.2 v0.19.1
traefik kube-system 1 deployed traefik-39.0.701+up39.0.7 v3.6.12
traefik-crd kube-system 1 deployed traefik-crd-39.0.701+up39.0.7 v3.6.12
And the whole pod inventory, if you want to see everything at once:
sudo k3s kubectl get pods -A
Checking the web endpoints
Rancher serves HTTPS on 443 and redirects port 80 to it. The certificate is generated by Rancher itself through cert-manager, so curl needs -k (and your browser will warn on the first visit - see "Using your own certificate" below).
curl -sk -o /dev/null -w 'healthz:%{http_code}\n' https://127.0.0.1/healthz
curl -s -o /dev/null -w 'http80:%{http_code}\n' http://127.0.0.1/
curl -sk -o /dev/null -w 'dashboard:%{http_code}\n' https://127.0.0.1/dashboard/
healthz:200
http80:302
dashboard:200
A note on why /dashboard/ is checked and not just /healthz: Traefik routes by Host header, and the Rancher chart requires a hostname. A stock chart install would answer 404 to anyone browsing the bare instance IP even while Rancher is perfectly healthy. The first boot service applies an extra host-less catch-all ingress so the bare public IP works directly:
sudo k3s kubectl -n cattle-system get ingress
NAME CLASS HOSTS ADDRESS PORTS AGE
rancher <none> 100.53.76.57.sslip.io 172.31.92.252 80, 443 8m53s
rancher-cloudimg-catchall-http traefik * 172.31.92.252 80 8m12s
rancher-cloudimg-catchall-https traefik * 172.31.92.252 80 8m12s
Signing in to the console
Open https://<public-ip>/ in a browser. Accept the certificate warning (the certificate is self signed - replace it with your own using the section below), then sign in as admin with the password from your credentials file.
At your first sign in Rancher asks you to confirm the server URL and accept its End User Licence Agreement. The server URL is already filled in with your instance address - the first boot service set it for you.
Once past that you land on the home page, which lists the clusters Rancher manages. Out of the box that is one cluster, local - the embedded K3s cluster on this instance.
Clicking local opens the cluster dashboard: capacity, node count, deployment count, control plane component health and a live event feed.
The Nodes view shows the single control plane node with its live CPU, memory and pod utilisation.
Cluster Management is where you register or provision the clusters you actually want to manage.
The Apps and Charts catalogue is wired up out of the box, with the Rancher, Partners and RKE2 repositories already present.
Verifying the security posture
These four checks are worth running once on a new instance. Every one of them is also asserted by the build before the image is captured.
An unauthenticated caller must not be able to read the cluster inventory, and neither the Kubernetes API server nor the kubelet may answer anonymously:
curl -sk -o /dev/null -w 'v3clusters_anon:%{http_code}\n' https://127.0.0.1/v3/clusters
curl -sk -o /dev/null -w 'kubeapi_anon:%{http_code}\n' https://127.0.0.1:6443/api/v1/nodes
curl -sk -o /dev/null -w 'kubelet_anon:%{http_code}\n' https://127.0.0.1:10250/pods
v3clusters_anon:401
kubeapi_anon:401
kubelet_anon:401
Ports 6443 and 10250 bind on all interfaces - that is stock K3s behaviour and cannot be changed without breaking the embedded agent. They are credential protected, as shown above, and the listing security group does not open them. Keep it that way.
The cluster admin kubeconfig must not be world readable:
sudo stat -c '%a %U:%G %n' /etc/rancher/k3s/k3s.yaml
600 root:root /etc/rancher/k3s/k3s.yaml
Using the Rancher API
Rancher's v3 API is served on the same HTTPS port. Note that the login endpoint answers HTTP 201, not 200, on success.
curl -sk -o /tmp/rancher-login.json -w 'login_http:%{http_code}\n' \
-X POST 'https://127.0.0.1/v3-public/localProviders/local?action=login' \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"<RANCHER_BOOTSTRAP_PASSWORD>"}'
python3 -c "import json;print('token_returned:', bool(json.load(open('/tmp/rancher-login.json')).get('token')))"
rm -f /tmp/rancher-login.json
login_http:201
token_returned: True
Substitute your own password from the credentials file. The response body carries a bearer token - the command above deliberately reports only whether one came back rather than printing it. Send it as Authorization: Bearer <your-token> on subsequent calls, for example GET /v3/clusters to list managed clusters, or use the Rancher proxied Kubernetes API at /k8s/clusters/local/api/v1/namespaces.
For anything long lived, create a dedicated API key from the console under your user menu rather than reusing the bootstrap login.
Where the data lives
The Kubernetes state directory, the embedded etcd datastore, the cluster TLS material and the container image store all sit on a dedicated EBS volume mounted at /var/lib/rancher, separate from the operating system disk and independently resizable.
findmnt -no SOURCE,SIZE,FSTYPE,TARGET /var/lib/rancher
grep ' /var/lib/rancher ' /etc/fstab
/dev/nvme1n1 97.9G ext4 /var/lib/rancher
UUID=8ea48246-0322-4458-998f-e04249b4ddc8 /var/lib/rancher ext4 defaults,nofail 0 2
The fstab entry is by filesystem UUID, so the mount survives reboots and NVMe device renaming.
This matters most for the container image store. K3s roots its containerd inside /var/lib/rancher, so image layers land on the data volume rather than filling the operating system disk:
findmnt -no SOURCE --target /var/lib/rancher/k3s/agent/containerd
findmnt -no SOURCE --target /
df -h --output=source,size,used,avail,target / /var/lib/rancher
/dev/nvme1n1
/dev/nvme0n1p1
Filesystem Size Used Avail Mounted on
/dev/root 48G 3.4G 44G /
/dev/nvme1n1 98G 11G 83G /var/lib/rancher
To grow the volume later, resize it in the EC2 console, then run sudo growpart on the device and sudo resize2fs on the filesystem. To back it up, snapshot the EBS volume with AWS Backup or a scheduled EBS snapshot policy - that captures the etcd datastore that holds every Rancher object.
Using your own certificate
Out of the box Rancher serves a certificate it generated itself through cert-manager (ingress.tls.source=rancher), which is upstream's default. Browsers warn on it. There are two ways to fix that properly.
Bring your own certificate. Create a tls-rancher-ingress secret from your certificate and key in the cattle-system namespace, and if your certificate is signed by a private CA also create a tls-ca secret, then upgrade the Rancher release with --set ingress.tls.source=secret. Upstream documents this at rancher.com/docs under "Adding TLS Secrets".
Use Let's Encrypt. This needs a real DNS name pointing at the instance and ports 80 and 443 reachable from the internet, because the HTTP-01 challenge is served over port 80. Upgrade the Rancher release with --set ingress.tls.source=letsEncrypt --set letsEncrypt.email=you@example.com --set hostname=rancher.your-domain.example.
In both cases you are running helm upgrade against the release that is already installed, so pass the same hostname you want Rancher to serve on, and update the server-url setting in the console to match.
Registering a downstream cluster
The point of Rancher is the clusters it manages, not the one it runs on. In Cluster Management you can:
- Import Existing - Rancher gives you a single
kubectl applycommand to run against any reachable Kubernetes cluster, which installs the Rancher agent and registers it. - Create - provision a new cluster into a cloud provider or onto machines you supply, using a cloud credential you add first.
Imported clusters connect outbound from the cluster to your Rancher server URL, so the downstream cluster needs to reach this instance's HTTPS port - which is one more reason to give it a real DNS name and a proper certificate before you start registering things.
Licensing
Rancher is licensed Apache-2.0 and this image ships the open source build. SUSE separately sells Rancher Prime, a commercial support and supply chain offering; nothing from Prime is included here and no SUSE support entitlement comes with this listing. Support for this image is provided by cloudimg.
Every component of the shipped stack, and its licence and upstream source, is listed on the image:
sed -n '1,14p' /usr/share/doc/cloudimg-rancher/NOTICE-THIRD-PARTY.txt
cloudimg Rancher appliance - third-party components and licenses
================================================================
This image redistributes the following third-party software. Apache-2.0 requires
that its license text and attribution notices travel with the redistribution;
this file is that attribution. Where a component is licensed GPL-2.0 or GPL-3.0,
the corresponding source is available from the upstream distributor named below,
and this notice passes through their source offer (GPL-2 s3(c) / GPL-3 s6(d)) -
the binaries here are unmodified upstream builds.
Primary components
------------------
Rancher 2.14.3 Apache-2.0 https://github.com/rancher/rancher
K3s v1.35.5+k3s1 Apache-2.0 https://github.com/k3s-io/k3s
Troubleshooting
The console is not answering yet. First boot installs a whole Kubernetes stack, so give it several minutes. Watch it directly:
sudo systemctl status rancher-firstboot.service --no-pager
Something is not ready. Look at what is still coming up:
sudo k3s kubectl get pods -A --field-selector=status.phase!=Running
Browsing the instance IP gives a 404. That means the catch-all ingress is missing. Check it with the get ingress command above; both rancher-cloudimg-catchall-http and rancher-cloudimg-catchall-https should be present.
You changed the administrator password and lost it. Reset it from the instance by running sudo k3s kubectl -n cattle-system exec deploy/rancher -- reset-password, which prints a new administrator password. That command rotates the live credential, so it is given here as text rather than as a runnable block - do not paste it unless you actually mean to reset the password.
Memory pressure. Rancher is memory hungry, and more so once it manages downstream clusters. Check headroom with free -h and move to a larger instance type if the Rancher pod is restarting.
Support
cloudimg provides 24/7 technical support for this image by email and live chat at support@cloudimg.co.uk - deployment and initial configuration, first sign in and password rotation, replacing the certificate, pointing the instance at your own domain, registering downstream clusters, restricting the Kubernetes API and kubelet ports, backing up the embedded datastore, resizing the data volume, performance tuning, and patching guidance.