Run Microservice Created Using MATLAB Compiler SDK on AWS

Open Live Script

This example shows how to create a microservice Docker® image and deploy it on Amazon Web Services (AWS®). The microservice image created by MATLAB® Compiler SDK™ provides an HTTP/HTTPS endpoint to access MATLAB code.

You package a MATLAB function into a deployable archive, and then create a Docker image that contains the archive and a minimal MATLAB Runtime package. You can then run the image in Docker and make calls to the service using any of the MATLAB Production Server™ client APIs.

Prerequisites

Verify that you have MATLAB Compiler SDK (R2022a or later) installed on the development machine.
Verify that you have the MATLAB Runtime installer. You can download the installer from the MathWorks® website: https://www.mathworks.com/products/compiler/matlab-runtime.html
Verify that you have Docker installed and configured on the development machine by typing [~,msg] = system('docker version') in a MATLAB command window. If you are using WSL, use 'wsl docker version' instead.
If you do not have Docker installed, follow the instructions on the Docker website to install and set up Docker. See https://docs.docker.com/engine/install/.
To build microservice images on Windows®, you must install either Docker Desktop or Docker on Windows Subsystem for Linux® v2 (WSL2). To install Docker Desktop, see https://docs.docker.com/desktop/install/windows-install/. To install Docker on WSL2, see https://www.mathworks.com/matlabcentral/answers/1758410-how-do-i-install-docker-on-wsl2.
Verify that you have an AWS account.
Verify that you have installed the AWS Command-Line Interface (CLI). For details, see: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html. The AWS CLI must be configured with your credentials using the following command: aws configure.

Create MATLAB Function

Create a MATLAB function from the MATLAB desktop. For this example, write a function named simpInterest.m using the following code.

function i = simpInterest(p,r,t)
    i = p * (1 + (r * t)) - p;
end

Create Deployable Archive

Package the simpInterest.m function into a deployable archive using the compiler.build.productionServerArchive function. Save the build information as the compiler.build.Results object results.

results = compiler.build.productionServerArchive("simpInterest.m","ArchiveName","financetools","Verbose","on")

Package Deployable Archive into Microservice Docker Image

Package the deployable archive into a microservice Docker image using the results object that you created.

compiler.package.microserviceDockerImage(results,"ImageName","financetools")

The function generates the following files within a folder named financetoolsmicroserviceDockerImage:

applicationFilesForMATLABCompiler/financetools.ctf — Deployable archive file
Dockerfile — Docker file that specifies run-time options
GettingStarted.txt — Text file that contains deployment information

Verify that the financetools image has been created by typing docker images.

For details, see MATLAB Compiler SDK Create Microservice Docker Image.

Create AWS Elastic Container Registry Repository

Go to your AWS Console and type Elastic Container Registry in the search bar. Select Elastic Container Registries service from the results. Click Create Repository and fill out the General settings.

Visibility settings — Choose Private or Public.
Repository name — Give it the same name as the image you created in the previous step.

In this example, the registry is named financetools and is set to public visibility.

Upload Microservice Docker Image to AWS Elastic Container Registry

Navigate to your newly created repository and click View Push Commands. This opens a command window titled Push Commands for financetools with instructions to push your microservice image to your repository.

Then, retrieve an authentication token and authenticate your Docker client to your registry. The appropriate visibility, region, and repository ID are prepopulated in the command shown in the popup window. Copy the command and run it in a command window. The command should resemble the following.

aws ecr-<visibility> get-login-password --region <your_region> | docker login --username AWS --password-stdin <visibility>.ecr.aws/<your_repository_id>

Tag the microservice Docker image with your container registry by running the command provided in Step 3 of the Push commands for financetools popup window. For example:

docker tag financetools:latest public.ecr.aws/l8f7j0c7/financetools:latest

Upload the microservice Docker image by running the command provided in Step 4 of the popup window titled Push commands for financetools. For example:

docker push public.ecr.aws/l8f7j0c7/financetools:latest

This takes a few minutes as the microservice Docker image is uploaded to the cloud. When complete, your Docker image is visible as a repository in your AWS Elastic Container Registry.

Run Microservice Docker Image

You can run your microservice Docker image using one of the following options on AWS:

AWS Fargate
Amazon EC2®
AWS App Runner
Amazon Elastic Container Service
Amazon Elastic Kubernetes® Service

For this example, use the AWS App Runner option, which lets you run a single container.

To run it as AWS App Runner:

From the AWS Console, search for 'AWS App Runner' and create a new App Runner service.

In the Source and deployment tab, complete the Source and the Deployment settings sections.

Project details

Repository type — Container registry.
Provider — Select appropriately.
Container image URI — Paste URI or click Browse to select your image.

Deployment settings

Deployment Trigger — Manual.
ECR access role — Use default or select appropriately.

Click Next. Complete the Service settings section.

Service settings

Service name — financetools.
Virtual CPU & Memory — 1 vCPU & 2 GB.
Port — 9910.
Auto scaling configuration — Use Default configuration.

Health check

Protocol: HTTP.
Path: /api/health.

Security

AWS KMS Key: Use default.

Networking:

Incoming network traffic: Select appropriately, this example uses Public endpoint.
Outgoing network traffic: Select appropriately, this example uses Public access.

Click Next. Click Create & deploy to create the AWS App Runner service.

Once your AWS App Runner service is deployed you can make requests to it using the Default domain on the Service overview page.

Make Request to Microservice Running in AWS App Runner

Make a request to the microservice using command line tool or UI such as Postman. Pass in the three input variables for principal, interest, and time in JSON format.

POST /financetools/simpInterest HTTP/1.1
Host: https://4kxqyz9md2.us-east-1.awsapprunner.com/financetools/simpInterest
Content-Type: application/json
Content-Length: 42
{"nargout": 1, "rhs": [21000, 0.043, 12] }

The format of the host URI is Default_domain/container_image_name/matlab_function_name.

Make a request using curl (replace with your own default domain prefix).

curl --location 'https://4kxqyz9md2.us-east-1.awsapprunner.com/financetools/simpInterest' \
--header 'Content-Type: application/json' \
--data '{"nargout": 1, "rhs": [21000, 0.043, 12] }'

You receive the simple interest amount as a JSON formatted result.

{"lhs":[{"mwdata":[10836],"mwsize":[1,1],"mwtype":"double"}]}