Introduction

Coworks is a unified serverless microservices framework based on AWS technologies.

Each atomic microservice (defined as class TechMicroService) is a simple python class deployed as a serverless AWS Lambda, and composition of microservices (defined as class BizMicroService) is performed over the AWS Step Function product.

Other AWS technologies are used for logging, administration, …

Technical documentation :

• Get started: Installation.
• Quick overview: TechMS Quickstart then BizMS Quickstart.
• The Command Line Interface CWS : Command Line Interface.
• Full documentation: Documentation.
• At least FAQ if not enough…

Using and derived from Chalice. Other tools used:

• Click - Command Line Interface Creation Kit.
• Terraform - Infrastructure Configuration Management Tool.

What does microservice mean in Coworks?

In short, the microservice architectural style is an approach to developing a single application as a suite of small services, each running in its own process and communicating with lightweight mechanisms.

In Microservice Architecture (Aligning Principles, Practices, and Culture), authors M. Amundsen, I. Nadareishvili, R. Mitra, and M. McLarty add detail to the definition by outlining traits microservice applications share:

• Small in size
• Messaging enabled
• Bounded by contexts
• Autonomously developed
• Independently deployable
• Decentralized
• Built and released with automated processes

In Coworks, microservices are serverless services over APIs.

Small in size

Simply implemented as a python class.

Messaging enabled

API Gateway request-response managed services.

Service oriented

Technological service on Lambda and Functional service over Step Function.

Independently deployable

All needed deployment information defined in the python class.

Decentralized

Serverless components.

Smart endpoints

Deriving directly from class methods.

What are Coworks main benefits?

Two levels of microservice

Coworks microservices are divided in two categories :

Small technical microservice

Implemented as a simple AWS Lambda function, this kind of microservice is dedicated to technical operations over a specific service.

Functional business microservice

Implemented over AWS Step Function, this kind of microservice allows non programmer to construct functional business workflows.

Distinction between TechMicroservice and BizMicroservice is based not only on granularity size but also:

• A TechMicroservice should only be used as receivers of orders coming from BizMicroservices.
• A BizMicroservice represents a logical workflow of actions while a MicroService represents a simple concrete action.
• A TechMicroservice is an independant microservice while a BizMicroservice is connected to event handlers (cron, notification, event, …).
• A TechMicroservice is more a handler pattern and BizMicroservice a reactor pattern.

Code oriented tools

Like any model of software architecture, it is very usefull to have complementary tools for programming, testing, documenting or deploying over it.

The main advantage of using Coworks is its ability to defined those tools, called commands, directly in the microservice code. Predefined commands like run or deploy are provided, but you can redefined them or creates new ones like for documentation or testing.

For more details, see: Commands.

Microservice architecture structuration

The Coworks microservice architecture provides some best pratices for code organization and directory structure. Indeed it’s so easy to start in serverless project, it’s also easy to start moving the wrong direction.

API and Lambda organization

With AWS API a single Lambda function handles a single HTTP verb/path combinaison. For Rest API it is better to have a single lambda function to handle all HTTP verbs for a particular resource.

Coworks regroups all microservice entrypoints into one single class. And a class is the resource granularity for the API.

For example, following the CRUD design :

The significant benefit of this architecture is that the number of Lambda functions is drastically reduced over a one to one CRUD event mapping.

Configuration

Coworks differenciates two kind of configurations:

• Automation and command configuraton
• Execution configuration

For those who are familiar with the Twelve-Factor App methodology, the Coworks configuration model correspond exactly with the strict separation of config from code. More precisely:

• The project configuration file : Use a declarative format for setup automation, to minimize time and cost for new developers joining the project
• The environmant variables file : Env vars are easy to change between deploys without changing any code

Documentation

Contents:

• Installation
  • Python Version
  • Install Coworks
  • Other tools
• TechMS Quickstart
  • First try
  • Deploy the try
  • Full project
  • Commands
• TechMS
  • Routing
  • Entrypoint Parameters
  • Microservice Response
  • Authorizer
  • Blueprints
• Commands
  • CWS : Command Line Interface
  • Predefined Coworks Commands
  • Defining a new command
  • Project configuration file
  • Testing
• Configuration
  • Layers
  • CORS
  • Authorization
  • Deploy vs update
  • Stages
• Context Manager
  • XRay
• BizMS Quickstart
  • Deployment
• BizMS
  • YAML Description
• Developer Interface
  • Microservices
  • Configuration
• FAQ
  • Is Coworks …
• Contributing
• Changelogs
  • Version 0.4
  • Version 0.3
  • Version 0.2
  • Version 0.1

Taking part in the project

If you want to contribute to this project in any kind, your help will be very welcome. Don’t hesitate to contact any project’s member.

Indices and tables

• Index
• Module Index
• Search Page