WSO2 API Microgateway has a runtime Docker image in which you can provide executable runtime artifacts as a mount. Let's follow the instructions below to see how we can create Docker image by including the runtime executable artifacts, so that you do not have to mount the artifacts from outside. This approach uses the deployment-config.toml
file as an input to the WSO2 API Microgateway Toolkit, which generates the Docker images from the WSO2 API Microgateway base image by including all the API runtime artifacts as well.
Let's deploy WSO2 API Microgateway in Docker.
Step 1 - Follow the installation prerequisites
Make sure to install and set up Docker and the installation prerequisites for the Microgateway Toolkit.
Step 2 - Create a microgateway project
- Navigate to a preferred workspace folder using the command line to set the location that is used to store the Microgateway project.
Create a project.
Let's create a project named "petstore" by running the following command. This will create the folder structure for the artifacts to be included.Formatmicro-gw init <project_name>
Examplemicro-gw init petstore Project 'petstore' is initialized successfully.
Step 3 - Build the microgateway project
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.Create the input for WSO2 API Microgateway Toolkit.
Create a file nameddeployment.toml
in a preferred location.This TOML file should contain the relevant deployment configurations (e.g., Docker image name, registry, tag, etc.) as shown below. For more information on each of the above parameters, see deployment.toml for Docker. Note that you will have to use this TOML file as the input, by way of passing the file path, when creating the Microgateway project.[docker] [docker.dockerConfig] enable = true name = "petstore" registry = 'docker.wso2.com' tag = 'v1' #buildImage = '' #dockerHost = '' #dockerCertPath = '' baseImage = 'wso2/wso2micro-gw:3.0.2' #enableDebug = '' #debugPort = '' #push = '' [docker.dockerCopyFiles] enable = true [[docker.dockerCopyFiles.files]] source = '<MICROGW_TOOLKIT_HOME>/resources/conf/micro-gw.conf' target = '/home/ballerina/conf/micro-gw.conf' isBallerinaConf = true
Specify docker credentials
If the docker image push is enabled to push the image to a docker registry , specifying of the username and password should be done using environment variables
export DOCKER_USERNAME=<USER>
export DOCKER_PASSWORD =<PASSWORD>
Build the microgateway project.
Use your command line tool to navigate to where the project directory ("petstore") was created and execute the following command to build the project.Formatmicro-gw build <project_name> --deployment-config <path-to-the-deployment.toml>
Examplemicro-gw build petstore --deployment-config /Users/kim/Downloads/deployment.toml
The Docker image is created in your local registry and you can use it to spawn a WSO2 API Microgateway Docker container.
Step 4 - Run the Docker container
Run the Docker container using the following command.
docker run -d -p 9090:9090 -p 9095:9095 docker.wso2.com/<docker_name>:<docker_tag>
When following this Docker deployment guide, you will end up by creating a Docker image with APIs built into it; thereby, the .balx
file will already be inside the Docker image. Therefore, unlike in the Quick Start Guide for Docker you do not have to specify the project name when running the Docker container and mount the .balx
file in to the Docker image.
If you are working in a Linux environment, you can either use the above command or the following command to start your Docker container. In the following command the Docker container uses the host network driver for your container.
docker run --network host -d docker.wso2.com/<docker_name>:<docker_tag>
For more information on working with Docker in different environments, see the relevant Docker documentation: Docker for Mac, Docker for Windows.
Step 5 - Invoke the sample API
Step 5.1 - Obtain token
After the APIs are exposed via WSO2 API Microgateway, 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.
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
Step 5.2 - Invoke the API
Invoke the API using the JWT token using the following command.
Retrieve the Docker container IP address.
docker ps - This provides the container id docker inspect <Container_ID> | grep "IPAddress"
Execute the command below to set a self-contained OAuth2.0 access token in the JWT format as a variable on your terminal session.
FormatTOKEN=<JWT-token>
ExampleTOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==
When you are deploying the Microgateway in production, make sure to change its default certificates.
You can now invoke the API running on the Microgateway using the following cURL command.
Formatcurl -X GET "<container_IP>:<MGW-runtime-port>/<API-context>/<API-resource>" -H "accept: application/xml" -H "Authorization:Bearer <JWT_TOKEN>" -k
Examplescurl -X GET "https://localhost:9095/petstore/v1/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k curl -X GET "https://localhost:9095/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k