Creating a service network with OpenShift
For Use with Application Interconnect 1.0 LIMITED AVAILABILITY
Abstract
Preface
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 Introduction to Application Interconnect for an introduction to Application Interconnect.
Prerequisites
-
Access to projects in two OpenShift clusters,
cluster-adminaccess is not required. - One of the OpenShift clusters must be addressable from the other cluster.
-
kubectlandocCLI. Many commands can be performed usingoc, however this tutorial shows thekubectloptions.
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.
Chapter 1. Installing the skupper CLI
Installing the skupper command-line interface (CLI) provides a simple method to get started with Application Interconnect.
Procedure
- Ensure your subscription has been activated and your system is registered.
Subscribe to the required repositories:
- Red Hat Enterprise Linux 8
$ sudo subscription-manager repos --enable=application-interconnect-1-for-rhel-8-x86_64-rpms
Use the
yumordnfcommand to install theskupperpackage:$ sudo yum install skupper-cli
Verify the installation.
$ skupper version client version 1.0.2-redhat-1
Chapter 2. Configuring terminal sessions
This procedure describes how to configure your terminal sessions to use configurations to avoid problems as you configure Application Interconnect on different clusters.
The following table shows how you might set up your terminal sessions.
Table 2.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
Start a terminal session to work on the
westnamespace and set theKUBECONFIGenvironment variable:$ export KUBECONFIG=$HOME/.kube/config-west
This session is referred to later as the west terminal session.
Start a terminal session to work on the
eastnamespace and set theKUBECONFIGenvironment variable:$ export KUBECONFIG=$HOME/.kube/config-east
This session is referred to later as the east terminal session.
- In each terminal session, log into the OpenShift cluster.
Chapter 3. Installing the service network router in both clusters
In the west terminal session:
Create the
westproject (namespace):$ kubectl create namespace west $ kubectl config set-context --current --namespace west
Create the service network router:
$ skupper init
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.
In the east terminal session:
Create the
eastproject (namespace):$ kubectl create namespace east $ kubectl config set-context --current --namespace east
Create the service network router:
$ skupper init
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.
Chapter 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
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.yamlfile in your home directory, which you can use to create the secure connection.In the east terminal session, use the token to create a connection to the west namespace:
$ skupper link create $HOME/secret.yaml
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'
Chapter 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:
Deploy the frontend service:
$ kubectl create deployment hello-world-frontend --image quay.io/skupper/hello-world-frontend
Expose the frontend deployment as a cluster service:
$ kubectl expose deployment hello-world-frontend --port 8080 --type LoadBalancer
Create a route for the frontend:
$ kubectl expose svc/hello-world-frontend
Check the frontend route:
Get the route details:
$ oc get routes
The output should be similar to the following:
NAME HOST/PORT hello-world-frontend <frontend-url>
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.
Chapter 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
Deploy the backend service in the east terminal session:
$ kubectl create deployment hello-world-backend --image quay.io/skupper/hello-world-backend
Expose the backend service on the service network from the east terminal session:
$ skupper expose deployment hello-world-backend --port 8080 --protocol tcp
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
eastnamespace.Check the frontend route in the west terminal session:
Get the route details:
$ oc get routes
The output should be similar to the following:
NAME HOST/PORT hello-world-frontend <frontend-url>
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 Application Interconnect balances the requests.
This shows how the frontend calls the backend service over the service network from a different OpenShift cluster.
Additional resources
Chapter 7. Tearing down the service network
This procedure describes how to remove the service network you created.
Delete the
westnamespace from the west terminal session:$ kubectl delete namespace west
Delete the
eastnamespace from the east terminal session:$ kubectl delete namespace east
Chapter 8. Creating sites using a custom certificate authority on OpenShift
By default, Application Interconnect creates certificates to establish links between sites using mutual TLS. These certificates are stored as secrets in the namespace when you create a site using skupper init. If you want to use your own certificates, you can populate the a set of secrets with the appropriate certificates before creating the site as described in this section. This set of secrets provides Application Interconnect with the configuration required to create a site.
The following certificates are required:
- skupper-claims-server
- Used for linking sites with claim type tokens.
- skupper-console-certs
- Used by the Skupper console.
- skupper-local-client and skupper-local-server
- Used by the Skupper router.
- skupper-site-server
- Used for all inter-router connections, and for headless services.
- skupper-service-client
- Used for services exposed over TLS.
Prerequisites
-
Access to an OpenShift cluster with sufficient permission to run
skupper init. - Access to create certificates using your certificate authority.
Procedure
Create one or more certificates for a site.
There are several alternative approaches to this step:
- Reissue an existing certificate with a set of Subject Alternative Names (SANs) for the site.
- Create a new certificate with a set of SANs for the site.
- Create a new certificate for each item relating to the site.
You require a certificate for each of the following secrets:
-
skupper.<namespace> -
skupper-router.<namespace> -
skupper-router-local -
skupper-router-local.<namespace>.svc.cluster.local -
claims-<namespace>.<clustername>.<domain> -
skupper-<namespace>.<clustername>.<domain> -
skupper-edge-<namespace>.<clustername>.<domain> -
skupper-inter-router-<namespace>.<clustername>.<domain>
where:
-
<namespace>is the name of the namespace where you want to create a site. -
<clustername>is the name of the cluster. -
<domain>is the domain name for the cluster.
Using a specific certificate authority technology is beyond the scope of this guide. However, the following commands show how to create a certificate authority on Linux and create a single certificate that you can use to populate the secrets.
Create a
cadirectory and create a certificate authority certificate:$ mkdir ca $ cd ca $ ssh-keygen -t rsa -m PEM -f tls.key -q -N "" $ openssl req -x509 -nodes -days 365 -key tls.key -out tls.crt
Given the certificate authority created
tls.crtandtls.keyfiles, you can create a certificate for the site as follows:$ cd .. $ mkdir certificate $ cd certificate $ openssl req -nodes -newkey rsa:4096 -x509 -CA ../ca/tls.crt -CAkey ../ca/tls.key -out tls.crt -keyout tls.key -addext "subjectAltName = DNS:skupper.<namespace>, DNS:skupper-router.<namespace>, DNS:skupper-router-local, DNS:skupper-router-local.<namespace>.svc.cluster.local,DNS:claims-<namespace>.<clustername>.<domain>, DNS:skupper-<namespace>.<clustername>.<domain>, DNS:skupper-edge-<namespace>.<clustername>.<domain>, DNS:skupper-inter-router-<namespace>.<clustername>.<domain>"
You should now have a root certificate in the
cadirectory and another certificate in thecertificatedirectory that you can use with a site.Create secrets for the site
Change to the parent directory of the
certificatedirectory:$ cd ..
Populate the
carelated secrets using the certificate from thecadirectory:$ kubectl create secret tls skupper-site-ca --cert=ca/tls.crt --key=ca/tls.key $ kubectl create secret tls skupper-service-ca --cert=ca/tls.crt --key=ca/tls.key $ kubectl create secret tls skupper-local-ca --cert=ca/tls.crt --key=ca/tls.key
Populate the other secrets and modify them into the format required by
skupper:$ kubectl create secret tls skupper-claims-server --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-claims-server -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-site-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}" $ kubectl create secret tls skupper-console-certs --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-console-certs -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-local-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}" $ kubectl create secret tls skupper-local-client --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-local-client -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-local-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}" $ kubectl create secret tls skupper-local-server --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-local-server -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-local-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}" $ kubectl create secret tls skupper-site-server --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-site-server -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-site-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}" $ kubectl create secret tls skupper-service-client --cert=certificate/tls.crt --key=certificate/tls.key $ kubectl patch secret skupper-service-client -p="{\"data\":{\"ca.crt\": \"$($ kubectl get secret skupper-service-ca -o json -o=jsonpath="{.data.tls\.crt}")\"}}"
Create the site using the following command:
$ skupper init
On OpenShift,
skupperdefaults to use therouteingress, which is the equivalent ofskupper init --ingress route.To verify your site, check the status:
$ skupper status
You can also verify the OpenShift routes are created using:
$ oc get routes
Finally, use the following command to check for errors relating to incorrect certificates:
$ skupper debug events
Revised on 2022-10-19 18:01:27 UTC