Rancher Installation Guide for DigitalOcean Kubernetes

Rancher is a powerful Kubernetes management platform that simplifies managing multiple Kubernetes clusters. If you’re setting it up on a DigitalOcean Kubernetes (DOKS) cluster and want to use a custom domain (e.g., rancher.yourdomain.com), this guide will take you from start to finish. We’ll cover every step, including configuring cert-manager, creating the necessary Issuer, and fixing common ingress-related issues.

Step 1: Set Up a Kubernetes Cluster on DigitalOcean

1. Create a DOKS Cluster:
   • Log in to your DigitalOcean Control Panel.
   • Click on Create → Kubernetes.
   • Choose your Kubernetes version, node size, and region.
   • Specify the number of nodes (at least 2 for redundancy).
   • Name your cluster (e.g., rancher-cluster) and click Create.
2. Download Your Kubeconfig File:
   • Once your cluster is ready, download the kubeconfig file or use doctl to configure access: doctl kubernetes cluster kubeconfig save rancher-cluster
3. Verify Access:
   • Test the cluster connectivity: kubectl get nodes You should see your cluster nodes listed.

Step 2: Install an NGINX Ingress Controller

To expose Rancher externally, you need an Ingress Controller. Follow these steps:

1. Install ingress-nginx Using Helm: helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update helm install ingress-nginx ingress-nginx/ingress-nginx \ --create-namespace --namespace ingress-nginx
2. Verify the Installation:
   • Check the Ingress Controller Service: kubectl get svc -n ingress-nginx
   • The output should show a LoadBalancer with an external IP. For example: NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ingress-nginx-controller LoadBalancer 10.245.65.81 167.172.15.201 80:31289/TCP,443:32627/TCP 5m
3. Set Up Your Domain’s DNS:
   • Point your domain (e.g., rancher.yourdomain.com) to the Ingress Controller’s external IP (167.172.15.201) by creating an A record in your DNS provider.

Step 3: Install cert-manager for TLS Certificates

Rancher requires HTTPS to work correctly. Use cert-manager to automatically obtain and renew TLS certificates.

1. Install cert-manager Using Helm: helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ --set installCRDs=true
2. Verify Installation:
   • Check that cert-manager pods are running: kubectl get pods -n cert-manager
   • You should see pods for cert-manager, cert-manager-cainjector, and cert-manager-webhook in a Running state.

Step 4: Install Rancher

1. Add the Rancher Helm Repository: helm repo add rancher-stable https://releases.rancher.com/server-charts/stable helm repo update
2. Create the cattle-system Namespace: kubectl create namespace cattle-system
3. Install Rancher: helm install rancher rancher-stable/rancher \ --namespace cattle-system \ --set hostname=rancher.yourdomain.com \ --set ingress.tls.source=letsEncrypt
4. Monitor Rancher Pods:
   • Wait for Rancher to initialize: kubectl get pods -n cattle-system
   • Ensure all pods are in the Running state.

Step 5: Fix Common Issues with Ingress

Issue 1: No CLASS Assigned to Ingress

1. Check your ingress resources: kubectl get ingress -n cattle-system If you see <none> under the CLASS column, it means the Ingress resources are not being picked up by the ingress-nginx controller.
2. Patch the Ingress Resources:
   • For the cert-manager challenge Ingress: kubectl patch ingress cm-acme-http-solver-<hash> -n cattle-system -p '{"spec": {"ingressClassName": "nginx"}}'
   • For the Rancher Ingress: kubectl patch ingress rancher -n cattle-system -p '{"spec": {"ingressClassName": "nginx"}}'
3. Verify the Ingress Class: kubectl get ingress -n cattle-system You should now see nginx in the CLASS column.

Issue 2: HTTP Challenge Fails

1. Check the temporary challenge Ingress: kubectl get ingress -n cattle-system Look for the cm-acme-http-solver-<hash> resource.
2. Describe the Ingress: kubectl describe ingress cm-acme-http-solver-<hash> -n cattle-system
3. Test the HTTP Challenge: Use curl to test the challenge URL: curl -I http://rancher.yourdomain.com/.well-known/acme-challenge/<challenge-token>
   • If this fails, ensure your DNS and firewall settings are correct.
   • Port 80 must be open to the public for the Let’s Encrypt HTTP-01 challenge to succeed.

Step 6: Verify TLS and Rancher Access

1. Monitor the Certificate Issuance: Check the status of the Certificate resource: kubectl describe certificate tls-rancher-ingress -n cattle-system
   • If the Status shows Ready: True, the certificate is successfully issued.
2. Restart Rancher Deployment (Optional): kubectl rollout restart deployment rancher -n cattle-system
3. Access Rancher: Open https://rancher.yourdomain.com in your browser. You should now see the Rancher login page with a valid TLS certificate.

Conclusion

By following these steps, you’ve successfully installed Rancher on a DigitalOcean Kubernetes cluster, configured it with an Ingress controller, and ensured HTTPS works seamlessly using cert-manager and Let’s Encrypt. This guide is tailored to help even Kubernetes beginners set up a secure and production-ready Rancher environment.

If you run into any issues, check the cert-manager logs and make sure your DNS and firewall settings are correct. With Rancher up and running, you can now easily manage multiple Kubernetes clusters from a single interface!

Happy Kubernetes management! 🎉