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 Skupper in your clusters
• Step 2: Set up your namespaces
• Step 3: Apply your YAML resources
• Step 4: Link your sites
• Step 5: Access the frontend
• Cleaning up
• Summary
• Next steps
• About this example

This example is a variant of Skupper Hello World that is deployed using YAML resource definitions instead of imperative commands.

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.

In this scenario, each service runs in a different Kubernetes cluster. The frontend runs in a namespace on cluster 1 called West, and the backend runs in a namespace on cluster 2 called East.

Skupper enables you to 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

Use the kubectl apply command to install the Skupper controller in each cluster.

West:

kubectl apply -f skupper.yaml

Sample output:

$ kubectl apply -f skupper.yaml
namespace/skupper-site-controller created
serviceaccount/skupper-site-controller created
clusterrole.rbac.authorization.k8s.io/skupper-site-controller created
clusterrolebinding.rbac.authorization.k8s.io/skupper-site-controller created
deployment.apps/skupper-site-controller created

East:

kubectl apply -f skupper.yaml

Sample output:

$ kubectl apply -f skupper.yaml
namespace/skupper-site-controller created
serviceaccount/skupper-site-controller created
clusterrole.rbac.authorization.k8s.io/skupper-site-controller created
clusterrolebinding.rbac.authorization.k8s.io/skupper-site-controller created
deployment.apps/skupper-site-controller created

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

To configure our example sites and service bindings, we are using the following resources:

West:

• site.yaml - Skupper configuration for West
• frontend.yaml - The Hello World frontend

East:

• site.yaml - Skupper configuration for East
• backend.yaml - The Hello World backend

Let's look at some of these resources in more detail.

The site ConfigMap defines a Skupper site for its associated Kubernetes namespace. This is where you set site configuration options. See the config reference for more information.

site.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: skupper-site
data:
  name: west

Like the one for West, here is the Skupper site definition for the East. It includes the ingress: none setting since no ingress is required at this site for the Hello World example.

site.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: skupper-site
data:
  name: east
  ingress: none

In East, the backend deployment has an annotation named skupper.io/proxy with the value tcp. This tells Skupper to expose the backend on the Skupper network. As a consequence, the frontend in West will be able to see the backend and call its API.

backend.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  labels:
    app: backend
  annotations:
    skupper.io/proxy: tcp
spec:
  selector:
    matchLabels:
      app: backend
  replicas: 3
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: quay.io/skupper/hello-world-backend
          ports:
            - containerPort: 8080

Now we're ready to apply everything. Use the kubectl apply command with the resource definitions for each site.

Note: If you are using Minikube, you need to start minikube tunnel before you create the Skupper sites.

West:

kubectl apply -f west/site.yaml -f west/frontend.yaml

Sample output:

$ kubectl apply -f west/site.yaml -f west/frontend.yaml
configmap/skupper-site created
deployment.apps/frontend created

East:

kubectl apply -f east/site.yaml -f east/backend.yaml

Sample output:

$ kubectl apply -f east/site.yaml -f east/backend.yaml
configmap/skupper-site created
deployment.apps/backend created

You can configure sites and service bindings declaratively, but linking sites is different. To create a link, you must have the authentication secret and connection details of the remote site. Since these cannot be known in advance, linking must be procedural.

This example uses the Skupper command-line tool to generate the secret token in West and create the link in East.

To install the Skupper command:

curl https://skupper.io/install.sh | sh

For more installation options, see Installing Skupper.

Once the command is installed, use skupper token create in West to generate the token. Then, use skupper link create in East to create a link.

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.

In order to use and test the application, we need external access to the frontend.

Use kubectl expose with --type LoadBalancer to open network access to the frontend service.

Once the frontend is exposed, use kubectl get service/frontend to look up the external IP of the frontend service. If the external IP is <pending>, try again after a moment.

Once you have the external IP, 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.

West:

kubectl expose deployment/frontend --port 8080 --type LoadBalancer
kubectl get service/frontend
curl http://<external-ip>:8080/api/health

Sample output:

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

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

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

West:

kubectl delete -f west/site.yaml -f west/frontend.yaml
kubectl delete -f skupper.yaml

East:

kubectl delete -f east/site.yaml -f east/backend.yaml
kubectl delete -f skupper.yaml

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.