PythonTemplateProject/.gitea/workflows/README-nomad-job.md

Top-Level Job Configuration

job

• Purpose: Defines the Nomad job.
• Attributes:
  • region: Specifies the Nomad region where the job should run. Reference: Nomad Regions
  • datacenters: Lists the datacenters in which the job is eligible to run. Reference: Job Placement
  • type: Defines the job type (service in this case). Service jobs are typically long-running. Reference: Job Types

---

Update Block

update

• Purpose: Specifies rolling update strategy for service jobs.
• Attributes:
  • stagger: Time between starting updates for each allocation.
  • max_parallel: Number of allocations to update simultaneously.
  • progress_deadline: Time to wait for a deployment to progress before failing.
• Reference: Update Stanza

---

Group Configuration

group

• Purpose: Defines a group of tasks that should be placed together on the same node.
• Attributes:
  • count: Number of task groups to run.
• Reference: Task Group

---

Network Configuration

network

• Purpose: Specifies networking requirements for the task group.
• Attributes:
  • port: Defines a named port mapping for the task group.
    • to: Specifies the internal port the application listens to within the container.
• Reference: Network Stanza

---

Consul Integration

service

• Purpose: Registers the service with Consul for discovery.
• Attributes:
  • provider: Specifies the service discovery provider (consul).
  • name: The name of the service in Consul.
  • port: References the named port defined in the network block.
  • tags: Metadata tags to annotate the service (e.g., for routing in Traefik).
  • check: Defines health check parameters for the service.
    • name: Name of the health check.
    • type: Health check type (tcp in this case).
    • interval: Frequency of the health check.
    • timeout: Maximum duration for the health check.
• Reference: Consul Service Stanza

---

Task Configuration

task

• Purpose: Defines a single executable unit of work.
• Attributes:
  • driver: Specifies the driver (docker in this case).
  • config: Driver-specific configuration.
    • image: Docker image for the task.
    • ports: References the named port defined in the network block.
  • env: Sets environment variables for the task.
  • resources: Specifies resource requirements for the task.
    • cpu: CPU allocation in MHz.
    • memory: Memory allocation in MB.
• Reference: Task Stanza

---

Dynamic Port Allocation

${NOMAD_PORT_<port-label>}

• Purpose: Refers to the dynamically allocated host port mapped to the internal container port.
• Usage: This is used in the env and tags sections to dynamically configure the application and Consul registration.
• Reference: Port Variables

---

Key Takeaways

1. This job defines a service that runs as a Docker container, listens on a dynamically assigned port, and registers itself in Consul for service discovery.
2. The network stanza ensures that Nomad assigns a dynamic host port, while the ${NOMAD_PORT_<port-label>} variable is used to pass this information to the container and Consul.
3. The update stanza ensures smooth rolling updates for the service.

For further details and advanced configurations, refer to the Nomad Job Specification Documentation.