github.com/sl1pm4t/consul@v1.4.5-0.20190325224627-74c31c540f9c/website/source/docs/commands/operator/area.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Operator Area"
     4  sidebar_current: "docs-commands-operator-area"
     5  description: >
     6   The operator area command is used to interact with Consul's network area subsystem.
     7  ---
     8  
     9  # Consul Operator Area
    10  
    11  Command: `consul operator area`
    12  
    13  [//]: # ( ~> The network area functionality described here is available only in )
    14  [//]: # (   [Consul Enterprise](https://www.hashicorp.com/products/consul/) version 0.8.0 and later. )
    15  
    16  <%= enterprise_alert :consul %>
    17  
    18  Consul Enterprise version supports network areas, which are operator-defined relationships
    19  between servers in two different Consul datacenters. The operator area command is used to
    20  interact with Consul's network area subsystem.
    21  
    22  Unlike Consul's WAN feature, network areas use just the server RPC port for communication,
    23  and relationships can be made between independent pairs of datacenters, so not all servers
    24  need to be fully connected. This allows for complex topologies among Consul datacenters like
    25  hub/spoke and more general trees.
    26  
    27  See the [Network Areas Guide](/docs/guides/areas.html) for more details.
    28  
    29  ```text
    30  Usage: consul operator area <subcommand> [options]
    31  
    32  The operator area command is used to interact with Consul's network area
    33  subsystem. Network areas are used to link together Consul servers in different
    34  Consul datacenters. With network areas, Consul datacenters can be linked
    35  together in ways other than a fully-connected mesh, as is required for Consul's
    36  WAN.
    37  
    38  Subcommands:
    39  
    40      create     Create a new network area
    41      delete     Remove a network area
    42      join       Join Consul servers into an existing network area
    43      list       List network areas
    44      members    Display Consul server members present in network areas
    45      update     Update the configuration of a network area
    46  ```
    47  
    48  If ACLs are enabled, the client will need to supply an ACL Token with `operator`
    49  read or write privileges to use these commands.
    50  
    51  ## create
    52  
    53  This command creates a new network area.
    54  
    55  Usage: `consul operator area create [options]`
    56  
    57  #### API Options
    58  
    59  <%= partial "docs/commands/http_api_options_client" %>
    60  <%= partial "docs/commands/http_api_options_server" %>
    61  
    62  #### Command Options
    63  
    64  * `-peer-datacenter=<value>` - Declares the peer Consul datacenter that will make up the other
    65  side of this network area. Network areas always involve a pair of datacenters: the datacenter
    66  where the area was created, and the peer datacenter. This is required.
    67  
    68  * `-retry-join=<value>` Specifies the address of a Consul server to join to, such as an IP
    69  or hostname with an optional port number. This is optional and can be specified multiple times.
    70  
    71  * `-use-tls=<value>` Specifies whether gossip over this area should be encrypted with
    72  TLS if possible. Must be either `true` or `false`.
    73  
    74  The output looks like this, displaying the ID of the newly-created network area:
    75  
    76  ```
    77  Created area "d2872ec5-68ea-b862-b75d-0bee99aca100" with peer datacenter "other"!
    78  ```
    79  
    80  The return code will indicate success or failure.
    81  
    82  ## delete
    83  
    84  This command deletes an existing network area.
    85  
    86  Usage: `consul operator area delete [options]`
    87  
    88  #### API Options
    89  
    90  <%= partial "docs/commands/http_api_options_client" %>
    91  <%= partial "docs/commands/http_api_options_server" %>
    92  
    93  #### Command Options
    94  
    95  * `-id=<value>` - Looks up the area to operate on by its ID. This can be given
    96  instead of a peer datacenter.
    97  
    98  * `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
    99  datacenter. This can be given instead of an ID.
   100  
   101  The output looks like this:
   102  
   103  ```
   104  Deleted area "154941b0-80e2-9d69-c560-ab2c02807332"!
   105  ```
   106  
   107  The return code will indicate success or failure.
   108  
   109  ## join
   110  
   111  This command joins Consul servers into an existing network area by address, such as
   112  an IP or hostname with an optional port. Multiple addresses may be given.
   113  
   114  Usage: `consul operator area join [options] ADDRESSES`
   115  
   116  #### API Options
   117  
   118  <%= partial "docs/commands/http_api_options_client" %>
   119  <%= partial "docs/commands/http_api_options_server" %>
   120  
   121  #### Command Options
   122  
   123  * `-id=<value>` - Looks up the area to operate on by its ID. This can be given
   124  instead of a peer datacenter.
   125  
   126  * `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
   127  datacenter. This can be given instead of an ID.
   128  
   129  The output looks like this:
   130  
   131  ```
   132  Address   Joined  Error
   133  10.1.2.3  false   failed to connect to "10.1.2.3:8300": dial tcp 10.1.2.3:8300: i/o timeout
   134  10.1.2.4  true    (none)
   135  10.1.2.5  true    (none)
   136  ```
   137  
   138  The `Error` field will have a human-readable error message if Consul was unable
   139  to join the given address.
   140  
   141  The return code will indicate success or failure.
   142  
   143  ## list
   144  
   145  This command lists all network areas.
   146  
   147  Usage: `consul operator area list [options]`
   148  
   149  #### API Options
   150  
   151  <%= partial "docs/commands/http_api_options_client" %>
   152  <%= partial "docs/commands/http_api_options_server" %>
   153  
   154  The output looks like this:
   155  
   156  ```
   157  Area                                  PeerDC  RetryJoin
   158  6a52a0af-62e2-dad4-da60-e66acc37096c  dc2     10.1.2.3,10.1.2.4,10.1.2.5
   159  96e33424-f5ce-9fcd-ecab-27974e36678f  other   (none)
   160  ```
   161  
   162  `Area` is the ID of the network area.
   163  
   164  `PeerDC` is the peer datacenter for the area.
   165  
   166  `RetryJoin` is the list of servers to join, defined when the area was created.
   167  
   168  The return code will indicate success or failure.
   169  
   170  ## members
   171  
   172  This command displays Consul server nodes present in a network area, or all
   173  areas if no area is specified.
   174  
   175  Usage: `consul operator area members [options]`
   176  
   177  #### API Options
   178  
   179  <%= partial "docs/commands/http_api_options_client" %>
   180  <%= partial "docs/commands/http_api_options_server" %>
   181  
   182  #### Command Options
   183  
   184  * `-id=<value>` - Looks up the area to operate on by its ID. This can be given
   185  instead of a peer datacenter.
   186  
   187  * `-peer-datacenter=<value>` - Looks up the area to operate on by its peer
   188  datacenter. This can be given instead of an ID.
   189  
   190  The output looks like this:
   191  
   192  ```
   193  Area                                  Node        Address         Status  Build  Protocol  DC   RTT
   194  6a52a0af-62e2-dad4-da60-e66acc37096c  node-1.dc1  127.0.0.1:8300  alive   0.8.0  2         dc1  0s
   195  6a52a0af-62e2-dad4-da60-e66acc37096c  node-2.dc1  127.0.0.2:8300  alive   0.8.0  2         dc1  594.191µs
   196  96e33424-f5ce-9fcd-ecab-27974e36678f  node-1.dc1  127.0.0.1:8300  alive   0.8.0  2         dc1  0s
   197  96e33424-f5ce-9fcd-ecab-27974e36678f  node-2.dc1  127.0.0.2:8300  alive   0.8.0  2         dc1  634.109µs
   198  ```
   199  
   200  `Area` is the ID of the network area.
   201  
   202  `Node` is the name of the node.
   203  
   204  `Address` is the IP and server RPC port for the node.
   205  
   206  `Status` is the current health status of the node, as determined by the network
   207  area distributed failure detector. This will be "alive", "leaving", "left", or
   208  "failed". A "failed" status means that other servers are not able to probe this
   209  server over its server RPC interface.
   210  
   211  `Build` has the Consul version running on the node.
   212  
   213  `Protocol` is the [protocol version](/docs/upgrading.html#protocol-versions) being
   214  spoken by the node.
   215  
   216  `DC` is the node's Consul datacenter.
   217  
   218  `RTT` is an estimated network round trip time from the server answering the query
   219  to the given server, in a human-readable format. This is computed using
   220  [network coordinates](/docs/internals/coordinates.html).
   221  
   222  The return code will indicate success or failure.
   223  
   224  ## update
   225  
   226  This command updates the configuration of network area.
   227  
   228  Usage: `consul operator area update [options]`
   229  
   230  #### API Options
   231  
   232  <%= partial "docs/commands/http_api_options_client" %>
   233  <%= partial "docs/commands/http_api_options_server" %>
   234  
   235  #### Command Options
   236  
   237  * `-id=<value>` - Looks up the area to operate on by its ID. This can be given
   238  instead of a peer datacenter.
   239  
   240  * `-peer-datacenter=<value>` - Declares the peer Consul datacenter that will make up the other
   241  side of this network area. Network areas always involve a pair of datacenters: the datacenter
   242  where the area was created, and the peer datacenter. This is required.
   243  
   244  * `-use-tls=<value>` Specifies whether gossip over this area should be encrypted with
   245  TLS if possible. Must be either `true` or `false`.
   246  
   247  The output looks like this:
   248  
   249  ```
   250  Updated area "d2872ec5-68ea-b862-b75d-0bee99aca100"
   251  ```
   252  
   253  The return code will indicate success or failure.