#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.

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

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:
        internalGateway:
            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.internalGateway.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 k8s-plugin. 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.
• 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.