AWS S3 연동

목적

본 기능은 에어브릿지를 통해 수집된 로그를 가공하지 않은 상태 그대로 AWS S3를 통해 고객사에 전달하는 것을 목적으로 하며, 아래 3가지 이벤트 소스를 전달할 수 있습니다.

앱 이벤트(App): 앱 SDK에서 발생하는 이벤트
웹 이벤트(Web): 웹 SDK에서 발생하는 이벤트
트래킹링크 이벤트(Tracking Link): 매체에서 트래킹링크 클릭/조회시 발생하는 이벤트

이렇게 전달된 데이터는 고객사의 데이터 웨어하우스에서 유의미한 형태로 가공하여 사용할 수 있습니다.

🚧
AWS S3 연동에는 (1) Access Key & Secret Key를 사용하는 방법과 (2) IAM Role 사용 방법 2가지 방법이 있습니다. (2) IAM Role 사용 방법이 보안적으로 더 권장되는 방법이고, (1) Access Key & Secret Key를 사용하는 방법의 경우 2024년 하반기부터 지원하지 않을 예정이니 연동에 참고 부탁드립니다.

AWS S3 연동 - (1) Access Key & Secret Key 사용 방법

STEP 1 - 로그인 및 버킷 생성하기 (S3)

AWS S3 접속 후 로그인합니다.
'+버킷 만들기' 버튼을 누르고 새로운 버튼을 생성합니다.
속성 및 권한 설정에서 별도로 추가할 값은 없습니다.

STEP 2 - 정책 생성하기 (IAM)

AWS IAM에서 좌측 게시판의 '정책'을 클릭합니다.
'정책 생성' 버튼을 누르고 JSON 값을 넣는 항목에 생성한 버킷 이름을 이용하여 아래 탬플릿을 붙여넣습니다.

'Review policy'를 선택하고 정책 생성을 마무리합니다.

{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": [
             "s3:ListBucket"
         ],
         "Resource": [
             "arn:aws:s3:::test-airbridge" // test-airbridge 부분을 STEP 1에서 생성한 버킷 이름으로 수정
         ]
     },
     {
         "Effect": "Allow",
         "Action": [
             "s3:PutObject",
             "s3:GetObject",
             "s3:DeleteObject"
         ],
         "Resource": [
             "arn:aws:s3:::test-airbridge/*" // test-airbridge 부분을 STEP 1에서 생성한 버킷 이름으로 수정
         ]
     }
 ]
}

STEP 3 - 사용자 추가 및 생성된 정책 연결하기 (IAM)

AWS IAM에서 좌측 게시판의 '사용자'를 클릭합니다.
'사용자 추가'를 선택하고 'AWS 엑세스 유형 선택'에서 '프로그래밍 방식 엑세스'에 체크 후 '다음: 권한'을 클릭합니다.
'기존 정책 직접 연결'을 클릭, STEP2에서 생성한 정책을 선택하고 '다음: 검토'를 클릭합니다.
사용자 추가를 마무리 하면서 '엑세스 키 ID' 및 '비밀 엑세스 키'를 가져옵니다. (비밀 엑세스 키는 '표시'를 눌러야 확인할 수 있습니다)

이름	설명	예시
AWS_ACCESS_KEY_ID	에어브릿지에게 제공하는 AWS 계정의 access key	CVAGZUZYPUTPHGXSXJGW
AWS_SECRET_ACCESS_KEY	에어브릿지에게 제공하는 AWS 계정의 secret key	XWzquDaznQDZieXPNnjimjNzhxnCVp

STEP 4 - 에어브릿지 대시보드에 추가하기

에어브릿지 대시보드에서 '서드파티 연동 - AWS S3' 항목으로 접속합니다.
지금까지 확인한 < (1) 엑세스 키 ID, (2) 비밀 엑세스 키, (3) REGION 정보, (4) 버킷 이름 > 정보를 입력합니다.

REGION 정보는 버킷을 생성할 때 지정한 값과 일치하게 맵핑해야 합니다. 맵핑 정보는 AWS Docs에서 확인 가능합니다.

이름	설명	예시
REGION	사용하고자 하는 AWS 리전	ap-northeast-1
BUCKET_NAME	사용하고자 하는 버킷의 이름	your-bucket-name

AWS S3 연동 - (2) IAM Role 사용 방법

STEP 1 - Policy 생성

AWS IAM > Policy 메뉴에 접속하여 Create Policy를 선택합니다.

JSON 탭을 선택하여 아래 값을 붙여넣습니다. <bucket_name>에는 덤프를 받을 S3 버킷 이름을 적습니다.

{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": "s3:ListBucket",
         "Resource": "arn:aws:s3:::<bucket_name>"
     },
     {
         "Effect": "Allow",
         "Action": [
             "s3:PutObject",
             "s3:GetObject",
             "s3:GetObjectVersion",
             "s3:DeleteObject",
             "s3:DeleteObjectVersion"
         ],
         "Resource": "arn:aws:s3:::<bucket_name>/*"
     }
 ]
}

다음 단계(Next: Review)를 누르고, policy 이름을 설정(ex. airbridge_s3_access)한뒤 Create policy 합니다.

STEP 2 - IAM Role 생성 및 Airbridge 전달

STEP 1에서 생성한 Policy를 갖는 IAM Role을 생성(Roles 메뉴 > Create Role)합니다. Role 생성시 "AWS Account" > "Another AWS account" 타입으로 만들고, Account ID에는 임시로 고객사의 Account ID(ex. 123456789000)를 넣고, Options에서 "Require external ID"를 선택한 뒤 External ID에는 0000을 넣어줍니다. 해당 값들은 STEP 3에서 Airbridge에서 발급받은 값으로 변경될 예정입니다.

Role을 생성하고, 생성된 role arn을 복사해둡니다.
아래 정보를 담당 Airbridge CSM에게 전달합니다.
1. STEP 1에서 생성한 Bucket Name (<bucket_name>)
2. STEP 1에서 생성한 Bucket Region (ex. ap-northeast-2)
3. STEP 2에서 복사한 IAM Role arn (arn:aws:iam::<aws_account_id>:role/<arn_role_name>)

STEP 3 - Airbridge가 제공한 ARN 및 External ID 등록

Airbridge CSM에게 요청해 iam_user_arn과 external_id를 발급받습니다.

발급받은 iam_user_arn과 external_id을 등록하면 STEP 1번에서 생성한 IAM Role의 Trust Relationship을 설정할 수 있습니다.

{
 "Version": "2012-10-17",
 "Statement": [
   {
     "Effect": "Allow",
     "Principal": {
       "AWS": "<iam_user_arn>"
     },
     "Action": "sts:AssumeRole",
     "Condition": {
       "StringEquals": {
         "sts:ExternalId": "<external_id>"
       }
     }
   }
 ]
}

설정 완료 후 Airbridge CSM에게 알려주시면, 사전에 조율한 날짜 이후부터 S3 덤프를 시작하게 됩니다.

Data 확인하기

설정을 완료하면 각 이벤트 소스는 설정한 Bucket 내 아래와 같은 위치에 덤프되며, 덤프되는 파일의 포맷은 .csv.gz 입니다.

앱 이벤트(App): ${YOUR-BUCKET-NAME}/${YOUR-APP-NAME}/app/${VERSION}/date=${year}-${month}-${day}/
웹 이벤트(Web): ${YOUR-BUCKET-NAME}/${YOUR-APP-NAME}/web/${VERSION}/date=${year}-${month}-${day}/
트래킹링크 이벤트(Tracking Link): ${YOUR-BUCKET-NAME}/${YOUR-APP-NAME}/tracking-link/${VERSION}/date=${year}-${month}-${day}/

Data Column Spec

각 이벤트 소스별로 덤프되는 파일의 Data Column Spec은 링크를 참고해주시기 바랍니다. Field Name 컬럼이 csv 파일의 헤더로 사용됩니다. 샘플 파일은 링크에서 확인할 수 있습니다.

Dump Spec

KST 타임존 설정 기준, 매일 KST 오전 4시~6시 사이 덤프됩니다.
"이벤트 발생 시간"이 아닌 "서버 수집 시간"을 기준으로 이벤트를 덤프합니다. 예를 들어, KST 2020년 10일 2일 0시 ~ KST 2020년 10월 2일 24시 사이 서버에 수집된 이벤트는 KST 2020년 10월 3일 오전 4시~6시 사이 .../date=2020-10-02/ 폴더에 덤프됩니다. 에어브릿지에선 최대 24시간 전 발생한 이벤트까지 수집하므로, .../date=2020-10-02/ 폴더엔 KST 2020년 10월 1일 0시 ~ 2020년 10월 2일 24시에 발생한 이벤트가 존재할 수 있습니다.
128MB 크기 이하의 파일이 여러개 덤프되므로, 여러개 파일을 로드하기 위한 처리를 해주시기 바랍니다.