Configuration Reference

Configuration files are JSON documents. The default path is src/main/serverless/config.json. Multiple files can be declared in the plugin configuration and are merged in order.

Prerequisites

Java 25+
Maven 3.9+
Cloud provider credentials configured (see Credentials)

Add the Plugin

Add the plugin to your project's pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>uk.co.taylor-made-software</groupId>
      <artifactId>serverless-maven-plugin</artifactId>
      <version>1.0.1-SNAPSHOT</version>
      <configuration>
        <!-- optional: defaults to src/main/serverless/config.json -->
        <configFiles>
          <configFile>src/main/serverless/config.json</configFile>
        </configFiles>
      </configuration>
    </plugin>
  </plugins>
</build>

Create Your Configuration

Place your configuration at src/main/serverless/config.json:

{
  "name": "My Application",
  "application": "com.example.myapp",
  "provider": "aws",
  "regions": [
    {
      "region": "eu-west-2",
      "items": [
        {
          "type": "function",
          "name": "api-handler",
          "references": ["app-db"]
        },
        { "type": "database", "name": "app-db" }
      ]
    }
  ]
}

Relationships are declared inline using the references array on each component. A function referencing a database automatically creates the correct IAM permissions — no separate links section needed.

Goals

Goal	Description	Prerequisite phases run automatically
serverless:validate	Parse and validate configuration	—
serverless:plan	Diff desired state against cloud	validate
serverless:deploy	Deploy all components	validate → plan
serverless:verify	Health-check deployed components	validate → plan → deploy
serverless:undeploy	Tear down all components	validate

Each goal automatically runs any missing prerequisite phases. Running serverless:deploy on a fresh project will validate and plan first. If any phase fails the build halts immediately.

Typical Workflow

# Validate your config
mvn serverless:validate
 
# Preview what will be created/changed
mvn serverless:plan
 
# Deploy everything
mvn serverless:deploy
 
# Verify health of deployed resources
mvn serverless:verify
 
# Tear everything down
mvn serverless:undeploy

Multi-File Configuration

Split large configurations across multiple files. Files are merged in declaration order; duplicate component names across files are an error.

<configFiles>
  <configFile>src/main/serverless/base.json</configFile>
  <configFile>src/main/serverless/auth.json</configFile>
  <configFile>src/main/serverless/messaging.json</configFile>
</configFiles>

Root Fields

Field	Type	Required	Description
name	string	required	Human-readable application name. Used in documentation and logs only.
description	string	optional	Free-text description of the application.
application	string	required	Reverse-domain-notation identifier, e.g. com.example.myapp. Used to derive globally unique resource names. Must match ^[a-z][a-z0-9](\.[a-z][a-z0-9])+$.
provider	string	required	Target cloud provider. One of: aws, azure, gcp.
variables	object	optional	Key/value map for variable substitution. Values are substituted for ${variableName} placeholders anywhere in the config. Only allowed in the root config file, not in referenced files.
regions	array	required	One or more region blocks, each containing a list of components to deploy.
credentials	object	optional	Cloud provider credentials. If omitted, environment-variable defaults are used. See Credentials.

Region Block

Field	Type	Required	Description
region	string	required	Provider region identifier (e.g. eu-west-2) or global for globally-scoped resources (Authentication, Email, SMS). Variable substitution is supported.
items	array	required	List of component definitions. Each item is either an inline component object or a string path to a component JSON file.

Component Object

Field	Type	Required	Description
type	string	required	Component type (matched case-insensitively). One of: website, storage, api-gateway, function or functions (equivalent aliases for the function group), database, authentication, email, sms, event-bus, waf.
name	string	required	Unique component name within the configuration. Used to derive the globally unique cloud resource name: application.replace('.', '-') + "-" + name.
links	array	optional	Explicit component relationships. Each link is an object with sourceComponent, targetComponent, and linkType. See component type pages for valid link types. Implicit references (function names in routes, subscriptions) should NOT be added here.
type-specific fields	varies	optional	Additional configuration fields specific to each component type. See individual component pages.

Relationships are declared using the links array on each component — there is no top-level links array (a root-level links block is ignored). Each link object requires sourceComponent, targetComponent, and linkType. The linkType value is case-sensitive and must exactly match one of the enum values (e.g. FUNCTION_TO_DATABASE). A WEBSITE_TO_STORAGE link also requires a path property (e.g. "/assets") to route that URL prefix to the target storage bucket. A FUNCTION_TO_FUNCTION link grants invoke permission and injects a FUNCTION_{NAME} env var with the target function ARN. Functions may also declare a permissions array (e.g. ["storage:create", "dns:update"]) to grant access to resource types without a component link. Some references are implicit (function names in routes, subscriptions) and must NOT be added to links. The plugin validates that each link type is supported for the source and target component types.

Multiple instances of any component type are supported. You can declare two website components, two api-gateway components, two functions groups, and so on — as long as each has a unique name. This allows you to deploy separate front-ends, APIs, or function groups from a single configuration file.

Variable Substitution

Use ${variableName} in any string value. Variables are resolved from the variables map before any validation runs. Substitution is idempotent. Unresolved references are a validation error.

{
  "variables": {
    "env": "prod",
    "region_primary": "eu-west-2"
  },
  "regions": [
    {
      "region": "${region_primary}",
      "items": [
        { "type": "function", "name": "api-handler-${env}" }
      ]
    }
  ]
}

Globally Unique Resource Names

Cloud resources that must be globally unique are named using:

application.replace('.', '-') + "-" + componentName

Example: application = com.example.myapp, name = assets → com-example-myapp-assets

The validator checks this derived name against provider-specific length and character constraints and reports an error if it would be invalid.

File References

Items in a region's items array can be a string path to a JSON file containing a single component definition. This allows splitting large configurations.

{
  "regions": [
    {
      "region": "eu-west-2",
      "items": [
        "components/api-handler.json",
        "components/app-db.json",
        { "type": "website", "name": "frontend" }
      ]
    }
  ]
}

File references are only allowed at the items array level. You cannot use a file path inside a component's property object. The variables block is only allowed in the root config file, not in referenced files.

Full Example

{
  "name": "Test Application",
  "description": "A sample project demonstrating all component types",
  "application": "com.sample.testapplication",
  "provider": "aws",
  "variables": {
    "env": "prod",
    "region_primary": "eu-west-2"
  },
  "regions": [
    {
      "region": "global",
      "items": [
        {
          "type": "authentication",
          "name": "user-auth",
          "providerSettings": {
            "loginProviders": ["email"],
            "groups": [
              { "name": "admin", "description": "Administrators" }
            ]
          },
          "links": [
            { "sourceComponent": "user-auth", "targetComponent": "transactional-email", "linkType": "AUTHENTICATION_TO_EMAIL" },
            { "sourceComponent": "user-auth", "targetComponent": "notification-sms", "linkType": "AUTHENTICATION_TO_SMS" }
          ]
        },
        { "type": "email", "name": "transactional-email", "providerSettings": { "fromAddress": "noreply@example.com" }, "links": [] },
        { "type": "sms",   "name": "notification-sms", "providerSettings": {}, "links": [] }
      ]
    },
    {
      "region": "${region_primary}",
      "items": [
        { "type": "database", "name": "app-db" },
        {
          "type": "storage",
          "name": "deploy-artifacts",
          "versioning": true
        },
        {
          "type": "functions",
          "name": "app-functions",
          "codeStorage": "deploy-artifacts",
          "codePath": "releases/app-functions/app-functions-1.0.0.jar",
          "functions": [
            {
              "name": "api-handler",
              "handler": "com.example.ApiHandler::handleRequest",
              "references": ["app-db", "transactional-email", "notification-sms", "domain-events"]
            },
            {
              "name": "event-processor",
              "handler": "com.example.EventProcessor::handleRequest"
            }
          ]
        },
        {
          "type": "api-gateway",
          "name": "main-api",
          "domain": "api.example.com",
          "routes": [
            { "method": "ANY", "path": "/api/{proxy+}", "function": "api-handler", "auth": "user-auth" }
          ]
        },
        {
          "type": "website",
          "name": "frontend",
          "domain": "www.example.com",
          "indexDocument": "index.html",
          "errorDocument": "index.html",
          "httpsOnly": true,
          "references": ["main-api"]
        },
        {
          "type": "event-bus",
          "name": "domain-events",
          "subscriptions": [
            { "eventType": "order.created", "function": "event-processor" }
          ]
        }
      ]
    }
  ]
}