Skip to content

Commit ce0a516

Browse files
davidebianchidavidebianchi
authored
docs: improve rhaii-helm-chart documentation (opendatahub-io#53)
1 parent 6b5e24e commit ce0a516

1 file changed

Lines changed: 58 additions & 85 deletions

File tree

‎charts/rhaii-helm-chart/README.md‎

Lines changed: 58 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,25 @@ Red Hat OpenShift AI Operator Helm chart for non-OLM installation.
44

55
This chart installs the RHAI operator and its cloud manager components. Exactly one cloud provider (Azure or CoreWeave) must be enabled.
66

7+
## Table of Contents
8+
9+
- [RHAII Helm Chart](#rhaii-helm-chart)
10+
- [Table of Contents](#table-of-contents)
11+
- [Prerequisites](#prerequisites)
12+
- [Installation](#installation)
13+
- [Azure](#azure)
14+
- [CoreWeave](#coreweave)
15+
- [Pull Secrets](#pull-secrets)
16+
- [How It Works](#how-it-works)
17+
- [Managed Dependencies](#managed-dependencies)
18+
- [Configuration Reference](#configuration-reference)
19+
- [Testing with kind](#testing-with-kind)
20+
- [Uninstall](#uninstall)
21+
722
## Prerequisites
823

9-
- Kubernetes cluster
10-
- Helm 3.x
24+
- Kubernetes cluster (or OpenShift)
25+
- Helm 4.x
1126
- Cluster-admin privileges (the chart creates CRDs, ClusterRoles, and namespaces)
1227

1328
## Installation
@@ -30,37 +45,8 @@ helm upgrade rhaii ./charts/rhaii-helm-chart/ \
3045
--set coreweave.enabled=true
3146
```
3247

33-
> **Note:** `helm install --wait` (or `helm upgrade --install --wait` the first time) is not supported at this stage. The chart uses post-install hooks (Jobs) to create Custom Resources after the operators are deployed. These hooks require the CRDs to be registered, but without the Custom Resource the rhods-operator will not start correctly because it needs the cert-manager, which means the `--wait` flag may cause the installation to time out or fail.
34-
35-
## What the Chart Installs
36-
37-
The chart deploys the following resources:
38-
39-
1. **RHAI Operator** — Deployment, ServiceAccount, RBAC, webhooks, and CRDs in the operator namespace
40-
2. **Cloud Manager** (Azure or CoreWeave) — Deployment, ServiceAccount, RBAC, and CRDs for the selected cloud provider
41-
3. **Post-install Job** — A Helm hook that automatically creates the required Custom Resources (Kserve, AzureKubernetesEngine, or CoreWeaveKubernetesEngine) after install/upgrade
42-
43-
### Custom Resources Created by Post-install Hook
44-
45-
The post-install Job creates the following CRs (configurable via values):
46-
47-
- **Kserve** — Created when `components.kserve.enabled=true` (default)
48-
- **AzureKubernetesEngine** — Created when `azure.enabled=true` and `azure.kubernetesEngine.enabled=true` (default)
49-
- **CoreWeaveKubernetesEngine** — Created when `coreweave.enabled=true` and `coreweave.kubernetesEngine.enabled=true` (default)
50-
51-
You can customize the spec of each CR through values. For example:
52-
53-
```yaml
54-
azure:
55-
enabled: true
56-
kubernetesEngine:
57-
spec:
58-
dependencies:
59-
certManager:
60-
managementPolicy: Unmanaged
61-
```
62-
63-
Set `managementPolicy: Unmanaged` for any dependency you want to manage yourself.
48+
> [!WARNING]
49+
> `helm install --wait` is **not supported**. The chart uses post-install hook Jobs to create Custom Resources after the operators are deployed. These hooks require CRDs to be registered first, and the rhods-operator depends on cert-manager to start correctly. Using `--wait` may cause the installation to time out or fail.
6450
6551
## Pull Secrets
6652

@@ -79,74 +65,61 @@ This will:
7965
1. Create a `kubernetes.io/dockerconfigjson` Secret named `rhaii-pull-secret` in all chart-managed namespaces (operator, applications, release, cloud manager and all dependency namespaces)
8066
2. Add `imagePullSecrets` to all chart-managed ServiceAccounts (RHAI operator, cloud manager and llmisvc-controller-manager in the applications namespace)
8167

82-
The secret name defaults to `rhaii-pull-secret` and MUST NOT be changed.
83-
84-
> **Note:** Pull secrets for dependency namespaces (`cert-manager-operator`, `cert-manager`, `istio-system`, `openshift-lws-operator`) are managed by this chart by default. To change the dependency namespaces managed, set `imagePullSecret.dependencyNamespaces` to the desired namespaces.
85-
86-
## Configuration
87-
88-
| Parameter | Description | Default |
89-
| --- | --- | --- |
90-
| `enabled` | Enable/disable all resource creation | `true` |
91-
| `installCRDs` | Install CRDs with the chart | `true` |
92-
| `labels` | Common labels applied to all resources | `{}` |
93-
| **Image Pull Secret** | | |
94-
| `imagePullSecret.name` | Name of the pull secret to create | `rhaii-pull-secret` |
95-
| `imagePullSecret.dockerConfigJson` | Docker config JSON content (use `--set-file`) | `""` |
96-
| **RHAI Operator** | | |
97-
| `rhaiOperator.namespace` | Operator namespace | `redhat-ods-operator` |
98-
| `rhaiOperator.applicationsNamespace` | Applications namespace | `redhat-ods-applications` |
99-
| `rhaiOperator.image` | Operator container image | `quay.io/opendatahub/opendatahub-operator:latest` |
100-
| `rhaiOperator.relatedImages` | Related images env vars (`RELATED_IMAGE_*`) | `{}` |
101-
| **Components** | | |
102-
| `components.kserve.enabled` | Create Kserve CR via post-install hook | `true` |
103-
| `components.kserve.spec` | Kserve CR spec | `{}` |
104-
| **Azure** | | |
105-
| `azure.enabled` | Enable Azure cloud provider | `false` |
106-
| `azure.cloudManager.namespace` | Azure Cloud Manager namespace | `rhai-cloudmanager-system` |
107-
| `azure.cloudManager.image` | Azure Cloud Manager image | `quay.io/opendatahub/opendatahub-operator:latest` |
108-
| `azure.kubernetesEngine.enabled` | Create AzureKubernetesEngine CR via post-install hook | `true` |
109-
| `azure.kubernetesEngine.spec` | AzureKubernetesEngine CR spec | See [values.yaml](values.yaml) |
110-
| **CoreWeave** | | |
111-
| `coreweave.enabled` | Enable CoreWeave cloud provider | `false` |
112-
| `coreweave.cloudManager.namespace` | CoreWeave Cloud Manager namespace | `rhai-cloudmanager-system` |
113-
| `coreweave.cloudManager.image` | CoreWeave Cloud Manager image | `quay.io/opendatahub/opendatahub-operator:latest` |
114-
| `coreweave.kubernetesEngine.enabled` | Create CoreWeaveKubernetesEngine CR via post-install hook | `true` |
115-
| `coreweave.kubernetesEngine.spec` | CoreWeaveKubernetesEngine CR spec | See [values.yaml](values.yaml) |
68+
The secret name defaults to `rhaii-pull-secret` and **must not** be changed.
11669

117-
## Testing with kind
70+
> [!NOTE]
71+
> Pull secrets for dependency namespaces (`cert-manager-operator`, `cert-manager`, `istio-system`, `openshift-lws-operator`) are managed by this chart by default. To customize which dependency namespaces receive pull secrets, set `imagePullSecret.dependencyNamespaces`.
11872
119-
You can test the chart locally using [kind](https://kind.sigs.k8s.io/).
73+
## How It Works
12074

121-
### Create a cluster
75+
The chart performs a **two-phase installation**:
12276

123-
```bash
124-
kind create cluster --name rhoai --config ./kind.config.yaml
125-
```
77+
1. **Phase 1 — Helm install:** deploys all operator resources (Deployments, RBAC, CRDs, etc.)
78+
2. **Phase 2 — Post-install hook:** a Helm hook Job runs after install/upgrade to create the Custom Resources that configure the operators
79+
80+
This two-phase approach is necessary because the CRs depend on CRDs that are only available after the operators are deployed.
81+
82+
## Managed Dependencies
83+
84+
The KubernetesEngine CRs (Azure or CoreWeave) manage the following dependencies. Each can be set to `Managed` (operator handles installation and lifecycle) or `Unmanaged` (you manage it yourself):
12685

127-
An example `kind.config.yaml` that uses local container registry credentials:
86+
| Dependency | Description |
87+
| --- | --- |
88+
| `certManager` | Certificate management (cert-manager) |
89+
| `gatewayAPI` | Gateway API CRDs and controller |
90+
| `lws` | LeaderWorkerSet (LWS) operator |
91+
| `sailOperator` | Sail Operator (Istio service mesh) |
92+
93+
To opt out of a managed dependency, set its `managementPolicy` to `Unmanaged`:
12894

12995
```yaml
130-
kind: Cluster
131-
apiVersion: kind.x-k8s.io/v1alpha4
132-
nodes:
133-
- role: control-plane
134-
extraMounts:
135-
- hostPath: /path/to/your/auth.json
136-
containerPath: /var/lib/kubelet/config.json
96+
azure:
97+
enabled: true
98+
kubernetesEngine:
99+
spec:
100+
dependencies:
101+
certManager:
102+
managementPolicy: Unmanaged
137103
```
138104
139-
This mounts a local `auth.json` into the kind node so it can pull images from private registries. Set `hostPath` to the actual path of your container credentials file (e.g. `$HOME/.config/containers/auth.json` or `$XDG_RUNTIME_DIR/containers/auth.json`, depending on your system).
105+
## Configuration Reference
140106
141-
Alternatively, the chart supports `imagePullSecret` — see the [Pull Secrets](#pull-secrets) section.
107+
For the configuration reference, please refer to the [API reference](api-docs.md) file and the [values.yaml](values.yaml) file.
108+
109+
## Testing with kind
142110
143-
### Install the chart
111+
You can test the chart locally using [kind](https://kind.sigs.k8s.io/).
144112
145113
```bash
114+
# Create a local cluster
115+
kind create cluster --name rhoai
116+
117+
# Install the chart (see "Pull Secrets" section for private registry auth)
146118
helm upgrade rhaii ./charts/rhaii-helm-chart/ \
147119
--install --create-namespace \
148120
--namespace rhaii \
149-
--set azure.enabled=true
121+
--set azure.enabled=true \
122+
--set-file imagePullSecret.dockerConfigJson=/path/to/auth.json
150123
```
151124

152125
## Uninstall

0 commit comments

Comments
 (0)