Create sameness groups

This topic describes how to create a sameness group, which designates a set of admin partitions as functionally identical in your network. Adding an admin partition to a sameness group enables Consul to recognize services registered to remote partitions with cluster peering connections as instances of the same service when they share a name and namespace.

For information about configuring a failover strategy using sameness groups, refer to Failover with sameness groups.

Workflow

Sameness groups are a user-defined set of partitions with identical configurations, including configuration entries for service and proxy defaults. Partitions on separate clusters should have an established cluster peering connection in order to recognize each other.

To create and use sameness groups in your network, complete the following steps:

Create sameness group configuration entries for each member of the group. For each partition that you want to include in the sameness group, you must write and apply a sameness group configuration entry that defines the group’s members from that partition’s perspective. Refer to the sameness group configuration entry reference for details on configuration hierarchy, default values, and specifications.
Export services to members of the sameness group. You must write and apply an exported services configuration entry that makes the partition’s services available to other members of the group. Refer to exported services configuration entry reference for additional specification information.
Create service intentions to authorize other members of the sameness group. For each partition that you want to include in the sameness group, you must write and apply service intentions configuration entries to authorize traffic to your services from all members of the group. Refer to the service intentions configuration entry reference for additional specification information.

Requirements

All datacenters where you want to create sameness groups must run Consul v1.16 or later. Refer to upgrade instructions for more information about how to upgrade your deployment.
A Consul Enterprise license is required.

Before you begin

Before creating a sameness group, take the following actions to prepare your network:

Check namespace and service naming conventions

Sameness groups are defined at the partition level. Consul assumes all partitions in the group have identical configurations, including identical service names and identical namespaces. This behavior occurs even when partitions in the group contain functionally different services that share a common name and namespace. For example, if distinct services named api were registered to different members of a sameness group, it could lead to errors because requests may be sent to the incorrect service.

To prevent errors, check the names of the services deployed to your network and the namespaces they are deployed in. Pay particular attention to the default namespace to confirm that services have unique names. If different services share a name, you should either change one of the service’s names or deploy one of the services to a different namespace.

Deploy mesh gateways for each partition

Mesh gateways are required for cluster peering connections and recommended to secure cross-partition traffic in a single datacenter. Therefore, we recommend securing your network, and especially your production environment, by deploying mesh gateways to each datacenter. Refer to mesh gateways specifications for more information about configuring mesh gateways.

Establish cluster peering relationships between remote partitions

You must establish connections with cluster peers before you can create a sameness group that includes them. A cluster peering connection exists between two admin partitions in different datacenters, and each connection between two partitions must be established separately with each peer. Refer to establish cluster peering connections for step-by-step instructions.

You can establish and manage cluster peering relationships between all of your self-managed clusters using HCP Consul Central. For more information, refer to cluster peering global view in the HCP documentation.

To establish cluster peering connections and define a group as part of the same workflow, follow instructions up to Export services between clusters. You can use the same exported services and service intention configuration entries to establish the cluster peering connection and create the sameness group.

Create a sameness group

To create a sameness group, you must write and apply a set of three configuration entries for each partition that is a member of the group:

Sameness group configuration entries: Defines the sameness group from each partition’s perspective.
Exported services configuration entries: Makes services available to other partitions in the group.
Service intentions configuration entries: Authorizes traffic between services across partitions.

Define the sameness group from each partition’s perspective

To define a sameness group for a partition, create a sameness group configuration entry that describes the partitions and cluster peers that are part of the group. Typically, the order follows this pattern:

The local partition
Other partitions in the same datacenter
Partitions with established cluster peering relationships

If you want all services to failover to other instances in the sameness group by default, set DefaultForFailover=true and list the group members in the order you want to use in a failover scenario. Refer to failover with sameness groups for more information.

Be aware that the sameness group configuration entries are different for each partition. The following example demonstrates how to format three different configuration entries for three partitions that are part of the sameness group product-group when Partition 1 and Partition 2 are in DC1, and the third partition is Partition 1 in DC2:

Kind                     = "sameness-group"  
Name                   = "product-group"
Partition                = "partition-1" 
Members                = [
      {Partition = "partition-1"},
      {Partition = "partition-2"},
      {Peer      = "dc2-partition-1"}
      ]

Kind                     = "sameness-group"  
Name                   = "product-group"
Partition                = "partition-2" 
Members                = [
      {Partition = "partition-2"},
      {Partition = "partition-1"},
      {Peer      = "dc2-partition-1"}
      ]

Kind                     = "sameness-group"  
Name                   = "product-group"
Partition                = "partition-1" 
Members                = [
      {Partition = "partition-1"},
      {Peer = "dc1-partition-1"},
      {Peer = "dc1-partition-2"}
      ]

After you create the configuration entry, apply it to the Consul server with the following CLI command:

$ consul config write product-group.hcl

Then, repeat the process to create and apply a configuration entry for every partition that is a member of the sameness group.

Export services to other partitions in the sameness group

To make services available to other members of the sameness group, you must write and apply an exported services configuration entry to each partition in the group. This configuration entry exports the local partition's services to the rest of the group members. In each configuration entry, set the sameness group as the Consumer for the exported services. You can export multiple services in a single exported services configuration entry.

Because you are configuring the consumer to reference the sameness group instead of listing out each partition and cluster peer, you do not need to edit this configuration again when you add a partition or peer to the group.

The following example demonstrates how to format three different exported-service configuration entries to make a service named api deployed to the store namespace of each partition available to all other group members:

Kind                     = "exported-services"  
Name                   = "product-sg-export"
Partition                = "partition-1" 
Services = [
  {
    Name = "api"
    Namespace = "store"
    Consumers = [
        {SamenessGroup="product-group"}
      ]
    }
 ]

Kind                     = "exported-services"  
Name                   = "product-sg-export"
Partition                = "partition-2" 
Services = [
  {
    Name = "api"
    Namespace = "store"
    Consumers = [
        {SamenessGroup="product-group"}
      ]
    }
 ]

Kind                     = "exported-services"  
Name                   = "product-sg-export"
Partition                = "partition-1" 
Services = [
  {
    Name = "api"
    Namespace = "store"
    Consumers = [
        {SamenessGroup="product-group"}
      ]
    }
 ]

For more information about exporting services, including examples of configuration entries that export multiple services at the same time, refer to the exported services configuration entry reference.

After you create each exported services configuration entry, apply it to the Consul server with the following CLI command:

$ consul config write product-sg-export.hcl

Export services for cluster peers and sameness groups as part of the same workflow

Creating a cluster peering connection between two partitions and then adding the partitions to a sameness group requires that you write and apply two separate exported services configuration entries. One configuration entry exports services to the peer, and a second entry exports services to other members of the group.

If your goal for peering clusters is to create a sameness group, you can write and apply a single exported services configuration entry by configuring the Services[].Consumers block with the SamenessGroup field instead of the Peer field.

Be aware that this scenario requires you to write the sameness-group configuration entry to Consul before you apply the exported-services configuration entry that references the sameness group.

Create service intentions to authorize traffic between group members

Exporting the service to other members of the sameness group makes the services visible to remote partitions, but you must also create service intentions so that local services are authorized to send and receive traffic from a member of the sameness group.

For each partition that is member of the group, write and apply a service intentions configuration entry that defines intentions for the services that are part of the group. In the Sources block of the configuration entry, include the service name, its namespace, the sameness group, and grant allow permissions.

Because you are using the sameness group in the Sources block rather than listing out each partition and cluster peer, you do not have to make further edits to the service intentions configuration entries when members are added to or removed from the group.

The following example demonstrates how to format three different service-intentions configuration entries to make a service named api available to all instances of payments deployed in all members of the sameness group including the local partition. In this example, api is deployed to the store namespace in all three partitions.

Kind      = "service-intentions"
Name      = "api-intentions"
Namespace = "store"
Partition = "partition-1"
Sources   = [
  {
    Name          = "api"
    Action        = "allow"
    Namespace     = "store"
    SamenessGroup = "product-group"
  }
]

Kind      = "service-intentions"
Name      = "api-intentions"
Namespace = "store"
Partition = "partition-2"
Sources   = [
  {
    Name          = "api"
    Action        = "allow"
    Namespace     = "store"
    SamenessGroup = "product-group"
  }
]

Kind      = "service-intentions"
Name      = "api-intentions"
Namespace = "store"
Partition = "partition-1"
Sources   = [
  {
    Name          = "api"
    Action        = "allow"
    Namespace     = "store"
    SamenessGroup = "product-group"
  }
]

Refer to create and manage intentions for more information about how to create and apply service intentions in Consul.

After you create each service intentions configuration entry, apply it to the Consul server with the following CLI command:

$ consul config write api-intentions.hcl

Create service intentions for cluster peers and sameness groups as part of the same workflow

Creating a cluster peering connection between two remote partitions and then adding the partitions to a sameness group requires that you write and apply two separate service intention configuration entries. One configuration entry authorizes services to the peer, and a second entry authorizes services to other members of the group.

If you are peering clusters with the goal of creating a sameness group, it is possible to combine these workflows by using a single service intentions configuration entry.

Configure the Sources block with the SamenessGroup field instead of the Peer field. Be aware that this scenario requires you to write the sameness-group configuration entry to Consul before you apply the service-intentions configuration entry that references the sameness group.

Next steps

When DefaultForFailover=true in a sameness group configuration entry, additional upstream configuration is not required.

After creating a sameness group, you can use them with static Consul DNS lookups and dynamic DNS lookups (prepared queries) for service discovery use cases. You can also set up failover between services in a sameness group. Refer to the following topics for more details: