{"id":15454441,"url":"https://github.com/dodonki1223/translate","last_synced_at":"2025-03-28T09:42:47.544Z","repository":{"id":98778917,"uuid":"463877385","full_name":"dodonki1223/translate","owner":"dodonki1223","description":"AWS ハンズオン資料の「サーバーレスアーキテクチャで翻訳 Web API を構築する」を参考に Terraform と Serverless Framework で書き直した翻訳 Web API です","archived":false,"fork":false,"pushed_at":"2022-03-29T02:12:58.000Z","size":433,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-02T10:29:48.675Z","etag":null,"topics":["api-gateway","dynamodb","lambda","serverless","serverless-framework","terraform"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dodonki1223.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-26T14:35:17.000Z","updated_at":"2022-03-24T01:17:15.000Z","dependencies_parsed_at":"2023-03-13T15:54:55.312Z","dependency_job_id":null,"html_url":"https://github.com/dodonki1223/translate","commit_stats":{"total_commits":75,"total_committers":1,"mean_commits":75.0,"dds":0.0,"last_synced_commit":"6e5fe1be623a8e2df144f0f74bcfd7de93f38618"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dodonki1223%2Ftranslate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dodonki1223%2Ftranslate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dodonki1223%2Ftranslate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dodonki1223%2Ftranslate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dodonki1223","download_url":"https://codeload.github.com/dodonki1223/translate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246009029,"owners_count":20708880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","dynamodb","lambda","serverless","serverless-framework","terraform"],"created_at":"2024-10-01T22:02:56.645Z","updated_at":"2025-03-28T09:42:47.525Z","avatar_url":"https://github.com/dodonki1223.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# translate 🇯🇵 → 🇺🇸\n\nこのリポジトリは [AWS ハンズオン資料](https://aws.amazon.com/jp/aws-jp-introduction/aws-jp-webinar-hands-on/) の [サーバーレスアーキテクチャで翻訳 Web API を構築する](https://pages.awscloud.com/event_JAPAN_Hands-on-for-Beginners-Serverless-2019_Contents.html) を参考に Terraform と Serverless Framework で書き直したものになります。  \n\n![overall](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/00_overall.png)\n\n## 📄 概要\n\nこのリポジトリには大きく分けて３つ目的があり作成しています。\n\n- **Terraform と Serverless Framework の相互連携**\n- **サーバーレスアーキテクチャーの Infrastructure as Code（IaC）化**\n- **ローカル環境にてサーバーレスアーキテクチャーのエミュレートしながらの開発を可能にする**\n\n基本的にはハンズオン資料で作成したものとほぼ同じになるように作成していますが一部 Lambda レイヤーを導入していたりと少し違っています。  \n\n## ⚙️ 環境構築\n\nAWS のリソースは Terraform で管理されているものと Serverless Framework で管理されているものがあります。  \nTerraform の tfstate ファイル（現在の状態を表すファイル）は複数人で開発することを想定しているため AWS S3 に保存して開発を行います。  \nまた Serverless Framework もデプロイするために AWS S3 を使用する（CloudFormation, Lambda のコードを zip化されたものなどを指す。 .serverless フォルダ配下に作成されているファイル群）ため作成が必要です。  \n\nS3 の作成後、Terraform と Serverless Framework の設定を順番に行っていきます。  \nTerraform と Serverless Framework の連携のため、 **設定する順番がとても重要** になってきます。 **必ず Terraform から設定をする必要** があります。\n\n### 🗑 Terraform と Serverless Framework で使用する S3 の作成\n\nS3 作成用のシェルスクリプトがあるため、基本的にはそのシェルスクリプトを実行するだけで大丈夫です。  \n[AWS CLI](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/kinesis-tutorial-cli-installation.html) を使用してバケットを作成するので、 [AWS CLI](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/kinesis-tutorial-cli-installation.html) が実行できる状態にしておいてください。  \n必ず profile の指定が必要なので profile の作成も行う必要があります。\n\nprofile の作成方法に関しては以下のコマンドを実行してください。\n\n```shell\n$ aws configure --profile terraform\n```\n\n実際に S3 作成用のシェルスクリプトを実行した時の例になります。\n\n```shell\ndodonki1223🐻: ~/project/translate on 🌱 main [📝🤷‍✓] took 10s\n└─\u003e bin/init_s3.sh\nS3バケット作成で使用するprofile名を入力してください: terraform\ntfstateもしくはServerless FrameworkのデプロイS3バケット名を入力して下さい: translate-sls\ntranslate-slsの作成を行います\nmake_bucket: translate-sls\ntranslate-slsにバージョンニングを有効化に成功しました\ntranslate-slsにサーバー側の暗号化を有効化に成功しました\ntranslate-slsのアクセスの変更に成功しました\n```\n\nこのリポジトリでは profile 名と バケット名は固定でソースコードに書かれているので適宜変更してください。\n\n| 設定名                                  | 設定値              |\n|:----------------------------------------|:--------------------|\n| AWS の profile 名                       | terraform           |\n| tfstate の格納バケット                  | translate-terraform |\n| Serverless Framework デプロイ用バケット | terraform-sls       |\n\n### 🌭 Terraform の環境構築\n\nローカル環境であっても **Serverless Framework と連携** するために **AWS Systems Manager Parameter Store を使用する必要がある** ため、予め開発用のパラメータをセットしておく必要があります。  \nなので Serverless Framework の開発を始める前にまずは AWS に必要なリソースを Terraform を使って作成していきます。\n\nこれからの作業は **terraform のディレクトリで行う** ので必ず移動してください。\n\n```shell\n$ cd translate/terraform\n```\n\n#### Terraform をインストールする\n\nasdf などのパッケージマネージャーを使用して Terraform をインストールして使える状態にします。\n\n```shell\n# terraform の plugin を追加する\n$ asdf plugin add terraform\nupdating plugin repository...remote: Enumerating objects: 41, done.\nremote: Counting objects: 100% (41/41), done.\nremote: Compressing objects: 100% (36/36), done.\nremote: Total 41 (delta 22), reused 14 (delta 5), pack-reused 0\nUnpacking objects: 100% (41/41), 40.13 KiB | 334.00 KiB/s, done.\nFrom https://github.com/asdf-vm/asdf-plugins\n   8ef69e3..fe90d7a  master     -\u003e origin/master\nHEAD is now at fe90d7a feat: add asdf-gcc-arm-none-eabi plugin (#565)\n\n# terraform をインストールする\n$ asdf install terraform\n```\n\n#### Terraform の初期化コマンドを実行する\n\nterraform 内で使用している plugin などのバイナリファイルをダウンロードします。\n\n```shell\n$ terraform init \n```\n\n#### workspace を作成する\n\n環境の切り分けについてはそれぞれの環境で差異があるわけではないので workspace を使うことを前提としています。  \ndev, stg, prod の環境をそれぞれ作成しておくと良いでしょう。\n\n注意：workspace は必ず `dev` 環境を作成しないとローカル実行もできないです！\n\n```shell\n$ terraform workspace new dev\nCreated and switched to workspace \"dev\"!\n\nYou're now on a new, empty workspace. Workspaces isolate their state,\nso if you run \"terraform plan\" Terraform will not see any existing state\nfor this configuration.\n```\n\n#### 作成した workspace を選択する\n\n```shell\n$ terraform workspace select dev\nSwitched to workspace \"dev\".\n```\n\n#### Terraform で AWS のリソースを作成する\n\n```shell\n$ terraform apply -parallelism=30\nTerraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:\n  + create\n・\n・\n・\nApply complete! Resources: 7 added, 0 changed, 0 destroyed.\n```\n\n### 🍔 Serverless Framework の環境構築\n\nServerless Framework は基本的に Docker で開発を行うため、Docker が使える状態にしておいてください。\n\nこれからの作業は **serverless のディレクトリ** で行うので必ず移動してください。\n\n```shell\n$ cd translate/serverless\n```\n\n#### 環境変数を設定する\n\nテンプレートファイルをコピーし環境変数を設定します。\n\n```shell\n$ cp .docker/.env.sample .docker/.env\n```\n\n| 環境変数名            | 説明                                                                                      |\n|:----------------------|:------------------------------------------------------------------------------------------|\n| AWS_ACCESS_KEY_ID     | IAM ユーザーまたはロールに関連付けられる AWS アクセスキー                                 |\n| AWS_SECRET_ACCESS_KEY | AWS アクセスキーに関連付けられているシークレットキー（AWS アクセスキーのパスワードのこと）|\n| AWS_REGION            | profile 設定のリージョン設定                                                              |\n| DYNAMODB_LOCAL_PORT   | ローカルで実行している DynamoDB Local へアクセスするためのポート番号                      |\n\n#### 開発環境を立ち上げる\n\nDocker のコマンドを実行し開発環境を立ち上げます。\n\n```shell\n$ docker-compose up\n・\n・\n・\noffline_1         | Server ready: http://0.0.0.0:3000 🚀\n```\n\n[http://localhost:3000/dev/translate?input_text=おはよう](http://localhost:3000/dev/translate?input_text=おはよう) へアクセスし `Good morning` と返ってくれば API Gateway, Lambda, DynamoDB のローカル実行が出来ています。\n\n![translate_web_api_result](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/03_translate_web_api_result.png)\n\nまた [http://localhost:8001](http://localhost:8001) にアクセスし dynamodb-admin が表示されていることも確認しておきましょう。\n\n![dynamodb_admin](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/04_dynamodb_admin.png)\n\nこれでローカルの環境構築完了です！\n\n## ⚔️ Terraform と Serverless Framework について\n\n![relationship_between_terraform_and_serverless_framework](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/01_relationship_between_terraform_and_serverless_framework.png)\n\n開発に入る前にまずはこのリポジトリでの Terraform と Serverless Framework についての説明をします。  \nAWS のリソースに関しては **Terraform が管理しているもの** と **Serverless Framework が管理しているもの** があります。\n\n### 🌭 Terraform の管理化リソース\n\nTerraform が管理しているリソースは **IAM ロール, パラメータストア** になります。  \n権限は Serverless Framework で管理せずに Terraform で管理しています。\n\n![terraform_resources](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/05_terraform_resources.png)\n\n### 🍔 Serverless Framework の管理化リソース\n\nServerless Framework が管理しているリソースは **API Gateway, Lambda, DynamoDB, CloudWatch Logs** になります。\n\n![serverless_framework](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/06_serverless_framework_resources.png)\n\n### 🌭 Terraform と 🍔 Serverless Framework の連携について\n\nTerraform と Serverless Framework の連携に関してですが **「Terraform → Serverless Framework」** と **「Serverless Framework → Terraform」** の２種類がありそれぞれちゃんと連携を考えないといけません。  \n連携するためにデプロイ順もちゃんと考慮する必要があるのでどうやって連携するのかということだけをちゃんと理解出来るようになっていれば応用がきくのでしっかりと概念を頭に入れておくとよいでしょう。  \n\nこのリポジトリでは「Terraform → Serverless Framework」の連携だけ実装されています。ただしサンプルとして「Serverless Framework → Terraform」も連携出来ることも確認済みなのでいつでも連携可能です。\n\n### 🌭 Terraform → 🍔 Serverless Framework 連携\n\nServerless Framework の公式サイトに Terraform との連携方法について書かれている記事がありそれを参考にして連携しています。  \nTerraform で作成したリソースの arn をパラメータストアに設定し設定したパラメータストアから arn を取得して Serverless Framework で使用します。\n\nserverless.yml のソースコード上だと以下のような記述で連携しています。\n\n```yml\ncustom:\n  iamRoleName: ${ssm:/translate/iam_role/lambda_function_${sls:stage}}\n```\n\n詳しくは以下の記事を参考にしてください。\n\n- [The definitive guide to using Terraform with the Serverless Framework](https://www.serverless.com/blog/definitive-guide-terraform-serverless/)\n\n### 🍔 Serverless Framework → 🌭 Terraform 連携\n\nServerless Framework は CloudFormation を使用してデプロイするので CloudFormation が出力した output を使用して Terraform で連携させます。  \naws_cloudformation_export を使用することで CloudFormation が出力した情報を読み込むことができるようになるので Terraform でも連携が可能になります。\n\n```terraform \ndata \"aws_cloudformation_export\" \"lambda_function_arn\" {\n  name = format(\"lambda-function-arn-%s\", terraform.workspace)\n}\n```\n\n## 💻 開発\n\n開発は Terraform と Serverless Framework によって方法が違うため、注意して下さい。  \nServerless Framework に関しては複数の開発方法があるため、好みによって使い分けて下さい。\n\n### 🌭 Terraform\n\n開発環境の構築が終わっていればそのまま開発することができます。  \n\nTerraform の開発は `translate/terraform` のディレクトリに移動し、Terraform の通常通りの開発と同じく `terraform init`, `terraform plan`, `terraform apply` などのコマンドを使用して開発を行って下さい。\n\n### 🍔 Serverless Framework\n\n![local_development_environment](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/02_local_development_environment.png)\n\nServerless Framework の開発は２通りあります。  \nDocker のコンテナ内で開発することは変わらないのですが、VSCode を使った **[Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) での開発** と **開発用のコンテナにログインして開発** する方法があります。\n\nServerless Framework の開発は translate/serverless のディレクトリに移動して開発を行います。\n\n#### なぜ Docker を使って開発を行っているのか？\n\n**DynamoDB Local が M1 Mac だと動作しなかった** ため仕方なく Docker 化して開発することにしました。\nDynamoDB Local で使用されている SQLLite のライブラリが arm64 に対応していないため M1 Mac での動作が出来ないためです。  \n\nただ現在では Serverless Framework で DynamoDB Local を使用する [plugin が Docker に対応した](https://github.com/99x/dynamodb-localhost/issues/63) ため Docker 化しなくても動作するようになった（未検証です）かもしれません。\n\n#### VSCode Remote Containers\n\n![remote_containers](https://raw.githubusercontent.com/dodonki1223/image_garage/master/translate/07_remote_containers.gif)\n\nVSCode の拡張機能である **[Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) を予めインストール** しておいてください。  \ngif を見る通り Remote Containers を使用し offline コンテナを起動して offline コンテナ内で開発を行います。\n\n#### 開発用コンテナ\n\ndocker-compose.yml に開発用のサービスを定義してあります。  \n`docker-compose up` のコマンドでは立ち上がらないように profiles の指定をしているので明示的に開発用のサービスを指定することで開発用のコンテナが立ち上がります。\n\n```shell\n$ docker-compose run --rm runner\n```\n\n## 🚀 デプロイ\n\nデプロイは Terraform と Serverless Framework の２つがあります。  \nこのリポジトリではデプロイ順はすごく大切なことなので **必ずデプロイ順を間違えず** に行いましょう。\n\n### 🚨 デプロイ順に関して\n\n**Serverless Framework は Terraform のリソースに依存** しています。なのでデプロイする時は **必ず Terraform から行う必要** があります。\n\nServerless Framework からデプロイしようとするとエラーになり失敗します。\n\n### 🌎 デプロイ環境に関して\n\nデプロイ環境ですが、以下の環境を想定して作成してあります。\n\n| 環境 | 説明             |\n|:----:|:-----------------|\n| dev  | 開発環境         |\n| stg  | ステージング環境 |\n| prod | 本番環境         |\n\n### 🌭 Terraform\n\nまずは terraform ディレクトリに移動して下さい。\n\n```shell\n$ cd translate/terraform\n```\n\nデプロイ対象の workspace を選択します。\n\n```shell\n$ terraform workspace select prod\nSwitched to workspace \"prod\".\n```\n\nデプロイコマンドを実行します。\n\n```shell\n$ terraform apply -parallelism=30\n```\n\nTerraform によるデプロイはこれで終了です。\n\n### 🍔 Serverless Framework\n\nまずは serverless ディレクトリに移動して下さい。\n\n```shell\n$ cd translate/serverless\n```\n\n開発用コンテナを実行します。\n\n```shell\n$ docker-compose run --rm runner\n```\n\nデプロイコマンドを実行します。  \n`--stage xxx` のパラメータを元にどの環境にデプロイするかが決まります。\n\n開発環境はローカル実行する時に `DYNAMODB_ENDPOINT` が `http://localhost:${env:DYNAMODB_LOCAL_PORT}` になるようにしているため、デプロイ時は明示的に `DYNAMODB_ENDPOINT` を指定することでデプロイを行います。\n\n```\n# 開発環境へのデプロイ\n$ DYNAMODB_ENDPOINT=https://dynamodb.ap-northeast-1.amazonaws.com yarn deploy --stage dev\n\n# ステージング環境へのデプロイ\n$ yarn deploy --stage stg\n\n# 本番環境へのデプロイ\n$ yarn deploy --stage prod\n```\n\nServerless Framework によるデプロイはこれで終了です。\n\n## 📕 その他\n\nちなみにですが [AWS ハンズオン資料](https://aws.amazon.com/jp/aws-jp-introduction/aws-jp-webinar-hands-on/) に [AWS SAM を使ってテンプレートからサーバーレスな環境を構築する](https://pages.awscloud.com/event_JAPAN_Ondemand_Hands-on-for-Beginners-Serverless-2_CP.html) というハンズオン資料が既にあり SAM を使用して Infrastructure as Code（IaC）化されています。  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdodonki1223%2Ftranslate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdodonki1223%2Ftranslate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdodonki1223%2Ftranslate/lists"}