Skupper Hello World

A minimal HTTP application deployed across Kubernetes clusters using Skupper

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: Access your Kubernetes clusters
• Step 2: Create your Kubernetes namespaces
• Step 3: Deploy the frontend and backend
• Step 4: Install Skupper on your Kubernetes clusters
• Step 5: Install the Skupper command-line tool
• Step 6: Create your sites
• Step 7: Link your sites
• Step 8: Expose the backend service
• Step 9: Access the frontend service
• Cleaning up
• Summary
• Next steps
• About this example

Overview

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 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.

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.

Prerequisites

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

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

Step 1: Access your Kubernetes clusters

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.

This example uses multiple cluster contexts at once. The KUBECONFIG environment variable tells skupper and kubectl which kubeconfig to use.

For each cluster, open a new terminal window. In each terminal, set the KUBECONFIG environment variable to a different path and log in to your cluster.

West:

export KUBECONFIG=~/.kube/config-west
<provider-specific login command>

East:

export KUBECONFIG=~/.kube/config-east
<provider-specific login command>

Note: The login procedure varies by provider.

Step 2: Create your Kubernetes namespaces

The example application has different components deployed to different Kubernetes namespaces. To set up our example, we need to create the namespaces.

For each cluster, use kubectl create namespace and kubectl config set-context to create the namespace you wish to use and set the namespace on your current context.

West:

kubectl create namespace west
kubectl config set-context --current --namespace west

East:

kubectl create namespace east
kubectl config set-context --current --namespace east

Step 3: Deploy the frontend and backend

Deploy the Hello World components, placing the frontend on one cluster and the backend on the other.

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

Step 4: Install Skupper on your Kubernetes clusters

Using Skupper on Kubernetes requires the installation of the Skupper custom resource definitions (CRDs) and the Skupper controller.

For each cluster, use kubectl apply with the Skupper installation YAML to install the CRDs and controller.

West:

kubectl apply -f https://skupper.io/v2/install.yaml

East:

kubectl apply -f https://skupper.io/v2/install.yaml

Step 5: Install the Skupper command-line tool

This example uses the Skupper command-line tool to create Skupper resources. 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/v2/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 6: Create your sites

A Skupper site is a location where your application workloads are running. Sites are linked together to form a network for your application.

For each namespace, use skupper site create with a site name of your choice. This creates the site resource and deploys the Skupper router to the namespace.

Note: If you are using Minikube, you need to start minikube tunnel before you run skupper site create.

West:

skupper site create west --enable-link-access

Sample output:

$ skupper site create west --enable-link-access
Waiting for status...
Site "west" is configured. Check the status to see when it is ready

East:

skupper site create east

Sample output:

$ skupper site create east
Waiting for status...
Site "east" is configured. Check the status to see when it is ready

You can use skupper site status at any time to check the status of your site.

Step 7: Link your sites

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 the use of two Skupper commands in conjunction: skupper token issue and skupper token redeem. The skupper token issue command generates a secret token that can be transferred to a remote site and redeemed for a link to the issuing site. The skupper token redeem command uses the token to create the link.

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 issue in West to generate the token. Then, use skupper token redeem in East to link the sites.

West:

skupper token issue ~/secret.token

Sample output:

$ skupper token issue ~/secret.token
Waiting for token status ...

Grant "west-cad4f72d-2917-49b9-ab66-cdaca4d6cf9c" is ready
Token file /run/user/1000/skewer/secret.token created

Transfer this file to a remote site. At the remote site,
create a link to this site using the "skupper token redeem" command:

	skupper token redeem <file>

The token expires after 1 use(s) or after 15m0s.

East:

skupper token redeem ~/secret.token

Sample output:

$ skupper token redeem ~/secret.token
Waiting for token status ...
Token "west-cad4f72d-2917-49b9-ab66-cdaca4d6cf9c" has been redeemed
You can now safely delete /run/user/1000/skewer/secret.token

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 being issued.

Step 8: Expose the backend service

We now have our sites linked to form a Skupper network, but no services are exposed on it.

Skupper uses listeners and connectors to expose services across sites inside a Skupper network. A listener is a local endpoint for client connections, configured with a routing key. A connector exists in a remote site and binds a routing key to a particular set of servers. Skupper routers forward client connections from local listeners to remote connectors with matching routing keys.

In West, use the skupper listener create command to create a listener for the backend. In East, use the skupper connector create command to create a matching connector.

West:

skupper listener create backend 8080

Sample output:

$ skupper listener create backend 8080
Waiting for create to complete...
Listener "backend" is ready

East:

skupper connector create backend 8080

Sample output:

$ skupper connector create backend 8080
Waiting for create to complete...
Connector "backend" is ready

The commands shown above use the name argument, backend, to also set the default routing key and pod selector. You can use the --routing-key and --selector options to set specific values.

Step 9: Access the frontend service

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.

Cleaning up

To remove Skupper and the other resources from this exercise, use the following commands:

West:

skupper site delete --all
kubectl delete deployment/frontend

East:

skupper site delete --all
kubectl delete deployment/backend

Summary

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.

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.