AWS API Gateway와 Lambda 서버리스 구축하며 겪은 현실적인 Q&A

AWS API Gateway와 Lambda를 연결해 서버리스 환경을 구축하다 보니 생각보다 삽질이 많았어요. 특히 설정값 하나, 권한 문제 하나가 전혀 예상치 못한 에러를 내면서 시간을 잡아먹더라고요.

그래서 이번 글에서는 직접 세팅하면서 제일 많이 헷갈렸던 점, 막힌 부분과 해결법들을 질문과 답변 형식으로 정리해봤어요. AWS 서버리스 처음 도전하는 분들께는 이 글 하나면 충분할 거예요.

개발 환경 / 버전 정보

이번 프로젝트에서 사용한 버전과 도구는 다음과 같아요.
AWS CLI v2, Node.js 18, AWS Lambda (Node.js 런타임), 그리고 AWS API Gateway HTTP API를 썼습니다.

AWS API Gateway랑 Lambda 연결은 이렇게 합니다

사실 이 부분이 가장 간단할 줄 알았는데, 의외로 설정 하나 때문에 한참 헤맸어요. 기본 흐름은 Lambda 함수를 만들고, API Gateway에서 HTTP API를 만든 뒤, 라우트를 Lambda에 연결하는 거거든요.

// Lambda 함수 예시 (index.js)
exports.handler = async (event) => {
  console.log('Request event:', event);
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Hello from Lambda!' }),
  };
};

이후 AWS CLI로 API Gateway 생성하고 라우트 등록할 때, 반드시 Lambda 권한 설정을 함께 해야 하는데, 이 부분을 빼먹으면 403 에러가 납니다.

# API Gateway HTTP API 생성
aws apigatewayv2 create-api --name MyServerlessApi --protocol-type HTTP

# Lambda 함수에 API Gateway 호출 권한 부여
aws lambda add-permission \
  --function-name MyLambdaFunction \
  --statement-id apigateway-access \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn arn:aws:execute-api:region:account-id:api-id/*/*/*

이 권한 명령어에 source-arn이 틀리면 호출이 막혀서 꼭 확인해야 해요.

Q1. API Gateway에서 CORS 설정은 어떻게 하나요?

많이들 헷갈려하시는 게 바로 CORS 문제예요. API Gateway는 기본적으로 CORS가 활성화되어 있지 않아서, 브라우저에서 호출하면 Access-Control-Allow-Origin 에러가 뜹니다.

AWS 콘솔에서 HTTP API를 생성할 때 CORS 설정을 명시하면 되는데, CLI로도 가능합니다.

aws apigatewayv2 update-api --api-id api-id \
  --cors-configuration AllowOrigins='["*"]' AllowMethods='["GET", "POST"]' AllowHeaders='["*"]' MaxAge=3600

이렇게 하면 모든 도메인에서 GET, POST 요청이 가능해져요. 하지만 보안상 AllowOrigins는 꼭 필요한 도메인만 넣는 게 좋겠더라고요.

Q2. Lambda 함수에 환경변수는 어떻게 주고, 배포할 때는?

실제로 저도 처음엔 환경변수를 코드에 하드코딩해서 바로 문제였거든요. AWS Lambda에서는 환경변수를 설정하면 코드 수정 없이 활용 가능해서 편해요.

CLI로 Lambda 함수 생성 또는 수정할 때 --environment 옵션을 활용하면 됩니다.

aws lambda update-function-configuration \
  --function-name MyLambdaFunction \
  --environment Variables={ENV_STAGE=prod,API_KEY=abcdef}

배포할 때는 이 환경변수 정보를 빼먹으면, 다른 환경에서 똑같이 안 돌아가서 꼭 신경 써야 해요.

Q3. ‘Missing Authentication Token’ 오류가 뜨면?

API Gateway 이용 중에 가장 자주 보는 오류 중 하나예요. 사실 이 오류는 대부분 요청 URL이나 메소드가 API Gateway에 등록된 것과 다를 때 발생합니다.

저도 처음엔 URL 경로가 미세하게 달라서 이 문제로 몇 시간 날렸어요.

확인 방법은 API Gateway 콘솔에서 라우트(경로와 메소드)를 정확히 맞췄는지, 그리고 호출하는 URL에 오타가 없는지 보는 거예요.

Q4. Lambda 함수 로그는 어떻게 빠르게 확인하나요?

사실 이 부분이 개발하면서 제일 빈번하게 쓰게 된 팁인데요, 로그는 CloudWatch에서 확인할 수 있어요.

AWS CLI로 실시간 로그 스트림을 보는 방법이 있는데, 바로 아래처럼 써요.

aws logs tail /aws/lambda/MyLambdaFunction --follow

이 명령어를 쓰면 Lambda 실행 로그가 실시간으로 쭉 출력돼서 디버깅할 때 정말 빠르고 유용했어요.

Q5. API Gateway와 Lambda 비용은 어떻게 확인하나요?

처음 서버리스 시작하면 비용 부분도 걱정되죠? 저도 한 달에 얼마 나올지 몰라서 걱정 많이 했거든요.

AWS 콘솔에서 Billing 대시보드를 보면 Lambda 함수 실행 횟수와 API Gateway 호출 수가 나와서 비용을 유추할 수 있어요.

또, AWS Cost Explorer에서 특정 서비스별로 비용을 상세히 분석할 수 있으니 꼭 확인해보세요.

Q6. Lambda 타임아웃과 메모리 설정은 어떻게 해야 실서비스에 적합할까요?

많이들 설정을 너무 넉넉하게 잡아서 불필요하게 비용이 나오는 경우가 많아요. 저도 처음엔 타임아웃 15초, 메모리 1024MB로 해놓고 썼는데, 실제 테스트해보니 512MB, 5초로도 충분했거든요.

AWS Lambda 함수 설정에서 아래처럼 조절할 수 있습니다.

aws lambda update-function-configuration \
  --function-name MyLambdaFunction \
  --timeout 5 \
  --memory-size 512

꼭 부하 테스트 같이 실제 상황에서 테스트해보고 적절히 조절하는 게 좋아요!

Q7. 배포 자동화는 어떻게 하셨나요?

AWS CDK나 Serverless Framework도 있지만, 저는 처음이라 간단하게 GitHub Actions로 AWS CLI 명령어를 실행하는 방식으로 자동화를 구축했어요.

예를 들어, GitHub Actions 워크플로우에서 이렇게 Lambda 함수 배포 명령어를 실행하도록 했습니다.

name: Deploy Lambda

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
      - name: Deploy Lambda function
        run: |
          zip function.zip index.js
          aws lambda update-function-code --function-name MyLambdaFunction --zip-file fileb://function.zip

이 방식이 저처럼 처음 시작하는 분들에겐 부담도 적고, 편하게 사용할 수 있어요.

Q8. Lambda 함수 크기 제한과 레이어 사용법이 궁금해요

Lambda 함수 크기가 50MB(압축 전) 제한이 있어서, 복잡한 의존성을 모두 넣으면 초과하기 쉽습니다. 저도 패키지 관리할 때 이 부분이 문제라 레이어를 적극 활용했어요.

레이어는 공통 라이브러리나 바이너리를 분리해서 여러 함수가 공유하도록 해줘서 배포 속도도 빨라지고 관리도 쉽더라고요.

레이어 생성 및 함수에 레이어 추가는 이렇게 명령어로 할 수 있어요.

# 레이어 ZIP 만들기
zip -r my-layer.zip nodejs/

# 레이어 생성
aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://my-layer.zip --compatible-runtimes nodejs18.x

# 함수에 레이어 추가하기
aws lambda update-function-configuration --function-name MyLambdaFunction --layers arn:aws:lambda:region:account-id:layer:my-layer:1

레이어 버전 숫자 맞춰야 해서 배포 자동화 때 신경 써야 해요.

이런 식으로 저는 AWS API Gateway와 Lambda 서버리스 환경을 구축하면서 실질적으로 부딪힌 문제와 대응책들을 정리했는데요, 직접 시도해보면서 알게 된 팁들이라 초보분들에게 특히 도움이 될 거 같아요.