DOCSEARCHbyAlgolia
Submit Docs

python-nomad

repository·master·Indexed 40 days ago

https://github.com/jrxfive/python-nomad

A Python client library for interacting with HashiCorp Nomad, providing a programmatic interface to manage jobs, allocations, nodes, namespaces, and other Nomad resources. It includes support for ACL management, event streaming, deployment control, and configuration via environment variables such as NOMAD_ADDR and NOMAD_TOKEN.

Tokens
17.7K
Snippets
83
Records
84
Agent score
50%

What's inside python-nomad

  2. Initialize a Nomad client for HTTPS instances

    master

    When connecting to HTTPS Nomad instances, use the secure=True parameter. Depending on your SSL configuration, you may need to adjust the verify and cert parameters:

    • Standard HTTPS (non-self-signed): Set secure=True and verify=True.
    • Self-signed (no verification): Set secure=True and verify=False.
    • Self-signed (with certificate validation): Set secure=True, verify=True, and provide the path to your certificate via the cert parameter.
    • Client Certificate and Key: Provide a tuple containing the path to the certificate file and the key file to the cert parameter.
    import nomad

# For HTTPS Nomad instances with non-self-signed SSL certificates
n = nomad.Nomad(host="172.16.100.10", secure=True, timeout=5, verify=True)

# For HTTPS Nomad instances with self-signed SSL certificates and no validate the cert
n = nomad.Nomad(host="172.16.100.10", secure=True, timeout=5, verify=False)

# For HTTPS Nomad instances with self-signed SSL certificates that must validate with cert
n = nomad.Nomad(host="172.16.100.10", secure=True, timeout=5, verify=True, cert="/path/to/certfile")

# For HTTPS Nomad instances with cert file and key
n = nomad.Nomad(host="https://172.16.100.10", secure=True, timeout=5, verify=True, cert=("/path/to/certfile", "/path/to/key"))

  3. Gracefully exit an Event Stream

    master

    To stop an event stream, use the stream_exit_event returned by get_stream(). Calling .set() on this event signals the background thread to exit.

    Because the thread may be waiting for a new event or a connection timeout, the exit is not always immediate. To handle this in a loop, use events.get(timeout=<VALUE>) within a try/except queue.Empty block and check stream.is_alive() to determine when the thread has successfully shut down.

    import nomad
import threading
import time
import queue

def stop_stream(exit_event, timeout):
    time.sleep(timeout)
    exit_event.set()

n = nomad.Nomad()
# Use a timeout in get_stream to allow the connection to cycle
stream, stream_exit_event, events = n.event.stream.get_stream(index=0, topic={"Node": "*"}, timeout=3.2)
stream.start()

# Trigger exit after 3 seconds
stop = threading.Thread(target=stop_stream, args=(stream_exit_event, 3.0))
stop.start()

while True:
    if not stream.is_alive():
        print("stream stopped")
        break

    try:
        event = events.get(timeout=1.0)
        print(event)
        events.task_done()
    except queue.Empty:
        continue

  4. Configure python-nomad via environment variables

    master

    To unify configuration with Nomad CLI tools, you can use the following environment variables instead of passing arguments to the Nomad constructor:

    • NOMAD_ADDR: The address of the Nomad server.
    • NOMAD_NAMESPACE: The Nomad namespace.
    • NOMAD_TOKEN: The ACL token.
    • NOMAD_REGION: The Nomad region.
    • NOMAD_CLIENT_CERT: Path to the client certificate file.
    • NOMAD_CLIENT_KEY: Path to the client key file.
    NOMAD_ADDR=http://127.0.0.1:4646
NOMAD_NAMESPACE=default
NOMAD_TOKEN=xxxx-xxxx-xxxx-xxxx
NOMAD_REGION=us-east-1a
NOMAD_CLIENT_CERT=/path/to/tls/client.crt
NOMAD_CLIENT_KEY=/path/to/tls/client.key

  5. Basic Job operations example

    master

    This example demonstrates how to access jobs, retrieve an ID, get allocations for a job, and deregister a job.

    import nomad
n = nomad.Nomad(host="172.16.100.10", timeout=5)

# Check if a job exists in the jobs dictionary
if "example" in n.jobs:
    # Access job details
j = n.jobs["example"]["ID"]

    # Get allocations for the job
    example_allocation = n.job.get_allocations(j)

    # Deregister the job
    n.job.deregister_job(j)

  6. Initialize a Nomad client with Namespace and ACL Token

    master

    To interact with a specific Nomad namespace or use an ACL token for authorization, pass the namespace and token arguments to the nomad.Nomad constructor.

    import nomad
# For HTTPS Nomad instances with namespace and acl token
n = nomad.Nomad(host="172.16.100.10", secure=True, timeout=5, verify=False, namespace='Namespace-example', token='3f4a0fcd-7c42-773c-25db-2d31ba0c05fe')

  8. Manage Nomad jobs and allocations

    master

    Once a client is initialized, you can inspect jobs, retrieve allocations for a specific job, and deregister jobs.

    • Check if a job exists in the n.jobs dictionary.
    • Access job details using the job ID.
    • Use n.job.get_allocations(job_id) to retrieve allocations for a job.
    • Use n.job.deregister_job(job_id) to remove a job.
    import nomad
n = nomad.Nomad(host="172.16.100.10", timeout=5)

# Check if 'example' job exists
if "example" in n.jobs:
    # Get the job ID
    j = n.jobs["example"]["ID"]
    
    # Get allocations for the job
    example_allocation = n.job.get_allocations(j)
    
    # Deregister the job
    n.job.deregister_job(j)

  9. Get job deployment and summary data

    master

    Use these methods to inspect the current state and health of a job:

    • get_deployment(job_id): Returns the single most recent deployment for the job.
    • get_summary(job_id): Returns summary information about the job.

    Note: The deployment object often contains a JobVersion key which is useful for reverting or stabilizing jobs.

    import nomad

my_nomad = nomad.Nomad(host='192.168.33.10')

deployment = my_nomad.job.get_deployment("example")
summary = my_nomad.job.get_summary("example")

  10. Delete a Sentinel policy

    master

    Use my_nomad.sentinel.delete_policy(name) to remove a specific policy from the Nomad cluster using its name.

    import nomad

my_nomad = nomad.Nomad(host='192.168.33.10', token='10f0cf19-2c8c-cb4b-721a-fda2a388740b', verify=False)

my_nomad.sentinel.delete_policy("my-policy")

  11. Create job evaluation or plan

    master

    Use these methods to interact with the Nomad scheduler without necessarily registering a new job:

    • evaluate_job(job_id): Forces the scheduling logic to run for the given job.
    • plan_job(job_id, job_spec): Performs a dry-run of the scheduler using the provided job specification. This is useful for predicting how a job will be scheduled before actually registering it.
    import nomad

my_nomad = nomad.Nomad(host='192.168.33.10')

# Force run scheduling logic
my_nomad.job.evaluate_job("example")

# Dry-run a job plan
plan = my_nomad.job.plan_job("example", job_spec_dict)

  12. Stop and reschedule an allocation

    master

    Use the allocation.stop_allocation method to stop and reschedule a specific Nomad allocation by its ID. This corresponds to the Nomad API stop-allocation endpoint.

    import nomad

my_nomad = nomad.Nomad(host='192.168.33.10')

# Replace with the actual allocation ID
my_nomad.allocation.stop_allocation('32c54571-fb79-97d2-ee38-16673bab692c')