2 How do I deploy SUSE AI Factory with NVIDIA? #
You can install SUSE AI Factory with NVIDIA on the Rancher Prime-enabled RKE2 Kubernetes cluster in the following ways:
on the command line by using the Helm command
using Rancher Prime UI
2.1 How do I install SUSE AI Factory with NVIDIA using the Helm CLI? #
To install SUSE AI Factory with NVIDIA on the command line using Helm, proceed as follows.
Identify the operator chart version number that you want to install. The latest version is 2.4.0.
Review the
aif-operatorHelm chart values.> helm show values oci://ghcr.io/suse/chart/aif-operator \ --version 2.4.0Install SUSE AI Factory Operator. The installation can take a few minutes.
> helm install aif-operator \ oci://ghcr.io/suse/chart/aif-operator:2.4.0 \ --namespace aif-operator \ --create-namespaceVerify that the operator is correctly installed and related pods running. The output should be similar to the following:
> kubectl get pods -A | grep aif aif-operator aif-operator-7bf464987-mnrw5 cattle-ui-plugin-system aif-ui-server-865c7fc84c-bmf7w
2.2 How do I install SUSE AI Factory with NVIDIA using Rancher? #
To deploy SUSE AI Factory with NVIDIA through the graphical interface, add the OCI repository and install the operator chart. This procedure walks you through setting up the repository endpoint and configuring the installation in the Rancher Prime UI.
You must have Rancher Prime Administrator privileges to perform this task.
Add a new repository for SUSE AI Factory with NVIDIA.
From the main left panel, select › › and click .
Select and enter your preferred repository name, for example,
suse-aif-operator.Enter
oci://ghcr.io/suse/chart/aif-operatoras an OCI repository URL.Leave
Nonefor authentication type and confirm with .
Install the
SUSE AI Operatorapplication.Navigate to › and select the new
suse-aif-operatorfilter in the left repository panel.Click and the
aif-operatorapplication tile appears.Click the application’s tile and then the button.
Select the
aif-operatornamespace and specify name for the workload.To customize detailed installation options, activate . Confirm with .
Review or update the installation chart and install the application with the button in the bottom right. You can watch the installation progress in the newly opened log window.
Verify that the application is listed in › .
2.3 Can I provide repository credentials during the SUSE AI Factory with NVIDIA installation? #
To access applications and blueprints from the SUSE Application Collection, SUSE Registry and NVIDIA AI Librarys, you need to provide valid credentials. By default, you can configure the credentials after the SUSE AI Factory with NVIDIA installation is complete as described in Chapter 4, Are there any post-deployment steps?.
However, you can specify the credentials during the SUSE AI Factory with NVIDIA installation process as well. The result is identical—specifying credentials during the installation creates the secrets and configure the settings in Rancher Prime.
Storing credentials in a plain-text values YAML file poses a security risk. Always restrict the file permissions of your custom values files to prevent unauthorized local access. Avoid passing passwords directly in command-line arguments to prevent them from being recorded in your shell history.
For production environments, we recommend using secure secrets-management tools, such as the helm-secrets plug-in with Mozilla SOPS, or the External Secrets Operator.
User names for specific registries are preconfigured:
SUSE Registry uses
regcode.NVIDIA AI Library uses
$oauthtoken.
2.3.1 Providing registry credentials during Helm CLI installation #
Download and display the default values for the SUSE AI Factory with NVIDIA installation.
> helm show values oci://ghcr.io/suse/chart/aif-operator --version 2.4.0Create the
aif-values.yamlfile and restrict its permissions so that only you can read and write to it:> touch aif-values.yaml && chmod 600 aif-values.yamlCopy the section that deals with registry credentials into the file, for example:
credentials: # credential for oci://dp.apps.rancher.io/charts applicationCollection: username: "" password: "" # credential to pull NGC artifacts # e.g. https://helm.ngc.nvidia.com/nvidia nvidia: username: "$oauthtoken" password: "" # credential for oci://registry.suse.com/ai/charts suseRegistry: username: "regcode" password: ""Provide the credentials to individual registries in the related
username:andpassword:fields.Save the file and install SUSE AI Factory with NVIDIA as described in Section 2.1, “How do I install SUSE AI Factory with NVIDIA using the Helm CLI?” by specifying the custom values file, for example:
> helm install aif-operator \ oci://ghcr.io/suse/chart/aif-operator:2.4.0 \ --namespace aif-operator \ --create-namespace \ -f aif-values.yaml
2.3.2 Providing registry credentials during installation in SUSE Rancher Prime #
You must have Rancher Prime Administrator privileges to perform this task.
Start the SUSE AI Factory with NVIDIA installation as described in Section 2.2, “How do I install SUSE AI Factory with NVIDIA using Rancher?”.
On the installation screen, activate .
Update the part of the installation chart that deals with registry credentials by providing credentials to individual registries.
credentials: # credential for oci://dp.apps.rancher.io/charts applicationCollection: username: "" password: "" # credential to pull NGC artifacts # e.g. https://helm.ngc.nvidia.com/nvidia nvidia: username: "$oauthtoken" password: "" # credential for oci://registry.suse.com/ai/charts suseRegistry: username: "regcode" password: ""Continue the installation by clicking the button in the bottom right.
2.4 How do I deploy Run:ai for GPU workload orchestration? #
Run:ai (Run:ai official documentation) is a graphics processing unit (GPU) orchestration and optimization platform designed to maximize compute resource use for artificial intelligence (AI) workloads in a Kubernetes environment. Installing Run:ai via SUSE AI Factory enables dynamic GPU resource allocation, efficient workload scheduling, and centralized cluster management.
2.4.1 Prerequisites #
DNS resolution and Ingress controller: The Run:ai Control Plane and cluster URLs must be fully qualified domain names (FQDNs) resolvable via public or private DNS. IP addresses are not supported. In a Kubernetes environment, you must configure a supported Ingress controller (such as traefik) and DNS records pointing to the Ingress IP address or host name. For more information about Ingress controller requirements, see the Run:ai Kubernetes Ingress Controller requirements.
TLS certificates: A configured
cert-managerinstance with a valid certificate authority (CA) or issuer is required. While Run:ai supports local or custom CAs, using Let’s Encrypt with an HTTP-01 or DNS-01 challenge solver simplifies certificate management.Prometheus Operator: Custom Resource Definitions (CRDs) and monitoring components provided by the Prometheus Operator are required for the Run:ai Cluster installation. You can deploy the Prometheus Operator from SUSE Application Collection (recommended) or install the upstream kube-prometheus-stack. The Control Plane does not require this stack.
Due to the complexity of Run:ai, blueprints currently do not support deploying either the Control Plane or the Cluster. Deploy them from the › catalog instead.
2.4.1.1 Configure DNS resolution for Ingress #
To allow external access to the Run:ai control plane, you must route your FQDNs to the Kubernetes cluster’s Ingress controller. RKE2 deploys the traefik Ingress Controller by default. For detailed information on supported Ingress controllers, see the Run:ai Kubernetes Ingress Controller requirements.
Retrieve the external IP address or host name of the Ingress controller service.
> kubectl get service -n kube-system rke2-traefikIn your DNS provider’s management console, create a DNS record (A or CNAME) pointing your FQDN (for example,
runai-control-plane.exampleclouddev.com) to the retrieved IP address or host name.
2.4.1.2 Install cert-manager (optional) #
If cert-manager is not yet installed, install it from SUSE Application Collection using the following steps:
Create a manifest file named
cert-manager-deployment.yamlwith the following content. Adjust the credentials to match your environment.--- apiVersion: v1 kind: Namespace metadata: name: cert-manager --- apiVersion: v1 data: .dockerconfigjson: "<YOUR_ENCODED_APPCO_CREDENTIAL_HERE>" kind: Secret metadata: name: application-collection namespace: cert-manager type: kubernetes.io/dockerconfigjson --- apiVersion: v1 data: .dockerconfigjson: "<YOUR_ENCODED_APPCO_CREDENTIAL_HERE>" kind: Secret metadata: name: application-collection namespace: kube-system type: kubernetes.io/dockerconfigjson --- apiVersion: helm.cattle.io/v1 kind: HelmChart metadata: name: cert-manager namespace: kube-system spec: chart: oci://dp.apps.rancher.io/charts/cert-manager version: "1.20.0" targetNamespace: cert-manager dockerRegistrySecret: name: application-collection valuesContent: |- global: imagePullSecrets: - application-collection crds: enabled: trueApply the manifest file to install cert-manager.
> kubectl apply -f cert-manager-deployment.yaml
2.4.1.3 Create a ClusterIssuer #
Create a ClusterIssuer to issue TLS certificates for the Run:ai endpoints. The following example configures Let’s Encrypt using an HTTP-01 challenge solver with traefik Ingress.
Create a manifest file named
cluster-issuer.yamlwith the following content. Adjust theemailfield to match your email address.--- apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: suse-ai-cluster-issuer spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: "tux@example.com" privateKeySecretRef: name: suse-ai-letsencrypt-key solvers: - http01: ingress: ingressClassName: traefikNoteAlternatively, you can use a DNS-01 challenge solver (for example, with Cloudflare or AWS Route 53) by supplying your DNS provider credentials, or use an internal enterprise Certificate Authority.
Apply the manifest file to create the ClusterIssuer.
> kubectl apply -f cluster-issuer.yaml
2.4.2 Install Run:ai Control Plane #
Determine a unique fully qualified domain name (FQDN) from your domain for the Run:ai Control Plane UI and API endpoint.
For example, if your domain is exampleclouddev.com, use an FQDN such as runai-control-plane.exampleclouddev.com.
Because the Run:ai Helm chart hardcodes the service URLs, both the Helm release name and the namespace for the Run:ai Control Plane must be runai-backend.
2.4.2.1 Create the Control Plane endpoint certificate #
Create a manifest file named
runai-control-plane-endpoint-cert.yamlwith the following content. Replace thecommonNameanddnsNamesfields with your own Run:ai endpoint URL.--- apiVersion: v1 kind: Namespace metadata: name: runai-backend --- apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: runai-tls namespace: runai-backend spec: commonName: "runai-control-plane.exampleclouddev.com" secretName: runai-tls-cert privateKey: rotationPolicy: Always issuerRef: name: suse-ai-cluster-issuer kind: ClusterIssuer dnsNames: - "runai-control-plane.exampleclouddev.com"Apply the manifest file to create the certificate.
> kubectl apply -f runai-control-plane-endpoint-cert.yaml
2.4.2.2 Create the runai-reg-creds secret #
Run:ai images are hosted in the secure nvcr.io registry.
For SUSE AI Factory with NVIDIA with NVIDIA, the required NVIDIA registry service key is already provided in SUSE Customer Center under your subscription details, so no separate NVIDIA AI Enterprise license purchase is required.
> kubectl create secret docker-registry runai-reg-creds \
--docker-server=nvcr.io \
--docker-username='$oauthtoken' \
--docker-password="<SERVICE_KEY>" \
--namespace=runai-backend2.4.2.3 Install Run:ai Control Plane #
In the left navigation menu, select › .
Select , search for
run:ai, and select the application tile.Figure 2.1: Run:ai Control Plane application #On the
Basic Informationscreen, set both theInstance NameandNamespacefields torunai-backend.On the
Target Clusterscreen, set theDeployment TypetoHelm. Do not use the defaultFleet Bundleoption.On the
Configurationscreen, override the default Helm values with your custom configuration, for example:global: domain: "runai-control-plane.exampleclouddev.com" ingress: ingressClass: traefik tlsSecretName: runai-tls-cert tenantsManager: config: adminUsername: "tux@example.com" adminPassword: "<PASSWORD>"Review the configuration and select . The installation takes several minutes to complete.
Once the deployment is complete, open a web browser, navigate to the Run:ai UI endpoint, and log in with the credentials specified in your Helm values. For example, navigate to
https://runai-control-plane.exampleclouddev.comand log in with the usernametux@example.comand your configured password.On your first login, accept the NVIDIA user agreement and follow the setup wizard to create your first cluster.
The Run:ai Cluster can be installed on the same Kubernetes cluster as the Control Plane. If you choose this option, the Cluster URL is identical to the Control Plane URL. Copy and save the installation instructions displayed on the screen.
Figure 2.2: Run:ai Cluster application #ImportantDo not run the installation commands displayed in the wizard. The Run:ai Cluster must be deployed using SUSE AI Factory instead. Record the following values from the wizard setup screen:
Control Plane URL
Control Plane Client Secret
Cluster UID
Cluster URL
Other wizard steps, such as setting up SAML (Security Assertion Markup Language) authentication or creating teams, are optional and can be configured later.
2.4.3 Install Run:ai Cluster #
2.4.3.1 Prerequisites #
Before installing the Run:ai Cluster, you must deploy the Run:ai Control Plane (see Section 2.4.2.3, “Install Run:ai Control Plane”) and create your cluster.
Obtain the following information from the Control Plane:
Control Plane URL
Control Plane Client Secret
Cluster UID
Cluster URL
2.4.3.2 Create the runai namespace #
The Run:ai Cluster must be installed in the runai namespace.
> kubectl create namespace runai2.4.3.3 Create the runai-reg-creds secret #
Run:ai images are hosted in the secure nvcr.io registry.
Create the runai-reg-creds secret in the runai namespace using the NVIDIA service key obtained from SUSE Customer Center to pull the images.
> kubectl create secret docker-registry runai-reg-creds \
--docker-server=nvcr.io \
--docker-username='$oauthtoken' \
--docker-password="<SERVICE_KEY>" \
--namespace=runai2.4.3.4 Install Prometheus Operator #
The Run:ai Cluster requires Custom Resource Definitions (CRDs) and monitoring components provided by the Prometheus Operator. SUSE recommends installing the Prometheus Operator from SUSE Application Collection. Alternatively, you can deploy the upstream Prometheus community stack.
Create a file named
prometheus-operator.yamlwith the following content. Adjust the credentials to match your environment.--- apiVersion: v1 kind: Namespace metadata: name: monitoring --- *apiVersion*: v1 data: .dockerconfigjson: "<YOUR_ENCODED_APPCO_CREDENTIAL_HERE>" kind: Secret metadata: name: application-collection namespace: monitoring type: kubernetes.io/dockerconfigjson --- apiVersion: v1 data: .dockerconfigjson: "<YOUR_ENCODED_APPCO_CREDENTIAL_HERE>" kind: Secret metadata: name: application-collection namespace: kube-system type: kubernetes.io/dockerconfigjson --- apiVersion: helm.cattle.io/v1 kind: HelmChart metadata: name: prometheus-operator namespace: kube-system spec: chart: oci://dp.apps.rancher.io/charts/prometheus-operator targetNamespace: monitoring dockerRegistrySecret: name: application-collection valuesContent: |- global: imagePullSecrets: - application-collectionApply the manifest file to install the Prometheus Operator.
> kubectl apply -f prometheus-operator.yaml
If you prefer to deploy the upstream kube-prometheus-stack instead of the SUSE Application Collection chart, you can use the following HelmChart manifest:
---
apiVersion: v1
kind: Namespace
metadata:
name: monitoring
---
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
name: prometheus
namespace: kube-system
spec:
repo: https://prometheus-community.github.io/helm-charts
chart: kube-prometheus-stack
version: "87.19.1"
targetNamespace: monitoring
valuesContent: |-
grafana:
enabled: false2.4.3.5 Install Run:ai cluster #
In the left navigation menu, select › .
Select , search for
run:ai, and select theRun:ai (self-hosted) Clusterapplication tile.On the
Basic Informationscreen, set theNamespacefield torunai-backend. You can leave theInstance Namefield with the default valuerunai-cluster.On the
Target Clusterscreen, set theDeployment TypetoHelm. Do not use the defaultFleet Bundleoption.On the
Configurationscreen, override the default Helm values with your custom configuration. Use the values forcontrolPlane.url,controlPlane.clientSecret,cluster.uid, andcluster.urlobtained in the previous step.controlPlane: url: "runai-control-plane.exampleclouddev.com" clientSecret: "<SECRET_KEY>" cluster: uid: "b735bbc6-a26e-477e-8e83-5a78156bee00" url: "https://runai-control-plane.exampleclouddev.com" clusterConfig: global: ingress: ingressClass: traefikReview the configuration and select .
2.4.4 Verify installation #
After the Run:ai Cluster installation is complete, verify that the cluster is connected to the Run:ai Control Plane:
In a web browser, log in to the Run:ai Control Plane UI.
In the left navigation menu, select › .
In the Clusters table, verify that your cluster is listed and its status is displayed as Connected.
For more information about cluster status indicators and cluster management, see the Run:ai Clusters documentation.

