Creating a service network with OpenShift

This tutorial demonstrates how to connect a frontend service on a OpenShift cluster with a backend service on a OpenShift cluster using the skupper command-line interface (CLI).

See Overview for an introduction to Skupper.

Prerequisites

  • Access to projects in two OpenShift clusters, cluster-admin access is not required.

  • One of the OpenShift clusters must be addressable from the other cluster.

  • kubectl and oc CLI. Many commands can be performed using oc, however this tutorial shows the kubectl options.

This tutorial shows how to connect the following namespaces:

  • west - runs the frontend service and is typically a public cluster.

  • east - runs the backend service.

1. Installing the skupper CLI

Installing the skupper command-line interface (CLI) provides a simple method to get started with Skupper.

Procedure

  1. Install the skupper command-line interface.

    For Linux:

    $ curl -fL https://github.com/skupperproject/skupper/releases/download/1.0/skupper-cli-1.0-linux-amd64.tgz | tar -xzf -

    For MacOS:

    $ curl -fL https://github.com/skupperproject/skupper/releases/download/1.0/skupper-cli-1.0-mac-amd64.tgz | tar -xzf -

  2. Copy the skupper executable to a directory in your $PATH:

    $ mkdir -p $HOME/bin
$ export PATH=$PATH:$HOME/bin
$ mv skupper $HOME/bin

  3. Verify the installation.

    $ skupper version
client version 1.0

2. Configuring terminal sessions

This procedure describes how to configure your terminal sessions to use configurations to avoid problems as you configure Skupper on different clusters.

The following table shows how you might set up your terminal sessions.

Table 1. Terminal sessions
west terminal session east terminal session 
 $ kubectl get pods
 
 $ kubectl get pods
Prerequisites

  • The OpenShift CLI is installed. See the OpenShift CLI documentation for more instructions on how to install oc.

In OpenShift 4.6 and later, you can use the web terminal to perform the following procedure, as described in the web terminal documentation.
Procedure

  1. Start a terminal session to work on the west namespace and set the KUBECONFIG environment variable:

    $ export KUBECONFIG=$HOME/.kube/config-west

    This session is referred to later as the west terminal session.

  2. Start a terminal session to work on the east namespace and set the KUBECONFIG environment variable:

    $ export KUBECONFIG=$HOME/.kube/config-east

    This session is referred to later as the east terminal session.

  3. In each terminal session, log into the OpenShift cluster.

3. Installing the service network router in both clusters

  1. In the west terminal session:

    1. Create the west project (namespace):

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

    2. Create the service network router:

      $ skupper init

    3. Check the site status:

      $ skupper status

      The output should be similar to the following:

      Skupper enabled for namespace 'west'. It is not connected to any other sites.

  2. In the east terminal session:

    1. Create the east project (namespace):

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

    2. Create the service network router:

      $ skupper init

    3. Check the site status:

      $ skupper status

      The output should be similar to the following:

      Skupper enabled for namespace 'east'. It is not connected to any other sites.

4. Connecting namespaces to create a service network

With the service network routers installed, you can connect them together securely and allow service sharing across the service network.

Procedure

  1. In the west terminal session, create a connection token to allow connection to the west namespace:

    $ skupper token create $HOME/secret.yaml

    This command creates the secret.yaml file in your home directory, which you can use to create the secure connection.

  2. In the east terminal session, use the token to create a connection to the west namespace:

    $ skupper link create $HOME/secret.yaml

  3. Check the site status from the west terminal session:

    $ skupper status

    The output should be similar to the following:

    Skupper is enabled for namespace "west" in interior mode. It is connected to 1 other site. It has no exposed services.
The site console url is:  https://<skupper-url>
The credentials for internal console-auth mode are held in secret: 'skupper-console-users'

5. Creating the frontend service

The frontend service is a simple Python application that displays a message from the backend application.

Procedure

Perform all tasks in the west terminal session:

  1. Deploy the frontend service:

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

  2. Expose the frontend deployment as a cluster service:

    $ kubectl expose deployment hello-world-frontend --port 8080 --type LoadBalancer

  3. Create a route for the frontend:

    $ kubectl expose svc/hello-world-frontend

  4. Check the frontend route:

    1. Get the route details:

      $  oc get routes

      The output should be similar to the following:

      NAME                   HOST/PORT
hello-world-frontend   <frontend-url>

    2. Navigate to the <frontend-url> value in your browser, you see a message similar to the following because the frontend cannot communicate with the backend yet:

      Trouble! HTTPConnectionPool(host='hello-world-backend', port=8080): Max retries exceeded with url: /api/hello (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fbfcdf0d1d0>: Failed to establish a new connection: [Errno -2] Name or service not known'))

      To resolve this situation, you must create the backend service and make it available on the service network.

6. Creating the backend service and making it available on the service network

The backend service runs in the east namespace and is not available on the service network by default. You use the skupper command to expose the service to all namespaces on the service network. The backend app is a simple Python application that passes a message to the frontend application.

Procedure

  1. Deploy the backend service in the east terminal session:

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

  2. Expose the backend service on the service network from the east terminal session:

    $ skupper expose deployment hello-world-backend --port 8080 --protocol tcp

  3. Check the site status from the west terminal session:

    $ skupper status

    The output should be similar to the following:

    Skupper is enabled for namespace "west" in interior mode. It is connected to 1 other site. It has 1 exposed service.

    The service is exposed from the east namespace.

  4. Check the frontend route in the west terminal session:

    1. Get the route details:

      $  oc get routes

      The output should be similar to the following:

      NAME                   HOST/PORT
hello-world-frontend   <frontend-url>

    2. Navigate to the <frontend-url> value in your browser, you see a message similar to the following:

      Hi, <name>. I am Mathematical Machine (backend-77f8f45fc8-mnrdp).

      If you click Say hello again, a different backend process responds showing how Skupper balances the requests.

This shows how the frontend calls the backend service over the service network from a different OpenShift cluster.

Additional resources

7. Tearing down the service network

This procedure describes how to remove the service network you created.

  1. Delete the west namespace from the west terminal session:

    $ kubectl delete namespace west

  2. Delete the east namespace from the east terminal session:

    $ kubectl delete namespace east