Submariner provides a Go-based Kubernetes custom controller, called an Operator, that provides easy API-based installation and management. A command line utility, subctl, wraps the Operator to aid users with manual deployments and easy experimentation. subctl greatly simplifies the deployment of Submariner, and is therefore the recommended deployment method. For complete information about subctl, please refer to this page.

In addition to Operator and subctl, Submariner also provides Helm Charts.

Installing subctl

Download the subctl binary and make it available on your PATH.

curl -Ls | bash
export PATH=$PATH:~/.local/bin
echo export PATH=\$PATH:~/.local/bin >> ~/.profile

If you have Go and the source code, you can build and install subctl instead:

cd go/src/submariner-io/submariner-operator
go install

(and ensure your go/bin directory is on your PATH).

Deployment of the Broker

The Broker is a set of Custom Resource Definitions (CRDs) backed by the Kubernetes datastore. The Broker must be deployed on a cluster whose Kubernetes API is accessible by all of the participating clusters.

subctl deploy-broker --kubeconfig <PATH-TO-KUBECONFIG-BROKER>

This will create:

  • The submariner-k8s-broker namespace.
  • The Endpoint and Cluster CRDs in the cluster.
  • A Service Account (SA) in the namespace for subsequent subctl access.

It also generates the broker-info.subm file which contains the following elements:

  • The API endpoint.
  • A CA certificate for the API endpoint.
  • The Service Account token for accessing the API endpoint.
  • A random IPsec PSK which will be stored only in this file.
  • Service Discovery settings.

The cluster in which the Broker is deployed can also participate in the dataplane connectivity with other clusters, but it will need to be joined (see following step).

You can customize the Broker namespace using the --broker-namespace flag, allowing you to use a namespace of your choice on the Broker for synchronising resources between clusters.

subctl deploy-broker --broker-namespace <CUSTOM-NAMESPACE> ...

Reference the subctl deploy-broker flag docs for additional details.

Joining clusters

For each cluster you want to join, issue the following command:

subctl join --kubeconfig <PATH-TO-JOINING-CLUSTER> broker-info.subm --clusterid <ID>

subctl will automatically discover as much as it can, and prompt the user for any missing necessary information. Note that each cluster must have a unique cluster ID; the cluster ID can be specified, or otherwise is going to be generated by default based on the cluster name in the kubeconfig file.