Skip to main content

Install Traefik Hub Gateway on Nomad

Prequisites​

  • Access to a Nomad cluster.
  • A Traefik Hub Gateway token (HUB_TOKEN) to use licensed Hub features.
    • If you don't have a token yet, skip it to run Traefik Hub in Proxy Mode. This means that you can access Traefik Proxy features but not Hub features, till you apply a valid license. Add a token later without redeploying.

Step1: Deploy Traefik Hub API Gateway​

With Nomad installed and configured on your machine, you can deploy Traefik Hub using the following steps:

  1. Store the Traefik Hub token as a Nomad Variable, so it's encrypted at rest in Nomad's keyring and only readable by the task via scoped workload identity:
nomad var put nomad/jobs/traefik-hub TRAEFIK_HUB_TOKEN=<YOUR_HUB_TOKEN>

Replace <YOUR_HUB_TOKEN> with the Traefik Hub token from your new Gateway. Select Nomad as the platform while creating a new Gateway.

If you don't have a token yet, skip this step to run Traefik Hub in Proxy Mode — leave TRAEFIK_HUB_TOKEN unset and the gateway starts without Hub features until you add a token later.

  1. Create a Nomad job file for Traefik Hub. We’ll name it traefik-hub.nomad:
Install Traefik Hub API Gateway using Nomad
sudo tee /etc/nomad.d/traefik-hub.nomad > /dev/null <<EOF
job "traefik-hub" {
  datacenters = ["dc1"]

  group "traefik" {

    network {
      mode = "bridge"
      port "web" {
        static = 8080
      }
    }

    service {
      name = "traefik"
      provider = "nomad"
      tags = [
        "traefik.enable=true",
        "traefik.http.routers.traefik.entrypoints=web",
        "traefik.http.routers.traefik.rule=PathPrefix(`/api`) || PathPrefix(`/dashboard`)",
        "traefik.http.routers.traefik.service=api@internal",
        "traefik.http.services.dummy-svc.loadbalancer.server.port=9999"
      ]
    }


    count = 1

    task "traefik" {

      driver = "docker"

      template {
        data        = <<EOT
TRAEFIK_HUB_TOKEN={{ with nomadVar "nomad/jobs/traefik-hub" }}{{ .TRAEFIK_HUB_TOKEN }}{{ end }}
EOT
        destination = "secrets/traefik.env"
        env         = true
      }

      config {
        image = "ghcr.io/traefik/traefik-hub:v3"

        args = [
          "traefik-hub",
          "--entryPoints.web.address=:8080/tcp",
          "--api.dashboard=true",
          "--providers.nomad.endpoint.address=<your-machine-ip>:4646",
          "--providers.nomad.exposedByDefault=false",
          "--log.level=DEBUG"
        ]

      ports = ["web"]
      cap_add = ["NET_BIND_SERVICE"]
      cap_drop = ["ALL"]
  }

      resources {
        cpu    = 500
        memory = 256
      }
    }
  }
}
EOF
info
  • We’re using the docker driver, which interfaces with containerd through Nomad.
  • We’re binding directly to ports 80, 443, and 8080.
Offline Mode

Working in an air-gapped environment? Want to install Traefik Hub API Gateway in an offline mode?

Check out the Offline Mode documentation.

  1. Run the Traefik Hub job using the Nomad CLI:
nomad job run traefik-hub.nomad

We should see output indicating that the job has been registered and dispatched.

Command Output
ID            = traefik-hub
Name          = traefik-hub
Submit Date   = XXXX
Type          = service
Priority      = 50
Datacenters   = dc1
Namespace     = default
Node Pool     = default
Status        = running
Periodic      = false
Parameterized = false

Summary
Task Group  Queued  Starting  Running  Failed  Complete  Lost  Unknown
traefik     0       0         1        0       0         0     0

Latest Deployment
ID          = ef7b3c7a
Status      = successful
Description = Deployment completed successfully

Deployed
Task Group  Desired  Placed  Healthy  Unhealthy  Progress Deadline
traefik     1        1       1        0          2024-11-06T14:49:45Z

Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created    Modified
4865d2bf  3b9a52c8  traefik     0        run      running  2m54s ago  2m22s ago

Step 2: Verify the Installation​

Now that Traefik Hub is deployed, We can verify our access to the Traefik Hub Dashboard by navigating to:

http://localhost:8080/dashboard/

# OR

http://<your-machine-ip>:8080/dashboard/

We should see the Traefik Hub local dashboard.

http://localhost:8080/dashboard/

&quot;Traefik Hub Dashboard&quot;

If we head over to the Traefik Hub SaaS platform we should see that the Gateway is online.

Conclusion​

In this guide, we’ve successfully:

  • Deployed Traefik Hub: Used Nomad to deploy Traefik Hub.
  • Verified the installation: Accessed the Traefik Hub dashboard to confirm it’s running correctly.

Related content​

  • Read about the Consul Catalog Enterprise provider in Traefik Hub in its dedicated section.
  • Learn more about integrating Traefik Hub and Consul Connect in this tutorial.