Mkdocs와 S3/Cloudfront를 기반으로 한 문서 공개 시스템 구축

TL;DR

Markdown에 기재된 문서를 GiitHub에 제출한 후
CodePipeline과 CodeBuild를 통해 HTML로 자동 변환되며, S3/CloudFront에서 DEPRO를 진행하여 공개합니다.
mkdocs에서 HTML로 변환합니다.

컨디션

No.
Resource
Purpose
Note
1
GitHub
Makrdown에 기재된 문서를 관리합니다.
-
2
AWS CodeStar
CodePipeline/CodeBuild를 생성합니다.
-
3
AWS CodePipeline
소스 코드가 GiitHub에 커밋된 Master 분기가 감지되고 AWS CodeBuild가 실행됩니다.
-
4
AWS CodeBuild
Markdown 문서와 관련해서는 Mkdocs를 통해 HTML 형식으로 변환하고 Amazon S3에서 프레젠테이션합니다.
-
5
Amazon S3
HTML 형식으로 변환된 문서를 배치합니다.여기에 놓인 문서는 공개될 것이다.
-
6
Amazon Cloudfront
S3에서 구성된 문서를 CDN으로 전송합니다.
-
7
Amazon Route 53
Cloudfront의 사용자 정의 도메인 관리
-
8
Certificate Manager
사용자 지정 도메인에 대한 SSL/TLS 인증서를 발행합니다.
-
9
AWS WAF
문서에 대한 액세스를 관리합니다.
Optional입니다.이번에는 사용하지 않겠습니다.
10
Google Analytics
공개된 문서의 접근 로그를 분석합니다.
-

구축

개요

AWS CodeStar에서 프로젝트를 만듭니다.

S3통을 제작한다.

도메인 및 SSL/TLS 인증서 발행

Cloudfront을 설정합니다.

DNS를 설정합니다.

git clone.

mkdocs를 설정합니다.

CodeBuild를 통해 빌드를 설정합니다.

CodePipeline을 설정합니다.

IAM Role의 정책을 수정합니다.

AWS CodeStar를 통한 프로젝트 제작

AWS CodeStar에서 프로젝트를 만듭니다.
AWS CodeBuild와 AWS CodePipeline만 사용하지만 이러한 템플릿이 존재하지 않기 때문에 제작 자원이 적은 Node.js/AWS Lambda를 선택했다.

AWS CodeStar를 사용하면 GiitHub의 창고와 이번에 사용한 AWS CodePipeline, CodeBuild의 자원이 자동으로 생성됩니다.
AWS 람바다, API Gateway, S3 구간도 자동으로 제작되며 사용하지 않으면 삭제할 수도 있다.

세 개의 작업 단계를 만들다

다음 S3 구간은 CodeStar에서 자동으로 생성됩니다.

[프로젝트 이름] -pipe·CodePipeline은 Artifact를 구성하는 데 사용되는 물통입니다.

[프로젝트 이름] -app... 웹 애플리케이션에 필요한 정적 내용(HTML 등)을 구성하는 구간입니다.

[プロジェクト名]-app 직접 사용 가능하지만, 최소한의 설정통을 사용하기 위해 새로운 통을 제작한다.

도메인 및 SSL/TLS 인증서 발행

필요에 따라 도메인을 발행하고 ACM(AWS Certificate Manager)을 사용하여 SSL/TLS 인증서를 발행합니다.
ACM은 バージニア北部 영역으로 제작해야 합니다.
도쿄 리존 등 ACM에 등록된 SSL/TLS 인증서는 클라우드front로 설정할 수 없습니다.

Cloudfront 설정

Cloudfront을 설정합니다.Cloudfront에서 다음 설정을 수행합니다.

사용자 지정 도메인

S3 구간에 대한 액세스 설정

Default Root Object의 설정

오리진은 이번에 제작된 S3 통을 지정합니다.mkdocs를 사용할 때 Origin Path에서 docs를 설정하면 mkdocs의 기본값과 일치하기 때문에 여분의 설정 변경을 생략할 수 있습니다.Restrict Bucket Access 설정은 클라우드front의 배달에서만 S3 구간에 접근할 수 있습니다.
따라서 S3통을 따로 공개적으로 설치할 필요가 없다.
Alternate Domain Names에서 문서를 공개할 영역을 지정합니다.
또한 ACM에서 SSL 인증서를 먼저 작성해야 합니다.Default Root Object에 지정index.html.
이 옵션을 설정하지 않으면 브라우저https://www.example.com에서 이렇게 FQDN만 지정하면 컨텐트를 표시할 수 없습니다.

DNS 설정

Cloudfront 설정이 완료되면 디버깅이 끝난 후 사용자 정의 영역에 접근할 수 있도록
개체 Cloudfront의 Distribution Domain Name을 DNS의 Alias로 등록합니다.

git clone

AWS 코드스타를 통해 프로젝트 제작이 완료되면 GitHub에 창고가 만들어지기 때문에 git clone이 진행된다.

mkdocs 설정

git clone 아래에 새 mkdocs.yml 파일을 만듭니다.
제작된 내용은 다음과 같다.

# web site setting
site_name: EXAMPLE.COM
site_url: https://www.example.com/
google_analytics: ['UA-XXXXXXXXX-1', 'auto']

# search engin
extra:
  search:
    language: 'jp'

## othters
use_directory_urls: false

점use_directory_urls은 false입니다.
AWS S3과 Cloudfront이 홈페이지를 공개한 후/example/와 같은 디렉터리가 정지된 URI라면 자동으로 보충되지 않는다index.html(Cloudfront의Default Root Object는 FQDN 바로 아래에만 유효하다.
Google Analytics에서 사용할 설정도 수행됩니다.

CodeBuild를 통해 빌드 컨텐트를 설정합니다.

CodeBuild는 다음과 같습니다.

Mkdocs의 Markdown 문서의 HTML 변환

S3에 업로드

Cloudfront의 Invalidation

CodeBuild의 빌드 내용은 buildspec.yml에 기재되어 있습니다.

version: 0.2

env:
  variables:
    HOMEPAGE_S3_BUCKET: "www.example.com"

phases:
  install:
    commands:
      - pip install --upgrade pip
      - pip install --upgrade awscli
      - aws --version
      - pip install mkdocs
      - mkdocs --version
  pre_build:
    commands:
  build:
    commands:
      - mkdocs build
  post_build:
    commands:
      - cd site
      - pwd
      - echo $HOMEPAGE_S3_BUCKET
      - aws s3 sync . s3://$HOMEPAGE_S3_BUCKET/docs --delete
      - aws cloudfront create-invalidation --region ap-northeast-1 --distribution-id XXXXXXXXXXXXXX --paths "/*"

distribution-id에서 이전에 설정한 Cloudfront의 Distribution ID를 설정합니다.
이 설정을 수행하지 않으면 문서를 업데이트해도 CDN 캐시가 즉시 반영되지 않습니다.

CodePipeline 구성

CodeStar에서 자동으로 작성한 Lambda/API Gateway를 삭제하면 CodePipeline을 변경하여 Deploy 관문을 삭제합니다.
만약 삭제하지 않는다면 원래의 모양을 유지해도 괜찮다.

IAM Role 정책 수정

CodeStar는 다음 명명규약에 따라 각 프로젝트의 Role을 제작했습니다.

CodeStarWorker-[프로젝트 이름] - [AWS 리소스 이름]

CodeBuild를 실행할 때 공개 문서 관리용 S3 업로드와 Cloudfront의 Invalidation (캐시 지우기) 을 위한 정책을 변경합니다.
IAM RoleCodeStarWorker-[プロジェクト名]-CodeBuild에 다음 정책을 추가하십시오.

        {
            "Sid": "XXXXXXXXXX",
            "Effect": "Allow",
            "Action": [
                "cloudfront:CreateInvalidation"
            ],
            "Resource": "*"
        },
        {
            "Sid": "XXXXXXXXXX",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject*",
                "s3:GetObjectVersion",
                "s3:List*"
            ],
            "Resource": [
                "arn:aws:s3:::www.example.com",
                "arn:aws:s3:::www.example.com/*"
            ]
        }

활용단어참조

그리고 Mardown에서 문서를 작성하여 GiitHub에 제출할 때 CodePipeline은 자동으로 감지하고 CodeBuild를 통해 HTML 변환,
Cloudfront은 S3을 통해 게시됩니다.
S3에서 콘텐츠를 관리하다 보니 가격이 저렴할 뿐만 아니라 클라우드 프론트에 캐시돼 있어 반응도 좋았다.

Editors Note

2018/11/26

나는 사용AWS Amplify Console이 더 빠를 것이라고 생각한다.기사가 제작된 지 얼마 되지 않아 새로운 서비스가 발표되어 슬프고 기쁩니다.