AWS SAM для управления Lambda-функциями

Быстрые ссылки

• Проблема
• Как написать SAM-файл
• Развёртывание SAM-файла

Проблема

Если вы знакомитесь с AWS и Lambda, вы, вероятно, видели встроенный веб-редактор функции:

Веб-редактор удобен для обучения и быстрых правок, но он не предназначен для управления production-приложениями. При масштабировании микросервисной архитектуры с десятками и сотнями функций ручное редактирование становится источником ошибок, несогласованности и отсутствия версионирования.

Решение — использовать AWS Serverless Application Model, сокращённо SAM. SAM позволяет описать всю серверлесс-приложение в виде YAML-шаблона и управлять обновлениями через инфраструктуру как код.

SAM облегчает перенос Lambda-функций в систему контроля версий и CI/CD. Вместо ручных изменений вы храните шаблон рядом с кодом, а при пуше в репозиторий CI запускает упаковку и деплой через SAM. Это даёт воспроизводимость, откат при ошибках и возможность плавного переключения трафика между версиями.

Важно: SAM — расширение CloudFormation. Он использует многие одни и те же конструкции, но специализирован для Lambda и связанных сервисов.

Что такое SAM и зачем он нужен

Коротко: SAM — это набор ресурсных типов и синтаксических сокращений поверх CloudFormation, плюс CLI-инструменты для локальной разработки и деплоя.

Определение: SAM-файл — простой YAML-файл, в котором вы описываете ресурсы приложения: функции, API, очереди, таблицы, разрешения и т.д.

Преимущества использования SAM:

• Версионирование инфраструктуры в Git.
• Автоматические обновления через CloudFormation стек.
• Интеграция с CI/CD для автоматизированного выпуска.
• Поддержка создания API Gateway, SQS, DynamoDB, EventBridge и других триггеров.
• Встроенные средства локального тестирования и отладки через sam local.

Когда SAM не подходит:

• Очень простые, одноразовые скрипты, где overhead по инфраструктуре не окупается.
• Если вы используете альтернативные инструменты IaC с готовыми модулями (например, Terraform) и не хотите смешивать подходы.

Как написать SAM-файл

Ниже базовый скелет SAM-шаблона. Сохраняйте файл как template.yml в корне проекта рядом с кодом функций.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Простое серверлесс-приложение с одной функцией
Resources:
  HelloWorld:
    Type: AWS::Serverless::Function
    Properties:
      Handler: HelloWorld/index.handler
      Runtime: nodejs12.x
      CodeUri: HelloWorld/
      Events:
        HelloWorldApi:
          Type: Api
          Properties:
            Path: /helloworld
            Method: GET

Пояснения к структуре:

• AWSTemplateFormatVersion: версия формата CloudFormation, обычно ‘2010-09-09’.
• Transform: обязателен для SAM-шаблонов, показывает, что это SAM.
• Resources: стандартный раздел CloudFormation, где объявляются ресурсы.
• Type: AWS::Serverless::Function — сокращённый тип SAM для Lambda.
• Properties: здесь указываются handler, runtime, CodeUri, переменные окружения, таймаут, память и другие параметры.
• Events: определяет источники событий, например Api, S3, Schedule, DynamoDB, SQS и т.д.

Пример с ресурсом разрешения для API Gateway:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
  HelloWorld:
    Type: AWS::Serverless::Function
    Properties:
      Handler: HelloWorld/index.handler
      Runtime: nodejs12.x
      CodeUri: HelloWorld/
  HelloWorldPermission:
    Type: AWS::Lambda::Permission
    Properties:
      Action: lambda:InvokeFunction
      FunctionName:
        Fn::GetAtt:
          - HelloWorld
          - Arn
      Principal: apigateway.amazonaws.com
      SourceArn:
        Fn::Sub: arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:*/*/*/*

Здесь Fn::GetAtt возвращает ARN функции, а Fn::Sub подставляет регион и идентификатор аккаунта. Такие встроенные функции CloudFormation полезны, когда точный ARN заранее неизвестен.

Советы по структуре шаблона:

• Разбивайте большой шаблон на отдельные файлы и используйте CloudFormation nested stacks или SAM Serverless Application Repository, если проект масштабируется.
• Храните CodeUri для каждой функции рядом с её исходниками.
• Определяйте отдельные IAM роли, если функции требуют разных прав.

Deploying SAM — развёртывание шаблона

Для деплоя SAM используется sam cli, отдельный от aws cli. Установка через pip:

pip install aws-sam-cli

Основные шаги локального ручного деплоя:

1. Упаковать артефакты и загрузить в S3.

sam package \
  --template-file template.yml \
  --output-template-file packaged.yml \
  --s3-bucket bucket-name

2. Развернуть стек CloudFormation на основе упакованного шаблона.

sam deploy \
  --template-file packaged.yml \
  --stack-name sam-hello-world \
  --capabilities CAPABILITY_IAM

Полезная опция для первого деплоя — флаг –guided. Он проведёт через настройку параметров и сохранит конфигурацию в samconfig.toml.

Примечания:

• Имя стека задаётся при запуске sam deploy; шаблон не содержит фиксированного имени стека. Смена имени создаст новый стек, одинаковое имя обновит существующий.
• Для CI/CD вы обычно выполняете этапы package и deploy автоматически в pipeline.

Интеграция с CI/CD

Типичный pipeline для SAM-приложения:

1. Коммит в ветку репозитория.
2. Сборка артефактов (установка зависимостей, тесты, сборка архива или образа).
3. sam package с загрузкой артефактов в S3 или ECR (для контейнерных Lambda).
4. sam deploy или cloudformation deploy для обновления стека.
5. Канареечный или пошаговый rollout с использованием версий и алиасов.

Варианты инструментария:

• AWS CodePipeline + CodeBuild — нативный вариант.
• GitHub Actions / GitLab CI / Jenkins — универсальные CI.
• Использование feature-стеков для тестирования перед слиянием.

Лучшие практики:

• Храните секреты в Secrets Manager или Parameter Store, не в шаблонах.
• Автоматизируйте тестирование (юнит, интеграция) перед деплоем.
• Используйте stages (dev/staging/prod) с разными параметрами и, при необходимости, разными S3-бакетами.

Плейбук: ручной деплой и проверка

Шаги для безопасного ручного релиза с SAM:

1. Убедиться в прохождении тестов на локальной машине или в CI.
2. Обновить шаблон template.yml и зафиксировать изменения в Git.
3. Выполнить sam package с корректным bucket-name.
4. Выполнить sam deploy –guided один раз, чтобы сохранить параметры, или sam deploy с явными флагами.
5. Проверить состояние CloudFormation стека в консоли или через aws cloudformation describe-stacks.
6. Протестировать основные маршруты API и критичные сценарии.
7. При проблемах — откат через CloudFormation rollback или восстановление предыдущего шаблона и повторный деплой.

Критерии приёмки

• Все функции успешно развернуты без ошибок в CloudFormation.
• API доступно по ожидаемым путям и методам.
• Логи функций (CloudWatch) показывают успешный запуск при тестовом запросе.
• IAM-права ограничены минимумом необходимых действий.
• Конфигурация зафиксирована в репозитории и изменения проходят через CI.

Рекомендации по безопасности

• Принцип наименьших привилегий: создавайте минимальные роли для функций и избегайте привилегированных ролей типа Administrator.
• Храните секреты в AWS Secrets Manager или Parameter Store и получайте их динамически из функций.
• Шифруйте переменные окружения через KMS, если они содержат чувствительные данные.
• Ограничивайте SourceArn для Lambda::Permission, чтобы API Gateway не мог вызывать функцию извне ожидаемых источников.
• Устанавливайте приемлемые таймауты и память, чтобы минимизировать риск DoS через долгие выполнения.

Отладка и типичные ошибки

• Ошибка при package: проверьте, что CodeUri указывает на существующую директорию или архив, и что у аккаунта есть права на запись в S3.
• Ошибка при deploy с CAPABILITY_IAM: убедитесь, что флаг указан, если шаблон создаёт IAM-роли.
• «Access denied» при вызове функции: проверьте роль функции и разрешения вызывающего сервиса.
• Неправильные пути API: проверьте раздел Events в шаблоне и соответствие пути и метода.

Плейбук инцидента: быстрый откат

1. Откат через CloudFormation: в консоли CloudFormation выберите предыдущую успешную версию шаблона и выполните восстановление.
2. Если стек обновлялся, можно сменить алиас на предыдущую версию Lambda для мгновенного переключения трафика.
3. При использовании Canary deployments — отмените rollout или переключите алиас обратно.
4. Просмотрите логирование и метрики CloudWatch, чтобы идентифицировать причину.
5. После исправления проведите тестовый запуск в staging перед повторным выкатом в production.

Модели принятия решений и альтернативы

Когда выбирать SAM:

• Вы хотите использовать CloudFormation и не вводить новую технологию IaC.
• Нужно гладко интегрировать Lambda, API Gateway и другие AWS-ресурсы.

Альтернативы:

• Terraform — популярный кросс-провайдерный инструмент IaC; хорошо для мультиоблачных сред.
• Serverless Framework — богат плагинами и удобен для быстрого старта, поддерживает провайдеры помимо AWS.
• CDK — инфраструктура на языке программирования (TypeScript, Python и т.д.), генерирует CloudFormation. Подходит тем, кто предпочитает код к декларации.

Ментальные модели:

• SAM = декларация инфраструктуры для serverless + утилиты для локальной разработки и деплоя.
• CloudFormation = движок, который применяет изменения; SAM генерирует удобный шаблон для этого движка.

Контроль качества: тесты и приёмка

Тесты, которые стоит автоматизировать:

• Юнит-тесты функции.
• Интеграционные тесты, которые запускают функцию через локальный emulate sam local invoke или через тестовые endpoints в staging.
• Smoke-тесты после деплоя, проверяющие базовую работоспособность API и основных сценариев.

Критерии приёмки для релиза описаны выше — обязательно автоматизируйте как минимум smoke-тесты в CI.

Глоссарий

• SAM: Serverless Application Model, упрощённый надстройка CloudFormation для Lambda.
• CodeUri: путь к исходникам функции в шаблоне.
• Fn::GetAtt, Fn::Sub: встроенные функции CloudFormation для получения атрибутов и подстановок.
• Alias: объект Lambda, позволяющий направлять трафик на определённую версию функции.

Советы по миграции и совместимости

• При переходе с устаревшего runtime обновляйте Runtime в шаблоне и тестируйте зависимости.
• Для большого количества функций рассматривайте разбивку на несколько шаблонов и nested stacks.
• Если используете Terraform, можно постепенно переводить части инфраструктуры на SAM/CloudFormation, но избегайте конфликта управления одним и тем же ресурсом из двух инструментов.

Итог

SAM превращает хаотичное ручное управление Lambda в управляемую, версионируемую и автоматизируемую практику. Для production-приложений использование SAM принято как хорошая практика: шаблон в репозитории, упаковка артефактов, проверка в CI и безопасный деплой через CloudFormation.

Важные заметки:

• Не храните секреты в шаблоне.
• Настраивайте минимальные IAM-права.
• Автоматизируйте тесты и используйте staged deploys.

Краткий чеклист перед деплоем:

• Есть проходящие тесты.
• Обновлён template.yml в репозитории.
• CodeUri указывает на корректные директории/архивы.
• S3-бакет доступен для загрузки артефактов.
• Проверены IAM-правила и роль функции.

Итоговая рекомендация: начните с небольшого SAM-шаблона для одной функции, автоматизируйте package и deploy в CI, и постепенно расширяйте шаблон по мере роста приложения.