> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rancher/rancher/llms.txt
> Use this file to discover all available pages before exploring further.

# Helm Installation

> Install Rancher on a Kubernetes cluster using the official Helm chart

Rancher can be installed on any Kubernetes cluster using the official Helm chart. This is the recommended method for production environments, enabling high availability and integration with Kubernetes scheduling.

## Prerequisites

Before installing Rancher, ensure your environment meets the following requirements:

### Supported Kubernetes Distributions

For installations covered under Rancher Support SLA, the target cluster must be one of:

* **RKE1** - Rancher Kubernetes Engine 1
* **RKE2** - Rancher Kubernetes Engine 2
* **K3s** - Lightweight Kubernetes
* **AKS** - Azure Kubernetes Service
* **EKS** - Amazon Elastic Kubernetes Service
* **GKE** - Google Kubernetes Engine

### Required Tools

* **kubectl** - Kubernetes command-line tool
* **helm** - Package management for Kubernetes (refer to Helm version requirements)

### System Requirements

* Operating system and container runtime requirements
* Hardware requirements:
  * CPU and Memory
  * Ingress controller
  * Disk storage
* Networking requirements:
  * Node IP addresses
  * Port requirements

## Installation Steps

<Steps>
  ### Add the Helm Chart Repository

  Add the Rancher Helm chart repository using the appropriate channel for your use case:

  ```bash theme={null}
  helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
  ```

  <Note>
    Choose the repository based on your version requirements:

    * `rancher-latest` - Latest stable releases
    * `rancher-stable` - Stable releases with extended testing
    * `rancher-alpha` - Alpha/preview releases
  </Note>

  ### Create the Namespace

  Create the `cattle-system` namespace where Rancher resources will be installed:

  ```bash theme={null}
  kubectl create namespace cattle-system
  ```

  ### Choose SSL Configuration

  Rancher requires SSL/TLS configuration. Select one of three certificate options:

  #### Option 1: Rancher-Generated Certificates (Default)

  Rancher generates a self-signed certificate using cert-manager:

  ```bash theme={null}
  helm install rancher rancher-latest/rancher \
    --namespace cattle-system \
    --set hostname=rancher.my.org
  ```

  #### Option 2: Let's Encrypt

  Use Let's Encrypt for automatic certificate generation:

  ```bash theme={null}
  helm install rancher rancher-latest/rancher \
    --namespace cattle-system \
    --set hostname=rancher.my.org \
    --set ingress.tls.source=letsEncrypt \
    --set letsEncrypt.email=me@example.org
  ```

  <Warning>
    The production environment only allows registering a name 5 times per week. Use `letsEncrypt.environment=staging` for testing.
  </Warning>

  #### Option 3: Bring Your Own Certificate

  Use certificates from files stored as Kubernetes secrets:

  ```bash theme={null}
  helm install rancher rancher-latest/rancher \
    --namespace cattle-system \
    --set hostname=rancher.my.org \
    --set ingress.tls.source=secret
  ```

  For private CA certificates, add the `--set privateCA=true` flag:

  ```bash theme={null}
  helm install rancher rancher-latest/rancher \
    --namespace cattle-system \
    --set hostname=rancher.my.org \
    --set ingress.tls.source=secret \
    --set privateCA=true
  ```

  ### Install cert-manager (if required)

  Install cert-manager if using Rancher-generated certificates or Let's Encrypt:

  ```bash theme={null}
  kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
  ```

  <Note>
    This step is only required when `ingress.tls.source=rancher` or `ingress.tls.source=letsEncrypt`.
  </Note>

  ### Verify the Deployment

  Check the rollout status of the Rancher deployment:

  ```bash theme={null}
  kubectl -n cattle-system rollout status deploy/rancher
  ```

  Expected output:

  ```
  Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  deployment "rancher" successfully rolled out
  ```

  Verify all replicas are available:

  ```bash theme={null}
  kubectl -n cattle-system get deploy rancher
  ```

  Expected output:

  ```
  NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  rancher   3         3         3            3           3m
  ```

  ### Access Rancher

  Open a web browser and navigate to the hostname you configured (e.g., `https://rancher.my.org`). You should see the Rancher login page.
</Steps>

## Common Configuration Options

### Basic Options

| Parameter                 | Default      | Description                                               |
| ------------------------- | ------------ | --------------------------------------------------------- |
| `hostname`                | " "          | Fully Qualified Domain Name for your Rancher Server       |
| `ingress.tls.source`      | "rancher"    | Certificate source: `rancher`, `letsEncrypt`, or `secret` |
| `letsEncrypt.email`       | " "          | Email address for Let's Encrypt                           |
| `letsEncrypt.environment` | "production" | Let's Encrypt environment: `staging` or `production`      |
| `privateCA`               | false        | Set to true if using a private CA-signed certificate      |
| `replicas`                | 3            | Number of Rancher pod replicas                            |
| `bootstrapPassword`       | ""           | Set a bootstrap password (random if empty)                |

### Advanced Options

| Parameter                  | Default           | Description                                                   |
| -------------------------- | ----------------- | ------------------------------------------------------------- |
| `antiAffinity`             | "preferred"       | AntiAffinity rule for Rancher pods: `preferred` or `required` |
| `auditLog.enabled`         | false             | Enable the Rancher audit logging system                       |
| `auditLog.level`           | 0                 | API audit log level (0-3, with 3 most verbose)                |
| `proxy`                    | " "               | HTTP\[S] proxy server for Rancher                             |
| `noProxy`                  | "127.0.0.0/8,..." | Comma-separated list of addresses not to proxy                |
| `resources`                | {}                | Pod resource requests and limits                              |
| `systemDefaultRegistry`    | ""                | Private registry for all system Docker images                 |
| `useBundledSystemChart`    | false             | Use system-charts packaged with Rancher (air-gapped)          |
| `ingress.ingressClassName` | " "               | Ingress class name if not using defaults                      |

### Example: Custom Resource Limits

```bash theme={null}
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set replicas=3 \
  --set resources.requests.cpu=1000m \
  --set resources.requests.memory=2Gi \
  --set resources.limits.cpu=2000m \
  --set resources.limits.memory=4Gi
```

### Example: Air-Gapped Installation

```bash theme={null}
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set systemDefaultRegistry=registry.example.com \
  --set useBundledSystemChart=true
```

## Saving Installation Options

<Warning>
  Make sure you save the `--set` options you used during installation. You will need to use the same options when upgrading Rancher to new versions with Helm.
</Warning>

## Troubleshooting

If deployment exceeds the progress deadline:

```bash theme={null}
kubectl -n cattle-system get pods
kubectl -n cattle-system logs -l app=rancher
```

For additional troubleshooting guidance, refer to the [Rancher Troubleshooting documentation](https://ranchermanager.docs.rancher.com/troubleshooting/general-troubleshooting).

### Gateway API Configuration

Rancher supports the Gateway API as an alternative to traditional Ingress controllers. This is useful for environments that use Gateway API for routing.

```yaml theme={null}
networkExposure:
  type: gateway  # Options: ingress, gateway
  gateway:
    gatewayClass: istio  # Gateway class to use
    gatewayName: rancher-gateway  # Name of the gateway
    listenerName: https  # Listener name on the gateway
```

To install Rancher with Gateway API:

```bash theme={null}
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set networkExposure.type=gateway \
  --set networkExposure.gateway.gatewayClass=istio
```

<Note>
  Gateway API support requires the Gateway API CRDs to be installed in your cluster and a compatible Gateway controller (e.g., Istio, Envoy Gateway).
</Note>

### Resource Requirements

For production deployments, it's recommended to set resource requests and limits to ensure stable performance:

```yaml theme={null}
resources:
  requests:
    memory: "2Gi"
    cpu: "1"
  limits:
    memory: "4Gi"
    cpu: "2"
```

Example installation with resource requirements:

```bash theme={null}
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set resources.requests.memory=2Gi \
  --set resources.requests.cpu=1 \
  --set resources.limits.memory=4Gi \
  --set resources.limits.cpu=2
```

<Tip>
  Adjust these values based on your cluster size and workload. Larger clusters with many downstream clusters may require more resources.
</Tip>

### Host Network Mode

In some scenarios, Rancher needs to run with host networking enabled. This is particularly common in EKS clusters using non-VPC CNI plugins like Calico.

```yaml theme={null}
hostNetwork: true
```

Example installation with host network:

```bash theme={null}
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set hostNetwork=true
```

<Warning>
  **Security Implications:**

  * Pods will use the host's network namespace
  * Ports will be exposed directly on the host
  * Bypasses NetworkPolicy controls
  * Should only be used when absolutely necessary (e.g., EKS with Calico CNI)
</Warning>

## Next Steps

* Configure [high availability](/configuration/high-availability) for production deployments
* Set up authentication providers
* Configure backup and disaster recovery
* Review [best practices](https://ranchermanager.docs.rancher.com/pages-for-subheaders/best-practices) for running Rancher in production