Plan Your Kubernetes Installation or Upgrade

You use the XL CLI's xl kube command to install or upgrade Digital.ai Deploy. For more information, see XL Kube Command Reference.

important

It is highly recommended to review the xl kube workshop for a comprehensive understanding of installing or upgrading Digital.ai Deploy on a Kubernetes cluster and its benefits.

The xl kube command acts as an installation options reference, prompting you for values that it cannot determine on its own and providing reasonable default values for the remaining parameters. In other words, installing Digital.ai Deploy can be as simple as running the xl kube install or xl kube upgrade commands and answering a set of questions asked by the installation options reference along the way.

However, you must gather and keep certain information handy to answer the questions in the installation options reference.

In addition, you must set up your Kubernetes cluster, install and configure the required Kubernetes CLI tools such as the kubectl, AWS CLI, Openshift CLI, gCloud CLI, and Azure CLI depending on the cloud platform you use.

You must also factor in things like using existing PostgreSQL and RabbitMQ servers—and if yes—gather and keep all the required information handy before you start installing or upgrading Digital.ai Deploy.

Supported Cloud Platforms to Install Digital.ai Deploy

You can install Digital.ai Deploy on the following platforms:

• Plain Multi-node Kubernetes Cluster On-premise versions 1.35

  note

  You can install Deploy in both online and air-gapped modes. See Install Deploy or Release—On-premise Kubernetes for more information.

• OpenShift on AWS

• OpenShiftCertified

• Amazon EKS

• Google GKE

• Azure AKS

  note

  Deploy installation is supported on any flavor of Openshift that meets the following criteria:

  • Kubernetes server versions 1.35
  • Storage class supports RWO mode.

Docker Image Tags for Deploy

The xl kube install and xl kube upgrade options reference let you go with the default (latest) docker image tags available when you install or upgrade Digital.ai Deploy . However, here are the Docker Hub links to verify all the available image tags.

• Digital.ai Deploy Operator Image
• Digital.ai Deploy Image
• Digital.ai Deploy Task Engine Image
• Digital.ai Deploy Central Configuration Image

note

• For third-party images, such as those from Bitnami for Ingress, PostgreSQL, or RabbitMQ, you may use the latest supported versions instead of the default ones, as they may have fewer vulnerabilities. However, it is recommended to use the default image tags suggested during installation. Using the default image versions for each installation ensures compatibility and helps prevent issues during upgrades.
• The PostgreSQL database provided with the Bitnami Helm chart is upgraded to version 17.6.
• Deprecation Notice: Starting with Deploy 25.3, Bitnami Helm charts are deprecated and will be completely removed from installation options in later versions. This affects Kubernetes Operator installations that rely on Bitnami-provided PostgreSQL and other services. All installations that depend on the Bitnami Helm charts will remain available through Deploy 25.3, but without image patch upgrades. It is recommended to plan for the migration to external databases or alternative deployment methods for production environments before upgrading. See Bitnami Secure Images Breaking Changes for Kubernetes Operator.

Image Registry Configuration

important

During installation, it is critical to provide accurate image registry details. Default values in the installation manifests may not always be correct or accessible in your environment.

Multi-Registry Requirements

Required images for Digital.ai Deploy are distributed across multiple container registries:

• gcr.io - Google Container Registry (kube-rbac-proxy and other Kubernetes components)
• docker.io - Docker Hub (Deploy images and various third-party images)
• quay.io - Red Hat Quay (operator images)

Ensure your environment has access to all required registries, or configure a local mirror/proxy registry.

Prerequisites for Registry Access

Before installation, verify:

1. Network access to all required registries
2. Authentication credentials (if using private registries)
3. Image pull secrets configured in your cluster (if required)
4. Firewall rules allow access to external registries

Configuring Custom Registry Images

If you need to use a private or mirror registry, you configure the image registry through the Custom Resource (CR) during installation using the xl kube install command. The installer will prompt you to select the type of image registry and provide the necessary details.

For detailed instructions on setting up and using a custom image registry, see Setup Custom Image Registry.

Creating Image Pull Secrets

If your registry requires authentication, create an image pull secret:

kubectl create secret docker-registry regcred \
  --docker-server=my-registry.example.com \
  --docker-username=myuser \
  --docker-password=mypassword \
  --docker-email=myemail@example.com \
  --namespace=digitalai

For air-gapped or restricted environments, see Install or Upgrade Deploy on an Air-gapped Environment for more information.

Deploy and Server Replicas

• For Deploy, you must estimate the number of master and worker replicas required.

The Kubernetes Cluster

The process of setting up a Kubernetes cluster and the tools required for the same varies from one platform to the other. However, there are certain things that you must think through before setting up a Kubernetes cluster in general.

Let us discuss some of those common aspects of setting up your Kubernetes cluster.

Nodes and Pods in the Kubernetes Cluster

You must plan and estimate the number of nodes in the cluster, and the number of pods and services you may want to run. You must plan the sizing of the pods resources, for the Deploy:

• Deploy Server Hardware Requirements

Kubernetes Namespace

important

For operator installation on various Kubernetes platforms, there is a limitation regarding the length of the namespace (or project). This limitation is based on the fact that custom namespaces play a crucial role in naming all resources created within the cluster. To ensure uniqueness across cluster resources generated by the operator, a maximum namespace length of 13 characters is supported. However, for OpenShift installations, the maximum namespace length is 9 characters.

• You need a namespace to install Digital.ai Deploy, on.
• By default, Digital.ai Deploy, are installed in the default namespace — digitalai.
• However, you can choose to create and install Deploy, in a custom namespace.

Ingress Controller

• The Ingress Controller to use for generic cloud providers such as Amazon EKS, Azure AKS, and Google GKE.
• The following ingress controllers are supported:
  • ingress-nginx-controller [Ingress NGINX controller (experimental/non-production)]. See Experimental Support for External Operators.
  • nginx [NGINX Ingress Bitnami Helm Chart (deprecated)].
  • haproxy [HAProxy Helm Chart (deprecated)].
• You can also choose to use an external ingress controller at the time of installation or upgrade.

Domain Name

• You need a registered domain name (a fully qualified domain name (FQDN)) to access the Digital.ai Deploy UI.
• Create a domain name and keep it handy for use during the Digital.ai Deploy installation or upgrade.

Digital.ai Deploy License

• You must procure and keep a valid version 4 license for Digital.ai Deploy handy for use during the Digital.ai Deploy installation or upgrade.
• The license file can be in plain text format or base64 encoded format.

Version 3 License End-of-Life

Deploy License version 3 is no longer supported by Deploy 25.1 and later:

• Required Action: Upgrade to a valid version 4 license
• Impact: Systems with v3 licenses will not function after upgrade
• For assistance, contact Digital.ai Support

Java Keystore

• You can choose to generate a new Java keystore when you install or upgrade Digital.ai Deploy .
• You must have the Keytool utility installed on your computer (Keytool is installed by default on Linux and MacOS)
• However, you can also use an existing keystore.
• Note that you must also create a Keystore passphrase, which must be no less than six characters.

TLS/SSL Configuration

Do you want to enable TLS/SSL protocols in your cluster?

If yes, you must create a namespace and have the TLS certificate and key created in the namespace as a secret in your cluster before you start the Digital.ai Deploy installation or upgrade.

For more information about creating the TLS cert and keys, see:

• Configure SSL/TLS—Deploy

PostgreSQL Database Server

Which PostgreSQL installation method do you want to use?

You can choose from the following PostgreSQL installation options:

1. CloudNativePG Operator: Install PostgreSQL using the CloudNativePG Operator. See External Operators Support.
2. External PostgreSQL: Use an existing external PostgreSQL database server.

note

The Bitnami Helm Chart option for PostgreSQL is deprecated and will be removed in a later version. It is recommended to migrate to an external database or use the CloudNativePG Operator.

If you choose to use an existing external PostgreSQL database server, you must gather and keep the following information about the external PostgreSQL server handy.

    main:
      url: jdbc:postgresql://<xld-db-host>:5432/<xld-database-name>
      username: <xld-username>
      password: |-
        <xld-password>
      maxPoolSize: 10
    report:
      url: jdbc:postgresql://<xld-report-db-host>:5432/<xld-report-database-name>
      username: <xld-report-username>
      password: |-
        <xld-report-password>
      maxPoolSize: 10

RabbitMQ Server

Which RabbitMQ installation method do you want to use?

You can choose from the following RabbitMQ installation options:

1. RabbitMQ Cluster Operator: Install RabbitMQ using the RabbitMQ Cluster Operator. See External Operators Support.
2. External RabbitMQ: Use an existing external RabbitMQ server.

note

The Bitnami Helm Chart option for RabbitMQ is deprecated and will be removed in a later version. It is recommended to migrate to an external RabbitMQ server or use the RabbitMQ Cluster Operator.

The default installation option is to create a new RabbitMQ server in your cluster. However, you can choose to use an existing RabbitMQ server if required.

In this case, you must gather and keep the following information about the external RabbitMQ server handy for the installation or upgrade of Deploy .

    url: <queue-url>
    queueName: <queue-name>
    username: <username>
    password: |-
      <password>
    driverClassName: <driver-class-name>

OIDC Configuration

Configuring OIDC is one of the steps in installing or upgrading Digital.ai Deploy using the Operator-based installer.

Here's the available OIDC configuration options when you install or upgrade Digital.ai Deploy.

• Use an existing OIDC authentication server such as Keycloak, Okta, Azure Active Directory (Office 365), and so on, if you have one.
• Integrate with the Digital.ai Platform's identity service.
• Use no OIDC authentication in favor of Digital.ai Deploy's native database-based local user authentication.

For more information, see Select the Type of OIDC Configuration.

PVC Size

Estimate the Persistent volume claim (PVC) size for Deploy, PostgreSQL, and RabbitMQ. Check recommended sizing here:

• Deploy Server Hardware Requirements.

Storage Class

• Selecting the storage class for Deploy, PostgreSQL, and RabbitMQ servers is one of the steps in installing or upgrading Digital.ai Deploy.
• Default storage classes are created in Kubernetes clusters that run Kubernetes version 1.22 or later.
• However, you can create your own storage classes that suit the quality-of-service or backup policies required for your site.

Manage Resources using XL CLI

From version 24.3.x and later, managing Kubernetes resources (such as CPU and Memory) for installations through the XL CLI is supported. These resources refer to container resources allocated to each pod.

There are three options to manage resources:

• Custom resource definition (Recommended for production): Resources can be specified as a YAML input with the required resources section. This is the preferred method for production.
• Resource Presets: Select predefined resource values based on appropriate sizing for different environments.
• Manual modification of CR file (Not recommended): Users can directly modify the resource configurations in the CR file.

For more information, see Select Resource Values.

Support for External Operators

The installation wizard supports operator-based external dependencies. This allows operator-managed deployments for key components such as PostgreSQL, RabbitMQ, and ingress controllers.

important

The experimental external operators such as CloudNativePG (PostgreSQL), RabbitMQ Cluster Operator, and Ingress-NGINX Controller are intended for non-production use only (evaluation, development, and testing environments). For production environments, use external PostgreSQL and RabbitMQ services.

These operator-based dependency installations have been enhanced with OpenShift support, private registry support, resource configuration, and Preserve PVC functionality.

Supported External Operators

The following Kubernetes operators are available:

Dependency	Operator	Reference
PostgreSQL	CloudNativePG Operator	https://cloudnative-pg.io/
Ingress Controller	Ingress-NGINX Controller	https://github.com/kubernetes/ingress-nginx
RabbitMQ	RabbitMQ Operator	https://www.rabbitmq.com/kubernetes/operator/operator-overview

Features

• Private registry support: Operators can be pulled from a private container registry.
• Resource configuration: CPU/memory requests and limits support for the operator-based installation.
• OpenShift support: OpenShift and SCC support for the operator-based installation.
• Preserve PVC functionality: Support for preserving PVC for operator-based PostgreSQL.

Recommendations

• Use the default configuration provided by the installation wizard for evaluation.
• For production installations, use external PostgreSQL and external RabbitMQ services. orted | | Resource configuration | Not available for operators and managed containers | | Registry configuration | Custom or private registries not supported | | Migration guidance | Documentation for migration from Bitnami-based installation will be provided in a future update |

Recommendations

• Use the default configuration provided by the installation wizard for evaluation.
• Continue to use the external PostgreSQL, external RabbitMQ, and Bitnami Helm chart options for production installations.

Additional Notes

Future releases (starting with 25.3.1) will expand support to include custom namespaces, OpenShift platforms, and hardened container configurations. external PostgreSQL** and external RabbitMQ services.