Onboard Serverless as a component

This article details out the process of using Serverless as a component within your service.

Serverless helps to deploy managed serverless services provided by AWS. For more information about serverless follow the documentation - Serverless Documentation.

Odin supports Serverless as a component and you can use Serverless to deploy any other managed services (e.g: Lambda) in Odin. However, to use the same within your service, Odin expects a certain standard.

For Stepfunction: To know about onboarding Stepfunction specifically, refer to the document - How to onboard Stepfunction as a component.

Jfrog Artifact Structure

In case of serverless, odin expects that the artifact pushed in the Jfrog artifactory is provided in a specific structure. The structure is as follow:

<Jfrog Artifact>
    └─── Serverless.zip
        └─── ServerLs <folder>   
            | main.yml //Main configuration file with respect to Serverless
            | node_modules // if its a node application
            | <Additional file 1>
            | <Additional file 2>

To create any managed service provided by AWS, Odin uses Serverless that expects a particular configuration file to be in place for creating the resource (in the above example, main.yaml). That configuration file should be written in such a way that Serverless can provision the resource. Along with the config file, if the user is using any additional file or folder to customise the resource, the same can be put in the folder within the zip file (in this case ServerLs).

Define Serverless as a component in Service Definition

While adding the Serverless as a component in the service definition, along with general details like component type, name, and version, Odin expect the following configuration details to be added. Please note that it is mandatory to include artifact name and version as part of config details for Serverless for the resource to be created.

//Sample Service Definition

{
    "name": "Service Name",
    "version": "1.0.0-SNAPSHOT",
    "team": "TeamName",
    "components":
    [
        {
        "type":"serverless",
        "version": "1.0.0",
        "name": "ServerLs", //The folder name within the Artifact zip should be same as this
        "config":{
	    "artifact_name": "Serverless", //As per the above example, Artifact name is Stepfucntion
	    "artifact_version": "1.0.0-SNAPSHOT", //The version with which artifact was pushed
	    "filename": "main.yml" //The file name, in this case main.yml
		}	
        }
    ]
}

Please note that in the above format, file name is not a mandatory field. By default, Odin would look for a file name called main.yml. However, user can use a different file name than this. In that case the file name needs to be mentioned in the config section for serverless component.

Define Provisioning file to use Serverless as a component

The provisioning details for the serverless should be provided along with the component name and deployment type. Please note that serverless being a managed service by AWS, the deployment type will always be 'aws_serverless'.

The configuration file complying with serverless is same across the environment. However, the user can customise the requirements based on the environment within the configuration file and the environment details can be passed to Odin using the provisioning file with the help of the parameter 'extra_env'. E.g: there might be difference in the provisioning requirement for serverless in prod environment and stage environment. The specific requirements can be mentioned within the configuration file [in this case, main.yml] while pushing the artifact.

// Sample Provisioning file

[
  {
    "component_name": "ServerLs",
    "deployment_type": "aws_serverless",
    "params": {
        "extra_envs": {
                    "NODE_ENV1":"stag",
                    "NODE_ENV2":"load",
		      }
		}
    }
]

The user has to specify the environment specific details in the config file created for serverless using placeholders for the extra environments. A sample structure for an artifact for a service which is using ServerLs and has custom configs for stage and load environment would be as follow:

<Jfrog Artifact>
    └─── Serverless.zip
        └─── ServerLs <folder>   
            | main.yml 
            | config/
                stag.conf
                load.conf