103 lines
3.4 KiB
Plaintext
103 lines
3.4 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Task HTTP API
|
|
description: |-
|
|
Jobs can access Nomad's HTTP API via the Task API.
|
|
---
|
|
|
|
# Task API
|
|
|
|
Nomad's Task API provides every task managed by Nomad with a Unix Domain Socket
|
|
(UDS) to access the local agent's HTTP API. Regardless of agent configuration
|
|
the Task API does *not* require [mTLS][], but *always* requires authentication.
|
|
See below for details.
|
|
|
|
The Unix Domain Socket is located at `${NOMAD_SECRETS_DIR}/api.sock`.
|
|
|
|
## Rationale
|
|
|
|
Nomad's HTTP API is available on every agent at the configured
|
|
[`bind_addr`][bind_addr]. While this is convenient for user access, it is not
|
|
always accessible to workloads running on Nomad. These workloads may have a
|
|
network configuration that makes it impossible to access the agent HTTP
|
|
address, or the agent's HTTP address may be difficult for workloads to discover
|
|
in a way that's portable between Nomad nodes and clusters.
|
|
|
|
A Unix Domain Socket is a way to expose network services that works with most
|
|
runtimes and operating systems and adds minimal complexity or runtime overhead
|
|
to Nomad.
|
|
|
|
## Security
|
|
|
|
Unlike the agent's HTTP API, the Task API *always requires authentication* even
|
|
if [ACLs][acl] are disabled. This allows Nomad to always make the Task API
|
|
available even if the workload is untrusted. If ACLs are enabled, the [anonymous
|
|
policy][anon] is not available via the Task API.
|
|
|
|
Both [ACL Tokens][acl-tokens] and [Workload Identities][workload-id] are
|
|
accepted. Once the Task API has authenticated the credentials, the normal
|
|
endpoint-specific authorization is applied when ACLs are enabled.
|
|
|
|
The Workload Identity should be used by tasks accessing the Task API.
|
|
|
|
An ACL Token should be used when an operator is accessing the Task API via
|
|
[`nomad alloc exec`][alloc-exec] or when a task is proxying Nomad HTTP requests
|
|
on behalf of an authenticated user. The Task API could be used by a proxy
|
|
presenting Nomad's UI with a standard TLS certificate for browsers.
|
|
|
|
If [`task.user`][task-user] is set in the jobspec, the Task API will only be
|
|
usable by that user. Otherwise the Unix Domain Socket is accessible by any
|
|
user.
|
|
|
|
mTLS is never enabled for the Task API since traffic never leaves the node.
|
|
|
|
## Using the Task API
|
|
|
|
The following jobspec will use the Task API to set [Dynamic Node Metadata][dnm]
|
|
and exit.
|
|
|
|
```hcl
|
|
job "taskapi-example" {
|
|
type = "batch"
|
|
|
|
group "taskapi-example" {
|
|
|
|
task "taskapi" {
|
|
driver = "docker"
|
|
|
|
config {
|
|
image = "curlimages/curl:7.87.0"
|
|
args = [
|
|
"--unix-socket", "${NOMAD_SECRETS_DIR}/api.sock",
|
|
"-H", "Authorization: Bearer ${NOMAD_TOKEN}",
|
|
"--data-binary", "{\"Meta\": {\"example\": \"Hello World!\"}}",
|
|
"--fail-with-body",
|
|
"--verbose",
|
|
"localhost/v1/client/metadata",
|
|
]
|
|
}
|
|
|
|
identity {
|
|
env = true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If the job was able to run successfully after about 10 seconds you can observe
|
|
the outcome by searching for the updated Node's metadata:
|
|
|
|
```shell-session
|
|
$ nomad node status -filter 'Meta.example == "Hello World!"'
|
|
```
|
|
|
|
[acl]: /nomad/docs/concepts/acl
|
|
[acl-tokens]: /nomad/docs/concepts/acl#token
|
|
[alloc-exec]: /nomad/docs/commands/alloc/exec
|
|
[anon]: /nomad/tutorials/access-control/access-control#acl-policies
|
|
[bind_addr]: /nomad/docs/configuration
|
|
[mTLS]: /nomad/tutorials/transport-security/security-enable-tls
|
|
[task-user]: /nomad/docs/job-specification/task#user
|
|
[workload-id]: /nomad/docs/concepts/workload-identity
|