You are browsing documentation for an older version. See the latest documentation here.

Get started with Red Hat OpenShift and 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

• Red Hat OpenShift Service on AWS (ROSA) CLI installed or another OpenShift 4.12 cluster with the ability to create LoadBalancer type Kubernetes Services
• An AWS account with ROSA permissions enabled
• kubectl CLI installed
• OpenShift Container Platform CLI installed
• Helm 3 installed
• Clone the Kong Mesh OpenShift quickstart repository:

    git clone https://github.com/Kong/kong-mesh-quickstart-openshift.git
  

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
   

3. Create a small ROSA cluster:

    rosa create cluster --cluster-name=$CLUSTER_NAME --region=$REGION --multi-az=false --version 4.12.13
   

4. When the cluster install is complete, create a cluster-admin user:

    rosa create admin --cluster $CLUSTER_NAME
   

   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
   

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>
   

   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
   

4. Get the latest Helm chart:

    helm repo add kong-mesh https://kong.github.io/kong-mesh-charts
   

5. Update Helm chart:

    helm repo update
   

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
   

7. Verify that Kong Mesh installed correctly by checking the pod health:

    kubectl get pods -n kong-mesh-system
   

   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
   

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
   

   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
      

   2. Apply the corresponding container patches:

       kubectl apply -f kong-mesh/container-patch.yaml 
      

      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
   

   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
   

3. In the kuma-demo directory, deploy the application:

     kubectl apply -f kuma-demo/kuma-demo-aio-ocp.yaml
   

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
   

5. Use port-forward to view the application:

     kubectl port-forward service/frontend -n kuma-demo 8080
   

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
   

2. Remove Kong Mesh:

    helm uninstall kong-mesh -n kong-mesh-system
   

   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
   

4. Delete the ROSA cluster:

    rosa delete cluster --cluster $CLUSTER_NAME
   

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:

• Deploy a standalone control plane
• Deploy a multi-zone global control plane