Merge pull request #797 from serverless/compose-multiframework-docs

docs(compose): update docs

Author: eahefnawy

compose-multiframework/README.md

@@ -0,0 +1,25 @@
+# Serverless Framework Compose: Multiframework Deployment
+
+Deploying multiple services in a monorepository is a common pattern in larger teams. Serverless Framework Compose simplifies the deployment and orchestration of these services by offering:
+
+1. Parallel deployment of multiple services
+2. Ordered deployment of services
+3. Support for deploying different types of services (e.g., Traditional, SAM, CloudFormation) together
+4. Sharing outputs between services
+5. Running commands across multiple services
+
+In this example, we demonstrate how to use Serverless Compose to deploy three types of services together:
+
+1. AWS CloudFormation Service: Deploys shared resources with outputs that are referenced by the other services.
+2. Serverless Framework Traditional Service
+3. AWS SAM Template Service
+
+The AWS CloudFormation service is deployed first to create shared resources, followed by the parallel deployment of the Traditional and AWS SAM services.
+
+This example also illustrates how to use Serverless Variables with Serverless Compose for organizing and structuring your application, as well as managing different stages.
+
+For more information about Serverless Compose, please see the [Serverless Compose docs](https://www.serverless.com/framework/docs/guides/compose)
+
+For more information about using AWS SAM and or AWS CloudFormation templates with the Serverless Framework, please see the [AWS SAM/CFN docs](https://www.serverless.com/framework/docs/guides/sam)
+
+For more information about Serverless Variables, please see the [Serverless Variables docs](https://www.serverless.com/framework/docs/guides/variables)

compose-multiframework/cloudformation-compose-service/template.yml

@@ -0,0 +1,27 @@
+# This is a shared CloudFormation service that is being referenced by the traditional and SAM services.
+# This is a good place to put shared resources like DynamoDB tables, S3 buckets, etc.
+# that will be used by other services.
+
+AWSTemplateFormatVersion: "2010-09-09"
+
+Resources:
+  SharedTable:
+    Type: "AWS::DynamoDB::Table"
+    Properties:
+      # We are using the parameter passed down from Serverless Compose, and the current stage.
+      # To construct the final table name.
+      TableName: ${param:tableNamePrefix}-${sls:stage}
+      AttributeDefinitions:
+        - AttributeName: "Id"
+          AttributeType: "S"
+      KeySchema:
+        - AttributeName: "Id"
+          KeyType: "HASH"
+      ProvisionedThroughput:
+        ReadCapacityUnits: 5
+        WriteCapacityUnits: 5
+
+# We are outputting the table name so that other services can reference it.
+Outputs:
+  TableName:
+    Value: !Ref SharedTable

compose-multiframework/cloudformation/template.yml

@@ -0,0 +1,7 @@
+exports.handler = async (event) => {
+  return {
+    service: "sam",
+    tableName: process.env.TABLE_NAME,
+    domain: process.env.DOMAIN,
+  };
+};

compose-multiframework/sam-compose-service/handler.js

@@ -1,9 +1,5 @@
 AWSTemplateFormatVersion: "2010-09-09"
 Transform: AWS::Serverless-2016-10-31
-Description: >
-  sam-app
-
-  Sample SAM Template for sam-app
 
 Globals:
   Function:
@@ -18,8 +14,10 @@ Resources:
       Runtime: nodejs20.x
       Environment:
         Variables:
+          # We are using the output of the shared resources CloudFormation template
+          # that is passed down from Serverless Compose, and the staged param "domain".
           TABLE_NAME: ${param:tableName}
-          STAGE_LABEL: ${param:stageLabel}
+          DOMAIN: ${param:domain}
       Architectures:
         - x86_64
       Events:

compose-multiframework/sam/handler.js

@@ -1,31 +1,45 @@
-# This example shows how to use Serverless Compose
-# to compose 3 services together:
-#   - A CloudFormation service
-#   - A traditional Serverless Framework service
-#   - A SAM service
-# It specifically shows how to pass parameters between services
-# and how to reference outputs from one service in another service.
+# Serverless Framework can deploy multiple types of templates:
+#   1) Traditional Serverless Framework templates
+#   2) AWS Cloudformation Templates
+#   3) AWS SAM Templates.
+# This is useful if your organization is using these different templates and wants one tool to standardize around.
+# Here, we use Serverless Framework Compose (serverless.com/framework/docs/guides/compose) to deploy three different template types in a single deploy command.
+# Deployments happen in parallel by default. You can also share outputs from one Service to another, across template types.
+# In this case, Compose will auto-determine the correct order to deploy each Service.
 
 stages:
   default:
     params:
-      stageLabel: "testing"
+      domain: "serverless.dev"
   prod:
     params:
-      stageLabel: "production"
+      domain: "serverless.com"
 
 services:
-  cloudformation-compose-service:
-    path: cloudformation-compose-service
+  # Framework: AWS CloudFormation
+  # The service name here will be used as the underlying cloudformation stack name.
+  # Make sure it’s unique so it doesn’t collide, and accidently update another stack.
+  # If you change it, make sure you update the references in other services.
+  shared-resources-example:
+    path: cloudformation
     params:
-      tableNamePrefix: compose-shared-table
+      # We are passing a simple string parameter to the CloudFormation template.
+      # If you open the template file, you will see that we reference it with ${param:tableNamePrefix}
+      tableNamePrefix: shared-table
 
-  traditional-compose-service:
-    path: traditional-compose-service
+  # Framework: Serverless Framework Traditional
+  traditional:
+    path: traditional
     params:
-      tableName: ${cloudformation-compose-service.TableName}
+      # We are passing a reference to the shared CloudFormation stack output to the traditional service.
+      # The shared CloudFormation stack is deployed first, and the output is passed to this service.
+      tableName: ${shared-resources-example.TableName}
 
-  sam-compose-service:
-    path: sam-compose-service
+  # Framework: AWS SAM
+  sam:
+    path: sam
     params:
-      tableName: ${cloudformation-compose-service.TableName}
+      # We do the same here, passing the shared CloudFormation stack output to the SAM service.
+      # Both the traditional and SAM services will be deployed in parallel.
+      # As they both depend on the same shared service.
+      tableName: ${shared-resources-example.TableName}

compose-multiframework/sam-compose-service/samconfig.toml renamed to compose-multiframework/sam/samconfig.toml

@@ -0,0 +1,7 @@
+exports.handler = async (event) => {
+  return {
+    service: "traditional",
+    tableName: process.env.TABLE_NAME,
+    domain: process.env.DOMAIN,
+  };
+};

compose-multiframework/sam-compose-service/template.yml renamed to compose-multiframework/sam/template.yml

@@ -1,4 +1,4 @@
-service: traditional-compose-service
+service: traditional
 
 provider:
   name: aws
@@ -12,5 +12,7 @@ functions:
           path: /
           method: get
     environment:
+      # We are using the output of the shared resources CloudFormation template
+      # that is passed down from Serverless Compose, and the staged param "domain".
       TABLE_NAME: ${param:tableName}
-      STAGE_LABEL: ${param:stageLabel}
+      DOMAIN: ${param:domain}