HashiCorp Nomad (cluster)

Deploy HashiCorp Nomad, a workload scheduler and orchestrator that lets you deploy and manage containerized or non-containerized applications using a single, unified workflow. Nomad uses bin packing for efficient job scheduling and resource optimization, and supports declarative infrastructure-as-code for your deployments.

📘
Cluster deployment
This app deploys six Linode instances (three Nomad servers and three Nomad clients) to create a highly available HashiCorp Nomad cluster, each with the plan type and size you select.
Each of these Linode instances will appear on your invoice as separate items. To deploy Nomad on a single instance instead, see HashiCorp Nomad.

1. Deploy HashiCorp Nomad `cluster`

Estimated deployment time: 15–20 minutes

Follow the deployment instructions from the Get started section to configure the app, deploy it, and verify software installation.

For information on the app-specific configurations, see the Configuration options section.

Base distribution and plan

Supported distribution: Ubuntu 24.04 LTS
Recommended plans: Use an 8GB Dedicated CPU or 8GB Shared CPU instance.

Configuration options

Configure the required options to deploy your instance. For additional customization, add advanced options.

The table maps the Cloud Manager UI fields to their corresponding API/CLI keys (stackscript_data) required for automated deployments.

StackScript ID: 1226544

UI field	API/CLI key	Description
Required options
Linode API token	`token_password`	The Linode API token used to deploy the additional Linode instances that make up this cluster. Follow Manage personal access tokens to get a token on your account with `Read/Write` access to `Linodes`.
Limited sudo user	`sudo_username`	Your preferred username for the limited sudo user, entered without any capital letters, spaces, or special characters. When adding a limited sudo user, the account is assigned to the `sudo` group, which provides elevated permissions when running commands with the `sudo` prefix. Note: For easier and more secure access with the sudo user, add an account SSH key for the Cloud Manager user during deployment and select that user as an `authorized_user`. Their SSH pubkey will be assigned to both the root and limited sudo users.
Email Address	`email_address`	A valid email address used for generating SSL certificates.
Advanced options
Cluster Settings	`clusterheader`	Set to Yes by default. Details of the cluster settings, including instance counts and whether to add account SSH keys to all nodes.
Add Account SSH Keys to All Nodes	`add_ssh_keys`	When set to yes, any SSH keys that are added to the root user account (in the SSH Keys section), are also added to your limited user account on all deployed Linode instances. Possible values are yes or no. Defaults to yes.
Total Instance count	`cluster_size`	The total number of Linode instances deployed for this cluster. Value is fixed at 6 (3 servers and 3 clients).
Nomad Server count	`servers`	The number of Nomad servers deployed. Value is fixed at 3.
Nomad Client size	`clients`	The number of Nomad clients deployed. Value is fixed at 3.

Note: After the app deployment completes, the password for your limited sudo user and other generated tokens are stored in the ~/.deployment-secrets.txt file on the first provisioned instance, labeled occ-server-1. Log in to your instance as root through the Lish console or SSH, then run cat ~/.deployment-secrets.txt to view its contents.

Use API, CLI, or Terraform

In addition to deploying the app to a new Linode instance via Cloud Manager, you can also use the Linode API, CLI, or Terraform. When running the operation, you need to provide the StackScript ID, supported Linux distribution, and app-specific fields along with the standard Linode deployment configurations.

Note: Generate a personal access token to authenticate your API, CLI, or Terraform requests.

curl --location 'https://api.linode.com/v4/linode/instances' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer abc123def456hij789klm' \
    --data-raw '{
        "region": "us-east",
        "type": "g6-dedicated-8",
        "image": "linode/ubuntu24.04",
        "label": "my-nomad-cluster-one-click-app",
        "root_pass": "@C0mpl3x#P@ssw0rd",
        "stackscript_id": 1226544,
        "stackscript_data": {
            "token_password": "abc123def456hij789klm",
            "sudo_username": "jsmith",
            "email_address": "jsmith@example.com"
        }
    }'

linode-cli linodes create \
    --region us-east \
    --type g6-dedicated-8 \
    --label my-nomad-cluster-one-click-app \
    --image linode/ubuntu24.04 \
    --root_pass @C0mpl3x#P@ssw0rd \
    --stackscript_id 1226544 \
    --stackscript_data '{"token_password":"abc123def456hij789klm", "sudo_username":"jsmith", "email_address":"jsmith@example.com"}'

resource "linode_instance" "my-linode" {
    region         = "us-east"
    type           = "g6-dedicated-8"
    label          = "my-nomad-cluster-one-click-app"
    image          = "linode/ubuntu24.04"
    root_pass      = "@C0mpl3x#P@ssw0rd"
    stackscript_id = 1226544
    stackscript_data = {
        "token_password" = "abc123def456hij789klm"
        "sudo_username"  = "jsmith"
        "email_address"  = "jsmith@example.com"
    }
}

2. Access the Nomad Web UI

Connect via SSH as the sudo user to the initially deployed instance, labeled occ-server-1.
View the contents of ~/.deployment-secrets.txt.
```
cat ~/.deployment-secrets.txt
```
This file contains multiple generated tokens and your limited sudo user password. These tokens are used for authenticating to the Nomad Web UI, adding Nomad clients to the cluster, managing jobs, and managing the Consul service mesh. Save the contents securely.
Open your web browser and navigate to http://[rDNS], replacing [rDNS] with the reverse DNS address of the instance labeled server-1.

See the How to Configure rDNS guide for details about viewing and editing rDNS.
On the Nomad Web UI, click the token link and enter the nomad_user_token from the ~/.deployment-secrets.txt file to authenticate.

Once authenticated, you can manage your cluster, jobs, integrations, and ACL tokens.

📘
HashiCorp recommends using mutual TLS (mTLS) with a private CA to secure cluster communications and the web UI. See the HashiCorp documentation for more details:

Enable TLS Encryption for Nomad

Nomad TLS Block Configuration

If you need additional clients for your cluster, see HashiCorp Nomad Clients (cluster) to scale horizontally by deploying three, five, or seven additional Linode instances as clients.

Additional resources

The HashiCorp Nomad cluster provides default configurations to get you started. For more information, see their official documentation.

📘
Note that we can't vouch for the accuracy or timeliness of externally hosted resources.

Cluster deployment

1. Deploy HashiCorp Nomad cluster

Base distribution and plan

Configuration options

Use API, CLI, or Terraform

2. Access the Nomad Web UI

Additional resources

1. Deploy HashiCorp Nomad `cluster`