github.com/outbrain/consul@v1.4.5/website/source/api/operator/autopilot.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Autopilot - Operator - HTTP API
     4  sidebar_current: api-operator-autopilot
     5  description: |-
     6    The /operator/autopilot endpoints allow for automatic operator-friendly
     7    management of Consul servers including cleanup of dead servers, monitoring
     8    the state of the Raft cluster, and stable server introduction.
     9  ---
    10  
    11  # Autopilot Operator HTTP API
    12  
    13  The `/operator/autopilot` endpoints allow for automatic operator-friendly
    14  management of Consul servers including cleanup of dead servers, monitoring
    15  the state of the Raft cluster, and stable server introduction.
    16  
    17  Please see the [Autopilot Guide](/docs/guides/autopilot.html) for more details.
    18  
    19  ## Read Configuration
    20  
    21  This endpoint retrieves its latest Autopilot configuration.
    22  
    23  | Method | Path                         | Produces                   |
    24  | ------ | ---------------------------- | -------------------------- |
    25  | `GET`  | `/operator/autopilot/configuration` | `application/json` |
    26  
    27  The table below shows this endpoint's support for
    28  [blocking queries](/api/index.html#blocking-queries),
    29  [consistency modes](/api/index.html#consistency-modes),
    30  [agent caching](/api/index.html#agent-caching), and
    31  [required ACLs](/api/index.html#acls).
    32  
    33  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
    34  | ---------------- | ----------------- | ------------- | --------------- |
    35  | `NO`             | `none`            | `none`        | `operator:read` |
    36  
    37  ### Parameters
    38  
    39  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    40    the datacenter of the agent being queried. This is specified as part of the
    41    URL as a query string.
    42  
    43  - `stale` `(bool: false)` - If the cluster does not currently have a leader an
    44    error will be returned. You can use the `?stale` query parameter to read the
    45    Raft configuration from any of the Consul servers.
    46  
    47  ### Sample Request
    48  
    49  ```text
    50  $ curl \
    51      http://127.0.0.1:8500/operator/autopilot/configuration
    52  ```
    53  
    54  ### Sample Response
    55  
    56  ```json
    57  {
    58    "CleanupDeadServers": true,
    59    "LastContactThreshold": "200ms",
    60    "MaxTrailingLogs": 250,
    61    "ServerStabilizationTime": "10s",
    62    "RedundancyZoneTag": "",
    63    "DisableUpgradeMigration": false,
    64    "UpgradeVersionTag": "",
    65    "CreateIndex": 4,
    66    "ModifyIndex": 4
    67  }
    68  ```
    69  
    70  For more information about the Autopilot configuration options, see the
    71  [agent configuration section](/docs/agent/options.html#autopilot).
    72  
    73  ## Update Configuration
    74  
    75  This endpoint updates the Autopilot configuration of the cluster.
    76  
    77  | Method | Path                         | Produces                   |
    78  | ------ | ---------------------------- | -------------------------- |
    79  | `PUT`  | `/operator/autopilot/configuration` | `application/json` |
    80  
    81  The table below shows this endpoint's support for
    82  [blocking queries](/api/index.html#blocking-queries),
    83  [consistency modes](/api/index.html#consistency-modes),
    84  [agent caching](/api/index.html#agent-caching), and
    85  [required ACLs](/api/index.html#acls).
    86  
    87  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required     |
    88  | ---------------- | ----------------- | ------------- | ---------------- |
    89  | `NO`             | `none`            | `none`        | `operator:write` |
    90  
    91  ### Parameters
    92  
    93  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    94    the datacenter of the agent being queried. This is specified as part of the
    95    URL as a query string.
    96  
    97  - `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. The update will
    98    only happen if the given index matches the `ModifyIndex` of the configuration
    99    at the time of writing.
   100  
   101  - `CleanupDeadServers` `(bool: true)` - Specifies automatic removal of dead
   102    server nodes periodically and whenever a new server is added to the cluster.
   103  
   104  - `LastContactThreshold` `(string: "200ms")` - Specifies the maximum amount of
   105    time a server can go without contact from the leader before being considered
   106    unhealthy. Must be a duration value such as `10s`.
   107  
   108  - `MaxTrailingLogs` `(int: 250)` specifies the maximum number of log entries
   109    that a server can trail the leader by before being considered unhealthy.
   110  
   111  - `ServerStabilizationTime` `(string: "10s")` - Specifies the minimum amount of
   112    time a server must be stable in the 'healthy' state before being added to the
   113    cluster. Only takes effect if all servers are running Raft protocol version 3
   114    or higher. Must be a duration value such as `30s`.
   115  
   116  - `RedundancyZoneTag` `(string: "")` - Controls the node-meta key to use when
   117    Autopilot is separating servers into zones for redundancy. Only one server in
   118    each zone can be a voting member at one time. If left blank, this feature will
   119    be disabled.
   120  
   121  - `DisableUpgradeMigration` `(bool: false)` - Disables Autopilot's upgrade
   122    migration strategy in Consul Enterprise of waiting until enough
   123    newer-versioned servers have been added to the cluster before promoting any of
   124    them to voters.
   125  
   126  - `UpgradeVersionTag` `(string: "")` - Controls the node-meta key to use for
   127    version info when performing upgrade migrations. If left blank, the Consul
   128    version will be used.
   129  
   130  ### Sample Payload
   131  
   132  ```json
   133  {
   134    "CleanupDeadServers": true,
   135    "LastContactThreshold": "200ms",
   136    "MaxTrailingLogs": 250,
   137    "ServerStabilizationTime": "10s",
   138    "RedundancyZoneTag": "",
   139    "DisableUpgradeMigration": false,
   140    "UpgradeVersionTag": "",
   141    "CreateIndex": 4,
   142    "ModifyIndex": 4
   143  }
   144  ```
   145  
   146  ## Read Health
   147  
   148  This endpoint queries the health of the autopilot status.
   149  
   150  | Method | Path                         | Produces                   |
   151  | ------ | ---------------------------- | -------------------------- |
   152  | `GET`  | `/operator/autopilot/health` | `application/json`         |
   153  
   154  The table below shows this endpoint's support for
   155  [blocking queries](/api/index.html#blocking-queries),
   156  [consistency modes](/api/index.html#consistency-modes),
   157  [agent caching](/api/index.html#agent-caching), and
   158  [required ACLs](/api/index.html#acls).
   159  
   160  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
   161  | ---------------- | ----------------- | ------------- | --------------- |
   162  | `NO`             | `none`            | `none`        | `operator:read` |
   163  
   164  ### Parameters
   165  
   166  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   167    the datacenter of the agent being queried. This is specified as part of the
   168    URL as a query string.
   169  
   170  ### Sample Request
   171  
   172  ```text
   173  $ curl \
   174      http://127.0.0.1:8500/v1/operator/autopilot/health
   175  ```
   176  
   177  ### Sample response
   178  
   179  ```json
   180  {
   181    "Healthy": true,
   182    "FailureTolerance": 0,
   183    "Servers": [
   184      {
   185        "ID": "e349749b-3303-3ddf-959c-b5885a0e1f6e",
   186        "Name": "node1",
   187        "Address": "127.0.0.1:8300",
   188        "SerfStatus": "alive",
   189        "Version": "0.7.4",
   190        "Leader": true,
   191        "LastContact": "0s",
   192        "LastTerm": 2,
   193        "LastIndex": 46,
   194        "Healthy": true,
   195        "Voter": true,
   196        "StableSince": "2017-03-06T22:07:51Z"
   197      },
   198      {
   199        "ID": "e36ee410-cc3c-0a0c-c724-63817ab30303",
   200        "Name": "node2",
   201        "Address": "127.0.0.1:8205",
   202        "SerfStatus": "alive",
   203        "Version": "0.7.4",
   204        "Leader": false,
   205        "LastContact": "27.291304ms",
   206        "LastTerm": 2,
   207        "LastIndex": 46,
   208        "Healthy": true,
   209        "Voter": false,
   210        "StableSince": "2017-03-06T22:18:26Z"
   211      }
   212    ]
   213  }
   214  ```
   215  
   216  - `Healthy` is whether all the servers are currently healthy.
   217  
   218  - `FailureTolerance` is the number of redundant healthy servers that could be
   219    fail without causing an outage (this would be 2 in a healthy cluster of 5
   220    servers).
   221  
   222  - `Servers` holds detailed health information on each server:
   223  
   224    - `ID` is the Raft ID of the server.
   225  
   226    - `Name` is the node name of the server.
   227  
   228    - `Address` is the address of the server.
   229  
   230    - `SerfStatus` is the SerfHealth check status for the server.
   231  
   232    - `Version` is the Consul version of the server.
   233  
   234    - `Leader` is whether this server is currently the leader.
   235  
   236    - `LastContact` is the time elapsed since this server's last contact with the leader.
   237  
   238    - `LastTerm` is the server's last known Raft leader term.
   239  
   240    - `LastIndex` is the index of the server's last committed Raft log entry.
   241  
   242    - `Healthy` is whether the server is healthy according to the current Autopilot configuration.
   243  
   244    - `Voter` is whether the server is a voting member of the Raft cluster.
   245  
   246    - `StableSince` is the time this server has been in its current `Healthy` state.
   247  
   248    The HTTP status code will indicate the health of the cluster. If `Healthy` is true, then a
   249    status of 200 will be returned. If `Healthy` is false, then a status of 429 will be returned.