Getting Started

This guide walks you through installing and using the Serverless Maven Plugin in your project.

Prerequisites

  • Java 25 or later
  • Maven 3.9 or later
  • Cloud provider account (AWS, Azure, or GCP)
  • Cloud provider credentials configured

Step 1: Install the Plugin

Clone the plugin repository and install it to your local Maven repository:

git clone https://github.com/taylormadesoftware/serverless-maven-plugin.git

cd serverless-maven-plugin

mvn clean install

This installs the plugin to ~/.m2/repository/uk.co.taylor-made-software/plugin-maven/1.0.1-SNAPSHOT/

Step 2: Add Plugin to Your Project

Add the plugin to your project's pom.xml in the <build><plugins> section:

<build>

    <plugins>

        <plugin>

            <groupId>uk.co.taylor-made-software</groupId>

            <artifactId>plugin-maven</artifactId>

            <version>1.0.1-SNAPSHOT</version>

        </plugin>

    </plugins>

</build>

The plugin automatically looks for src/main/serverless/config.json. To specify custom config file paths:

<configuration>

    <configFiles>

        <configFile>${project.basedir}/src/main/serverless/config.json</configFile>

    </configFiles>

</configuration>

Configuration Options

Parameter
Required
Description
configFiles
No
List of serverless config JSON file paths. Defaults to src/main/serverless/config.json
credentialMethod
No
Credential method: env, profile, static, service-principal, service-account-key
profileName
No
AWS profile name (required when credentialMethod=profile)
provider
No
Cloud provider override: aws, azure, gcp. Defaults to value in config JSON.

Step 3: Create Configuration File

Create src/main/serverless/config.json with your serverless configuration:

{

  "name": "My Serverless Application",

  "application": "com.example.myapp",

  "provider": "aws",

  "regions": [

    {

      "region": "eu-west-2",

      "items": [

        {

          "type": "website",

          "name": "frontend",

          "providerSettings": {

            "domain": "www.example.com"

          }

        },

        {

          "type": "api-gateway",

          "name": "api",

          "providerSettings": {}

        },

        {

          "type": "database",

          "name": "main-db",

          "providerSettings": {

            "tableName": "users"

          }

        }

      ]

    }

  ]

}

Root Configuration Fields

Field
Required
Description
name
Yes
Human-readable application name
application
Yes
Reverse-domain notation identifier (e.g., com.example.myapp)
provider
Yes
Cloud provider: aws, azure, or gcp
regions
Yes
Array of region configurations
description
No
Optional application description
variables
No
Key-value pairs for variable substitution

Step 4: Validate Configuration

Validate your configuration before deploying:

mvn serverless:validate

This checks:

  • JSON syntax is valid
  • All required fields are present
  • Component types are valid
  • Links between components are valid
  • Provider-specific settings are correct

Step 5: Preview Changes

Generate a deployment plan to see what resources will be created:

mvn serverless:plan

The plan shows:

  • Resources to be created
  • Dependency order
  • Estimated costs (if available)

Step 6: Deploy

Deploy your infrastructure to the cloud:

mvn serverless:deploy

The deploy goal:

  • Provisions cloud resources in dependency order
  • Configures component links
  • Applies security policies
  • Returns resource identifiers

Step 7: Verify Deployment

Run health checks on deployed resources:

mvn serverless:verify

This verifies:

  • Resources are accessible
  • Links are working
  • Health endpoints respond

Provider notes: AWS and Azure health checks call the provider's Resource Manager to confirm the deployed resource group / resources exist. On Azure this uses azure-resourcemanager-resources for a resource-group-existence probe; deep per-service state (Function App state, Cosmos provisioning state) can be added by supplying a custom HealthProbe. On teardown, serverless:undeploy deletes the derived resource group (cascading delete of all resources) on Azure, mirroring the AWS per-resource path.

Available Maven Goals

Goal
Description
serverless:validate
Validate configuration file against schema and business rules
serverless:plan
Generate deployment plan showing what resources will be created
serverless:deploy
Provision cloud resources according to configuration
serverless:verify
Run health checks on deployed resources
serverless:undeploy
Tear down all provisioned infrastructure

Next Steps

Troubleshooting

Plugin Not Found

If Maven can't find the plugin, ensure you've installed it to your local repository:

cd serverless-maven-plugin

mvn clean install

Verify the plugin exists at:

~/.m2/repository/uk/co/taylor-made-software/plugin-maven/1.0.1-SNAPSHOT/

Wrong Group ID

The correct group ID is uk.co.taylor-made-software (with hyphens), not uk.co.taylormadesoftware:

<groupId>uk.co.taylor-made-software</groupId>

<artifactId>plugin-maven</artifactId>

Configuration Validation Errors

Run mvn serverless:validate to see detailed error messages with field paths and suggestions.

Cloud Provider Credentials

Ensure your cloud provider credentials are configured:

  • AWS: ~/.aws/credentials or environment variables
  • Azure: az login or service principal
  • GCP: gcloud auth login or service account key