#Configuration

This page explains how to think about Sandbox0Infra configuration and includes a generated field reference sourced from the operator CRD.

The goal is to keep the page readable for operators while still exposing the full supported config surface.

How to Read Sandbox0Infra#

A Sandbox0Infra spec is easier to reason about when you split it into five layers:

Recommended Reading Order#

1. Pick your topology with spec.services.*.
2. Decide whether database/storage/registry stay builtin or move external.
3. Configure public exposure and cluster identity.
4. Seed templates and initial admin user.
5. Only then tune per-service config blocks.

spec.initUser is consumed by the gateway runtime, not created by the operator itself. In local-password mode it bootstraps the first admin credentials; in OIDC-only mode it pre-creates the admin user and initial team so the first OIDC login with the same email lands on the intended admin account.

Deployment Profiles#

Official sample manifests:

• single-cluster/minimal.yaml
• single-cluster/fullmode.yaml
• single-cluster/volumes.yaml
• single-cluster/network-policy.yaml
• multi-cluster/control-plane.yaml
• multi-cluster/data-plane.yaml

What Usually Changes First#

External PostgreSQL#

Move spec.database.type from builtin to external when you want managed PostgreSQL durability, backup policy, and operational separation.

yaml
spec:
    database:
        type: external
        external:
            host: your-db.rds.amazonaws.com
            port: 5432
            database: sandbox0
            username: sandbox0
            passwordSecret:
                name: db-credentials
                key: password

S3 or OSS Backing Storage#

If you need persistent volume features in production, configure spec.storage and enable services.storageProxy.

yaml
spec:
    storage:
        type: s3
        s3:
            bucket: sandbox0-prod
            region: us-east-1
            endpoint: https://s3.amazonaws.com
            credentialsSecret:
                name: aws-credentials
                accessKeyKey: accessKeyId
                secretKeyKey: secretAccessKey
    services:
        storageProxy:
            enabled: true

Public Routing and Region Identity#

spec.publicExposure decides the public host pattern used for sandbox URLs. Keep it consistent with your region and DNS plan.

yaml
spec:
    publicExposure:
            enabled: true
            rootDomain: sandbox0.example.com
            regionId: aws-us-east-1

SSH Gateway#

Enable spec.services.sshGateway when you want a region-scoped SSH entrypoint that bridges standard ssh and scp clients into sandbox procd sessions.

The routing model is intentionally simple:

• One ssh-gateway per region
• One fixed DNS-only host or TCP proxy address per region, for example aws-us-east-1.ssh.sandbox0.app
• SSH username is the target sandbox ID
• User authentication uses SSH public keys uploaded to the gateway API

In Kubernetes terms, spec.services.sshGateway.service.port is the externally exposed Service port and spec.services.sshGateway.config.sshPort is the container listen port. You usually keep the internal port at 2222 and expose 22 or a NodePort externally.

The operator also manages a persistent Ed25519 host key Secret for the service. As long as that Secret is retained, clients continue to see the same SSH host identity across pod restarts.

yaml
spec:
    services:
        sshGateway:
            enabled: true
            replicas: 1
            service:
                type: LoadBalancer
                port: 22
            config:
                sshPort: 2222

For local labs or kind-style environments, a NodePort is often simpler:

yaml
spec:
    services:
        sshGateway:
            enabled: true
            replicas: 1
            service:
                type: NodePort
                port: 30222

After exposing the service through DNS or a load balancer, users can upload SSH public keys with POST /api/v1/users/me/ssh-keys and connect with standard clients. See SSH for the user-facing flow.

AWS LoadBalancer TLS#

When you expose regionalGateway or globalGateway through a cloud load balancer instead of Kubernetes Ingress, declare provider-specific Service annotations under spec.services.<service>.service.annotations. On AWS, this is the supported place to attach ACM certificates and choose the load balancer mode.

Also set spec.services.<service>.config.baseUrl to the final browser-facing URL. That keeps auth callbacks, generated links, and projected status endpoints aligned with the hostname you put behind Cloudflare.

yaml
spec:
    services:
        regionalGateway:
            enabled: true
            service:
                type: LoadBalancer
                port: 443
                annotations:
                    service.beta.kubernetes.io/aws-load-balancer-type: nlb
                    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
                    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: <acm-certificate-arn>
                    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
            config:
                baseUrl: https://your-gateway.example.com

Multi-Cluster Data Plane Registration#

Data-plane clusters need control-plane connection details and a stable cluster identity.

yaml
spec:
    controlPlane:
        url: https://api.sandbox0.example.com
        internalAuthPublicKeySecret:
            name: control-plane-public-key
            key: public.key
    cluster:
        id: cluster-001
        name: production-use1-a
    services:
        clusterGateway:
            enabled: true
            config:
                authMode: internal
        manager:
            enabled: true

Service-Level Config#

spec.services.<service>.config is where you tune component-specific behavior after the topology is already correct.

Examples:

• services.clusterGateway.config.authMode switches between public, internal, and both
• services.manager.config.autoscaler.* tunes pool scale behavior
• services.storageProxy.config.juicefs* tunes JuiceFS behavior and cache sizing
• services.netd.config.* controls proxy ports, policy enforcement, and node-level networking behavior

Use spec.sandboxNodePlacement for the shared node placement consumed by sandbox template Pods, netd, and ctld. infra-operator owns sandbox0.ai/data-plane-ready and adds it to sandbox Pod placement after the required node-local components are Ready. The older services.netd.nodeSelector and services.netd.tolerations fields remain as compatibility aliases when the shared placement is unset.

Full Reference#

The reference below is generated from the Sandbox0Infra CRD schema produced by controller-gen, not manually maintained MDX.

Practical Rules#

• Pin the infra-operator chart version in production instead of relying on floating tags.
• Prefer external PostgreSQL and external object storage for serious deployments.
• Enable storageProxy only when you need volume and snapshot features.
• Enable netd only on Linux nodes and only when you need network policy enforcement.
• Use sandboxNodePlacement to keep sandbox workloads and node-local sandbox services on the same node set.
• Treat sandbox0.ai/data-plane-ready as operator-owned; use your own labels under sandboxNodePlacement and let infra-operator manage readiness.
• If sandbox workloads use gvisor or kata, keep services.netd.runtimeClassName on a host-compatible runtime such as the cluster default runtime.
• Keep control-plane and data-plane components in the same storage and latency domain for a given region.