Before you deploy
Choose a deployment model, make the decisions that shape the first rollout, and prepare the cluster, network, storage, and tools.
This page is for the platform engineer who prepares a first BullSequana AI deployment. Work through it before the first bsqai apply. The platform deploys its own shared services, but it cannot fix missing cluster capacity, an unreachable registry, or an undecided DNS owner during the deployment.
Choose a deployment model
BullSequana AI runs in four deployment models. The platform architecture is the same in all of them; the models differ in who provides and operates the infrastructure. They are listed in order of preference.
| Order | Model | Choose it when | What you get |
|---|---|---|---|
| 1 | BullSequana hardware | You want an integrated platform on known hardware, delivered from factory preparation to on-site rollout. This is the reference path. | Sizing optimized for AI workloads, simpler delivery, one alignment between hardware, platform, and support, and the fastest path to production. |
| 2 | Sovereign public cloud | The site must stay in a sovereign hosting model, with a provider such as IONOS, OVHcloud, or OUTSCALE. | Local or regional control of the infrastructure, data residency, and cloud-style flexibility without hyperscaler lock-in. Fits a white-label or service-provider model. |
| 3 | Existing GPU infrastructure | You already own compatible servers or a Kubernetes cluster, with registry and network foundations in place. | An AI platform layer on top of what you have, often the fastest way to start. |
| 4 | Hybrid deployment | Workloads must be split across sites or operating domains. | For example, inference on premises and experiments in the cloud, a staged move to BullSequana hardware, or separate environments for regulated and non-regulated workloads. |
Between models, these inputs change: storage classes, DNS and certificate provisioning, the registry and image delivery path, the Git and Argo CD source, GPU scheduling and node placement, and cloud-specific identity or DNS integration. The environment guides give the values for each environment.
Decisions to make first
Settle these points with the teams involved before you prepare the environment. Each one changes the settings you write in platform.env.
| Decision | Options | Read more |
|---|---|---|
| Platform scope | Foundation only, Foundation + AI, or Foundation + AI + Data. The scope sets which components you enable, and so the secrets, storage, and capacity you need. | Minimum hardware requirements |
| DNS and certificates | Which DNS zone hosts the platform, and who updates it. The platform manages records and certificates on Azure DNS, RFC2136 servers, and Amazon Route 53; with any other provider, you manage them. | Network, DNS, and TLS |
| Object storage | rook-ceph: the platform runs Ceph in the cluster. external-s3: your storage team provides an S3-compatible service. Models can use the same store or a separate [model_storage] endpoint. | Persistent storage |
| Secrets backend | sealed-secrets (default): secrets are sealed and stored in Git. external-vault: values are read from a Vault that you operate. | Configuration and secrets |
| Identity and access | The platform's own identity provider, or federation with an existing one. Decide the access model for operators, developers, and end users. | Security model |
| Registry and Git | Use an existing registry and Git server, or prepare them. A disconnected site needs a mirror of every release artifact. | Artifact and desired-state systems |
| GPUs | No GPU, the platform's GPU Operator, or the NVIDIA integration of the cluster owner, and whether GPU node pools share GPUs through time slicing or KAI fractioning, chosen per node pool. | Capacity and scheduling, Share GPUs |
| Network policies | An engine that enforces Kubernetes NetworkPolicy: the cluster's own, or Calico installed by the platform CLI. Whether to roll out the platform default-deny, in stages, after the first deployment. | Network, DNS, and TLS, Network policies |
| Tenant defaults | The compute quota every new tenant starts with, and the GPUs that tenants can be guaranteed. | Tenant defaults and usage metering |
| Agent sandbox | Off by default. Turning it on needs a dedicated node pool. | Agent sandbox (optional) |
Choose the object storage provider before the first deployment
Moving an existing site between Rook-Ceph and an external S3 service is a data migration, not a configuration change.
Prerequisites
Kubernetes access
Provide a supported Kubernetes cluster and an identity that can create namespaces, CRDs, cluster roles, storage resources, and Gateway API resources.
Save the kubeconfig at <bsqai-platform>/.kube/config, then test the access:
bsqai test-k8sThe CLI does not read ~/.kube/config
The CLI reads the kubeconfig only from the .kube/config file inside your clone of the platform repository.
Capacity and scheduling
Check the CPU, memory, and storage of the cluster against the minimum hardware requirements. Set the labels, taints, quotas, and placement rules before you deploy the applications.
If models or document processing need GPUs:
- Install compatible NVIDIA drivers and the container runtime on the GPU nodes.
- Use the NVIDIA integration of the cluster owner.
- With the cluster owner's integration, set
GPU_OPERATOR_RUNTIME_CLASSto the NVIDIA RuntimeClass that exists on the cluster. See Enable GPU for AI components.
KServe has LLM profiles for CPU and for 1, 2, 4, or 8 whole NVIDIA GPUs, optional time-sliced and fractional profiles that share one GPU, and CPU or one-GPU Triton runtimes for predictive ONNX models. The number of GPUs depends on the models and profiles you choose; there is no single platform minimum.
Node kernel limits
Every Linux node must allow at least these inotify limits:
| Setting | Minimum |
|---|---|
fs.inotify.max_user_instances | 8192 |
fs.inotify.max_user_watches | 1048576 |
The usual Linux default is too low
The kubelet and the container runtime hold inotify instances for every container, all under the same user. The common default of 1024 instances runs out on a node with many pods, and new containers then fail with too many open files.
Set the limits where the site provisions its nodes, so that every node starts with them, including nodes that an autoscaler adds later. On self-managed nodes, add a file under /etc/sysctl.d/ and load it:
printf 'fs.inotify.max_user_instances = 8192\nfs.inotify.max_user_watches = 1048576\n' | sudo tee /etc/sysctl.d/99-inotify.conf
sudo sysctl --systemManaged node pools that do not expose these settings, such as AKS, need a privileged DaemonSet that writes them on each node. To check the current value on a node:
kubectl debug node/<node> -it --image=busybox -- cat /proc/sys/fs/inotify/max_user_instancesAfter deployment, the platform Prometheus raises NodeInotifyInstancesBelowRequirement or NodeInotifyWatchesBelowRequirement for a node below these minimums.
Persistent storage
The cluster needs two storage classes. Set them with COMMON_RWO_STORAGECLASS and COMMON_RWX_STORAGECLASS:
| Storage class | Used by |
|---|---|
ReadWriteOnce (RWO) | Databases and stateful services with one writer |
ReadWriteMany (RWX) | Workloads that share files across replicas |
Check that both classes create and delete volumes as expected on the target cluster.
Then choose the object storage provider:
| Provider | Who provides buckets and credentials |
|---|---|
rook-ceph | The platform runs Ceph and creates the buckets and users. |
external-s3 | The storage team provides the endpoints, buckets, credentials, certificates, and provider capabilities in one handoff. Complete External S3 object storage before you deploy. |
For external-s3, the bucket CORS policy must allow GET and HEAD from https://portal.<base-domain>, so that browser downloads work.
manage_bucket_cors replaces the whole CORS policy
Turn on [object_storage.capabilities] manage_bucket_cors only when the storage owner lets BullSequana AI manage the CORS policy of the bucket. The platform then replaces the existing policy; it does not merge rules into it.
Decide separately whether models use the primary store or a shared [model_storage] endpoint.
Network, DNS, and TLS
- Choose a base domain.
- Make the shared Envoy Gateway endpoint reachable. BullSequana AI publishes its routes with Gateway API
HTTPRouteresources. - Decide who owns the DNS records, and whether External DNS can update the zone. The platform manages records and certificates on Azure DNS, RFC2136 servers, and Amazon Route 53. With any other provider, you manage the records and certificates. See DNS and TLS.
- Provide the zone and credentials of the DNS provider, or your own TLS certificate.
- Make sure the certificates of a private registry and of an S3 service chain to a trusted CA, or supply the CA in the platform configuration.
- Run a network policy engine that enforces Kubernetes
NetworkPolicy, such as Calico or Cilium. The platform renders its allow policies by default, and the tenant operator gives each tenant namespace a default-deny policy. Without an engine, these policies have no effect, so the isolation of tenants, Managed MCP Servers, private tenant MLflow and the agent sandbox is not enforced. On a cluster without one, install Calico withbsqai helm-apply calico, thenbsqai helm-apply calico-installation. Check enforcement withbsqai test-npe.
If the cluster DNS service or domain is not kube-dns.kube-system and cluster.local, set the internal resolver name, its namespace, and the cluster domain. See Cluster DNS and registry trust.
Artifact and desired-state systems
Provide:
- an OCI registry for images and Helm charts, reachable from the cluster nodes and from Argo CD;
- registry credentials and, for a private PKI, the CA certificate of the registry;
- a Git repository and branch dedicated to the rendered manifests;
- a token that can push to this repository;
- a read credential for Argo CD.
For a disconnected or restricted site, mirror the release artifacts into the approved registry before you deploy. See Artifact delivery with Harbor.
Agent sandbox (optional)
Skip this section unless the site enables the agent sandbox. It needs:
- a dedicated node pool whose VM type supports nested virtualization (
/dev/kvmon the node), labeledworkload=sandboxand taintedworkload=sandbox:NoSchedule; - a network policy engine that enforces Kubernetes
NetworkPolicy, such as Calico or Cilium; - cluster DNS pod labels that match
[network_policy]and, on Cilium with socket load balancing,socketLB.hostNamespaceOnly=true; - when previews are enabled, a DNS record for
*.<preview_host_prefix>.<base-domain>that resolves to the Envoy Gateway, and a wildcard certificate that also covers that name; the platform provides both when it manages DNS and certificates (see DNS and TLS); - the Kata Containers chart and image, the agent-sandbox controller image, and the
sandbox-runtimeimage in the platform registry; - a storage bucket for each tenant that uses the sandbox, which the tenant operator creates, since workspaces are saved in the tenant's
<tenantId>-databucket; - with external S3, a pre-created
sandbox-workspacesbucket for the Global organization's workspaces, and the tenant operator'sBSQAI_TENANT_OPERATOR_S3_*account, through which the BSQAI API reaches tenant buckets.
No network policy engine, no sandbox isolation
Without an engine that enforces NetworkPolicy, the network isolation of the sandbox is not applied.
Operator workstation
Install Python 3.12, uv, Git, Helm 3.12 or later, and kubeseal 0.24 or later. Clone the platform repository, then install the CLI from the clone:
uv sync
uv tool install --editable . --python 3.12Keep the clone
The bsqai command reads its templates and configuration from the clone. If you delete or move the clone, the command stops working.
Configuration and secrets
Create platform.env for the site settings and local.env for your personal credentials. See Configuration model for how to write them.
Decide whether to set RANDOMIZE_SECRETS=true. The CLI then generates the secrets and saves them in generated_secrets.env. Protect this file until its values are in the site's secret-management process.
Choose the secrets backend:
| Backend | Needs |
|---|---|
sealed-secrets (default) | kubeseal on the workstation |
external-vault | A Vault that you operate, reachable from the cluster, a read-only token for the platform entries, and an owner who fills them. See External Vault secrets. |
Readiness checklist
Before the first render, confirm that:
- cluster access works with the kubeconfig in the repository;
- every Linux node meets the node kernel limits;
- the storage classes and object storage match the chosen provider;
- the owners of DNS, Gateway API exposure, and TLS are known;
- the Git server and the OCI registry are reachable;
- the cluster runs an engine that enforces
NetworkPolicy, andbsqai test-npepasses; - the required images and charts are mirrored;
- GPU drivers, the runtime, and the platform GPU Operator or an equivalent integration exist for the chosen runtime profiles;
- if the agent sandbox is enabled, the nested-virtualization node pool, an enforcing CNI, and the preview DNS name and certificate exist;
- the owners of secrets and of backup recovery are known.
Then continue with the environment guide for your site, the configuration model, and the deployment sequence.