The Shipa Developer Hub

Welcome to the Shipa developer hub. You'll find comprehensive guides and documentation to help you start working with Shipa as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog

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
metadata:
  name: shipa-admin
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: shipa-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- 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>
Annotations:  kubernetes.io/service-account.name=gitlab-admin
              kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8

Type:  kubernetes.io/service-account-token

Data
====
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='{.data.ca\.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.

If you are using Traefik as the ingress for your framework, the fields displayed in the image above are optional. Shipa automatically configures Traefik 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 Traefik ingress information so Shipa can properly connect to it.

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

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

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.

📘

Istio ingress controller support

Shipa expects Cert Manager to be installed along with Istio ingress. Istio support requires cert manager to be installed on the cluster.

Note: Istio 1.7 and higher requires Kubernetes 1.16+.

Refer to Istio documentation for details.

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.

Updated 21 days ago


What's Next

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

Managing Clusters

Connecting Clusters


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.