Skupper Hello World using the console

Explore an application network using the Skupper web console

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: Set up your namespaces
• 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 web console
• Cleaning up
• Summary
• Next steps
• About this example

Overview

The Skupper web console provides a graphical view of a Skupper network. This example shows you how to set it up. It uses the Skupper Hello World as an example application.

The Hello World application contains two components:

• A backend service that exposes an /api/hello endpoint. It returns greetings of the form Hi, <your-name>. I am <my-name> (<pod-name>).

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

These two components run on two distinct Kubernetes clusters (two sites). With the Skupper console, you can observe the two sites and the two components and see the metrics for their communication.

Prerequisites

• The kubectl command-line tool, version 1.15 or later (installation guide)

• Access to at least one Kubernetes cluster, from any provider you choose

Step 1: Install the Skupper command-line tool

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.

Step 2: Set up your namespaces

Skupper is designed for use with multiple Kubernetes namespaces, usually on different clusters. The skupper and kubectl commands use your kubeconfig and current context to select the 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

Step 3: Deploy the frontend and backend

This example runs the frontend and the backend in separate Kubernetes namespaces, on different clusters.

Use kubectl create deployment to deploy the frontend in namespace west and the backend in namespace 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

Step 4: Create your sites

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.

In West, use skupper init with the --enable-console and --enable-flow-collector options. These options make the console available from West.

In East, use skupper init again, this time without the extra options.

After each skupper init operation, run 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 --enable-console --enable-flow-collector
skupper status

Sample output:

$ skupper init --enable-console --enable-flow-collector
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.

Step 5: Link your sites

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 site West to generate the token. Then, use skupper link create in site 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.

Step 6: Expose the backend

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

Step 7: Access the web console

Now we're ready to try the console. To access it, use skupper status to look up the URL of the 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.

West:

skupper status
kubectl get secret/skupper-console-users -o jsonpath={.data.admin} | base64 -d

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'

$ 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:

West:

skupper delete
kubectl delete service/frontend
kubectl delete deployment/frontend

East:

skupper delete
kubectl delete deployment/backend

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.