Skip to content
Switch branches/tags

Skupper Hello World


A minimal HTTP application deployed across Kubernetes clusters using Skupper

This example is part of a suite of examples showing the different ways you can use Skupper to connect services across cloud providers, data centers, and edge sites.



This example is a very simple multi-service HTTP application that can be deployed across multiple Kubernetes clusters using Skupper.

It contains two services:

  • A backend service that exposes an /api/hello endpoint. It returns greetings of the form Hi, <your-name>. I am <my-name> (<pod-name>).

  • A frontend service that sends greetings to the backend and fetches new greetings in response.

With Skupper, you can place the backend in one cluster and the frontend in another and maintain connectivity between the two services without exposing the backend to the public internet.


  • The kubectl command-line tool, version 1.15 or later (installation guide)

  • The skupper command-line tool, the latest version (installation guide)

  • Access to at least one Kubernetes cluster, from any provider you choose

Step 1: Configure separate console sessions

Skupper is designed for use with multiple namespaces, typically on different clusters. The skupper command uses your kubeconfig and current context to select the namespace where it operates.

Your kubeconfig is stored in a file in your home directory. The skupper and kubectl commands use the KUBECONFIG environment variable to locate it.

A single kubeconfig supports only one active context per user. Since you will be using multiple contexts at once in this exercise, you need to create distinct kubeconfigs.

Start a console session for each of your namespaces. Set the KUBECONFIG environment variable to a different path in each session.

Console for west:

export KUBECONFIG=~/.kube/config-west

Console for east:

export KUBECONFIG=~/.kube/config-east

Step 2: Access your clusters

The methods for accessing your clusters vary by Kubernetes provider. Find the instructions for your chosen providers and use them to authenticate and configure access for each console session. See the following links for more information:

Step 3: Set up your namespaces

Use kubectl create namespace to create the namespaces you wish to use (or use existing namespaces). Use kubectl config set-context to set the current namespace for each session.

Console for west:

kubectl create namespace west
kubectl config set-context --current --namespace west

Console for east:

kubectl create namespace east
kubectl config set-context --current --namespace east

Step 4: Install Skupper in your namespaces

The skupper init command installs the Skupper router and service controller in the current namespace. Run the skupper init command in each namespace.

Note: If you are using Minikube, you need to start minikube tunnel before you install Skupper.

Console for west:

skupper init

Console for east:

skupper init

Step 5: Check the status of your namespaces

Use skupper status in each console to check that Skupper is installed.

Console for west:

skupper status

Console for east:

skupper status

You should see output like this for each namespace:

Skupper is enabled for namespace "<namespace>" in interior mode. It is not connected to any other sites. It has no exposed services.
The site console url is: http://<address>:8080
The credentials for internal console-auth mode are held in secret: 'skupper-console-users'

As you move through the steps below, you can use skupper status at any time to check your progress.

Step 6: Link your namespaces

Creating a link requires use of two skupper commands in conjunction, skupper token create and skupper link create.

The skupper token create command generates a secret token that signifies permission to create a link. The token also carries the link details. Then, in a remote namespace, The skupper link create command uses the token to create a link to the namespace that generated it.

Note: The link token is truly a secret. Anyone who has the token can link to your namespace. Make sure that only those you trust have access to it.

First, use skupper token create in one namespace to generate the token. Then, use skupper link create in the other to create a link.

Console for west:

skupper token create ~/west.token

Console for east:

skupper link create ~/west.token

If your console sessions are on different machines, you may need to use scp or a similar tool to transfer the token.

You can use the skupper link status command to check if linking succeeded.

Step 7: Deploy the frontend and backend services

Use kubectl create deployment to deploy the frontend service in west and the backend service in east.

Console for west:

kubectl create deployment frontend --image

Console for east:

kubectl create deployment backend --image --replicas 3

Step 8: Expose the backend service

We now have two namespaces linked to form a Skupper network, but no services are exposed on it. Skupper uses the skupper expose command to select a service from one namespace for exposure on all the linked namespaces.

Use skupper expose to expose the backend service to the frontend service.

Console for east:

skupper expose deployment/backend --port 8080

Step 9: Expose the frontend service

We have established connectivity between the two namespaces and made the backend in east available to the frontend in west. Before we can test the application, we need external access to the frontend.

Use kubectl expose with --type LoadBalancer to open network access to the frontend service.

Console for west:

kubectl expose deployment/frontend --port 8080 --type LoadBalancer

Sample output:

service/frontend exposed

Step 10: Test the application

Now we're ready to try it out. Use kubectl get service/frontend to look up the external IP of the frontend service. Then use curl or a similar tool to request the /api/health endpoint at that address.

Note: The <external-ip> field in the following commands is a placeholder. For you, it is an IP address.

Console for west:

kubectl get service/frontend
curl http://<external-ip>:8080/api/health

Sample output:

$ kubectl get service/frontend
NAME       TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
frontend   LoadBalancer   <external-ip>   8080:30407/TCP   15s

$ curl http://<external-ip>:8080/api/health

If everything is in order, you can now access the web interface by navigating to http://<external-ip>:8080/ in your browser. The frontend assigns each new user a name. Click Hello to send greetings to the backend.


This example locates the frontend and backend services in different namespaces, on different clusters. Ordinarily, this means that they have no way to communicate unless they are exposed to the public internet.

Introducing Skupper into each namespace allows us to create a virtual application network that can connect services in different clusters. Any service exposed on the application network is represented as a local service in all of the linked namespaces.

The backend service is located in east, but the frontend service in west can "see" it as if it were local. When the frontend sends a request to the backend, Skupper forwards the request to the namespace where the backend is running and routes the response back to the frontend.

Cleaning up

To remove Skupper and the other resources from this exercise, use the following commands.

Console for west:

skupper delete
kubectl delete service/frontend
kubectl delete deployment/frontend

Console for east:

skupper delete
kubectl delete deployment/backend

Next steps

Check out the other examples on the Skupper website.