Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
214 lines (145 sloc) 7.75 KB

Skupper Hello World

A minimal HTTP application deployed with Skupper


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 Hello <count>.

  • A frontend service that accepts HTTP requests, calls the backend to fetch new greetings, and serves them to the user.

With Skupper, we 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)
  • Two Kubernetes namespaces, from any providers you choose, on any clusters you choose

Step 1: Set up your namespaces

Since we are dealing with two namespaces, we need to set up isolated kubectl configurations, one for each namespace. In this example, we will use distinct kubeconfigs on separate consoles.

Console for namespace us-east:

export KUBECONFIG=$HOME/.kube/config-us-east
kubectl create namespace us-east
kubectl config set-context --current --namespace us-east
skupper init

Console for namespace eu-north:

export KUBECONFIG=$HOME/.kube/config-eu-north
kubectl create namespace eu-north
kubectl config set-context --current --namespace eu-north
skupper init

See Getting started with Skupper for more information about setting up namespaces.

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

$ skupper status
Namespace '<ns>' is ready.  It is connected to 0 other namespaces.

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

Step 2: Deploy the backend and frontend services

Use kubectl create deployment and kubectl expose to deploy the services:

Namespace us-east:

kubectl create deployment hello-world-backend --image
kubectl expose deployment/hello-world-backend --port 8080

Namespace eu-north:

kubectl create deployment hello-world-frontend --image
kubectl expose deployment/hello-world-frontend --port 8080 --type LoadBalancer

At this point, the frontend is exposed externally (from the kubectl expose with --type LoadBalancer), but if you send a request to it, you will see that the frontend has no connectivity to the backend:

Namespace eu-north:

$ curl $(kubectl get service/hello-world-frontend -o jsonpath='http://{.status.loadBalancer.ingress[0].ip}:{.spec.ports[0].port}/')
Trouble! HTTPConnectionPool(host='hello-world-backend', port=8080):
  Max retries exceeded with url: /api/hello
    (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fe411ea7990>:
      Failed to establish a new connection: [Errno -2] Name or service not known'))

The backend service is currently available only inside namespace us-east, so when the frontend service in namespace eu-north attempts to contact it, it fails.

In the next steps, we will establish connectivity between the two namespaces and make the backend available to the frontend in eu-north.

Step 3: Connect your namespaces

To connect namespaces, Skupper requires a token representing permission to form a connection. This token contains a secret (only share it with those you trust) and the logistical details of making a connection.

Use skupper connection-token in us-east to generate the token.

Namespace us-east:

skupper connection-token $HOME/secret.yaml

Use skupper connect in eu-north to use the generated token to form a connection.

Namespace eu-north:

skupper connect $HOME/secret.yaml

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

Step 4: Expose the backend service on the Skupper network

We now have connected namespaces, but there is one more step. To select a service from one namespace for exposure on all the connected namespaces, Skupper uses an annotation the Kubernetes service.

Use kubectl annotate with the annotation to expose the backend service:

Namespace us-east:

kubectl annotate service/hello-world-backend

Once the service is annotated, Skupper creates matching services on all the connected namespaces. Use kubectl get services on eu-north to look for the hello-world-backend service to appear.

Namespace eu-north:

$ kubectl get services
NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)          AGE
hello-world-backend    ClusterIP    <none>           8080/TCP         11h
hello-world-frontend   LoadBalancer   8080:31313/TCP   6m31s

Step 5: Test the application

Now we can send a request to the frontend again to see if it has full connectivity to the backend.

Namespace eu-north:

curl $(kubectl get service/hello-world-frontend -o jsonpath='http://{.status.loadBalancer.ingress[0].ip}:{.spec.ports[0].port}/')

Sample output:

I am the frontend.  The backend says 'Hello 1'.

What just happened?

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 connected namespaces.

The backend service is located in us-east, but the frontend service in eu-north 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:

Namespace us-east:

skupper delete
kubectl delete service/hello-world-backend
kubectl delete deployment/hello-world-backend

Namespace eu-north:

skupper delete
kubectl delete service/hello-world-frontend
kubectl delete deployment/hello-world-frontend

Next steps

You can’t perform that action at this time.