Skupper Hello World using Ansible

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 Ansible collection
• Step 2: Access your Kubernetes clusters
• Step 3: Install Skupper on your Kubernetes clusters
• Step 4: Set up your clusters
• Step 5: Inspect the inventory file
• Step 6: Run the setup playbook
• Step 7: Access the frontend service
• Step 8: Run the teardown playbook
• Next steps
• About this example

Overview

This example is a variant of Skupper Hello World that is deployed using the Skupper Ansible collection.

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 Skupper Ansible collection is used in this example to connect two sites running on Kubernetes, but the collection can also be used to manage the lifecycle of sites running on Podman, Docker or Linux.

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

• The skupper command-line tool, version 2.0 or later. 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 -s -- --version 2.0.0-preview-2

  See Installing the Skupper CLI for more information.

• Ansible, version 2.15 or later (installation guide)

Step 1: Install the Skupper Ansible collection

Use the ansible-galaxy command to install the skupper.v2 collection.

Terminal:

ansible-galaxy collection install skupper.v2

Step 2: 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.

Terminal:

export KUBECONFIG=$PWD/ansible/kubeconfigs/west
<provider-specific login command>

East:

export KUBECONFIG=$PWD/ansible/kubeconfigs/east
<provider-specific login command>

Note: The login procedure varies by provider.

Step 3: 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.

Terminal:

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

East:

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

Step 4: Set up your clusters

This example uses two clusters. The clusters are accessed using two kubeconfig files:

<project-dir>/ansible/kubeconfigs/east
<project-dir>/ansible/kubeconfigs/west

For each kubeconfig, set the KUBECONFIG environment variable to the file path and run the login command for your cluster. This updates the kubeconfig with the required credentials.

Note: The cluster 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

Terminal:

cd <project-dir>
export KUBECONFIG=$PWD/ansible/kubeconfigs/west
# Enter your provider-specific login command for cluster 1
export KUBECONFIG=$PWD/ansible/kubeconfigs/east
# Enter your provider-specific login command for cluster 2

Step 5: Inspect the inventory file

Before we start running commands, let's examine the inventory file. Although it is not mandatory to have an inventory file, you can have the kubeconfig file, the namespace and the path to the resources defined per inventory host.

ansible/inventory.yml:

all:
  vars:
    ansible_connection: local
  hosts:
    west:
      kubeconfig: "{{ inventory_dir }}/kubeconfigs/west"
      namespace: west
      resources_path: "{{ playbook_dir }}/kubernetes/west.yaml"
    east:
      kubeconfig: "{{ inventory_dir }}/kubeconfigs/east"
      namespace: east
      resources_path: "{{ playbook_dir }}/kubernetes/east.yaml"

The playbooks that follow use this inventory data to set up and tear down the Skupper network.

For more information about inventory files, see the Ansible inventory guide.

Step 6: Run the setup playbook

Now let's look at the setup playbook.

ansible/setup.yml:

- hosts: all
  connection: local
  tasks:
    - name: Apply site resources
      skupper.v2.resource:
        path: "{{ resources_path }}"
        kubeconfig: "{{ kubeconfig }}"
        namespace: "{{ namespace }}"

- hosts: west
  connection: local
  tasks:
    - name: Create a token to the west site
      skupper.v2.token:
        name: "west"
        kubeconfig: "{{ kubeconfig }}"
        namespace: "{{ namespace }}"
      register: accesstoken

- hosts: east
  connection: local
  tasks:
    - name: Link east site to west
      skupper.v2.resource:
        def: "{{ hostvars['west']['accesstoken']['token'] }}"
        kubeconfig: "{{ kubeconfig }}"
        namespace: "{{ namespace }}"

The first task applies all needed resources on both west and east namespaces. Those resources contain the whole example definition, including: the workloads (backend and frontend apps) along with all the Skupper V2 resources needed. We apply those resources using the skupper.v2.resource module, see the Resource module documentation.

The second task is performed against the west inventory host only and it generates an AccessGrant named west, returning its respective AccessToken, which is registered to the host variable accesstoken. This task uses the skupper.v2.token module for that, see the Token module documentation.

The last task is to link the east site to the west, using the skupper.v2.resource module again, and applying the AccessToken registered into the west host variables as accesstoken.token.

Use the ansible-playbook command to run the playbook:

Terminal:

ansible-playbook -i ansible/inventory.yml ansible/setup.yml

Sample output:

$ ansible-playbook -i ansible/inventory.yml ansible/setup.yml
[...]
PLAY RECAP *********************************************************************************************
east             : ok=4    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
west             : ok=4    changed=2    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Note: The collection also requires some Python modules to be present on the target node, in case you have problems, you will need to install the collection requirements, in example:

pip install -r https://raw.githubusercontent.com/skupperproject/skupper-ansible/refs/heads/main/requirements.txt

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

Terminal:

export KUBECONFIG=$PWD/ansible/kubeconfigs/west
kubectl -n west port-forward deployment/frontend 8080:8080

You can now access the web interface by navigating to http://localhost:8080 in your browser.

Step 8: Run the teardown playbook

To clean everything up, run the teardown playbook.

ansible/teardown.yml:

- hosts: all
  connection: local
  tasks:
    - name: Delete site resources
      skupper.v2.resource:
        state: absent
        path: "{{ resources_path }}"
        kubeconfig: "{{ kubeconfig }}"
        namespace: "{{ namespace }}"

The skupper.v2.resource modules from the skupper.v2 collection is called for both west and east resources using action absent, which removes the definitions provided through the YAML files.

Terminal:

ansible-playbook -i ansible/inventory.yml ansible/teardown.yml

Sample output:

$ ansible-playbook -i ansible/inventory.yml ansible/teardown.yml
[...]

PLAY RECAP *********************************************************************************************
east             : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
west             : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

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.