Ansible Playbook Bundle 開発ガイド

APB をビルドし、デプロイする前に APB のディレクトリー構造および仕様ファイルを準備する必要があります。作業の開始のトピックでは、APB の初回作成時の段階的なチュートリアルを提供しています。 以下のセクションでは、このワークフローについて簡単に説明しています。

example-apb/
├── Dockerfile
├── apb.yml
└── roles/
│   └── example-apb-openshift
│       ├── defaults
│       │   └── main.yml
│       └── tasks
│           └── main.yml
└── playbooks/
    └── provision.yml
    └── deprovision.yml
    └── bind.yml
    └── unbind.yml

version: 1.0
name: my-test-apb
description: This is a sample application generated by apb init
bindable: False
async: optional
metadata: 1
  displayName: my-test
plans:
  - name: default
    description: This default plan deploys my-test-apb
    free: True
    metadata: {}
    parameters: [] 2

ビルドの手順では、名前付き Playbook から配布するコンテナーイメージをビルドします。パッケージ化により、Ansible ランタイムを含むベースイメージと Playbook の実行に必要な Ansible アーティファクトおよびその他の依存関係が組み合わされます。

結果として、いくつかの引数を取るための ENTRYPOINT が設定されたコンテナーイメージがビルドされます。 それらの 1 つにはプロビジョニングおよびプロビジョニング解除などの実行メソッドが含まれます。

図1.1 APB のビルド

APB のデプロイにより、コンテナーが起動し、必要な変数と共に実行される Playbook の名前が渡されます。OAB を経由しなくても APB を直接起動できます。それぞれの APB はパッケージ化されるため、その ENTRYPOINT が実行時に Ansible を起動します。このコンテナーの有効期限は短く設定され、アプリケーションを管理し、終了するための Ansible Playbook を実行します。

通常の APB デプロイでは、APB コンテナーは、Ansible ロールを実行する provision.yml Playbook を実行してアプリケーションをプロビジョニングします。このロールは、oc create コマンドを呼び出すか、または Ansible モジュールを利用して OpenShift Container Platform リソースを作成します。最終的な結果として、APB は Ansible を実行して OpenShift Container Platform と通信し、対象アプリケーションのプロビジョニングのオーケストレーションを実行します。

以下の図は、ユーザーが利用可能な APB の一覧を検出し、次に選択した APB をプロジェクトにプロビジョニングする 2 つのフェーズで設定されるデプロイメントのフローを示しています。

図1.2 利用可能な APB の一覧表示

OpenShift Container Platform ユーザーはサービスをプロジェクトにプロビジョニングすることを検討しているので、OpenShift Container Platform UI (Web コンソールまたは CLI) にアクセスしてサービスカタログと対話し、すでに利用可能な APB を検出します。

サービスカタログは、ユーザーに表示するために OAB から APB の一覧を要求します。

OAB は設定済みのすべてのコンテナーレジストリー (クラスターの OpenShift Container レジストリーまたはその他のリモートレジストリー) で APB (LABEL=apb-1.0 などの特定ラベルの付いたイメージ) を検索します。

OAB は検出された一覧をサービスカタログに返し、ユーザーはこの一覧を OpenShift Container Platform UI で表示できます。

図1.3 選択した APB のデプロイ

ユーザーはサービスカタログで提供される検出された一覧から APB を選択できるようになります。

サービスカタログは、ユーザーが選択した APB の使用について要求した OAB と通信します。

OAB は適切なコンテナーイメージレジストリーからイメージプルを開始します。

イメージのプル後に、OAB はアプリケーションのオーケストレーションのロジックを APB に送ります。サービスは APB コンテナーをいくつかのパラメーターで実行してデプロイされます。これを実行するには、以下のコマンドを一時的な namespace の OpenShift Container Platform クラスターに対して実行します。

$ oc run $IMAGE $METHOD $VARS ansible-playbook ${METHOD}.yaml ${VARS}

このコマンドは、以下のように分けられます。

結果として、ユーザーは OpenShift Container Platform UI から要求したサービスがプロジェクトに正常にプロビジョニングされていることを確認できます。

APB CLI ツールは apb パッケージによって提供されます。 これは rhel-7-server-ose-3.11-rpms チャンネルで利用できます。

$ sudo yum install apb

apb help を実行して、ツールが適切にインストールされていることを確認します。

$ apb help
usage: apb [-h] [--debug] [--project BASE_PATH]
           {init,help,prepare,push,bootstrap,list,remove,build} ...

APB tooling for assisting in building and packaging APBs.

optional arguments:
  -h, --help            show this help message and exit
  --debug               Enable debug output
  --project BASE_PATH, -p BASE_PATH
                        Specify a path to your project. Defaults to CWD.

subcommand:
  {init,help,prepare,push,bootstrap,list,remove,build}
    init                Initialize the directory for APB development
    help                Display this help message
    prepare             Prepare an ansible-container project for APB packaging
    push                Push local APB spec to an OAB
    bootstrap           Tell OAB to reload APBs from the
                        container repository
    list                List APBs from the target OAB
    remove              Remove APBs from the target OAB
    build               Build and package APB container

OpenShift Container レジストリーを使用して APB を調達するには、OpenShift Ansible Broker を local_openshift タイプのレジストリーアダプターを使用するように設定する必要があります。詳細は、config のセクションを参照してください。

$ apb init my-new-apb
$ cd my-new-apb
$ apb build
$ apb push
$ apb list

APB をホストするためにデフォルトの openshift namespace 以外の namespace を使用する場合は、以下のコマンドを使用できます。

$ apb push --namespace <namespace>

OAB は、docker.io/ansibleplaybookbundle または独自の個人アカウントなどの、リモートレジストリーや組織を使用するように設定することもできます。これを APB を開発するために使用するには、APB をビルドし、リモートレジストリーにプッシュしてから bootstrap を実行して APB を再度読み込むことができます。

$ apb init my-new-apb
$ cd my-new-apb
$ apb build --tag docker.io/my-org/my-new-apb
$ docker push docker.io/my-org/my-new-apb
$ apb bootstrap
$ apb list

説明

新規 APB のディレクトリー構造を初期化します。さらに、適切なデフォルト値が設定された新規 APB のサンプルファイルを作成します。

使用方法

$ apb init [OPTIONS] NAME

引数

NAME: 作成される APB およびディレクトリーの名前です。

オプション

例

ディレクトリー my-new-apb を作成します。

$ apb init my-new-apb
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   ├── deprovision.yml
# │   └── provision.yml
# └── roles
#     ├── deprovision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     └── provision-my-new-apb
#         └── tasks
#             └── main.yml

ディレクトリー my-new-apb を作成しますが、プロビジョニング解除 Playbook およびロールの生成を省略します。

$ apb init my-new-apb --skip-deprovision
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   └── provision.yml
# └── roles
#     └── provision-my-new-apb
#         └── tasks
#             └── main.yml

ディレクトリー my-new-apb を作成し、古いバージョンを上書きします。APB はバインド可能になるように設定され、async をオプションに設定します。

$ apb init my-new-apb --force --bindable --async optional
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   ├── bind.yml
# │   ├── deprovision.yml
# │   ├── provision.yml
# │   └── unbind.yml
# └── roles
#     ├── bind-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     ├── deprovision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     ├── provision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     └── unbind-my-new-apb
#         └── tasks
#             └── main.yml

説明

APB を base64 エンコーディングでコンパイルし、これを Dockerfile のラベルとして作成します。

これにより、OAB はイメージをダウンロードせずにレジストリーから APB メタデータを読み取ることができます。このコマンドは APB ディレクトリー内から実行される必要があります。build コマンドを実行すると、prepare も自動的に実行されます。 つまり、通常は prepare 自体を実行する必要はありません。

使用方法

$ apb prepare [OPTIONS]

オプション

例

Dockerfile に仕様フィールドのラベルを作成します。

$ apb prepare

Dockerfile-custom に仕様フィールドのラベルを作成します。

$ apb prepare --dockerfile Dockerfile-custom

説明

APB のイメージをビルドします。

タグを使って apb prepare および docker build を実行するのと同様です。

使用方法

$ apb build [OPTIONS]

オプション

例

イメージをビルドし、apb.yml の名前フィールドをタグとして使用します。

$ apb build

イメージをビルドし、タグ docker.io/my-org/my-new-apb を使用します。

$ apb build --tag docker.io/my-org/my-new-apb

イメージをビルドし、タグ docker.io/my-org/<my-apb-name> を使用します。

$ apb build --registry docker.io --org my-org

ファイル Dockerfile-custom を Dockerfile 定義として使用してイメージをビルドします。

$ apb build --dockerfile Dockerfile-custom

説明

APB を OpenShift Container レジストリーに、またはこれが OAB による読み取りが行われるブローカーのモックレジストリーにアップロードします。

ブローカーのモックレジストリーを使用する場合、仕様はアップロードされ、OpenShift Container Platform に表示されますが、通常 OpenShift Container Platform はイメージをレジストリーからプルします。このレジストリーは通常は oc cluster up が実行されるレジストリーになります。

OpenShift Container レジストリーを使用する場合、イメージは OpenShift Container Platform に直接アップロードされます。

使用方法

$ apb push [OPTIONS]

オプション

例

OAB 開発エンドポイントにプッシュします。

$ apb push

ローカルの OpenShift Container レジストリーにプッシュします。

$ apb push

namespace myproject の下のローカルの OpenShift Container レジストリーにプッシュします。

$ apb push --namespace myproject

説明

APB 単体テストを実行します。

使用方法

$ apb test [OPTIONS]

オプション

例

テストを実行します。

$ apb test

テストを実行しますが、ビルドされたイメージの特定のタグを使用します。

$ apb test --tag docker.io/my-org/my-new-apb

説明

ブローカーが読み込んだすべての APB を一覧表示します。

使用方法

$ apb list [OPTIONS]

オプション

例

名前、ID および説明を含む APB の基本的な一覧です。

$ apb list

詳細な、読み取りが容易な仕様を一覧表示します。

$ apb list -v

すべての JSON 出力を一覧表示します。

$ apb list -v -o json

説明

OAB がすべての APB をレジストリーから再度読み込むことを要求します。

使用方法

$ apb bootstrap [OPTIONS]

オプション

例

APB の基本的な再読み込み:

$ apb bootstrap

説明

1 つ (またはすべての) APB を OAB から削除します。

使用方法

$ apb remove [OPTIONS]

オプション

例

ID を使用して APB を削除します。

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb

$ apb list
ID                                NAME                     DESCRIPTION
ca91b61da8476984f18fc13883ae2fdb  dh-etherpad-apb          Note taking web application

すべての APB を削除します。

$ apb remove --all

説明

サービスカタログに対し、ブローカーに一致する提供されたサービスを再度一覧表示するよう強制します。

使用方法

$ apb relist [OPTIONS]

オプション

例

$ apb relist

説明

ヘルプメッセージを表示します。

使用方法

$ apb help

例

$ apb help

$ apb -h

このチュートリアルでは、いくつかのサンプル Ansible Playbook Bundle (APB) の作成を行います。APB でプロビジョニング、プロビジョニング解除、バインドおよびバインド解除を可能にするアクションを作成します。APB の設計についての詳細は、設計のトピックを参照してください。APB の作成についてのさらに詳細な情報は、参照のトピックを参照してください。

独自の APB を作成する前に、開発環境をセットアップする必要があります。

このチュートリアルでは、コンテナー化された hello world アプリケーションの APB を作成します。ここでは、APB hello-world-apb をミラーリングする基本的な APB を扱います。

直前のセクションで作成された完全に新規の APB は、そのままの状態では多くのことを実行できないため、いくつかのアクションを追加する必要があります。そのためには、いくつかのアクションを追加する必要があります。サポートされるアクションは以下のとおりです。

以下のセクションで上記のアクションのそれぞれを追加していきます。開始前に、以下を確認してください。

3.1.4.1. プロビジョニング

apb init プロセス中に、プロビジョニングタスクの 2 つの部分が消去されました。Playbook playbooks/provision.yml および roles/provision-my-test-apb の関連ロール。

my-test-apb
├── apb.yml
├── Dockerfile
├── playbooks
│   └── provision.yml 1
└── roles
    └── provision-my-test-apb
        └── tasks
            └── main.yml 2

1

この Playbook を検査します。

2

このロールを編集します。

playbooks/provision.yml ファイルは、プロビジョニングアクションが OAB から呼び出される際に実行される Ansible Playbook です。Playbook は変更可能ですが、ここではコードをそのままにしておきます。

playbooks/provision.yml

- name: my-test-apb playbook to provision the application
  hosts: localhost
  gather_facts: false
  connection: local
  roles:
  - role: ansible.kubernetes-modules
    install_python_requirements: no
  - role: ansibleplaybookbundle.asb-modules
  - role: provision-my-test-apb
    playbook_debug: false

Playbook は localhost で実行され、ロール provision-my-test-apb を実行します。この Playbook はサービスブローカーで作成されるローカルコンテナーで機能します。ansible.kubernetes-modules ロールによって、kubernetes-modules を使用して OpenShift Container Platform リソースを作成できます。asb-modules は OAB で使用できる追加の機能を提供します。

現時点で、このロールに設定されたタスクはありません。roles/provision-my-test-apb/tasks/main.yml のコンテンツには、共通のリソース作成タスクを示すコメントのみが含まれます。 現時点でプロビジョニングタスクを実行できますが、実行するタスクがないために APB コンテナーが単純に起動されるのみで、何もデプロイせずに終了されることになります。

これは Web コンソールを使用し、my-test APB をクリックして、これを getting-started プロジェクトにデプロイして試してみることができます。

図3.2 my-test のプロビジョニング

プロビジョニングの実行中、新規の namespace が dh-my-test-apb-prov-<random> という名前で作成されます。開発モードでは、これは永続しますが、通常この namespace は正常な完了後に削除されます。APB がプロビジョニングに失敗すると、デフォルトでは namespace は永続します。

Pod リソースを参照すると、ログで APB の実行を確認することができます。Pod のログを表示するには、以下を実行します。

1. Web コンソールを使用してすべての namespace を表示し、作成日で並べ替えるか、または以下のコマンドを使用するかのいずれかを実行して namespace を検索します。

   $ oc get ns
   NAME                                STATUS    AGE
   ansible-service-broker              Active    1h
   default                             Active    1h
   dh-my-test-apb-prov-<random>        Active    4m

2. プロジェクトに切り替えます。

   $ oc project dh-my-test-apb-prov-<random>
   Now using project "dh-my-test-apb-prov-<random>" on server "<cluster_host>:<port>".

3. Pod 名を取得します。

   $ oc get pods
   NAME             READY     STATUS      RESTARTS   AGE
   <apb_pod_name>   0/1       Completed   0          3m

4. ログを表示します。

   $ oc logs -f <apb_pod_name>
   ...
   + ansible-playbook /opt/apb/actions/provision.yml --extra-vars '{"_apb_plan_id":"default","namespace":"getting-started"}'
   PLAY [my-test-apb playbook to provision the application] ***********************
   TASK [ansible.kubernetes-modules : Install latest openshift client] *************
   skipping: [localhost]
   TASK [ansibleplaybookbundle.asb-modules : debug] *******************************
   skipping: [localhost]
   PLAY RECAP *********************************************************************
   localhost                  : ok=0    changed=0    unreachable=0    failed=0

3.1.4.1.1. デプロイメント設定の作成

APB は少なくともアプリケーション Pod をデプロイできる必要があります。これは デプロイメント設定を指定して実行できます。

1. provision-my-test-apb/tasks/main.yml ファイルでコメントアウトされている最初のタスクの 1 つに、デプロイメント設定の作成があります。このコメントを解除することも、または以下を貼り付けることもできます。

   注記

   通常、image: 値を独自のアプリケーションイメージに置き換えることができます。

   - name: create deployment config
     openshift_v1_deployment_config:
       name: my-test
       namespace: '{{ namespace }}' 1
       labels: 2
         app: my-test
         service: my-test
       replicas: 1 3
       selector: 4
         app: my-test
         service: my-test
       spec_template_metadata_labels:
         app: my-test
         service: my-test
       containers: 5
       - env:
         image: docker.io/ansibleplaybookbundle/hello-world:latest
         name: my-test
         ports:
         - container_port: 8080
           protocol: TCP

   1

   デプロイメント設定が置かれる必要のある namespace を指定します。

   2

   オブジェクトの編成、分類および選択に使用されます。

   3

   1 つの Pod のみを必要とするように指定します。

   4

   selector セクションは Pod に対する ラベルのクエリーです。

   5

   この containers セクションは、コンテナーを TCP のポート 8080 で実行される hello-world アプリケーションで指定します。イメージ は docker.io/ansibleplaybookbundle/hello-world に保存されます。

   詳細については、APB の作成: 参照を参照してください。 また、すべてのフィールドの詳細については、ansible-kubernetes-modules ドキュメントを参照してください。

2. APB をビルドし、プッシュします。

   $ apb build
   $ apb push

3. Web コンソールを使用して APB をプロビジョニングします。

4. プロビジョニングの後に、新規に実行される Pod および新規のデプロイメント設定が利用可能になります。OpenShift Container Platform リソースをチェックして検証します。

   $ oc project getting-started
   $ oc get all
   NAME         REVISION   DESIRED   CURRENT   TRIGGERED BY
   dc/my-test   1          1         1         config
   
   NAME           DESIRED   CURRENT   READY     AGE
   rc/my-test-1   1         1         1         35s
   
   NAME                 READY     STATUS    RESTARTS   AGE
   po/my-test-1-2pw4t   1/1       Running   0          33s

   また、Web コンソールのプロジェクトの Overview ページでデプロイされたアプリケーションを表示できます。

この Pod を現行の状態で使用する唯一の方法として、以下を実行します。

$ oc describe pods/<pod_name>

これにより、その IP アドレスを検索し、それに直接アクセスします。複数の Pod がある場合、それらは別個にアクセスされます。それらを単一ホストのように処理するには、次のセクションで説明されているように サービス を作成する必要があります。

ヒント

次に進む前にクリーンアップし、再度プロビジョニングを実行するために、getting-started プロジェクトを削除してから再作成するか、または新規のプロジェクトを作成することができます。

3.1.4.1.2. サービスの作成

複数の Pod を使用して負荷分散を行い、ユーザーがそれらに単一ホストとしてアクセスできるようにサービスを作成する必要になる場合があります。 以下を実行します。

1. provision-my-test-apb/tasks/main.yml ファイルを変更し、以下を追加します。

   - name: create my-test service
     k8s_v1_service:
       name: my-test
       namespace: '{{ namespace }}'
       labels:
         app: my-test
         service: my-test
       selector:
         app: my-test
         service: my-test
       ports:
         - name: web
           port: 80
           target_port: 8080

   selector セクションでは、my-test サービスに適切な Pod を組み込むことができます。ports はターゲットポートを Pod から取得し (8080)、それらをサービスの単一ポート (80) として公開します。アプリケーションは 8080 で実行されていますが、これがデフォルトの HTTP ポート 80 で利用可能になることに注意してください。

   ポートの name フィールドでは、このポートを今後に他のリソースで使用できるように指定できます。詳細については、k8s_v1_service モジュールを参照してください。

2. APB をビルドし、プッシュします。

   $ apb build
   $ apb push

3. Web コンソールを使用して APB をプロビジョニングします。

プロビジョニング後に、新規サービスが Web コンソールまたは CLI に表示されます。Web コンソールでは、アプリケーションの Overview ページの Networking の下か、または Applications → Services の下で新規サービスをクリックできます。負荷が分散されたアプリケーションに使用するために使用できるサービスの IP アドレスが表示されます。

コマンドラインでサービスの情報を表示するには、以下を実行できます。

$ oc project getting-started
$ oc get services
$ oc describe services/my-test

describe は、サービスにアクセスするために使用する IP アドレスを表示します。ただし、ユーザーがアプリケーションにアクセスするために IP アドレスを使用する方法は通常は理想的な方法ではありません。その代わりに、次のセクションで説明されるように route を作成する必要があります。

ヒント

次に進む前にクリーンアップし、再度プロビジョニングを実行するために、getting-started プロジェクトを削除してから再作成するか、または新規のプロジェクトを作成することができます。

3.1.4.1.3. ルートの作成

アプリケーションへの外部アクセスは、信頼できる名前付きルートで公開できます。

1. provision-my-test-apb/tasks/main.yml ファイルを変更して以下を追加します。

   - name: create my-test route
     openshift_v1_route:
       name: my-test
       namespace: '{{ namespace }}'
       labels:
         app: my-test
         service: my-test
       to_name: my-test
       spec_port_target_port: web

   to_name はターゲットサービスの名前です。spec_port_target_port はターゲットサービスのポートの名前を参照します。詳細は、openshift_v1_route モジュール を参照してください。

2. APB をビルドし、プッシュします。

   $ apb build
   $ apb push

3. Web コンソールを使用して APB をプロビジョニングします。

プロビジョニング後に、作成される新規ルートが表示されます。Web コンソールの getting-started プロジェクトの Overview ページでは、アクティブでクリック可能なルートリンクがアプリケーションに一覧表示されます。ルートをクリックするか、または URL にアクセスすると、hello-world アプリケーションが起動します。

CLI からルート情報を表示することもできます。

$ oc project getting-started

$ oc get routes
NAME      HOST/PORT                                   PATH      SERVICES   PORT      TERMINATION   WILDCARD
my-test   my-test-getting-started.172.17.0.1.nip.io             my-test    web                     None

$ oc describe routes/my-test
Name:			my-test
Namespace:		getting-started
...

この時点で、my-test アプリケーションは完全に機能し、負荷分散が行われており、拡張可能かつアクセス可能です。完成した APB を hello-world-apb サンプルリポジトリーの hello-world APB と比較できます。

my-test-apb/
├── apb.yml
├── Dockerfile
├── playbooks
│   └── deprovision.yml 1
└── roles
    └── deprovision-my-test-apb
        └── tasks
            └── main.yml 2

- name: my-test-apb playbook to deprovision the application
  hosts: localhost
  gather_facts: false
  connection: local
  roles:
  - role: ansible.kubernetes-modules
    install_python_requirements: no
  - role: ansibleplaybookbundle.asb-modules
  - role: deprovision-my-test-apb
    playbook_debug: false

- openshift_v1_route:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

- k8s_v1_service:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

- openshift_v1_deployment_config:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

my-apb/
├── ...
├── playbooks/
    ├── test.yml
    └── vars/
        └── test_defaults.yml

- name: test media wiki abp
  hosts: localhost
  gather_facts: false
  connection: local

  roles:
  - role: ansible.kubernetes-modules 1
    install_python_requirements: no

  post_tasks:
  - name: Load default variables for testing 2
    include_vars: test_defaults.yaml
  - name: create project for namespace
    openshift_v1_project:
      name: '{{ namespace }}'
  - name: Run the provision role. 3
    include_role:
      name: provision-mediawiki-apb
  - name: Run the verify role. 4
    include_role:
      name: verify-mediawiki-apb

my-apb/
├── ...
└── roles/
    ├── ...
    └── verify_<name>
        ├── defaults
             └── defaults.yml
        └── tasks
            └── main.yml

 - name: url check for media wiki
   uri:
     url: "http://{{ route.route.spec.host }}"
     return_content: yes
   register: webpage
   failed_when: webpage.status != 200

 - name: url check for media wiki
   uri:
     url: "http://{{ route.route.spec.host }}"
     return_content: yes
   register: webpage

  - name: Save failure for the web page
    asb_save_test_result:
      fail: true
      msg: "Could not reach route and retrieve a 200 status code. Recieved status - {{ webpage.status }}"
    when: webpage.status != 200

  - fail:
      msg: "Could not reach route and retrieve a 200 status code. Recieved status - {{ webpage.status }}"
    when: webpage.status != 200

  - name: Save test pass
    asb_save_test_result:
      fail: false
    when: webpage.status == 200

$ apb test

使用開始のトピックでは初回の Ansible Playbook Bundle (APB) の作成を手順ごとに説明していますが、このトピックでは、詳細な参考情報を提供します。ここでは APB を設定する基本的なコンポーネントについて詳細に説明し、経験豊かな APB 開発者が APB 内の個々のコンポーネントをよく理解するのに役立つ情報を提供します。

完成した APB サンプルについては、GitHub の ansibleplaybookbundle 組織で APB を参照できます。

以下は、APB のディレクトリー構造のサンプルを示しています。

example-apb/
├── Dockerfile
├── apb.yml
└── roles/
│   └── example-apb-openshift
│       ├── defaults
│       │   └── main.yml
│       └── tasks
│           └── main.yml
└── playbooks/
    └── provision.yml
    └── deprovision.yml
    └── bind.yml
    └── unbind.yml

APB 仕様ファイルは apb.yml に置かれ、ここではアプリケーションの概要情報が宣言されます。以下は APB 仕様の例です。

  version: 1.0
  name: example-apb
  description: A short description of what this APB does
  bindable: True
  async: optional 1
  metadata:
    documentationUrl: <link_to_documentation>
    imageUrl: <link_to_url_of_image>
    dependencies: ['<registry>/<organization>/<dependency_name_1>', '<registry>/<organization>/<dependency_name_2>']
    displayName: Example App (APB)
    longDescription: A longer description of what this APB does
    providerDisplayName: "Red Hat, Inc."
  plans:
    - name: default
      description: A short description of what this plan does
      free: true
      metadata:
        displayName: Default
        longDescription: A longer description of what this plan deploys
        cost: $0.00
      parameters:
        - name: parameter_one
          required: true
          default: foo_string
          type: string
          title: Parameter One
          maxlength: 63
        - name: parameter_two
          required: true
          default: true
          title: Parameter Two
          type: boolean

parameters:
  - name: my_param
    title: My Parameter
    type: enum
    enum: ['X', 'Y', 'Z']
    required: True
    default: X
    display_type: select
    display_group: Group 1

Dockerfile は APB イメージを実際にビルドする際に使用されます。そのため、これを独自のニーズに合わせてカスタマイズする必要があります。たとえば、PostgreSQL との対話が必要な Playbook を実行する場合、yum install コマンドを追加して必要なパッケージをインストールすることが必要になる可能性があります。

FROM ansibleplaybookbundle/apb-base
MAINTAINER Ansible Playbook Bundle Community

LABEL "com.redhat.apb.spec"=\
"<------------base64-encoded-spec------------>"


COPY roles /opt/ansible/roles
COPY playbooks /opt/apb/actions
RUN chmod -R g=u /opt/{ansible,apb}


### INSTALL THE REQUIRED PACKAGES
RUN yum -y install python-boto postgresql && yum clean all

USER apb

APB のアクションは APB の実行で使用されるコマンドです。サポートされている標準的なアクションは以下になります。

アクションを有効にするには、playbooks/ ディレクトリーに <action>.yml という名前の有効なファイルがなければなりません。これらの Playbook はすべてのことを実行できる、つまり、希望するすべてのアクションを作成できます。たとえば、 mediawiki-apb には update アクションを作成する Playbook があります。

ほとんどの APB にはリソースを作成するためのプロビジョニングアクションと、サービスを削除する際にリソースを破棄するためのプロビジョニング解除アクションがあります。

バインドおよびバインド解除アクションは、1 つのサービスの位置情報 (coordinate) を別のサービスで利用可能にする必要がある場合に使用されます。通常、これはデータサービスを作成し、これをアプリケーションで利用可能にする場合に該当します。現時点では、この位置情報 (coordinate) はプロビジョニング時に利用可能になります。

位置情報 (coordinate) を別のサービスで適切に利用可能にするには、asb_encode_binding モジュールを使用します。このモジュールは APB のプロビジョニングロールの最後に呼び出され、これは OpenShift Ansible Broker (OAB) にバインド認証情報を返します。

- name: encode bind credentials
  asb_encode_binding:
    fields:
      EXAMPLE_FIELD: foo
      EXAMPLE_FIELD2: foo2

このセクションでは、APB の開発時に作成される共通の OpenShift Container Platform リソースの一覧について説明します。利用可能なリソースモジュールの詳細の一覧については、Ansible Kubernetes Moduleを参照してください。

- name: create hello-world service
  k8s_v1_service:
    name: hello-world
    namespace: '{{ namespace }}'
    labels:
      app: hello-world
      service: hello-world
    selector:
      app: hello-world
      service: hello-world
    ports:
      - name: web
        port: 8080
        target_port: 8080

- k8s_v1_service:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

- name: create deployment config
  openshift_v1_deployment_config:
    name: hello-world
    namespace: '{{ namespace }}'
    labels:
      app: hello-world
      service: hello-world
    replicas: 1
    selector:
      app: hello-world
      service: hello-world
    spec_template_metadata_labels:
      app: hello-world
      service: hello-world
    containers:
    - env:
      image: docker.io/ansibleplaybookbundle/hello-world:latest
      name: hello-world
      ports:
      - container_port: 8080
        protocol: TCP

- openshift_v1_deployment_config:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

- name: create hello-world route
  openshift_v1_route:
    name: hello-world
    namespace: '{{ namespace }}'
    spec_port_target_port: web
    labels:
      app: hello-world
      service: hello-world
    to_name: hello-world

- openshift_v1_route:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

# Persistent volume resource
- name: create volume claim
  k8s_v1_persistent_volume_claim:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: present
    access_modes:
      - ReadWriteOnce
    resources_requests:
      storage: 1Gi

- name: create hello-world-db deployment config
  openshift_v1_deployment_config:
    name: hello-world-db
    ---
    volumes:
    - name: hello-world-db
      persistent_volume_claim:
        claim_name: hello-world-db
      test: false
      triggers:
      - type: ConfigChange

- openshift_v1_deployment_config:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: absent

- k8s_v1_persistent_volume_claim:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: absent

オプションの変数は、環境変数を使用して APB に追加できます。変数を APB に渡すには、.yml ファイルで変数置換をエスケープする必要があります。

たとえば、etherpad-apb の以下の roles/provision-etherpad-apb/tasks/main.yml ファイルについて見てみましょう。

- name: create mariadb deployment config
  openshift_v1_deployment_config:
    name: mariadb
    namespace: '{{ namespace }}'
    ...
    - env:
      - name: MYSQL_ROOT_PASSWORD
        value: '{{ mariadb_root_password }}'
      - name: MYSQL_DATABASE
        value: '{{ mariadb_name }}'
      - name: MYSQL_USER
        value: '{{ mariadb_user }}'
      - name: MYSQL_PASSWORD
        value: '{{ mariadb_password }}'

APB の変数は roles/provision-etherpad-apb/defaults/main.yml ファイルに定義されます。

playbook_debug: no
mariadb_root_password: "{{ lookup('env','MYSQL_ROOT_PASSWORD') | default('admin', true) }}"
mariadb_name: "{{ lookup('env','MYSQL_DATABASE') | default('etherpad', true) }}"
mariadb_user: "{{ lookup('env','MYSQL_USER') | default('etherpad', true) }}"
mariadb_password: "{{ lookup('env','MYSQL_PASSWORD') | default('admin', true) }}"
etherpad_admin_password: "{{ lookup('env','ETHERPAD_ADMIN_PASSWORD') | default('admin', true) }}"
etherpad_admin_user: "{{ lookup('env','ETHERPAD_ADMIN_USER') | default('etherpad', true) }}"
etherpad_db_host: "{{ lookup('env','ETHERPAD_DB_HOST') | default('mariadb', true) }}"
state: present

APB の開発において、開発者が apb ツールが提供する完全な開発ライフサイクルを使用できない状態になるいくつかの要因があります。これらの主な要因には、以下が含まれます。

開発者が上記のいずれかの条件を満たす場合は、以下のワークフローを使用してイメージを内部 OpenShift Container Platform レジストリーに公開し、ブローカーがイメージのブートストラップ (APB 仕様をブローカーに読み込むプロセス) を実行できるようにします。以下のセクションでは、apb ツールを使用する場合と使用しない場合にこれらの手順を実行する方法について説明しています。

OpenShift Container Platform イメージのビルド時に、アプリケーションを root ユーザーとして実行していないことは重要になります (可能な場合)。制限付き SCC で実行される場合、アプリケーションのイメージはランダム UID で起動します。これは、アプリケーションフォルダーが root ユーザーで所有されている場合には問題を生じさせます。

この問題の適切な回避策として、ユーザーを root グループに追加し、アプリケーションを root グループによって所有されるようにすることができます。任意のユーザー ID をサポートする方法についての詳細は、OpenShift Container Platform-Specific Guidelinesを参照してください。

以下は、/usr/src で実行されるノードアプリケーションの Dockerfile の例です。このコマンドは、アプリケーションが /usr/src にインストールされ、関連付けられた環境変数が設定された後に実行されます。

ENV USER_NAME=haste \
    USER_UID=1001 \
    HOME=/usr/src

RUN useradd -u ${USER_UID} -r -g 0 -M -d /usr/src -b /usr/src -s /sbin/nologin -c "<username> user" ${USER_NAME} \
               && chown -R ${USER_NAME}:0 /usr/src \
               && chmod -R g=u /usr/src /etc/passwd
USER 1001

Ansible モジュールのバグ対策として、Ansible から ConfigMaps を作成するために一時的な回避策を使用できます。

ConfigMaps の 1 つの一般的なユースケースとして、APB のパラメーターがアプリケーションまたはサービスの設定ファイル内で使用される場合があります。ConfigMap モジュールにより、ConfigMap を Pod にボリュームとしてマウントできます。これは設定ファイルを保存するために使用できます。 この方法では、ConfigMap を APB パラメーターから作成するために Ansible の テンプレート モジュール機能を活用することもできます。

以下は、ボリュームとして Pod にマウントされた Jinja テンプレートから ConfigMap を作成する例です。

- name: Create hastebin config from template
  template:
    src: config.js.j2
    dest: /tmp/config.js

- name: Create hastebin configmap
  shell: oc create configmap haste-config --from-file=haste-config=/tmp/config.js

<snip>

- name: create deployment config
  openshift_v1_deployment_config:
    name: hastebin
    namespace: '{{ namespace }}'
    labels:
      app: hastebin
      service: hastebin
    replicas: 1
    selector:
      app: hastebin
      service: hastebin
    spec_template_metadata_labels:
      app: hastebin
      service: hastebin
    containers:
    - env:
      image: docker.io/dymurray/hastebin:latest
      name: hastebin
      ports:
      - container_port: 7777
        protocol: TCP
      volumeMounts:
        - mountPath: /usr/src/haste-server/config
          name: config
    - env:
      image: docker.io/modularitycontainers/memcached:latest
      name: memcached
      ports:
      - container_port: 11211
        protocol: TCP
    volumes:
      - name: config
        configMap:
          name: haste-config
          items:
            - key: haste-config
              path: config.js

プロビジョニング呼び出しが失敗すると、デフォルトのエラーメッセージが Web コンソールに返されます。以下に例を示します。

Error occurred during provision. Please contact administrator if the issue persists.

失敗した場合にトラブルシューティングに使用する詳細情報を提供するために、Web コンソールがチェックできる APB についてのカスタムエラーメッセージを作成し、これをユーザーに返せるようにすることができます。

Kubernetes は Pod が終了ログに対して致命的なイベントのログを記録できるようにします。ログファイルの場所は、Pod の仕様の terminationMessagePath フィールドで設定され、デフォルトでは /dev/termination-log に設定されます。

ブローカーはこの終了ログでファイルに書き込まれたメッセージの有無を確認し、その内容をサービスカタログに渡します。Web コンソールは失敗が生じるとこれらのメッセージを表示します。

以下は、CloudFormation テンプレートを使用して、これを APB で実行する方法の例について示しています。

- name: Writing Termination Message
  shell: echo "[CloudFormation Error] - {{ ansible_failed_result.msg }}" > /dev/termination-log

- fail: msg="[APB Failed Plain - '{{ _apb_plan_id }}'] "

エラーが発生すると、このカスタムメッセージのサンプルは Pod が失敗する前にデフォルトの終了ログパスに書き込まれます。