def state(self):
"""This endpoint queries the state of the target agent (self).
:return:
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/agent/self')
def peers(self):
"""This endpoint returns the set of raft peers in the region.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/status/peers')
def evaluate(self, job_id):
"""This endpoint creates a new evaluation for the given job. This can be used to force run the scheduling logic if necessary.
:return application/json
"""
return self.agent.http.post(CB.json(index=False, allow_404=False),
'/v1/job/%s/evaluate' % job_id)
def leader(self):
"""This endpoint returns the address of the current leader in the region.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/status/leader')
def force_periodic(self, job_id):
"""This endpoint forces a new instance of the periodic job. A new instance will be created even if it violates the job's prohibit_overlap settings. As such, this should be only used to immediately run a periodic job.
:return application/json
"""
return self.agent.http.post(CB.json(index=False),
'/v1/job/%s/periodic/force' % job_id)
def servers(self):
"""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.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/agent/servers')
def allocation_health(self,
deployment_id,
HealthyAllocationIDs=None,
UnhealthyAllocationIDs=None):
"""This endpoint is used to promote task groups that have canaries for a deployment. This should be done when the placed canaries are healthy and the rolling upgrade of the remaining allocations should begin.
:param: deployment_id (string: <required>)- Specifies the UUID of the deployment. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:param: all (bool: false) - Specifies whether all task groups should be promoted.
:param: groups (array<string>: nil) - Specifies a particular set of task groups that should be promoted.
"""
req = {
'DeploymentID': deployment_id,
}
if HealthyAllocationIDs:
if isinstance(HealthyAllocationIDs, list):
req['HealthyAllocationIDs'] = HealthyAllocationIDs
else:
raise RuntimeError(
"When calling promote, the 'HealthyAllocationIDs' argument must be a list if provided"
)
if UnhealthyAllocationIDs:
if isinstance(UnhealthyAllocationIDs, list):
req['UnhealthyAllocationIDs'] = UnhealthyAllocationIDs
else:
raise RuntimeError(
"When calling promote, the 'UnhealthyAllocationIDs' argument must be a list if provided"
)
data = dumps(req)
return self.agent.http.post(CB.json(index=False),
'/v1/deployment/allocation-health/%s' %
deployment_id,
data=data)
def members(self):
"""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.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/agent/members')
def fail(self, deployment_id):
"""This endpoint is used to mark a deployment as failed. This should be done to force the scheduler to stop creating allocations as part of the deployment or to cause a rollback to a previous job version. This endpoint only triggers a rollback if the most recent stable version of the job has a different specification than the job being reverted.
:param: deployment_id (string: <required>)- Specifies the UUID of the deployment. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
"""
return self.agent.http.post(CB.json(index=False),
'/v1/deployment/fail/%s' % deployment_id)
def dispatch(self, job_id, **kwargs):
"""This endpoint dispatches a new instance of a parameterized job.
:return application/json
"""
return self.agent.http.post(CB.json(index=False, allow_404=False),
'/v1/job/%s/dispatch' % job_id,
data=kwargs)
def stats(self):
"""This endpoint queries the actual resources consumed on a node. The API endpoint is hosted by the Nomad client and requests have to be made to the nomad client whose resource usage metrics are of interest.
:return application/json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/client/stats')
def read(self, deployment_id):
"""This endpoint reads information about a specific deployment by ID.
:param: deployment_id (string: <required>)- Specifies the UUID of the deployment. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
"""
return self.agent.http.get(CB.json(index=False),
'/v1/deployment/%s' % deployment_id)
def purge(self, node_id):
"""This endpoint purges a node from the system. Nodes can still join the cluster if they are alive.
:param: :node_id (string: <required>)- Specifies the UUID of the node. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:return application/json
"""
return self.agent.http.post(CB.json(index=False, allow_404=False),
'/v1/node/%s/purge' % node_id)
def allocations(self, node_id):
"""This endpoint lists all of the allocations for the given node. This can be used to determine what allocations have been scheduled on the node, their current status, and the values of dynamically assigned resources, like ports.
:param: :node_id (string: <required>)- Specifies the UUID of the node. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/node/%s/allocations' % node_id)
def read(self, node_id):
"""This endpoint reads information about a single job for its specification and status.
:param :node_id (string: <required>)- Specifies the ID of the node. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/node/%s' % node_id)
def evaluations(self, job_id):
"""This endpoint reads information about a single job's evaluations
:job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/job/%s/evaluations' % job_id)
def most_recent_deployment(self, job_id):
"""This endpoint returns a single job's most recent deployment.
:job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/job/%s/deployment' % job_id)
def evaluate(self, node_id):
"""This endpoint creates a new evaluation for the given node. This can be used to force a run of the scheduling logic.
:param: :node_id (string: <required>)- Specifies the UUID of the node. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(CB.json(index=False, allow_404=False),
'/v1/node/%s/evaluate' % node_id)
def allocations(self, deployment_id):
"""This endpoint lists the allocations created or modified for the given deployment.
:param: deployment_id (string: <required>)- Specifies the UUID of the deployment. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
"""
return self.agent.http.get(
CB.json(index=False),
'/v1/deployment/allocations/%s' % deployment_id)
def bootstrap(self):
"""
This endpoint is used to bootstrap the ACL system and provide the initial management token. This request is always forwarded to the authoritative region. It can only be invoked once until a bootstrap reset is performed.
:return: json
"""
return self.agent.http.post(
CB.json(index=False, allow_404=False),
'/v1/acl/bootstrap')
def list(self):
"""
This endpoint lists all ACL tokens. This lists the local tokens and the global tokens which have been replicated to the region, and may lag behind the authoritative region.
:return: json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/acl/tokens')
def list(self):
"""
This endpoint lists all ACL policies. This lists the policies that have been replicated to the region, and may lag behind the authoritative region.
:return: json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/acl/policies')
def allocation(self, alloc_id):
"""This endpoint queries the actual resources consumed on a node. The API endpoint is hosted by the Nomad client and requests have to be made to the nomad client whose resource usage metrics are of interest.
:param: :alloc_id (string: <required>) - Specifies the allocation ID to query. This is specified as part of the URL. Note, this must be the full allocation ID, not the short 8-character one. This is specified as part of the path.
:return application/json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/client/allocation/%s/stats' % alloc_id)
def delete(self, policy_name):
"""
This endpoint deletes the named ACL policy. This request is always forwarded to the authoritative region.
:param: policy_name (string: <required>) - Specifies the policy name to delete.
:return: boolean
"""
return self.agent.http.delete(
CB.bool(), '/v1/acl/policy/%s' % policy_name)
def delete(self, accessor_id):
"""
This endpoint deletes the ACL token by accessor. This request is forwarded to the authoritative region for global tokens.
:param: accessor_id (string: <required>) - Specifies the ACL token accessor ID.
:return: json
"""
return self.agent.http.delete(
CB.bool(), '/v1/acl/token/%s' % accessor_id)
def list(self, prefix=None):
"""The /allocation endpoints are used to query for and interact with allocations.
prefix (string: "")- Specifies a string to filter allocations on based on an index prefix. This is specified as a querystring parameter.
"""
params = {}
if prefix is not None:
params['prefix'] = prefix
return self.agent.http.get(CB.json(index=False, decode='Payload'),
'/v1/allocations',
params=params)
def read(self, policy_name):
"""
This endpoint reads an ACL policy with the given name. This queries the policy that have been replicated to the region, and may lag behind the authoritative region.
:param: policy_name (string: <required>) - Specifies the policy name to read.
:return: json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/acl/policy/%s' % policy_name)
def read(self, accessor_id="self"):
"""
This endpoint reads an ACL token with the given accessor. If the token is a global token which has been replicated to the region it may lag behind the authoritative region.
:param: accessor_id (string: defaults to 'self') - Specifies the token (by accessor) that is being retrieved.
:return: json
"""
return self.agent.http.get(
CB.json(index=False, allow_404=False),
'/v1/acl/token/%s' % accessor_id)
def list(self, prefix=None):
"""This endpoint lists all deployments
:param: prefix (string: "")- Specifies a string to filter deployments on based on an index prefix. This is specified as a querystring parameter
"""
params = {}
if prefix is not None:
params['prefix'] = prefix
return self.agent.http.get(CB.json(index=False, decode='Payload'),
'/v1/deployments',
params=params)
def drain(self, node_id, enabled=True):
"""This endpoint toggles the drain mode of the node. When draining is enabled, no further allocations will be assigned to this node, and existing allocations will be migrated to new nodes.
:param: :node_id (string: <required>)- Specifies the UUID of the node. This must be the full UUID, not the short 8-character one. This is specified as part of the path.
:param: enable (bool: default True) - Specifies if drain mode should be enabled. This is specified as a query string parameter.
:return application/json
"""
params = {'enabled': 'true' if enabled else 'false'}
return self.agent.http.post(CB.json(index=False, allow_404=False),
'/v1/node/%s/drain' % node_id,
params=params)
