Paketo Buildpacks の設定

設定例について

それぞれの例では、サンプルアプリケーションのリポジトリのルートディレクトリを作業ディレクトリとします。

git clone https://github.com/paketo-buildpacks/samples
cd samples
Copied!

全ての例で使用する pack CLI は、Paketo Buildpack を使用してコンテナイメージをビルドできる Cloud Native Buildpack Platform の1つです。

それぞれの例では、既定のビルダーとして Paketo Base ビルダーを使用します。

pack config default-builder paketobuildpacks/builder:base
Copied!

設定の種類

Paketo Buildpack は次のような仕組みを通じて設定できます。

環境変数 - ビルド時点 と 実行時点 の両方で使用できる汎用的な設定方法です
buildpack.yml - ビルド時点 で使用できる汎用的な設定方法です
バインディング - ビルド時点 と 実行時点 の両方で、秘匿情報 の設定に使用できる設定方法です
Procfiles - ビルド時点 で独自の プロセス種類 を指定できる設定方法です

環境変数

ビルド時に環境変数を指定する

利用者は、Buildpack の環境で使用する環境変数を指定することでビルドの仕方を変更できます。ビルド時に使用できるのは名前が BP_ で始まる変数や、Paketo Buildpack の外部で慣習的に使用されている変数（http_proxy など）です。

Java Buildpack がインストールする JVM のバージョンを環境変数で指定するときは次のように実行します。

pack build samples/java  \
  --path java/jar \
  --env BP_JVM_VERSION=8
Copied!

ビルド処理の途中、Buildpack は環境変数で指定された設定を引き継ぐようにして外部プログラムを実行します。利用者は外部プログラムを普通に実行するときと同じように、環境変数を渡すことができるのです。例えば、MAVEN_OPTS で Maven の使用する JVM のメモリ設定を変更するときは次のように実行します。

pack build samples/java  \
  --path java/maven \
  --env "MAVEN_OPTS=-Xms256m -Xmx512m"
Copied!

実行時に環境変数を指定する

利用者は、コンテナイメージを実行するときの環境変数を通じて、実行時の設定を変更できます。 Buildpack の提供するランタイムコンポーネント（プロファイルスクリプトやプロセス種類）は名前が BPL_ で始まる変数や、Paketo Buildpack の外部で慣習的に使用されている変数（JAVA_TOOL_OPTIONS など）です。

Spring Boot のサンプルアプリケーションについて、環境変数 JAVA_TOOL_OPTIONS で待ち受けポート番号を指定するには次のように実行します。

docker run --rm --publish 8082:8082 --env "JAVA_TOOL_OPTIONS=-Dserver.port=8082" samples/java
curl -s http://localhost:8082/actuator/health
Copied!

アプリケーションだけでなく、実行時に起動するプログラムは、普通に実行した場合と同じように環境変数を参照できます。

Environment Variables buildpack を使うと、コンテナイメージ自体に環境変数を埋め込むことができます。 Environment Variables buildpack は名前が BPE_* にマッチする環境変数を探索し、アプリケーションを起動した環境で利用できるよう、起動環境を変更します。秘匿性の低い設定項目の初期値を設定したり、利用者が設定する必要のない設定項目の環境変数を変更できます。

Environment Variables buildpack は次のような環境変数の操作に対応しています。

環境変数名	説明
`$BPE_<NAME>`	環境変数 `NAME` を設定します。同じ名前の変数は上書きします
`$BPE_APPEND_<NAME>`	環境変数 `NAME` の後ろに指定した値を追加します
`$BPE_DEFAULT_<NAME>`	環境変数 `NAME` の初期値を設定します
`$BPE_OVERRIDE_<NAME>`	環境変数 `NAME` を設定します。同じ名前の変数は上書きします
`$BPE_PREPEND_<NAME>`	環境変数 `NAME` の前に指定した値を追加します

環境変数の操作について詳しくは CNB の仕様を参照してください。

環境変数 BPE_DELIM_<NAME> で、前後に値を追加するときの区切り文字を変更できます。初期値は空文字列、すなわち、区切り文字なしになっています。例えば、区切り文字が「コロン（:）」の環境変数 PATH や LD_LIBRARY_PATH へパス要素を追加するときに使うといいでしょう。

絶対にやらないでください：Environment Variables buildpack で、秘匿性の高い資格情報をコンテナイメージに埋め込むのはやめましょう。ビルドツールの生成したコンテナイメージに何らかの情報を埋め込むということは、そのコンテナイメージにアクセスできる人なら誰でも埋め込まれた情報を参照できることになるからです。

buildpack.yml

多くの Paketo Buildpack は、アプリケーションのソースコードリポジトリの直下に置かれた buildpack.yml の設定を読み取ることができます。

例えば、Node.js Buildpack のインストールする Node.js のバージョンを指定するには、サンプルリポジトリの nodejs/yarn ディレクトリへ、次のような内容の buildpack.yml を配置します。

nodejs:
  version: 12.12.0
Copied!

同じようにビルドすると、指定したバージョンの Node.js をインストールします。

pack build samples/nodejs --path nodejs/yarn
Copied!

バインディング

バインディングとは何か

Paketo Buildpack や、Paketo Buildpack がインストールするコンポーネントの中には、ビルド時点と実行時点の両方で、バインディングに配置した資格情報やそれ以外の秘匿情報を使用できるものがあります。一般的には、外部サービスへ接続するためのアドレス情報や資格情報を提供するためにバインディングを使用します。

外部サービスの中には、ビルド時点でバインディングを必要とするものがあります。

プライベートアーティファクトリポジトリ
SaaS のセキュリティスキャンツール

例えば、Maven Buildpack がプライベート Maven リポジトリへ接続するためのアドレス情報と資格情報はバインディングで構成できます。

外部サービスの中には、実行時点でバインディングを必要とするものがあります。

APM
データストア
OAuth2 プロバイダ

例えば、Spring Boot Buildpack のインストールする Spring Cloud Bindings は、バインディングで指定したさまざまな外部サービスの接続情報を、Spring Boot アプリケーションの自動構成プロパティとして使用できるようにします。

バインディングには何が入っているのか

バインディングには次のような内容を含みます。

name（名前）：バインディングを識別する名前です。基本的にビルド時点や実行時点の振る舞いには影響しませんが、ログ出力などでバインディングを参照するときの情報として使われる場合があります
type（種類）あるいは kind（種類）：バインディングに格納した資格情報の種類を表します。例えば、ApplicationInsights なら Azure Application Insights へ接続するための資格情報を含むことになります
provider（プロバイダー）：任意要素です。バインディングの提供元を表します。例えば、PaaS ではバインディングを提供するサービスブローカーを使う場合があります
キー・値の対：設定項目と値です。例えば ApplicationInsights のバインディングならキー InstrumentationKey とその値からなる対を含めることになります

Buildpack にはコンテナファイルシステムのディレクトリとしてバインディングを連携します（ボリュームマウントを利用する場合が多いでしょう）。ディレクトリ名がバインディングの名前を表します。バインディングの（ディレクトリの）要素は次のいずれかの形式に従うようにします。

Kubernetes サービスバインディング仕様：実行環境が対応しているなら CNB バインディング仕様よりこちらの仕様に従うことをお勧めします
Cloud Native Buildpacks バインディング仕様：伝統的な Buildpack のバインディング仕様ですが [廃止予定] です

Paketo Buildpack はビルド時に参照するバインディングを /platform/bindings ディレクトリから探索します。また、実行時に参照するバインディングは、環境変数 SERVICE_BINDING_ROOT あるいは CNB_BINDINGS の値が指すディレクトリから探索します。

例えば、Maven Buildpack は type が maven 、キーが settings.xml で値が Maven settings になっているバインディングを受け付けます。ビルド用コンテナでは、次のいずれかの場所で見つけた settings.xml を使用するのです。

/platform
└── bindings
    └── <name>
        ├── settings.xml
        └── type
Copied!

/platform
└── bindings
    └──<name>
        └── metadata
        |   └── kind
        └── secret
            └── settings.xml
Copied!

バインディングの使い方

バインディングの作成方法や、ビルド時に指定する方法は、プラットフォームによって異なります。例えば、pack コマンドなら、 --volume フラグでボリュームマウントさせたディレクトリを使用します。 kpack コマンドなら、キーと値の対を Kubernetes の Secret リソースへ登録し、コンテナスペックのメタデータで secret フィールドに指定します。詳しくは kpack でサービスバインディングを使う方法を参照してください。

例：pack build コマンドにバインディングを指定する

あるディレクトリをビルド時に使用するバインディングとして使用する場合、--volume フラグで指定します。

pack build --volume <absolute-path-to-binding>:/platform/bindings/<binding-name> <image-name>
Copied!

例：docker run にバインディングを指定する

あるディレクトリを実行時に使用するバインディングとして使用する場合、--volume フラグと --env フラグで指定します。

docker run --env SERVICE_BINDING_ROOT=/bindings --volume <absolute-path-to-binding>:/bindings/<binding-name> <image-name>
Copied!

Procfiles

利用者は Procfile で Paketo Buildpack の提供する type（プロセス種類）を上書きしたり、使用できるプロセス種類を追加したりできます。 Procfile を処理できるのは Paketo Procfile Buildpack です。 Procfile Buildpack はアプリケーションのルートディレクトリで Procfile を探索します。 Procfile の形式は次のとおりです。

<type>: <command>

指定された言語モジュール Buildpack に Procfile Buildpack が含まれていないときは、pack コマンドを実行するとき、明示的に指定します。

例：Procfile で Hello World

プロセス種類に追加した hello を初期値にするときは次のようにします。

echo "hello: echo hello world" > nodejs/yarn/Procfile
pack build samples/nodejs \
  --path nodejs/yarn \
  --buildpack gcr.io/paketo-buildpacks/nodejs \
  --buildpack gcr.io/paketo-buildpacks/procfile \
  --default-process hello
docker run samples/nodejs # should print "hello world"
Copied!

ファイアーウォールの内側でビルドする

プロキシの設定

Paketo Buildpack は環境変数 http_proxy や https_proxy や no_proxy で http トラフィックを送信するプロキシアドレスを変更できます。ホストマシンで pack コマンドを実行するときにこれらの環境変数を設定すると、ビルドコンテナに継承させることができます。

依存関係の対応付け

Paketo Buildpack はさまざまな依存対象をインターネットからダウンロードします。例えば、Java Buildpack なら BellSoft Liberica JRE を Liberica の github releases からダウンロードします。

依存対象の URI がビルド環境からアクセスできないネットワークにある場合、依存対象の URI としてバインディングと対応付けることができます。組織としてアクセスを許可する場所へ検査済みの依存対象（の複製）をアップロードすれば、開発者や CI/CD パイプラインはバインディングで指定した場所から、依存対象へアクセスできるようになります。

URI の対応付けをするのは、type を dependency-mapping にした1つ以上のバインディングです。それぞれのバインディングには、キー sha256 の値として依存対象を参照可能な URI を格納します。 Buildpack が依存対象をダウンロードするために必要な情報（sha256 や元の uri を含む）は、それぞれのコンポーネント Buildpack の buildpack.toml で定義されています。

例：JRE を内部ネットワークの URI へ対応付ける

GitHub へアクセスできない環境で、Bellsoft Liberica JRE を依存対象として含むビルドを成功させるには、次のようにします。

Bellsoft Liberica buildpack の buildpack.toml から必要な依存対象の sha256 と元の uri を確認する。以下は具体例です
- sha256: b4cb31162ff6d7926dd09e21551fa745fa3ae1758c25148b48dadcf78ab0c24c
- uri: https://github.com/bell-sw/Liberica/releases/download/11.0.8+10/bellsoft-jre11.0.8+10-linux-amd64.tar.gz
uri から依存対象をダウンロードして、ビルド中にアクセスできる内部ネットワークのどこかへ配置する
バインディングを作成する
- type: dependency-mapping
- sha256: 内部ネットワークに配置した依存対象の URI
作成したバインディングを指定してコンテナイメージをビルドします

CA 証明書

Paketo CA Certificates Buildpack を使うとシステムのトラストストアへ CA 証明書を追加できます。

CA 証明書を追加するには type が ca-certficates のバインディングを使用します。キーは証明書の名前、値は PEM 形式にした単独の CA 証明書にします。

<binding-name>
├── <cert file name>
└── type

指定された言語モジュール Buildpack に CA Certficates Buildpack が含まれていないときは、pack コマンドを実行するとき、明示的に指定します。

例：CA 証明書を追加する

サンプルリポジトリの Go アプリケーションは指定した URL に HEAD リクエストを送信します。

ファイル <your-ca.pem> は、<url> への TLS 通信をするための証明書で、PEM 形式にしておきます。このファイルをバインディングへ追加しましょう。

cp <your-ca.pem> ca-certificates/binding/

CA Certificates Buildpack を指定して pack build コマンドを実行します。

pack build samples/ca-certificates \
    --path ca-certificates \
    --buildpack paketo-buildpacks/ca-certificates \
    --buildpack paketo-buildpacks/go

バインディングを指定して、引数に <url> を指定してサンプルアプリケーションを実行します。成功すれば SUCCESS! と表示されます。

docker run --rm \
  --env SERVICE_BINDING_ROOT=/bindings \
  --volume "$(pwd)/ca-certficates/binding:/bindings/ca-certificates" \
  samples/ca-certificates <url>

CA 証明書を無効化する

言語モジュール Buildpack に Paketo CA Certifcates Buildpack が含まれている場合、コンテナイメージを実行するとき、常に証明書ファイルを探索し、追加するようになります。

この振る舞いを変更するには、ビルド時に環境変数 BP_ENABLE_RUNTIME_CERT_BINDING へ false を設定します。そうすると、実行時に証明書を探索する機能は無効化され、CA Certifcates Buildpack はビルド時にバインディングで指定した証明書ファイルだけを探索するようになります。

独自ラベルを指定する

Image Labels Buildpackを使うと、コンテナイメージにラベルを追加できます。

名前が BP_OCI_ で始まる環境変数は OCI 特有のラベルを設定するために使用できます。例えば、ビルド時に BP_OCI_AUTHORS を指定すると、Image Labels Buildpack はキー org.opencontainers.image.authors のラベルを設定します。

環境変数 BP_IMAGE_LABELS の値に、空白文字を区切り文字として並べたキーと値の対を指定すると、複数の任意のラベルを設定できます。ラベルの値に空白文字を含む場合はクォート文字でエスケープできます。

言語モジュール Buildpack に Image Labels Buildpack が含まれていないときは、pack コマンドを実行するとき、明示的に指定します。

例：独自のラベルを設定する

pack build samples/nodejs \
  --path nodejs/yarn \
  --buildpack  gcr.io/paketo-buildpacks/nodejs \
  --buildpack  gcr.io/paketo-buildpacks/image-labels \
  --env "BP_OCI_DESCRIPTION=Demo Application" \
  --env 'BP_IMAGE_LABELS=io.packeto.example="Adding Custom Labels"'
docker inspect samples/nodejs | jq '.[].Config.Labels["org.opencontainers.image.description"]' # should print "Demo Application"
docker inspect samples/nodejs | jq '.[].Config.Labels["io.packeto.example"]' # should print "Adding Custom Labels"
Copied!

ロケールを設定する

初期設定では、Paketo Buildpack で作成したコンテナイメージにロケールは設定されていません。 locale コマンドを実行すると次のように表示されるでしょう。

LANG=
LANGUAGE=
LC_CTYPE="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_COLLATE="POSIX"
LC_MONETARY="POSIX"
LC_MESSAGES="POSIX"
LC_PAPER="POSIX"
LC_NAME="POSIX"
LC_ADDRESS="POSIX"
LC_TELEPHONE="POSIX"
LC_MEASUREMENT="POSIX"
LC_IDENTIFICATION="POSIX"
LC_ALL=

ロケールを設定するには適切な環境変数を指定しなければなりません。例えば、Docker でコンテナイメージを実行するなら docker run -e LANG=en_US.utf8 ... のようにします。

常に必要な設定ではありませんが、アプリケーションの出力に影響する場合があります。例えば、アプリケーションがユニコード文字列を標準出力と標準エラー出力へ書き込んでも、ユニコードに対応したロケールを設定していなければ、docker logs などで正しく表示されない可能性があります。

Edit

Last modified: September 14, 2021