Table of contents
...
Table of Contents | ||||
---|---|---|---|---|
|
Overview
...
Here we will explain the steps to build the iPRO Camera SDK app using the Azure IoT Edge container and check its operation. Also, in this tutorial, the SDK installation directory is described as ${SDK_DIR}
.
Info |
---|
This tutorial only supports SDK ver.2.00 or later. Please note that it cannot be used with SDK ver.2.00 or lower. |
Operation confirmation procedure
...
Create a new IoT Edge Solution on Visual Studio Code
The following describes the case where the sample app to be referenced is skeleton_sample_app for the C version, additional_info_sample_app for the Python version, and test_app for the Edge Solution to be created. Please note that the Edge Solution name must be in all lowercase letters. Please see below for details.
https://docs.docker.com/reference/cli/docker/image/tag/
Description of C version/Python version application
Info |
---|
The operation confirmation method for both the C version and Python version of the application is almost the same. This page will explain using the C version as an example, and the different parts will be explained as appropriate. Also, the application path is as follows, so please read it as appropriate. C version app path Python version app path |
...
Enter the information for the container registry to which you want to push the created image.
Info |
---|
This document uses Azure Container Registry administrator login credentials to speed up development and testing. In production environments, we recommend using least-privilege authentication options like service principals or repository-scoped tokens. Please see here for details. |
Log in to Azure portal(Cloud Computing Services | Microsoft Azure) and select the container registry you want to target. The screen below is an example.
...
Display "Settings" - "Access Keys" from the left menu.
...
Based on the information displayed, enter the following:
...
When using the container registry operated by i-PRO to build a development environment, please use the values in the table below for each item in the explanation below. If you want to prepare a container registry yourself, please refer to the documentation of the container registry you are using to obtain the values.
container registry name | iprocamsdk |
login server | http://iprocamsdk.azurecr.io |
user name | [Separately notified user name] |
password | [Separately notified password] |
repository name | [Separately notified repository name] |
Enter the following based on the information you obtained.
${SDK_DIR}
\src\adamapp\test_app\container\deployment.template.json
Enter “registryCredentials” in the above file as follows.Code Block "registryCredentials": { "[container registry name]": { "username": "$CONTAINER_REGISTRY_USERNAME_[container registry name]", "password": "$CONTAINER_REGISTRY_PASSWORD_[container registry name]", "address": "[login server]" } }
For example, if in the container registry name is “iprocv5xcontainerregistry” and the container registry login server is “iprocv5xcontainerregistry.azurecr.io”, it will case of a container registry operated by i-PRO, it would be as follows.
...
${SDK_DIR}
\src\adamapp\test_app\container\modules\test_app\module.json
Enter “repository” in the above file as follows.Code Block "repository": "[login server]/[repository name]/test_app"
If For example, if the container registry login server is "iprocv5xcontainerregistry“iprocamsdk.azurecr.io"io” and the repository name is “dev/company-a”, it will be as follows.
${SDK_DIR}
\src\adamapp\test_app\container
Create an .env file in the directory, write the container registry user name and password, and save it.Code Block CONTAINER_REGISTRY_USERNAME_[container registry name]=[user name] CONTAINER_REGISTRY_PASSWORD_[container registry name]=[password]
An example is shown below.
...
Coding the app
Now code as you like on Visual Studio Code. If you copy skeleton_sample_app etc., the source file name will be the one before copying (skeletonSampleApp.cpp for skeleton_sample_app), so please rename it if necessary. Below is an example.
...
Code Block |
---|
${SDK_DIR}\src\adamapp\test_app\Makefile Before PROG_NAME= SkeletonSampleApp After PROG_NAME= TestApp ${SDK_DIR}\src\adamapp\test_app\configuration.txt Before APPLICATION SkeletonSampleApp After APPLICATION TestApp ${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json Before "APPLICATION_NAME=SkeletonSampleApp" After "APPLICATION_NAME=TestApp" |
Build the app
When building, use the built-in functionality of the Azure IoT extension. In Visual Studio Code's Explorer Right-click on "${SDK_DIR}
\src\adamapp\test_app\container\deployment.template.json" to display the build menu.
Select “Build IoT Edge Solution”. This operation only performs a build.
For your first build, you will be asked to log in to your container registry. The following is an example when the container registry is "iprocv5xcontainerregistry.azurecr.io".The Dockerfile provided with the SDK acquires the image from the i-PRO container registry and builds the image, so for the first build, you will be asked to log in to the container registry. Below is an example of an error message.
Code Block |
---|
ERROR: failed to solve: iprocv5xcontainerregistryiprocamsdk.azurecr.io/sdk/cadamappbase:1.0.0.2: failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized |
At this time, enter the following command on the Visual Studio Code terminal.
Code Block |
---|
docker login iprocv5xcontainerregistryiprocamsdk.azurecr.io |
Then enter Enter the Username and Password that are then displayed. Enter the container registry user name and password.
...
ID and password. If you wish to use i-PRO's container registry, please log in using the username and password provided to you.
Code Block |
---|
Username: [user name]
Password: [password] |
If you want to use your own container registry, enter the following:
Code Block |
---|
Username: sdk-containeradam-ro
Password: H291gWcZ7Tg6Eph+TbTrsDKyYgHLtWq1vQHPuxIOZb+ACRADu2w4 |
If Login Succeeded
is displayed, the login is successful.Next, right-click "
Note |
---|
Please do not share your Username and Password with others. Please note that this information is subject to change, so please always check for the latest information. |
Then right click on ${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json " and Select “Build Build and Push IoT Edge Solution”Solution. This operation builds and pushes to the container registry.
The build is done by running Docker buildx build as described in the Dockerfile.arm64v8 azureIoT file located under “ ${SDK_DIR}\src\adamapp\test_app\”. The environment name (arm64v8) after Dockerfile. is the architecture selected in the above step. (You can see the current architecture at the bottom of Visual Studio Code)
...
Check the built image
...
Info |
---|
If you use your own container registry, Build and Push IoT Edge Solution will cause the push to fail. This is because there is a restriction that prevents you from logging into multiple container registries at the same time. Therefore, in this case, after building the image with Build IoT Edge Solution, log back into the push destination container registry and push the image manually. |
Check the built image
If the build is successful, you can check the existence of the image with docker images. Below is an example.
Code Block |
---|
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE iprocv5xcontainerregistry.azurecr.io/azureiot/test_app 0.0.5-arm64v8 f1772ccfed77 35 minutes ago 91.4MB |
Deploy to camera
Select the device you want to deploy from under "AZURE IOT HUB" in the bottom left, right-click and select "Deploy to one IoT Edge" to deploy it to the camera. What to deploy Follows "${SDK_DIR}
\src\adamapp\test_app\container\deployment.template.json".
...
Deployment Succeeded
is displayed, the deployment is successful.
...
Check runtime status on Azure
Log in to the Azure portal(Cloud Computing Services | Microsoft Azure) and select the IoT Edge device you added on the IoT Hub - IoT Edge screen.
...
Info |
---|
The runtime status will be "Error" for a while after deployment. It takes time to become "running". However, the amount of time required to become "running" depends on the app. |
Check the operation of the app
Access the URL below with a PC that can connect to the camera.
...
You can check the app operation as below. Below is an example of running skeleton_sample_app.
...
Controlling Container version Adamapp using Azure IoT Explorer
...
It is possible to control and check the Container version of Adamapp using Azure IoT Explorer published by Microsoft. The following describes the installation and initial settings of Azure IoT Exporlor.
Install
Follow Install and use Azure IoT explorer - Azure IoT | Microsoft Learn and install Azure IoT Explorer on your PC.
Initial setting
When you start Azure IoT Explorer, the following initial screen will appear, so select "Connect via IoT Hub connection string".
...
Select the device you want to check from the displayed device (camera) list.
Checking the setting values with ModuleTwin
The settings values listed in the app settings (AppPrefs.json) can be checked from the cloud using Azure IoT's ModuleTwin mechanism.
...
Info |
---|
Setting values are read-only. |
Setting the operation schedule
Use ModuleTwin to set the time zone in which the application will run.
...
After entering the settings, press "Save" at the top of the screen to apply the settings to the camera.
Up to 8 can be set.
If it is within any of the configured times, Container AdamApp for Azure IoT Edge will work.
If the inference end time is later than the inference start time, the inference end time represents the next day.
If scheduleField is empty, it will always operate.
If the information is incorrect, the application will not start.
Stop/start decisions are made at 15 second intervals. Therefore, the start and stop times will be delayed by up to 15 seconds.
Sending telemetry data from the device via cloud communication
Sending telemetry data
Telemetry data can be sent from the device via cloud communication by calling the ADAM_SendTelemetry() function, which is valid only for Container AdamApp for Azure IoT Edge.
Please specify values in JSON format for the arguments of this API. Please see the API specification for details.
Device-to-cloud communication has a limit on the number of times it can communicate depending on the Azure IoT Hub settings. Please check here for more details.
To control communication, sending is set to OFF by default. In order to send to the cloud, you must first turn on the sending function.
There are two ways to turn on the transmission function: Module direct method and Module twin desired property. Please see below.
How to turn on using module direct method
Select the target Container Adamapp for Azure IoT Edge in Azure IoT Explorer.
Select "Module direct method" from the left menu. You can send a direct method on the screen below.
...
The results will be displayed in a pop-up. If the status is 200, it is successful.
...
How to set with Module twin desired property
Display the Module twin of the target Container Adamapp in for Azure IoT Edge in Azure IoT Explorer.
Set as follows in “properties”.”desired”.”aplField”.
...
Info |
---|
|
How to check the settings
Setting values can be checked with Module twin.
Check the value of “properties”.”reported”.”aplField”.”azureSettings”.”telemetry”.
...
Checking received telemetry data
Select the target Container Adamapp for Azure IoT Edge in Azure IoT Explorer.
Select "Telemetry" from the left menu.
...
The string set in ADAM_SendTelemetry will be set as the value of the payload key.
...
How to check the log
...
App log
You can check messages output by ADAM_DEBUG_PRINT() within the app and logs output by libraries linked from the app. You can also check if there is an error.
Log in to Azure portal(Cloud Computing Services | Microsoft Azure).
Select the target IoT Hub.
Select the target camera from "Device Management" and "IoT Edge" on the left.
From the list of modules below, click the "Runtime Status" link for the app name you want to view logs for.
...
Note |
---|
Container Adamapp for Azure IoT Edge logs cannot be checked with UDPLog. |
camera pflog
By checking the log in the camera, you can also analyze the behavior when Container Adamapp for Azure IoT Edge is not working properly. Logs can be obtained by clicking the execution button below.
...
Among the multiple log files, we will introduce the log files that are most related to Container Adamapp for Azure IoT Edge.
cadam (files with file names starting with pf_cadam, pf_cadamCgi) cadam is a process that manages Container Adamapp for Azure IoT Edge.
Azure IoT Edge runtime (files whose names start with pf_aziot-certd, pf_aziot-edged, pf_aziot-identityd, pf_aziot-keyd)Azure IoT Edge runtime communicates with Azure IoT Hub.
Docker (files with file names starting with pf_docker, pf_containerd, pf_opa) Logs related to Docker operations. opa is used for security checks, and if the created deployment manifest contains content that violates the camera's security policy, a log will be output to this file.
Enhance Security Level of your Container
...
This article describes techniques for strengthening container security when developing container applications.
...
No. | Security measures | Explanation |
---|---|---|
1 | Select base image | Choose a lightweight, reliable base image. Consider using official or security-enhanced images. i-PRO's SDK provides base images, so please use them unless you need additional information. |
2 | Image vulnerability scan | Regularly scan container images with tools to identify and remediate vulnerabilities. |
3 | Creating a secure Dockerfile | Create Dockerfile securely. Don't install unnecessary packages, use ADD instead of COPY, minimize user privileges, etc. Many of these practices can be detected by the vulnerability tools listed above. |
4 | Applying security context | Minimize risk by setting appropriate permissions and resource limits on your containers. The i-PRO camera restricts these settings, and an error will occur if you try to start the container with settings outside the permitted range. To avoid this error, please use the template settings provided by i-PRO. |
5 | Container network security | Configure your network settings appropriately and avoid opening unnecessary ports. It also applies security policies to communication between containers. |
6 | Logging and monitoring | Monitor containers and collect logs to quickly detect anomalies and security incidents. It is necessary to implement output logging with an appropriate amount and content. |
7 | Confidential data measures | Avoid keeping sensitive data inside containers. If you want to handle sensitive data or safely manage application settings, you need to take measures such as using a secure storage solution. The i-PRO camera provides a data storage environment using named volumes as a method. |
8 | CI/CD pipeline security | We perform security checks at each stage of build, test, and deployment to detect and fix unauthorized operations and vulnerable code. This includes using the vulnerability scanning tools mentioned above. Set up appropriate access controls in your CI/CD pipeline and adhere to security best practices. |
9 | Creating and managing SBOM | Create and manage SBOM for vulnerability management and supply chain risk management. We recommend that you understand the OSS included in the image. |
Run Vulnerability Checker against your Image
One way to strengthen container security is to use tools to extract vulnerabilities in container images and remove or fix them as much as possible.
...
In addition, in this figure, vulnerability checks are not limited to application container images that are self-developed products, but also container images that are used as a base for multi-build purposes during development (e.g., Debian official images, etc.) It also covers. The reason for this is to thoroughly check for vulnerabilities in the packages you use. The details will be described in the Trivy explanation section.
Trivy: Comprehensive Vulnerability Scanner
Trivy is an open source scanner that detects vulnerabilities in container images and file systems. It mainly targets vulnerabilities related to OS packages and programming language libraries. Trivy is developed and maintained by Aqua Security and is one of the most reliable tools for container developers.
...
As mentioned above, it is important to regularly check for vulnerabilities in container images using tools like Trivy to reduce security risks. Additionally, by incorporating Trivy into your CI/CD pipeline, you can achieve automated vulnerability detection and improve security throughout your development process.
Dockle: Container Image Security Linter
Dockle は、コンテナイメージのセキュリティベストプラクティスに基づいて、潜在的な問題を特定するオープンソースのツールです。Dockleは、Dockerfile やイメージ設定など、主にシステム関連の脆弱性を検出します。GoodwithTech 社によって開発・メンテナンスされており、Trivy と同様にコンテナ開発者にとって有益なツールの一つです。
Dockle の使い方の基本例を以下に示します。
(1) Install Dockle:
まず、Dockle をインストールします。Dockle のリリースページから最新版のバイナリをダウンロードできます。下記リンクから Dockle のリリースページにアクセスしてください。
https://github.com/goodwithtech/dockle/releases
リリースページには、Linux、macOS、Windowsなどの各プラットフォーム向けのバイナリが用意されています。自分の環境に合ったバイナリを選択し、ダウンロードしてください。また、Dockle の公式ドキュメントには、各プラットフォームでのインストール方法が詳細に記載されていますので、そちらも参考にしてください。
(2) Run Dockle:
インストールが完了したら、コマンドラインから Dockle を実行して、対象となるコンテナイメージのセキュリティベストプラクティスをチェックします。以下のコマンドは、your-image というコンテナイメージをチェックする例です。
Code Block |
---|
buildhost$ dockle your-image |
絞り込みを行う際は必要に応じて、Dockle のオプションを使用してチェック対象や表示内容をカスタマイズできます。例えば、特定のチェック ID (後述) を無視する場合は、以下のように実行します。
Code Block |
---|
buildhost$ dockle --ignore CIS-DI-0001 your-image |
(3) Check the result and determine how to deal with:
チェックが完了すると、Dockle は検出された問題の一覧を表示します。各問題には、CIS(Center for Internet Security)ベンチマークに基づいたチェック ID が付与されており、対処すべき箇所を特定しやすくなります。この結果をもとに、影響度などを加味しながらどれをどう対処していくのかを決定していきます。
参考で、以下に Azure IoT Edge のサンプルアプリケーションのイメージに対し Dockle を実行した例 (オプション指定無し) の抜粋を示します。
Example execution of Dockle: target image = azureiotedge example application
buildhost$ dockle mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0 INFO - CIS-DI-0005: Enable Content trust for Docker
INFO - CIS-DI-0006: Add HEALTHCHECK instruction to the container image
INFO - CIS-DI-0008: Confirm safety of setuid/setgid files
<<<<........ SNIP ........>>>>
INFO - DKL-LI-0003: Only put necessary files
<<<<........ SNIP ........>>>>
|
以上、Trivy と同様に Dockle のようなツールを利用してコンテナイメージに含まれるシステム関連の問題を定期的にチェックし、セキュリティリスクを低減させることが重要です。また、CI/CD パイプラインに Dockle を組み込むことで、自動化されたセキュリティベストプラクティスのチェックを実現し、開発プロセス全体のセキュリティを向上させることができます。
Force-Limit on Access to Host Resources
セキュリティ上の理由から、i-PROカメラ上で動作するコンテナはアクセス可能なi-PROカメラのホスト側の権限やリソースが強制的に制限されています。Docker API に対し、i-PROに許可されていない権限やリソースの場所、範囲外の値のオプションを指定したコンテナを起動しようとした場合、ホスト側のチェック機構がそれら要求を拒否する仕組みが搭載されています (下記の図を参照)。
...
上記の制約下において、i-PROが許可しているオプション一式が事前設定されているテンプレートを SDK のビルド環境にて提供しています。このテンプレートにはコンテナアプリケーションが起動許可されるために必要かつ十分な設定となっており、上記のような権限やリソースに関する設定は変更せずにそのまま使用可能となっています (コンテナ名などの個別対応が必要なものを除く)。開発されるコンテナアプリケーションからアクセスが必要な権限やリソースに対して、上記テンプレートに事前設定されていない場合や、ご自身で追加、変更した設定がi-PROカメラのホスト側から拒否される場合には、設計、設定の見直しをお願いします。is an open source tool that identifies potential issues based on container image security best practices. Dockle primarily detects system-related vulnerabilities, such as Dockerfiles and image configurations. It is developed and maintained by GoodwithTech and, like Trivy, is one of the most useful tools for container developers.
Below is a basic example of how to use Dockle.
(1) Install Dockle:
First, install Dockle. You can download the latest version of the binaries from the Dockle release page. Please access Dockle's release page from the link below.
https://github.com/goodwithtech/dockle/releases
The release page provides binaries for each platform, including Linux, macOS, and Windows. Select the binary that suits your environment and download it. Also, please refer to Dockle's official documentation, which provides detailed instructions on how to install it on each platform.
(2) Run Dockle:
Once installed, run Dockle from the command line to check the security best practices for your container image. The following command is an example of checking a container image called your-image.
Code Block |
---|
buildhost$ dockle your-image |
When filtering, you can use Dockle's options to customize what to check and what to display if necessary. For example, if you want to ignore a particular check ID (described below), run:
Code Block |
---|
buildhost$ dockle --ignore CIS-DI-0001 your-image |
(3) Check the result and determine how to deal with:
Once the check is complete, Dockle displays a list of detected issues. Each issue has a check ID based on Center for Internet Security (CIS) benchmarks to help you identify areas to address. Based on these results, you will decide which ones to deal with and how to deal with them, taking into consideration factors such as the degree of impact. For reference, below is an excerpt of an example of running Dockle on an Azure IoT Edge sample application image (no options specified).
Example execution of Dockle: target image = azureiotedge example application
buildhost$ dockle mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0 INFO - CIS-DI-0005: Enable Content trust for Docker
INFO - CIS-DI-0006: Add HEALTHCHECK instruction to the container image
INFO - CIS-DI-0008: Confirm safety of setuid/setgid files
<<<<........ SNIP ........>>>>
INFO - DKL-LI-0003: Only put necessary files
<<<<........ SNIP ........>>>>
|
As mentioned above, it is important to use tools like Dockle to regularly check for system-related issues in container images and reduce security risks, just like Trivy. You can also incorporate Dockle into your CI/CD pipeline to provide automated security best practice checks and improve security throughout your development process.
Force-Limit on Access to Host Resources
For security reasons, the permissions and resources of the i-PRO camera host that can be accessed by containers running on the i-PRO camera are forcibly restricted. If an attempt is made to start a container that specifies permissions, resource locations, or out-of-range options for Docker API that are not allowed by i-PRO, a check mechanism on the host side will reject the request. (see diagram below).
...
Under the above constraints, we provide a template in the SDK build environment that is preconfigured with a set of options allowed by i-PRO. This template has the necessary and sufficient settings for the container application to be allowed to start, and can be used as is without changing settings related to permissions and resources such as the above (individual settings such as container name etc. (excluding those that require action).
If the permissions and resources that need to be accessed from the container application being developed are not pre-configured in the above template, or if the settings you have added and/or changed yourself are rejected by the i-PRO camera host. Please review the design and/or settings.
Checkpoints if things don't work in the WSL environment
...
If it does not work in WSL environment, please check the following.
The following must be enabled in the Visual Studio Code "LOCAL" extension
Dev Containers
Remote - SSH, Remote - SSH: Editing Configuration FIles, Remote - Tunnels, Remote Development, Remote Explorer
WSL
The following must be enabled in Visual Studio Code's "WSL: UBUNTU-20.04" extension:
Azure Account
Azure IoT Edge
Azure IoT Hub
"WSL: Ubuntu-20.04" is displayed at the bottom left of the Visual Studio Code screen.
If permission denied is displayed in Build IoT Edge Solution, check whether the current user has access rights to the target directory.
Code Block sudo chown -r ipro:ipro [development directory] ※ipro:ipro is an example, so please set it according to each environment.
Run the above to change the owner.
About trademarks
We will post about the trademarks used on the site.
...