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: Set up your clusters
- Step 3: Deploy the frontend and backend
- Step 4: Create your sites
- Step 5: Link your sites
- Step 6: Expose the backend
- Step 7: Access the frontend
- Cleaning up
- Summary
- Next steps
- About this example
This example is a very simple multi-service HTTP application deployed across Kubernetes clusters using Skupper.
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> (<pod-name>)
. -
A frontend service that sends greetings to the backend and fetches new greetings in response.
With Skupper, you can place the backend in one cluster and the frontend in another and maintain connectivity between the two services without exposing the backend to the public internet.
-
The
kubectl
command-line tool, version 1.15 or later (installation guide) -
Access to at least one Kubernetes cluster, from any provider you choose
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.
Skupper is designed for use with multiple Kubernetes clusters.
The skupper
and kubectl
commands use your
kubeconfig and current context to select the cluster
and namespace where they operate.
Your kubeconfig is stored in a file in your home directory. The
skupper
and kubectl
commands use the KUBECONFIG
environment
variable to locate it.
A single kubeconfig supports only one active context per user. Since you will be using multiple contexts at once in this exercise, you need to create distinct kubeconfigs.
For each namespace, open a new terminal window. In each terminal,
set the KUBECONFIG
environment variable to a different path 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 yours:
- Minikube
- Amazon Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- Google Kubernetes Engine (GKE)
- IBM Kubernetes Service
- OpenShift
West:
export KUBECONFIG=~/.kube/config-west
# Enter your provider-specific login command
kubectl create namespace west
kubectl config set-context --current --namespace west
East:
export KUBECONFIG=~/.kube/config-east
# Enter your provider-specific login command
kubectl create namespace east
kubectl config set-context --current --namespace east
This example runs the frontend and the backend in separate Kubernetes namespaces, on different clusters.
Use kubectl create deployment
to deploy the frontend in West
and the backend in East.
West:
kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
East:
kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
A Skupper site is a location where components of your application are running. Sites are linked together to form a network for your application. In Kubernetes, a site is associated with a namespace.
For each namespace, 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
.
West:
skupper init
skupper status
Sample output:
$ skupper init
Waiting for LoadBalancer IP or hostname...
Waiting for status...
Skupper is now installed in namespace 'west'. Use 'skupper status' to get more information.
$ skupper status
Skupper is enabled for namespace "west". It is not connected to any other sites. It has no exposed services.
East:
skupper init
skupper status
Sample output:
$ skupper init
Waiting for LoadBalancer IP or hostname...
Waiting for status...
Skupper is now installed in namespace 'east'. Use 'skupper status' to get more information.
$ skupper status
Skupper is enabled for namespace "east". It is not connected to any other sites. It has no exposed services.
As you move through the steps below, you can use skupper status
at
any time to check your progress.
A Skupper link is a channel for communication between two sites. Links serve as a transport for application connections and requests.
Creating a link requires use of two skupper
commands in
conjunction, skupper token create
and skupper link create
.
The skupper token create
command generates a secret token that
signifies permission to create a link. The token also carries the
link details. Then, in a remote site, The skupper link create
command uses the token to create a link to the site
that generated it.
Note: The link token is truly a secret. Anyone who has the token can link to your site. Make sure that only those you trust have access to it.
First, use skupper token create
in West to generate the
token. Then, use skupper link create
in East to link the
sites.
West:
skupper token create ~/secret.token
Sample output:
$ skupper token create ~/secret.token
Token written to ~/secret.token
East:
skupper link create ~/secret.token
Sample output:
$ skupper link create ~/secret.token
Site configured to link to https://10.105.193.154:8081/ed9c37f6-d78a-11ec-a8c7-04421a4c5042 (name=link1)
Check the status of the link using 'skupper link status'.
If your terminal sessions are on different machines, you may need
to use scp
or a similar tool to transfer the token securely. By
default, tokens expire after a single use or 15 minutes after
creation.
We now have our sites linked to form a Skupper network, but no
services are exposed on it. Skupper uses the skupper expose
command to select a service from one site for exposure in all the
linked sites.
Use skupper expose
to expose the backend service in East to
the frontend in West.
East:
skupper expose deployment/backend --port 8080
Sample output:
$ skupper expose deployment/backend --port 8080
deployment backend exposed as backend
In order to use and test the application, we need external access to the frontend.
Use kubectl port-forward
to make the frontend available at
localhost:8080
.
West:
kubectl port-forward deployment/frontend 8080:8080
You can now access the web interface by navigating to http://localhost:8080 in your browser.
To remove Skupper and the other resources from this exercise, use the following commands:
West:
skupper delete
kubectl delete service/frontend
kubectl delete deployment/frontend
East:
skupper delete
kubectl delete deployment/backend
This example locates the frontend and backend services in different namespaces, on different clusters. Ordinarily, this means that they have no way to communicate unless they are exposed to the public internet.
Introducing Skupper into each namespace allows us to create a virtual application network that can connect services in different clusters. Any service exposed on the application network is represented as a local service in all of the linked namespaces.
The backend service is located in east
, but the frontend service
in west
can "see" it as if it were local. When the frontend
sends a request to the backend, Skupper forwards the request to the
namespace where the backend is running and routes the response back to
the 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.