Deployment sequence

This playbook is the supported sequence for a fresh BullSequana AI deployment. It applies to cloud, hybrid, and on-premises clusters after the Kubernetes foundation is ready.

Recommended path

1. Plan and assign owners

Choose the deployment model, record the platform scope, and agree on acceptance criteria before changing the environment.

Assign an owner for each external dependency:

• Kubernetes and node capacity
• DNS, load balancing, and certificates
• RWO and RWX storage classes
• primary and optional model object storage
• OCI registry and release-artifact mirroring
• Git repository and credentials for generated manifests
• external Vault, when secrets are delivered from it
• identity federation and administrative access
• backups, monitoring, and incident response

For an on-premises delivery, complete hardware, network, operating-system, storage, and Kubernetes acceptance before platform bootstrap. Use the BullSequana hardware guide for the platform-facing requirements.

2. Prepare Kubernetes and external services

Complete the prerequisites and validate the minimum requirements. In particular:

• place the target kubeconfig at <bsqai-platform>/.kube/config
• verify cluster-admin access for namespaces, CRDs, cluster roles, storage, and Gateway API resources
• confirm working RWO and RWX storage classes
• make the Envoy Gateway address reachable and define the platform DNS records
• provide public or private-PKI certificate material and client trust
• select rook-ceph or external-s3 and verify both private and browser-facing endpoints; for an external provider, complete the External S3 object storage playbook
• select the sealed-secrets or external-vault secrets backend; for an external Vault, complete the External Vault secrets playbook
• prepare GPU nodes, if used, with compatible NVIDIA drivers, the container runtime, labels, taints, and capacity

Do not proceed while an external interface is unresolved. Record the expected endpoint, credential owner, test method, and recovery owner for each one.

3. Deliver release artifacts

Make the 1.4.0 container images and Helm charts available in the approved OCI registry. For disconnected or restricted environments, mirror the complete release set before deployment and supply the private registry CA where required.

Create a Git branch dedicated to the rendered manifests. The Platform CLI replaces the contents of that branch with generated desired state, so do not mix hand-maintained resources into it.

See Artifact delivery with Harbor for the restricted-network path.

4. Configure and validate

Install the Platform CLI from the 1.4.0 checkout and preserve that checkout because the editable command resolves its templates from the repository:

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

Put shared site configuration in platform.env and personal credentials in local.env. Configure the GitOps repository, registry, domain, storage classes, object-storage provider, TLS, sizing, and enabled components through the configuration model.

Validate the workstation, cluster connection, component structure, and resolved values:

bsqai test-k8s
bsqai validate
bsqai load

Resolve every missing variable, unreachable dependency, and invalid provider combination before rendering.

5. Render and publish desired state

Generate a clean output tree and publish it to the GitOps branch:

bsqai apply all -r
bsqai push-manifests "Deploy BullSequana AI 1.4.0"

The render creates child Applications and the enabled common, coreai, inference, and proai parent applications. Before pushing in a production environment, review component enablement, routes, storage classes, registry paths, resource sizing, and generated SealedSecret resources. With an external Vault, review the generated ExternalSecret resources and populate the entries listed by bsqai list-vault-secrets instead.

6. Bootstrap the cluster

Install the sealing identity and registry pull secret, then bootstrap Argo CD:

bsqai apply-sealing-key
bsqai helm-apply argocd

These commands are for a fresh cluster. Preserve the generated sealing private key, certificate, environment configuration, and generated secret values in the approved secret store immediately after bootstrap.

With an external Vault, do not run apply-sealing-key. Create the registry pull secret and the Vault token secret in the external-secrets namespace, then bootstrap Argo CD:

bsqai apply-registry-secret external-secrets
kubectl -n external-secrets create secret generic vault-token --from-file=token=./vault-token
bsqai helm-apply argocd

On a GPU cluster that does not already provide an equivalent supported NVIDIA Kubernetes integration, install the optional GPU Operator:

bsqai helm-apply gpu-operator

The supplied values install node feature discovery, the NVIDIA device plugin, GPU feature discovery, DCGM metrics, and MIG support. The NVIDIA driver and container runtime must already exist on the nodes. See Enable GPU for AI components.

7. Reconcile and verify

Wait for Argo CD to create the enabled parent and child Applications. Investigate errors in dependency order instead of repeatedly forcing syncs.

The deployment is ready for acceptance when:

• every enabled Application is Synced and Healthy, or documented drift has an owner
• platform DNS names resolve and trusted HTTPS routes answer through Envoy Gateway
• Keycloak login works and the initial administrator can open the portal
• tenant creation reconciles identity and the selected optional resources
• a model can be registered, deployed through KServe, and called through the BSQAI API
• object-storage reads, writes, and browser-facing presigned URLs work
• PostgreSQL, backup, and restore checks pass for the selected topology
• Grafana receives metrics, pod logs, and application traces through the documented signal paths
• selected Data services and one representative pipeline pass their smoke tests
• GPU nodes expose allocatable resources and a selected GPU workload schedules, when GPU support is enabled

8. Hand over operations

Record the deployed GitOps commit, component versions, platform configuration, external-service owners, backup locations, recovery tests, dashboards, alerts, and escalation paths. Transfer sealed-secrets recovery material, or the Vault token and access owner for an external Vault, and credentials through the approved secret-management process.

Continue with Administration and operations, Observability and audit, and Backup and disaster recovery.