Create Network Segments

This topic describes how to create Consul network segments so that services can connect to other services in the LAN gossip pool that have been placed into separate communication boundaries. Refer to Network Segments Overview for additional information.

Requirements

  • Consul Enterprise 0.9.3+

Define segments in the server configuration

  1. Add the segments block to your server configuration. Refer to the segments documentation for details about how to define the configuration.

    In the following example, an alpha segment is configured to listen for traffic on port 8303 and a beta segment is configured to listen to traffic on port 8304:

    Example network segments configuration for server agents

    Example network segments configuration for server agents

    1. segments = [
    2. {
    3.    name = "alpha"
    4.    bind = "10.0.0.1"
    5.    advertise = "10.0.0.1"
    6.    port = 8303
    7. },
    8. {
    9.    name = "beta"
    10.    bind = "10.0.0.1"
    11.    advertise = "10.0.0.1"
    12.    port = 8304
    13. }
    14. ]
    1. {
    2. "segments": [
    3.    {
    4.       "name": "alpha",
    5.       "bind": "10.0.0.1",
    6.       "advertise": "10.0.0.1",
    7.       "port": 8303
    8.    },
    9.    {
    10.       "name": "beta",
    11.       "bind": "10.0.0.1",
    12.       "advertise": "10.0.0.1",
    13.       "port": 8304
    14.    }
    15. ]
    16. }

  2. Start the server using the consul agent command. Copy the address for each segment listener so that you can direct clients to join the segment when you start them:

    1. $ consul agent -config-file server.hcl
    2. [INFO] serf: EventMemberJoin: server1.dc1 10.20.10.11
    3. [INFO] serf: EventMemberJoin: server1 10.20.10.11
    4. [INFO] consul: Started listener for LAN segment "alpha" on 10.20.10.11:8303
    5. [INFO] serf: EventMemberJoin: server1 10.20.10.11
    6. [INFO] consul: Started listener for LAN segment "beta" on 10.20.10.11:8304
    7. [INFO] serf: EventMemberJoin: server1 10.20.10.11

  3. Verfiy that the server is a member of all segments:

    1. $ consul members
    2. Node          Address           Status  Type    Build      Protocol  DC   Segment
    3. server1       10.20.10.11:8301  alive   server  1.14+ent  2         dc1  <all>

Configure clients to join segments

Client agents can only be members of one segment at a time. You can direct clients to join a segment by specifying the address and name of the segment with the -join and -segment command line flags when starting the agent.

  1. $ consul agent -config-file client.hcl -join 10.20.10.11:8303 -segment alpha

Alternatively, you can add the retry_join and segment parameters to your client agent configuration file:

  1. node_name  = "consul-client"
  2. server     = false
  3. datacenter = "dc1"
  4. data_dir   = "consul/client-data"
  5. log_level  = "INFO"
  6. retry_join = ["10.20.10.11:8303"]
  7. segment = "alpha"

Verify segments

You can use the CLI, API, or GUI to verify which segments your agents have joined.

Run the consul members command to verify that the client agents are joined to the correct segments:

  1. $ consul members
  2. Node             Address        Status  Type     Build       Protocol  DC   Partition  Segment
  3. server    192.168.4.159:8301    alive   server   1.14+ent  2         dc1  default    <all>
  4. client1   192.168.4.159:8447    alive   client   1.14+ent  2         dc1  default    alpha

You can also pass the name of a segment in the -segment flag to view agents in a specific segment. Note that server agents display their LAN listener port for the specified segment the segment filter applied. In the following example, the command returns port 8303 for alpha, rather than for the <default> segment port:

  1. $ consul members -segment alpha
  2. Node          Address           Status  Type    Build      Protocol  DC   Segment
  3. server1      10.20.10.11:8301   alive   server  1.14+ent  2         dc1  alpha
  4. client1      10.20.10.21:8303   alive   client  1.14+ent  2         dc1  alpha

Refer to the members documentation for additional information.

Call the /agent/members API endpoint to view members that the agent sees in the cluster gossip pool.

  1. $ curl http://127.0.0.1:8500/v1/agent/members?segment=alpha 
  3. {
  4.    "Addr" : "192.168.4.163",
  5.    "DelegateCur" : 4,
  6.    "DelegateMax" : 5,
  7.    "DelegateMin" : 2,
  8.    "Name" : "consul-client",
  9.    "Port" : 8447,
  10.    "ProtocolCur" : 2,
  11.    "ProtocolMax" : 5,
  12.    "ProtocolMin" : 1,
  13.    "Status" : 1,
  14.    "Tags" : {
  15.       "build" : "1.13.1+ent:5bd604e6",
  16.       "dc" : "dc1",
  17.       "ft_admpart" : "1",
  18.       "ft_ns" : "1",
  19.       "id" : "aeaf70d7-57f7-7eaf-e246-6edfe8386e9c",
  20.       "role" : "node",
  21.       "segment" : "alpha",
  22.       "vsn" : "2",
  23.       "vsn_max" : "3",
  24.       "vsn_min" : "2"
  25.    }
  26. }

Refer to the /agent/members API endpoint documentation for additional information.

If the UI is enabled in your agent configuration, the segment name appears in the node’s Metadata tab.

  1. Open the URL for the UI. By default, the UI is localhost:8500.
  2. Click Node in the sidebar and click on the name of the client agent you want to check.
  3. Click the Metadata tab. The network segment appears as a key-value pair.

You can also create and run a prepared query to query for additional information about the services registered to client nodes. Prepared queries are HTTP API endpoint features that enable you to run complex queries of Consul nodes. Refer Prepared Query HTTP Endpoint for usage.