ユーザーガイド

• 1: ジョブステータス
• 2: Dockerによるパッケージング
• 3: Artefacts クラウドシミュレーションでのテスト実行
• 4: GitHub による継続的インテグレーション
• 5: テストの実行と追跡
• 6: アップロード

1 - ジョブステータス

ジョブと実行のライフサイクルステータス

このページでは、ダッシュボードで表示されるジョブおよびジョブランの各ステータスの意味について説明します。

ジョブステータス

ジョブは、プロジェクトのシナリオ実行のグループを表します。そのステータスは全体の進捗と結果を反映しています。

• 作成済み: ジョブが作成され、処理待ちの状態です。
• ビルド待ち: ジョブがキューに入っており、まもなくビルドされます。
• ビルド中: ジョブが現在ビルドされています。
• ビルド失敗: ビルドプロセスが正常に完了しませんでした。
• ビルド完了: ビルドプロセスが正常に完了しました。
• 実行スケジュール済み: ジョブがシナリオの実行をスケジュールしています。
• 実行中: ジョブがシナリオを実行中です。
• 完了: すべてのシナリオの実行を終了しました。一部が失敗またはクラッシュしている可能性があります。
• タイムアウト: ジョブが時間を超過し、自動的に停止されました。
• キャンセル中: ジョブがキャンセル処理中です。
• キャンセル済み: ジョブが完了前にキャンセルされました。

ランステータス

ジョブラン（またはサブジョブ）は、ジョブ内の個別のシナリオ実行です。そのステータスは進捗を示しています。

• 実行中: シナリオが現在実行されています。
• 成功: シナリオが正常に終了しました。
• 失敗: シナリオは終了しましたが、成功しませんでした。
• クラッシュ: シナリオが予期せずクラッシュしました。
• タイムアウト: シナリオが時間を超過し、自動的に停止されました。

2 - Dockerによるパッケージング

多くの一般的なユースケースでは、有効な artefacts.yaml 設定ファイルがあれば、Artefactsは自動的に実行されます。これはArtefactsインフラストラクチャ上で実行する場合 (run-remote) と artefacts run --in-containerを使用する場合の両方に適用されます。Artefactsインフラストラクチャ上でのジョブ実行の詳細については、 cloud-simulation を参照してください。

ArtefactsはカスタムのDockerファイル設定もサポートしています。このガイドではArtefactsでスムーズに実行するための条件について説明します。

カスタムDockerfileまたはイメージ名を使用する場合

Artefactsクラウドシミュレーション (run-remote)上で実行する場合、または artefacts run --in-containerを使用する場合、現在、以下の状況ではカスタム Dockerfile またはイメージを指定する必要があります：

• ROSを使用していない
• サポートされていないROSバージョンを使用している
• サポートされていないシミュレーターを使用している
• プロジェクトがプロジェクトリポジトリのsrcフォルダとは別の/追加のビルドステージを持っている
• プロジェクトに他の特定の要件がある

my-job:
  type: test
  package:
    docker:
      build: # Sample with a custom Dockerfile. Another option is to specify an image.
        dockerfile: ./Dockerfile

Dockerfileの例は nav2サンプルプロジェクト で確認できます。

Artefactsベースイメージ

ROS2プロジェクトのベースレイヤーとして自由に使用できる多くのイメージを用意しています。これらのベースイメージには以下が含まれています：

• タグに対応するROSバージョン (例 humble-fortress には ros-humble-ros-core パッケージが含まれています)
• タグに対応するシミュレーター
• そのROS/シミュレーターの組み合わせに対してよく使用されるROS依存関係 (ROS2 Humble / Fortressベースイメージの ros-humble-ros-ign-bridge など)
• 必要なビルドツール (catkin / colcon)
• rosdep の初期化と更新
• Artefacts CLI
• jazzy（Ubuntu 24、Python 3.12）イメージでは、仮想環境が /opt/venv に既に設定されアクティブ化されています。PYTHONPATH 環境変数は、仮想環境の site-packages とシステムの dist-packages の両方を含むように事前に設定されています。これにより、ROS をソースした後でも、pip でインストールされたパッケージと ROS パッケージの両方が利用可能になります。その結果、Python 仮想環境を作成したり手動で設定したりする必要はありません。

公開されているベースイメージの完全なリストは ECRパブリックレジストリで確認できます。以下の命名規則に従っています：

public.ecr.aws/artefacts/<framework>:<framework_version>-<simulator>-gpu
# -gpu is optional
# Examples:
public.ecr.aws/artefacts/ros2:humble-fortress
public.ecr.aws/artefacts/ros2:humble-fortress-gpu

これらのベースイメージを使用することで、プロジェクトのDockerfileは（最低限）以下の手順を実行する必要があります：

• プロジェクトファイルをコピーする
• ROS依存関係をインストールする
• プロジェクトをビルドする
• artefactsクライアントを実行する

例として、ROS2 Humble / Ignition Fortressプロジェクトのartefactsで動作するDockerfileは以下のようになります：

# Use the artefacts ROS2 humble base image
FROM public.ecr.aws/artefacts/ros2:humble-fortress

# Set the working directory and copy our project
WORKDIR /ws
COPY . /ws/src

# ROS dependencies
RUN rosdep install --from-paths src --ignore-src -r -y
# Source ROS version and build
RUN . /opt/ros/galactic/setup.sh && colcon build --symlink-install

WORKDIR /ws/src

# Source colcon workspace and run the artefacts client
CMD . /ws/install/setup.sh && artefacts run $ARTEFACTS_JOB_NAME

Dockerfileの要件

現在、Dockerfileは2つの要件を満たす必要があります：

• CLIをインストールする必要があります（artefactsが提供するベースイメージには既にインストールされています）

RUN pip install artefacts-cli

• コンテナ起動コマンドはCLIを実行する必要があります：

CMD artefacts run $ARTEFACTS_JOB_NAME

これは artefacts run <job_name> --in-container (ローカル) または artefacts run-remote <job_name> (クラウドシミュレーション)で実行できます。

3 - Artefacts クラウドシミュレーションでのテスト実行

概要

artefacts run [jobname] を使用すると、テストはローカルで実行されます。しかし、テストに時間がかかる場合、例えば複数のパラメータ化されたシナリオがある場合は、Artefacts クラウドシミュレーション上で実行したいと思うかもしれません。

その場合は artefacts run-remote [jobname]を使用できます。ローカルコードがアーカイブファイルに圧縮され、実行のために当社のサーバーに送信されます。

以下は実行モデルの概要です。

graph TD
  subgraph artefacts
    ac(cloud simulation) --> dashboard(dashboard)
  end
  subgraph LocalMachine
    lc(local code) -.-CLI
    CLI --run_local-->dashboard
    CLI --run_remote-->ac
  end
  lc --push--> github
  github --pushEvent/pullCode--> ac

Artefacts クラウドシミュレーションでの実行時間は、使用量クォータに計上されます。

.artefactsignore ファイル

プロジェクト内にテスト実行に必要のないファイル（例：rosbags、一部のアセットなど）がある場合、アップロードするアーカイブファイルのサイズを小さく保つために、プロジェクトのルートに .artefactsignore ファイルを追加することができます。これは .gitignore ファイルと同じ方法で使用できます。例えば：

rosbags/
venv/
.DS_Store

これにより、 rosbags と venv フォルダ、および隠しファイル .DS_Store はバンドルされません。

クラウドシミュレーション用のパッケージング

Artefacts はいくつかのシミュレーターとフレームワークをすぐに使用できるよう対応しています。その場合、必要なのはテスト起動ファイルを提供するだけです ( Running and Tracking Tests を参照)

現在サポートされているのは：

• Gazebo Ignition（Fortress）を使用した ROS2

runtime:
  simulator: gazebo:fortress
  framework: ros2:humble

• Gazebo（Harmonic）を使用した ROS2

runtime:
  simulator: gazebo:harmonic
  framework: ros2:humble 

設定ファイルの runtime セクションでこれらが適切に指定されていることを確認してください ( 設定構文 を参照)。 また、（プロジェクトが ROS を使用していない場合など）Artefacts クラウドシミュレーション上で実行するための Docker パッケージを準備する 必要があるかもしれません。

クラウドシミュレーション用のパッケージングのカスタマイズ

ほとんどの場合、ランタイムブロックで使用するフレームワークとシミュレーターを指定するだけで十分です：

runtime:
  simulator: gazebo:fortress
  framework: ros2:humble

そしてテスト起動ファイルを提供するだけで、Artefacts は他の入力なしであなたのプロジェクトを構築してテストすることができます。しかし、一部のプロジェクトでは、いくつかのカスタマイズや微調整が必要な場合があることも理解しています。

これらのケースに対応するため、 artefacts.yaml ファイルの package['custom'] セクションで以下のキーを使用できます：

package:
  custom:
    os: # string
    include: # List
    commands: # List

• os: 文字列 ベースイメージを入力します (例： ubuntu:22.04)。 これは framework と simulator の選択に基づいてArtefactsが使用するベースイメージをオーバーライドします。

例：

package:
  custom:
    os: ubuntu:22.04

• include: リスト デフォルトでは、Artefacts はGitHubリポジトリ（継続的インテグレーション）または現在の作業ディレクトリ（‘run-remote’）を再帰的にサーバー上で実行されているコンテナにコピーします。 include を使用して、コンテナで利用可能にしたいディレクトリ/ファイルを指定します。

例：

package:
  custom:
    include:
	  - ./path/to/my_necessary_files
	  - ./makefile

• commands: リスト プロジェクトのビルド段階の前に実行する追加のbashコマンドが必要な場合は、ここに入力します。一般的な使用例は、ros/gazeboプロジェクトを構築する際に、通常のros source に加えてカスタム source が必要な場合です。

例：

package:
  custom:
    commands:
	  - source simulator/my_workspace/install/setup.bash
runtime:
  framework: ros2:humble
  simulator: gazebo:fortress

4 - GitHub による継続的インテグレーション

Artefacts クラウドシミュレーションは、新しいコードがリポジトリにプッシュされたときにテストジョブを実行できます。そのためには、お好みの CI ツールで run-remote をトリガーするだけです。

結果は他のジョブと同様にダッシュボードに表示されます。GitHub によってトリガーされたジョブには、コミット ID などの追加メタデータが含まれています。

継続的インテグレーションジョブの実行に問題がある場合は、まず ローカルでテストを実行 し、次に the tests can run on artefacts cloud を確認して、テストとパッケージが正しく動作していることを確認してください。

Artefacts GitHubアクション

GitHub CI ワークフローの一部として Artefacts クラウドシミュレーションを統合したい方は、GitHub ワークフローに art-e-fact/action-artefacts-ci@main アクションを追加できます。このアクションには Python が必要であり、実行するためには（ダッシュボードから作成できる）Artefacts API キーも必要です。

基本的な例を以下に示します：

name: test
on: push
  
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.11]

    steps:
      - uses: actions/checkout@v3

      - name: Set Up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}

      - uses: art-e-fact/action-artefacts-ci@main
        with:
          artefacts-api-key: ${{ secrets.ARTEFACTS_API_KEY }}
          job-name: test_job

• artefacts-api-key: 特定のプロジェクト用にダッシュボードで作成されます。
• job-name: artefacts.yaml ファイルで実行したいジョブと一致する必要があります。

GitHub アクションは、プロジェクトの実行に必要な追加リポジトリがある場合に特に便利です。以下のアクションを使用して、Artefacts クラウドシミュレーションを実行する前にそのリポジトリをプロジェクトにクローンできます：

- name: Clone My Repo
  uses: actions/checkout@v3
  with:
    repository: my-org/my-repo
    token: ${{ secrets.MYREPO_PAT }} # if cloning a private repository
    path: my-repo
    ref: main

5 - テストの実行と追跡

ROS2とTurtlesimシミュレーターを使用した例については、 example-turtlesim ご参照してください。 ROS1 noeticとTurtlesimシミュレーターを使用した例については、 demo-ros1-turtlesim を参照してください：Artefactプラットフォームを使用したシンプルなロボットのオドメトリ/位置推定アプリケーションの開発例です。

6 - アップロード

Artefactsクライアントは、 artefacts.yaml 設定ファイルのoutput_dirsで指定されたパスにあるすべてのファイルをアップロードします ( 設定構文を参照)。