Connecting Clusters

There are three steps to adding clusters using the Shipa dashboard.

  • Cluster setup
  • Cluster connection
  • Ingress controller

The sections below explain each of the three parts in detail.

Connecting Clusters Workflow

Cluster Setup

You can add Kubernetes clusters using Shipa's dashboard. Open the Clusters page, then click the Add Cluster button to open the Add Cluster page.

You should enter the following information during this step:

  • Name:the cluster identifier name. The name used in this field does not need to match the actual name of the Kubernetes cluster.
  • Frameworks: one or multiple frameworks that you want to bind to this cluster. By default, the dashboard only shows available frameworks that are not yet bound to other clusters.

Click on Next.

Cluster Connection

In this second step, you will be required to enter the connection details that Shipa should use when connecting to your Cluster API.

You can find your cluster address by running the command below:

kubectl cluster-info | grep 'Kubernetes' | awk '/http/ {print $NF}'

The next fields you will need to enter are Token and CA Certificate.

Shipa requires a service account to connect to your cluster. Once created, this service account will give you a token and CA Certificate that you should use in the next two fields.

To create this service account, you can use the file and execution instruction below:

1. Create a file called shipa-admin-service-account.yaml with the following content:
*Note, the rbac.authorization has moved from v1beta1 to v1 in Kubernetes 1.22+

apiVersion: v1
kind: ServiceAccount
  name: shipa-admin
  namespace: kube-system
kind: ClusterRoleBinding
  name: shipa-admin
  kind: ClusterRole
  name: cluster-admin
- kind: ServiceAccount
  name: shipa-admin
  namespace: kube-system

2. Apply the newly created service account and cluster role binding to your cluster:

kubectl apply -f shipa-admin-service-account.yaml


Cluster level roles

Container.clusterRoleBindings.create permission is required to create cluster-level roles.

If you do not have container.clusterRoleBindings.create permission, you can alternatively enable Basic Authentication and then run the kubectl apply command as an admin, as shown below:

$ kubectl apply -f shipa-admin-service-account.yaml --username=admin --password=

3. Retrieve the token for the shipa-admin service account with the command below:

kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep shipa-admin | awk '{print $1}')

Copy the <authentication_token> value from the output generated by the command above:

Name:         shipa-admin-token-b5zv4
Namespace:    kube-system
Labels:       <none>


ca.crt:     1025 bytes
namespace:  11 bytes
token:      <authentication_token>

Enter the token output in the Token field of the cluster connection step form

4. Retrieve the CA Certificate for the shipa-admin service account with the command below:

kubectl get secret $(kubectl get secret | grep default-token | awk '{print $1}') -o jsonpath='{\.crt}' | base64 --decode

Copy and paste the output into the CA Certificate field of the form

Click on Next.

Ingress Controller

The last step will allow you to enter specific information regarding the ingress controller used in the cluster. Shipa leverages the cluster ingress controller to deliver application-specific functionalities, such as endpoints, CNAME management, and more, so the information entered on this step will be used by Shipa when binding frameworks to that cluster.

The fields displayed on this last step will change based on the ingress controller you selected when creating the framework you are binding to this cluster during the cluster connection workflow.

Shipa supports nginx (default), istio and traefik ingress controllers. See table below for supported versions of these ingress controllers.


Supported Version


= v1.0.4





Cert Manager


If you are using Nginx as the ingress for your framework - Nginx is default ingress when you create a framework, the fields displayed in the image above are optional. Shipa automatically configures Nginx as part of its internal cluster connection workflow. You don't need to enter any specific information unless you want to provide Shipa with custom Nginx ingress information so Shipa can properly connect to it.

If you are using Istio or Traefik as the ingress controller for the framework you are binding to this cluster, e.g. you should see the following options in this last step if you are using Istio:

When using Istio or Traefik or your own Nginx, Shipa requires you to enter the Ingress IP of your ingress service, so Shipa can properly connect to it and provide the default services to the applications you deploy.

e.g. you can find Istio's Ingress IP by running the command below:

kubectl get services -n istio-system

You should use the IP presented under the EXTERNAL-IP column.


Cert Manager

Shipa expects Cert Manager to be installed along with ingress. If not already installed, Shipa installs cert manager.

Click on Create.

This will start the process, and you can check on its progress through the Events page in your Shipa dashboard. Once Shipa is connected to your cluster, and the selected frameworks are bound to it, you can start deploying your applications.

What’s Next

Cluster integration can also be managed directly through the Shipa CLI. For more information, please visit the page below:

Did this page help you?