Submariner connects multiple Kubernetes clusters in a way that is secure and performant. Submariner flattens the networks between the connected clusters, and enables IP reachability between Pods and Services. Submariner also provides, via Lighthouse, service discovery capabilities. The service discovery model is built using the proposed Kubernetes Multi Cluster Services.

Submariner consists of several main components that work in conjunction to securely connect workloads across multiple Kubernetes clusters, both on-premises and on public clouds:

  • Gateway Engine: manages the secure tunnels to other clusters.
  • Route Agent: routes cross-cluster traffic from nodes to the active Gateway Engine.
  • Broker: facilitates the exchange of metadata between Gateway Engines enabling them to discover one another.
  • Service Discovery: provides DNS discovery of Services across clusters.

Submariner has optional components that provide additional functionality:

The diagram below illustrates the basic architecture of Submariner:

Submariner Architecture

Terminology and Concepts

  • ClusterSet - a group of two or more clusters with a high degree of mutual trust that share Services amongst themselves. Within a cluster set, all namespaces with a given name are considered to be the same namespace.

  • ServiceExport (CRD) - used to specify which Services should be exposed across all clusters in the cluster set. If multiple clusters export a Service with the same name and from the same namespace, they will be recognized as a single logical Service.

    • ServiceExports must be explicitly created by the user in each cluster and within the namespace in which the underlying Service resides, in order to signify that the Service should be visible and discoverable to other clusters in the cluster set. The ServiceExport object can be created manually or via the subctl export command.

    • When a Service is exported, it then becomes accessible as <service>.<ns>.svc.clusterset.local.

    • For Headless Services, individual Pods can be accessed as <pod-name>.<cluster-id>.<svc-name>.<ns>.svc.clusterset.local. <cluster-id> must be a valid DNS-1123 Label

  • ServiceImport (CRD) - representation of a multi-cluster Service in each cluster. Created and used internally by Lighthouse and does not require any user action.