Skip to content

Migrate NetBox from Docker on ctrl-01 to RKE2 Using PostgreSQL LXC

This HOWTO describes how to migrate NetBox from a Docker deployment on ctrl-01 to an RKE2-based deployment, while keeping PostgreSQL in the db-01 LXC as the shared system of record.

It builds on:

The goal is to:

  • Move NetBox’s compute from Docker on ctrl-01 → RKE2.
  • Keep the database on db-01 (PostgreSQL LXC) with continuity.
  • Perform a controlled cutover window with clear rollback.

1. Objectives

By the end of this HOWTO you will be able to:

  • Prepare an RKE2-based NetBox deployment that reuses the existing PostgreSQL database on db-01.
  • Plan and execute a short migration window from Docker → RKE2.
  • Validate NetBox behaviour after cutover.
  • Capture migration evidence under output/artifacts/apps/netbox/.

2. Prerequisites

2.1 Platform state

You should have:

  1. Existing NetBox on ctrl-01 (Docker)

  2. Running NetBox container on ctrl-01 with:

    • NETBOX_DB_* pointing at db-01.

  3. Access to logs and configuration for this instance.

  4. RKE2 cluster running

  5. RKE2 cluster available and reachable with kubectl.

  6. Namespace plan ready (for example, network-platform).

  7. PostgreSQL LXC (db-01)

  8. PostgreSQL LXC (db-01) running on Proxmox, as per ADR-0013.

  9. NetBox database (netbox) and user (netbox_user) already in place.

  10. Regular backups configured.

  11. RKE2 NetBox deployment defined

  12. You have followed or are ready to follow:
    HOWTO – Deploy NetBox on RKE2 Using PostgreSQL LXC

  13. RKE2 manifests/Helm values prepared to point at the same db-01 instance.

2.2 Access and tooling

  • SSH access to ctrl-01 and Proxmox hosts.
  • kubectl access to RKE2.
  • Ability to reach NetBox UI endpoints from a browser.

2.3 Evidence location

Use:

mkdir -p output/artifacts/apps/netbox/migration-docker-to-rke2-<date>/

Replace <date> with a timestamp (for example, 2025-12-02T200000Z).

3. Migration strategy

The migration strategy is:

  1. Prepare RKE2 NetBox deployment pointing to db-01.
  2. Choose a short migration window and notify stakeholders.
  3. Put Docker NetBox in maintenance / drain mode.
  4. Deploy NetBox on RKE2 and validate.
  5. Switch users/DNS from Docker → RKE2.
  6. Monitor, then optionally decommission Docker instance.

Because PostgreSQL stays on db-01, the migration focuses on the application layer, not data movement.

4. Phase 1 – Prepare RKE2 NetBox deployment

  1. Ensure db-01 state and connectivity

  2. From ctrl-01 or an RKE2 node:

    psql -h <db01-hostname> -U netbox_user -d netbox -c "SELECT now();"

  3. Save the output to:

    psql -h <db01-hostname> -U netbox_user -d netbox -c "SELECT now();"        > output/artifacts/apps/netbox/migration-docker-to-rke2-<date>/db-connectivity-pre.txt

  4. Prepare RKE2 manifests/Helm values

  5. Follow the deployment HOWTO:
    HOWTO – Deploy NetBox on RKE2 Using PostgreSQL LXC

  6. Ensure:

    • DB_HOST points to db-01.
    • Credentials match the existing NetBox DB user.
    • Namespace is chosen (for example, network-platform).
    • Ingress/service is configured for the target URL.

  7. Dry-run manifests (if supported)

  8. For Helm:

    helm template netbox ./charts/netbox -f values-netbox-rke2.yaml > /tmp/netbox-rendered.yaml

  9. For raw manifests, run kubectl apply --dry-run=server.

  10. Check for obvious errors.

5. Phase 2 – Plan and announce migration window

  1. Confirm usage pattern

  2. Identify if NetBox is:

    • Primarily used by you (lab/portfolio) or
    • Shared with others (wider team).

  3. Choose a migration window

  4. Select a low-usage period.

  5. Decide whether to enforce read-only/maintenance mode or accept a brief full outage.

  6. Announce the change

  7. For shared environments:

    • Announce that NetBox will be briefly unavailable or degraded while migrating to RKE2.
  8. For solo/lab use:
    • Log the window in a short text file under the migration proof folder.

6. Phase 3 – Put Docker NetBox into maintenance mode

  1. Identify the running container on ctrl-01
ssh <user>@ctrl-01
docker ps --format 'table {{.Names}} {{.Status}} {{.Ports}}'

  1. Optional: enable maintenance banner in NetBox

  2. If configured, toggle a maintenance banner or message in NetBox (config or UI) to signal impending downtime.

  3. Capture baseline

  4. Take a quick screenshot of the current NetBox UI and store under:

    • output/artifacts/apps/netbox/migration-docker-to-rke2-<date>/before-ui.png

  5. Stop Docker NetBox

At the start of the migration window:

docker stop <netbox-container-name>
  • Optionally also stop any associated worker containers (if used).
  • Record the exact time in the migration notes.

After this step, NetBox will be unavailable until the RKE2 instance is up.

7. Phase 4 – Deploy NetBox on RKE2

  1. Deploy on RKE2

  2. Using Helm example:

    kubectl create ns network-platform || true

helm upgrade --install netbox ./charts/netbox        -n network-platform        -f values-netbox-rke2.yaml

  3. Or apply K8s manifests.

  4. Wait for pods to become Ready

kubectl get pods -n network-platform

  • Save output:

    kubectl get pods -n network-platform        > output/artifacts/apps/netbox/migration-docker-to-rke2-<date>/kubectl-get-pods-netbox.txt

  • Check logs for DB connectivity

kubectl logs deploy/netbox -n network-platform | tail -n 50

  • Confirm:

    • No DB authentication/connection errors.
    • NetBox startup completes successfully.

  • Port-forward for validation (optional)

kubectl port-forward -n network-platform deploy/netbox 8001:8001
  • Open http://localhost:8001/ and check UI loads.

8. Phase 5 – Cut over access to RKE2 NetBox

  1. Confirm application health

  2. Log in to the RKE2 NetBox instance.

  3. Verify:

    • You can see existing sites/devices.
    • Data matches what you expect from the Docker-based instance.

  4. Update DNS or access URL

Depending on how users access NetBox today:

  • If they use a hostname (for example, netbox.internal.local) pointing at ctrl-01:
    • Update DNS to point at the RKE2 ingress/entry point.

  • If there is no DNS and you use a direct URL:

    • Update documentation and bookmarks to use the RKE2 address.

  • Re-test from user perspective

  • From a normal client machine:

    • Open the NetBox URL.
    • Confirm login and basic navigation work.

  • Record cutover time

  • Note the exact time you updated DNS/URL in your migration notes.

  • Save a screenshot of the RKE2 NetBox UI to the proof folder.

9. Phase 6 – Post-migration checks and rollback plan

  1. Run basic functional tests

  2. Create and delete a test object (for example, a dummy site or device) to confirm write operations.

  3. Check that data appears consistent and there are no obvious performance issues.

  4. Monitor logs

  5. Watch NetBox logs and PostgreSQL logs on db-01 for any errors.

  6. Rollback option (if needed)

If serious issues appear:

  • Stop or scale down the RKE2 NetBox deployment.

  • Restart the Docker container on ctrl-01:

    docker start <netbox-container-name>

  • Revert DNS/URL to ctrl-01 NetBox.

  • Document the reason for rollback in the migration notes.

  • Decommission Docker NetBox (once stable)

After a stabilisation period:

  • Remove the Docker NetBox container and, if appropriate, related images.
  • Keep configuration backups for historical reference.
  • Ensure all future operations/automation target the RKE2 NetBox instance.

10. Evidence and documentation

Before closing the migration:

  1. Ensure output/artifacts/apps/netbox/migration-docker-to-rke2-<date>/ contains:

  2. Pre- and post- kubectl get pods output.

  3. DB connectivity checks.
  4. Screenshots of old (Docker) and new (RKE2) UIs.

  5. Notes on cutover times and any issues encountered.

  6. Update:

  7. Evidence 3 (if needed) with a brief mention of the migration.

  8. Any internal documentation pointing at the old Docker deployment.

  9. If this migration will be shown in a portfolio or video:

  10. Capture short terminal and UI clips showing:

    • Docker NetBox running.
    • Stopping Docker & deploying to RKE2.
    • NetBox running successfully on RKE2.

11. Validation checklist

  • [ ] RKE2 deployment of NetBox is configured to use PostgreSQL on db-01.
  • [ ] Docker-based NetBox on ctrl-01 was cleanly stopped at the start of the window.
  • [ ] NetBox pods on RKE2 are Running and logs show successful startup.
  • [ ] Users can reach NetBox via the new (RKE2) endpoint/DNS entry.
  • [ ] Basic operations (viewing/creating objects) work as expected.
  • [ ] Evidence artefacts stored under output/artifacts/apps/netbox/.
  • [ ] Rollback plan was documented, and either not needed or executed successfully.

References

Maintainer: HybridOps.Studio
License: MIT-0 for code, CC-BY-4.0 for documentation