Nomad Nodes

Overview #

This guide describes how to create and run a StrongDM node (gateway or relay) on HashiCorp Nomad.

To learn more about gateways and relays in general, see Nodes.

Prerequisites #

• Be an Administrator in StrongDM.
• Ensure that you have a running Nomad instance and are familiar with the Nomad CLI or Nomad Web UI.

Steps #

Add a node in the Admin UI #

You can add either a gateway (allows ingress) or relay (egress connections only) using Nomad.

Add a gateway #

To add a gateway, follow these steps.

1. Log in to the StrongDM Admin UI at app.strongdm.com.
2. Go to Networking > Gateways and click Add gateway.
3. For Name, enter a unique name for the gateway. This is the name that is displayed throughout StrongDM.
4. For Advertised Host, use the IP address or hostname of your Nomad server.
5. For Advertised Port, edit the port number if you want it to differ from the default 5000.
6. Click Advanced to set optional properties.
7. For Bind IP, optionally set the IP address for the gateway to listen on. You can use 0.0.0.0 for all interfaces.
8. For Bind Port, optionally set the port for the gateway to listen on (default: 5000).
9. Click Create gateway to save.
10. Copy the token that is generated. This token is used in later steps.

Add a relay #

To add a relay, follow these steps.

1. Log in to the StrongDM Admin UI.
2. Go to Networking > Relays.
3. Click Add relay.
4. For Name, enter a name for the relay.
5. Click Create relay.
6. Copy the token and keep it in a secure place.

Create the node on Nomad #

You can choose one of two ways to create a StrongDM node on Nomad. You can use either the Nomad CLI or Nomad Web UI.

Use the Nomad CLI #

1. Use SSH to log in to your Nomad server.
2. Use a text editor to create a new file called sdm-gateway.nomad.hcl.
3. Copy the following example code and paste it into your file:

variable "datacenters" {
  type = list(string)
  default = ["dc1"]
}

variable "sdm_relay_token" {
  type    = string
}

job "sdm" {
  datacenters = var.datacenters
  
  # Add namespace if using one
  # namespace = "default"
  
  # Add type specification
  type = "service"
  
  group "gateways" {
    count = 1
    
    network {
      port "gateway" {
        static = 5000
        to     = 5000
      }
    }
    
    # Add service registration
    service {
      name = "sdm-gateway"
      port = "gateway"
      provider = "nomad"
      tags = ["sdm"]
      check {
        type     = "tcp"
        port     = "gateway"
        interval = "30s"
        timeout  = "2s"
      }
    }
    
    task "server" {
      driver = "docker"
      
      config {
        image = "public.ecr.aws/strongdm/relay"
      }
      
      resources {
        cpu    = 2000 # MHz
        memory = 4096 # MB
      }
      
      # Add template for secrets management (optional)
      template {
        data = <<EOT
SDM_RELAY_TOKEN="${var.sdm_relay_token}"
EOT
        destination = "${NOMAD_SECRETS_DIR}/env.txt"
        env         = true
      }
      
      # Add restart policy
      restart {
        attempts = 3
        delay    = "30s"
        interval = "5m"
        mode     = "delay"
      }
    }
    
    # Add update strategy
    update {
      max_parallel = 1
      health_check = "checks"
      min_healthy_time = "10s"
      healthy_deadline = "5m"
      auto_revert = true
    }
  }
}

4. In your file, replace the $datacenters and $SDM_RELAY_TOKEN placeholders with the actual values. If you added a gateway in the Admin UI and changed the port to a port other than the default, change the port here too.

5. Save and close the file.

6. Create a new job:

   nomad job init sdm-gateway
   

7. Do a dry run to make sure there are no issues:

nomad job plan sdm-gateway

8. Start the job:

nomad job run sdm-gateway

Use the Nomad Web UI #

1. Log in to the Nomad Web UI.
2. Go to the Jobs tab.
3. Click Run Job.
4. Copy the following example code:

variable "datacenters" {
  type = list(string)
  default = ["dc1"]
}

variable "sdm_relay_token" {
  type    = string
}

job "sdm" {
  datacenters = var.datacenters
  
  # Add namespace if using one
  # namespace = "default"
  
  # Add type specification
  type = "service"
  
  group "gateways" {
    count = 1
    
    network {
      port "gateway" {
        static = 5000
        to     = 5000
      }
    }
    
    # Add service registration
    service {
      name = "sdm-gateway"
      port = "gateway"
      provider = "nomad"
      tags = ["sdm"]
      check {
        type     = "tcp"
        port     = "gateway"
        interval = "30s"
        timeout  = "2s"
      }
    }
    
    task "server" {
      driver = "docker"
      
      config {
        image = "public.ecr.aws/strongdm/relay"
      }
      
      resources {
        cpu    = 2000 # MHz
        memory = 4096 # MB
      }
      
      # Add template for secrets management (optional)
      template {
        data = <<EOT
SDM_RELAY_TOKEN="${var.sdm_relay_token}"
EOT
        destination = "${NOMAD_SECRETS_DIR}/env.txt"
        env         = true
      }
      
      # Add restart policy
      restart {
        attempts = 3
        delay    = "30s"
        interval = "5m"
        mode     = "delay"
      }
    }
    
    # Add update strategy
    update {
      max_parallel = 1
      health_check = "checks"
      min_healthy_time = "10s"
      healthy_deadline = "5m"
      auto_revert = true
    }
  }
}

5. In the Job Definition section, paste that example code.
6. Replace the $datacenters and $SDM_RELAY_TOKEN placeholders with the actual values. If you added a gateway in the Admin UI and changed the port to a port other than the default, change the port here too.
7. Click Plan.
8. Ensure no errors occurred.
9. Click run.

Verify that your node is online #

In the Admin UI, go to Networking > Gateways or Networking > Relays to verify that the node you created is online.

If it does not appear online, perform a hard refresh of your web browser. Within a couple of minutes, if it is still not online, verify that the StrongDM daemon is running by running ps aux|grep sdm on the server and looking for sdm relay in the output.