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: Access your Kubernetes cluster
• Step 3: Set up your Kubernetes namespace
• Step 4: Install Skupper in your Kubernetes namespace
• Step 5: Install the Skupper gateway
• Step 6: Deploy the frontend and backend services
• Step 7: Expose the backend service
• Step 8: Test the application
• Accessing the web console
• Cleaning up
• 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 backend runs on Kubernetes and the frontend 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 httpx, starlette, sse_starlette, and uvicorn Python modules. This is required to run the frontend service locally. To install the modules, run pip install httpx starlette sse_starlette uvicorn.

Step 1: Install the Skupper command-line tool

The skupper command-line tool is the entrypoint for installing and configuring 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: Access your Kubernetes cluster

The procedure for accessing a Kubernetes cluster varies by provider. Find the instructions for your chosen provider and use them to authenticate and configure access.

Step 3: Set up your Kubernetes namespace

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

Console for hello-world:

kubectl create namespace hello-world
kubectl config set-context --current --namespace hello-world

Sample output:

$ kubectl create namespace hello-world
namespace/hello-world created

$ kubectl config set-context --current --namespace hello-world
Context "minikube" modified.

Step 4: Install Skupper in your Kubernetes namespace

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

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

Console for hello-world:

skupper init

Sample output:

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

Step 5: Install 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.

Console for hello-world:

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 6: Deploy the frontend and backend services

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

Use kubectl create deployment to deploy the backend service in hello-world.

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

Console for hello-world:

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

Sample output:

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

Step 7: Expose the backend service

Use skupper service create to define a Skupper service called backend. Use skupper servce bind to associate it with your backend deployment. Use skupper gateway forward to link local requests to port 8081 to the new service.

Console for hello-world:

skupper service create backend 8080
skupper service bind backend deployment/backend
skupper gateway forward backend 8081

Step 8: Test the application

Now we're ready to try it out. Use curl or a similar tool to request the http://localhost:8080/api/health endpoint.

Console for hello-world:

curl http://localhost:8080/api/health

Sample output:

$ curl http://localhost:8080/api/health
OK

If everything is in order, you can now access the web interface by navigating to http://localhost:8080/ in your browser.

Accessing the web console

Skupper includes a web console you can use to view the application network. To access it, use skupper status to look up the URL of the web console. Then use kubectl get secret/skupper-console-users to look up the console admin password.

Note: The <console-url> and <password> fields in the following output are placeholders. The actual values are specific to your environment.

Console for hello-world:

skupper status
kubectl get secret/skupper-console-users -o jsonpath={.data.admin} | base64 -d

Sample output:

$ skupper status
Skupper is enabled for namespace "hello-world" in interior mode. It is connected to 1 other site. It has 1 exposed service.
The site console url is: <console-url>
The credentials for internal console-auth mode are held in secret: 'skupper-console-users'

$ kubectl get secret/skupper-console-users -o jsonpath={.data.admin} | base64 -d
<password>

Navigate to <console-url> in your browser. When prompted, log in as user admin and enter the password.

Cleaning up

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

Console for hello-world:

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.