第3章 APB の作成

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

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

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

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

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

3.1.4.1. プロビジョニング

apb init プロセスで、Playbook の playbooks/provision.yml と roles/provision-my-test-apb の関連ロールの、プロビジョニングタスクの 2 つの部分が表示されます。

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
│   └── provision.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-mediawiki123-apb
  - name: Run the verify role. 4
    include_role:
      name: verify-mediawiki123-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

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