HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Consul
Consul Home

Create sameness groups on Kubernetes

This topic describes how to create a sameness group, which designates a set of admin partitions as functionally identical in a Consul deployment running Kubernetes. 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 Consul namespace.

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

Overview

Sameness groups are a user-defined set of partitions with identical configurations, includingcustom resource definitions (CRDs) 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 custom resource definitions (CRDs) 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 CRD 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 CRD 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 for each member of the sameness group. For each partition that you want to include in the sameness group, you must write and apply service intentions CRDs 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

Before you begin

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

Check Consul namespaces 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 Consul namespaces. This behavior occurs even when two partitions in the group contain functionally different services that share a common name and namespace. For example, if distinct services both 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.

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 CRDs for each partition that is a member of the group:

  • Sameness group CRDs: Define the sameness group from each partition’s perspective.
  • Exported services CRDs: Make services available to other partitions in the group.
  • Service intentions CRDs: Authorize 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 CRD that describes the partitions and cluster peers that are part of the group. Typically, this order follows this pattern:

  1. The local partition
  2. Other partitions in the same datacenter
  3. Partitions with established cluster peering relationships

If you want all services to failover to other instances in the sameness group by default, set spec.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 CRDs are different for each partition. The following example demonstrates how to format three different CRDs 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:

product-group.yaml

apiVersion: consul.hashicorp.com/v1alpha1
kind: SamenessGroup 
metadata:
  name: product-group
spec:
  defaultForFailover: true
  members:                                   
    - partition: partition-1
    - partition: partition-2
    - peer: dc2-partition-1

After you create the CRD, apply it to the Consul server with the following kubectl CLI command:

$ kubectl apply -f product-group.yaml

Then, repeat the process to create and apply a CRD 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 CRD for each partition in the group. This CRD exports the local partition's services to the rest of the group members. In each CRD, 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 ExportedServices CRDs to make a service named api deployed to the store namespace of each partition available to all other group members:

apiVersion: consul.hashicorp.com/v1alpha1
Kind: ExportedServices
metadata:
  name: partition-1
spec:
  services:
    - name: api
      namespace: store
      consumers:
        - samenessGroup: product-group

For more information about exporting services, including examples of CRDs 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:

$ kubectl apply -f product-group-export.yaml

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 CRDs. One CRD exports services to the peer, and a second CRD 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 SamenessGroup CRD to Kubernetes before you apply the ExportedServices CRD 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 a member of the group, write and apply a service intentions CRD 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 ServiceIntentions CRDs 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.

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
  name: api-intentions
spec:
  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:

$ kubectl apply -f api-intentions.yaml

Create service intentions 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 service intentions CRDs. One CRD authorizes services for the peer, and a second CRD authorizes services for other members of the group.

If your goal for peering clusters is to create a sameness group, you can write and apply a single service intentions CRD by configuring the sources block with the samenessGroup field instead of the peer field. Be aware that this scenario requires you to write the SamenessGroup CRD to Kubernetes before you apply the ServiceIntentions CRD that references the sameness group.

Next steps

When defaultForFailover=true in a sameness group CRD, additional upstream configuration is not required.

After creating a sameness group, you can also set up failover between services in a sameness group. Refer to Failover with sameness groups for more information.

Edit this page on GitHub