株式会社メドレー の技術ブログ
全1406件
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ https://www.medley.jp/jobs/
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
自己紹介 株式会社メドレーのエンジニア阪本です。 9 月に入っても暑い日が続く中、皆さんはいかがお過ごしでしょうか。 前回のブログでも書きましたが私は野球観戦（虎党）が趣味で、毎日の試合結果に一喜一憂しています。 このブログの執筆時点ではセ・リーグは首位巨人にマジックが点灯し、残試合 50 を切った状況でのゲーム差 10。優勝を目指す阪神にとっては厳しい状況となりましたが、残り直接対決をすべて勝てば可能性は見えてくるはず。ここは諦めずに応援しようと思います。 次の記事を書く頃には何らかの決着が着いていると思いますので、その時には喜びのメッセージが書ける事を願っています。 はじめに 突然ですが、皆さんは Fargate を使いこなしていますか？ 今まで ECS(EC2)での運用がメインでしたが、ジョブメドレーのシステムでも Fargate に触れる機会が増えてきました。 筆者自身は初めての Fargate でしたが、EC2 の存在が無くなることに不思議な感覚を覚えつつも、管理するものが減って運用が楽になったと実感しています。 しかし、EC2 が無くなった事によりサーバ内にターミナルで入る手段を失いました。 公式の ガイド では 質問２：コンテナの中に ssh や docker exec で入ることは出来ますか？ こちら現状サポートしておりませんが、コンテナワークロードでは「 同一の環境でしっかりテストを行う 」ことや「 ログを外部に全て出す 」ことがベストプラクティスとされていて、コンテナに入る必要性を出来る限り減らす方が将来的にも好ましいです。 と「事前にテストを十分に実施する」「ログは(S3 や CloudWatchLogs など)外部に出力する」 さえ出来ていれば入る必要が無いはずと記載されているものの・・・心配性な自分は不測の事態が発生した時の事を考えてサーバに入る手段を求めてしまいます。 そこで代替手段を模索していた所、 SessionManager を使えば可能との文献を見つけました。 すでに SessionManager 自体は EC2 に対して運用を行っていたため導入の敷居は低いと考え、この手段を採用することにしました。 Session Manager とは？ Session Manager とは AWS の Systems Manager サービスの 1 機能で、AWS 上で管理しているサーバ（マネージドインスタンス）に対してターミナルのアクセスを可能にするものです。 ターミナルへのアクセス手段は、よくある手段だと SSH がありますが この方法は SSH ポートを外部に開放する必要があるため攻撃の対象になりやすく、あまり好ましくありません。 それに比べて Session Manager は SSH ポートの開放は不要でサーバから見てアウトバウンド方向の HTTPS 通信の確保で済む為、外部からの攻撃も受けず安全にアクセス経路の確保が実現できます。 ※通信経路の確保以外にも IAM ロールの設定などが必要となります。詳しくは こちら を参考 「AWS 上で管理しているサーバ」と先に記載しましたが、このサーバは EC2 インスタンスに限らないのが本記事の重要なポイントになります。 オンプレミスなサーバも AWS 上で管理されているのであれば、SessionManager エージェントをインストールする事により管理対象に含めることが可能になるのです。 今回は EC2 で動いていた SessionManager エージェントを Fargate で動くコンテナにインストールする事によりコンテナ自体をサーバと見立ててマネージドインスタンスとし、SessionManager でアクセスする事を目指します。 対応 Systems Manager インスタンス枠をスタンダードからアドバンスドに変更する ／ AWS コンソールでの設定 オンプレミスなサーバに SessionManager にてアクセスする場合、Systems Manager のオンプレミスインスタンスティアを スタンダードからアドバンスドへと変更する必要 があります。 この変更作業は AWS コンソールから行う事になりますが、アドバンスドへの変更に当たって既存のマネージドインスタンスに影響することはありません。 ただし、この逆の場合、スタンダードに戻す際には考慮が必要となるので こちら を参照ください。 SSM Agent のインストール ／ コンテナに対する設定 ここからは実際に動くコンテナに対する設定になります。 AWS のドキュメント 手動でインストール SSM エージェント EC2 で Linux のインスタンス を参考に、OS に合った方法で SessionManager エージェントのインストールを行います。 インストール作業には通信などの時間が必要となるので、事前にコンテナイメージにインストールする形としました。 コンテナをマネージドインスタンスとして登録する ／ コンテナに対する設定 コンテナをマネージドインスタンスとして登録するため、コンテナのスタートアップ(Entrypoint)にて下記スクリプトを実行します。 # 1. ハイブリッドアクティベーションの作成 SSM_ACTIVATE_INFO = ` aws ssm create-activation --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances --registration-limit 1 --region ap-northeast-1 --default-instance-name medley-blog-fargate-container` # 2. アウトプットからアクティベーションコード/ID の抽出 SSM_ACTIVATE_CODE = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationCode'` SSM_ACTIVATE_ID = ` echo $SSM_ACTIVATE_INFO | jq -r '.ActivationId'` # 3. コンテナ自身をマネージドインスタンスへの登録 amazon-ssm-agent -register -code $SSM_ACTIVATE_CODE -id $SSM_ACTIVATE_ID -region "ap-northeast-1" # 4. SessionManager エージェントの起動 amazon-ssm-agent & これらのコマンドについては各行ごとに説明します 1.ハイブリッドアクティベーションの作成 マネージドインスタンス登録に必要なアクティベーションコード/ID 取得のため、ハイブリッドアクティベーションの登録を行います。 後々 AWS コンソールにてインスタンスの識別ができるように、 --default-instance-name オプションにて medley-blog-fargate-container という名前を付与しています。 このコマンドのアウトプットにて下記のような JSON が返される為、一旦変数に格納しています。 { "ActivationId" : "<<アクティベーション ID>>", "ActivationCode": "<<アクティベーションコード>>" } また --iam-role オプションでサービスロール AmazonEC2RunCommandRoleForManagedInstances を使っています。 このロールがまだ存在しない場合、AWS コンソールからハイブリッドアクティベーションから IAM ロール →「必要な権限を備えたシステムのデフォルトコマンド実行ロールを作成」により作成してください。 2. アウトプットからアクティベーションコード/ID の抽出 前項のアウトプットからアクティベーションコード/ID を個々の変数に分離しています。 3. コンテナ自身をマネージドインスタンスへの登録 取得したアクティベーションコード/ID を利用し、コンテナ自身をマネージドインスタンスとして登録します。 環境変数 AWS_DEFAULT_REGION のように AWS の Credential にてデフォルトの Region 設定があった場合でも、このコマンドではオプションで Region 指定が必須となるのでご注意ください。 4. SessionManager エージェントの起動 最後に SessionManager エージェントを起動します。 これにより AWS との通信が確立され、SessionManager が利用できるようになります。 この状態でマネージドインスタンス画面にて目的のインスタンスが「オンライン」であれば設定が完了です。 接続確認 設定が完了したので、実際に SessionManager にて接続してみます。 AWS コンソールのセッションマネージャからセッションの開始を選択し、名前が事前に登録した medley-blog-fargate-container であるものを選択します。 外見は他の EC2 と変わらない表示ですが、この手段で登録したものはインスタンス ID が mi から始まる ID になります(通常の EC2 は i から始まる ID)。 後は普段通りにセッションを開始するとコンテナ内へのアクセスが開始されます。 これで EC2 の無い Fargate 上のコンテナに対してもターミナルに入ることができました。 運用してみての感想 Fargate 上のコンテナに直接入ることにより、今まで出来なかった top コマンドによるプロセス状態の確認 df コマンドによる Disk 容量の確認 などの環境調査が出来るようになりました。 利用頻度が多い訳ではありませんが、調査の選択肢を増やす事により有事の際の早期対応に繋げれられていると感じています。 注意点 ここからは運用に当たっての注意点について数点紹介します。 料金 EC2 での SessionManager と違い、 この方法で登録したサーバへの SessionManager 通信は料金が発生します 。 正確には 「SessionManager エージェントが起動し AWS と通信が確立している状態」 での時間課金で SessionManager での接続有無は問いません。 よって、常時必要ではない場合は SessionManager エージェントを止めて節約する方法を検討してください。 アクティベーションやマネージドインスタンスがリストに残る コンテナ終了時でも AWS コンソールのハイブリッドアクティベーション一覧やマネージドインスタンス一覧に表示が残ってしまうようです。 一覧の上限の記載は見つからなかったものの、無限に増えるとも思えないので適時 Lambda を使って削除しています。 SessionManager での操作について EC2 インスタンスに対しての SessionManager と同様ですが、セッション開始直後のユーザは ssm-user 固定になるようです。 特定ユーザでの操作が必要となる場合、 su コマンドでのユーザ切り替えが必要になります。 さいごに 今回のようにメドレーでは新たな技術を取り入れつつ、サービスの安定を目的とした様々な施策を導入しています。 こういった働き方に興味を持たれた方、まずは下記リンクからお気軽にお話しませんか？ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! https://www.medley.jp/jobs/
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! メドレーで働く｜株式会社メドレー メドレーでの働き方や人事制度、求人情報など、採用に関する情報をご紹介します。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 https://www.medley.jp/jobs/
こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp
こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp