Configuration Guide

Required Variables

These are the essential variables you need to configure when using sls.tf:

module "serverless" {
  source = "./modules/sls.tf"

  # Required: Path to your serverless configuration
  config_path = "${path.root}/serverless.yml"
}

Optional Variables

Customize your deployment with these optional configuration options:

module "serverless" {
  source = "./modules/sls.tf"

  # Basic configuration
  config_path   = "${path.root}/serverless.yml"
  config_format = "yaml"   # yaml | typescript | sam

  # Override the deployment stage (default: from serverless.yml)
  stage_override = "production"

  # Override AWS region (default: from serverless.yml)
  aws_region = "us-east-1"

  # Lambda code source
  lambda_code_path = "."

  # Restrict which resource types from the resources: section get created
  # null (default) = create all supported types
  resource_types = ["AWS::Serverless::Function", "AWS::DynamoDB::Table"]

  # Custom domain support
  enable_custom_domain = true
  acm_certificate_arn  = "arn:aws:acm:us-east-1:123456789:certificate/12345"

  # Environment variables for ${env:VAR} resolution
  environment_vars = {
    DATABASE_URL = "postgres://..."
  }

  # Variable resolution behaviour
  strict_variable_resolution = true
  max_variable_depth         = 10
}

Configuration File Options

sls.tf supports YAML, TypeScript, and AWS SAM configuration files:

service: my-api
provider:
  name: aws
  runtime: nodejs18.x
  region: us-east-1
  stage: production
  environment:
    NODE_ENV: production
    DATABASE_URL: ${ssm:/my-app/database-url}

functions:
  api:
    handler: dist/index.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY
    environment:
      FUNCTION_NAME: api

import type { AWS } from '@serverless/typescript';

const serverlessConfiguration: AWS = {
  service: 'my-api',
  frameworkVersion: '3',
  provider: {
    name: 'aws',
    runtime: 'nodejs18.x',
    region: 'us-east-1',
    stage: 'production',
    environment: {
      NODE_ENV: 'production',
      DATABASE_URL: process.env.DATABASE_URL
    }
  },
  functions: {
    api: {
      handler: 'dist/index.handler',
      events: [
        {
          http: {
            path: '/{proxy+}',
            method: 'any'
          }
        }
      ]
    }
  }
};

export default serverlessConfiguration;

Variable Resolution

sls.tf automatically resolves variables in your serverless configuration:

# Environment variables
DATABASE_URL: ${env:DATABASE_URL}

# AWS Systems Manager Parameter Store
API_KEY: ${ssm:/my-app/api-key~true}

# AWS Secrets Manager
DB_PASSWORD: ${secretsmanager:my-app-db-password}

# File references
PRIVATE_KEY: ${file(./keys/private.key)}

# Other function references
BUCKET_NAME: ${cf:stack-name.OutputBucketName}

# Self references
FUNCTION_NAME: ${self:service}-${self:provider.stage}

S3-Based Lambda Packages

For CI/CD pipelines where artefacts are built once and promoted between environments:

module "serverless" {
  source      = "./modules/sls.tf"
  config_path = "${path.root}/serverless.yml"

  lambda_code_source = {
    type       = "s3"
    bucket     = "my-artefact-bucket"
    key_prefix = "releases/my-api"
    sha        = var.deploy_sha   # passed in from CI
  }
}

Best Practices

Follow these best practices for optimal configuration:

• Use environment-specific stages: Separate configurations for dev, staging, and production
• Secure secrets: Use AWS Systems Manager Parameter Store or Secrets Manager for sensitive data
• Resource naming: Use consistent naming conventions with resource prefixes
• Tagging: Apply comprehensive tags for cost allocation and resource management
• IAM permissions: Follow the principle of least privilege for IAM roles
• Monitoring: Enable CloudWatch logging and X-Ray tracing for observability

Troubleshooting

Common configuration issues and solutions:

• Variable resolution errors: Ensure all referenced variables exist and are accessible
• Permission errors: Verify IAM roles have sufficient permissions for all resources
• Resource limits: Check AWS service limits for your region
• Invalid syntax: Validate your serverless.yml syntax before deployment