Skupper Hello World using Docker or Podman

Connect services running as Docker or Podman containers

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: Expose the frontend service
• Step 9: 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 running Docker or Podman containers.

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

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

With Skupper, you can run the backend as a container on your local machine and the frontend in Kubernetes and maintain connectivity between the two services without exposing the backend to the public internet.

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

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 frontend on Kubernetes and the backend as a local Docker or Podman container.

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

Use docker run or podman run to run the backend service on your local machine.

Console for hello-world:

kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
docker run --name backend --detach --rm -p 8080:8080 quay.io/skupper/hello-world-backend

Sample output:

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

$ docker run --name backend --detach --rm -p 8080:8080 quay.io/skupper/hello-world-backend
262dde0287af2c76c3088d9ff4f865f02732a762b0afd91e03ec9e3fe6b03f88

Step 7: Expose the backend service

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.

Console for hello-world:

skupper service create backend 8080
skupper gateway bind backend localhost 8080

Sample output:

$ skupper service create backend 8080


$ skupper gateway bind backend localhost 8080
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:8080 siteId:d187db66-cbda-43fe-ac3b-4be22bbad1c9]

Step 8: Expose the frontend service

We have established connectivity between the Kubernetes namespace and the your local machine, and we've made the backend in hello-world available to the frontend running as container. 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 hello-world:

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

Sample output:

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

Step 9: 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. The actual value is an IP address.

Console for hello-world:

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

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:

docker stop backend
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.