Deploying Red Hat AI Inference Server in OpenShift Container Platform
Deploy Red Hat AI Inference Server in OpenShift Container Platform clusters that have supported AI accelerators installed
Abstract
Chapter 1. About OpenShift Container Platform deployments Copy linkLink copied to clipboard!
You can deploy Red Hat AI Inference Server in OpenShift Container Platform clusters with supported AI accelerators that have full access to the internet.
Install the NVIDIA GPU Operator or AMD GPU Operator as appropriate for the underlying host AI accelerators that are available in the cluster.
Deploying Red Hat AI Inference Server in OpenShift Container Platform requires installing the Node Feature Discovery (NFD) Operator to detect hardware capabilities, then installing the appropriate GPU operator for your accelerator hardware. After the operators are configured, you can deploy inference workloads using Red Hat AI Inference Server container images.
Chapter 2. Installing the Node Feature Discovery Operator Copy linkLink copied to clipboard!
Install the Node Feature Discovery Operator so that the cluster can use the AI accelerators that are available in the cluster.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges.
Procedure
Create the
NamespaceCR for the Node Feature Discovery Operator:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
OperatorGroupCR:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
SubscriptionCR:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification
Verify that the Node Feature Discovery Operator deployment is successful by running the following command:
oc get pods -n openshift-nfd
$ oc get pods -n openshift-nfd
Example output
NAME READY STATUS RESTARTS AGE nfd-controller-manager-7f86ccfb58-vgr4x 2/2 Running 0 10m
NAME READY STATUS RESTARTS AGE
nfd-controller-manager-7f86ccfb58-vgr4x 2/2 Running 0 10m
Chapter 3. Installing the NVIDIA GPU Operator Copy linkLink copied to clipboard!
Install the NVIDIA GPU Operator to use the underlying NVIDIA CUDA AI accelerators that are available in the cluster.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. - You have installed the Node Feature Discovery Operator.
Procedure
Create the
NamespaceCR for the NVIDIA GPU Operator:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
OperatorGroupCR:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
SubscriptionCR:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification
Verify that the NVIDIA GPU Operator deployment is successful by running the following command:
oc get pods -n nvidia-gpu-operator
$ oc get pods -n nvidia-gpu-operator
Example output
Chapter 4. Installing the AMD GPU Operator Copy linkLink copied to clipboard!
Install the AMD GPU Operator to use the underlying AMD ROCm AI accelerators that are available in the cluster.
Installing the AMD GPU Operator is a multi-step procedure that requires installing the Node Feature Discovery Operator, the Kernel Module Management Operator (KMM), and then the AMD GPU Operator through the OpenShift OperatorHub.
The AMD GPU Operator is only supported in clusters with full access to the internet, not in disconnected environments. This is because the Operator builds the driver inside the cluster which requires full internet access.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. You have installed the following Operators in the cluster:
Expand Table 4.1. Required Operators Operator Description Service CA Operator
Issues TLS serving certificates for Service objects. Required for certificate signing and authentication between the
kube-apiserverand the KMM webhook server.Operator Lifecycle Manager (OLM)
Manages Operator installation and lifecycle maintenance.
Machine Config Operator
Manages the operating system configuration of worker and control-plane nodes. Required for configuring the kernel blacklist for the amdgpu driver.
Cluster Image Registry Operator
The Cluster Image Registry Operator (CIRO) manages the internal container image registry that OpenShift Container Platform clusters use to store and serve container images. Required for driver image building and storage in the cluster.
Procedure
Create the
NamespaceCR for the AMD GPU Operator Operator:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the Service CA Operator is operational. Run the following command:
oc get pods -A | grep service-ca
$ oc get pods -A | grep service-caCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
openshift-service-ca-operator service-ca-operator-7cfd997ddf-llhdg 1/1 Running 7 35d openshift-service-ca service-ca-8675b766d5-vz8gg 1/1 Running 6 35d
openshift-service-ca-operator service-ca-operator-7cfd997ddf-llhdg 1/1 Running 7 35d openshift-service-ca service-ca-8675b766d5-vz8gg 1/1 Running 6 35dCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the Machine Config Operator is operational:
oc get pods -A | grep machine-config-daemon
$ oc get pods -A | grep machine-config-daemonCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
openshift-machine-config-operator machine-config-daemon-sdsjj 2/2 Running 10 35d openshift-machine-config-operator machine-config-daemon-xc6rm 2/2 Running 0 2d21h
openshift-machine-config-operator machine-config-daemon-sdsjj 2/2 Running 10 35d openshift-machine-config-operator machine-config-daemon-xc6rm 2/2 Running 0 2d21hCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the Cluster Image Registry Operator is operational:
oc get pods -n openshift-image-registry
$ oc get pods -n openshift-image-registryCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: If you plan to build driver images in the cluster, you must enable the OpenShift internal registry. Run the following commands:
Verify current registry status:
oc get pods -n openshift-image-registry
$ oc get pods -n openshift-image-registryCopy to Clipboard Copied! Toggle word wrap Toggle overflow NAME READY STATUS RESTARTS AGE #... image-registry-7b67584cd-sdxpk 1/1 Running 10 36d
NAME READY STATUS RESTARTS AGE #... image-registry-7b67584cd-sdxpk 1/1 Running 10 36dCopy to Clipboard Copied! Toggle word wrap Toggle overflow Configure the registry storage. The following example patches an
emptyDirephemeral volume in the cluster. Run the following command:oc patch configs.imageregistry.operator.openshift.io cluster --type merge \ --patch '{"spec":{"storage":{"emptyDir":{}}}}'$ oc patch configs.imageregistry.operator.openshift.io cluster --type merge \ --patch '{"spec":{"storage":{"emptyDir":{}}}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the registry:
oc patch configs.imageregistry.operator.openshift.io cluster --type merge \ --patch '{"spec":{"managementState":"Managed"}}'$ oc patch configs.imageregistry.operator.openshift.io cluster --type merge \ --patch '{"spec":{"managementState":"Managed"}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow
- Install the Node Feature Discovery (NFD) Operator. See Installing the Node Feature Discovery Operator.
- Install the Kernel Module Management (KMM) Operator. See Installing the Kernel Module Management Operator.
Configure node feature discovery for the AMD AI accelerator:
Create a
NodeFeatureDiscovery(NFD) custom resource (CR) to detect AMD GPU hardware. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteDepending on your specific cluster deployment, you might require a
NodeFeatureDiscoveryorNodeFeatureRuleCR. For example, the cluster might already have theNodeFeatureDiscoveryresource deployed and you don’t want to change it. For more information, see Create Node Feature Discovery Rule.
Create a
MachineConfigCR to add the out-of-treeamdgpukernel module to the modprobe blacklist. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Where:
machineconfiguration.openshift.io/role: worker-
Specifies the node role for the machine configuration. Set this value to
masterfor single-node OpenShift clusters.
ImportantThe Machine Config Operator automatically reboots selected nodes after you apply the
MachineConfigCR.Create the
DeviceConfigCR to start the AMD AI accelerator driver installation. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Where:
image: image-registry.openshift-image-registry.svc:5000/$MOD_NAMESPACE/amdgpu_kmod- Specifies the driver image location. By default, you do not need to configure a value for this field because the default value is used.
After you apply the
DeviceConfigCR, the AMD GPU Operator collects the worker node system specifications, builds or retrieve the appropriate driver image, uses KMM to deploy the driver, and finally deploys the ROCM device plugin and node labeller.
Verification
Verify that the KMM worker pods are running:
oc get pods -n openshift-kmm
$ oc get pods -n openshift-kmmCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
NAME READY STATUS RESTARTS AGE kmm-operator-controller-774c7ccff6-hr76v 1/1 Running 30 (2d23h ago) 35d kmm-operator-webhook-76d7b9555-ltmps 1/1 Running 5 35d
NAME READY STATUS RESTARTS AGE kmm-operator-controller-774c7ccff6-hr76v 1/1 Running 30 (2d23h ago) 35d kmm-operator-webhook-76d7b9555-ltmps 1/1 Running 5 35dCopy to Clipboard Copied! Toggle word wrap Toggle overflow Check device plugin and labeller status:
oc -n openshift-amd-gpu get pods
$ oc -n openshift-amd-gpu get podsCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
NAME READY STATUS RESTARTS AGE amd-gpu-operator-controller-manager-59dd964777-zw4bg 1/1 Running 8 (2d23h ago) 9d test-deviceconfig-device-plugin-kbrp7 1/1 Running 0 2d test-deviceconfig-metrics-exporter-k5v4x 1/1 Running 0 2d test-deviceconfig-node-labeller-fqz7x 1/1 Running 0 2d
NAME READY STATUS RESTARTS AGE amd-gpu-operator-controller-manager-59dd964777-zw4bg 1/1 Running 8 (2d23h ago) 9d test-deviceconfig-device-plugin-kbrp7 1/1 Running 0 2d test-deviceconfig-metrics-exporter-k5v4x 1/1 Running 0 2d test-deviceconfig-node-labeller-fqz7x 1/1 Running 0 2dCopy to Clipboard Copied! Toggle word wrap Toggle overflow Confirm that GPU resource labels are applied to the nodes:
oc get node -o json | grep amd.com
$ oc get node -o json | grep amd.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 5. Deploying Red Hat AI Inference Server and inference serving the model Copy linkLink copied to clipboard!
Deploy a language model with OpenShift Container Platform by configuring secrets, persistent storage, and a deployment custom resource (CR) that pulls the model from Hugging Face and uses Red Hat AI Inference Server to inference serve the model.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. - You have installed NFD and the required GPU Operator for your underlying AI accelerator hardware.
Procedure
Create the
Secretcustom resource (CR) for the Hugging Face token. The cluster uses theSecretCR to pull models from Hugging Face.Set the
HF_TOKENvariable using the token you set in Hugging Face.HF_TOKEN=<your_huggingface_token>
$ HF_TOKEN=<your_huggingface_token>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set the cluster namespace to match where you deployed the Red Hat AI Inference Server image, for example:
NAMESPACE=rhaiis-namespace
$ NAMESPACE=rhaiis-namespaceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
SecretCR in the cluster:oc create secret generic hf-secret --from-literal=HF_TOKEN=$HF_TOKEN -n $NAMESPACE
$ oc create secret generic hf-secret --from-literal=HF_TOKEN=$HF_TOKEN -n $NAMESPACECopy to Clipboard Copied! Toggle word wrap Toggle overflow
Create the Docker secret so that the cluster can download the Red Hat AI Inference Server image from the container registry. For example, to create a
SecretCR that contains the contents of your local~/.docker/config.jsonfile, run the following command:oc create secret generic docker-secret --from-file=.dockercfg=$HOME/.docker/config.json --type=kubernetes.io/dockercfg -n rhaiis-namespace
oc create secret generic docker-secret --from-file=.dockercfg=$HOME/.docker/config.json --type=kubernetes.io/dockercfg -n rhaiis-namespaceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a
PersistentVolumeClaim(PVC) custom resource (CR) and apply it in the cluster. The following examplePVCCR uses a default IBM VPC Block persistence volume. You use thePVCas the location where you store the models that you download.Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteConfiguring cluster storage to meet your requirements is outside the scope of this procedure. For more detailed information, see Configuring persistent storage.
Create a
Deploymentcustom resource (CR) that pulls the model from Hugging Face and deploys the Red Hat AI Inference Server container. Reference the following exampleDeploymentCR, which uses AI Inference Server to serve a Granite model on a CUDA accelerator.Copy to Clipboard Copied! Toggle word wrap Toggle overflow +
Where:
namespace: rhaiis-namespace-
Specifies the deployment namespace. The value of
metadata.namespacemust match the namespace where you configured the Hugging FaceSecretCR. claimName: model-cache-
Specifies the persistent volume claim name. The value of
spec.template.spec.volumes.persistentVolumeClaim.claimNamemust match the name of thePVCthat you created. initContainers:- Defines a container that runs before the main application container to download the required model from Hugging Face. The model pull step is skipped if the model directory has already been populated, for example, from a previous deployment.
mountPath: /dev/shm- Mounts the shared memory volume required by the NVIDIA Collective Communications Library (NCCL). Tensor parallel vLLM deployments fail without this volume mount.
Increase the deployment replica count to the required number. For example, run the following command:
oc scale deployment granite -n rhaiis-namespace --replicas=1
oc scale deployment granite -n rhaiis-namespace --replicas=1Copy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Watch the deployment and ensure that it succeeds:
oc get deployment -n rhaiis-namespace --watch
$ oc get deployment -n rhaiis-namespace --watchCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
NAME READY UP-TO-DATE AVAILABLE AGE granite 0/1 1 0 2s granite 1/1 1 1 14s
NAME READY UP-TO-DATE AVAILABLE AGE granite 0/1 1 0 2s granite 1/1 1 1 14sCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Create a
ServiceCR for the model inference. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Create a
RouteCR to enable public access to the model. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Get the URL for the exposed route. Run the following command:
oc get route granite -n rhaiis-namespace -o jsonpath='{.spec.host}'$ oc get route granite -n rhaiis-namespace -o jsonpath='{.spec.host}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output
granite-rhaiis-namespace.apps.example.com
granite-rhaiis-namespace.apps.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification
Ensure that the deployment is successful by querying the model. Run the following command:
Chapter 6. Deploying Red Hat AI Inference Server on IBM Z with IBM Spyre accelerators Copy linkLink copied to clipboard!
Deploy a language model on OpenShift Container Platform running on IBM Z with IBM Spyre AI accelerators. You configure secrets, persistent storage, and a deployment custom resource (CR) that pulls the model from Hugging Face and uses Red Hat AI Inference Server to inference serve the model.
For more information about installing the Spyre Operator, see the Spyre Operator for Z and LinuxONE User’s Guide.
Prerequisites
-
You have installed the OpenShift CLI (
oc). -
You have logged in as a user with
cluster-adminprivileges. - Your cluster deployed on IBM Z has worker nodes with IBM Spyre AI accelerators installed.
- You have installed the IBM Spyre Operator in the cluster. For more information, see Installing the Spyre Operator.
- You have a Hugging Face account and have generated a Hugging Face access token.
-
You have access to
registry.redhat.ioand the cluster can pull images from this registry.
IBM Spyre AI accelerator cards support FP16 format model weights only. For compatible models, the Red Hat AI Inference Server inference engine automatically converts weights to FP16 at startup. No additional configuration is needed.
Procedure
Create the
Secretcustom resource (CR) for the Hugging Face token. The cluster uses theSecretCR to pull models from Hugging Face.Set the
HF_TOKENvariable using the token you set in Hugging Face:HF_TOKEN=<your_huggingface_token>
$ HF_TOKEN=<your_huggingface_token>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set the cluster namespace to match where you deployed the Red Hat AI Inference Server image, for example:
NAMESPACE=rhaiis-namespace
$ NAMESPACE=rhaiis-namespaceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
SecretCR in the cluster:oc create secret generic hf-secret --from-literal=HF_TOKEN=$HF_TOKEN -n $NAMESPACE
$ oc create secret generic hf-secret --from-literal=HF_TOKEN=$HF_TOKEN -n $NAMESPACECopy to Clipboard Copied! Toggle word wrap Toggle overflow
Create the Docker secret so that the cluster can download the Red Hat AI Inference Server image from the container registry. For example, to create a
SecretCR that contains the contents of your local~/.docker/config.jsonfile, run the following command:oc create secret generic docker-secret --from-file=.dockercfg=$HOME/.docker/config.json --type=kubernetes.io/dockercfg -n rhaiis-namespace
$ oc create secret generic docker-secret --from-file=.dockercfg=$HOME/.docker/config.json --type=kubernetes.io/dockercfg -n rhaiis-namespaceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a
PersistentVolumeClaim(PVC) custom resource (CR) and apply it in the cluster. The following examplePVCCR uses a default IBM VPC Block persistence volume. You use thePVCas the location where you store the models that you download.Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteConfiguring cluster storage to meet your requirements is outside the scope of this procedure. For more detailed information, see Configuring persistent storage.
Create a
Deploymentcustom resource (CR) that pulls the model from Hugging Face and deploys the Red Hat AI Inference Server container. Reference the following exampleDeploymentCR, which uses AI Inference Server to serve a Granite model with IBM Spyre AI accelerators.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Where:
namespace: rhaiis-namespace-
Specifies the deployment namespace. The value of
metadata.namespacemust match the namespace where you configured the Hugging FaceSecretCR. claimName: model-cache-
Specifies the persistent volume claim name. The value of
spec.template.spec.volumes.persistentVolumeClaim.claimNamemust match the name of thePVCthat you created. initContainers-
Defines a container that runs before the main application container to download the required model from Hugging Face by using the
huggingface_hubPython library. The model download step is skipped if the model directory has already been populated, for example, from a previous deployment. FLEX_DEVICE-
Specifies the device type for IBM Spyre accelerators. Set to
VFfor virtual function mode. TOKENIZERS_PARALLELISM- Disables tokenizer parallelism to prevent resource conflicts.
VLLM_SPYRE_USE_CB- Enables continuous batching for improved throughput on IBM Spyre accelerators.
VLLM_SPYRE_REQUIRE_PRECOMPILED_DECODERS- Requires precompiled decoders for optimal performance on Spyre accelerators.
TORCH_SENDNN_CACHE_ENABLE- Enables caching for the SendNN backend to improve model loading times.
ibm.com/spyre_vf- Requests IBM Spyre virtual function devices from the cluster. The number specifies how many Spyre AI accelerator devices to allocate.
mountPath: /dev/shm- Mounts the shared memory volume required for tensor parallel inference across multiple Spyre accelerators.
Increase the deployment replica count to the required number.
oc scale deployment granite-spyre -n rhaiis-namespace --replicas=1
$ oc scale deployment granite-spyre -n rhaiis-namespace --replicas=1Copy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Watch the deployment and ensure that it succeeds, for example:
oc get deployment -n rhaiis-namespace --watch
$ oc get deployment -n rhaiis-namespace --watchCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example output:
NAME READY UP-TO-DATE AVAILABLE AGE granite-spyre 0/1 1 0 2s granite-spyre 1/1 1 1 5m
NAME READY UP-TO-DATE AVAILABLE AGE granite-spyre 0/1 1 0 2s granite-spyre 1/1 1 1 5mCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a
ServiceCR for the model inference. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Notespec.selector.appmust match the label in yourDeploymentpod.Optional: Create a
RouteCR to enable public access to the model with TLS encryption. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Get the URL for the exposed route. Run the following command:
oc get route granite-spyre -n rhaiis-namespace -o jsonpath='{.spec.host}'$ oc get route granite-spyre -n rhaiis-namespace -o jsonpath='{.spec.host}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output:
granite-spyre-rhaiis-namespace.apps.example.com
granite-spyre-rhaiis-namespace.apps.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification
Ensure that the deployment is successful by querying the model. Run the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example output:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow