How to deploy Moleculer to AWS Lambda?

[Susros]

Hi, just wondering if anyone has done Moleculer in Serverless architecture? I am wondering if anyone could walk me through how do I configure and deploy to AWS Lambda with SQS please? Thanks.

[ccampanale]

@Susros

Preface

First, let's address the fact that AWS Lambda is a type of Serverless computing but is not the only type. ECS Fargate makes very quick work of deploying containerized solutions in what is essentially a serverless architecture since you are not responsible for maintaining the underlying infrastructure. Developing and containerizing Moleculer microservices is straight forward and is documented elsewhere, so let's focus on AWS Lambda as you stated in the subject of the discussion.

Lambda provides us with a "Function as a Service" which, in my opinion, aligns the closest with Moleculer service actions. Given a Moleculer system, a service provides a collection of actions and event handlers to the system which may be invoked by calling (actions) or due to an event in the system. AWS Lambda supports "Applications" which essentially group functions and could be considered similar in way to the Moleculer service. Given appropriate permissions lambda functions may be invoked by other internal AWS resource (such as an EC2 instance, ECS task, another lambda, etc.) as well as external resources using the AWS SDK or CLI. Additionally, various types of triggers may be configured for lambdas from services such as API Gateway, CloudWatch, and EventBridge to name a few. The AWS services consumed to architect the solution basically handle what could be considered functionally equivalent to Moleculer service brokers.

With that baseline set, I think it's important to consider why you may want to use Moleculer in AWS Lambda. If you do not have an existing Moleculer system you may be over complicating the situation when you could just as easily leave Moleculer out of the equation, implement lambda in the language of your choice, and architect function integration (etc.) using the AWS services/resources available to you. Frameworks like Serverless actually make this extremely approachable and support exposing API gateways and several other features out of the box. However, I do think there are situations where this might be useful.

Exploring this concept is something that's been on my back burner for some time but I haven't gotten around to building anything. In my team's case, we have an existing Moleculer system at the core of our platform with an NATS cluster providing the system's transport. This was originally developed to avoid some level of CSP lock-in so all of our services are deployed via "packages" (see this discussion for more detail on that) which each run in highly available ECS Service Tasks. So exploring a Lambda integration for us has a very specific use case; essentially, exposing an easily authenticated/authorized (using IAM) non-HTTP interface (AWS Lambda API/SDK) for integrating pure AWS solutions with our Moleculer system. This interface could then be used primarily for concerns such as:

• exposing Moleculer microservice actions as Lambda functions which would be otherwise unreachable (or only available on a public API GW) providing a sort of "secure private/internal API"
• ingesting events from within AWS by invoking lambdas and emitting/broadcasting these events within the Moleculer system

Given that you can simply provision the appropriate IAM permissions to anything else running virtually anywhere, it would seem unnecessary to use Moleculer in Lambda for the purposes of providing existing services with a means to "do something in AWS" as this could simply be implemented in the existing Moleculer system. In other words, Moleculer in Lambda is probably very niche and mostly about exposing the existing system's functionality to solutions running purely in AWS.

AWS Solution Invokes Lambda exposing Moleculer System

graph TD;
  AWS_Solution-->Lambda;
  Lambda-->Moleculer_Broker;
  Moleculer_Broker-->Moleculer_Service;

Loading

This is plausible, as this would essentially allow you to expose a custom interface for Remote Procedure Calls into Moleculer.

Moleculer Service Consumes AWS

graph TD;
  Moleculer_Service-->AWS_SDK;

Loading

Notice there is no need for this to be done by way of Lambda; simply act directly upon the AWS resources as needed.

If the use case is right then definitely move ahead, but be sure you are not over complicating things trying to use something "different" just for the sake of it; think carefully about why you want to use Moleculer in Lambda.

Moving forward I'm going to assume that you have an existing system that you are connecting to for integration purposes.

Configuration

There are a few things to keep in mind as far as configuration is concerned:

• Your lambda function will need to initialize a ServiceBroker and connect to your existing system. Consider how this will be done; using lambda environment variables to configure transport configurations, fetching configuration from SSM PS or Secrets Manager, etc.
• I may be wrong (again, I have not gotten into the actually implementation, just a bit of thought around it) but I don't believe the standard on-rails startup processes will be sufficient or desirable; ergo, you'll likely need to cook up your own start-up implementation rather than relying on the Moleculer Runner.
• Lambda functions each run in their own execution environment which are not shared between functions, even functions which share the same underlying code. Therefore, each invocation will initialize an execution environment which will start a Broker and add a node to your system. How many nodes per function would be determined by your lambda's concurrency configuration.
• Service broker initialization and startup is an asynchronous process so you'll need to configure your lambda appropriately as an ES module such that you can use a top-level await such that initialization and startup can finish before the Lambda runtime considers the function initialized. (This guide has the details on that.) Failure to do this could easily go unnoticed - perhaps the service broker almost always initialized in under the 10 seconds allotted by default - but if there is ever a hiccup that causes a delayed initialization, the Lambda runtime may invoke your function handler and get and throw an exception due to an incomplete initialization/start-up.

Lambda

With the package.json configured appropriately such that the codebase is loaded as an ES module, assuming all dependencies are declared and loaded as needed, the following should be a somewhat close to working:

import { ServiceBroker } from 'moleculer';

// Note: The config file must also be ESM formatted to be loaded this way
import * as config  from './moleculer.config.js';

const exampleServiceSchema = {
  name: 'example-lambda-service',
  version: 1,
  actions: {
    getFunctionEnvironment: {
      handler(ctx) {
        console.log(`lambda function environment details requested from ${ctx.caller}`);
        return this.collectEnvironment();
      }
    }
  },
  methods: {
    collectEnvironment() {
      return {
        // – The handler location configured on the function.
        _HANDLER: process.env._HANDLER, 
        // – The X-Ray tracing header.
        _X_AMZN_TRACE_ID: process.env._X_AMZN_TRACE_ID, 
        // – The AWS Region where the Lambda function is executed.
        AWS_REGION: process.env.AWS_REGION,
        //  – The runtime identifier, prefixed by AWS_Lambda_ (for example, AWS_Lambda_java8). This environment variable
        // is not defined for custom runtimes (for example, runtimes that use the provided or provided.al2 identifiers).
        AWS_EXECUTION_ENV: process.env.AWS_EXECUTION_ENV,
        //  – The name of the function.
        AWS_LAMBDA_FUNCTION_NAME: process.env.AWS_LAMBDA_FUNCTION_NAME,
        //  – The amount of memory available to the function in MB.
        AWS_LAMBDA_FUNCTION_MEMORY_SIZE: process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE,
        //  – The version of the function being executed.
        AWS_LAMBDA_FUNCTION_VERSION: process.env.AWS_LAMBDA_FUNCTION_VERSION,
        //  – The initialization type of the function, which is either on-demand or provisioned-concurrency. For 
        // information, see Configuring provisioned concurrency.
        AWS_LAMBDA_INITIALIZATION_TYPE: process.env.AWS_LAMBDA_INITIALIZATION_TYPE,
        // – The name of the Amazon CloudWatch Logs group and stream for the function.
        AWS_LAMBDA_LOG_GROUP_NAME: process.env.AWS_LAMBDA_LOG_GROUP_NAME,
        AWS_LAMBDA_LOG_STREAM_NAME: process.env.AWS_LAMBDA_LOG_STREAM_NAME,
        //  DANGER!! – The access keys obtained from the function's execution role. DANGER!!
        AWS_ACCESS_KEY: process.env.AWS_ACCESS_KEY,
        AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID,
        AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY,
        AWS_SESSION_TOKEN: process.env.AWS_SESSION_TOKEN,
        // – (Custom runtime) The host and port of the runtime API.
        AWS_LAMBDA_RUNTIME_API: process.env.AWS_LAMBDA_RUNTIME_API,
        // – The path to your Lambda function code.
        LAMBDA_TASK_ROOT: process.env.LAMBDA_TASK_ROOT,
        // – The path to runtime libraries.
        LAMBDA_RUNTIME_DIR: process.env.LAMBDA_RUNTIME_DIR,
        // – The environment's time zone (UTC). The execution environment uses NTP to synchronize the system clock.        
        TZ: process.env.TZ,
      }
    }
  }
};

let broker, service;

try {
  broker = new ServiceBroker(config);
  service = broker.createService(exampleServiceSchema);
  await broker.start(); 
} catch (error) {
  throw error;
}

// Call service.action using an unnamed function exported as a const
export const callServiceAction = async function(event, context) {
  try {
    return await broker.call('service.action', {});
  } catch (err) {
    throw err;
  }
}

// Emit an event using an arrow function exported as a const
export const emitMyEvent = async (event, context) => {
  try {
    return await broker.emit('my.event.topic', {});
  } catch (err) {
    throw err;
  }
}

// Broadcast an event using an exported, asynchronous, named function
export async function broadcastMyEvent(event, context) {
  try {
    return await broker.broadcast('my.event.topic', {});
  } catch (err) {
    throw err;
  }
}

// Call an action for the service created locally within the lambda execution
export async function callLocalServiceAction(event, context) {
  try {
    return await service.actions.getFunctionEnvironment({});
  } catch (err) {
    throw err;
  }
}

Here we have a very simple lambda function code which exposes four handlers, thus this code can be used for four different lambda functions. Each handler uses a slightly different type of function and use either the broker or the service created during initialization to communicate with the larger system.

We load Moleculer and the broker config - note, the config must be in ESM format as it cannot be loaded using require() and must use import - declare the service schema in a const, declare variables for both the broker and service, then safely and asynchronously create the broker and service. Scope is important here as we'll need to be able to reference the broker/service from our exported handlers.

We then export each handler for lambda to invoke and include calls to the broker to provide a few examples.

Theoretically, when invoked, a node should be created along with a service and when started, connect to your configured transport, then start the included service(s). Other services in the Moleculer system should be able to call the provided action and the lambda handlers should work as expected.

The node would stay connected to the system along with any service(s) running on it until the lambda is terminated. Of course, you can look into how to keep the lambda warm which should keep the node running and connected.

SQS

You also mentioned use of SQS. Given there is no transport support for SQS I can only assume you either want to trigger your lambda using SQS or consume SQS via the AWS SDK directly in your lambda function.

For details on approaching the former, start with this documentation. It's pretty straight forward and highly customizable.

For the latter, you simply need to amend the above code to import the aws-sdk, create an SQS service instance, then implement for your use case.

For example:

import { SQS } from 'aws-sdk';
const SQSClient = new SQS();
const sendMessageResponse = await SQS.sendMessage({
  MessageBody: 'example',
  // Assuming this is set in the lambda process environment...
  QueueUrl: process.env.SQS_QUEUE_URL,
}).promise();

Perhaps you want to push messages into the queue when actions are called; simply toss the above in an action handler and populate the message with the content from the ctx.

If you want the lambda to be a consumer of the queue, it's relatively straight forward to read directly from the queue using the aws-sdk, however I have had good experiences using the sqs-consumer package and recommend it.

Lastly

As I said, this is mostly just my thoughts. I have not fully tested this idea but conceptually I do believe this is accurate and ultimately possible.

Take care with how you approach this, be certain that you are doing it for the right reasons, and do research to cover your bases. There is a lot more that can be done here but as with anything in the cloud, take caution not to accidentally cause unnecessary spending.

Let me know if you have any follow-up questions, need clarification, etc. and happy coding!

[Susros]

Awesome @ccampanale . Thanks for your time explaining this. It's really helpful.

I currently don't have any system running on MoleculerJS. I am working on new project and creating a microservice in Serverless architecture. I'm exploring technologies and found MoleculerJS, and played around with it. I like the overall design of MoleculerJS. So, was wondering if this can be done in Serverless architecture by using Serverless framework to deploy to AWS lambda.

[ccampanale]

@Susros

You're welcome - it was equally as helpful for me as I had not had the chance to dump my thoughts about how I would approach this so, win-win.

Totally understand. I too am a big fan of Moleculer, the overall design, flexibility, extensibility, and simplicity so I get it. I think using the above as a template for how to approach an integration with Severless and Moleculer using AWS Lambda should certainly be doable.

Again, just be sure to consider why you are doing it. There's nothing wrong with toying around with something like this for fun and doing so is a great way to practice and learn. So if that's the goal then I would definitely say "dig in, and have fun!". However, as I said before, I would think critically about what you want to achieve and what the benefit would be. As I said in my response, Lambda Applications allow you to group Lambda Functions which can be essentially equivalent to Moleculer services where the lambda functions are the Moleculer actions and event handlers.

• Inter-function calls are trivial using the AWS SDK and properly scoped IAM permissions;
• Event coordination, subscriptions, triggers, etc. are also trivial using the AWS SDK not to mention that the Serverless framework makes quick work fo declaratively configuring these event types;
• Metrics is literally built-in to AWS Lambda and tracing is not tough to add;

Form my perspective, outside of the situation I described above about integrating an existing system with pure cloud solutions, the only other big features that Moleculer provides that I think I would miss is the REPL console (which I use both for development and operations personally). Outside of that, I think the Serverless framework is more well suited for AWS Lambda based applications.

P.S. - I got a notification this morning and realized that someone is working on an AWS SQS powered transport for Moleculer; perhaps this new transport would make this endeavor more fruitful by providing an AWS powered transport for inter-service communication. Though again, I'm not sure all of the extra Moleculer overhead is really necessary and could just add a bit of unnecessary complexity.

[ccampanale]

I forgot to mention - I could see the "mixin" support for Moleculer services being another useful feature that may be appreciated in this sort of setup. I could certainly see how it may be helpful using mixins to ease development of new services based on previously developed functionalities or the library of supported Moleculer modules.

Additionally, regarding my statement about the Moleculer REPL CLI, I do believe that could make for a very nice control plane but I don't think it would be much better than either direct use of the AWS CLI or the Serverless CLI (if you were to go that route), both of which make it pretty easy to list/invoke functions. One major difference is that technically, the AWS/Serverless CLI approaches would both benefit from AWS IAM access control, allowing you to scope who (developer/operator/etc.) could see/invoke what much easier than you could with the Moleculer REPL. (A problem my team has not needed to solve, thankfully...)