Deploying an API

APIs defined with Osiris are deployed to AWS using a Maven plugin or a Gradle plugin. The plugin configuration is generated by Osiris when a project is created.

The project created by the archetype contains a build file with configuration for the Osiris plugin, as well as an example application that can be immediately deployed to AWS and demonstrates the basic use of Osiris. See getting started for more details.

The generated project also contains the configuration that defines how the application will be deployed to AWS. It is a public property named config in the file Config.kt in the core module.

Requirements for Deployment

1. An AWS account. See here
2. An AWS user with administrator permissions. See here
3. AWS user credentials. See here
4. AWS configuration file specifying the region. See here

Deploying an API

An API is deployed to AWS using the deploy goal in Maven or the deploy task in Gradle. The example application in the project created by Osiris can be immediately deployed to AWS with the following commands:

mvn deploy

or

gradle deploy

This builds the project, creates the artifacts and configuration needed for deployment and deploys the application to AWS.

Application Configuration

The application configuration contains a number of properties used when deploying the API to AWS Lambda and API Gateway. The Config.kt file generated by the Maven archetype contains settings suitable for deploying the example application. The following configuration properties can be changed to control deployment of your application:

Property	Description
applicationName	The name of the application. Used to name the CloudFormation stack and other AWS resources
applicationDescription	A brief description of the application
stages	The stages to which the API is deployed
environmentVariables	The environment variables used for configuration
lambdaTimeout	The maximum number of seconds a lambda function is allowed to run. Defaults to 10
runtime	The runtime used by the Osiris lambda function. This should not be specified unless you are using a layer that provides a custom runtime. In that case the value should be LambdaRuntime.Provided
lambdaMemorySizeMb	The memory allocated to the lambda function in MB. Defaults to 512
lambdaName	The name of the lambda function. Optional. If the name is not specified a name is generated
authConfig	Configuration of any external authorisation mechanism. See here for details. Optional
staticFilesBucket	The bucket from which static files are served. If this is not specified a bucket will be created. Optional
codeBucket	The bucket to which the application jar file is copied for deployment. If this is not specified a bucket will be created. Optional
vpcConfig	The VPC subnets and security groups to which the application code requires access
layers	The ARNs of the layers that should be used for the Osiris lambda function. This can contain any of the standard CloudFormation pseudo parameters, e.g. ${AWS::Region} and ${AWS::AccountId}.
binaryMimeTypes	The MIME types that should be treated as binary data. If you return a ByteArray from an endpoint it is converted to Base64 and returned to API Gateway. If you want the response to contain binary data then you must tell API Gateway to convert it using this property.

stages

The stages section controls three things:

• The stages to which the API is deployed
• The stage variables available to the code from the stageVariables map on the request
• Which stages the API is deployed to when it is updated

The configuration property deployOnUpdate controls whether the API is deployed to a stage when the application is redeployed. When an application is deployed for the first time it is deployed to all stages defined in the configuration.

When an existing API is redeployed, only the stages where deployOnUpdate is true are automatically deployed. Any other stages must be deployed by hand.

This allows (for example) the dev stage to be updated continuously during development without deploying changes to the prod stage until they are fully tested.

Example Application Configuration

This is an example of the application configuration created by the archetype:

val config = ApplicationConfig(
    applicationName = "my-application",
    lambdaMemorySizeMb = 512,
    lambdaTimeout = Duration.ofSeconds(10),
    stages = listOf(
        Stage(
            name = "dev",
            description = "Development stage",
            deployOnUpdate = true
        )
    ),
    vpcConfig = VpcConfig(
        subnetIds = listOf(
            "subnet123",
            "subnet245"
        ),
        securityGroupIds = listOf(
            "securityGroupABC",
            "securityGroupCDE"
        )
    )
)

Deployment Details

An application is deployed using CloudFormation. This is the AWS service that creates or updates AWS resources based on a configuration file. The Maven and Gradle plugins generate a CloudFormation YAML file that defines a single CloudFormation "stack" for the API, lambda function and other required resources.

When an API is deployed it creates or modifies the following resources in AWS:

S3 Code Bucket

This is used during deployment to hold the CloudFormation file and the jar file containing the code. This is not part of the CloudFormation stack for the application as it contains the CloudFormation definition file and therefore must exist before the stack can be created.

API Gateway API

The deployment creates or modifies an API in API Gateway. The API name is derived from the project artifactId (Maven) or name (Gradle). An endpoint is created for every route in the API definition.

Lambda Function

One lambda function is created to handle all requests from the API. Its name is derived from the project artifactId (Maven) or name (Gradle).

IAM Role

A role is created for the lambda function. This has permission to execute the lambda. If the API includes static files the role also has permission to get objects from S3. The role can also be assumed by API Gateway. This is necessary when serving static files from S3.