open-consul/website/content/commands/maint.mdx

74 lines
2.4 KiB
Plaintext
Raw Normal View History

2015-01-21 22:07:54 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Maint'
description: |
2015-01-21 22:07:54 +00:00
The `maint` command provides control of both service and node maintenance mode
---
# Consul Maint
Command: `consul maint`
2022-01-11 13:26:58 +00:00
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/maintenance](/api-docs/agent#enable-maintenance-mode)
The `maint` command provides control of service maintenance mode.
Using the command, it is possible to mark a service provided by a node or all the services on the
2015-01-21 22:07:54 +00:00
node as a whole as "under maintenance". In this mode of operation, the service
2020-04-07 18:55:19 +00:00
will not appear in DNS query results, or API results. This effectively
takes the service out of the pool of available "healthy" nodes of a service.
2015-01-21 22:07:54 +00:00
Under the hood, maintenance mode is activated by registering a health check in
critical status against a service, and deactivated by deregistering the
2015-01-21 22:07:54 +00:00
health check.
The table below shows this command's [required ACLs](/api-docs#authentication). Configuration of
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
| ACL Required |
| ------------ |
| `node:write` |
2015-01-21 22:07:54 +00:00
## Usage
Usage: `consul maint [options]`
#### Command Options
2015-01-21 22:07:54 +00:00
- `-enable` - Enable node-wide maintenance mode flag. If combined with the
`-service` flag, we operate on a specific service ID instead. Node and
service maintenance flags are independent.
2015-01-21 22:07:54 +00:00
- `-disable` - Disable the node-wide maintenance flag. If combined with the
`-service` flag, we operate on a specific service ID instead. Node and
service maintenance flags are independent.
2015-01-21 22:07:54 +00:00
2020-04-07 18:55:19 +00:00
- `-reason` - An optional reason for placing the service into
2015-01-21 22:07:54 +00:00
maintenance mode. If provided, this reason will be visible in the newly-
registered critical check's "Notes" field.
2020-04-07 18:55:19 +00:00
- `-service` - An optional service ID to control maintenance mode for a given service. By
2015-01-21 22:07:54 +00:00
providing this flag, the `-enable` and `-disable` flags functionality is
modified to operate on the given service ID.
#### API Options
@include 'http_api_options_client.mdx'
## List mode
If neither `-enable` nor `-disable` are passed, the `maint` command will
switch to "list mode", displaying any current maintenances. This may return
blank if nothing is currently under maintenance. The output will look like:
2020-05-19 18:32:38 +00:00
```shell-session
$ consul maint
Node:
Name: node1.local
Reason: This node is broken.
Service:
ID: redis
Reason: Redis is currently offline.
```