Prerequisites

Prepare the external foundations before running the platform CLI. BullSequana AI deploys shared services, but it cannot resolve missing cluster capacity, unreachable artifact systems, or undecided DNS ownership during bootstrap.

Kubernetes access

Provide a supported Kubernetes cluster and installation identity that can create namespaces, CRDs, cluster roles, storage resources, and Gateway API resources. Save its kubeconfig at <bsqai-platform>/.kube/config; the CLI does not read ~/.kube/config.

Run:

bsqai test-k8s

Capacity and scheduling

Confirm CPU, memory, and storage capacity against Minimum hardware requirements. If models or accelerated document processing need GPUs, provide compatible NVIDIA drivers and the container runtime, then either use the cluster owner's supported device-plugin integration or install the platform-supplied GPU Operator with bsqai helm-apply gpu-operator. Establish the required labels, taints, quotas, and placement policy before application deployment.

KServe includes profiles for CPU and 1, 2, 4, or 8 NVIDIA GPUs. Capacity depends on the selected model and profile; GPU count is not a single fixed platform minimum.

Persistent storage

Set valid COMMON_RWO_STORAGECLASS and COMMON_RWX_STORAGECLASS values. RWO storage supports databases and single-writer stateful services; RWX storage supports workloads that share files across replicas. Validate volume provisioning and deletion behavior in the target cluster.

Choose the primary object-storage model:

• rook-ceph, where the platform operates Ceph and creates buckets and users; or
• external-s3, where the storage operator supplies reachable endpoints, buckets, credentials, certificates, and provider capabilities through one approved handoff for the BullSequana AI deployment operator to configure.

For external S3, configure bucket CORS to allow GET and HEAD from https://portal.<base-domain> so browser-facing presigned downloads work. If the storage owner delegates the whole CORS document to BullSequana AI, explicitly enable [object_storage.capabilities] manage_bucket_cors; the platform's PutBucketCors operation replaces, rather than merges with, the existing document.

Decide separately whether models use the primary store or a shared [model_storage] endpoint.

Complete External S3 object storage before deployment when provider = "external-s3".

Network, DNS, and TLS

Choose a base domain and make the shared Envoy Gateway endpoint reachable. BullSequana AI publishes platform routes with Gateway API HTTPRoute resources.

Establish who owns DNS records and whether External DNS can update the zone. Provide either certificate-issuer prerequisites or operator-managed custom TLS material. Private registry and S3 certificates must chain to a trusted CA or be supplied through the relevant CA configuration.

If the cluster DNS service or domain differs from kube-dns.kube-system and cluster.local, configure the internal resolver name, namespace, and cluster domain.

Artifact and desired-state systems

Provide:

• an OCI registry reachable by cluster nodes and Argo CD for images and Helm charts;
• registry credentials and, for private PKI, the registry CA certificate;
• a Git repository and branch dedicated to rendered manifests;
• a token that can update the manifests repository; and
• a read credential for Argo CD.

Mirror the release artifacts into the approved registry before deploying a disconnected or restricted environment.

Operator workstation

Install Python 3.12, uv, Git, Helm 3.12 or later, and kubeseal 0.24 or later. Clone the platform repository and install the editable CLI:

uv sync
uv tool install --editable . --python 3.12

Preserve the clone: the editable bsqai command resolves templates and configuration from it.

Existing-deployment upgrade baseline

An in-place upgrade requires the existing Argo CD installation and its BullSequana AI app-of-apps hierarchy to be reachable from the CLI. Do not run the fresh-deployment Argo CD bootstrap command against an existing cluster.

For 1.3.0-to-1.4.0 preparation, use Upgrade and release process. The automated CLI does not implement that transition.

The following baseline applies only to the historical 1.2.1-to-1.3.0 path: the standard baseline is Argo CD v3.3.12 installed as Helm release argo-cd in namespace argocd through chart 9.5.11. The customer-run CLI upgrade moves that release to Argo CD v3.5.2 through chart 10.4.1 before the GitOps cutover. Do not manually pre-upgrade it. Treat a different Argo CD version, release name, namespace, or locally modified control plane as an advanced upgrade case.

The automated path also verifies these conditions:

• the platform root Application exists and every unclassified Application is idle, Synced, and Healthy;
• the cnpg-operator, keycloak, strimzi, rook-ceph, and rook-ceph-cluster chart revisions match the 1.2.1 fingerprint;
• AKS system and user node pools are both present, every system node has CriticalAddonsOnly=true:NoSchedule, and at least one user-pool node is Ready; and
• when Azure DNS is enabled, the resourceGroup embedded in AZURE_DNS_CLIENT_JSON matches AZURE_DNS_RESOURCE_GROUP_NAME.

A cluster that does not meet these conditions requires remediation or the manual migration procedure.

Configuration and secrets

Prepare platform.env for site settings and local.env for personal credentials. Decide whether to enable RANDOMIZE_SECRETS; if enabled, protect generated_secrets.env until its generated values are transferred to the site's secret-management process.

Choose the secrets backend. The default sealed-secrets backend needs kubeseal on the workstation. The external-vault backend needs a customer-managed Vault that is reachable from the cluster, a read-only token for the platform entries, and an owner who populates them. See External Vault secrets.

For an existing deployment using the sealed-secrets backend, place the current sealed-secrets private key and certificate under src/manifests/seal/ in the target checkout before rendering. Preserve the active deployment configuration and manifest revision. Follow the version-specific upgrade procedure for GIT_BRANCH and the target manifest ref. Never generate a new sealing identity as part of an upgrade.

Readiness checklist

Before the first render, confirm:

• cluster access succeeds through the repository kubeconfig;
• storage classes and object storage match the selected provider;
• DNS, Gateway API exposure, and TLS ownership are defined;
• Git and OCI registry endpoints are reachable;
• required images and charts are mirrored;
• GPU drivers, runtime, and either the platform GPU Operator or an equivalent cluster integration exist for selected runtime profiles;
• for an upgrade, the existing Argo CD installation and managed Applications are reachable and healthy; and
• the secrets and backup recovery owners are identified.