Get started with Red Hat OpenShift and Kong Mesh

Uses: Kong Mesh

In this guide, you will learn how to get Kong Mesh up and running quickly in standalone mode on Red Hat OpenShift. This tutorial assumes some base-level OpenShift knowledge.

This tutorial doesn’t require a license because Kong Mesh can start in evaluation mode, which allows you to have up to five Data Planes or sidecars. This provides just enough Data Planes to get comfortable with the product and test it out.

This quickstart tutorial covers:

  • How to use the Red Hat Certified Kong Mesh images
  • How to implement the required OpenShift security context constraints (SCCs) for the kong-mesh sidecar
  • How to deploy a sample application, kuma-demo, on the mesh and validate that the application is working
  • How to use the sample application to test the features of Kong Mesh

Prerequisites

Install ROSA

In this section, you will install a ROSA cluster called kong-mesh-2 in the us-west-2 region. Then, you’ll create an admin user to get quick access to the cluster.

  1. Navigate to the kong-mesh-quickstart-openshift repository that you just cloned in the prerequisites. All commands in this guide should be run from that repository.

  2. Create system variables for the cluster name and region:
     CLUSTER_NAME=kong-mesh-demo
     REGION=us-west-2
    
    Copied to clipboard!
  3. Create a small ROSA cluster:
     rosa create cluster --cluster-name=$CLUSTER_NAME --region=$REGION --multi-az=false --version 4.12.13
    
    Copied to clipboard!
  4. When the cluster install is complete, create a cluster-admin user:
     rosa create admin --cluster $CLUSTER_NAME
    
    Copied to clipboard!

    Creating an admin user gives you quick access to the cluster for this quickstart. We recommend using a formal identity provider that you grant admin privileges to in a production environment.

  5. Validate you can log in to the cluster using the credentials provided by the ROSA CLI stout. Once you successfully login, you can proceed to the next section.

Install Kong Mesh in standalone mode

In this section, you’ll install Kong Mesh in standalone mode. Standalone mode is used in this quickstart for simplicity.

  1. Create the kong-mesh-system namespace:
     kubectl create namespace kong-mesh-system
    
    Copied to clipboard!
  2. Create the image pull secret:
     kubectl create secret docker-registry rh-registry-secret -n kong-mesh-system \
         --docker-server=registry.connect.redhat.com \
         --docker-username=$USERNAME \
         --docker-password=$PASSWORD \
         --docker-email=$EMAIL
    
    Copied to clipboard!

    This authenticates you to Red Hat’s image registry, which allows you to pull the certified images.

  3. Add nonroot-v2 to job service accounts so that each of their Kubernetes jobs successfully runs:
     oc adm policy add-scc-to-user nonroot-v2 system:serviceaccount:kong-mesh-system:kong-mesh-install-crds
     oc adm policy add-scc-to-user nonroot-v2 system:serviceaccount:kong-mesh-system:kong-mesh-patch-ns-job 
     oc adm policy add-scc-to-user nonroot-v2 system:serviceaccount:kong-mesh-system:kong-mesh-pre-delete-job
    
    Copied to clipboard!
  4. Get the latest Helm chart:
     helm repo add kong-mesh https://kong.github.io/kong-mesh-charts
    
    Copied to clipboard!
  5. Update Helm chart:
     helm repo update
    
    Copied to clipboard!
  6. Install Kong Mesh:
     helm upgrade -i kong-mesh kong-mesh/kong-mesh --version 2.2.0 -f kong-mesh/values.yaml -n kong-mesh-system
    
    Copied to clipboard!
  7. Verify that Kong Mesh installed correctly by checking the pod health:
     kubectl get pods -n kong-mesh-system
    
    Copied to clipboard!

    This should return the Control Plane that is running, like the following:

     NAME                                       READY   STATUS    RESTARTS   AGE
     kong-mesh-control-plane-7443h46bd4-cmhsa   1/1     Running   0          19s
    
    Copied to clipboard!
  8. In a new terminal window, port-forward to reach the Kong Mesh GUI:
     kubectl port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681
    
    Copied to clipboard!

    You should be able to reach the Kong Mesh UI at http://localhost:5681/gui.

  9. Finally, you must do some prep work for the sidecar itself so sidecars will start up successfully.
    1. Apply the kong-mesh-sidecar SCCs:
       kubectl create -f kong-mesh/kong-mesh-sidecar-scc.yaml
      
      Copied to clipboard!
    2. Apply the corresponding container patches:
       kubectl apply -f kong-mesh/container-patch.yaml 
      
      Copied to clipboard!

      In OpenShift, by default, all pods and containers are given the restricted SCC. This is insufficient for the Kong Mesh sidecars (containers). The sidecars need a slightly escalated permissions, these permissions are defined in the kong-mesh-sidecar-scc manifest. The container-patch file defines how to patch the sidecars with the SCCs.

Deploy the demo application

In this step, you’ll deploy the kuma-demo app to Kong Mesh. This allows you to quickly populate your mesh with Services so you can test the capabilities of Kong Mesh.

The kuma-demo app consists of two Services:

  • demo-app: A web application that lets you increment a numeric counter
  • redis: A data store for the counter
  1. Escalate the SCC of PostgreSQL SA to privileged:
      oc adm policy add-scc-to-user privileged system:serviceaccount:kuma-demo:kuma-demo-postgres
    
    Copied to clipboard!

    Escalating the SCC allows access to all privileged and host features. This is only recommended for this tutorial, do not escalate the SSC of PostgreSQL SA in a production environment.

  2. Escalate the SCC of the default SA (this is the SA for the rest of the kuma-demo application pods) to use the kong-mesh-sidecar SCC:
      oc adm policy add-scc-to-user kong-mesh-sidecar system:serviceaccount:kuma-demo:default
    
    Copied to clipboard!
  3. In the kuma-demo directory, deploy the application:
      kubectl apply -f kuma-demo/kuma-demo-aio-ocp.yaml
    
    Copied to clipboard!
  4. You should see four application pods, each with two containers, in the output:
      kubectl get pods -n kuma-demo
      NAME                                    READY   STATUS    RESTARTS   AGE
      kuma-demo-app-5f5f685863-8778x          2/2     Running   0          51s
      kuma-demo-backend-v0-90bc879754-srafd   2/2     Running   0          52s
      postgres-master-6577s699c8-z9nas        2/2     Running   0          54s
      redis-master-949t4d567-khmha            2/2     Running   0          53s
    
    Copied to clipboard!
  5. Use port-forward to view the application:
      kubectl port-forward service/frontend -n kuma-demo 8080
    
    Copied to clipboard!

You can see the applications in the Kong Mesh UI at http://localhost:8080.

Test Kong Mesh capabilities

Now that you’ve deployed Kong Mesh along with the demo application on your ROSA cluster, you can test Kong Mesh. You can follow the instructions in Enable Mutual TLS and Traffic Permissions to learn how to use policies in Kong Mesh.

Clean up

In this section, you will remove all components, including kuma-demo and Kong Mesh, and delete the ROSA cluster. Once all of these are removed, you can create a Kong Mesh production environment.

  1. Remove the kuma-demo application:
     kubectl delete deploy,svc --all -n kuma-demo
    
    Copied to clipboard!
  2. Remove Kong Mesh:
     helm uninstall kong-mesh -n kong-mesh-system
    
    Copied to clipboard!

    All the components are now removed, so it’s safe to delete the ROSA cluster.

  3. Delete the ROSA cluster admin user:
     rosa delete admin --cluster $CLUSTER_NAME
    
    Copied to clipboard!
  4. Delete the ROSA cluster:
     rosa delete cluster --cluster $CLUSTER_NAME
    
    Copied to clipboard!

Next steps

Now that you’ve deleted your demo cluster and components, you can deploy Kong Mesh in a production environment. Follow the instructions in one of the following guides to deploy Kong Mesh using your method of choice:

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!