Hướng Dẫn Triển Khai API Serverless với AWS SAM và Github Action

Hướng Dẫn Triển Khai API Serverless với AWS SAM và Github Action

avatar

Long Ngo

2025.07.01

Trong bài blog này, chúng ta sẽ tìm hiểu cách sử dụng AWS Serverless Application Model (SAM) để triển khai một API serverless đơn giản theo mô hình "Hello World". Hướng dẫn này sẽ dẫn bạn qua các bước từ việc cài đặt môi trường, khởi tạo ứng dụng, xây dựng, triển khai, đến xóa tài nguyên trên AWS Cloud. Ứng dụng mẫu sẽ bao gồm một hàm AWS Lambda, một endpoint API Gateway và các vai trò IAM cần thiết.

Tổng quan

Trong thời đại công nghệ hiện nay, serverless computing đang trở thành xu hướng phổ biến nhờ khả năng giảm chi phí vận hành và tăng tính linh hoạt. AWS Serverless Application Model (SAM) là một công cụ mạnh mẽ giúp các nhà phát triển dễ dàng xây dựng và triển khai ứng dụng serverless trên AWS. Trong bài viết này, chúng ta sẽ tìm hiểu cách triển khai một API serverless đơn giản bằng SAM và tự động hóa quy trình triển khai bằng GitHub Actions, sử dụng xác thực OpenID Connect (OIDC) để tăng cường bảo mật.

Bài viết này sẽ hướng dẫn bạn qua các bước cụ thể, từ việc khởi tạo ứng dụng SAM, triển khai thủ công, đến thiết lập tự động hóa với GitHub Actions. Hướng dẫn được viết với giọng văn thân thiện, dễ hiểu, phù hợp cho cả người mới bắt đầu và người đã có kinh nghiệm với AWS.

Giới thiệu về AWS SAM

AWS SAM (Serverless Application Model) là một framework mã nguồn mở giúp các nhà phát triển xây dựng và triển khai ứng dụng serverless trên AWS. SAM sử dụng AWS CloudFormation để định nghĩa cơ sở hạ tầng và tài nguyên như Lambda Functions, API Gateway, và DynamoDB. Một số đặc điểm nổi bật của SAM:

  • Hỗ trợ nhiều ngôn ngữ lập trình: Node.js, Java, Python, .NET, và Go.
  • Cung cấp môi trường kiểm thử và gỡ lỗi cục bộ, giúp nhà phát triển kiểm tra mã trước khi triển khai.
  • Tích hợp với AWS CodePipeline để hỗ trợ CI/CD.
  • Cung cấp giao diện dòng lệnh (CLI) và tích hợp với AWS Toolkit for Visual Studio Code.
  • Miễn phí sử dụng.

Một số lệnh SAM CLI phổ biến:

  • sam init: Khởi tạo một ứng dụng serverless mới.
  • sam build: Chuẩn bị ứng dụng serverless cho kiểm thử cục bộ hoặc triển khai lên AWS.
  • sam deploy: Triển khai ứng dụng serverless lên AWS Cloud.
  • sam delete: Xóa tài nguyên của ứng dụng serverless bằng cách xóa CloudFormation stack.

Lab Introduction

  • Trình độ AWS: Người mới bắt đầu / Trung cấp
  • Thời gian hoàn thành: Khoảng 45 phút
  • Vùng AWS: US East (N. Virginia) us-east-1
  • Chi phí hoàn thành: Có thể sử dụng Free Tier
  • Dịch vụ sử dụng: AWS SAM, AWS Lambda, API Gateway, S3, IAM, GitHub Actions

Architecture Diagram

Dưới đây là kiến trúc tổng quan của ứng dụng sau khi hoàn thành triển khai:

Ứng dụng mẫu trong hướng dẫn này là một API "Hello World" đơn giản, bao gồm:

  • Một AWS Lambda Function xử lý các yêu cầu HTTP.
  • Một API Gateway để cung cấp endpoint cho API.
  • Một bucket S3 để lưu trữ artifact triển khai. (sam sẽ tự động tạo)
  • CloudFormation để quản lý cơ sở hạ tầng.
Tài nguyênMô tả
Lambda FunctionXử lý logic của API
API GatewayCung cấp endpoint để truy cập API
S3 BucketLưu trữ artifact triển khai
CloudFormationQuản lý và triển khai cơ sở hạ tầng

Prerequisites

Trước khi bắt đầu, bạn cần chuẩn bị:

  • Một tài khoản AWS .
  • Một tài khoản GitHub.
  • Git được cài đặt trên máy tính .

Task Details

  1. Cài đặt Sam CLI
  2. Khởi tạo ứng dụng SAM
  3. Xây dựng ứng dụng
  4. Triển khai ứng dụng lên AWS
  5. Thiết lập OIDC trong AWS
  6. Cấu hình GitHub Actions
  7. Test workflow:
  8. Clean Up

##1. Cài đặt Sam CLI

Lưu ý: Hiện tại phiên bản 1.42 đang có lỗi khi chạy lệnh deploy. Mọi người cài đặt bản 1.42 trở về trước nhé. Vào trang https://github.com/aws/aws-sam-cli/releases để download và install theo hướng dẫn ở đây nhé

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html

##2. Khởi tạo ứng dụng SAM

Để bắt đầu, chúng ta sử dụng lệnh sam init để tạo một ứng dụng mẫu.

sam init

  • Chọn 1 - AWS Quick Start Templates
  • Chọn template "Hello World Example".
  • Chọn runtime là python (ấn y).
  • Không enable X-Ray tracing
  • Chọn không enable CloudWatch Application Insights
  • Enable Json format
  • Đặt tên dự án, ví dụ: soa-sam-app.

Sau khi chạy lệnh, thư mục dự án sẽ có cấu trúc như sau:

└── soa-sam-app
    ├── README.md
    ├── __init__.py
    ├── events
    │   └── event.json
    ├── hello_world
    │   ├── __init__.py
    │   ├── app.py
    │   └── requirements.txt
    ├── samconfig.toml
    ├── template.yaml
    └── tests
        ├── __init__.py
        ├── integration
        │   ├── __init__.py
        │   └── test_api_gateway.py
        ├── requirements.txt
        └── unit
            ├── __init__.py
            └── test_handler.py
  • template.yaml: Định nghĩa cơ sở hạ tầng của ứng dụng (Lambda Function, API Gateway, v.v.).
  • hello_world/app.py: Chứa mã nguồn của Lambda Function.

##3. Xây dựng ứng dụng

Tiếp theo, chúng ta xây dựng ứng dụng bằng lệnh sam build để chuẩn bị các artifact cần thiết cho triển khai.

cd soa-sam-app
sam build

Lệnh này sẽ:

  • Tạo thư mục .aws-sam chứa các artifact đã được xây dựng.

##4. Triển khai ứng dụng lên AWS

Để triển khai ứng dụng, sử dụng lệnh sam deploy --guided.

sam deploy --guided

Lệnh này sẽ:

  • Hướng dẫn bạn cấu hình các tham số như tên stack (ví dụ: sam-app), vùng AWS (ví dụ: us-east-1), và bucket S3 để lưu trữ artifact.
  • Tạo CloudFormation stack để triển khai Lambda Function và API Gateway.
  • Cung cấp URL của API Gateway sau khi triển khai thành công.

Các steps:

  1. Nhập stack name : SOA-Stack-Serverless-Application
  2. Region: us-east-1
  3. Confirm change: Y
  4. Cho phép SAM tự động tạo Role: Y
  5. Disable rollback: y
  6. Allow no authen: Y
  7. Save argument to file: Y
  8. SAM configuration file [samconfig.toml] nhấn Enter
  9. SAM configuration environment [default]: nhấn Enter
  10. Deploy this changeset? [y/N]: y
  11. Sau khi deploy xong các bạn có thể vào Cloudformation và thấy rằng SAM đã tự động tạo một stack để deploy các resource liên quan . Chúng ta có thể hiểu ngay rằng chúng ta vẫn đang sử dụng cloudformation để deploy chẳng qua SAM đã lo hết những công việc tay chân cho chúng ta mà thôi

Sau khi triển khai, bạn có thể kiểm tra API bằng cách gửi yêu cầu HTTP đến endpoint được cung cấp.

  1. Kiểm tra lambda funtion mới được tạo
  2. API Gateway
  3. Vào Stage > Prd > Copy Invoke URL
  4. Vào trình duyệt và test:
https://{Invoke URL}/hello

  1. Sau khi chạy xong các bước trên các bạn sẽ có file samconfig.toml

##5. Thiết lập OIDC trong AWS

Để tự động hóa triển khai bằng GitHub Actions mà không cần lưu trữ thông tin xác thực AWS lâu dài, chúng ta sử dụng xác thực OIDC.

A PhongNX đã có một bài giải thích rất kỹ vì sao nên sử dụng OIDC mình sẽ để link ở đây và không giải thích lại:

Tham khảo thêm bài của a Phong : Integrating GitHub Actions with AWS Using OIDC authentication

  1. Tạo Identity Provider

  2. Truy cập AWS Management Console, vào IAM > Identity providers > Add provider.

  3. Chọn OpenID Connect.

  4. Nhập Provider URL: https://token.actions.githubusercontent.com.

  5. Nhập Audience: sts.amazonaws.com.

  6. Nhấn Add provider để hoàn tất.

  7. Tạo IAM Role cần thiết cho Github Action

  8. Trong IAM Console, vào Roles > Create role.

  9. Chọn Web identity và chọn Identity Provider vừa tạo (token.actions.githubusercontent.com).

  10. Gắn các policy cần thiết:

    • AWSLambdaFullAccess
    • AmazonS3FullAccess
    • CloudFormationFullAccess
    • (Tùy chọn) AmazonAPIGatewayAdministrator để quản lý API Gateway.

  11. Đặt tên role, ví dụ: SOA-GitHubActions-SAMDeploy.

  12. Chỉnh sửa trust relationship của role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_USERNAME/YOUR_REPO_NAME:ref:refs/heads/main"
        }
      }
    }
  ]
}

Sample của mình :

  • Thay YOUR_ACCOUNT_ID bằng ID tài khoản AWS của bạn.
  • Thay YOUR_GITHUB_USERNAME và YOUR_REPO_NAME bằng tên người dùng và kho lưu trữ GitHub của bạn.

##6. Cấu hình GitHub Actions

Để tự động hóa triển khai, chúng ta tạo một workflow GitHub Actions.

  1. Trong kho lưu trữ GitHub, tạo thư mục .github/workflows và file deploy.yml:
name: Apiapp auto build

on:
  push:
    paths:
      - 'hello_world/**' # Kích hoạt workflow khi có thay đổi trong thư mục hello_world

permissions:
  id-token: write # Quyền ghi token để xác thực với AWS
  contents: read # Quyền đọc nội dung repository
  repository-projects: write # Quyền ghi vào projects của repository

jobs:
  deploy-sam:
    runs-on: ubuntu-latest # Chạy job trên máy Ubuntu mới nhất

    steps:
      # Lấy mã nguồn từ repository
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Lấy toàn bộ lịch sử commit để đảm bảo có commit hash chính xác

      - uses: actions/checkout@v3
      - uses: actions/setup-python@v3
      - uses: aws-actions/setup-sam@v2

      # Cấu hình thông tin xác thực AWS
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }} # Vai trò AWS để xác thực
          aws-region: ${{ secrets.AWS_REGION }} # Vùng AWS được chỉ định

      - name: SAM Build
        run: sam build

      - name: SAM Deploy
        run: sam deploy --no-confirm-changeset --no-fail-on-empty-changeset --stack-name SOA-Stack-Serverless-Application --capabilities CAPABILITY_IAM --region us-east-1
  1. Đẩy mã nguồn lên GitHub:
git add .
git commit -m "Initial commit - AWS SAM API setup"
git push -u origin main

  1. Setting Secret :
  • Vào link : https://github.com/{GIT_USERNAME}/{PROJECTNAME}/settings/secrets/actions Thêm 2 Secret như bên dưới
  • Thay AWS_ROLE_ARN bằng ARN của role được tạo trong step Bước 4: Thiết lập OIDC trong AWS .
  • Thay AWS_REGION bằng us-east-1.

##7. Test workflow:

  1. Sửa api bằng cách sử nội dung message:
  2. Sau đó commit và push
  3. Confirm Workflow được trigger Action tab . Và đợi đến khi build thành công :
  4. Refresh browser và xác nhận change đã được phản ánh

##8.Clean Up:

Để tránh phát sinh chi phí, hãy xóa các tài nguyên sau khi hoàn tất:

  • Xóa CloudFormation stack:
    • Chạy lệnh: sam delete --stack-name SOA-Stack-Serverless-Application
    • Hoặc vào AWS Console > CloudFormation > Chọn stack > SOA-Stack-Serverless-Application > Delete.
  • Xóa nội dung S3 bucket Bucket được sam cli generate
  • Xóa S3 bucket Bucket được sam cli generate
  • Xóa IAM Role: SOA-GitHubActions-SAMDeploy
  • Xóa Identity Provider:
    • Vào IAM Console > Identity providers > Chọn token.actions.githubusercontent.com > Delete.

Nơi đặt resouce:

Kết luận

Bằng cách sử dụng AWS SAM và GitHub Actions với xác thực OIDC, bạn có thể triển khai và tự động hóa các ứng dụng serverless một cách an toàn và hiệu quả. Phương pháp này không chỉ giúp tiết kiệm thời gian mà còn tăng cường bảo mật bằng cách loại bỏ nhu cầu lưu trữ thông tin xác thực lâu dài. Hãy thử áp dụng và khám phá thêm các tính năng của SAM và GitHub Actions để xây dựng các ứng dụng serverless mạnh mẽ hơn!