notes/IT/Hashicorp Nomad.md

# Terminology
## Cluster Terms

| Phrase      | Definition                                                                                                                                                                                                     |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| agent       | A process running in server or client mode.                                                                                                                                                                    |
| client/node | A Nomad client is responsible for running tasks assigned to it. A client registers itself with servers and watches for work to be assigned. When running the agent, the client may be referred to as a *node*. |
| server      | A Nomad server manages all jobs and clients, monitors tasks, and controls which tasks get placed on which nodes.                                                                                               |
| dev_agent   | The development agent is an agent configuration that provides useful defaults for running a single node cluster of nomad.                                                                                      |

## Work terms
| Phrase                    | Definition                                                                                                                                                                                                                                                                        |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| task                      | The smallest unit of work in Nomad. Tasks are executed by task drivers like `docker` or `exec`, which allows Nomad to be flexible in the types of tasks it supports. Tasks specify their required task driver, configuration for the driver, constraints, and resources required. |
| task driver               | Task drivers are used by nomad clients to execute a task and provide resource isolation.                                                                                                                                                                                          |
| group                     | A series of tasks that run on the same Nomad client.                                                                                                                                                                                                                              |
| job                       | The core unit of *control* for Nomad and defines the application and its configuration. It can contain one or many tasks                                                                                                                                                          |
| service job               | A long lived service that runs until explicitly stopped                                                                                                                                                                                                                           |
| batch job                 | Short lived jobs that run until they exit successfully                                                                                                                                                                                                                            |
| job_specification/jobspec | A job specification, also known as a jobspec defines the schema for nomad jobs. This describes the type of the job, the tasks and resources necessary for the job to run, job information like which clients it can run on, or more.                                              |
| allocation                | An allocation is a mapping between a task group in a job and a client node. When a job is run, Nomad will chose a client capable of running it and allocates resources on the machine for the ask(s) in the task group defined for the job.                                       |
| workload artifact         | The runnable blob to be scheduled on a task driver. Examples include docker images, raw binaries, java applications, and VMs using QEMU.                                                                                                                                          |

# Typical Workflow
Running a task is generally done by:
1. *Define a job specification for your task(s):* it'll contain info like where the workload artifact is located, ports used by the service, the number of instances desired, and more.
2. *Deploying the job*: The jobspec is submitted to Nomad and it schedules an allocation for the job on one or more clients.
3. Updating and redploying the job. 

# Deployment
## Installing the CLI
https://developer.hashicorp.com/nomad/tutorials/get-started/gs-install#install-the-nomad-cli

## Creating a single node cluster
<https://stackoverflow.com/questions/56112422/nomad-configuration-for-single-node-to-act-as-production-server-and-client>
1. Install the `nomad` binary.
2. Create a config file with in `/etc/nomad.d` named `config.hcl`:
```hcl
# https://developer.hashicorp.com/nomad/docs/configuration
# The client block configures the Nomad agent to accept jobs as assigned
# by the server.
# https://developer.hashicorp.com/nomad/docs/configuration/client
client {
  enabled = true
}
# https://developer.hashicorp.com/nomad/docs/configuration/server
server {
  enabled = true
  # The number of server nodes to wait for before bootstrapping.
  bootstrap_expect = 1
}
# The local directory where agent state is stored. 
data_dir = "/opt/nomad"
name =  "YOUR_NOMAD_NAME_HERE"
```
3. Create a Linux service `nomad.service` inside `/etc/systemd/system`:
```systemd
[Unit]
Description=Nomad
Documentation=https://nomadproject.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/usr/local/bin/nomad agent -config /etc/nomad.d
KillMode=process
KillSignal=SIGINT
LimitNOFILE=infinity
LimitNPROC=infinity
Restart=on-failure
RestartSec=2
StartLimitBurst=3
TasksMax=infinity

[Install]
WantedBy=multi-user.target
```
4. Load the service file with `sudo systemctl daemon-reload`, then start the service with `sudo systemctl enable nomad && sudo systemctl start nomad`.
# Resources
- <https://developer.hashicorp.com/nomad/tutorials/get-started/gs-overview>
- <https://developer.hashicorp.com/nomad/docs/drivers>
- https://developer.hashicorp.com/nomad/docs/configuration