Self-Hosted S3 for High Availability

High availability in NetBox Enterprise requires shared object storage for NetBox media: the media volume cannot be shared across nodes, so without shared object storage NetBox is pinned to the node holding that volume and does not survive its loss (see High Availability).

An external endpoint does not have to be a cloud provider. NetBox Enterprise works with any S3-compatible endpoint — including one you run yourself. This page is a reference architecture for a customer-run S3 endpoint: self-hosted S3-compatible software (such as MinIO, Ceph with RadosGW, or Garage) that you operate outside the NetBox Enterprise cluster.

If you already have a managed cloud bucket, you do not need this page — go straight to Storage Options for provider setup.

When to self-host

Both paths satisfy the external-S3 requirement equally. The choice is operational.

Self-hosting is the path that unblocks customers who have no cloud object storage but can provision a few extra hosts.

Reference topology

Run the S3 endpoint on hosts independent of the NetBox Enterprise nodes. Co-locating the object store on the same machines that run NetBox reunites the failure domains you separated them to avoid: losing a node would then take down both a NetBox replica and part of the storage tier at once.

PostgreSQL and Redis are also external in an HA deployment; they are omitted here to keep the focus on object storage. See High Availability for the full data-tier picture.

Endpoint requirements

A customer-run endpoint must meet the same bar NetBox Enterprise expects of any external dependency:

1. Highly available in its own right. NetBox Enterprise depends on the endpoint; it does not make it HA. Run the S3 software as a multi-node, replicated cluster so the object store survives the loss of one of its hosts. A single-node MinIO (or equivalent) reintroduces the single point of failure you are removing.
2. Reachable from every NetBox node at one stable address. Front the S3 nodes with a load balancer or virtual IP and give NetBox that single endpointUrl. NAT between NetBox nodes and the endpoint is not required, but the address must resolve and route identically from all nodes.
3. TLS. Serve the endpoint over HTTPS. A certificate from a public CA is simplest; for a private CA or mTLS, NetBox Enterprise references the certificates through its keychain rather than disabling verification. See SSL Certificate Errors.
4. CORS. NetBox's web UI makes direct browser requests to the endpoint, so CORS is mandatory — without it, media and static files fail to load. See CORS Configuration.
5. AWS Signature Version 4. The endpoint must implement the S3 API with SigV4 authentication, which the supported self-hosted options all do.

Software options

Any S3-compatible service that implements the S3 API with Signature Version 4 works. Common self-hostable choices are MinIO, Ceph (RadosGW), SeaweedFS, and Garage. Storage Options lists the tested providers along with bucket, IAM, and CORS setup for each; follow your chosen software's own clustering and sizing guidance to build the endpoint itself.

Sizing and placement

• Dedicated hosts. Provision the S3 endpoint on separate hosts (or a separate cluster) from the NetBox Enterprise nodes, per the topology above.
• Capacity. Size the endpoint for media growth, not for the NetBox database — uploaded images, attachments, and custom-script files land here. Enable versioning to guard against accidental deletion.
• Locality. Keep the endpoint on the same low-latency network as the NetBox cluster. Media reads and writes are in the request path for parts of the UI, so a distant or high-latency endpoint shows up as slow page loads.

Configure NetBox Enterprise

Once the endpoint is running, point NetBox Enterprise at it. The connection fields are the same as for any external S3; only the endpointUrl differs.

• Embedded Cluster: configure S3 in the Admin Console — see Storage Installation.
• Helm: set netbox.config.storage.s3 in your values file — see S3 Media Storage.

netbox:
  config:
    storage:
      s3:
        enabled: true
        bucketName: netbox-media
        endpointUrl: https://s3.internal.example.com  # your self-hosted endpoint
        accessKeyId:
          name: netbox-s3-creds
          key: access_key
        secretAccessKey:
          name: netbox-s3-creds
          key: secret_key

For a private CA or mTLS, add a tlsConfig block referencing keychain certificates instead of skipping verification — see S3 TLS Configuration.

On an existing install, migrate the media already on node-local storage before this cutover takes effect — see Storage Migration.

Proxy environments

If your cluster reaches the internet through a corporate egress proxy, NetBox's S3 client honors the standard proxy environment variables. NetBox Enterprise sets nothing that overrides them, so HTTP_PROXY, HTTPS_PROXY, and NO_PROXY apply to media traffic as they do to any other outbound request.

Two behaviors matter for a self-hosted endpoint:

• NO_PROXY always includes the private address ranges. NetBox Enterprise prepends the cluster-internal suffixes plus 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and 169.254.0.0/16 to whatever you configure. A self-hosted endpoint on a private address is therefore reached directly, bypassing the proxy — which is usually what you want for an endpoint on your own network, but it also means you cannot force that traffic through the proxy. An endpoint reached by a public hostname goes through the proxy normally.
• The variables are only present if a proxy is configured. They are stamped onto NetBox and the other workloads only when proxy settings exist; a direct-connection install is unaffected.

Availability is not backup

A shared, highly available S3 endpoint keeps NetBox media reachable through a node failure — that is what unblocks HA. It is not a backup. A bucket that is deleted, corrupted, or lost with its hosts still needs an independent backup target on separate storage.

Next steps

• Storage Migration — move existing media off node-local storage before cutting over
• Storage Options — provider tables, bucket, IAM, and CORS setup
• Storage Installation — configure S3 during NetBox Enterprise setup
• High Availability — full HA topology, network budget, and prerequisites
• Multi-Node Deployment — install the HA cluster