trainer/charts/kubeflow-trainer/README.md.gotmpl

{{- /*
Copyright 2026 The Kubeflow Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/ -}}

{{ template "chart.header" . }}

{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

## Introduction

This chart bootstraps a [Kubernetes Trainer]({{template "chart.homepage" . }}) deployment using the [Helm](https://helm.sh) package manager.

## Prerequisites

- Helm >= 3
- Kubernetes >= 1.29

## Usage

### Install the Helm Chart

Install the released version (e.g. 2.1.0):

```bash
helm install kubeflow-trainer oci://ghcr.io/kubeflow/charts/kubeflow-trainer --version 2.1.0
```

Alternatively, you can install the latest version from the master branch (e.g. `bfccb7b` commit):

```bash
helm install kubeflow-trainer oci://ghcr.io/kubeflow/charts/kubeflow-trainer --version 0.0.0-sha-bfccb7b
```

### Install with ClusterTrainingRuntimes

You can optionally deploy ClusterTrainingRuntimes as part of the Helm installation. Runtimes are disabled by default to keep the chart lightweight.

To enable all default runtimes (torch, deepspeed, mlx, torchtune):

```bash
helm install kubeflow-trainer oci://ghcr.io/kubeflow/charts/kubeflow-trainer \
  --version 2.1.0 \
  --set runtimes.defaultEnabled=true
```

To enable specific runtimes:

```bash
helm install kubeflow-trainer oci://ghcr.io/kubeflow/charts/kubeflow-trainer \
  --version 2.1.0 \
  --set runtimes.torchDistributed.enabled=true \
  --set runtimes.deepspeedDistributed.enabled=true
```

Or use a custom values file:

```yaml
# values.yaml
runtimes:
  torchDistributed:
    enabled: true
  deepspeedDistributed:
    enabled: true
  mlxDistributed:
    enabled: true

# For torch-distributed-with-cache, enable both dataCache.enabled and dataCache.runtimes.torchDistributed.enabled
dataCache:
  enabled: true
  cacheImage:
    tag: "v2.0.0"
  runtimes:
    torchDistributedWithCache:
      enabled: true
```

Then install with:

```bash
helm install kubeflow-trainer oci://ghcr.io/kubeflow/charts/kubeflow-trainer \
  --version 2.1.0 \
  -f values.yaml
```

### Available Runtimes

- **torch-distributed**: PyTorch distributed training (no custom images)
- **torch-distributed-with-cache**: PyTorch with distributed data cache support (requires `dataCache.enabled=true`)
- **deepspeed-distributed**: DeepSpeed distributed training with MPI
- **mlx-distributed**: MLX distributed training with MPI

### Uninstall the chart

```shell
helm uninstall [RELEASE_NAME]
```

This removes all the Kubernetes resources associated with the chart and deletes the release, except for the `crds`, those will have to be removed manually.

See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall) for command documentation.

### Istio sidecar configuration

If you are running Istio and need to exclude the manager webhook port from sidecar interception, configure the annotation via `manager.podAnnotations`:

```yaml
manager:
  podAnnotations:
    traffic.sidecar.istio.io/excludeInboundPorts: "9443"
```

{{ template "chart.valuesSection" . }}

{{- define "chart.maintainersTable" -}}
| Name | Url |
| ---- | --- |
{{- range .Maintainers }}
| {{ .Name }} | {{ if .Url }}<{{ .Url }}>{{ end }} |
{{- end }}
{{- end }}

{{ template "chart.maintainersSection" . }}