Deploying the API Microgateway in Kubernetes

This documentation is for the API Microgateway component that is coupled with WSO2 API Manager 2.6.0.
View the documentation for the latest release - WSO2 API Microgateway 3.0.2.

Start the API Manager and log in to the API Publisher (https://<hostname>:9443/publisher) using admin as the username and password.
Create an API with the following details:

Field Sample value
Name hello_world - v1
Context
/hello/v1
Version 1.0.0
Access Control All
Visibility on Store Public
Production URL http://bk.test.com
Tier Availability Gold, Unlimited

You can create an application that supports JWT tokens, subscribe to the API and get a JWT token to invoke the API.

Create a deployment.toml file enabling Kubernetes deployment, service and config map resources.

The config map is used to copy the micro-gw.conf file.

[kubernetes]
  [kubernetes.kubernetesDeployment]
    enable = true
    #name = ''
    #labels = ''
    #replicas = ''
    #enableLiveness = ''
    #initialDelaySeconds = ''
    #periodSeconds = ''
    #livenessPort = ''
    #imagePullPolicy = ''
    #image = ''
    #env = ''
    #buildImage = ''
    #[kubernetes.kubernetesDeployment.copyFiles]
    #  enable = true
    #  [[kubernetes.kubernetesDeployment.copyFiles.files]]
    #    source = '/home/user/custom_truststore.p12'
    #    target = '/home/ballerina/runtime/bre/security'
    #    isBallerinaConf = false
    #  [[kubernetes.kubernetesDeployment.copyFiles.files]]
    #    source = '/home/user/keystore.p12'
    #    target = '/home/ballerina/runtime/bre/security'
    #    isBallerinaConf = false  
    #dockerHost = ''
    #dockerCertPath = ''
    #push = ''
    #username = ''
    #password = ''
    #baseImage = ''
    #singleYAML = ''
  [kubernetes.kubernetesService]
    enable = true
    #name = ''
    #labels = ''
    serviceType = 'NodePort'
    #port = ''
  [kubernetes.kubernetesConfigMap]
    enable = true
    ballerinaConf = '/home/user/wso2am-micro-gw-toolkit-2.5.0/resources/conf/micro-gw.conf'
    #[[kubernetes.kubernetesConfigMap.configMaps]]
    #    name = ''
    #    mountPath = ''
    #    readOnly = false
    #    data = ['']

Let’s create a project called k8s_project and provide the deployment.toml file as an input.

Click here to see the description for each parameter...

kubernetes.kubernetesDeployment

Parameter	Description	Default value
name	Name of the deployment.	<outputfilename>-deployment
namespace	Namespace of the deployment.	null
labels	The labels related to the particular deployment.	"app: <outputfilename>"
replicas	The number of replicas.	1
dependsOn	The endpoints that the deployment depends on.	null
enableLiveness	Enable or disable the liveness probe.	false
initialDelaySeconds	The initial delay in seconds before performing the first probe.	10s
periodSeconds	The time interval between liveness probes in seconds.	5s
livenessPort	The port checked by the liveness probe.	<ServicePort>
imagePullPolicy	Docker image pull policy.	IfNotPresent
image	Docker image with tag.	<output file name>:latest
env	List of environment variables.	null
buildImage	Enable or disable building the Docker image.	true
copyFiles	Copy external files for the Docker image.	null
dockerHost	Docker host IP and docker PORT. E.g. `tcp://192.168.99.100:2376`	null
dockerCertPath	Docker cert path.	null
push	Enable or disable pushing the Docker image to the registry. This can only be enabled if `buildImage` parameter is set to true.	false
username	Username for the docker registry.	null
password	Password for the docker registry.	null
baseImage	Base image to create the docker image.	ballerina/ballerina:latest
imagePullSecrets	Image pull secrets value.	null
singleYAML	Enable or disable generating a single yaml file for all k8s resources.	false

kubernetes.kubernetesService

Parameter	Description	Default value
name	Name of the Service.	<service name>-service
labels	The labels for the service.	"app: <outputfilename>"
serviceType	The type of service.	ClusterIP
port	The port used by the service.	Port number

kubernetes.kubernetesIngress

Parameter	Description	Default value
name	Name of the Ingress.	<service name>-ingress
labels	The labels for the service.	"app: <outputfilename>"
hostname	Host name of the Ingress.	<service name>.com
annotations	Map of additional annotations.	null
path	Resource path.	/
targetPath	This URL will be used to rewrite.	null
ingressClass	Ingress class.	nginx
enableTLS	Enable or disable Ingress TLS.	false

kubernetes.kubernetesHPA

Parameter	Description	Default value
name	Name of the Horizontal Pod Autoscaler	<service name>-hpa
labels	The labels for the service.	"app: <outputfilename>"
minReplicas	The minimum number of replicas in the deployment.	No of replicas in deployment
maxReplicas	The maximum number of replicas in the deployment.	minReplicas+1
cpuPrecentage	CPU percentage to start scaling.	50

kubernetes.kubernetesSecret

Parameter	Description	Default value
name	Name of the secret mount.	<service_name>-secret
mountPath	Path to the mount on the container.	null
readOnly	Denotes whether the mount is read-only or not.	true
data	Paths to the data files.	null

kubernetes.kubernetesConfigMap

Parameter	Description	Default value
name	Name of the config map mount	<service_name>-config-map
mountPath	Path to the mount on the container	null
readOnly	Denotes whether the mount is read-only or not.	true
ballerinaConf	Location of the ballerina conf file.	null
data	Paths to the data files.	null

kubernetes.kubernetesPersistentVolumeClaim

Parameter	Description	Default value
name	Name of the secret mount.	null
annotations	The metadata annotations in the map.	null
mountPath	Path to mount on the container.	null
readOnly	Denotes whether the mount is read-only or not.	false
accessMode	Access mode.	ReadWriteOnce
volumeClaimSize	Size of the volume claim.	null

kubernetes.kubernetesJob

Parameter	Description	Default value
name	Name of the job.	<output file name>-job
namespace	Namespace for the job.	default
labels	The labels for the job.	"app: <outputfilename>"
restartPolicy	Restart policy for the job.	Never
backoffLimit	Backoff limit for the job.	3
activeDeadlineSeconds	Active deadline given in seconds.	20
schedule	Schedule for cron jobs.	none
imagePullPolicy	Docker image pull policy.	IfNotPresent
image	Docker image with tag.	<output file name>:latest
env	List of environment variables.	null
buildImage	Enable or disable building the Docker image.	true
dockerHost	Docker host IP and docker PORT. E.g. `tcp://192.168.99.100:2376`	null
dockerCertPath	Docker cert path.	null
push	Enable or disable pushing the Docker image to the registry. This can only be enabled if `buildImage` parameter is set to true.	false
username	Username for the docker registry.	null
password	Password for the docker registry.	null
baseImage	Base image to create the docker image.	ballerina/ballerina:latest

Navigate to the wso2am-micro-gw-toolkit-2.5.0/bin directory and run the following command,
```
./micro-gw setup k8s_project -a hello_world -v v1 --deployment-config deployment.toml
```
This commands creates the following folders under the k8s_project folder.
├── k8s_project
│   ├── conf
│   │ └── deployment-config.toml
│   ├── src
│   │ ├── extension_filter.bal
│   │ ├── hello_world_v1.bal
│   │ ├── listeners.bal
│   │ └── policies
│   │    ├── application_10PerMin.bal
│   │    ├── application_20PerMin.bal
│   │    ├── application_50PerMin.bal
│   │    ├── subscription_Bronze.bal
│   │    ├── subscription_Gold.bal
│   │    ├── subscription_Silver.bal
│   │    ├── subscription_Unauthenticated.bal
│   │    └── throttle_policy_initializer.bal
│   ├── target
│   └── temp
│       └── hashes.json
Build the project using the following command,
```
./micro-gw build k8s_project
```
This generates the following Kubernetes resources.
├── k8s_project
│ └── docker
│ └── Dockerfile
├── k8s_project_config_map.yaml
├── k8s_project_deployment.yaml
└── k8s_project_svc.yaml
The docker image to be deployed in Kubernetes is created in your local registry. You can find the image k8s_project:latest when you execute the docker images command.
Deploy the docker image in a Kubernetes environment.

You can push the docker image to the docker hub or to a private docker registry. If you change the docker image name, you need to change the image name in the k8s_project_deployment.yaml file.
You can also SCP the image to the Kubernetes nodes as follows:
1. Save the docker image to a tar file. For example,
```
docker save k8s_project:latest > image.tar
```
2. SCP the image to the Kubernetes nodes. For example,
```
scp -i <identity file> image.tar username@K8s_NODE_IP:
```
3. Load the docker image in the Kubernetes nodes. This needs to be executed in the Kubernetes nodes. For example,
```
docker load < image.tar
```
Deploy the API Microgateway in Kubernetes by deploying the Kubernetes resources using the following command,
```
kubectl create -f k8s_project/target/kubernetes/
```
Access the API in HTTPS using the following details:

The NodePort service type has been used in Kubernetes. For that service type, you can access the API using any of the Kubernetes node IP addresses and node ports.
https://<Any_Kubernetes_Node_IP>:<NodePort>/hello/v1/check
You can use the kubectl get services command to list down the services that run on Kubernetes.
Node port - 32616
URL - https://<Any_Kubernetes_Node_IP>:32616/hello/v1/check
Headers - Authorization Bearer <JWT_TOKEN>
Method - GET

As JWT is a self-contained access token, the Microgateway does not need to connect to the Key Manager. However, if you are using an Oauth2 access token, point the Microgateway to the Key Manager using the Key Manager details in the micro-gw.conf configuration file of the Microgateway. If you are running Key Manager in Kubernetes, you can provide the Key Manager serverUrl as shown below. The serverUrl has to be accessible from the Microgateway pods.

[keyManager]
serverUrl="https://localhost:9443"
username="admin"
password="admin"
tokenContext="oauth2"
timestampSkew=5000

Field		Sample value
Name		hello_world - v1
Context		`/hello/v1`
Version		1.0.0
Access Control		All
Visibility on Store		Public
Production URL		`http://bk.test.com`
Tier Availability		Gold, Unlimited