This documentation is for WSO2 Microgateway 3.0.1. View documentation for the latest release.
API Microgateway Documentation

All docs This doc
Expand all   Collapse all

Versions Compared

Old Version 7

changes.mady.by.user Rajith Roshan

Saved on

compared with

New Version Current

changes.mady.by.user Mariangela Hills

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added the dev first approach

...

Follow the

...

Create an API with the following details:

...

/hello/v1

...

instructions below to deploy WSO2 API Microgateway in Kubernetes.

Table of Contents

Step 1 - Follow the installation prerequisites

Make sure to do the following:

  1. Carry  out the installation prerequisites for WSO2 API Microgateway Toolkit.
  2. Install and setup kubectl in your client machine.
  3. Setup a Kubernetes cluster.
  4. Make sure that kubectl points to your Kubernetes cluster.

Step 2 - Create a Microgateway project

  1. Navigate to a preferred workspace folder using the command line to set the location that is used to store the Microgateway project.

  2. Create a project.
    Let's create a project named k8s_project  by running the following command. This will create the folder structure for the artifacts to be included.

    Code Block
    titleFormat
    micro-gw init <project_name>
    Code Block
    titleExample
    micro-gw init k8s_project  
Project 'k8s_project' is initialized successfully.

Step 3 - Build the Microgateway project

  1. Add the API to the project. 

    Navigate to the  /petstore/api_definitions  directory and add the OpenAPI definition(s) to this  directory. Let's use the  Petstore sample OpenAPI definition in this scenario.

    Info

    The latter mentioned instructions uses the developer first approach. However, if you wish to work with APIs that you have published in WSO2 API Manager, you can either import a single API or you can import the APIs as a group.

  2. Create the input for WSO2 API Microgateway Toolkit.
    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.that you will use as the input when creating the microgateway project. This TOML file should contain the relevant deployment configurations as shown below. For more information on each of the above parameters, see deployment.toml for Kubernetes.

    Code Block
    [kubernetes]
  [kubernetes.kubernetesDeployment]
    enable = true
    #name = ''
    #labels = ''
    #replicas = ''
    #enableLiveness = ''
    #initialDelaySeconds = ''
    #periodSeconds = ''
    #livenessPort = ''
    #imagePullPolicy = ''
    #image = ''
    #env = ''
    #buildImage = ''
    #copyFiles = ''
    #dockerHost = ''
    #dockerCertPath = ''
    #push = ''
    #username = ''
    #password = ''
    #baseImage = ''
    #singleYAML = ''
  [kubernetes.kubernetesService]
    enable = true
    #name = ''
    #labels = ''
    serviceType = 'NodePort'
    #port = ''
  [kubernetes.kubernetesConfigMap]
    enable = true
    ballerinaConf = '<MICROGW_TOOLKIT_HOME>/resources/conf/micro-gw.conf'
    #[[kubernetes.kubernetesConfigMap.configMaps]]
    #    name = ''
    #    mountPath = ''
    #    readOnly = false
    #    data = ['']
    Specify
    Info
    titledeployment-config.toml
    Note

    Make sure to specify the complete path for the ballerinaConf, by replacing the <MICROGW_TOOLKIT_HOME>

    placeholder with

    the

    full

    path.

    ex

    Example:


    home/users/wso2am-micro-gw-toolkit-3.x.x/resources/conf/micro-gw.conf

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

    Expand
    titleClick here to see the description for each parameter...

    Table of Contents
    maxLevel4
    minLevel4

    kubernetes.kubernetesDeployment

    ParameterDescriptionDefault valuenameName of the deployment.<outputfilename>-deploymentnamespaceNamespace of the deployment.nulllabelsThe labels related to the particular deployment."app: <outputfilename>"replicasThe number of replicas.1dependsOnThe endpoints that the deployment depends on.nullenableLivenessEnable or disable the liveness probe.falseinitialDelaySecondsThe initial delay in seconds before performing the first probe.10speriodSecondsThe time interval between liveness probes in seconds.5slivenessPortThe port checked by the liveness probe.<ServicePort>imagePullPolicyDocker image pull policy.IfNotPresentimageDocker image with tag.<output file name>:latestenvList of environment variables.nullbuildImageEnable or disable building the Docker image.truecopyFilesCopy external files for the Docker image.nulldockerHostDocker host IP and docker PORT.
    E.g. tcp://192.168.99.100:2376nulldockerCertPathDocker cert path.nullpushEnable or disable pushing the Docker image to the registry.
    This can only be enabled if buildImage parameter is set to true.falseusernameUsername for the docker registry.nullpasswordPassword for the docker registry.nullbaseImageBase image to create the docker image.ballerina/ballerina:latestimagePullSecretsImage pull secrets value.nullsingleYAMLEnable or disable generating a single yaml file for all k8s resources.false

    kubernetes.kubernetesService

    ParameterDescriptionDefault valuenameName of the Service.<service name>-servicelabelsThe labels for the service."app: <outputfilename>"serviceTypeThe type of service.ClusterIPportThe 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

    nameName of the Horizontal Pod Autoscaler<service name>-hpalabelsThe labels for the service."app: <outputfilename>"minReplicasThe minimum number of replicas in the deployment.No of replicas in deploymentmaxReplicasThe maximum number of replicas in the deployment.minReplicas+1cpuPrecentageCPU percentage to start scaling.50

    kubernetes.kubernetesSecret

    Parameter

    Description

    Default value

    nameName of the secret mount.<service_name>-secretmountPathPath to the mount on the container.nullreadOnlyDenotes whether the mount is read-only or not.truedataPaths to the data files.null

    kubernetes.kubernetesConfigMap

    Parameter

    Description

    Default value

    nameName of the config map mount<service_name>-config-mapmountPathPath to the mount on the containernullreadOnlyDenotes whether the mount is read-only or not.trueballerinaConfLocation of the ballerina conf file.nulldataPaths to the data files.null

    kubernetes.kubernetesPersistentVolumeClaim

    Parameter

    Description

    Default value

    nameName of the secret mount.nullannotationsThe metadata annotations in the map.nullmountPathPath to mount on the container.nullreadOnlyDenotes whether the mount is read-only or not.falseaccessModeAccess mode.ReadWriteOncevolumeClaimSizeSize of the volume claim.null

    kubernetes.kubernetesJob

    ParameterDescriptionDefault valuenameName of the job.<output file name>-jobnamespaceNamespace for the job.defaultlabelsThe labels for the job."app: <outputfilename>"restartPolicyRestart policy for the job.NeverbackoffLimitBackoff limit for the job.3activeDeadlineSecondsActive deadline given in seconds.20scheduleSchedule for cron jobs.noneimagePullPolicyDocker image pull policy.IfNotPresentimageDocker image with tag.<output file name>:latestenvList of environment variables.nullbuildImageEnable or disable building the Docker image.truedockerHostDocker host IP and docker PORT.
    E.g. tcp://192.168.99.100:2376nulldockerCertPathDocker cert path.nullpushEnable or disable pushing the Docker image to the registry.
    This can only be enabled if buildImage parameter is set to true.falseusernameUsername for the docker registry.nullpasswordPassword for the docker registry.nullbaseImageBase image to create the docker image.ballerina/ballerina:latest

  3. Lets create a microgateway project/

    1. Navigate to a preferred workspace folder using the command line. (This location is used to run the Microgateway commands and to generate Microgateway artifacts.)

    2. Create a project using the command given below,(We need to add the <MGW_TOOLKIT_HOME>/bin folder to PATH variable in order to run the command from any location) 

    Code Block
    micro-gw init k8s_project

  4. Now lets add the API(open API definition) to the project. Navigate to the /k8s_project/api_definitions directory. Add the API definition(s) to this directory. A sample open API definition can be found here.

  5. Build the project using the following command,

    code

    Build the microgateway project.

    Use your command line tool to navigate to where the project directory ( k8s_project ) was created and execute the following command to build the project. 

    Code Block
    titleFormat
    micro-gw build <project_name> --deployment-config deployment.toml
    Code Block
    titleExample
    micro-gw build k8s_project --deployment-config deployment.toml

    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 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 Docker images command.Deploy the docker

    Step 4 - Deploy the Docker image in a Kubernetes environment

    .
    Info
    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:

    Save the docker image to a tar file. For example,

    Code Block

    Let's SCP the image to the Kubernetes nodes to deploy the Docker image in a K8s environment.
    Info

    For more options on deploying the Docker image in a Kubernetes environment, see the Deployment related FAQs.

    1. Save the Docker image to a tar file.

      Code Block
      titleFormat
      docker save <MGW-project-name>:latest > <Docker-image-name>.tar
      Code Block
      titleExample
      docker save k8s_project:latest > image.tar

    2. SCP the image to the Kubernetes nodes. For example, 

      Code Block
      titleFormat
      scp -i <identity -file> image.tar [email protected][email protected]<K8s_NODE_IP:IP>:

      • Identity file - This refers to the public key of the Kubernetes node. For example you can get a google_compute_engine.pub for GCE. You have to scp the Docker image for each and every Kubernetes node.

        Note

        When using minikube, the username is docker and you can find the IP address by using the minikube ip command.

    3. Load the docker Docker image in the Kubernetes nodes. This needs to be executed
      You need to execute the following command in the Kubernetes nodes. For example,

      Code Block

       

      Code Block
      titleFormat
      docker load < [Docker-image-name].tar
      Code Block
      titleExample
      docker load < image.tar

Step 5 - Start the Kubernetes cluster

Deploy

...

WSO2 API Microgateway in Kubernetes by deploying the Kubernetes resources

...

(artifacts) and starting WSO2 API Microgateway.

Code Block
titleFormat
kubectl create -f <MGW-project-name>/target/kubernetes/
Code Block
titleExample
kubectl create -f k8s_project/target/kubernetes/

Access the API in HTTPS using the following details:

Info

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


...

Step 6 - Invoke the sample API

Step 6.1 - Obtain token

After the APIs are exposed via WSO2 API Microgateway, which you deployed in a Kubernetes cluster, you can invoke an API with a valid JWT token or an opaque access token.
In order to use JWT tokens, WSO2 API Microgateway should be presented with a JWT signed by a trusted OAuth2 service.
Let's use the following sample JWT token that never expires, which was generated using WSO2 API Manager for testing purposes.

Code Block
titleJWT Token
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
Info
iconfalse
titleMore information
  • You can obtain a JWT token from any third-party secure token service or via the WSO2 API Manager. 
  • Alternatively, you can also use an OAuth2 token to invoke the API.

For more information, see the FAQs on Working with Tokens.

Step 6.2 - Invoke the API

Invoke the API using the JWT token using the following command.

...

  1. Execute the command below to set a self-contained OAuth2.0 access token in the JWT format as a variable on your terminal session.

    Code Block
    titleFormat
    TOKEN=<JWT-token>
    Code Block
    titleExample
    TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
    Note

    When you are deploying the Microgateway in production, make sure to change its default certificates.

  2. You can now invoke the API running on the Microgateway using the following cURL command.

    Code Block
    titleFormat
    curl -X GET "<Any_Kubernetes_Node_IP>:
    32616
    <NodePort>/
    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.

  1. <API-context>/<API-resource>" -H "accept: application/xml" -H "Authorization:Bearer <JWT_TOKEN>" -k
    Info

    As this example uses NodePort as the service typein Kubernetes, you can access the API using any of the Kubernetes node IP addresses and node ports when using the latter mentioned service type.
    In addition, you can use the kubectl get svc command to list down the services that run on Kubernetes in order to get the port. However, to identify an external IP of the Kubernetes cluster you can use the command 
    kubectl get nodes -o yaml | grep -B 1 "type: ExternalIP"
    If you use minukube as the Kuberneterse cluster, then you can find the external IP by using the minikube ip command.

    Code Block
    titleExamples
    curl -X GET "https://localhost:32616/petstore/v1/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

curl -X GET "https://localhost:32616/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

    In the above example, localhost is used as the Kubernetes node IP, because it was based on Kubenetes that was provided by Docker for Mac.