Skip to main content

NetBox on Google Cloud Run

NetBox on Google Cloud Run

NetBox is the industry-standard open-source "source of truth" for network engineering teams — IP address management (IPAM), device and rack inventory, cabling, and network topology, all modeled as structured data behind a full REST/GraphQL API. This module deploys NetBox on Cloud Run v2 on top of the App_CloudRun foundation, which provisions and manages the shared Google Cloud infrastructure.

This guide focuses on the cloud services NetBox uses and how to explore and operate them from the Google Cloud Console and the command line. For the mechanics common to every Cloud Run application — service identity, ingress and load balancing, scaling and concurrency, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, backups, and the deployment lifecycle — refer to the App_CloudRun foundation guide rather than repeating them here.


1. Overview

NetBox runs as a custom-built Python/Django container on Cloud Run v2, wrapping the official netboxcommunity/netbox image with a co-located background rqworker --with-scheduler process. The deployment wires together a focused set of Google Cloud services:

CapabilityGoogle Cloud serviceNotes
ComputeCloud Run v2Custom-built image, 2 vCPU / 2 GiB by default, serverless autoscaling; scale-to-zero supported
DatabaseCloud SQL for PostgreSQL 15Required — NetBox does not support MySQL or SQLite in production
Object storageCloud Storage (GCS Fuse)A media bucket mounted at /etc/netbox/media, NetBox's real MEDIA_ROOT
Cache & queueRedis (mandatory)Task queue (REDIS_DATABASE=0) and cache (REDIS_CACHE_DATABASE=1) on separate logical databases; defaults to the NFS server IP
SecretsSecret ManagerAuto-generated SECRET_KEY and SUPERUSER_PASSWORD; database password
IngressCloud Run URL / Cloud Load BalancingDefault run.app URL; optional external HTTPS load balancer + custom domain

Sensible defaults worth knowing up front:

  • PostgreSQL 15 is mandatory. The database engine is fixed by the shared application layer; NetBox does not support MySQL or SQLite for production use.
  • Redis is mandatory, not optional. NetBox uses Redis as the broker for its RQ (Redis Queue) background task system — webhooks, custom scripts, reports, and scheduled/system jobs — and as its cache backend. These are two separate logical Redis databases (REDIS_DATABASE=0, REDIS_CACHE_DATABASE=1); NetBox's own documentation warns that sharing one database number risks losing queued background tasks during a cache flush.
  • A background worker is co-located in the same container. The image runs manage.py rqworker --with-scheduler as a backgrounded process alongside the Granian web server. Without it, background tasks queue silently and never execute — there is no separate error.
  • Media uploads are mounted at NetBox's actual MEDIA_ROOT. /etc/netbox/media, not the more obvious-looking /opt/netbox/netbox/media — confirmed live via manage.py shell. Getting this path wrong doesn't error; uploads simply never persist to GCS (see §4 for the full story).
  • Cost-first cold-start by default (cpu_always_allocated = false, min_instance_count = 0). Trade-off: the RQ worker only runs while a request keeps the instance warm — background tasks queue and drain on the next request instead of executing immediately. Set cpu_always_allocated = true and min_instance_count >= 1 together to restore continuous processing.
  • The container runs as root (uid 0 / gid 0) — the official netboxcommunity/netbox image sets no USER. This is intentional and matches upstream; the GCS Fuse mount is pinned to uid=0/gid=0 accordingly.
  • SECRET_KEY and SUPERUSER_PASSWORD are generated automatically and stored in Secret Manager. SECRET_KEY must be at least 50 characters (NetBox enforces this); it is generated at 64.
  • Health checks use /login/, not /api/status/. The login page is public and unauthenticated; the status API requires auth and would fail every probe.
  • ALLOWED_HOSTS = "*" and CORS_ORIGIN_ALLOW_ALL = "true" are open by default for a zero-touch first deploy — tighten via environment_variables before exposing a production instance to the internet.

2. Google Cloud Services & How to Explore Them

All commands assume PROJECT and REGION are set. Service and resource names are reported in the deployment Outputs.

A. Cloud Run — the NetBox service

NetBox runs as a Cloud Run v2 service that autoscales by request load between the minimum and maximum instance counts. Each deployment creates an immutable revision; traffic can be split across revisions for safe rollouts.

  • Console: Cloud Run → select the service for revisions, traffic, logs, and metrics.
  • CLI:
    gcloud run services list --project "$PROJECT" --region "$REGION"
    gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
    gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

See App_CloudRun for scaling, concurrency, execution environment, and traffic splitting.

B. Cloud SQL for PostgreSQL 15

NetBox stores all inventory and IPAM data (devices, racks, IP addresses, prefixes, VLANs, circuits, users) in a managed Cloud SQL for PostgreSQL 15 instance. The service connects privately through the Cloud SQL Auth Proxy over a Unix socket; no public IP is exposed. On first deploy an initialization Job creates the application database and user.

  • Console: SQL → select the instance for connections, backups, flags, metrics.
  • CLI:
    gcloud sql instances list --project "$PROJECT"
    gcloud sql instances describe <instance-name> --project "$PROJECT"
    gcloud sql connect <instance-name> --user=<db-user> --database=<db-name> --project "$PROJECT"

The instance name, database, user, and password secret are in the Outputs. See App_CloudRun for the connection model, backups, and password rotation.

C. Cloud Storage (GCS Fuse media store)

A dedicated media bucket is provisioned automatically and mounted at /etc/netbox/media — NetBox's real MEDIA_ROOT — for uploaded device/rack images and file attachments.

  • Console: Cloud Storage → Buckets.
  • CLI:
    gcloud storage buckets list --project "$PROJECT"
    gcloud storage ls gs://<media-bucket>/ # bucket name is in the Outputs

See App_CloudRun for GCS Fuse and CMEK options.

D. Redis (task queue and cache)

Redis is required (enable_redis = true by default). When redis_host is left empty and enable_nfs is true, the NFS server VM's IP is used as the Redis endpoint. NetBox splits its usage across two logical databases — REDIS_DATABASE=0 for the RQ task queue, REDIS_CACHE_DATABASE=1 for the cache.

  • Console: Memorystore → Redis (if using a managed instance).
  • CLI:
    redis-cli -h <redis-host> ping
    redis-cli -h <redis-host> -n 0 llen rq:queue:default # inspect the RQ default queue depth
    # Confirm the resolved Redis host in the running revision:
    gcloud run services describe <service-name> --region "$REGION" \
    --format='value(spec.template.spec.containers[0].env)'

E. Secret Manager

Two cryptographic secrets are generated automatically and stored in Secret Manager: SECRET_KEY (Django cryptographic secret used for sessions, CSRF, and signed cookies) and SUPERUSER_PASSWORD (the initial admin account password). The database password is managed separately by the foundation.

  • Console: Security → Secret Manager.
  • CLI:
    gcloud secrets list --project "$PROJECT"
    gcloud secrets versions access latest --secret=<secret-name> --project "$PROJECT"

See App_CloudRun for injection and rotation details.

F. Networking & ingress

The service is reachable at its run.app URL by default. An external HTTPS load balancer with a custom domain, Cloud CDN, and Cloud Armor can be layered on; ingress settings and VPC egress control connectivity.

  • Console: Cloud Run (service URL); Network services → Load balancing.
  • CLI:
    gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
    gcloud compute addresses list --project "$PROJECT"

See App_CloudRun.

G. Cloud Logging & Monitoring

Container logs flow to Cloud Logging; Cloud Run and Cloud SQL metrics flow to Cloud Monitoring, with optional uptime checks and alert policies.

  • Console: Logging → Logs Explorer; Monitoring → Dashboards / Alerting.
  • CLI:
    gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50

3. NetBox Application Behaviour

  • First-deploy database setup. An initialization Job runs db-init.sh using postgres:15-alpine. It connects through the Cloud SQL Auth Proxy and idempotently creates the application database and user and grants privileges. The job is safe to re-run.
  • Database migrations on start. docker-entrypoint.sh true runs NetBox's own first-boot sequence synchronously on every container start — a DB-readiness wait, migrate --no-input, stale-contenttype cleanup, session cleanup, and a lazy search-index reindex — before the web server and RQ worker start. This is idempotent; a no-op when there's nothing new to migrate.
  • Superuser bootstrap is idempotent. The initial admin account (admin_user/admin_email, password from Secret Manager) is created from SUPERUSER_* env vars on first boot; creation is skipped — not an error — if a user with that name already exists, so it's safe on every restart.
  • Media uploads persist to the real MEDIA_ROOT. NetBox's actual MEDIA_ROOT is /etc/netbox/media (confirmed live via manage.py shell), which is where the GCS Fuse media volume is mounted. An earlier revision of this module mounted the more obvious-looking /opt/netbox/netbox/media instead — a real, non-existent NetBox path — which caused uploads to write to the ephemeral container filesystem instead: they were readable back immediately (same local filesystem, so the round-trip "worked"), but never reached GCS and were lost on every container restart, on both Cloud Run and GKE identically. This was fixed by correcting the mount path, verified live with gcloud storage ls showing the uploaded test file with correct byte size, content type, and timestamp within 5 seconds of upload. Lesson: this looked exactly like a Cloud-Run-specific storage limitation until traced with real shell access — it was a mundane Terraform mount-path bug affecting both platforms identically, not a platform gap.
  • CSRF_TRUSTED_ORIGINS reflects the real service URL. Computed from the app-scoped module.deployment_id.service_name and the project number — not the tenant-only resource prefix, which would build a URL for a service that doesn't exist and reject every authenticated POST (including login) with a CSRF failure. Verify the deployed value:
    gcloud run services describe <service-name> \
    --region "$REGION" --project "$PROJECT" \
    --format='value(status.url)'
  • The RQ worker processes background tasks. Webhooks, custom scripts, reports, and scheduled/system jobs are executed by manage.py rqworker --with-scheduler, co-located in the same container as the web server. Under the cost-first cold-start default, this worker only runs while an instance is warm; enable cpu_always_allocated = true + min_instance_count >= 1 for continuous background processing.
  • Health path. Startup and liveness probes target /login/ — NetBox's public, unauthenticated login page. /api/status/ requires authentication and would fail every probe.
  • Inspect job execution:
    gcloud run jobs list --project "$PROJECT" --region "$REGION"
    gcloud run jobs executions list --job <job-name> --project "$PROJECT" --region "$REGION"

4. Configuration Variables

Variables are grouped exactly as they appear on the deployment platform. Only settings specific to or notable for NetBox are listed; every other input is inherited from App_CloudRun with its standard behaviour.

Group 1 — Project & Identity

VariableDefaultDescription
project_id(required)Target Google Cloud project.
regionus-central1Region for the service and regional resources.

Group 2 — Deployment Environment

VariableDefaultDescription
tenant_deployment_iddemoShort suffix that makes resource names unique per environment.
support_users[]Emails granted project access and monitoring alerts.
resource_labels{}Labels applied to all resources.

Group 3 — Application Identity

VariableDefaultDescription
application_namenetboxBase name for resources. Do not change after first deploy.
display_nameNetBox - Network Documentation & IPAMHuman-readable name shown in the Console.
description(set)Service description.
application_versionlatestContainer image version tag, passed through to the Dockerfile's APPLICATION_VERSION build ARG.

Group 4 — Runtime & Scaling

VariableDefaultDescription
deploy_applicationtrueSet false to provision infrastructure only.
cpu_limit2000mCPU per instance; shared by the web server and the RQ worker.
memory_limit2GiMemory per instance; minimum 1Gi.
min_instance_count00 enables scale-to-zero; the RQ worker only runs while an instance is warm.
max_instance_count3Upper bound on autoscaling.
cpu_always_allocatedfalsetrue + min_instance_count >= 1 restores continuous background-task processing.
container_port8080NetBox's Granian (WSGI) server listens on port 8080.
execution_environmentgen2Gen2 required for GCS Fuse mounts.
timeout_seconds300Maximum request duration (0–3600 seconds).
enable_cloudsql_volumetrueCloud SQL Auth Proxy for socket connections.
enable_image_mirroringtrueMirror the built image into Artifact Registry.
traffic_split[]Split traffic across revisions for staged rollouts.
max_revisions_to_retain7Old revisions to keep.

Group 5 — Access & Ingress Control

VariableDefaultDescription
ingress_settingsallCloud Run ingress control.
vpc_egress_settingPRIVATE_RANGES_ONLYRoute only RFC 1918 traffic via VPC.
enable_iapfalseRequire Google sign-in.
iap_authorized_users / iap_authorized_groups[]Who may access through IAP.

Group 6 — Environment Variables & Secrets

VariableDefaultDescription
environment_variables{}Extra non-secret settings. Do not set SECRET_KEY, SUPERUSER_PASSWORD, or DB_* here — they're injected automatically.
secret_environment_variables{}Map of env var → Secret Manager secret name.
secret_propagation_delay30Seconds to wait after secret creation before proceeding.
secret_rotation_period2592000sSecret Manager rotation notification frequency.

Group 7 — Backup & Restore

VariableDefaultDescription
backup_schedule0 2 * * *Automated backup cron (UTC).
backup_retention_days7Retention; raise for production/compliance.
enable_backup_import / backup_source / backup_uri / backup_formatrestore optionsRestore from a backup on deploy.

Group 8 — CI/CD & Binary Authorization

Standard App_CloudRun Cloud Build / Cloud Deploy integration — see App_CloudRun. Key inputs: enable_cicd_trigger, github_repository_url, github_token, enable_cloud_deploy, enable_binary_authorization.

Group 9 — Custom SQL Scripts

enable_custom_sql_scripts, custom_sql_scripts_bucket, custom_sql_scripts_path, custom_sql_scripts_use_root — run SQL from a GCS bucket after provisioning. See App_CloudRun.

Group 10 — Load Balancer, CDN & Image Retention

VariableDefaultDescription
enable_cloud_armorfalseProvision Global HTTPS LB + Cloud Armor WAF.
admin_ip_ranges[]CIDR ranges exempted from WAF rules.
application_domains[]Custom domain names for the HTTPS LB.
enable_cdnfalseEnable Cloud CDN on the HTTPS LB backend.
max_images_to_retain / delete_untagged_images / image_retention_days(set)Artifact Registry cleanup policy.

Group 11 — Storage & Filesystem

VariableDefaultDescription
create_cloud_storagetrueCreate GCS buckets defined in storage_buckets.
storage_buckets[]Additional GCS buckets beyond the auto-provisioned media bucket.
enable_nfstrueProvisions NFS; used as the Redis host when redis_host is blank.
nfs_mount_path/mnt/nfsMount path inside the container.
gcs_volumes[]GCS Fuse volume mounts. When empty, Netbox_Common auto-mounts netbox-media at /etc/netbox/media (NetBox's real MEDIA_ROOT).
manage_storage_kms_iam / enable_artifact_registry_cmekfalseCMEK options.

Group 12 — Database Backend

VariableDefaultDescription
database_typePOSTGRES_15Fixed; NetBox requires PostgreSQL 14+.
db_namenetboxPostgreSQL database name. Immutable after first deploy.
db_usernetboxApplication database user. Password auto-generated in Secret Manager.
database_password_length32Generated password length (16–64).
enable_auto_password_rotation / rotation_propagation_delay_secoffDB password rotation.

Group 13 — Jobs & Scheduled Tasks

VariableDefaultDescription
initialization_jobs[]Leave empty to use the built-in db-init job.
cron_jobs[]Not forwarded — NetBox has no platform-scheduled recurring tasks; its own scheduled jobs run through the co-located RQ worker instead.
additional_services[]Additional Cloud Run services deployed alongside NetBox.

Group 14 — Observability & Health

VariableDefaultDescription
startup_probeHTTP /login/, 60s delay, 60 failure thresholdNetBox-specific startup probe (takes effect).
liveness_probeHTTP /login/, 30s failure windowNetBox-specific liveness probe.
startup_probe_config / health_check_configgeneric App_CloudRun defaultsAlternative structured probes; superseded by startup_probe/liveness_probe above.
uptime_check_config{ enabled=true, path="/login/" }Cloud Monitoring uptime check.
alert_policies[]Metric alert policies.

Group 15 — NetBox Application Settings

VariableDefaultDescription
time_zoneUTCTimezone for NetBox timestamps and scheduled tasks.
admin_useradminUsername for the auto-created superuser. Creation is idempotent — skipped if it already exists.
admin_emailadmin@example.comEmail for the auto-created superuser.

Group 21 — Redis Cache & Queue

VariableDefaultDescription
enable_redistrueRequired. Backs NetBox's RQ task queue and cache layer. NetBox cannot run without it.
redis_host""Redis endpoint. Leave empty to use the NFS server IP (requires enable_nfs = true).
redis_port6379Redis port.
redis_auth""Optional Redis auth password (sensitive).

Group 22 — VPC Service Controls & Audit Logging

VariableDefaultDescription
enable_vpc_scfalseEnforce a VPC-SC perimeter (requires organization_id).
vpc_cidr_ranges / vpc_sc_dry_run(set)Access level CIDRs / dry-run mode.
enable_audit_loggingfalseDetailed Cloud Audit Logs.

5. Outputs

Returned on a successful deployment — the quickest way to locate and explore the running resources.

OutputDescription
service_nameCloud Run service name.
service_urlPublic run.app URL of the NetBox web UI.
service_locationRegion the service runs in.
stage_servicesStage-specific service details (Cloud Deploy).
load_balancer_ip / load_balancer_urlExternal HTTPS load balancer IP / URL (when enabled).
database_instance_nameCloud SQL instance name.
database_name / database_userApplication database name / user.
database_password_secretSecret Manager secret holding the DB password.
database_host / database_portDB endpoint / port.
storage_bucketsCreated Cloud Storage buckets.
network_name / network_exists / regionsVPC network, presence, regions.
container_image / container_registryDeployed image and Artifact Registry repo.
monitoring_enabled / monitoring_notification_channels / uptime_check_namesMonitoring status, channels, uptime checks.
initialization_jobsNames of the setup jobs.
deployment_id / tenant_id / resource_prefixNaming identifiers.
project_id / project_numberProject identifiers.
cicd_enabled / github_repository_url / github_repository_owner / github_repository_name / cicd_configurationCI/CD status and details.
artifact_registry_repository / cloudbuild_trigger_name / cloudbuild_trigger_idRegistry and build trigger.
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_modeVPC-SC status.
audit_logging_enabled / artifact_registry_cmek_enabledAudit logging and CMEK status.

6. Configuration Pitfalls & Sensible Defaults

Risk: Critical (data loss / outage / security) — High (service degraded) — Medium (cost or partial degradation) — Low (minor).

Inherited plan-time validation. This module passes its configuration through the App_CloudRun foundation engine, which validates values and combinations at plan time — a read replica without its primary, IAP with no authorized identities, a gen1 runtime with NFS/GCS mounts, an out-of-range redis_port/backup_retention_days. Invalid configuration fails the plan with a clear, named error before any resource is created, so most mistakes below are caught up front rather than at apply or runtime.

SettingSensible valueRiskConsequence if wrong
gcs_volumes mount path (auto-set to /etc/netbox/media)Never override to a different path unless you've confirmed NetBox's real MEDIA_ROOTCriticalA wrong mount path leaves uploads on the ephemeral container filesystem — they read back fine immediately, but are silently lost on every restart with no error. This exact bug was found and fixed on this module's earlier /opt/netbox/netbox/media mount.
SECRET_KEY (auto-generated)Never rotate after first bootCriticalRotating it invalidates all active sessions and signed cookies; NetBox also enforces a minimum 50-character length.
SUPERUSER_PASSWORD (auto-generated)Rotate via the NetBox UI, not by regenerating the secretMediumRegenerating the Secret Manager value does not retroactively change the already-created admin account's password.
db_name / db_userSet onceCriticalImmutable after first deploy; renaming recreates the DB/user and destroys all data.
enable_backup_importfalse unless restoringCriticalEnabling without a valid backup_uri fails the import job.
enable_redistrue (mandatory)CriticalNetBox's background task system (webhooks, reports, scripts, scheduled jobs) and its cache layer do not function without Redis — there is no fallback mode.
redis_host"" (NFS) or explicitHighWhen Redis is on but NFS is off and no host is set, the Redis connection is blank and background processing silently never runs.
REDIS_DATABASE / REDIS_CACHE_DATABASEKeep separate (0 / 1)HighSharing one logical Redis database risks losing queued background tasks during a cache flush, per NetBox's own documentation.
memory_limit2GiHighValues below 1Gi risk OOM kills, especially with the RQ worker co-located in the same container.
cpu_always_allocated / min_instance_counttrue + >=1 if background jobs must run continuouslyMediumAt the cost-first default (false / 0), webhooks/reports/scheduled jobs only run while a request keeps the instance warm — they queue instead of executing immediately.
ALLOWED_HOSTS / CORS_ORIGIN_ALLOW_ALL (auto-injected "*" / "true")Tighten for production internet-facing useMediumLeft open, any hostname/origin is accepted — acceptable for a first deploy, not for a hardened production instance.
CSRF_TRUSTED_ORIGINS (auto-computed)Verify it matches the actual service URL after deployHighA stale or incorrect value rejects every authenticated POST, including login, with a CSRF failure.
ingress_settingsall for public accessMediuminternal blocks browser access to the login/setup flow unless reached via VPN/IAP.
backup_retention_days7 (raise for prod)MediumToo short for compliance retention.
enable_cloud_armorenable for productionMediumThe admin UI is publicly reachable without WAF protection by default.

For the foundation behaviour referenced throughout — service identity, scaling and concurrency, ingress and load balancing, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, backups, and image mirroring — see App_CloudRun. NetBox-specific application configuration shared with the GKE variant is described in Netbox_Common.