🛰️

SORACOM Orbit向けGitHub Actionを作りました

2023/05/22に公開

GitHub

 この記事はSORACOM Orbitの開発・運用をより効率的かつ安全に行うためのGitHub Actionを作ったお話です。

 これまでのSORACOM Orbitの開発とその課題SORACOM Orbitの開発は、基本的には公式ドキュメントに沿って進めていきます。

ざっくりと手順を説明しますと、
開発環境をダウンロードする
環境に含まれているdevContainerを使って開発する
ビルドしたsoraletをSORACOMコンソールないしはSORACOM cliでアップロードする
アップロードしたsoraletをSIMグループに紐付ける
という流れになります。

アップロードされたsoraletはSORACOM内部でバージョン管理が行われており、SIMグループに紐付ける(Orbitの設定をする)際は特定のバージョンか、LATEST(その時の最新のバージョン)を指定します。
さて、この流れでやってると以下のような問題が起こることがあります。
間違えて古いバイナリをアップロードしてしまう
テストをしていないバイナリをアップロードしてしまう
アップロード時のパラメータ指定を間違えて、想定していないsoraletにアップロードしてしまう
アップロード先のsoraletのLATESTを参照しているSIMグループがあって、運用中のシステムに不具合が発生する
SORACOM Orbitの開発/運用以外でも似たような話、結構耳にしますよね？

こういった事故を防ぐためには、ちゃんとCI/CDのパイプラインを作っておくのが大切です。そこで、GitHub Actionを使ってCI/CDのパイプラインを作ってみました。パイプラインを作った件については会社ブログに書いたので、以下の記事を参照してください。
GitHubを活用してSORACOM Orbitの開発を加速する: CI/CD編
さて、上記記事ではひとまずGitHubでのCI/CDは実現できていますが、ワークフロー定義内でSORACOM cliコマンドを駆使していて、シェルスクリプトを書いてるのとほぼ変わらない状態です。これはちょっと美しくないし、使い回しにくいです。そこで、カスタムGitHub Actionを作ってみることにしました。

 soraletをアップロードするカスタムアクションを作るGitHubのカスタムアクションの作り方としては、Dockerを使う方法とjavascript(Node.js)を使う方法があります。

Dockerを使う場合は、SORACOM cliをインストールしたカスタムイメージ内で、SORACOM cliを実行するシェルスクリプトを実行するという実装方法が考えられます。この方法は比較的簡単に実現はできますが、ワークフローファイル内でコマンドを書いているのと変わらないので面白くないですね。そこで今回はjavascriptで作ることにしました。
javascriptで作る場合、action.ymlで指定されたjavascriptファイルがNode.jsで実行されます。そのため、このjavascriptファイルの中でSORACOM APIを呼び出していくことになります。

地道にREST APIの呼び出しを書いていくのもいいですが、SORACOM APIはOpenAPIの定義があるので、OpenAPI Generatorを使ってjavascriptのコードを生成しました。
SORACOM APIのOpenAPI定義はこちらにありますので、これをダウンロードしてきます。

openapi-generatorで出力できる言語はこちらに一覧がありますが、今回はtypescript-nodeを使うことにしました。

適当なディレクトリで以下のコマンドを実行します。
docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate\
 -i /local/soracom-api.ja.yaml\
 -g typescript-node\
 -o /local/out/typescript-node
これでout/typescript-nodeディレクトリにtypescriptのコードが生成されます。

生成されたコードを用いて、以下の機能を実装していきます。
指定されたAuthKeyId/AuthKeyを用いてログインする
指定されたsoralet_idのsoraletがなければ作成する
指定されたsoralet_idのsoraletに、指定されたファイルをアップロードする
アップロード時に「バージョンが多すぎる」とエラーになった場合は、使われていないバージョンのうち最も古いものを消して、再度アップロードする
この削除機能は利用するかどうかを設定で変更できるようにする

実装の詳細は今回は割愛しますが、実際のソースコードを参照してみてください。
kenichiro-kimura/action-soracom-upload-soralet
openapi-generatorで生成されたコードから、2箇所だけ変更を加えています。ここを変更しないとsoraletのアップロードでバイナリーファイルをPOSTできなかったのと、戻り値がうまく取得できませんでした。該当部分は以下になります。
POSTのパラメータでjson:falseとしないとバイナリファイルを正しく処理できない
json:falseとしたので、API呼び出しの戻り値が自動でJSONにマップされないため、JSON.parse()を呼ぶ

 使ってみるさて、それでは実際に使ってみます。ワークフローファイルは以下のようになります。

ワークフローファイルの全体図については、先述のGitHubを活用してSORACOM Orbitの開発を加速する: CI/CD編を参照してください。
name: SORACOM Orbit CI/CD

on:
  push:
    branches:
      - master

env:
  SORALET_ID: soralet-github-action-test
  COVERAGE: jp

jobs:
  build-and-test:
  (ビルド部分省略)
      - name: upload assets
        uses: actions/upload-artifact@v2
        with:
          name: soracom-orbit
          path: build/soralet-optimized.wasm

  deploy:
    runs-on: ubuntu-latest
    needs: build-and-test
    steps:
      - name: download artifact
        uses: actions/download-artifact@v2
        with:
          name: soracom-orbit
      - name: upload
        uses: kenichiro-kimura/action-soracom-upload-soralet@1.2.0
        id: upload
        with:
          soracom_auth_key: ${{ secrets.AUTH_KEY }}
          soracom_auth_key_id: ${{ secrets.AUTH_KEY_ID}}
          soracom_coverage: ${{ env.COVERAGE }}
          soracom_soralet_id: ${{ env.SORALET_ID }}
          soracom_soralet_filename: soralet-optimized.wasm
          soracom_delete_old_soralet: true
uploadステップで、今回作ったカスタムアクションを使ってsoraletをアップロードしています。

masterブランチにpushされたときに、soraletがアップロードされるようになりましたので、「間違って古いものをアップロードする」「パラメータを間違えて別のsoraletにアップロードする」という事故は防げるようになりました。

 ステージング環境を作りたいしかし、これではアップロード先のsoraletのLATESTバージョンが常にmasterブランチのもので更新されます。できればステージング環境にアップロードして、動作検証をしたいところです。ステージング環境を実現するには、deployジョブを例えば以下のようにするという手が考えられます。
on:
  push:
    branches:
      - master
      - staging
env:
  SORALET_ID_PROD: soralet-github-action-test
  SORALET_ID_STG: soralet-github-action-test-staging
  COVERAGE: jp
(省略)
  deploy:
    runs-on: ubuntu-latest
    needs: build-and-test
    steps:
      - name: download artifact
        uses: actions/download-artifact@v2
        with:
          name: soracom-orbit
      - name: upload to staging
        uses: kenichiro-kimura/action-soracom-upload-soralet@1.2.0
        id: upload-staging
        if: github.ref == 'refs/heads/staging'
        with:
          soracom_auth_key: ${{ secrets.AUTH_KEY }}
          soracom_auth_key_id: ${{ secrets.AUTH_KEY_ID}}
          soracom_coverage: ${{ env.COVERAGE }}
          soracom_soralet_id: ${{ env.SORALET_ID_STG }}
          soracom_soralet_filename: soralet-optimized.wasm
          soracom_delete_old_soralet: true
      - name: upload to production
        uses: kenichiro-kimura/action-soracom-upload-soralet@1.2.0
        id: upload-prod
        if: github.ref == 'refs/heads/master'
        with:
          soracom_auth_key: ${{ secrets.AUTH_KEY }}
          soracom_auth_key_id: ${{ secrets.AUTH_KEY_ID}}
          soracom_coverage: ${{ env.COVERAGE }}
          soracom_soralet_id: ${{ env.SORALET_ID_PROD }}
          soracom_soralet_filename: soralet-optimized.wasm
          soracom_delete_old_soralet: true
本番環境用とは別にステージング環境用のsoraletを作成し、stagingブランチにpushすると、そちらを更新するようにします。

そして、ステージング環境用のSIMグループはSORALET_ID_STGのLATESTを使うように設定します。本番環境用のSIMグループはSORALET_ID_PRODのLATESTを使うように設定します。
とりあえずこれでうまくいきますが、ステージング環境だけでなく開発環境も・・・と、環境が増えるたびにSIMグループだけでなくsoraletも増えることになります。せっかくSORACOMプラットフォーム側でsoraletのバージョンが管理されているのですから、もうちょっとスマートにやりたいところです。

それぞれの環境がLATESTを参照しているからsoraletを分割しないといけなかったわけですから、手順で行けば以下のようにしてあげればいいことになります。
アップロード先のsoraletはSORALET_IDにする
ステージング環境はSORALET_IDのLATESTを参照するように設定する
本番環境は、SORALET_IDの特定のバージョンを参照するように設定する

stagingならびにmasterブランチにpushされたら、SOLALET_IDにアップロードする。これによってステージング環境は最新のsoraletになる

masterブランチにpushされたときは、アップロードした新しいバージョンを参照するように本番環境の設定を変更する
図で表すとこんな感じです。
つまり、必要になるのは「SIMグループのOrbitの設定を変更する」カスタムアクションです。次はこれを作ります。

 SIMグループのOrbitの設定を変更するカスタムアクションを作る作り方は基本的にアプロード用のカスタムアクションと同様です。OpenAPI Generatorで出力した、SORACOM APIを叩くtypescriptを使います。

そして、以下の機能を実装します。
生成されたコードを用いて、以下の機能を実装していきます。
Orbitの設定に必要なパラメータを指定する
指定されたAuthKeyId/AuthKeyを用いてログインする
指定されたGroupIDのSIMグループのOrbitの設定を更新する。
Orbitの設定で指定するパラメータは以下の通りです。


パラメータ名
必須
説明


CodeSRN
〇
soraletのSRN

Direction
〇

uplinkまたはdownlinkまたはuplink,downlink


ContentType

デフォルトはapplication/json


Enabled

デフォルトはfalse


UseLocation

デフォルトはfalse


UseMetadata

デフォルトはfalse


そして、パラメータのCodeSRNに、アップロードステップの出力に含まれるsrnを渡してやればOKです。
実装の詳細は今回は割愛しますが、実際のソースコードを参照してみてください。
kenichiro-kimura/action-soracom-configure-orbit

 使ってみる早速使ってみましょう。デプロイ部分を以下のように変更します。
on:
  push:
    branches:
      - master
      - staging

env:
  SORALET_ID: soralet-github-action-test
  COVERAGE: jp

jobs:
(省略)
  deploy:
    runs-on: ubuntu-latest
    needs: build-and-test
    steps:
      - name: download artifact
        uses: actions/download-artifact@v2
        with:
          name: soracom-orbit
      - name: upload
        uses: kenichiro-kimura/action-soracom-upload-soralet@1.2.0
        id: upload
        with:
          soracom_auth_key: ${{ secrets.AUTH_KEY }}
          soracom_auth_key_id: ${{ secrets.AUTH_KEY_ID}}
          soracom_coverage: ${{ env.COVERAGE }}
          soracom_soralet_id: ${{ env.SORALET_ID }}
          soracom_soralet_filename: soralet-optimized.wasm
          soracom_delete_old_soralet: true
      - name: deploy
        uses: kenichiro-kimura/action-soracom-simgroup-soralet@1.0.0
        if: github.ref == 'refs/heads/master'
        with:
          soracom_auth_key: ${{ secrets.AUTH_KEY }}
          soracom_auth_key_id: ${{ secrets.AUTH_KEY_ID}}
          soracom_coverage: ${{ env.COVERAGE }}
          soracom_soralet_code_srn: ${{ steps.upload.outputs.soralet_srn }}
          soracom_soralet_direction: uplink
          soracom_soralet_enabled: true
          soracom_group_id: ${{ secrets.SORACOM_GROUP_ID }}
スッキリしましたね！

ステージを増やしたくなったら、条件とグループIDを変えたdeployステップを追加するだけでOKです。

 今回作ったアクション今回作ったアクションの、GitHub Marketplaceでのリンクは以下になります。
Upload Soralet
Update SORACOM Orbit configuration

 まとめSoraletのコードは小規模で、それほど頻繁に更新されることもないからCI/CDパイプラインまで作るほどではない・・・と思われている方も多いかもしれません。

しかし、Orbitがデバイスとのデータのやり取りの部分に必ず挟まるということを考えると、soraletの更新はSORACOMプラットフォーム(ならびにOrbit)を使ったみなさまのシステムの動作全体に影響することになります。つまり、運用中のシステムでのOrbitの設定ミスは、システム全体の事故につながるということです。
重大な事故を避け、安心して開発を行うためにはやはり開発初期段階でCI/CDパイプラインを組んでおくのが重要だといえます。
今回私が作ったカスタムアクションを使えば、このCI/CDパイプラインは短期間で構築できます(必要なのはSIMグループならびにGitHubのシークレット設定程度で、ほぼコピペで作れる)。

皆様のsoralet開発並びに運用のお役に立てれば幸いです。

パラメータ名	必須	説明
CodeSRN	〇	soraletのSRN
Direction	〇	`uplink`または`downlink`または`uplink,downlink`
ContentType		デフォルトは`application/json`
Enabled		デフォルトは`false`
UseLocation		デフォルトは`false`
UseMetadata		デフォルトは`false`

GitHubで編集を提案

この記事は

これまでのSORACOM Orbitの開発とその課題

soraletをアップロードするカスタムアクションを作る

使ってみる

ステージング環境を作りたい

SIMグループのOrbitの設定を変更するカスタムアクションを作る

使ってみる

今回作ったアクション

まとめ

Discussion