第2章 CLI ツール

2.1. 概要

apb CLI ツールを使用する Ansible Playbook Bundle (APB) の作成者は、APB を作成し、ビルドしてこれをコンテナーレジストリーに公開できます。これにより、ベストプラクティスが実施され、詳細事項が処理されることでデプロイが容易になります。

2.2. ツールのインストール

2.2.1. 前提条件

2.2.1.1. Docker デーモン

docker デーモンは正常にインストールされており、システム上で実行されている必要があります。

2.2.1.2. アクセスパーミッション

apb ツールは、ユーザーにトークンを使用するクラスターユーザーとしてログインすることを要求します。デフォルトの system:admin システムユーザーはツールの認証に使用できるトークンを持たないために適切ではありません。さらに、apb ツールの機能全体を許可するには、数多くのローカルロール (プロジェクト単位) およびクラスターロール (クラスター全体) が存在している必要があります (「Cluster and Local RBAC」を参照してください)。

最も簡単なオプションとして、ユーザーに cluster-admin クラスターロールを持たせることができます。このロールを別のユーザーに追加するには、このパーミッションをすでに持つユーザー (system:admin デフォルトシステムユーザーなど) として以下を実行することができます。

警告

これはクラスターの root であり、開発設定でのみ使用する必要があります。

$ oc adm policy add-cluster-role-to-user cluster-admin <user>
$ oc login -u <user> <openshift_server>

さらに厳密にパーミッションが設定された環境が必要な場合、デフォルトで提供される OpenShift テンプレートにより developer というユーザーのロールが付与されます。このテンプレートは、各種ロールを作成できるパーミッションのあるユーザーによって実行される必要があります。developer ユーザーにはこのようなパーミッションはありませんが、system:admin ユーザーにはこれを実行するためのパーミッションがあります。

テンプレートを実行するには、以下を実行します。

  1. openshift-permissions.template.yaml ファイルをローカルにダウンロードします。
  2. 以下のコマンドを実行します。

    $ oc process -f openshift-permissions.template.yaml \
      -p BROKER_NAMESPACE=openshift-ansible-service-broker \
      -p GLOBAL_IMAGE_PROJECT=default \
      [-p USER=<your_desired_user>] \ 1
      | oc create -f -
    1
    デフォルトで、テンプレートは developer ユーザーのロールを付与します。オプションで -p フラグを使用して、デフォルト値を必要なユーザーで上書きすることができます。

2.2.2. RPM でのインストール

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

$ sudo yum install apb

2.2.3. インストールの検証

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

2.3. 通常のワークフロー

2.3.1. ローカルレジストリー

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>

2.3.2. リモートレジストリー

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

2.4. APB 作成コマンド

2.4.1. init

説明

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

使用法
$ apb init [OPTIONS] NAME
引数

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

オプション
オプション (短縮形表記)説明

--help, -h

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

--force

ディレクトリーの再初期化および上書きを強制的に実行します。

--async {required,optional,unsupported}

アプリケーションの非同期操作を指定します。通常は optional にデフォルト設定されます。

--bindable

アプリケーションをバインド可能な設定で生成します。

--skip-provision

プロビジョニング Playbook およびロールを生成しません。

--skip-deprovision

プロビジョニング解除 Playbook およびロールを生成しません。

--skip-bind

バインド Playbook およびロールを生成しません。

--skip-unbind

バインド解除 Playbook およびロールを生成しません。

--skip-roles

ロールを生成しません。

注記

非同期バインドおよびバインド解除は実験的な機能であり、デフォルトではサポートされておらず、有効にされていません。

ディレクトリー 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

2.4.2. prepare

説明

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

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

使用法
$ apb prepare [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--dockerfile DOCKERFILE, -f DOCKERFILE

APB 仕様を、Dockerfile という名前のファイルの代わりにターゲットファイル名に書き込みます。

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

$ apb prepare

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

$ apb prepare --dockerfile Dockerfile-custom

2.4.3. build

説明

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

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

使用法
$ apb build [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--tag TAG

ビルドイメージのタグを <registry>/<org>/<name> 形式で文字列に設定します。

--registry

イメージのタグのレジストリー部分です (例: docker.io)。

--org, -o

イメージのタグのユーザーまたは組織の部分です。

イメージをビルドし、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-customDockerfile 定義として使用してイメージをビルドします。

$ apb build --dockerfile Dockerfile-custom

2.4.4. push

説明

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

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

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

使用法
$ apb push [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--broker BROKER_URL

OAB へのルートです。

--namespace NAMESPACE

OpenShift Container レジストリーにプッシュする namespace です。

--openshift, -o

OpenShift Container レジストリーを使用します。

--dockerfile DOCKERFILE, -f DOCKERFILE

内部レジストリーイメージをビルドするための Dockerfile です。通常は Dockerfile に設定されますが、任意のファイル名に設定することができます。

--secure

OAB へのセキュアな接続を使用します。

--username USERNAME

ブローカーの通信で使用される基本認証ユーザー名です。

--password PASSWORD

ブローカーの通信で使用される基本認証パスワードです。

--no-relist

APB のブローカーへのプッシュ後にカタログを再度一覧表示しません。

--broker-name

ServiceBroker Kubernetes リソースの名前です。

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

$ apb push

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

$ apb push

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

$ apb push --namespace myproject

2.4.5. test

説明

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

使用法
$ apb test [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--tag TAG

ビルドイメージのタグを <registry>/<org>/<name> 形式で文字列に設定します。

テストを実行します。

$ apb test

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

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

2.5. ブローカーのユーティリティーコマンド

2.5.1. list

説明

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

使用法
$ apb list [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--broker BROKER_URL

OAB へのルートです。

--secure

OAB へのセキュアな接続を使用します。

--verbose, -v

OAB から詳細な仕様情報を出力します。

--output {yaml,json}, -o {yaml,json}

詳細な出力形式を yaml (デフォルト) または json で指定します。

--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME

使用される基本認証ユーザー名を指定します。

--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD

使用される基本認証パスワードを指定します。

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

$ apb list

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

$ apb list -v

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

$ apb list -v -o json

2.5.2. bootstrap

説明

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

使用法
$ apb bootstrap [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--broker BROKER_URL

OAB へのルートです。

--secure

OAB へのセキュアな接続を使用します。

--no-relist

ブローカーのブートストラップにカタログを再度一覧表示しません。

--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME

使用される基本認証ユーザー名を指定します。

--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD

使用される基本認証パスワードを指定します。

--broker-name BROKER_NAME

ServiceBroker Kubernetes リソースの名前です。

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

$ apb bootstrap

2.5.3. remove

説明

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

使用法
$ apb remove [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--broker BROKER_URL

OAB へのルートです。

--secure

OAB へのセキュアな接続を使用します。

--all

すべての保存された APB を削除します。

--id ID

削除する APB の ID です。

--secure

OAB へのセキュアな接続を使用します。

--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME

使用される基本認証ユーザー名を指定します。

--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD

使用される基本認証パスワードを指定します。

--no-relist

削除後にカタログを再度一覧表示しません。

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

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb
注記

APB の ID が必要な場合は、以下を使用します。

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

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

$ apb remove --all

2.5.4. relist

説明

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

使用法
$ apb relist [OPTIONS]
オプション
オプション (短縮形表記)説明

--help, -h

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

--broker-name BROKER_NAME

ServiceBroker Kubernetes リソースの名前です。

--secure

OAB へのセキュアな接続を使用します。

--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME

使用される基本認証ユーザー名を指定します。

--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD

使用される基本認証パスワードを指定します。

$ apb relist

2.6. その他のコマンド

2.6.1. help

説明

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

使用法
$ apb help
$ apb help
$ apb -h

このページには機械翻訳が使用されている場合があります (詳細はこちら)。