2015-01-21 22:07:54 +00:00
|
|
|
---
|
2020-09-01 15:14:13 +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-10 17:40:11 +00:00
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/maintenance](https://www.consul.io/api-docs/agent#enable-maintenance-mode)
|
|
|
|
|
|
2017-09-02 00:49:51 +00:00
|
|
|
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
|
2017-09-02 00:49:51 +00:00
|
|
|
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
|
2017-09-02 00:49:51 +00:00
|
|
|
critical status against a service, and deactivated by deregistering the
|
2015-01-21 22:07:54 +00:00
|
|
|
health check.
|
|
|
|
|
|
2022-01-10 21:44:56 +00:00
|
|
|
The table below shows this command's [required ACLs](/api#authentication). Configuration of
|
|
|
|
|
[blocking queries](/api/features/blocking) and [agent caching](/api/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]`
|
|
|
|
|
|
2017-02-09 21:50:45 +00:00
|
|
|
#### API Options
|
2015-01-21 22:07:54 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
@include 'http_api_options_client.mdx'
|
2017-02-09 21:50:45 +00:00
|
|
|
|
|
|
|
|
#### Command Options
|
2015-01-21 22:07:54 +00:00
|
|
|
|
2020-09-21 16:32:10 +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
|
|
|
|
2020-09-21 16:32:10 +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
|
2020-12-08 23:24:36 +00:00
|
|
|
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.
|
|
|
|
|
|
2015-01-22 18:29:48 +00:00
|
|
|
## 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
|
2015-01-22 18:29:48 +00:00
|
|
|
$ consul maint
|
|
|
|
|
Node:
|
|
|
|
|
Name: node1.local
|
|
|
|
|
Reason: This node is broken.
|
|
|
|
|
|
|
|
|
|
Service:
|
|
|
|
|
ID: redis
|
|
|
|
|
Reason: Redis is currently offline.
|
|
|
|
|
```
|
