Skupper Declarative 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: 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

Overview

This example is a very simple multi-service HTTP application that can be deployed across multiple Kubernetes clusters using Skupper with a declarative approach.

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

• 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

The skupper command-line tool is the primary 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.

Step 2: Configure separate console sessions

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

Step 3: Access your clusters

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. See the following links for more information:

• Minikube
• Amazon Elastic Kubernetes Service (EKS)
• Azure Kubernetes Service (AKS)
• Google Kubernetes Engine (GKE)
• IBM Kubernetes Service
• OpenShift
• More providers

Step 4: Set up your namespaces

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:

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

Sample output:

$ kubectl create namespace west
namespace/west created

$ kubectl config set-context --current --namespace west
Context "minikube" modified.

Console for east:

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

Sample output:

$ kubectl create namespace east
namespace/east created

$ kubectl config set-context --current --namespace east
Context "minikube" modified.

Step 5: Install Skupper in your namespaces

Deploy a site controller and create a site.

Console for east:

kubectl apply -f https://raw.githubusercontent.com/skupperproject/skupper/master/cmd/site-controller/deploy-watch-current-ns.yaml
kubectl apply -f ./backend/east-site.yml

Console for west:

kubectl apply -f https://raw.githubusercontent.com/skupperproject/skupper/master/cmd/site-controller/deploy-watch-current-ns.yaml
kubectl apply -f ./frontend/west-site.yml

Step 6: Check the status of your namespaces

Use skupper status in each console to check that Skupper is installed.

Console for west:

skupper status

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'

Console for east:

skupper status

Sample output:

$ skupper status
Skupper is enabled for namespace "east" 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.

Step 7: Link your namespaces

Apply yaml to create a token from west and use that token in east.

Console for west:

kubectl apply -f ./frontend/token-request.yml
sleep 1s
kubectl get secret -o yaml west-link | yq 'del(.metadata.namespace)' > ~/west-link.yaml

Console for east:

kubectl apply -f ~/west-link.yaml
skupper link status --wait 60

Step 8: Deploy the frontend and backend services

Use kubectl create deployment to deploy the frontend service in west and the backend service in east.

Console for west:

kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend

Sample output:

$ kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
deployment.apps/frontend created

Console for east:

kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3

Sample output:

$ kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
deployment.apps/backend created

Step 9: Expose the backend service

We now have two namespaces linked to form a Skupper network, but no services are exposed on it. Skupper uses skupper.io annotations to select a service from one namespace for exposure on all the linked namespaces.

Use annotations to expose the backend service to the frontend service.

Console for east:

kubectl annotate deployment/backend skupper.io/proxy="http"
kubectl annotate deployment/backend skupper.io/port="8080"

Step 10: Expose the frontend service

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 kubectl expose with --type LoadBalancer to open network access to the frontend service.

Console for west:

kubectl expose deployment/frontend --port 8080 --type LoadBalancer

Sample output:

$ kubectl expose deployment/frontend --port 8080 --type LoadBalancer
service/frontend exposed

Step 11: Test the application

Now we're ready to try it out. Use kubectl get service/frontend to look up the external IP of the frontend service. Then use curl or a similar tool to request the /api/health endpoint at that address.

Note: The <external-ip> field in the following commands is a placeholder. The actual value is an IP address.

Console for west:

kubectl get service/frontend
curl http://<external-ip>:8080/api/health

Sample output:

$ kubectl get service/frontend
NAME       TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
frontend   LoadBalancer   10.103.232.28   <external-ip>   8080:30407/TCP   15s

$ curl http://<external-ip>:8080/api/health
OK

If everything is in order, you can now access the web interface by navigating to http://<external-ip>:8080/ in your browser.

Accessing the web console

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

Console for west:

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

Console for east:

skupper delete
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 some utilities 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.