Running Docker Containers in HashiCorp Nomad: A Beginner’s Guide

Learn to seamlessly deploy and orchestrate Docker containers with HashiCorp Nomad using simple configurations and tools. Whether you're deploying a simple web server or experimenting with microservices, this guide will provide you with the foundation to get started.

What Is Nomad?

Nomad is a simple, flexible, and scalable workload orchestrator that supports running containerized and non-containerized applications. Though it is not as popular as Kubernetes, which currently dominates the container orchestration space, Nomad has its advantages: ease of use, lightweight architecture, and support for mixed workloads.

Prerequisites

Before running Docker containers in Nomad, ensure the following:

1. Nomad Installed: Download and install Nomad from HashiCorp's website.

2. Docker Installed: Install Docker and confirm it is running with:
   docker --version

3. Nomad Agent Running: Start a Nomad agent in development mode for simplicity. The -dev flag starts a local Nomad cluster in development mode:
   nomad agent -dev

Step 1: Write a Nomad Job File

Nomad uses job specification files written in HashiCorp Configuration Language (HCL) to define the jobs it manages. Below is a basic example of a Nomad job file (docker.nomad) to run an NGINX web server.

Example: Simple Nomad Job File

job "nginx-job" {

  datacenters = ["dc1"]

  group "web-group" {

    count = 1

    task "nginx" {

      driver = "docker"

      config {

        image = "nginx:latest"  # Docker image to run

        ports = ["http"]

      }

      resources {

        network {

          port "http" {

            static = 8080  # Expose container on host's port 8080

          }

        }

      }

    }

  }

}

Explanation of the Job File

• job: Defines the job name and datacenter to deploy to.

• group: Groups related tasks (containers) together.

• task: Specifies a single container to run, including the driver (docker) and configuration.

• config: Contains Docker-specific settings like the image to use and ports to expose.

• resources: Defines resource limits and networking settings for the container.

Step 2: Run the Nomad Job

Submit the job file to the Nomad cluster using the nomad run command:
nomad run docker.nomad

This will schedule the NGINX container on the Nomad agent. If successful, you’ll see output indicating that the job has been successfully deployed.

Step 3: Verify the Job

Check the status of the job using:
nomad status nginx-job

You should see the job details, including its allocation ID and deployment status.

Step 4: Access the Running Container

1. Find the IP address of the host running the container. If you're running locally, it’s likely 127.0.0.1.

2. Open a web browser and visit http://localhost:8080. You should see the default NGINX welcome page.

Step 5: Stop the Job

To stop the container, use the nomad stop command:
nomad stop nginx-job

This will cleanly shut down the container managed by Nomad.

Advanced Examples

1. Add Environment Variables

You can pass environment variables to your Docker container using the env block in the task section:

task "nginx" {

  driver = "docker"

  config {

    image = "nginx:latest"

    ports = ["http"]

  }

  env {

    APP_ENV = "production"

  }

}

2. Mount Volumes

To mount a host directory into the container, use the volumes option in the config block:

task "nginx" {

  driver = "docker"

  config {

    image = "nginx:latest"

    ports = ["http"]

    volumes = ["/host/path:/container/path"]

  }

}

3. Scale Containers

To scale the container to multiple instances, modify the count parameter in the group section:

group "web-group" {

  count = 3  # Run 3 instances of the container

}

Nomad will distribute the instances across available nodes in your cluster.

Tips for Beginners

1. Test in Development Mode: Start with the nomad agent -dev command for quick local testing before deploying to a production cluster.

2. Leverage Nomad's Web UI: Use the Nomad UI (enabled by default in dev mode) to monitor jobs and allocations visually. Access it at http://localhost:4646.

3. Use Logs for Debugging: Check logs for troubleshooting with:
   nomad logs 

Conclusion

Running Docker containers with HashiCorp Nomad is a straightforward and powerful way to orchestrate workloads. By defining jobs in simple HCL files, you can easily deploy, monitor, and scale containers across your infrastructure. Whether you're just starting or looking for an alternative to Kubernetes, Nomad’s simplicity and flexibility make it an excellent choice for managing containerized applications.

About ZippyOPS:
We provide consulting, implementation, and management services on DevOps, DevSecOps, DataOps, Cloud, Automated Ops, AI Ops, ML Ops, Microservices, Infrastructure, and Security Services. Learn more about our services, products, and solutions. For demo videos, check out our YouTube Playlist. If this seems interesting, please email us at [email protected] for a call.