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: Expose the frontend service
- Step 9: 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 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.
-
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
anduvicorn
Python modules. This is required to run the backend service locally. To install the modules, runpip install 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 frontend on Kubernetes and the backend as a local system process.
Use kubectl create deployment
to deploy the frontend service
in hello-world
.
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.
Console for hello-world:
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)
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 8081
Sample output:
$ skupper service create backend 8080
$ 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]
Our frontend is running on Kubernetes. Use skupper service create
and skupper service bind
to define a Skupper service
and attach the frontend deployment to it.
We want to be able to connect locally as a client to the Skupper
frontend service. Use skupper gateway forward
to map local
port 8080 to the frontend service.
Console for hello-world:
skupper service create frontend 8080
skupper service bind frontend deployment/frontend
skupper gateway forward frontend 8080
Sample output:
$ skupper service create frontend 8080
$ skupper service bind frontend deployment/frontend
$ skupper gateway forward frontend 8080
2022/09/08 07:07:07 CREATE io.skupper.router.tcpListener fancypants-jross-ingress-frontend:8080 map[address:frontend:8080 name:fancypants-jross-ingress-frontend:8080 port:8080 siteId:d187db66-cbda-43fe-ac3b-4be22bbad1c9]
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.