イメージ形式¶
イメージはルートファイルシステムとイメージを記述するメタデータファイルを含みます。 またイメージを使用するインスタンス内部でファイルを生成するためのテンプレートも含められます。
イメージは統合イメージ(単一ファイル)か分離イメージ(2 つのファイル)としてパッケージできます。
中身¶
コンテナのイメージは以下のディレクトリー構造を持ちます:
metadata.yaml
rootfs/
templates/
仮想マシンのイメージは以下のディレクトリー構造を持ちます:
metadata.yaml
rootfs.img
templates/
どちらのインスタンスタイプでも、templates/
ディレクトリーは省略可能です。
メタデータ¶
metadata.yaml
ファイルはイメージが Incus 内で稼働するために関連する情報を含みます。
以下の情報を含んでいます:
architecture: x86_64
creation_date: 1424284563
properties:
description: Ubuntu 22.04 LTS Intel 64bit
os: Ubuntu
release: jammy 22.04
templates:
...
architecture
とcreation_date
フィールドは必須です。
properties
フィールドはイメージのデフォルトプロパティのセットを含みます。
os
, release
, name
, description
フィールドはよく使われますが、必須ではありません。
templates
フィールドは省略可能です。
テンプレートをどのように設定するかの情報はテンプレート(省略可能_を参照してください。
ルートファイルシステム¶
コンテナでは、rootfs/
ディレクトリーがコンテナ内のルートディレクトリー(/
)の完全なファイルシステムツリーを含みます。
仮想マシンはrootfs/
ディレクトリーの代わりにrootfs.img
qcow2
ファイルを使います。
このファイルはメインのディスクデバイスになります。
テンプレート(省略可能_¶
インスタンス内部でファイルを動的に作成するのにテンプレートを使用できます。
そのためには、metadata.yaml
ファイル内でテンプレートルールを設定し、templates/
ディレクトリー内にテンプレートファイルを配置します。
一般的なルールとして、パッケージに所有されるファイルはテンプレート化は決してするべきではないです。そうでないとインスタンスの通常のオペレーションで上書きされてしまうでしょう。
テンプレートルール¶
生成すべき各ファイルに対して、metadata.yaml
ファイル内でルールを作成します。
たとえば:
templates:
/etc/hosts:
when:
- create
- rename
template: hosts.tpl
properties:
foo: bar
/etc/hostname:
when:
- start
template: hostname.tpl
/etc/network/interfaces:
when:
- create
template: interfaces.tpl
create_only: true
/home/foo/setup.sh:
when:
- create
template: setup.sh.tpl
create_only: true
uid: 1000
gid: 1000
mode: 755
when
キーは以下の 1 つ以上を指定できます:
create
- 新規インスタンスがイメージから作成された時に実行copy
- 既存インスタンスからインスタンスが作成されたときに実行start
- インスタンスが開始する度に毎回実行
template
キーはtemplates/
ディレクトリー内のテンプレートファイルを指します。
properties
キーでユーザー定義のテンプレートプロパティをテンプレートファイルに渡せます。
ファイルが存在しない場合にのみ Incus にファイルを作らせ、ファイルが存在する場合は上書きしてほしくない場合は、create_only
キーをセットします。
uid
、gid
、mode
キーはファイルの所有者とパーミションを制御するのに使えます。
テンプレートファイル¶
テンプレートファイルはPongo2形式を使います。
テンプレートファイルは常に以下のコンテキストを受け取ります。
変数 |
型 |
説明 |
---|---|---|
|
|
テンプレートをトリガーしたイベント名 |
|
|
テンプレートを使用するファイルのパス |
|
|
インスタンスプロパティのキー/値マップ(名前、アーキテクチャ、特権、一時的) |
|
|
インスタンス設定のキー/値マップ |
|
|
インスタンスに割り当てられたデバイスのキー/値マップ |
|
|
|
利便性のため、以下の関数が Pongo2 テンプレートにエクスポートされます。
config_get("user.foo", "bar")
-user.foo
の値か、未設定の場合は"bar"
を返します。
イメージのtarball¶
Incus は 2 種類の Incus 固有のイメージ形式、統合 tarball と分離 tarball をサポートします。
これらの tarball は圧縮されていても構いません。
Incus は tarball の広範囲の圧縮アルゴリズムをサポートします。
しかし、互換性のためにはgzip
またはxz
を使うのが良いです。
統合tarball¶
統合 tarball は単一の tarball(通常*.tar.xz
)で、イメージの完全な中身を含みます。それにはメタデータ、ルートファイルシステムと省略可能なテンプレートファイルが含まれます。
これが Incus 自身がイメージを公開する際に内部的に使用している形式です。 通常こちらのほうが扱いやすいので、Incus 固有のイメージを作る際は統合形式を使うのが良いです。
この形式のイメージの識別子は tarball の SHA-256 ハッシュ値です。
分離tarball¶
分離イメージは 2 つの tarball から構成されます。
1 つは (通常*.tar.xz
)はメタデータと省略可能なテンプレートファイルを含む tarball で、もう 1 つは実際のインスタンスデータを含む tarball、squashfs
、または qcow2
イメージです。
コンテナでは、2 つめのファイルはたいていは SquashFS でフォーマットされたファイルシステムツリーですが、同じツリーの tarball でもよいです。
仮想マシンでは、2 つめのファイルはqcow2
でフォーマットされたディスクイメージです。
tarball は外部で圧縮されていてもよい(.tar.xz
、.tar.gz
、…)ですが squashfs
と qcow2
はそれぞれのネイティブの圧縮オプションで内部を圧縮してもよいです。
この形式は既に利用可能である既存の Incus 以外の rootfs tarball から簡単にイメージをビルドできるように設計されています。 Incus と他のツールの両方で使用するイメージを作りたい場合もこの形式を使うのが良いです。
これらのイメージのイメージ識別子はメタデータとデータファイルを(この順で)結合したものの SHA-256 ハッシュ値です。