About segments

In multicluster service meshes, the principle of namespace sameness determines how services are identified and aggregated across clusters. While this approach provides significant operational benefits, it introduces critical limitations when namespace naming cannot be aligned across all clusters.

Version 1.28 of the Solo distribution of Istio introduces segments to address these fundamental limitations. Segments enable logical mesh partitioning, allowing you to organize clusters and namespaces into discrete units that operate independently while maintaining the benefits of a unified service mesh. This approach provides the flexibility that enterprise organizations need without sacrificing the security and operational benefits of Istio’s multicluster capabilities.

Key capabilities include:

  • Independent namespace management: Different segments can use different naming conventions and organizational patterns without conflict.
  • Cross-segment service communication: Services in different segments can communicate securely with explicit configuration.
  • Flexible migration paths: Organizations can transition between multitenancy patterns within segments or migrate services between segments as needed.
  • Simplified policy management: Authorization and traffic policies apply predictably within segment boundaries.

Segments achieve all of these capabilities by logically partitioning your mesh into discrete units that operate independently. Each segment maintains namespace sameness internally while eliminating the requirement across segments, allowing different organizational patterns in each segment.

How segments work

Segments provide logical mesh partitioning through a custom resource that creates discrete units within your global mesh. Each segment maintains namespace sameness internally while allowing different organizational patterns across segments.

A segment defines a logical grouping of clusters and namespaces that share common identity and addressing rules. Each segment has a unique domain that eliminates naming conflicts, and services within a segment are addressed using the pattern <service>.<namespace>.<segment-domain>.

Segment resource structure

Segments are defined using a Segment custom resource, which must be applied to the istio-system namespace in each cluster that needs awareness of that segment. The configuration also defines a unique, custom domain for the segment, such as mesh.acme in the following example.

  apiVersion: admin.istio.io/v1
kind: Segment
metadata:
  name: acme-segment
  namespace: istio-system  # Required namespace
spec:
  domain: mesh.acme  # Unique domain for this segment

You then assign a cluster to a segment by labeling its istio-system namespace. Note that a cluster can belong to exactly one segment.

  kubectl label namespace istio-system admin.solo.io/segment=acme-segment

Each cluster must have access to the segment resources associated with its peers. For example, if you have two peered clusters, deploy the exact same segment CRs to both clusters before assigning clusters to segments. If a segment resource does not exist for a peer cluster, service discovery for that peer is disabled, and an error status is reported on the corresponding peer Gateway.

For detailed steps to create segments in your multitenant, multicluster mesh, see Create segments.

Multicluster service discovery within segments

After you create the segments, you can make segmented services available across clusters. For example, you can apply the solo.io/service-scope label to either an individual service that you want to be accessible from multiple clusters, or to an entire namespace so that global hostnames are created for each service in that namespace. A global service entry with a hostname in the format <svc_name>.<namespace>.<segment_domain> is created for the service.

For detailed steps to expose services in segments across clusters, see Make segmented services available across clusters.

Segments solutions to namespace sameness challenges

While namespace sameness provides significant benefits, several common scenarios in enterprise environments violate its assumptions, leading to routing conflicts, security issues, and operational complexity.

Review the following namespace sameness challenges. Then, flip to the segment solution tab for each challenge to see how segments solve each problem.

Organizational constraints

The most significant limitation stems from Istio’s reliance on namespace sameness across clusters. Different business units often have independent naming conventions or existing namespace structures that cannot be easily aligned across clusters. Large organizations may find it impractical to enforce consistent naming across autonomous teams, regions, or business units, especially when these groups operate independently with their own governance structures.

Acquisitions and mergers compound this challenge. When organizations merge infrastructure, reconciling namespace naming across previously independent systems is often infeasible. Legacy systems with established naming conventions may be impossible to change without significant risk and disruption.

Scenario 1: Onboarded cluster breaks namespace sameness

Consider this challenge with a concrete scenario.

Problem: ACME has two clusters, acme-us-east and acme-us-west, that successfully use namespace sameness. Their global hostnames, such as foo.foo.mesh.internal and bar.bar.mesh.internal, unify the endpoints of each service across clusters. However, when ACME acquires another company and peers the acquired-company cluster, service name and namespace conflicts arise.

Impact: Both organizations have services named bar in the bar namespace. When clusters are peered, endpoints are aggregated, causing clients calling bar.bar.mesh.internal to randomly hit either ACME’s or the acquired company’s service, which are two logically different backends.

Without a solution to this namespace sameness violation, organizations must either rename services, which is disruptive and risky, or avoid peering clusters entirely, sacrificing multicluster benefits.

Now, review how segments can resolve this problem.

  1. In every cluster, create acme and acquired-company segments, with domains mesh.acme and mesh.acquired.
  2. Label the istio-system namespace in the ACME clusters with the acme segment.
  3. Label the istio-system namespace in the acquired company cluster with the acquired-company segment.

Result: Services are now addressable separately:

  • bar.bar.mesh.acme routes to the endpoints for the bar services in ACME’s clusters.
  • bar.bar.mesh.acquired routes to the endpoint for the bar service in the acquired company’s cluster.

Global service aggregation conflicts

When namespace sameness breaks down, services cannot be properly grouped across clusters if they have different names, ports, or namespaces. This prevents effective load balancing and failover across cluster boundaries. Even when services are logically similar and should work together, Istio cannot aggregate them without matching names and namespaces.

Conversely, when different services share the same name and namespace across clusters, Istio incorrectly aggregates them, as illustrated in the previous scenario. This creates unpredictable routing behavior and potential security vulnerabilities where traffic intended for one service reaches an entirely different application.

Scenario 2: Peering different environments

Environment separation represents another common scenario where namespace sameness creates problems.

Problem: Development and QA environments need to communicate across clusters, but they use identical service names in identical namespaces. The foo.foo.mesh.internal global hostname unifies the endpoints of each service across clusters.

Impact: When dev and qa clusters are peered, the foo.foo.mesh.internal global hostname aggregates all foo.foo service endpoints. Clients cannot selectively target only dev or only QA versions of services.

This makes testing workflows impossible when they require communication between environments, such as integration tests in QA that need to call dev services, or gradual migration scenarios where some components move to QA while others remain in dev.

Now, review how segments can resolve this problem.

  1. In every cluster, create dev and qa segments with domains mesh.dev and mesh.qa.
  2. Label the istio-system namespace in dev clusters with the dev segment.
  3. Label the istio-system namespace in QA clusters with the qa segment.

Result: Environment-specific addressing becomes possible:

  • foo.foo.mesh.dev routes only to the endpoints for the dev environment services.
  • foo.foo.mesh.qa routes only to the endpoints for the QA environment services.

Complex peering topologies

Partial peering and transitive relationships introduce additional complexity. In large mesh deployments, not all clusters are directly peered with each other. Instead, clusters may have partial peering relationships where cluster 1 peers with cluster 2, and cluster 2 peers with cluster 3, but clusters 1 and 3 are not directly peered.

When namespace sameness violations exist in such topologies, the middle cluster (cluster 2) receives conflicting service definitions from both sides, leading to unpredictable behavior.

Scenario 3: Transitive peering conflicts

Problem: Three clusters use partial peering, in that clusters 1 and 2 are peered, and clusters 2 and 3 are peered, but clusters 1 and 3 are not directly peered. Clusters 1 and 3 both have different foo.foo services.

Impact: Cluster 2’s Istio control plane receives conflicting ServiceEntry resources for foo.foo, causing unpredictable routing behavior where only one service may be reachable.

Without a solution, cluster 2 cannot reliably address both services, forcing operators to either avoid partial peering topologies or implement complex workarounds.

Now, review how segments can resolve this problem.

  1. Create the following segments based on the clusters’ peering relationships:
    • In cluster 1, create segments cluster-1 and cluster-2 with domains mesh.one and mesh.two.
    • In cluster 2, which is peered with both clusters, create segments cluster-1, cluster-2, and cluster-3 with domains mesh.one, mesh.two, and mesh.three.
    • In cluster 3, create segments cluster-2 and cluster-3 with domains mesh.two and mesh.three.
  2. Label each cluster’s istio-system namespace with its respective segment.

Result: Cluster 2 can address both services distinctly:

  • foo.foo.mesh.one routes only to the endpoint for cluster 1’s foo service.
  • foo.foo.mesh.three routes only to the endpoint for cluster 3’s foo service.

Solution summary

While an alternative approach to these namespace sameness conflicts might be to simply avoid peering clusters, this solution sacrifices the core benefits of a multicluster service mesh. Without peering, you lose automatic failover, cross-cluster load balancing, unified policy management, and the ability to treat geographically distributed services as a single logical application.

Segments provide a better solution by enabling you to maintain all multicluster benefits while resolving namespace conflicts. With segments, you can:

  • Peer clusters safely without namespace collision concerns
  • Enable cross-segment service communication when needed with explicit configuration
  • Support flexible organizational patterns like mergers, multi-environment deployments, and complex topologies
  • Maintain unified observability and policy management across your entire mesh

Segments allow you to adopt multicluster architectures that match your organizational reality, rather than forcing organizational changes to fit technical constraints.

Understanding segment limitations

Segments specifically address namespace sameness challenges in multicluster environments. However, they don’t solve all multitenancy concerns. Understanding what segments don’t address helps you plan a complete multitenancy strategy.

What segments solve

Segments provide solutions for:

  • Namespace naming conflicts across clusters
  • Service aggregation issues across differently named services
  • Flexible organizational patterns across clusters
  • Migration paths between multitenancy patterns

What segments do not solve

Segments create logical boundaries for service discovery and addressing but don’t automatically enforce other multitenancy requirements. You must still implement additional controls for a complete multitenancy solution.

Traffic isolation

Segments create logical boundaries but don’t enforce traffic isolation. You still need Istio AuthorizationPolicy resources to control which services can communicate within and across segments.

A fundamental requirement for multitenancy is precisely controlling whether and how traffic flows between tenants. Tenants are typically isolated from each other by default, following a zero-trust security model in which all traffic is denied unless explicitly authorized. Istio provides robust building blocks to achieve required traffic isolation through the AuthorizationPolicy API, which works alongside segments.

AuthorizationPolicy resources are scoped at the namespace level and can express rules allowing or denying traffic based on several identity attributes:

  • Service account: Authorize traffic from specific workloads based on Kubernetes service accounts.
  • Namespace: Authorize traffic from any workload within one or more specific namespaces.
  • Cluster: Express cluster-level authorization using trust domains, provided that each cluster has a unique trust domain identifier.

Multiple AuthorizationPolicy resources targeting the same workload are evaluated consistently with well-defined rules for merging and precedence, making traffic isolation behavior predictable and manageable.

Configuration isolation

Configuration isolation ensures that configuration changes made by one tenant do not impact other tenants, unless explicitly agreed upon by both parties. Kubernetes namespaces serve as the fundamental unit for configuration scope, and Istio adheres to this model. Segments don’t change these configuration isolation requirements.

Istio resource visibility: Istio resources (including Gateway API resources) are scoped to a namespace by default, meaning that a tenant’s configuration changes only affect that tenant’s workloads. RBAC ensures that tenants cannot modify resources outside their namespace, containing any blast radius of misconfigurations. The exception to this standard are Istio API resources created in the rootNamespace (istio-system by default), which have mesh-wide scope. However, access to this namespace is typically limited to mesh administrators or platform teams.

Additionally, while Istio resources are namespaced and apply only within their defined namespace, certain traffic management resources such as DestinationRule and ServiceEntry have configurable visibility across namespaces. By default, these resources are visible cluster-wide, meaning tenants could inadvertently expose services or configurations to other namespaces.

Gateway API considerations: When using the Kubernetes Gateway API for ingress and east-west traffic in your service mesh, configuration is isolated by namespace. Gateway API resources like Gateway and HTTPRoute are namespaced, and cross-namespace references require you to explicitly grant access with a ReferenceGrant resource.

Service discovery visibility

In multitenant environments, security requirements often dictate restricting service discovery. Applications should not only be prevented from accessing unauthorized services, but should also not have visibility into their existence. Segments address service addressing conflicts but don’t restrict service discovery visibility.

Service registry visibility: Istio’s service registry is populated by discovering ServiceEntry and Kubernetes Service resources. In ambient mesh, these registry entries are visible cluster-wide, so tenants could potentially expose their services to other namespaces unintentionally. To prevent unintended cross-tenant traffic, define AuthorizationPolicy resources as discussed in the traffic isolation section.

DNS-level visibility: DNS-based service discovery in Kubernetes and Istio currently lacks built-in fine-grained visibility controls. Pods can perform DNS queries (using tools like nslookup or dig) to discover service names across all namespaces in the cluster. For example, a pod can query <service-name>.<namespace>.svc.cluster.local to test if services exist, even if actual network access is blocked by AuthorizationPolicy resources at runtime.

By default, CoreDNS allows cross-namespace service name resolution, potentially exposing the existence of services to unauthorized tenants. This represents an information disclosure risk in multitenant environments, as tenants can map out the service landscape even when they cannot access those services directly.

Other considerations

Beyond the technical controls described above, a complete multitenancy strategy requires:

  • RBAC: Namespace-level access control to ensure tenants can only modify their own resources.
  • Platform team coordination: Segment definitions should be managed centrally by platform teams to ensure consistent addressing and prevent conflicts.
  • Monitoring and observability: Telemetry and observability tools must be configured to provide appropriate visibility within and across segment boundaries.

Next steps

Now that you understand namespace sameness challenges and how segments address them, follow the steps to create segments in your mesh environment.