Развёртывание статического сайта в Amazon S3 через CodePipeline и CodeBuild

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

• Как это работает?
• Настройка пайплайна

Как это работает

Хостинг статического сайта в S3 — распространённая практика: дешёво, без серверов, подходит для клиентских SPA (React, Vue и т.п.). Обновления можно делать вручную через aws s3 sync или добавлением объектов в бакет. Но ручной процесс легко автоматизировать.

Архитектура, которую мы настраиваем здесь:

• Источник: Git-репозиторий (CodeCommit, GitHub, Bitbucket).
• CodePipeline: следит за изменениями в источнике и запускает пайплайн.
• CodeBuild: выполняет сборку проекта (npm run build) и в post_build синхронизирует артефакты в S3.

Если у вас нет шага сборки (чисто статические файлы в репозитории), можно пропустить CodeBuild и использовать встроенный action “AWS S3” в CodePipeline для синхронизации содержимого.

Важные моменты одним предложением:

• buildspec.yml управляет командами CodeBuild.
• Роль сервиса CodeBuild должна иметь права на запись в деплойный бакет.
• При ошибке сборки пайплайн остановится, и S3 не обновится.

Когда такой подход подходит, а когда нет

• Подходит: SPA или статические сайты, где сборка генерирует production-артефакты (минификация, бандлинг).
• Не подходит: динамические серверные приложения (нужно использовать ECS, Lambda, Elastic Beanstalk и т.д.).
• Альтернатива: использовать GitHub Actions или внешние CI для тех, кто не хочет привязываться к AWS.

Настройка пайплайна — пошагово

1. В консоли CodePipeline нажмите “Create New Pipeline”, укажите имя и создайте новую роль сервиса.

2. На шаге Source выберите репозиторий и ветку. CodeCommit интегрируется напрямую; для GitHub/Bitbucket потребуется подключение. GitLab не поддерживается напрямую.

3. Для шага Build выберите CodeBuild и создайте новый проект сборки.

4. В диалоге создания проекта CodeBuild будет автоматически выбран источник от CodePipeline. Настройте среду выполнения: OS, образ (managed image), runtime. Создайте новую роль сервиса для CodeBuild — её нужно будет расширить правами на доступ к S3.

5. Для конфигурации сборки выберите использование buildspec файла.

6. Создайте в корне репозитория файл buildspec.yml. Пример для проекта на Node.js (npm):

version: 0.2
phases:
  install:
    runtime-versions:
      nodejs: 10
    commands:
      - npm i npm@latest -g
  pre_build:
    commands:
      - npm install
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - aws s3 sync ./build s3://bucket-name

Этот buildspec выполняет сборку и на этапе post_build запускает aws s3 sync, чтобы синхронизировать локальную папку ./build с указанным бакетом.

7. Нажмите Create на проекте CodeBuild — вы вернётесь в CodePipeline. На странице пайплайна можете выбрать пропуск встроенной стадии Deploy, если CodeBuild сам делает aws s3 sync.

8. Первый запуск, скорее всего, упадёт — роль CodeBuild не имеет прав на S3 по умолчанию. Перейдите в IAM → Roles, найдите роль CodeBuild и прикрепите политику с доступом к бакету (желательно ограничить только деплойный бакет).

Пример минимальной политики (замените bucket-name):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::bucket-name",
        "arn:aws:s3:::bucket-name/*"
      ]
    }
  ]
}

9. Вернитесь в CodePipeline и нажмите “Release Change” для ручного запуска. Если buildspec корректен и права настроены — пайплайн завершится успешно и сайт обновится.

10. При последующих коммитах пайплайн автоматически запустится и обновит содержимое бакета, если сборка пройдёт успешно.

Отладка и логирование

• Если пайплайн падает, откройте CodeBuild в консоли и посмотрите логи последней сборки — там будут stdout/stderr и ошибки npm.
• Частые проблемы: неправильный путь в aws s3 sync (не ./build), отсутствие aws-cli в образе, неверные права IAM, устаревший nodejs runtime.

Советы:

• В локальном окружении выполните npm run build и aws s3 sync локально, чтобы проверить процесс до настройки CI.
• В buildspec добавляйте echo и set -e для лучшей диагностики.

План действий при неудачном деплое (runbook)

1. Остановите пайплайн (если нужно).
2. Просмотрите логи сборки в CodeBuild.
3. Если проблема — в сборке (npm/webpack), откатите код в репозитории на предыдущую рабочую версию и запустите пайплайн.
4. Если нужно быстро вернуть рабочую версию: используйте S3 Versioning или храните сборки в префиксах (releases/vX) и сделайте aws s3 sync из предыдущей директории.
5. Проверить права IAM и временные токены.
6. После фиксирования — запустить пайплайн вручную и проверить CloudFront (если есть) на необходимость invalidation.

Важно: включите версионирование бакета S3 для безопасного отката и аудита изменений.

Контроль доступа и безопасность

• Дайте роли CodeBuild минимально необходимые права (принцип least privilege).
• При использовании CloudFront добавьте инвалидацию после деплоя если требуется немедленное обновление кеша.
• Не храните секреты в buildspec.yml: используйте Parameter Store или Secrets Manager и передавайте через переменные окружения CodeBuild.

Чек-листы по ролям

Разработчик:

• Убедиться, что npm run build локально создаёт корректный ./build.
• Добавить/обновить buildspec.yml в корень репозитория.
• Прописать корректные пути статических ассетов.

DevOps:

• Создать/настроить CodePipeline и CodeBuild.
• Настроить роли IAM с минимальными правами на S3.
• Включить версионирование S3 и настроить CloudFront invalidation при необходимости.

Security:

• Проверить политики IAM на избыточные права.
• Убедиться, что секреты хранятся в AWS KMS/Secrets Manager.
• Настроить аудит S3 и логирование доступа.

Шаблон проверки перед релизом

• npm run build проходит локально без ошибок.
• buildspec.yml присутствует и корректен.
• Роль CodeBuild имеет права на s3:PutObject и s3:ListBucket для нужного бакета.
• Включено версионирование бакета (рекомендуется).
• Если используется CloudFront — настроена инвалидация.

Полезные сниппеты и подсказки

• Запуск синхронизации из локальной директории:

aws s3 sync ./build s3://bucket-name --delete

(–delete удаляет файлы в бакете, которых больше нет в ./build — полезно, но осторожно.)

• Проверка прав роли (локальная команда для диагностики):

aws sts get-caller-identity
aws s3 ls s3://bucket-name

• Пример переменных окружения в CodeBuild: NODE_ENV=production

Решение: нужен ли шаг сборки?

flowchart TD
  A[Есть сборка 'npm run build'?] -->|Да| B[Использовать CodeBuild]
  A -->|Нет| C[Пропустить сборку и добавить S3 Deploy Action]
  B --> D[Post_build: aws s3 sync ./build s3://bucket-name]
  C --> E[CodePipeline: Deploy -> AWS S3 action 'sync']

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

• При коммите в целевую ветку пайплайн автоматически запустился.
• CodeBuild успешно выполнил npm install и npm run build.
• Содержимое ./build корректно синхронизировано с бакетом S3 и сайт доступен по URL.
• При ошибке сборки пайплайн не изменил содержимое бакета.

Частые ошибки и как их решать

• “AccessDenied” при aws s3 sync — проверьте IAM политику роли CodeBuild.
• Ошибки npm (peerDependencies, registry) — проверьте network/proxy и версию node.
• Пустая директория ./build — убедитесь, что ваш скрипт сборки кладёт артефакты в ожидаемый путь.

Итог

Настройка CodePipeline + CodeBuild для деплоя сайта в S3 даёт простой, безсерверный и автоматизированный процесс обновления статических сайтов и SPA. Ключевые элементы — корректный buildspec.yml, минимальные права роли CodeBuild и продуманная стратегия отката (версионирование или архивы сборок).

Important: включите версионирование бакета и используйте минимально необходимые IAM-права.

Короткое резюме:

• Автоматизация уменьшает ручные ошибки и ускоряет релизы.
• CodeBuild может и собирать, и деплоить в S3 через aws s3 sync.
• Защищайте доступ с помощью минимальных IAM-политик и храните секреты в Secrets Manager.