Rancher - Developer Guide

Learn how to deploy Rancher on AWS with our step-by-step guide. It walks you through launching the Meetrix Rancher AMI with CloudFormation, pointing your domain at it, logging in for the first time, and keeping the server healthy once it runs.

Rancher is an open-source Kubernetes management platform from SUSE. From one dashboard you can create new clusters, import existing ones such as Amazon EKS, manage users and access, and deploy apps across all of them. The Meetrix image runs Rancher on a single EC2 instance on top of a lightweight K3s cluster, so you get a working management server in minutes instead of building one by hand. If you are running GPU workloads, our guides on GPU scheduling in Kubernetes and deploying vLLM on EKS pair well with a Rancher-managed cluster.

Launching the AMI

Step 1: Find and Select Rancher AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Rancher' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Rancher" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter an "AdminPassword". This is the bootstrap password you use for the first login to Rancher, so store it securely.
4. Enter a value for "DeploymentName".
5. Provide a public domain for "DomainName". Rancher will automatically try to set up SSL if the domain is hosted on Route 53. If unsuccessful, you must set up SSL manually.
6. Choose an instance type "InstanceType" (Recommended: t3a.large).
7. Select your preferred "KeyName".
8. Enter the name of your S3 bucket for "S3Bucket", used for storing backups.
9. Set "SSHLocation" to 0.0.0.0/0, or restrict it to your own IP range.
10. Keep "SubnetCidrBlock" as 10.0.0.0/24.
11. Keep "VpcCidrBlock" as 10.0.0.0/16.
12. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the parameters you've entered.

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait 5-10 minutes until the stack status shows CREATE_COMPLETE.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name matching the DomainName you entered, keep the record type as A, and paste the copied PublicIp into the value textbox.
4. Click "Create records".

Access Rancher

Access Rancher using the "DashboardUrl" in the Outputs tab. Until DNS and SSL are in place you can use "DashboardUrlIp" instead, which shows a self-signed certificate warning in the browser.

On the first visit, Rancher shows a "Welcome to Rancher" screen asking for a bootstrap password. Enter the AdminPassword you set in the stack parameters and click "Log in with Local User". You do not need to run the kubectl command shown on the screen.

Follow the prompts to confirm the Server URL (your DashboardUrl) and accept the terms. You then land on the Rancher home page, where the local K3s cluster that Rancher runs on is already listed as Active. From here you can Create a new cluster or Import Existing ones. The Rancher documentation covers each cluster type in detail.

Generate SSL Manually

Rancher will automatically try to set up SSL when a Route 53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

1. Follow the Update DNS steps above, if not already done.
2. Copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the following command, replacing the key name and IP address.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Run the following command and follow the prompts:

sudo /root/certificate_generate_standalone.sh

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

List the running containers, then view the logs of the Rancher container using the first few characters of its container ID:

sudo docker ps

sudo docker logs <container-id-prefix>

Shutting Down Rancher

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Rancher instance from the Instance state dropdown. You can restart it later as needed.

Remove Rancher

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete". Downstream clusters that Rancher created in your account are separate resources, so remove them first if you no longer need them.

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

If you face vCPU quota limits, request an increase: How to increase AWS quota.

If you face insufficient capacity errors while creating the stack, try another region or time.

If the dashboard shows a 502 Bad Gateway error, wait 5-10 minutes and retry. Rancher can take a few minutes to start after the instance boots.

Check whether the instance storage is full. Log into the server and run:

df -h

If the root volume is between 90-100%, resize the EBS volume, then reboot and restart the service.

Conclusion

The Meetrix Rancher Deployment Guide helps you run a Kubernetes management server in your AWS environment. Whether you're a DevOps engineer, platform engineer, or IT leader, this guide provides step-by-step instructions for a secure setup. See the Rancher store page for what the Meetrix image includes and how it compares with OpenShift. If you want to monitor the clusters Rancher manages, our Grafana developer guide shows how to launch Grafana on AWS the same way.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Rancher issues.