Skupper Hello World using the gateway

Connect services running as system processes

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.

Contents

• Overview
• Prerequisites
• Step 1: Install the Skupper command-line tool
• Step 2: Set up your Kubernetes namespace
• Step 3: Create your Kubernetes site
• Step 4: Set up the Skupper gateway
• Step 5: Deploy the frontend and backend
• Step 6: Expose the backend
• Step 7: Access the frontend
• Cleaning up
• Summary
• Next steps
• About this example

Overview

This example is a basic multi-service HTTP application deployed across a Kubernetes cluster and a bare-metal host or VM.

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> (<hostname>).

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

The frontend runs on Kubernetes and the backend runs on your local machine. Skupper enables the frontend to connect to the backend using a dedicated service network.

Prerequisites

• A working installation of Docker (installation guide) or Podman (installation guide)

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

• Access to a Kubernetes cluster, from any provider you choose

• The starlette and uvicorn Python modules. This is required to run the backend service locally. To install the modules, run pip install starlette uvicorn.

Step 1: Install the Skupper command-line tool

This example uses the Skupper command-line tool to deploy Skupper. You need to install the skupper command only once for each development environment.

On Linux or Mac, you can use the install script (inspect it here) to download and extract the command:

curl https://skupper.io/install.sh | sh

The script installs the command under your home directory. It prompts you to add the command to your path if necessary.

For Windows and other installation options, see Installing Skupper.

Step 2: Set up your Kubernetes namespace

Open a new terminal window and log in to your cluster. Then create the namespace you wish to use and set the namespace on your current context.

Note: The login procedure varies by provider. See the documentation for your chosen providers:

• Minikube
• Amazon Elastic Kubernetes Service (EKS)
• Azure Kubernetes Service (AKS)
• Google Kubernetes Engine (GKE)
• IBM Kubernetes Service
• OpenShift

Kubernetes:

# Enter your provider-specific login command
kubectl create namespace hello-world
kubectl config set-context --current --namespace hello-world

Step 3: Create your Kubernetes site

A Skupper site is a location where components of your application are running. Sites are linked together to form a Skupper network for your application.

In Kubernetes, use skupper init to create a site. This deploys the Skupper router and controller. Then use skupper status to see the outcome.

Note: If you are using Minikube, you need to start minikube tunnel before you run skupper init.

Kubernetes:

skupper init

Sample output:

$ skupper init
Waiting for LoadBalancer IP or hostname...
Waiting for status...
Skupper is now installed in namespace 'hello-world'.  Use 'skupper status' to get more information.

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

Step 4: Set up the Skupper gateway

The skupper gateway init command starts a Skupper router on your local system and links it to the Skupper router in the current Kubernetes namespace.

Kubernetes:

skupper gateway init --type docker

Sample output:

$ skupper gateway init --type docker
Skupper gateway: 'fancypants-jross'. Use 'skupper gateway status' to get more information.

The --type docker option runs the router as a Docker container. You can also run it as a Podman container (--type podman) or as a systemd service (--type service).

Step 5: Deploy the frontend and backend

For this example, we are running the frontend on Kubernetes and the backend as a local system process.

Use kubectl create deployment to deploy the frontend service in your Kubernetes namespace.

Change to the backend directory and use python python/main.py to start the backend process. You can run this in a different terminal if you prefer.

Kubernetes:

kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
(cd backend && python python/main.py --host localhost --port 8081) &

Sample output:

$ kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
deployment.apps/frontend created

$ (cd backend && python python/main.py --host localhost --port 8081) &
INFO:     Started server process [208334]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8081 (Press CTRL+C to quit)

Step 6: Expose the backend

Use skupper service create to define a Skupper service called backend. Then use skupper gateway bind to attach your running backend process as a target for the service.

Kubernetes:

skupper service create backend 8080
skupper gateway bind backend localhost 8081

Sample output:

$ skupper gateway bind backend localhost 8081
2022/09/08 07:07:00 CREATE io.skupper.router.tcpConnector fancypants-jross-egress-backend:8080 map[address:backend:8080 host:localhost name:fancypants-jross-egress-backend:8080 port:8081 siteId:d187db66-cbda-43fe-ac3b-4be22bbad1c9]

Step 7: Access the frontend

In order to use and test the application, we need external access to the frontend.

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

Once the frontend is exposed, use kubectl get service/frontend to look up the external IP of the frontend service. If the external IP is <pending>, try again after a moment.

Once you have the external IP, 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. The actual value is an IP address.

Kubernetes:

kubectl expose deployment/frontend --port 8080 --type LoadBalancer
kubectl get service/frontend
curl http://<external-ip>:8080/api/health

Sample output:

$ kubectl expose deployment/frontend --port 8080 --type LoadBalancer
service/frontend exposed

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

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

If everything is in order, you can now access the web interface by navigating to http://<external-ip>:8080/ in your browser.

Cleaning up

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

Kubernetes:

kill $(ps -ef | grep 'python python/main\.py' | awk '{print $2}') 2> /dev/null
skupper gateway delete
skupper delete
kubectl delete service/frontend
kubectl delete deployment/frontend

Next steps

Check out the other examples on the Skupper website.

About this example

This example was produced using Skewer, a library for documenting and testing Skupper examples.

Skewer provides utility functions for generating the README and running the example steps. Use the ./plano command in the project root to see what is available.

To quickly stand up the example using Minikube, try the ./plano demo command.