|Index|Deploying SUSE AI Factory with NVIDIA|How do I deploy SUSE AI Factory with NVIDIA?
Applies to SUSE AI Factory with NVIDIA

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.

  1. Identify the operator chart version number that you want to install. The latest version is 2.4.0.

  2. Review the aif-operator Helm chart values.

    > helm show values oci://ghcr.io/suse/chart/aif-operator \
      --version 2.4.0
  3. Install 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-namespace
  4. Verify 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.

Important
Important

You must have Rancher Prime Administrator privileges to perform this task.

  1. Add a new repository for SUSE AI Factory with NVIDIA.

    1. From the main left panel, select local › Apps › Repositories and click Create.

    2. Select OCI Repository and enter your preferred repository name, for example, suse-aif-operator.

    3. Enter oci://ghcr.io/suse/chart/aif-operator as an OCI repository URL.

    4. Leave None for authentication type and confirm with Create.

  2. Install the SUSE AI Operator application.

    1. Navigate to Apps › Charts and select the new suse-aif-operator filter in the left repository panel.

    2. Click Refresh all repositories and the aif-operator application tile appears.

    3. Click the application’s tile and then the Install this version button.

    4. Select the aif-operator namespace and specify name for the workload.

    5. To customize detailed installation options, activate Customize Helm options before install. Confirm with Next.

    6. Review or update the installation chart and install the application with the Install button in the bottom right. You can watch the installation progress in the newly opened log window.

    7. Verify that the application is listed in Apps › Installed Apps.

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.

Warning
Warning

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.

Tip
Tip

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

  1. 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.0
  2. Create the aif-values.yaml file and restrict its permissions so that only you can read and write to it:

    > touch aif-values.yaml && chmod 600 aif-values.yaml
  3. Copy 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: ""
  4. Provide the credentials to individual registries in the related username: and password: fields.

  5. 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

Important
Important

You must have Rancher Prime Administrator privileges to perform this task.

  1. 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?”.

  2. On the installation screen, activate Customize Helm options before install.

  3. 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: ""
  4. Continue the installation by clicking the Install 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-manager instance 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.

Important
Important: Limitations

Due to the complexity of Run:ai, blueprints currently do not support deploying either the Control Plane or the Cluster. Deploy them from the SUSE AI Factory › Apps 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.

  1. Retrieve the external IP address or host name of the Ingress controller service.

    > kubectl get service -n kube-system rke2-traefik
  2. In 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:

  1. Create a manifest file named cert-manager-deployment.yaml with 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: true
  2. Apply 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.

  1. Create a manifest file named cluster-issuer.yaml with the following content. Adjust the email field 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: traefik
    Note
    Note

    Alternatively, 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.

  2. 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.

Important
Important

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

  1. Create a manifest file named runai-control-plane-endpoint-cert.yaml with the following content. Replace the commonName and dnsNames fields 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"
  2. 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-backend

2.4.2.3 Install Run:ai Control Plane

  1. In the left navigation menu, select SUSE AI Factory › Apps.

  2. Select NVIDIA AI Library, search for run:ai, and select the application tile.

    Screenshot showing NVIDIA applications including Run:ai Control Plane
    Figure 2.1: Run:ai Control Plane application
  3. On the Basic Information screen, set both the Instance Name and Namespace fields to runai-backend.

  4. On the Target Cluster screen, set the Deployment Type to Helm. Do not use the default Fleet Bundle option.

  5. On the Configuration screen, 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>"
  6. Review the configuration and select Install. The installation takes several minutes to complete.

  7. 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.com and log in with the username tux@example.com and your configured password.

  8. On your first login, accept the NVIDIA user agreement and follow the setup wizard to create your first cluster.

  9. 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.

    Screenshot showing a command to install the Run:ai cluster
    Figure 2.2: Run:ai Cluster application
    Important
    Important

    Do 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 runai

2.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=runai

2.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.

  1. Create a file named prometheus-operator.yaml with 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-collection
  2. Apply the manifest file to install the Prometheus Operator.

    > kubectl apply -f prometheus-operator.yaml
Tip
Tip

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: false

2.4.3.5 Install Run:ai cluster

  1. In the left navigation menu, select SUSE AI Factory › Apps.

  2. Select NVIDIA AI Library, search for run:ai, and select the Run:ai (self-hosted) Cluster application tile.

  3. On the Basic Information screen, set the Namespace field to runai-backend. You can leave the Instance Name field with the default value runai-cluster.

  4. On the Target Cluster screen, set the Deployment Type to Helm. Do not use the default Fleet Bundle option.

  5. On the Configuration screen, override the default Helm values with your custom configuration. Use the values for controlPlane.url, controlPlane.clientSecret, cluster.uid, and cluster.url obtained 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: traefik
  6. Review the configuration and select Install.

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:

  1. In a web browser, log in to the Run:ai Control Plane UI.

  2. In the left navigation menu, select Resources › Clusters.

  3. 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.