1. 初めに
Container AdamAppに対応したi-PRO Camera SDKでは、アプリの構成をDocker compose構成ファイルに記述することで、様々な構成のコンテナをi-PROカメラ内で動作させることができます。これにより新規機能拡張ソフトウェアをDockerコンテナの形で作成できるようになるほか、すでに他のサーバーやデバイス上で動作しているDockerコンテナが開発済みの場合は、本ドキュメントにしたがって移植を行うことで、簡単にカメラ上で動作させることが可能です。本ドキュメントでは、SDKに含まれるdocker_multi_imagesサンプルアプリを例にして複数コンテナ構成のContainer AdamAppを作成する方法を説明します。
2. 概要
2.1 ユーザー別のアプリ構成選択の指針
既存のAdamApp、AzureIoT用のContainer AdamApp及びext版のContainer AdamAppのそれぞれどれを選択すべきかについては、こちらをご参照ください。
ext形式Container AdamAppは、コンテナの構成をDocker composeの設定ファイル (docker-compose.yaml) で指定することが可能です。docker-compose.yamlファイルでは、サービス名を複数記載することで、複数のコンテナを起動できます。
以下に従来にAdamAppとContainer AdamAppの構成の違いの概念図を示します。
上記は一つの機能拡張ソフトウェア (ext形式のバイナリが一つ) の中で複数のコンテナを動作させる場合の概念図ですが、一方で新Xシリーズカメラでは、複数のアプリをインストールすることが可能なため、独立した複数のアプリを同時に動作させることも可能です。
用途によってどのような構成を選択するかの指針を以下に示します。
番号 | ユースケース | アプリの構成 | 概念図 |
|---|---|---|---|
1 | すでにi-PRO CAMERA SDKを使用して開発したアプリをコンテナ化したい場合 | 既存のアプリをそのままコンテナ化した、一つのコンテナ構成を持つ一つのアプリ | |
2 | i-PROカメラ以外のデバイス向けに開発済みのAIアプリを、i-PROカメラ向けに移植したい場合 | 既存のアプリのAI機能や、映像取得部分をADAM APIに置き換えた、一つのコンテナの構成を持つ一つのアプリ | |
3 | i-PROカメラ以外のデバイス向けに開発済みの、AI機能を持たないアプリを簡単にi-PROカメラ向けに移植したい場合 | i-PROカメラ向け管理機能を持ったコンテナと、既存のアプリが動作するコンテナを含む、二つのコンテナの構成を持つ一つのアプリ | |
4 | i-PROカメラ以外のデバイス向けに開発済みの、OSS等複数のコンテナ構成を持つアプリをi-PROカメラ向けに移植したい場合 | i-PROカメラ向け管理機能を持つコンテナと、既存の複数のコンテナ構成を持つ一つのアプリ | |
5 | アプリ間で直接通信を行うことがなく、開発元も異なる関連性の低い二つのアプリをi-PROカメラ向けに移植したい場合 | 二つのアプリ | |
6 | ADAM APIを使用したいアプリが複数ある場合 | 二つのアプリ |
2.2 複数コンテナ構成でアプリを開発する場合の構成
SDKに含まれるdocker_multi_imagesは、2.1章のユースケース3や4を選んだ場合に参考となるサンプルアプリです。docker_multi_imagesサンプルアプリは2つのDockerイメージから構成されています。
docker_multi_images イメージ
カメラ本体からアプリの開始停止やキープアライブメッセージの応答を行うために存在します。本ドキュメントでは「メインイメージ」と呼びます。また、このイメージから生成されたコンテナを「メインコンテナ」と呼びます。サンプルアプリでは、イベントループを回して待機のみ実施しています。i-PRO CAMERA SDKでビルドします。web イメージ
DockerHubで公開されている 軽量版のnginx をベースにデフォルトの設定ファイル (default.conf) のみを置き換えたイメージとなります。本ドキュメントでは「サブイメージ」と呼びます。また、このイメージから生成されたコンテナを「サブコンテナ」と呼びます。nginxのTCP 80ポートを外部にTCP 8081ポートとして公開し、外部機器からのhttpリクエストを受け付けます。Container AdamAppを作成する際には、事前にDockerイメージとしてビルドされている必要があります。
既存のコンテナをi-PROカメラで動作させたい場合、docker_multi_imagesイメージをカメラからの管理用として新たに追加することで、既存コンテナは少ない変更量でカメラ上で動作させることができます。
2.3 移植にあたっての考慮事項
i-PROカメラ上で既存コンテナを動作させる場合、主に以下三点を考慮する必要があります。
RAM / ROM / CPUリソースが足りるか
データのストレージは必要か
i-PROカメラのセキュリティポリシーに合致しているか
ADAM APIを使用するコンテナは一つだけか
以下ではこれらの内容を説明します。
2.3.1 RAM / ROM / CPUリソース について
新Xシリーズカメラが機能拡張アプリケーションで使用できるリソースは i-PROカメラへのソフトウェアインストール条件 - チュートリアル・FAQ - Development Partner Portal をご参照ください。
移植対象のアプリがこの制限内で動作できることをご確認ください。
RAM/CPUの制限はcgroupsによって行われています。RAM使用量が制限値を超えた場合、OOM Killerによってアプリが強制終了します。
2.3.2 セキュリティポリシーについて
Container AdamAppに関するセキュリティポリシーの詳細は アプリの開発と動作確認方法(Container Adamapp編) - チュートリアル・FAQ - Development Partner Portal (i-pro.com) をご覧ください。
移植に関して特に考慮する内容を説明します。
コンテナはroot権限で動作させることはできません。
カメラ内ではuid 1000、gid 1000のユーザー権限でアプリが動作します。コンテナはread onlyでマウントされます。
コンテナ内に書き込みを行うことはできません。既存のアプリがコンテナ内に書き込みを行っている場合、一時的なデータであればtmpfs、永続的なデータであればボリュームを別途マウントし、そちらに書き込む必要があります。--previledgedなどのセキュリティを緩和するオプションは使用できません。
カメラ内から直接外部のコンテナレジストリよりイメージをpullすることはできません。必要なイメージは開発用PC上でpull、ビルドし、extファイル内に含まれる必要があります。
2.3.3 ADAM APIの使用制限
Container AdamAppに複数のコンテナが含まれている場合、ADAM APIが使用できるコンテナはメインコンテナのみとなり、サブコンテナからは使用できません。
カメラの機能を使用したい場合は、メインイメージ内に実装し、カメラに依存しない汎用的な機能をそのままカメラ上で動かしたい場合はサブイメージ内に実装することをお勧めします。
メインイメージ・サブイメージ間のデータ共有は、3.4章で説明します。
3. 開発手順
3.1 プロジェクトの作成
プロジェクトディレクトリの準備
SDKのサンプルアプリに含まれる iPRO_CAMERA_SDK/src/adamapp/docker_multi_images をコピーし、任意の名前にリネームします。ディレクトリ名がメインイメージのイメージ名と一致するとわかりやすいため、全て小文字にすることを推奨します。
container/docker-compose.yaml に含まれる「docker_multi_images」という文字列をメインイメージの名前に一括変換します。
メインイメージのバイナリ (multiImages) は特に変更する必要はありません。変更する場合は、Configuration.txt及びMakefileの編集も実施する必要が有ります。
アプリの情報記載
configuration.txtを開き以下の項目を編集します。
アプリバージョン名
カメラブラウザの管理画面上に表示されるバージョン情報となります。メインイメージのタグ名と合わせるとわかりやすいです。アプリ名
カメラブラウザの管理画面上に表示されるアプリ名となります。各言語で記述することが可能です。リソース関連情報
アプリが使用するROM/RAM/CPU使用率 (申告値）を記載します。インストール時に他のアプリで申告された値の合計が制限を超えていないかチェックするために使用されます。全アプリの申告値の合計が制限を超える場合、アプリはインストールに失敗します。ライセンス関連情報
i-PROより割り当てられたFUNC IDを指定してください。
3.2 サブイメージ (移植対象イメージ) の準備
既存のコンテナイメージを移植する場合はそのイメージをサブイメージとして作成します。
SDKのビルドスクリプトではサブイメージをビルドしませんので、事前に開発者自身でイメージを用意する必要があります。
別途DockerfileやDocker Composeを利用してサブイメージをビルドします。ビルド時のアーキテクチャ (プラットフォーム) はarm64を指定してください。
以下は、docker_multi_images内に含まれるnginxのイメージの準備を例に説明します。
docker_multi_images/web ディレクトリ以下にnginxのイメージに必要なファイルが含まれています。
web ディレクトリ以下に移動します。
cd [iPRO_CAMERA_SDKディレクトリ]/src/Aadamapp/[アプリディレクトリ]/web
docker imageをビルドします。
docker build -t web:0.0.1-arm64v8 .
dockerイメージがビルドされ開発環境に存在することを確認します。
docker images
出力例
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE web 0.0.1-arm64v8 78a72756f85e 16 hours ago 16.6MB
3.3 docker-compose.yaml の編集
docker-compose.yaml内にサブイメージに関する情報を記載します。 docker-compose.yamlの記述方法自体については、 https://docs.docker.jp/compose/compose-file/index.html などをご参照ください。
ここで編集するdocker-compose.yaml はカメラ内でアプリ起動時に実行されます。
ファイル内でbuild コマンドを使用することはできません。
services キーの子レベルにサブイメージの情報を追加します。 サンプルアプリではすでに記載されていますのでその内容を説明します。
webサービスについての全体の記載は以下となります。
images:
ここには3.2で作成したイメージ名とタグを指定します。ここで指定したイメージが存在しない場合、アプリのビルドスクリプトは失敗します。networks:
コンテナ間で通信したい場合、同じネットワークを指定する必要があります。restart:
コンテナが終了したときにどのように復旧するかを指定します。ext形式Dockerの場合、メインコンテナはDockerの仕組みを使用せずにカメラファームウェアによって監視されるため、noを指定することで、適切に再起動します。一方サブコンテナはカメラファームウェアから監視されませんので、実動作に合わせて設定します。ports:
サブイメージが外部から接続できるポートを公開する場合、[カメラ側]:[コンテナ側]の書式で記載します。volumes:
ボリューム、バインドマウントを記載します。
ボリュームは、サービス名(コンテナ名)と同名のボリューム名のもののみ作成できます。匿名ボリュームは作成できません。
メインコンテナの場合、ボリュームの”target”は “/ai_data” を指定する必要があります。サブコンテナにはこの制限はありません。
ここに定義されているボリューム名は別途yamlファイルトップのvolumes: セクションにも記載する必要があります。
バインドマウントできるディレクトリパスには制限があります。tmpfs:
セキュリティポリシーによりコンテナ内には書き込めないため、/var以下などのアプリが一時的に保存するディレクトリがある場合はここに指定します。
nginxの場合、 /var/cache/nginx、/var/run 以下に書き込みますので、これらをtmpfs として指定しています。必須のパラメータ
以下パラメータはi-RPOカメラのセキュリティポリシーを満たすために付与が必要です。 このままコピー&ペーストしてください。read_only: true user: 1000:1000 cap_drop: - "net_raw" security_opt: - "label=type:ipro-container.process" - "no-new-privileges" labels: com.i-pro.app-type: "ext" com.i-pro.device-category: "CV5x-A" com.i-pro.device-vendor: "i-PRO"ルートレベルのvolumesの記載
yamlファイルのルート (トップ) 以下のvolumes: セクションに、ボリューム名を記載します。
3.4 独自の機能を実装する
3.4.1 コンテナ間の通信やデータ共有
メインイメージ・サブイメージ間や、コンテナとカメラ間でデータをやり取りするには以下の方法があります。
volumeを使用する。
docker-compose.yamlに記載することでvolumeをコンテナ間で共有することができますのでこの中でデータをやり取りできます。ただしこの領域はFlashROM上となり、寿命に影響がありますので大量なデータのやり取りには向きません。共有が許可されているtmpfsを使用する。
ADAM_GetTmpDirPath() APIで取得できる領域はtmpfs上にあり、一時的なデータ保存用として利用できます。
サブコンテナからこの領域にアクセスするためには、docker-compose.yamlのサブイメージの記述内のvolumes: に以下を追加します。- type: bind target: "/dev/shm/Adamapp" source: "/dev/shm/Adamapp" read_only: false consistency: defaultただし、サブコンテナからはADAM_GetTmpDirPath()を呼ぶことができませんので、別途volumeを使う方法などでメインコンテナからパスを通知する必要があります。
HTTP経由で取得する。
Dockerでは各コンテナに仮想のIPアドレスが割り当てられるため、こちらを利用して、カメラ外と同様にWebAPIを呼ぶことができます。また、docker-compose.yamlのhostnameキーでドメイン名を指定すると、この名前で通信を行うこともできます。
メインコンテナでは、ADAMの仕組みとして、sendDataToAdamApplication WEB APIを使用して通信を行うことができます。この仕組みはカメラ本体がメインコンテナにデータを仲介する方法ですので、あて先はカメラ本体のIPアドレスとなります。
また、同様にカメラのCGIを利用してカメラ本体の設定値などを取得することができます。
コンテナ内から仮想環境上のカメラ本体のIPアドレスはコンテナ内から/etc/hostsを参照し、一番最後のエントリの最下位バイトを1にしたものとなります。
WebAPIでアクセスする際、カメラのユーザー名・パスワードの指定が必要です。
3.4.2 サンプルアプリの実装例
docker_multi_imagesサンプルアプリではコンテナ間ネットワークのDNS機能を使用し、メインコンテナからコンテナ名でサブコンテナへhttpリクエストを出すサンプルコードを実装しています。${SDK_DIR}/adamapp/docker_multi_images/main.cpp の response_by_html関数内で以下の様にcurlでリクエストを行うsystem関数を呼び出しています。 ここで “web” はdocker-compose.yamlに記載されているサービス名となります。
char cmd[256];
snprintf( cmd, 256, "curl http://web/index.html > /tmp/local/index.html");
if( system(cmd) != 0 ) {
ADAM_DEBUG_PRINT(ADAM_LV_ERR, "system error (%s)\n", cmd);
}
カメラブラウザの「ソフトウェア管理画面」に表示された、「Dockerマルチイメージ」アプリの「設定画面へ」ボタンを押下することで、このコードが呼び出され、webコンテナのindex.htmlの内容をそのままブラウザに表示します。
3.5 アプリのビルド
開発環境構築については下記を参照ください。
開発環境構築(Install development environment編) - Technology Partner - Confluence (atlassian.net)
アプリ開発方法やビルドについては下記を参照ください。
開発方法(how develop編) - Technology Partner - Confluence (atlassian.net)