Drew Bailey 6fd1901ef0

2019-11-05 14:24:52 -05:00

14 KiB

Raw Blame History

layout	page_title	sidebar_current	description
api	Agent - HTTP API	api-agent	The /agent endpoints interact with the local Nomad agent to interact with members and servers.

Agent HTTP API

The /agent endpoints are used to interact with the local Nomad agent.

List Members

This endpoint queries the agent for the known peers in the gossip pool. This endpoint is only applicable to servers. Due to the nature of gossip, this is eventually consistent.

Method	Path	Produces
`GET`	`/agent/members`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`node:read`

Sample Request

$ curl \
    https://localhost:4646/v1/agent/members

Sample Response

{
  "ServerName": "bacon-mac",
  "ServerRegion": "global",
  "ServerDC": "dc1",
  "Members": [
    {
      "Name": "bacon-mac.global",
      "Addr": "127.0.0.1",
      "Port": 4648,
      "Tags": {
        "mvn": "1",
        "build": "0.5.5dev",
        "port": "4647",
        "bootstrap": "1",
        "role": "nomad",
        "region": "global",
        "dc": "dc1",
        "vsn": "1"
      },
      "Status": "alive",
      "ProtocolMin": 1,
      "ProtocolMax": 5,
      "ProtocolCur": 2,
      "DelegateMin": 2,
      "DelegateMax": 4,
      "DelegateCur": 4
    }
  ]
}

List Servers

This endpoint lists the known server nodes. The servers endpoint is used to query an agent in client mode for its list of known servers. Client nodes register themselves with these server addresses so that they may dequeue work. The servers endpoint can be used to keep this configuration up to date if there are changes in the cluster.

Method	Path	Produces
`GET`	`/agent/servers`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`agent:read`

Sample Request

$ curl \
    https://localhost:4646/v1/agent/servers

Sample Response

[
  "127.0.0.1:4647"
]

Update Servers

This endpoint updates the list of known servers to the provided list. This replaces all previous server addresses with the new list.

Method	Path	Produces
`POST`	`/agent/servers`	`(empty body)`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`agent:write`

Parameters

address (string: <required>) - Specifies the list of addresses in the format ip:port. This is specified as a query string!

Sample Request

$ curl \
    --request POST \
    https://localhost:4646/v1/agent/servers?address=1.2.3.4:4647&address=5.6.7.8:4647

Query Self

This endpoint queries the state of the target agent (self).

Method	Path	Produces
`GET`	`/agent/self`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`agent:read`

Sample Request

$ curl \
    https://localhost:4646/v1/agent/self

Sample Response

{
  "config": {
    "Addresses": {
      "HTTP": "127.0.0.1",
      "RPC": "127.0.0.1",
      "Serf": "127.0.0.1"
    },
    "AdvertiseAddrs": {
      "HTTP": "127.0.0.1:4646",
      "RPC": "127.0.0.1:4647",
      "Serf": "127.0.0.1:4648"
    },
    "BindAddr": "127.0.0.1",
    "Client": {
      "AllocDir": "",
      "ChrootEnv": {},
      "ClientMaxPort": 14512,
      "ClientMinPort": 14000,
      "DisableRemoteExec": false,
      "Enabled": true,
      "GCDiskUsageThreshold": 99,
      "GCInodeUsageThreshold": 99,
      "GCInterval": 600000000000,
      "MaxKillTimeout": "30s",
      "Meta": {},
      "NetworkInterface": "lo0",
      "NetworkSpeed": 0,
      "NodeClass": "",
      "Options": {
        "driver.docker.volumes": "true"
      },
      "Reserved": {
        "CPU": 0,
        "DiskMB": 0,
        "MemoryMB": 0,
        "ParsedReservedPorts": null,
        "ReservedPorts": ""
      },
      "Servers": null,
      "StateDir": ""
    },
    "Consul": {
      "Addr": "",
      "Auth": "",
      "AutoAdvertise": true,
      "CAFile": "",
      "CertFile": "",
      "ChecksUseAdvertise": false,
      "ClientAutoJoin": true,
      "ClientServiceName": "nomad-client",
      "EnableSSL": false,
      "KeyFile": "",
      "ServerAutoJoin": true,
      "ServerServiceName": "nomad",
      "Timeout": 5000000000,
      "Token": "",
      "VerifySSL": false
    },
    "DataDir": "",
    "Datacenter": "dc1",
    "DevMode": true,
    "DisableAnonymousSignature": true,
    "DisableUpdateCheck": false,
    "EnableDebug": true,
    "EnableSyslog": false,
    "Files": null,
    "HTTPAPIResponseHeaders": {},
    "LeaveOnInt": false,
    "LeaveOnTerm": false,
    "LogLevel": "DEBUG",
    "NodeName": "",
    "Ports": {
      "HTTP": 4646,
      "RPC": 4647,
      "Serf": 4648
    },
    "Region": "global",
    "Revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9",
    "Server": {
      "BootstrapExpect": 0,
      "DataDir": "",
      "Enabled": true,
      "EnabledSchedulers": null,
      "HeartbeatGrace": "",
      "NodeGCThreshold": "",
      "NumSchedulers": 0,
      "ProtocolVersion": 0,
      "RejoinAfterLeave": false,
      "RetryInterval": "30s",
      "RetryJoin": [],
      "RetryMaxAttempts": 0,
      "StartJoin": []
    },
    "SyslogFacility": "LOCAL0",
    "TLSConfig": {
      "CAFile": "",
      "CertFile": "",
      "EnableHTTP": false,
      "EnableRPC": false,
      "KeyFile": "",
      "VerifyServerHostname": false
    },
    "Telemetry": {
      "CirconusAPIApp": "",
      "CirconusAPIToken": "",
      "CirconusAPIURL": "",
      "CirconusBrokerID": "",
      "CirconusBrokerSelectTag": "",
      "CirconusCheckDisplayName": "",
      "CirconusCheckForceMetricActivation": "",
      "CirconusCheckID": "",
      "CirconusCheckInstanceID": "",
      "CirconusCheckSearchTag": "",
      "CirconusCheckSubmissionURL": "",
      "CirconusCheckTags": "",
      "CirconusSubmissionInterval": "",
      "CollectionInterval": "1s",
      "DataDogAddr": "",
      "DataDogTags": [],
      "DisableHostname": false,
      "PublishAllocationMetrics": false,
      "PublishNodeMetrics": false,
      "StatsdAddr": "",
      "StatsiteAddr": "",
      "UseNodeName": false
    },
    "Vault": {
      "Addr": "https://vault.service.consul:8200",
      "AllowUnauthenticated": true,
      "ConnectionRetryIntv": 30000000000,
      "Enabled": null,
      "Role": "",
      "TLSCaFile": "",
      "TLSCaPath": "",
      "TLSCertFile": "",
      "TLSKeyFile": "",
      "TLSServerName": "",
      "TLSSkipVerify": null,
      "TaskTokenTTL": "",
      "Token": "root"
    },
    "Version": "0.5.5",
    "VersionPrerelease": "dev"
  },
  "member": {
    "Addr": "127.0.0.1",
    "DelegateCur": 4,
    "DelegateMax": 4,
    "DelegateMin": 2,
    "Name": "bacon-mac.global",
    "Port": 4648,
    "ProtocolCur": 2,
    "ProtocolMax": 5,
    "ProtocolMin": 1,
    "Status": "alive",
    "Tags": {
      "role": "nomad",
      "region": "global",
      "dc": "dc1",
      "vsn": "1",
      "mvn": "1",
      "build": "0.5.5dev",
      "port": "4647",
      "bootstrap": "1"
    }
  },
  "stats": {
    "runtime": {
      "cpu_count": "8",
      "kernel.name": "darwin",
      "arch": "amd64",
      "version": "go1.8",
      "max_procs": "7",
      "goroutines": "79"
    },
    "nomad": {
      "server": "true",
      "leader": "true",
      "leader_addr": "127.0.0.1:4647",
      "bootstrap": "false",
      "known_regions": "1"
    },
    "raft": {
      "num_peers": "0",
      "fsm_pending": "0",
      "last_snapshot_index": "0",
      "last_log_term": "2",
      "commit_index": "144",
      "term": "2",
      "last_log_index": "144",
      "protocol_version_max": "3",
      "snapshot_version_max": "1",
      "latest_configuration_index": "1",
      "latest_configuration": "[{Suffrage:Voter ID:127.0.0.1:4647 Address:127.0.0.1:4647}]",
      "last_contact": "never",
      "applied_index": "144",
      "protocol_version": "1",
      "protocol_version_min": "0",
      "snapshot_version_min": "0",
      "state": "Leader",
      "last_snapshot_term": "0"
    },
    "client": {
      "heartbeat_ttl": "17.79568937s",
      "node_id": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
      "known_servers": "127.0.0.1:4647",
      "num_allocations": "0",
      "last_heartbeat": "10.107423052s"
    },
    "serf": {
      "event_time": "1",
      "event_queue": "0",
      "encrypted": "false",
      "member_time": "1",
      "query_time": "1",
      "intent_queue": "0",
      "query_queue": "0",
      "members": "1",
      "failed": "0",
      "left": "0",
      "health_score": "0"
    }
  }
}

Join Agent

This endpoint introduces a new member to the gossip pool. This endpoint is only eligible for servers.

Method	Path	Produces
`POST`	`/agent/join`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`none`

Parameters

address (string: <required>) - Specifies the address to join in the ip:port format. This is provided as a query parameter and may be specified multiple times to join multiple servers.

Sample Request

$ curl \
    --request POST \
    https://localhost:4646/v1/agent/join?address=1.2.3.4&address=5.6.7.8

Sample Response

{
  "error": "",
  "num_joined": 2
}

Force Leave Agent

This endpoint forces a member of the gossip pool from the "failed" state to the "left" state. This allows the consensus protocol to remove the peer and stop attempting replication. This is only applicable for servers.

Method	Path	Produces
`POST`	`/agent/force-leave`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`agent:write`

Parameters

node (string: <required>) - Specifies the name of the node to force leave.

Sample Request

$ curl \
    --request POST \
    https://localhost:4646/v1/agent/force-leave?node=client-ab2e23dc

Health

This endpoint returns whether or not the agent is healthy. When using Consul it is the endpoint Nomad will register for its own health checks.

When the agent is unhealthy 500 will be returned along with JSON response containing an error message.

Method	Path	Produces
`GET`	`/agent/health`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`none`

Sample Request

$ curl \
    https://localhost:4646/v1/agent/health

Sample Response

{
    "client": {
        "message": "ok",
        "ok": true
    },
    "server": {
        "message": "ok",
        "ok": true
    }
}

Stream Logs

This endpoint streams logs from the local agent until the connection is closed

Method	Path	Produces
`GET`	`/agent/monitor`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`agent:read`

Parameters

log-level (string: "info") - Specifies a text string containing a log level to filter on, such as info. Possible values include trace, debug, info, warn, error
json (bool: false) - Specifies if the log format for streamed logs should be JSON.
node-id (string: "a57b2adb-1a30-2dda-8df0-25abb0881952") - Specifies a text string containing a node-id to target for streaming.
plain (bool: false) - Specifies if the response should be JSON or plaintext

Sample Request

$ curl \
    https://localhost:4646/v1/agent/monitor?log-level=debug&node-id=a57b2adb-1a30-2dda-8df0-25abb0881952

Sample Response

{
  "Offset": 0,
  "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..."
  "FileEvent": "log"
}

Field Reference

The return value is a stream of frames. These frames contain the following fields:

Data - A base64 encoding of the bytes being streamed.
FileEvent - An event that could cause a change in the streams position. The possible value for this endpoint is "log".
Offset - Offset is the offset into the stream.

14 KiB Raw Blame History

Agent HTTP API

List Members

Sample Request

Sample Response

List Servers

Sample Request

Sample Response

Update Servers

Parameters

Sample Request

Query Self

Sample Request

Sample Response

Join Agent

Parameters

Sample Request

Sample Response

Force Leave Agent

Parameters

Sample Request

Health

Sample Request

Sample Response

Stream Logs

Parameters

Sample Request

Sample Response

Field Reference

14 KiB

Raw Blame History