Initial configuration

This section describes how the product will be configured after installation for Nomad Enterprise deployments. It may take several weeks to work through all of the recommendations from each section, but this should be the primary focus of the Nomad Enterprise platform operators after the initial deployment of Nomad Enterprise has been completed. Establishing these foundational configuration best practices before targeting consumer workflows is crucial. This will ensure a stable foundation for both current and future growth.

After a Nomad deployment has been set up and bootstrapped, follow these steps to configure your Nomad servers:

1. Enable mTLS and gossip encryption(opens in new tab)
2. Enable and configure access control lists and OIDC for RBAC
3. Set up automated upgrades to ensure Nomad cluster stays up-to-date with the latest features and security patches
4. Implement a robust backup strategy to protect your Nomad cluster's state and configuration
5. Load balance and reverse proxy for Nomad's web UI(opens in new tab)
6. Use Terraform to manage Nomad configuration as code, enabling version control and reproducibility

Configure Nomad as Code

When managing Nomad Enterprise configurations, prioritize automation from the start. While organizations may adopt different GitOps and configuration management practices, avoiding manual changes to your Production Nomad Enterprise environment to minimize inconsistencies and control change promotion across environments.

Implement a Git-based workflow as the primary method for modifying Nomad configuration through pull or merge requests:

1. Block direct commits to the main branch linked to production configuration.
2. Require approvals and code reviews for pull requests.
3. Restrict manual operator-level changes to reduce drift between code-defined configuration and real-world state.
4. Stick to a single configuration style when possible.

There are two main approaches for configuring Nomad Enterprise:

Terraform

• Manages configuration state, maintaining a system of record and single source of truth, overwriting any changes made when using a different configuration method.
• HCP Terraform and Terraform Enterprise customers can leverage advanced self-service capabilities such as private module registry, no-code modules, and Sentinel.
• Preferred for automating day 2 resources, such as namespaces, node pools, etc.
• Provides a single central place to manage configurations.

API and CLI

• Covers all configuration options.
• Requires additional logic for dependencies, creation ordering, and existing state management.
• More challenging and time consuming to build configuration workflows.

Choose Terraform as the primary method when possible, as it simplifies management and provides better control. However, the API and CLI are valuable for configurations not covered by Terraform or for specific use cases requiring fine-grained control.

GitOps repository structure

In the earlier stages of adoption, it is common for the central team operating Nomad to use one monolithic configuration repo where the policies and roles, and configuration values are defined for all consumers.

nomad-config/ 
├── main.tf 
├── variables.tf 
├── outputs.tf 
├── node_pools/ 
│ ├── general.tf 
│ └── gpu.tf 
├── namespaces/ 
│ ├── production.tf 
│ ├── staging.tf
│ └── development.tf
├── resource_quotas/
│ ├── production_quota.tf
│ ├── staging_quota.tf 
│ └── development_quota.tf 
└── sentinel_policies/ 
  ├── enforce_docker.tf
  └── restrict_job_priority.tf

As adoption matures, consider splitting your repository based on specific components or teams. Alternatively, for organizations anticipating significant Nomad adoption and growth, consider implementing a distributed repository structure from the beginning. This approach involves creating separate repositories for different components or teams, rather than starting with a monolithic configuration repository. This strategy can provide better scalability and delegation of responsibilities as your Nomad usage expands.

nomad-core-config/ 
├── main.tf
├── variables.tf
├── outputs.tf
├─nomad-sentinel-policies/
| ├── main.tf
| ├── enforce_docker.tf
| └── restrict_job_priority.tf
└─nomad-node-pools/ 
  ├── general.tf
  └── gpu.tf
 
nomad-team-namespaces/
├── main.tf
├── team_alpha.tf
├── team_beta.tf
└── team_gamma.tf
nomad-team-resource-quotas/
├── main.tf
├── team_alpha_quota.tf 
├── team_beta_quota.tf
└── team_gamma_quota.tf

The repo structures above are basic examples to get started. Terraform modules and workflows and their best practices are out of scope of this document, but can be found in the Terraform Style Guide. For more detailed information on Terraform modules and workflows, visit the Terraform Validated Design pages at Infrastructure-as-code and cloud provisioning(opens in new tab) and Terraform Workflows(opens in new tab).