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.
- 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
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 formHi, <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.
-
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
, anduvicorn
Python modules. This is required to run the frontend service locally. To install the modules, runpip install httpx starlette sse_starlette uvicorn
.
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.
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.
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.
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.
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
).
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
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
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.
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.
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
Check out the other examples on the Skupper website.
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.