From a498b90f6753efb3844a6c7c9c66257de9d5e8ab Mon Sep 17 00:00:00 2001 From: Gaurav Chaudhary Date: Fri, 13 Nov 2026 00:18:00 +0530 Subject: [PATCH] docs(helm): document installation from source Signed-off-by: Gaurav Chaudhary --- README.md | 63 ++++++++++++++++---------------------------------- docs/README.md | 31 ++++++++++--------------- helm/README.md | 54 +++++++++++++++++-------------------------- 3 files changed, 53 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 32e35c9..1abfd86 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ [![Coverage](https://codecov.io/gh/kubevirt/redfish-controller/branch/main/graph/badge.svg)](https://codecov.io/gh/kubevirt/redfish-controller) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Container](https://img.shields.io/badge/container-quay.io-red.svg)](https://quay.io/repository/kubevirt/redfish-controller) -[![Helm](https://img.shields.io/badge/helm-oci-blue.svg)](https://quay.io/repository/kubevirt/charts/redfish-controller) [![Platform](https://img.shields.io/badge/platform-OpenShift-red.svg)](https://docs.openshift.com/container-platform/latest/virt/about-virt.html) A Redfish-compatible API server for KubeVirt/OpenShift Virtualization that enables out-of-band management of virtual machines through standard Redfish protocols. @@ -65,70 +64,48 @@ KubeVirt Redfish bridges the gap between traditional virtualization management t ## Installation QuickStart (via Helm) -The `kubevirt-redfish` project uses [Quay.io](https://quay.io/) to store both the [container](https://quay.io/repository/kubevirt/redfish-controller?tab=tags) and [Helm](https://quay.io/repository/kubevirt/charts/kubevirt-redfish?tab=tags) chart artifacts. Previous instructions were to written to support a direct OCI installation (i.e. `helm pull oci://quay.io/kubevirt/charts/redfish-controller --version 0.2.1`), however I would suggest you follow the instructions below to install `kubevirt-redfish`. Reserve any direct OCI chart testing for development purposes only. There is also an [operator](https://github.com/kubevirt/redfish-controller-operator) that can be leveraged as well, but please wait until release v0.3.0 for these projects to work seamlessly. For now, follow the instructions below for the most recent installation proceedures. +Install the `kubevirt-redfish` chart included in this repository. The previously documented public chart endpoints, `https://kubevirt.github.io/charts` and `oci://quay.io/kubevirt/charts/redfish-controller`, are unavailable; see [issue #21](https://github.com/kubevirt/redfish-controller/issues/21). -(*Updated: 25/08/25 at 11:35UTC) - -1. Add the Helm repository for the most recent Chart for this project (`kubevirt-redfish`). +1. Clone the source and enter the repository root. Git is required for this step. ```bash - helm repo add kubevirt https://kubevirt.github.io/charts - helm repo update + git clone https://github.com/kubevirt/redfish-controller.git + cd redfish-controller ``` - You should then see the Helm chart when performing a `helm list`. + This installs the chart from your source checkout, rather than a published chart release. To use a specific Git revision, run `git checkout ` before continuing. Run all chart commands below from the repository root. - ```bash - ❯ helm search repo kubevirt - NAME CHART VERSION APP VERSION DESCRIPTION - kubevirt/redfish-controller 0.2.3 v0.2.3-f87ff92 Custom kubevirt-redfish chart with enhanced fea... - kubevirt/vms-on-ocpv 0.1.1 v0.1.1-ff18cb3 A Helm chart that deploys Virtual Machines on O... - ``` +2. Review and save the chart values for editing. -2. You can then review the example `values.yaml` included with the Helm chart by using the following command. ```bash - helm show values kubevirt/redfish-controller --version 0.2.3 + helm show values ./helm + helm show values ./helm > my-values.yaml ``` - NOTE: If you prefer to have a cleaned version of the `values.yaml` (i.e. without comments or line breaks) you can run the following. - ```bash - helm show values kubevirt/redfish-controller --version 0.2.3 | sed 's/\s*#.*$//' | grep -v '^\s*$' - ``` + Edit `my-values.yaml` for your environment, including authentication, chassis namespaces, and the OpenShift route. Set `global.namespace` to the installation namespace if you change it. Choose an available container image tag in `global.image.tag` from the [container repository](https://quay.io/repository/kubevirt/redfish-controller?tab=tags); selecting a Git revision does not change the image tag automatically. -3. To save the `values.yaml` to your your local environment for direct editing, just redirect the output to a YAML file. - ```bash - helm show values kubevirt/redfish-controller --version 0.2.3 > my-values.yaml - ``` +3. Install the chart with your custom values. -4. You can also save the chart locally by issuing the following command. ```bash - # Download the Chart locally: - helm pull kubevirt/redfish-controller --version 0.2.3 - - # Explode the tar file: - tar -xzf kubevirt-redfish-0.2.3.tgz - - # Make a copy of the sample values.yaml manifest: - cp kubevirt-redfish/values.yaml my-values.yaml - ``` - -5. Now you can install the Chart using your own custom values.yaml: - ```bash - helm install kubevirt-redfish kubevirt/redfish-controller --version 0.2.3 \ + helm install kubevirt-redfish ./helm \ --namespace kubevirt-redfish \ --create-namespace \ -f my-values.yaml ``` -6. You can also ***optionally*** use inline edits during the `helm install` command. + You can also override values inline. Replace `` with your chosen container image tag: + ```bash - helm install kubevirt-redfish kubevirt/redfish-controller \ - --set image.tag=v0.2.3 \ - --set service.type=LoadBalancer \ + helm install kubevirt-redfish ./helm \ --namespace kubevirt-redfish \ - --create-namespace + --create-namespace \ + -f my-values.yaml \ + --set-string global.image.tag='' \ + --set service.type=LoadBalancer ``` +For upgrades, see the [chart upgrade instructions](helm/README.md#upgrading). + ### Verification You can verify the installation with the following commands. diff --git a/docs/README.md b/docs/README.md index aada8ec..7f34e21 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,28 +26,15 @@ This guide is intended to provide an end-to-end demonstration of an OpenShift `C 3. This will open a new web link to [mirror.openshift.com](https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest). You can select your version of Helm, unpack it, and move it to a location as defined in your `$PATH` (typically `/usr/local/bin` works). -### Add the Helm Repository +### Add the VM Helm Repository -1. Add the following Helm repository using the command below. This Charts repository is hosted via [GitHub pages](http://github.com/v1k0d3n/charts). +1. Add the following Helm repository for the separate `vms-on-ocpv` example chart used in Step 1. This repository is hosted via [GitHub Pages](https://github.com/v1k0d3n/charts). The controller itself will use the source chart in Step 2. ```bash helm repo add v1k0d3n https://v1k0d3n.github.io/charts helm repo update v1k0d3n ``` -2. Now you can view the versions of the Helm chart with the following command. Be aware of the `appVersion` tag and commit, which matches tags and commits within this GitHub repository (i.e. `v0.2.3-f87ff92`). - - ```bash - helm search repo v1k0d3n/kubevirt-redfish --versions - ``` - - Example: - ```bash - ❯ helm search repo v1k0d3n/kubevirt-redfish --versions - NAME CHART VERSION APP VERSION DESCRIPTION - v1k0d3n/kubevirt-redfish 0.2.3 v0.2.3-f87ff92 Custom kubevirt-redfish chart with enhanced fea... - ``` - ## Step 1: Install Virtual Machines (via Helm) 1. Using the `v1k0d3n` Helm repository, you will need to deploy the VMs using the sample Helm chart called `v1k0d3n/vms-on-ocpv`. To do this, create a custom values.yaml called `custom-values-vms.yaml` using the following command. @@ -79,18 +66,24 @@ This guide is intended to provide an end-to-end demonstration of an OpenShift `C ## Step 2: Install kubevirt-redfish (via Helm) -1. Again using the `v1k0d3n` Helm repository, you can deploy the `kubevirt-redfish` using the Helm chart called `v1k0d3n/kubevirt-redfish`. I ***am not** going to recommend downloading a custom `values.yaml` in this case, but instead I recommend you edit/use the [sample values file](./examples/custom-values-kubevirt-redfish.yaml). +1. Install the controller from this repository's chart, following the [source installation approach](../README.md#installation-quickstart-via-helm). The previously documented public controller chart endpoints are unavailable; see [issue #21](https://github.com/kubevirt/redfish-controller/issues/21). + + Clone the repository with Git and run all commands below from its root. If you already have a checkout, use that directory. Optionally select a specific Git revision with `git checkout `. ```bash - curl -L -o custom-values-kubevirt-redfish.yaml https://raw.githubusercontent.com/kubevirt/redfish-controller/refs/heads/main/docs/examples/custom-values-kubevirt-redfish.yaml + git clone https://github.com/kubevirt/redfish-controller.git + cd redfish-controller + cp docs/examples/custom-values-kubevirt-redfish.yaml custom-values-kubevirt-redfish.yaml ``` - **EXTREMELY IMPORTANT:** *This is a demonstration, so assuming that you're keeping the same namespace names (and all the other settings), than the only field you should have to edit is the `route.host` field (which is configured to be: `kubevirt-redfish-jinkit-kvm.apps.hub.lab.ocp.run`). You can change the `.` but if you've left all the other settings (as I recommended), then you can leave the other parts of the URL (i.e. `kubevirt-redfish-jinkit-kvm.apps.`). + Edit the [sample values file](./examples/custom-values-kubevirt-redfish.yaml) copy for your environment. Choose an available `global.image.tag` from the [container repository](https://quay.io/repository/kubevirt/redfish-controller?tab=tags); the sample's historical image tag may be unavailable. Keep `global.namespace: jinkit-kvm` for this demonstration. + + For this demonstration, set `route.host` to a hostname for your cluster. The example uses `kubevirt-redfish-jinkit-kvm.apps.hub.lab.ocp.run`; replace the cluster domain while keeping the namespace and other values consistent with the demonstration. 2. Once you have *minimally* configure/edit the `custom-values-kubevirt-redfish.yaml` file for your environment, you can install the chart by using the following command. ```bash - helm upgrade --install kubevirt-redfish v1k0d3n/kubevirt-redfish --version 0.2.3 -f custom-values-kubevirt-redfish.yaml -n jinkit-kvm + helm upgrade --install kubevirt-redfish ./helm -f custom-values-kubevirt-redfish.yaml -n jinkit-kvm ``` ## Step 3: Deploy OpenShift via ClusterInstance diff --git a/helm/README.md b/helm/README.md index 5540755..ea3865a 100644 --- a/helm/README.md +++ b/helm/README.md @@ -2,13 +2,6 @@ This Helm chart deploys the KubeVirt Redfish API server, which provides a Redfish-compliant REST API for managing KubeVirt virtual machines. The server enables integration with tools like Metal3/Ironic for bare metal provisioning workflows and Zero Touch Provisioning (ZTP) automation. -## Chart Version - -- **Chart Version**: 0.2.1-73abb30 -- **App Version**: v0.2.1 -- **Kubernetes**: 1.25+ -- **Helm**: 3.0+ - ## Prerequisites - Kubernetes 1.25+ or OpenShift 4.18+ @@ -18,27 +11,27 @@ This Helm chart deploys the KubeVirt Redfish API server, which provides a Redfis ## Quick Start -### Option 1: OCI Registry Deployment (Recommended) +### Install from Source + +The previously documented public chart endpoints, `https://kubevirt.github.io/charts` and `oci://quay.io/kubevirt/charts/redfish-controller`, are unavailable; see [issue #21](https://github.com/kubevirt/redfish-controller/issues/21). Use the chart in this repository instead. + +Clone the repository with Git and run the following commands from its root: ```bash -# Show available values -helm show values oci://quay.io/kubevirt/charts/redfish-controller --version 0.2.1 +git clone https://github.com/kubevirt/redfish-controller.git +cd redfish-controller +``` -# Install with default values -helm install kubevirt-redfish oci://quay.io/kubevirt/charts/redfish-controller \ - --version 0.2.1 \ - --namespace kubevirt-redfish \ - --create-namespace +The chart comes from your source checkout, rather than a published chart release. Optionally select a specific revision with `git checkout `. Inspect its metadata with `helm show chart ./helm`. -# Install with custom values -helm install kubevirt-redfish oci://quay.io/kubevirt/charts/redfish-controller \ - --version 0.2.1 \ - --namespace kubevirt-redfish \ - --create-namespace \ - -f my-values.yaml +Review and save the values before installing: + +```bash +helm show values ./helm +helm show values ./helm > my-values.yaml ``` -### Option 2: Local Chart Deployment +Edit `my-values.yaml` for your environment, including authentication, chassis namespaces, and the OpenShift route. Set `global.namespace` to your installation namespace. Choose an available `global.image.tag` from the [container repository](https://quay.io/repository/kubevirt/redfish-controller?tab=tags); changing the source revision does not select a matching container image automatically. ```bash # Install with default values @@ -90,7 +83,7 @@ helm install kubevirt-redfish ./helm \ | Parameter | Description | Default | Example | |-----------|-------------|---------|---------| | `global.namespace` | Deployment namespace | `"kubevirt-redfish"` | `"my-namespace"` | -| `global.image.tag` | Container image tag | `"v0.2.1"` | `"v0.2.1"` | +| `global.image.tag` | Container image tag | `"latest"` | An available tag from the container repository | | `deployment.replicas` | Number of replicas | `1` | `1` | | `route.host` | OpenShift route hostname | `"kubevirt-redfish-default.apps.clustername.example.com"` | `"kubevirt-redfish-default.apps.clustername.example.com"` | | `datavolume.storage_class` | Storage class for ISOs | `""` (default) | `"lvms-vg1"` | @@ -418,22 +411,17 @@ kubectl logs deployment/kubevirt-redfish -n your-namespace | grep -E "(virtual m ## Upgrading -```bash -# Upgrade with OCI registry -helm upgrade kubevirt-redfish oci://quay.io/kubevirt/charts/redfish-controller \ - --version 0.2.1 \ - --namespace kubevirt-redfish +Update your source checkout to the desired Git revision before upgrading, then run Helm from the repository root. Review changes to `helm/values.yaml` and update your custom values as needed, including `global.image.tag` for the container version you want to deploy. -# Upgrade with local chart -helm upgrade kubevirt-redfish ./helm \ - --namespace kubevirt-redfish - -# Upgrade with custom values +```bash +# Upgrade with your custom values helm upgrade kubevirt-redfish ./helm \ -f my-values.yaml \ --namespace kubevirt-redfish ``` +Use the same release name and namespace as your existing installation. If you installed with example values or another values file, pass that file instead. + ## Troubleshooting ### Common Issues