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: Configure separate console sessions
- Step 3: Access your clusters
- Step 4: Set up your namespaces
- Step 5: Install Skupper in your namespaces
- Step 6: Check the status of your namespaces
- Step 7: Link your namespaces
- Step 8: Deploy the frontend and backend services
- Step 9: Expose the backend service
- Step 10: Expose the frontend service
- Step 11: Test the application
- Accessing the web console
- Cleaning up
- Summary
- 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
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.
Skupper is designed for use with multiple namespaces, usually on
different clusters. The skupper
command uses your
kubeconfig and current context to select the
namespace where it operates.
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.
Start a console session for each of your namespaces. Set the
KUBECONFIG
environment variable to a different path in each
session.
Console for west:
export KUBECONFIG=~/.kube/config-west
Console for east:
export KUBECONFIG=~/.kube/config-east
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 for each console session.
Use kubectl create namespace
to create the namespaces you wish
to use (or use existing namespaces). Use kubectl config set-context
to set the current namespace for each session.
Console for west:
oc create namespace west
oc config set-context --current --namespace west
Console for east:
oc create namespace east
oc config set-context --current --namespace east
The skupper init
command installs the Skupper router and service
controller in the current namespace. Run the skupper init
command
in each namespace.
Note: If you are using Minikube, you need to start minikube tunnel
before you install Skupper.
Console for west:
skupper init --enable-console --enable-flow-collector
Console for east:
skupper init
Sample output:
$ skupper init
Waiting for LoadBalancer IP or hostname...
Skupper is now installed in namespace '<namespace>'. Use 'skupper status' to get more information.
Use skupper status
in each console to check that Skupper is
installed.
Console for west:
skupper status
Console for east:
skupper status
Sample output:
Skupper is enabled for namespace "<namespace>" 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'
As you move through the steps below, you can use skupper status
at
any time to check your progress.
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 namespace, The skupper link create
command uses the token to create a link to the namespace
that generated it.
Note: The link token is truly a secret. Anyone who has the token can link to your namespace. Make sure that only those you trust have access to it.
First, use skupper token create
in one namespace to generate the
token. Then, use skupper link create
in the other to create a
link.
Console for west:
skupper token create ~/secret.token
Sample output:
$ skupper token create ~/secret.token
Token written to ~/secret.token
Console for 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 console sessions are on different machines, you may need
to use sftp
or a similar tool to transfer the token securely.
By default, tokens expire after a single use or 15 minutes after
creation.
Use oc new-app
to create the frontend service in west
.
Console for west:
oc new-app --name frontend --image quay.io/skupper/hello-world-frontend
Sample output:
$ oc new-app --name frontend --image quay.io/skupper/hello-world-frontend ─╯
--> Found container image ca3ab60 (4 months old) from quay.io for "quay.io/skupper/hello-world-frontend"
* An image stream tag will be created as "frontend:latest" that will track this image
--> Creating resources ...
imagestream.image.openshift.io "frontend" created
deployment.apps "frontend" created
service "frontend" created
--> Success
Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
'oc expose service/frontend'
Run 'oc status' to view your app.
Use oc new-app
to create the backend service in east
Console for east:
oc new-app --name backend --image quay.io/skupper/hello-world-backend ─╯
Sample output:
$ oc new-app --name backend --image quay.io/skupper/hello-world-backend ─╯
--> Found container image 2c3292a (4 months old) from quay.io for "quay.io/skupper/hello-world-backend"
* An image stream tag will be created as "backend:latest" that will track this image
--> Creating resources ...
imagestream.image.openshift.io "backend" created
deployment.apps "backend" created
service "backend" created
--> Success
Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
'oc expose service/backend'
Run 'oc status' to view your app.
oc scale deployment/backend --replicas 3 ─╯
Sample output:
$ oc scale deployment/backend --replicas 3 ─╯
deployment.apps/backend scaled
We now have two namespaces 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 namespace for
exposure on all the linked namespaces.
Note: You can expose services that are not in the same namespace where you installed Skupper as described in the Exposing services from a different namespace documentation.
Use skupper expose
to expose the backend service to the
frontend service.
Console for east:
skupper expose deployment/backend --port 8080
Sample output:
$ skupper expose deployment/backend --port 8080
deployment backend exposed as backend
We have established connectivity between the two namespaces and
made the backend in east
available to the frontend in west
.
Before we can test the application, we need external access to
the frontend.
Use oc expose service frontend
to open network access to the frontend service.
Console for west:
oc expose service frontend
Sample output:
$ oc expose service frontend ─╯
route.route.openshift.io/frontend exposed
Now we're ready to try it out. Use oc get route frontend --output jsonpath={.spec.host}
to look up the hostname for the frontend service. Then use
curl
or a similar tool to request the /api/health
endpoint at
that address.
Console for west:
oc get route frontend --output jsonpath={.spec.host}
curl <front_end_route>/api/health
Sample output:
$ oc get route frontend --output jsonpath={.spec.host} ─╯
<front_end_route>
$ curl http://<front_end_route/api/health
OK
If everything is in order, you can now access the web interface by
navigating to http://<front_end_route>/
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 west:
skupper status
oc get secret skupper-console-users --template={{.data.admin}} | base64 --decode
Sample output:
$ skupper status
Skupper is enabled for namespace "west" 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'
$ oc get secret skupper-console-users --template={{.data.admin}} | base64 --decode
<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 west:
skupper delete
oc delete project west
Console for east:
skupper delete
oc delete project east
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.