Versions Compared

Old Version 4

changes.mady.by.user Tachibana Yuta (立花 裕太)

Saved on

compared with

New Version 5

changes.mady.by.user Yoshitaka Fukushima (福島 佳孝)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

1. 初めに

Container AdamAppに対応したi-PRO Camera SDKでは、アプリの構成をDocker compose構成ファイルに記述することで、様々な構成のコンテナをi-PROカメラ内で動作させることができます。これにより新規機能拡張ソフトウェアをDockerコンテナの形で作成できるようになるほか、すでに他のサーバーやデバイス上で動作しているDockerコンテナが開発済みの場合は、本ドキュメントにしたがって移植を行うことで、簡単にカメラ上で動作させることが可能です。本ドキュメントでは、SDKに含まれるdocker_multi_imagesサンプルアプリを例にして複数コンテナ構成のContainer AdamAppを作成する方法を説明します。

2. 概要

2.1 ユーザー別のアプリ構成選択の指針

Info

既存のAdamApp、AzureIoT用のContainer AdamApp及びext版のContainer AdamAppのそれぞれどれを選択すべきかについては、こちらをご参照ください。

...

以下に従来にAdamAppとContainer AdamAppの構成の違いの概念図を示します。

Drawio
simple
mVer2
simple0
zoom1
0inComment0
custContentId1528037395
pageId14748884881536098552
lboxcustContentId11544618761
diagramDisplayNameadam_vs_containeradam.drawio
lbox1
contentVer1
revision12
baseUrlhttps://iproiot.atlassian.net/wiki
diagramNameadam_vs_containeradam.drawio
pCenter0
width1020.5
links
tbstyle
height1060.51070

上記は一つの機能拡張ソフトウェア (ext形式のバイナリが一つ) の中で複数のコンテナを動作させる場合の概念図ですが、一方で新Xシリーズカメラでは、複数のアプリをインストールすることが可能なため、独立した複数のアプリを同時に動作させることも可能です。

...

番号

ユースケース

アプリの構成

概念図

1

すでにi-PRO CAMERA SDKを使用して開発したアプリをコンテナ化したい場合

既存のアプリをそのままコンテナ化した、一つのコンテナ構成を持つ一つのアプリ

Drawio
mVer2
simple0
zoom1
inComment0
pageId1474888488
custContentId1532854940
diagramDisplayName名称未設定ファイル-1725850726446.drawio
lbox1
contentVer2
revision2
baseUrlhttps://iproiot.atlassian.net/wiki
diagramName名称未設定ファイル-1725850726446.drawio
pCenter0
width431.0000000000001
links
tbstyle
height320.99999999999994

2

i-PROカメラ以外のデバイス向けに開発済みのAIアプリを、i-PROカメラ向けに移植したい場合

既存のアプリのAI機能や、映像取得部分をADAM APIに置き換えた、一つのコンテナの構成を持つ一つのアプリ

3

i-PROカメラ以外のデバイス向けに開発済みの、AI機能を持たないアプリを簡単にi-PROカメラ向けに移植したい場合

i-PROカメラ向け管理機能を持ったコンテナと、既存のアプリが動作するコンテナを含む、二つのコンテナの構成を持つ一つのアプリ

Drawio
mVer2
simple0
zoom1
inComment0
pageId1474888488
custContentId1532593214
diagramDisplayNameコンテナケース3-1725850796064.drawio
lbox1
contentVer2
revision2
baseUrlhttps://iproiot.atlassian.net/wiki
diagramNameコンテナケース3-1725850796064.drawio
pCenter0
width451
links
tbstyle
height321

4

i-PROカメラ以外のデバイス向けに開発済みの、OSS等複数のコンテナ構成を持つアプリをi-PROカメラ向けに移植したい場合

i-PROカメラ向け管理機能を持つコンテナと、既存の複数のコンテナ構成を持つ一つのアプリ

Drawio
mVer2
simple0
zoom1
inComment0
pageId1474888488
custContentId1533116887
diagramDisplayName複数コンテナケース4.drawio
lbox1
contentVer2
revision2
baseUrlhttps://iproiot.atlassian.net/wiki
diagramName複数コンテナケース4.drawio
pCenter0
width601
links
tbstyle
height321

5

アプリ間で直接通信を行うことがなく、開発元も異なる関連性の低い二つのアプリをi-PROカメラ向けに移植したい場合

二つのアプリ

Drawio
mVer2
simple0
zoom1
inComment0
pageId1474888488
custContentId1532822385
diagramDisplayName複数コンテナケース5.drawio
lbox1
contentVer2
revision2
baseUrlhttps://iproiot.atlassian.net/wiki
diagramName複数コンテナケース5.drawio
pCenter0
width631
links
tbstyle
height321

6

ADAM APIを使用したいアプリが複数ある場合

二つのアプリ

2.2 複数コンテナ構成でアプリを開発する場合の構成

SDKに含まれるdocker_multi_imagesは、2.1章のユースケース3や4を選んだ場合に参考となるサンプルアプリです。docker_multi_imagesサンプルアプリは2つのDockerイメージから構成されています。

...

既存のコンテナをi-PROカメラで動作させたい場合、docker_multi_imagesイメージをカメラからの管理用として新たに追加することで、既存コンテナは少ない変更量でカメラ上で動作させることができます。

Drawio
custContentId
mVer2
simple0
zoom1
simple0
inComment0
1491337304pageId14748884881536098552
lboxcustContentId11544815116
diagramDisplayNamedocker_multi_images構成.drawio
lbox1
contentVer1
revision12
baseUrlhttps://iproiot.atlassian.net/wiki
diagramNamedocker_multi_images構成.drawio
pCenter0
width721
links
tbstyle
height791

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 をコピーし、任意の名前にリネームします。ディレクトリ名がメインイメージのイメージ名と一致するとわかりやすいため、全て小文字にすることを推奨します。

...

メインイメージのバイナリ (multiImages) は特に変更する必要はありません。変更する場合は、Configuration.txt及びMakefileの編集も実施する必要が有ります。

アプリの情報記載

configuration.txtを開き以下の項目を編集します。

  • アプリバージョン名
    カメラブラウザの管理画面上に表示されるバージョン情報となります。メインイメージのタグ名と合わせるとわかりやすいです。

  • アプリ名
    カメラブラウザの管理画面上に表示されるアプリ名となります。各言語で記述することが可能です。

  • リソース関連情報
    アプリが使用するROM/RAM/CPU使用率 (申告値）を記載します。インストール時に他のアプリで申告された値の合計が制限を超えていないかチェックするために使用されます。全アプリの申告値の合計が制限を超える場合、アプリはインストールに失敗します。

  • ライセンス関連情報
    i-PROより割り当てられたFUNC IDを指定してください。

3.2 サブイメージ (移植対象イメージ) の準備

既存のコンテナイメージを移植する場合はそのイメージをサブイメージとして作成します。

...

  • docker_multi_images/web ディレクトリ以下にnginxのイメージに必要なファイルが含まれています。

  • web ディレクトリ以下に移動します。

    Code Block
    cd [iPRO_CAMERA_SDKディレクトリ]/src/Aadamapp/[アプリディレクトリ]/web

  • docker imageをビルドします。

    Code Block
    docker build -t web:0.0.1-arm64v8 .

  • dockerイメージがビルドされ開発環境に存在することを確認します。

    Code Block
    docker images

    出力例

    Code Block
    $ 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 などをご参照ください。

...

  • services キーの子レベルにサブイメージの情報を追加します。 サンプルアプリではすでに記載されていますのでその内容を説明します。

  • webサービスについての全体の記載は以下となります。

    image-20240909-101606.png

  • images:
    ここには3.2で作成したイメージ名とタグを指定します。ここで指定したイメージが存在しない場合、アプリのビルドスクリプトは失敗します。

  • networks:
    コンテナ間で通信したい場合、同じネットワークを指定する必要があります。

  • restart:
    コンテナが終了したときにどのように復旧するかを指定します。ext形式Dockerの場合、メインコンテナはDockerの仕組みを使用せずにカメラファームウェアによって監視されるため、noを指定することで、適切に再起動します。一方サブコンテナはカメラファームウェアから監視されませんので、実動作に合わせて設定します。

  • ports:
    サブイメージが外部から接続できるポートを公開する場合、[カメラ側]:[コンテナ側]の書式で記載します。

  • volumes:
    ボリューム、バインドマウントを記載します。
    volumeはこのdocker-compose.yaml内で定義されているボリュームのみ指定できます。また、ここに定義されているvolume名は別途yamlファイルトップのvolumesボリュームは、サービス名(コンテナ名)と同名のボリューム名のもののみ作成できます。匿名ボリュームは作成できません。
    メインコンテナの場合、ボリュームの”target”は “/ai_data” を指定する必要があります。サブコンテナにはこの制限はありません。
    ここに定義されているボリューム名は別途yamlファイルトップのvolumes: セクションにも記載する必要があります。
    バインドマウントできるディレクトリパスには制限があります。

  • tmpfs:
    セキュリティポリシーによりコンテナ内には書き込めないため、/var以下などのアプリが一時的に保存するディレクトリがある場合はここに指定します。
    nginxの場合、 /var/cache/nginx、/var/run 以下に書き込みますので、これらをtmpfs として指定しています。

  • 必須のパラメータ
    以下パラメータはi-RPOカメラのセキュリティポリシーを満たすために付与が必要です。 このままコピー&ペーストしてください。

    Code Block
        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: セクションに、ボリューム名を記載します。

    image-20240801-032019.png

3.4 独自の機能を実装する

3.4.1 コンテナ間の通信やデータ共有

メインイメージ・サブイメージ間や、コンテナとカメラ間でデータをやり取りするには以下の方法があります。

...

Info

コンテナ内から仮想環境上のカメラ本体の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に記載されているサービス名となります。

...

カメラブラウザの「ソフトウェア管理画面」に表示された、「Dockerマルチイメージ」アプリの「設定画面へ」ボタンを押下することで、このコードが呼び出され、webコンテナのindex.htmlの内容をそのままブラウザに表示します。

3.5 アプリのビルド

開発環境構築については下記を参照ください。

開発環境構築(Install development environment編) - Technology Partner - Confluence (atlassian.net)

...