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

# Custom Helm Charts

> Deploy external Helm charts to your Porter cluster via the dashboard or Helm CLI for third-party components not natively managed by Porter

Sometimes you need to install external charts that are not managed by Porter. You can deploy custom Helm charts either through the Porter dashboard or directly via the Helm CLI.

***

## Deploying via Porter

Deploy Helm charts through the Porter dashboard for a managed experience with visibility into your deployments.

<Steps>
  <Step title="Select Helm Chart addon">
    Navigate to **Add-ons** in your Porter dashboard and select **Helm Chart**.
  </Step>

  <Step title="Configure the chart">
    Enter the Helm repository URL and select the chart you want to deploy.
  </Step>

  <Step title="Select version">
    Choose the chart version you want to install.
  </Step>

  <Step title="Customize values (optional)">
    Modify any values from the chart's default configuration as needed.
  </Step>

  <Step title="Deploy">
    Click **Deploy** to install the chart to your cluster.
  </Step>
</Steps>

<Info>
  Since custom Helm charts install external components into your cluster, they fall outside of Porter's standard support. However, we'll do our best to help you troubleshoot issues.
</Info>

### Managing deployed charts

Once deployed, you can:

* View the chart status in the Add-ons tab
* Update values and redeploy
* Upgrade to newer chart versions
* Delete the chart when no longer needed

***

## Deploying via Helm CLI

For more control or CI/CD integration, you can deploy Helm charts directly using the Helm CLI.

### Prerequisites

1. Install the [Helm CLI](https://helm.sh/docs/intro/install/)
2. Configure kubectl to connect to your Porter cluster. Run:
   ```bash theme={null}
   porter config set-cluster
   ```
   And select the cluster from the dropdown. If there is only one
   cluster in your project it will be automatically selected.

### Deploying a chart

```bash theme={null}
# Add the Helm repository
helm repo add <repo-name> <repo-url>
helm repo update

# Install the chart:
porter helm -- install <release-name> <repo-name>/<chart-name> \
  --namespace <namespace> \
  --values values.yaml
```

### Example: Installing NGINX Ingress

```bash theme={null}
# Add the ingress-nginx repository
porter helm -- repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
porter helm -- repo update

# Install the chart
porter helm -- install my-ingress ingress-nginx/ingress-nginx \
  --namespace ingress \
  --create-namespace
```

### Upgrading a release

```bash theme={null}
porter helm -- upgrade <release-name> <repo-name>/<chart-name> \
  --namespace <namespace> \
  --values values.yaml
```

### Listing releases

```bash theme={null}
porter helm -- list --all-namespaces
```

### Uninstalling a release

```bash theme={null}
porter helm -- uninstall <release-name> --namespace <namespace>
```

***

## Observability

There is limited observability offered for third-party helm chart installations, consisting of logs available in the dashboard.

For more complex scenarios, you can deploy a **Grafana** addon, which is already configured with the existing observability
stack deployed in the cluster. Grafana makes it possible to explore, query and build dashboard to monitor any charts or
workloads deployed in your cluster.

***

## Best Practices

### Use version pinning

Always specify a chart version to ensure reproducible deployments:

```bash theme={null}
porter helm -- install my-release repo/chart --version 1.2.3
```

### Store values in version control

Keep your custom values files in version control alongside your application code. For example, for the
"custom-chart" helm chart, you can keep the following structure:

`porter-custom-helm-chart-addons/custom-chart/chart.yaml`

```yaml theme={null}
# chart.yaml
chartUrl: https://custom-chart-repo.com
version: 1.0.0
```

`porter-custom-helm-chart-addons/custom-chart/values.yaml`

```yaml theme={null}
# values.yaml
replicaCount: 3
resources:
  limits:
    cpu: 100m
    memory: 128Mi
```

You can then use these values in CI to install the chart

```bash theme={null}
CHART_URL=$(yq e '.chartUrl' porter-custom-helm-chart-addons/custom-chart/chart.yaml)
VERSION=$(yq e '.version' porter-custom-helm-chart-addons/custom-chart/chart.yaml)

porter helm -- install custom-chart $CHART_URL \
  --version $VERSION \
  --values porter-custom-helm-chart-addons/custom-chart/values.yaml
```

### Test in non-production first

Before deploying to production, test custom charts in a development or staging cluster to verify compatibility with your Porter environment.