Red Hat Quay の使用

Red Hat Quay 3

Red Hat Quay の使用

概要

Red Hat Quay の使用方法について確認します。

序文

Red Hat Quay コンテナーイメージレジストリーを使用すると、コンテナーイメージを中央の場所に保存できます。Red Hat Quay レジストリーの通常のユーザーとして、リポジトリーを作成してイメージを整理し、制御するリポジトリーへの読み取り (pull) および書き込み (push) アクセスを選択することができます。管理権限を持つユーザーは、ユーザーの追加やデフォルト設定を制御する機能など、幅広いタスクセットを実行できます。

本書では、Red Hat Quay がデプロイされており、この設定を開始し、使する準備が整っていることを前提としています。

第1章 Red Hat Quay のユーザーおよび組織

Red Hat Quay でコンテナーイメージを保持するリポジトリーの作成を開始する前に、これらのリポジトリーの整理方法を検討する必要があります。Red Hat Quay インスタンスのすべてのリポジトリーは、組織 または User に関連付けられている必要があります。

1.1. Red Hat Quayのテナントモデル

Quay tenancy model

  • 組織は、共通の名前空間の下でリポジトリを共有する方法を提供します。この名前空間は、一人のユーザーに属するものではなく、(会社などの)共有設定の多くのユーザーに属するものです。
  • チームは、組織が権限 (グローバルおよび特定のリポジトリの両方) をユーザーのセットまたはグループに委譲する方法を提供します。
  • ユーザーは、QuayのWeb UIやクライアント(podman loginなど)を使ってレジストリにログインできます。各ユーザーは自動的にユーザーnamespaceを取得します。例えば、quay-server.example.com/user/<username>のようになります。
  • スーパーユーザーは、ユーザーインターフェースのSuper User Admin Panelや、通常のユーザーには見えないまたはアクセスできない、Super User APIコールを通じて、強化されたアクセスと権限を持っています。
  • ロボットアカウントは、パイプラインツールなどの人間以外のユーザーにリポジトリへの自動アクセスを提供するもので、OpenShiftのサービスアカウントと似た性質を持っています。リポジトリ内のロボットアカウントに権限を付与するには、そのアカウントを他のユーザーやチームと同様に追加します。

1.2. ユーザーアカウントの作成

Red Hat Quay インスタンスの新規ユーザーを作成するには、以下を実行します。

  1. スーパーユーザー (デフォルトではquay) として Red Hat Quay にログインします。
  2. ホームページの右上からアカウント名を選択し、Super User Admin Panel を選択します。
  3. 左側の列から「Users」アイコンを選択します。
  4. 「Create User」ボタンを選択します。
  5. 新しいユーザーの「Username」および「Email address」を入力してから「Create User」ボタンを選択します。
  6. 「Users」ページに戻り、新規「 Username」の右側にある「Options」アイコンを選択します。以下の図のように、ドロップダウンメニューが表示されます。

    Select Options drop-down to change user passwords

  7. メニューから「Change Password」を選択します。
  8. 新しいパスワードを追加し、検証してから「Change User Password」ボタンを選択します。

新規ユーザーは、そのユーザー名とパスワードを使用して Web UI または一部のコンテナークライアント経由でログインできるようになります。

1.3. 組織アカウントの作成

ユーザーは、コンテナーイメージのリポジトリーを共有するために独自の組織を作成できます。新しい組織を作成するには、以下を実行します。

  1. ユーザーとしてログインしている場合、ホームページの右上からプラス記号 (+) を選択し、「New Organization」を選択します。
  2. 組織の名前を入力します。名前には、すべて小文字で、2 ~ 255 文字の英数字にする必要があります。
  3. 「Create Organization」を選択します。新しい組織が表示され、左側の列のアイコンからリポジトリー、チーム、ロボットアカウント、およびその他の機能を追加できます。以下の図は、設定 (settings) タブが選択された新しい組織ページの例を示しています。

    Create new repos and teams from an Organization page

第2章 リポジトリーの作成

リポジトリーは、関連するコンテナーイメージのセットを保存する中心となる場所を提供します。Red Hat Quay でリポジトリーを作成するには、プッシュ(docker または podman から) および Red Hat Quay UI を使用する 2 つの方法があります。これらは、Quay.io を使用するか、Red Hat Quay の独自のインスタンスを使用する場合でも基本的に同じです。

2.1. UI を使用したイメージリポジトリーの作成

Red Hat Quay UI で、ユーザーアカウントでリポジトリーを作成するには、以下を実行します。Web UI でユーザーアカウントにログインします。ホームページのヘッダー(またはユーザーに関連するその他のページ)の右上にある + アイコンをクリックし、以下の図に示すように「New Repository」を選択します。

+ Create a new repository for a user.

  1. 表示される「Create New Repository」ページ:

    • ユーザー名に新しいリポジトリー名を追加します。
    • 「Repository Description」をクリックし、リポジトリーの説明を入力します。
    • 「Repository Visibility」で、リポジトリーをパブリックまたはプライベートのどちらにするかを選択します。
    • 「Create Repository」ボタンをクリックします。

新規リポジトリーが作成され、空の状態で開始されます。このリポジトリーから (イメージ名を除く) イメージをプルするために使用できる docker pull コマンドが画面に表示されます。

Red Hat Quay UI で組織の下でリポジトリーを作成するには、以下を実行します。

  1. 組織への Admin または Write パーミッションを持つユーザーとしてログインします。
  2. 「Repositories」ビューで、「Users」および「Organizations」の右側の列から組織名を選択します。組織のページが表示されます。これは、図 2.x に示されているページと似ています。
  3. ページの右上にある「+Create New Repository」をクリックします。
  4. 表示される「Create New Repository」で、以下を実行します。

    • 新規のリポジトリー名を組織名に追加します。
    • 「Repository Description」をクリックし、リポジトリーの説明を入力します。
    • 「Repository Visibility」で、リポジトリーをパブリックまたはプライベートのどちらにするかを選択します。
    • 「Create Repository」ボタンをクリックします。

新規リポジトリーが作成され、空の状態で開始されます。このリポジトリーから (イメージ名を除く) イメージをプルするために使用できる docker pull コマンドが画面に表示されます。

2.2. docker または podman でのイメージリポジトリーの作成

適切な認証情報がある場合、イメージを Red Hat Quay インスタンスにまだ存在していないリポジトリーにプッシュすると、イメージをそのリポジトリーにプッシュする際にそのリポジトリーが作成されます。これらの例では、docker コマンドまたは podman コマンドのいずれかが機能します。

  1. イメージにタグ付けします。ローカルシステムの docker または podman で利用できるイメージの場合、新規リポジトリー名とイメージ名を使ってそのイメージにタグ付けします。以下は、イメージを Quay.io または独自の Red Hat Quay 設定にプッシュする例です(例: reg.example.com)。この例では、namespace を Red Hat Quay ユーザー名または組織に置き換え、repo_name を、作成するリポジトリーの名前に置き換えます。

    # sudo podman tag myubi-minimal quay.io/namespace/repo_name
    # sudo podman tag myubi-standard reg.example.com/namespace/repo_name
  2. 適切なレジストリーにプッシュします。以下に例を示します。

    # sudo podman push quay.io/namespace/repo_name
    # sudo podman push reg.example.com/namespace/repo_name
注記

アプリケーションリポジトリーを作成するには、コンテナーイメージリポジトリーの作成に使用した同じ手順に従います。

第3章 リポジトリーへのアクセスの管理

Red Hat Quay ユーザーとして、独自のリポジトリーを作成し、Red Hat Quay インスタンスの他のユーザーがこれにアクセスできるようにします。または、組織を作成して、チームベースでリポジトリーへのアクセスを許可することもできます。ユーザーリポジトリーと組織リポジトリーの両方で、ロボットアカウントに関連付けられた認証情報を作成してこれらのリポジトリーへのアクセスを許可できます。ロボットアカウントを使用すると、クライアントに Red Hat Quay ユーザーアカウントがなくても、各種のコンテナークライアント (docker または podman など) がリポジトリーに簡単にアクセスできます。

3.1. ユーザーリポジトリーへのアクセスの許可

ユーザーの namespace でリポジトリーを作成する場合は、そのリポジトリーへのアクセスをユーザーアカウントに追加したり、ロボットアカウントを使用して追加したりできます。

3.1.1. ユーザーリポジトリーへのユーザーアクセスの許可

ユーザーアカウントに関連付けられたリポジトリーへのアクセスを許可するには、以下を実行します。

  1. Red Hat Quay ユーザーアカウントにログインします。
  2. アクセスを共有するユーザー namespace でリポジトリーを選択します。
  3. 左側の列から「Settings」アイコンをクリックします。
  4. リポジトリーへのアクセスを付与するユーザーの名前を入力します。以下の図のように、ユーザーが入力するユーザー名が表示されます。

    Grant user access to a user repository

  5. パーミッションボックスで、以下のいずれかを選択します。

    • Read (読み取り): ユーザーはリポジトリーを表示し、そこからプルすることができます。
    • Write (書き込み): ユーザーはリポジトリーの表示や、リポジトリーから/へのイメージのプルまたはプッシュを行えます。
    • Admin (管理): リポジトリーに対するすべての管理設定と、読み取りおよび書き込みパーミッションをすべて許可します。
  6. 「Add Permission」ボタンを選択します。ユーザーにパーミッションが割り当てられます。

リポジトリーへのユーザーパーミッションを削除するには、ユーザーエントリーの右側にある「Options」アイコンを選択してから「Delete Permission」を選択します。

3.2. ユーザーリポジトリーへのロボットアクセスの許可

ロボットアカウントは、Red Hat Quay レジストリーのリポジトリーへの自動アクセスを設定するために使用されます。これらは OpenShift サービスアカウントと同様です。ロボットアカウントを設定する場合は、以下を実行します。

  • ロボットアカウントに関連付けられる認証情報を生成します。
  • リポジトリーおよびロボットがイメージをプッシュしたり、プルできるイメージを特定します。
  • 定義されたそれぞれのリポジトリーにアクセスするために、異なるコンテナークライアント(Docker、podman、Kubernetes、Mesos など) で使用するために生成される認証情報をコピーし、貼り付けます。

それぞれのロボットアカウントは、単一のユーザー namespace または組織に制限される点に留意してください。たとえば、ロボットアカウントはユーザー jsmith がアクセスできるすべてのリポジトリーへのアクセスを提供できますが、そのユーザーのリポジトリー一覧にないリポジトリーへのアクセスを提供することはできません。

以下では、リポジトリーへのアクセスを許可するロボットアカウントを設定する手順を説明します。

  1. 「Robot」アイコンを選択します。「Repositories」ビューの左側の列で「Robot」アイコンを選択します。
  2. ロボットアカウントを作成します。「Create Robot Account」ボタンを選択します。
  3. ロボット名を設定します。名前および説明を入力し、「Create robot account」ボタンを選択します。ロボット名はユーザー名と設定するロボット名の組み合わせになります (例: jsmith+myrobot)。
  4. パーミッションをロボットアカウントに追加します。ロボットアカウントの「Add permissions」画面で、以下のようにロボットがアクセスできるようにするリポジトリーを定義します。

    • ロボットがアクセスできる各リポジトリーの横にチェックマークを付けます。
    • 各リポジトリーについて、以下のいずれかを選択し、「Add permissions」をクリックします。

      • None: ロボットにはリポジトリーへのパーミッションがありません。
      • Read: ロボットはリポジトリーを表示し、これからプルできます。
      • Write: ロボットはリポジトリーから/への読み取り (pull) および書き込み (push) を実行できます。
      • Admin: リポジトリーから/への pull および push を実行するためのアクセスがあります。また、リポジトリーに関連付けられる管理タスクを実行することもできます。
    • 「Add permissions」ボタンを選択して設定を適用します。
  5. ロボット経由でリポジトリーにアクセスするための認証情報を取得します。「Robot Accounts」ページに戻り、ロボットアカウント名を選択してそのロボットアカウントの認証情報を表示します。
  6. トークンを取得します。以下の図に示されているように「Robot Token」を選択し、ロボット用に生成されたトークンを確認します。トークンをリセットする必要がある場合は、「Regenerate Token」を選択します。

    トークンを再生成すると、このロボット用の以前のトークンが無効になる点を理解しておく必要があります。

    Select Options drop-down to change user passwords

  7. 認証情報を取得します。生成されたトークンに問題がなければ、以下の方法で生成される認証情報を取得します。

    • Kubernetes Secret: これを選択し、Kubernetes プルシークレットの yaml ファイルの形式で認証情報をダウンロードします。
    • rkt Configuration: これを選択し、json ファイルの形式で rkt コンテナーランタイムの認証情報をダウンロードします。
    • Docker Login: これを選択し、認証情報が含まれる docker login コマンドラインすべてをコピーします。
    • Docker Configuration: これを選択し、Docker config.json ファイルとして使用するファイルをダウンロードし、認証情報をクライアントシステムに永続的に保存します。
    • Mesos Credentials: これを選択し、Mesos 設定ファイルの uris フィールドで特定できる認証情報を提供する tarball をダウンロードします。

3.3. 組織リポジトリーへのアクセスの許可

組織を作成した後に、リポジトリーのセットをその組織に直接関連付けることができます。その組織のリポジトリーへのアクセスを追加するには、Team (同じパーミッションを持つユーザーセット) と個々のユーザーを追加できます。基本的に、組織にはユーザーと同様のリポジトリーおよびロボットアカウントを作成する機能がありますが、組織はユーザーのグループを (チームまたは個別で)使用して共有リポジトリーを設定することを目的としています。

組織について知っておく必要のあるその他の点

  • 別の組織に組織を作成することはできません。組織を細分化するには、チームを使用します。
  • 組織には、ユーザーを直接含めることはできません。最初にチームを追加してから、各チームにユーザーを追加する必要があります。
  • チームは、リポジトリーおよび関連イメージを使用するメンバーや、組織を管理するための特別な権限を持つ管理者として組織内に設定できます。

3.3.1. チームの組織への追加

所属する組織のチームを作成する場合は、チーム名を選択し、チームが利用できるリポジトリーを選択し、チームのアクセスレベルを決定することができます。

  1. 「Organization」ビューの左側の列で「Teams」および「Membership」アイコンを選択します。組織を作成したユーザーの管理者権限を持つ所有者チームが存在することを確認できます。
  2. 「Create New Team」を選択します。組織に関連付ける新しいチーム名の入力を求めるプロンプトが出されます。チーム名を入力します。これは小文字で開始し、残りは小文字と数字の任意の組み合わせを使用する必要があります (大文字または特殊文字を使用することはできません)。
  3. 「Create team」ボタンを選択します。「Add permissions」ウィンドウが表示され、組織のリポジトリーの一覧が表示されます。
  4. チームがアクセスできる各リポジトリーを確認します。次に、それぞれについて以下の権限のいずれかを選択します。

    • Read: チームメンバーはイメージを表示し、プルできます。
    • Write: チームメンバーはイメージを表示、プルおよびプッシュを実行できます。
    • Admin: チームメンバーには完全な読み取り/書き込み権限があり、リポジトリーに関連する管理タスクを実行できます。
  5. 「Add permissions」を選択して、チームのリポジトリーパーミッションを保存します。

3.3.2. チームロールの設定

チームを追加したら、組織内にそのチームのロールを設定できます。組織内の「Teams and Membership」画面で、以下の図に示すように TEAM ROLE ドロップダウンメニューを選択します。

Set the role that a team has within an organization

選択したチームで、以下のロールのいずれかを選択します。

  • Member: チームに設定されるすべての権限を継承します。
  • Creator: すべてのメンバー権限、および新規リポジトリーを作成する機能があります。
  • Admin: チームの作成、メンバーの追加、パーミッションの設定機能など、組織への完全な管理アクセスがあります。

3.3.3. ユーザーのチームへの追加

組織に対する管理者権限があるユーザーとして、ユーザーおよびロボットをチームに追加できます。ユーザーを追加すると、そのユーザーにメールが送信されます。ユーザーは、招待状を受け取るまで保留状態になります。

ユーザーまたはロボットをチームに追加するには、組織の画面から開始し、以下を実行します。

  1. ユーザーまたはロボットを追加するチームを選択します。
  2. 「Team Members」ボックスに以下のいずれかを入力します。

    • Red Hat Quay レジストリーのアカウントからのユーザー名
    • レジストリーのユーザーアカウントのメールアドレス
    • ロボットアカウントの名前。この名前は orgname+robotname の形式で指定する必要があります。
  3. ロボットアカウントの場合には、すぐにチームに追加されます。ユーザーアカウントの場合、参加を促す招待メールがユーザーに送信されます。ユーザーがその招待を受け入れるまで、ユーザーは INVITED TO JOIN 状態になります。

次に、ユーザーはチームに参加するための招待メールを受け入れます。ユーザーの Red Hat Quay インスタンスへの次回のログイン時に、ユーザーは INVITED TO JOIN 一覧から組織の MEMBERS 一覧に移動します。

第4章 タグの使用

タグを使用すると、イメージのバージョンを特定し、同じイメージに異なる方法で名前を付けることができます。イメージのバージョンに加えて、イメージタグはその用途(devel、testing、prod など) や最新バージョン (latest) を特定することができます。

イメージリポジトリーの「Tags」タブで、タグ の履歴を表示、変更、追加、移動、削除、および表示できます。また、さまざまなコマンドを使用して、(名前とタグに基づいて) 特定のイメージをダウンロード (プル) するために使用できるコマンドラインをフェッチすることもできます。

4.1. タグの表示および変更

リポジトリーのタグは、「 Tags 」タブをクリックして、リポジトリーページのタグパネルで表示し、変更できます。 View and modify tags from your repository

4.1.1. 新規タグのタグ付けされたイメージへの追加

新しいタグは、タグの横にある歯車のアイコンをクリックし、「Add New Tag」を選択して、タグ付けされたイメージに追加できます。Red Hat Quay では、新規タグのイメージへの追加を確認します。

4.1.2. タグの移動

タグを別のイメージに移動するには、新規タグを追加するのと同じ操作を実行し、追加として既存のタグ名を指定します。Red Hat Quay は、タグを追加せずに移動することを確認します。

4.1.3. タグの削除

特定のタグとそのすべてのイメージは、タグの歯車アイコンをクリックし、「Delete Tag」を選択して削除できます。これにより、タグとそのタグに固有のイメージが削除されます。イメージは、親子関係から直接的または間接的にこれらを参照するタグがなくなるまで削除されません。

4.1.4. タグ履歴を表示し、過去に遡る

4.1.4.1. タグ履歴の表示

タグのイメージ履歴を表示するには、Actions メニューにある View Tags History メニュー項目をクリックします。上記のページには、タグが過去に参照したそれぞれのイメージと、タグが参照した時間が表示されます。

4.1.4.2. 過去に遡る

タグを以前のイメージに戻すには、必要なイメージが上書きされた履歴の行を見つけ、「Restore」リンクをクリックします。

4.1.5. タグまたはダイジェストでのイメージのフェッチ

Tags 」タブで、それらのイメージを使用できるクライアントからイメージをプルする複数の異なる方法を確認できます。

  1. 特定のリポジトリー/イメージを選択します。
  2. 左側の列で「Tags」を選択します。
  3. 特定のイメージ/タグの組み合わせについての「Fetch Tag」アイコンを選択します。
  4. 「Fetch Tag」ポップアップが表示されたら、「Image format」ボックスを選択し、イメージのプルに利用できるさまざまな方法を示すドロップダウンメニューを表示できます。選択内容には、特定のコンテナーイメージをローカルシステムにプルするための詳細なコマンドラインが含まれます。

Get commands for fetching images in different ways

docker コマンドを使用して、タグ名またはダイジェスト名でイメージの通常のプルを選択できます。必要なプルのタイプを選択し、Copy Command を選択します。詳細のコマンドラインがクリップボードにコピーされます。以下の 2 つのコマンドにより、タグおよびダイジェストでの docker プル が表示されます。

docker pull quay.io/cnegus/whatever:latest
docker pull quay.io/cnegus/whatever@sha256:e02231a6aa8ba7f5da3859a359f99d77e371cb47e643ce78e101958782581fb9

このコマンドを、docker コマンドおよび利用可能なサービスを持つシステムのコマンドラインシェルに貼り付け、Enter を押します。この時点で、コンテナーイメージはローカルシステムで実行できます。

RHEL および Fedora システムでは、選択されたイメージをプルし、実行するために、docker の代わりに podman を使用できます。

4.2. タグの有効期限

イメージは、tag expiration という機能を使用して、Red Hat Quay リポジトリーで選択される日時に期限切れになるように設定できます。以下は、タグの有効期限について知っておく必要のあるいくつかの点です。

  • タグの期限が切れると、タグはリポジトリーから削除されます。特定イメージの最後のタグの場合、イメージは削除するように設定されます。
  • 有効期限はタグごとに設定されますが、リポジトリー全体には設定されません。
  • タグの有効期限が切れるか、または削除される場合、これはレジストリーからすぐに削除されません。(「User」設定の)「Time Machine」の値は、削除されたタグが実際に削除され、ガベージコレクションの対象になるタイミングを定義します。デフォルトで、この値は 14 日です。その時点まで、タグを期限切れになったか、または削除されたイメージに再びポイントできます。
  • Red Hat Quay のスーパーユーザーには、ユーザーリポジトリーからの期限切れのイメージの削除に関連する特別な権限がありません。スーパーユーザーがユーザーリポジトリーについての情報を収集し、これに対してアクションを実行するための中心的なメカニズムはありません。イメージの有効期限や最終的にイメージを削除するかどうかについては、それぞれのリポジトリーの所有者が決定します。

タグの有効期限は、さまざまな方法で設定できます。

  • イメージの作成時に quay.expires-after= LABEL を Dockerfile に設定する。これにより、イメージがビルドされてから期限切れになる時間が設定されます。
  • リポジトリータグの EXPIRES 列から有効期限を選択し、期限切れになる特定の日時を選択する。

以下の図は、タグの有効期限を変更するための「Options」エントリーと、タグの有効期限についての「EXPIRES」フィールドを示しています。「EXPIRES」フィールドにカーソルを合わせ、現在設定されている有効期限の日時が表示されます。

Change tag expiration under the Options icon or from the EXPIRES column

4.2.1. Dockerfile でのタグの有効期限の設定

Dockerfile LABEL コマンドで quay.expires-after=20h などのラベルを追加すると、タグは指定された時間の後に自動的に期限切れになります。時間の値は、イメージのビルド時からそれぞれ時間、日数、週を表す 1h2d3w のように表されます。

4.2.2. リポジトリーからのタグ有効期限の設定

「Repository Tag」ページに、タグの有効期限を示す「EXPIRES」という UI の列があります。ユーザーは、有効期限が切れる時間をクリックするか、右側の「Settings」 ボタン (歯車アイコン) をクリックしてこれを設定でき、その後は「Change Expiration」を選択します。

プロンプトが出されたら日時を選択し、「Change Expiration」を選択します。タグは、有効期限に達するとリポジトリーから削除されるように設定されます。

4.3. セキュリティースキャン

タブの横にある脆弱性または修正可能なカウントをクリックすると、そのタグのセキュリティースキャン情報に移動できます。ここでは、イメージに影響する CVEと、選択可能な修復オプションを見つけることができます。

イメージのスキャンでは、Clair イメージスキャナーが検知する脆弱性のみが一覧表示される点に留意してください。発見された脆弱性についてアクションは、それぞれのユーザーが判断します。Red Hat Quay スーパーユーザーは、検知される脆弱性に対してアクションを実行しません。

第5章 ログの表示およびエクスポート

Red Hat Quay では、すべてのリポジトリーおよび namespace(ユーザーおよび組織)についてアクティビティーログが収集されます。ログファイルにアクセスする方法は複数あります。以下が含まれます。

  • Web UI でログを表示する。
  • ログを外部で保存できるようにエクスポートする。
  • API 経由でログエントリーにアクセスする。

ログにアクセスするには、選択したリポジトリーまたは namespace に対する Admin 権限が必要です。

注記

最大 100 のログ結果は API 経由で一度に取得できます。さらに多くの結果を収集するには、本章に記載するログエクスポーター機能を使用する必要があります。

5.1. ログの表示

Web UI からリポジトリーまたは namespace のログエントリーを表示するには、以下を実行します。

  1. Admin 権限を持つリポジトリーまたは namespace(組織またはユーザー)を選択します。
  2. 左側の列から「Usage Logs」アイコンを選択します。以下の図のような「Usage Logs」画面が表示されます。

    View usage logs

  3. 「Usage Logs」ページから、以下を実行できます。

    • 開始から終了 (From および To) までの日付を追加して、ログエントリーを表示する日付範囲を設定します。デフォルトでは、ログエントリーの直近 1 週間が表示されます。
    • 「Filter Logs」ボックスに文字列を入力し、指定の文字列を含むログエントリーを表示します。
    • 矢印をログエントリーの左側に切り替えて、そのログエントリーに関連するテキストを表示します。

5.2. リポジトリーログのエクスポート

多数のログファイルを取得し、それらを Red Hat Quay データベース外に保存できるようにするには、「Export Logs」機能を使用できます。以下は、「Export Logs」について知っておく必要があるいくつかの点になります。

  • リポジトリーから収集するログの日付範囲を選択できます。
  • ログをメールの添付ファイルとして送信するか、コールバック URL に送信するかについてリクエストできます。
  • ログをエクスポートするには、リポジトリーまたは namespace への Admin 権限が必要です。
  • 1 度に最大 30 日間のログデータをエクスポートできます
  • 「Export Logs」機能は、以前に生成されたログデータのみを収集します。ロギングデータのストリーミングは行われません。
  • Red Hat Quay インスタンスは、この機能の外部ストレージ用に設定される必要があります(ローカルストレージは機能しません)。
  • ログが収集され、利用可能になったら、保存する必要がある場合はそのデータをすぐにコピーする必要があります。デフォルトでは、データは 1 時間後に期限切れになります。

Export Logs 機能を使用するには、以下を実行します。

  1. Admin 権限のあるリポジトリーを選択します。
  2. 左側の列から「Usage Logs」アイコンを選択します。「Usage Logs」画面が表示されます。
  3. 収集するログエントリーの起点 (From) および日付の範囲を選択します。
  4. 「Export Logs」ボタンを選択します。以下に示すように、「Export Usage Logs」ポップアップが表示されます。

    Enter email or callback URL to receive exported logs

  5. エクスポートされたログの受信に使用するメールアドレスまたはコールバック URL を入力します。コールバック URL には、webhook.site などの場所への URL を使用できます。
  6. 「Start Logs Export」を選択します。これにより、Red Hat Quay が選択したログエントリーの収集を開始します。収集されるロギングデータの量によっては、完了までに 1 分から 1 時間の時間がかかる場合があります。
  7. ログのエクスポートが完了したら、以下のいずれかを行います。

    • 要求したエクスポートされたログエントリーの利用可能性について警告するメールを受信します。
    • Webhook URL からのログエクスポート要求の正常なステータスが表示されます。エクスポートされたデータへのリンクを選択して、ログをダウンロードできます。

URL は Red Hat Quay 外部ストレージ内の場所をポイントし、1 時間以内に期限切れになるように設定される点に留意してください。したがって、保持する必要がある場合は、エクスポートされたログを有効期限になる前にコピーしてください。

第6章 ビルドワーカーを使用した Dockerfile の自動ビルド

Red Hat Quay は、OpenShift または Kubernetes でワーカーノードのセットを使用した Dockerfile のビルドをサポートします。GitHub Webhook などのビルドトリガーは、新規コードがコミットされる際にリポジトリーの新規バージョンを自動的にビルドするように設定できます。本書では、Red Hat Quay インストールでビルドを有効にし、1 つ以上の OpenShift/K8s クラスターを設定して Red Hat Quay からのビルドを受け入れる方法について説明します。Red Hat Quay 3.4 では、基礎となる Build Manager が Python 2 から Python 3 への移行の一環として完全に再作成されました。その結果、ビルダーイメージは、Red Hat Quay 3.3 以前のバージョンで継続的に実行された Kubernetes ジョブに対し、ベアメタルノードとして動的に作成されるようになりました。これにより、Red Hat Quay によるビルドの管理方法が大幅に単純化化され、同じメカニズムの quay.io を使用して数千ものコンテナーイメージビルドを日次で処理できるようになりました。現時点で静的 (Red Hat Quay 3.3 の「Enterprise」ビルダー) を実行しているお客様は、Kubernetes ベースのビルドメカニズムに移行する必要があります。

6.1. アーキテクチャーの概要

Red Hat Quay ビルドシステムはスケーラビリティーを確保できるように設計されています(これは quay.io ですべてのビルドをホストするために使用されます)。Red Hat Quay の Build Manager コンポーネントは、ビルド要求を追跡し、Build Executor(OpenShift/K8s クラスター)が各要求を実行できるようにするオーケストレーション層を提供します。各ビルドは、イメージのビルドプロセスを完全に分離し、そのプロセスを組み込むために小規模な仮想マシンを起動する Kubernetes ジョブによって処理されます。これにより、コンテナービルドが相互に影響を与えたり、基礎となるビルドシステムに影響を与えたりしなくなります。インフラストラクチャーに障害が発生した場合でもビルドを実行できるように、複数の Executor を設定できます。Red Hat Quay は、1 つの Executor に問題があることを検知すると、ビルドを別の Executor に自動的に送信します。

注記

Red Hat Quay のアップストリームバージョンは、AWS/EC2 ベースの Executor の設定方法を提供します。この設定は、Red Hat Quay のお客様向けにはサポートされていません。

6.1.1. ビルドマネージャー

ビルドマネージャーは、スケジュールされたビルドのライフサイクルに対応します。ビルドキュー、ビルドフェーズの更新、およびジョブのステータスの実行を必要とする操作は、ビルドマネージャーによって処理されます。

6.1.2. ビルドワーカーのコントロールプレーン

ビルドジョブは個別のワーカーノードで実行され、別のコントロールプレーン (Executor) でスケジュールされます。現時点で、Red Hat Quay は AWS および Kubernetes でのジョブの実行をサポートしています。ビルドは quay.io/quay/quay-builder を使用して実行されます。AWS では、ビルドは EC2 インスタンスにスケジュールされます。k8s では、ビルドはジョブリソースとしてスケジュールされます。

6.1.3. オーケストレーター

オーケストレーターは、現在実行中のビルドジョブの状態を保存し、ビルドマネージャーが消費するイベントを公開します (例: 期限満了のイベント)。現時点で、サポートされているオーケストレーターのバックエンドは Redis です。

6.2. OpenShift の要件

Red Hat Quay ビルドは Kubernetes および OpenShift 4.5 以降でサポートされます。ビルド Pod には kvm 仮想化を実行する機能が必要になるため、ベアメタル (仮想化以外) のワーカーノードが必要です。各ビルドは一時的な仮想マシンで実行され、ビルドの実行中に完全に分離され、セキュリティーが確保されるようにします。さらに、OpenShift クラスターでは、Red Hat Quay ビルドに関連付けられた ServiceAccount が特権付きコンテナーをサポートするのに必要な SecurityContextConstraint で実行されることが許可される必要があります。

6.3. オーケストレーターの要件

Red Hat Quay ビルドでは、ビルドのステータス情報を追跡するために Redis インスタンスへのアクセスが必要です。Red Hat Quay インストールですでにデプロイされている同じ Redis インスタンスを使用することができます。すべてのビルドキューは Red Hat Quay データベースで管理されるため、可用性の高い Redis インスタンスは必要ありません。

6.4. OpenShift を使用した Red Hat Quay Builder の設定

6.4.1. Red Hat Quay ビルド向けの OpenShift の準備

Red Hat Quay からのビルドを許可する前に、OpenShift クラスターで必要となるいくつかのアクションがあります。

  1. ビルドが実行されるプロジェクトを作成します (例:「builder」)。

    $ oc new-project builder
  2. ビルドの実行に使用されるこの ProjectServiceAccount を作成します。これに Jobs および Pods を作成するのに十分な権限があることを確認します。後で使用できるように ServiceAccount のトークンをコピーします。

    $ oc create sa -n builder quay-builder
    $ oc policy add-role-to-user -n builder edit system:serviceaccount:builder:quay-builder
    $ oc sa get-token -n builder quay-builder
  3. OpenShift クラスターの API サーバーの URL を特定します。これは OpenShift コンソールで確認できます。
  4. ビルド Jobs のスケジュール時に使用されるワーカーノードラベルを特定します。ビルド Pod はベアメタルワーカーノードで実行される必要があるため、通常はそれらが特定のラベルで識別されます。クラスター管理者と、どのノードラベルを使用する必要があるかを確認します。
  5. クラスターが自己署名証明書を使用している場合、Red Hat Quay の追加証明書に追加する kube apiserver の CA を取得します。

    1. CA を含むシークレットの名前を取得します。

      $ oc get sa openshift-apiserver-sa --namespace=openshift-apiserver -o json | jq '.secrets[] | select(.name | contains("openshift-apiserver-sa-token"))'.name
    2. Openshift コンソールのシークレットから ca.crt キー値を取得します。値は「-----BEGIN CERTIFICATE-----」で開始されるはずです。
    3. ConfigTool を使用した Red Hat Quay での CA のインポートこのファイルの名前が K8S_API_TLS_CA と一致することを確認します。
  6. ServiceAccount に必要なセキュリティーコンテキスト/ロールバインディングを作成します。
apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: quay-builder
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities: null
runAsUser:
  type: RunAsAny
seLinuxContext:
  type: RunAsAny
seccompProfiles:
- '*'
supplementalGroups:
  type: RunAsAny
volumes:
- '*'
allowHostDirVolumePlugin: true
allowHostIPC: true
allowHostNetwork: true
allowHostPID: true
allowHostPorts: true
allowPrivilegeEscalation: true
allowPrivilegedContainer: true
allowedCapabilities:
- '*'
allowedUnsafeSysctls:
- '*'
defaultAddCapabilities: null
fsGroup:
  type: RunAsAny
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: quay-builder-scc
  namespace: builder
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - quay-builder
  resources:
  - securitycontextconstraints
  verbs:
  - use
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: quay-builder-scc
  namespace: builder
subjects:
- kind: ServiceAccount
  name: quay-builder
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: quay-builder-scc

6.4.2. ビルダーを有効にし、ビルド設定を Red Hat Quay の設定バンドルに追加します。

  1. Red Hat Quay 設定でビルドが有効にされていることを確認します。
FEATURE_BUILD_SUPPORT: True
  1. 以下を Red Hat Quay 設定バンドルに追加し、それぞれの値をご使用のインストールに固有の値に置き換えます。
注記

現時点で、ビルド機能自体は Red Hat Quay Config Tool で有効にできます。Build Manager および Executor の実際の設定は、config.yaml ファイルで手動で行う必要があります。

BUILD_MANAGER:
- ephemeral
- ALLOWED_WORKER_COUNT: 1
  ORCHESTRATOR_PREFIX: buildman/production/
  ORCHESTRATOR:
    REDIS_HOST: quay-redis-host
    REDIS_PASSWORD: quay-redis-password
    REDIS_SSL: true
    REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
  EXECUTORS:
  - EXECUTOR: kubernetes
    BUILDER_NAMESPACE: builder
    K8S_API_SERVER: api.openshift.somehost.org:6443
    K8S_API_TLS_CA: /conf/stack/extra_ca_cert_build_cluster.crt
    VOLUME_SIZE: 8G
    KUBERNETES_DISTRIBUTION: openshift
    CONTAINER_MEMORY_LIMITS: 5120Mi
    CONTAINER_CPU_LIMITS: 1000m
    CONTAINER_MEMORY_REQUEST: 3968Mi
    CONTAINER_CPU_REQUEST: 500m
    NODE_SELECTOR_LABEL_KEY: beta.kubernetes.io/instance-type
    NODE_SELECTOR_LABEL_VALUE: n1-standard-4
    CONTAINER_RUNTIME: podman
    SERVICE_ACCOUNT_NAME: *****
    SERVICE_ACCOUNT_TOKEN: *****
    QUAY_USERNAME: quay-username
    QUAY_PASSWORD: quay-password
    WORKER_IMAGE: <registry>/quay-quay-builder
    WORKER_TAG: some_tag
    BUILDER_VM_CONTAINER_IMAGE: <registry>/quay-quay-builder-qemu-rhcos:v3.4.0
    SETUP_TIME: 180
    MINIMUM_RETRY_THRESHOLD: 0
    SSH_AUTHORIZED_KEYS:
    - ssh-rsa 12345 someuser@email.com
    - ssh-rsa 67890 someuser2@email.com

それぞれの設定フィールドについては、以下で説明します。

ALLOWED_WORKER_COUNT
Red Hat Quay Pod ごとにインスタンス化されるビルドワーカーの数を定義します。通常、これは「1」です。
ORCHESTRATOR_PREFIX
すべての Redis キーに追加する一意のプレフィックスを定義します(他の Redis キーから Orchestrator 値を分離するのに便利です)。
REDIS_HOST
Redis サービスのホスト名。
REDIS_PASSWORD
Redis サービスに対して認証を行うためのパスワード。
REDIS_SSL
Redis 接続が SSL を使用するかどうかを定義します。
REDIS_SKIP_KEYSPACE_EVENT_SETUP
デフォルトで、Red Hat Quay は実行時にキーのイベントに必要なキースペースイベントを設定しません。これを実行するには、REDIS_SKIP_KEYSPACE_EVENT_SETUP を false に設定します。
EXECUTOR
このタイプの Executor の定義を開始します。有効な値は 'kubernetes' および 'ec2' です。
BUILDER_NAMESPACE
Red Hat Quay ビルドが実行される Kubernetes namespace
K8S_API_SERVER
ビルドが実行される OpenShift クラスターの API サーバーのホスト名
K8S_API_TLS_CA
API 呼び出しの実行時に Quay アプリケーションが信頼するビルドクラスターの CA 証明書の Quay コンテナーのファイルパス。
KUBERNETES_DISTRIBUTION
使用されている Kubernetes のタイプを示します。有効な値は 'openshift' および 'k8s' です。
CONTAINER_*
各ビルド Pod のリソース要求および制限を定義します。
NODE_SELECTOR_*
ビルド Pod がスケジュールされるノードセレクターのラベルの名前/値のペアを定義します。
CONTAINER_RUNTIME
ビルダーが docker または podman を実行するかどうかを指定します。Red Hat の quay-builder イメージを使用しているお客様は、これを podman に設定する必要があります。
SERVICE_ACCOUNT_NAME/SERVICE_ACCOUNT_TOKEN
ビルド Pod によって使用されるサービスアカウントの名前/トークンを定義します。
QUAY_USERNAME/QUAY_PASSWORD
WORKER_IMAGE フィールドに指定される Red Hat Quay ビルドワーカーイメージをプルするために必要なレジストリーの認証情報を定義します。お客様は、記事 (https://access.redhat.com/RegistryAuthentication) の「Creating Registry Service Accounts」のセクションで定義されているように、registry.redhat.io に対して Red Hat Service Account 認証情報を指定する必要があります。
WORKER_IMAGE
Red Hat Quay ビルダーイメージのイメージ参照: registry.redhat.io/quay/quay-builder
WORKER_TAG
必要なビルダーイメージのタグ。最新バージョンは v3.4.0 です。
BUILDER_VM_CONTAINER_IMAGE
各 Red Hat Quay ビルドの実行に必要な内部仮想マシンを保持するコンテナーイメージの完全な参照 (registry.redhat.io/quay/quay-builder-qemu-rhcos:v3.4.0)。
SETUP_TIME
ビルドマネージャーでまだ登録されていない場合に、ビルドのタイムアウトの秒数を指定します (デフォルトは 500 秒)。タイムアウトしたビルドについては、再起動が 3 回試行されます。3 回の試行後にビルドがそれ自体を登録しない場合は失敗したとみなされます。
MINIMUM_RETRY_THRESHOLD
この設定は、複数の Executor で使用されます。これは、別の Executor を選択する前にビルドの開始の再試行回数を示します。0 に設定すると、ビルドジョブの試行回数に制限がないことになります。インフラストラクチャーに障害が発生した場合にフェイルオーバーがすぐに実行されるように、この値を意図的に小さく (3 以下) する必要があります。たとえば、Kubernetes は最初の Executor として設定され、EC2 は 2 番目の Executor として設定されます。最後の試行を Kubernetes ではなく EC2 で常に実行されるようにする必要がある場合、 Kubernetes Executor の MINIMUM_RETRY_THRESHOLD を 1 に、 EC2 の MINIMUM_RETRY_THRESHOLD を 0 (設定されていない場合、デフォルトは 0 になります) に設定します。この場合、kubernetes の MINIMUM_RETRY_THRESHOLD > retries_remaining(1) が False に評価されるため、設定された 2 つ目の Executor にフォールバックします。
SSH_AUTHORIZED_KEYS
Ignition 設定でブートストラップする ssh キーの一覧。これにより、EC2 インスタンスまたは QEMU 仮想マシンに ssh を実行するために他のキーを使用できるようになります。

6.5. OpenShift Route の制限

注記

このセクションは、OpenShift の Quay Operator を管理対象の route コンポーネントと共に使用している場合にのみ適用されます。

OpenShift Routes の制限により、トラフィックを単一ポートしか送信できないため、ビルドのセットアップには追加の手順が必要になります。kubectl または oc CLI ツールが Quay Operator がインストールされているクラスターと共に機能するように設定され、QuayRegistry が存在することを確認します (ビルダーが実行されるベアメタルクラスターと同じであるとは限りません)。

  • 以下の手順に従い、HTTP/2 ingress が OpenShift で有効にされていることを確認します。
  • Quay Operator は、既存の Quay Pod 内で実行されるビルドマネージャーサーバーに gRPC トラフィックを転送する Route を作成します。カスタムのホスト名 (例: builder.registry.example.com などのサブドメイン)を使用する場合は、作成された Routestatus.ingress[0].host を参照する DNS プロバイダーを使用して CNAME レコードを作成します。

    $ kubectl get -n <namespace> route <quayregistry-name>-quay-builder -o jsonpath={.status.ingress[0].host}
  • OpenShift UI または CLI を使用して、QuayRegistryspec.configBundleSecret によって参照される Secret をビルドクラスター CA 証明書 (キー名に extra_ca_cert_build_cluster.cert を指定する) で更新し、config.yaml エントリーを、BUILDMAN_HOSTNAME フィールドと共に上記のビルダー設定 (使用する実行プログラムによって異なる) で参照される適切な値で更新します。

    BUILD_MANAGER:
    - ephemeral
    - ALLOWED_WORKER_COUNT: 1
      ORCHESTRATOR_PREFIX: buildman/production/
      ORCHESTRATOR:
        REDIS_HOST: quay-redis-host
        REDIS_PASSWORD: quay-redis-password
        REDIS_SSL: true
        REDIS_SKIP_KEYSPACE_EVENT_SETUP: false
      EXECUTORS:
      - EXECUTOR: kubernetes
        BUILDER_NAMESPACE: builder
        BUILDMAN_HOSTNAME: <build-manager-hostname>
        ...

追加の設定フィールドについては、以下で説明します。

BUILDMAN_HOSTNAME
ビルドジョブがビルドマネージャーとの通信に使用する外部アクセス可能なサーバーのホスト名。デフォルトは SERVER_HOSTNAME と同じです。OpenShift Route の場合、カスタムホスト名を使用する場合は status.ingress[0].host または CNAME エントリーのいずれかになります。BUILDMAN_HOSTNAME には、Openshift Route のポート番号 (例: somehost:443) を含める必要 があります。これが省略される場合、ビルドマネージャーとの通信に使用される gRPC クライアントはポートについて推測しないためです。

6.6. ビルドのトラブルシューティング

ビルドマネージャーによって起動するビルダーインスタンスは一時的なインスタンスです。つまり、これらはタイムアウト/障害発生時に Red Hat Quay によってシャットダウンされるか、またはコントロールプレーン (EC2/K8s) によってガべージコレクションが実行されることを意味します。つまり、ビルダーログを取得するには、ビルドが実行されている にこれを実行する必要があります。

6.6.1. DEBUG 設定フラグ

ビルダーインスタンスが完了/障害の発生後にクリーンアップされないように、DEBUG フラグを設定できます。これを実行するには、必要な Executor 設定で DEBUG を true に設定します。以下は例になります。

  EXECUTORS:
    - EXECUTOR: ec2
      DEBUG: true
      ...
    - EXECUTOR: kubernetes
      DEBUG: true
      ...

true に設定すると、DEBUG は quay-builder サービスの実行または失敗後にビルドノードのシャットダウンを防ぎます。これにより、ビルドマネージャーがインスタンスをクリーンアップできなくなります(EC2 インスタンスを終了するか、または k8s ジョブを削除します)。これにより、ビルダーノードの問題のデバッグが可能になります。これは、実稼働環境で設定 すべきではありません。ライフタイムサービスは引き続き存在します。つまり、約 2 時間後にインスタンスをシャットダウンします(EC2 インスタンスが終了し、k8s ジョブの完了します) DEBUG を設定すると、未終了のインスタンス/ジョブも実行中のワーカーの合計数にカウントされるため、ALLOWED_WORKER_COUNT に影響を与えます。これは、ALLOWED_WORKER_COUNT に達して新規ビルドをスケジュールできるようになる場合、既存のビルダーワーカーを手動で削除する必要があることを意味します。

以下の手順を使用します。

  1. ゲスト仮想マシンは、SSH ポート (22) をホストの (Pod) ポート 2222 に転送します。ポートはビルダー Pod のポート 2222 を localhost のポートに転送します。例:

    $ kubectl port-forward <builder pod> 9999:2222
  2. SSH_AUTHORIZED_KEYS のキーセットを使用してコンテナー内で実行中の仮想マシンに SSH を実行します。

    $ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost
  3. quay-builder サービスログを取得します。

    $ systemctl status quay-builder
    $ journalctl -f -u quay-builder
    • ステップ 2-3 は、単一の SSH コマンドで実行することもできます。

      $ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost ‘systemctl status quay-builder’
      $ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost ‘journalctl -f -u quay-builder’

6.7. GitHub ビルドの設定 (オプション)

GitHub (または GitHub Enterprise) へのプッシュでビルドを実行する予定がある場合は、GitHub での OAuth アプリケーションの作成 に進みます。

第7章 Dockerfile のビルド

Red Hat Quay は、ビルドフリートで Dockerfile をビルドし、生成されるイメージをリポジトリーにプッシュする機能をサポートします。

7.1. ビルドの表示および管理

リポジトリービルドを表示し、管理するには、「Repository View」の「Builds」タブをクリックします。

7.2. ビルドの手動での開始

リポジトリービルドを手動で開始するには、リポジトリーページのヘッダーの右上にある + アイコンをクリックし、「New Dockerfile Build」を選択します。アップロードされたDockerfile.tar.gz、または HTTP URL をビルドに使用できます。

注記

手動でビルドを開始する場合、Docker ビルドコンテキストを指定することはできません。

7.3. ビルドトリガー

リポジトリービルドは、SCM(GitHub、BitBucket、または GitLab)へのプッシュなどのイベントや Webhook への呼び出し によって自動的にトリガーされます。

7.3.1. 新規ビルドトリガーの作成

ビルドトリガーを設定するには、「Builds view」ページの「 Create Build Trigger」ボタンをクリックし、ダイアログの指示に従います。トリガーを設定するには Red Hat Quay アクセスをリポジトリーに付与する必要があり、アカウントには SCM リポジトリーでの管理アクセスが必要です

7.3.2. ビルドトリガーの手動トリガー

ビルドトリガーを手動でトリガーするには、ビルドトリガーの横にあるアイコンをクリックして「Run Now」を選択します。

7.3.3. ビルドコンテキスト

Docker を使用してイメージをビルドする場合、ディレクトリーはビルドコンテキストになるように指定されます。これは手動ビルドとビルドトリガーの両方に当てはまります。Red Hat Quayによって実行されるビルドは、独自のマシンで docker build を実行する場合と同じであるためです。

Red Hat Quay のビルドコンテキストは、常にビルドセットアップから指定される サブディレクトリー であり、指定がない場合は、ビルドソースのルートにフォールバックします。ビルドがトリガーされると、Red Hat Quay ビルドワーカーは git リポジトリーをワーカーマシンにクローンし、ビルドコンテキストを入力してビルドを実行します。

tar アーカイブをベースとするビルドの場合、ビルドワーカーはアーカイブを展開し、ビルドコンテキストを入力します。以下に例を示します。

example
├── .git
├── Dockerfile
├── file
└── subdir
    └── Dockerfile

上記の例は「example」という GitHub リポジトリーのディレクトリー構造を示しています。ビルドトリガーの設定にサブディレクトリーが指定されていない場合や、ビルドを手動で開始している場合に、ビルドは example ディレクトリーで動作します。

ビルドトリガーセットアップで subdir がサブディレクトリーになるように指定されている場合、その中の Dockerfile のみがビルドに表示されます。これは、ビルドコンテキスト外にあるために Dockerfile で ADD コマンドを使用して file を追加できないことを意味します。

Docker Hub とは異なり、Dockerfile は Red Hat Quay のビルドコンテキストの一部です。そのため、これは .dockerignore ファイルには表示されません。

第8章 カスタム Git トリガーの設定

カスタム Git トリガーは、ビルドトリガーとして機能する git サーバーの汎用的な方法です。これは SSH キーと Webhook エンドポイントのみに依存しますが、その他はユーザーによって実装されます。

8.1. トリガーの作成

カスタム Git トリガーの作成は、いくつかのわずかな違いはありますが、他のトリガーの作成と同様です。

  • Red Hat Quay は、トリガーで使用する適切なロボットアカウントを自動的に検出することができません。これは作成プロセスで手動で行う必要があります。
  • トリガーを使用するためには、トリガーの作成後に追加の手順を実行する必要があります。これらの手順を以下に示します。

8.2. トリガー作成後の設定

トリガーが作成されたら、トリガーを使用する前に 2 つの追加手順が必要 になります。

  • トリガーの作成時に生成される SSH 公開鍵 への読み取りアクセスを提供します。
  • Red Hat Quay エンドポイントに POST する webhook をセットアップして、ビルドをトリガーします。

キーと URL は、どちらもトリガーの一覧にある歯車で「View Credentials」を選択して常に利用できます。 View and modify tags from your repository

8.2.1. SSH 公開鍵のアクセス

Git サーバーの設定に応じて、Red Hat Quay がカスタム git トリガー用に生成する SSH 公開鍵をインストールする各種の方法を使用できます。たとえば、Git ドキュメント では、鍵を $HOME/.ssh/authorize_keys に追加するだけでリポジトリーをクローンするためのビルダーのアクセスが提供される小規模なサーバー設定が説明されています。公式にサポートされない git リポジトリー管理ソフトウェアについては、通常 Deploy Keys というラベルが付けられるキーを入力する場所があります。

8.2.2. Webhook

ビルドを自動的にトリガーするには、以下の形式で JSON ペイロードを Webhook URL に POST する必要があります。

{
  "commit": "1c002dd",                                   // required
  "ref": "refs/heads/master",                            // required
  "default_branch": "master",                            // required
  "commit_info": {                                       // optional
    "url": "gitsoftware.com/repository/commits/1234567", // required
    "message": "initial commit",                         // required
    "date": "timestamp",                                 // required
    "author": {                                          // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    },
    "committer": {                                       // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    }
  }
}
注記

この要求を有効にするには、application/json を含む Content-Type ヘッダーが必要です。

これはサーバーの設定によって各種の方法で実行できますが、ほとんどの場合は post-receive git フックを使用して実行できます。

第9章 ソースコントロールでトリガーされるビルドの省略

コミットが Red Hat Quay build システムで無視されるように指定するには、テキストの [skip build] または [build skip] をコミットメッセージの任意の場所に追加します。

第10章 GitHub ビルドトリガータグの設定

Red Hat Quay は、GitHub または GitHub Enterprise をイメージのビルドのトリガーとして使用することをサポートします。これを実行していない場合は、Red Hat Quay でビルドサポートを有効にしてください

10.1. ビルドトリガーのタグの名前付けについて

Red Hat Quay 3.3 より前のリリースでは、ビルドトリガーで作成されるイメージの命名方法は制限されていました。ビルドトリガーでビルドされたイメージには以下を使用して名前が付けられまう。

  • 変更でトリガーを起動したブランチまたはタグを使用する
  • デフォルトのブランチを使用するイメージに latest タグを使用する

Red Hat Quay 3.3 以降では、イメージタグの設定方法がより柔軟になりました。最初にカスタムタグを入力し、それぞれのビルドされるイメージのタグとして任意の文字の文字列を割り当てることができます。ただし、代わりに、以下のタグテンプレートを使用して、各コミットの情報でイメージをタグ付けすることもでき

  • ${commit_info.short_sha}: コミットの短い SHA
  • ${commit_info.date}: コミットのタイムスタンプ
  • ${commit_info.author}: コミットの作成者
  • ${commit_info.committer}: コミットの作成者
  • ${parsed_ref.branch}: ブランチ名

以下の手順では、ビルドトリガーにタグ付けを設定する方法を説明します。

10.2. ビルドトリガーのタグ名の設定

以下の手順に従って、ビルドトリガーのカスタムタグを設定します。

  1. リポジトリービューで、左側のナビゲーションから「Builds」アイコンを選択します。
  2. 「Create Build Trigger」メニューを選択し、必要なリポジトリープッシュのタイプ (GitHub、Bitbucket、GitLab、またはカスタム Git リポジトリーのプッシュ) を選択します。この例では、以下の図で説明されているように GitHub リポジトリーのプッシュ が選択されています。

    Choose the type of build trigger to use

  3. Setup Build Trigger」ページが表示されたら、トリガーを設定するリポジトリーおよび namespace を選択します。
  4. 「Configure Trigger」で、「Trigger for all branches and tags」または「 Trigger only on branches and tags matching a regular expression」のいずれかを選択します。次に、「Continue」を選択します。以下の図のように、「Configure Tagging」セクションが表示されます。

    Set tagging with your own tags or using tag templates

  5. Configure Tagging」までスクロールダウンし、以下のオプションから選択します。

    • Tag manifest with the branch or tag name: このボックスにチェックを付け、コミットが発生したブランチまたはタグの名前を、イメージで使用されるタグとして使用します。これは、デフォルトで有効にされています。
    • Add latest tag if on default branch: リポジトリーのデフォルトブランチを使用している場合に、このボックスにチェックを付け、イメージに latest タグを使用します。これは、デフォルトで有効にされています。
    • Add custom tagging templates: カスタムタグまたはテンプレートを「Enter a tag template」ボックスに入力します。本セクションで説明されているように、ここに複数のタグテンプレートを入力できます。これには、短いSHA、タイムスタンプ、作成者の名前、コミッター、およびコミットからのブランチ名をタグとして使用する方法が含まれます。
  6. 「Continue」を選択します。Docker ビルドのディレクトリービルドコンテキストを選択することを求めるプロンプトが出されます。ビルドコンテキストディレクトリーは、ビルドのトリガー時に必要な他のファイルと共に Dockerfile を含むディレクトリーの場所を特定します。Dockerfile が git リポジトリーのルートにある場合は「/」を入力します。
  7. 「Continue」を選択します。オプションのロボットアカウントの追加を求めるプロンプトが出されます。ビルドプロセスでプライベートベースイメージをプルする場合に、これを行います。ロボットアカウントには、ビルドへのアクセスが必要です。
  8. 「Continue」を選択して、ビルドトリガーの設定を完了します。

リポジトリーの「Repository Builds」ページに戻る場合、設定したビルドトリガーは「Build Triggers」ヘッダーの下に一覧表示されます。

See the tagging options you set from the repository view

第11章 GitHub での OAuth アプリケーションの作成

レジストリーを GitHub OAuth アプリケーションとして登録し、GitHub アカウントおよびそのリポジトリーにアクセスできるようにレジストリーを承認できます。

11.1. 新規 GitHub アプリケーションの作成

  1. GitHub (Enterprise) にログインします。
  2. ご自分の組織設定で「Applications」ページにアクセスします。
  3. Register New Application」をクリックします。「 Register a new OAuth application 」設定画面が表示されます。 Register a new OAuth application
  4. ホームページ URL を設定します。「Quay Enterprise URL」を Homepage URL として入力します。

    注記

    パブリック GitHub を使用している場合は、ユーザーが入力されるホームページ URL にアクセスできる必要があります。これは依然として内部 URL の場合もあります。

  5. 認可コールバック URL を設定します。https://{$RED_HAT_QUAY_URL}/oauth2/github/callback を認可コールバック URL として入力します。
  6. 「Register application」ボタンをクリックして設定を保存します。新規アプリケーションの概要が表示されます。
  7. 新しいアプリケーションについて表示されるクライアント ID およびクライアントシークレットを記録します。

第12章 リポジトリー通知

Quay は、リポジトリーのライフサイクルで発生するさまざまイベントについての 通知 のリポジトリー追加をサポートします。通知を追加するには、リポジトリーの表示時に 「Settings 」タブをクリックし、Create Notification を選択します。「When this event occurs」フィールドから、通知を受信する必要のある項目を選択します。

Create repository notifications

イベントを選択してから、そのイベントの通知方法を追加して追加の設定を行います。

注記

通知を追加するには、リポジトリーの管理者権限 が必要です。

以下は、リポジトリーイベントの例になります。

12.1. リポジトリーイベント

12.1.1. リポジトリーのプッシュ

1 つ以上のイメージがリポジトリーに正常にプッシュされる。

{
  "name": "repository",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "homepage": "https://quay.io/repository/dgangaia/repository",
  "updated_tags": [
    "latest"
  ]
}

12.1.2. Dockerfile ビルドのキュー

以下は、ビルドシステムのキューに入れられた Dockerfile ビルドの応答例です。応答は、オプション属性の使用によって異なる場合があります。

{
  "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "repo": "test",
  "trigger_metadata": {
    "default_branch": "master",
    "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735",
    "ref": "refs/heads/master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                             //Optional
      "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735",
      "date": "2019-03-06T12:48:24+11:00",
      "message": "adding 5",
      "author": {                                                                //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                    //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"    //Optional
      },
      "committer": {
        "username": "web-flow",
        "url": "https://github.com/web-flow",
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"
      }
    }
  },
  "is_manual": false,
  "manual_user": null,
  "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2"
}

12.1.3. Dockerfile ビルドの開始

ビルドシステムで開始される Dockerfile ビルドの例を以下に示します。応答は、任意の属性によって異なる場合があります。

{
  "build_id": "a8cc247a-a662-4fee-8dcb-7d7e822b71ba",
  "trigger_kind": "github",                                                     //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                         //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "50bc599",
  "trigger_metadata": {                                                         //Optional
    "commit": "50bc5996d4587fd4b2d8edc4af652d4cec293c42",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                            //Optional
      "url": "https://github.com/dgangaia/test/commit/50bc5996d4587fd4b2d8edc4af652d4cec293c42",
      "date": "2019-03-06T14:10:14+11:00",
      "message": "test build",
      "committer": {                                                            //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                   //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"   //Optional
      },
      "author": {                                                               //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                   //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"   //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/a8cc247a-a662-4fee-8dcb-7d7e822b71ba"
}

12.1.4. Dockerfile ビルドの正常な完了

ビルドシステムで正常に完了した Dockerfile ビルドの応答例を以下に示します。

注記

このイベントは、ビルドされたイメージの Repository Push イベントと 同時 に生じます。

{
  "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "b7f7d2b",
  "image_id": "sha256:0339f178f26ae24930e9ad32751d6839015109eabdf1c25b3b0f2abf8934f6cb",
  "trigger_metadata": {
    "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                              //Optional
      "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735",
      "date": "2019-03-06T12:48:24+11:00",
      "message": "adding 5",
      "committer": {                                                              //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                     //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"                                                        //Optional
      },
      "author": {                                                                 //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                     //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"     //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2",
  "manifest_digests": [
    "quay.io/dgangaia/test@sha256:2a7af5265344cc3704d5d47c4604b1efcbd227a7a6a6ff73d6e4e08a27fd7d99",
    "quay.io/dgangaia/test@sha256:569e7db1a867069835e8e97d50c96eccafde65f08ea3e0d5debaf16e2545d9d1"
  ]
}

12.1.5. Dockerfile ビルドの失敗

Dockerfile ビルドの失敗

{
  "build_id": "5346a21d-3434-4764-85be-5be1296f293c",
  "trigger_kind": "github",                                                       //Optional
  "name": "test",
  "repository": "dgangaia/test",
  "docker_url": "quay.io/dgangaia/test",
  "error_message": "Could not find or parse Dockerfile: unknown instruction: GIT",
  "namespace": "dgangaia",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",                           //Optional
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "6ae9a86",
  "trigger_metadata": {                                                           //Optional
    "commit": "6ae9a86930fc73dd07b02e4c5bf63ee60be180ad",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {                                                              //Optional
      "url": "https://github.com/dgangaia/test/commit/6ae9a86930fc73dd07b02e4c5bf63ee60be180ad",
      "date": "2019-03-06T14:18:16+11:00",
      "message": "failed build test",
      "committer": {                                                              //Optional
        "username": "web-flow",
        "url": "https://github.com/web-flow",                                     //Optional
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"     //Optional
      },
      "author": {                                                                 //Optional
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",                                     //Optional
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"     //Optional
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/5346a21d-3434-4764-85be-5be1296f293c"
}

12.1.6. Dockerfile ビルドの取り消し

Dockerfile ビルドの取り消し

{
  "build_id": "cbd534c5-f1c0-4816-b4e3-55446b851e70",
  "trigger_kind": "github",
  "name": "test",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e",
  "docker_tags": [
    "master",
    "latest"
  ],
  "build_name": "cbce83c",
  "trigger_metadata": {
    "commit": "cbce83c04bfb59734fc42a83aab738704ba7ec41",
    "ref": "refs/heads/master",
    "default_branch": "master",
    "git_url": "git@github.com:dgangaia/test.git",
    "commit_info": {
      "url": "https://github.com/dgangaia/test/commit/cbce83c04bfb59734fc42a83aab738704ba7ec41",
      "date": "2019-03-06T14:27:53+11:00",
      "message": "testing cancel build",
      "committer": {
        "username": "web-flow",
        "url": "https://github.com/web-flow",
        "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4"
      },
      "author": {
        "username": "dgangaia",
        "url": "https://github.com/dgangaia",
        "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4"
      }
    }
  },
  "homepage": "https://quay.io/repository/dgangaia/test/build/cbd534c5-f1c0-4816-b4e3-55446b851e70"
}

12.1.7. 脆弱性の検知

リポジトリーでの脆弱性の検知

{
  "repository": "dgangaia/repository",
  "namespace": "dgangaia",
  "name": "repository",
  "docker_url": "quay.io/dgangaia/repository",
  "homepage": "https://quay.io/repository/dgangaia/repository",

  "tags": ["latest", "othertag"],

  "vulnerability": {
    "id": "CVE-1234-5678",
    "description": "This is a bad vulnerability",
    "link": "http://url/to/vuln/info",
    "priority": "Critical",
    "has_fix": true
  }
}

12.2. 通知アクション

12.2.1. Quay 通知

通知が Quay.io 通知エリアに追加されます。Quay.io ページの右上にあるベルアイコンをクリックすると、通知エリアを見つけることができます。

Quay.io 通知は、全体として ユーザーチーム、または 組織 に送信されるように設定できます。

12.2.2. メール

発生したイベントを説明するメールが指定されるアドレスに送信されます。

注記

すべてのメールアドレスは、リポジトリーごと に認証される必要があります。

12.2.3. Webhook POST

HTTP POST 呼び出しは、イベントのデータを含む指定された URL に対して行われます(各イベントのデータ形式については上記を参照してください)。

URL が HTTPS の場合、呼び出しには Quay.io から SSL クライアント証明書が設定されます。この証明書の検証により、Quay.io からの呼び出しが証明されます。2xx 範囲のステータスコードが含まれる応答は成功とみなされます。他のステータスコードを含む応答は失敗とみなされ、Webhook 通知が再試行されます。

12.2.4. Flowdock 通知

Flowdock にメッセージを投稿します。

12.2.5. HipChat 通知

HipChat にメッセージを投稿します。

12.2.6. Slack 通知

Slack にメッセージを投稿します。

:leveloffset: +2

パート I. Helm および OCI の前提条件

  • 信頼される証明書: Helm クライアントと Quay 間の通信は HTTPS 経由で行われ、Helm 3.5 の時点では、サポートは信頼される証明書を使用して HTTPS で通信するレジストリーについてのみ利用できます。さらに、オペレーティングシステムはレジストリーで公開される証明書を信頼する必要があります。今後の Helm リリースでのサポートにより、リモートレジストリーとの非セキュアな通信が可能になります。これを念頭に置いて、オペレーティングシステムが Quay で使用される証明書を信頼するように設定されていることを確認します。以下は例になります。

    $ sudo cp rootCA.pem   /etc/pki/ca-trust/source/anchors/
    $ sudo update-ca-trust extract
  • 実験的な機能: Helm および OCI レジストリーと対話するコマンドの多くは、helm chart サブコマンドを利用します。本書の作成時点では、Helm での OCI サポートは「experimental (実験的な)」機能とマークされており、明示的に有効にする必要があります。これは、環境変数 HELM_EXPERIMENTAL_OCI=1 を設定して実行されます。
  • Helm クライアントのインストール: 必要なバージョンを https://github.com/helm/helm/releases からダウンロードします (例: https://get.helm.sh/helm-v3.5.3-linux-amd64.tar.gz)。これを展開し、helm バイナリーをその必要な宛先に移動します。

    $ tar -zxvf helm-v3.5.3-linux-amd64.tar.gz
    $ mv linux-amd64/helm /usr/local/bin/helm
  • Quay での組織の作成: Quay レジストリー UI を使用し、Helm チャートを保存するために新しい組織を作成します。たとえば、helm という名前の組織を作成します。

1. Quay での Helm チャートの使用

Helm は、Cloud Native Computing Foundation (CNCF) から進展したプロジェクトとして、アプリケーションのパッケージ化およびデプロイを単純化する、Kubernetes の事実上のパッケージマネージャーです。Helm は、アプリケーションを表す Kubernetes リソースが含まれる Chart というパッケージ形式を使用します。Chart (チャート) は、リポジトリーでの一般的なディストリビューションや消費用に利用できます。Helm リポジトリーは、index.yaml メタデータファイルと、オプションでパッケージ化されたチャートのセットを提供する HTTP サーバーです。Helm バージョン 3 以降、従来のリポジトリーの代わりとして OCI レジストリーでチャートを提供するためのサポートが利用できるようになりました。Quay を Helm チャートのレジストリーとして使用する方法を説明するために、Helm リポジトリーの既存チャートを使用してチャート開発者とユーザー向けに OCI レジストリーとの対話を示します。

以下の例では、以下の手順に従って、サンプルの etherpad チャートが Red Community of Practice (CoP) リポジトリーからダウンロードされ、ローカルの Red Hat Quay リポジトリーにプッシュされます。

  • 適切なリポジトリーを追加します。
  • リポジトリーを最新のメタデータで更新します
  • チャートをダウンロードして展開し、 etherpad というローカルディレクトリーを作成します。

以下に例を示します。

$ helm repo add redhat-cop https://redhat-cop.github.io/helm-charts
$ helm repo update
$ helm pull redhat-cop/etherpad --version=0.0.4 --untar

チャートにタグ付けするには、helm chart save コマンドを使用する必要があります。これは、イメージにタグ付けするために podman タグ を使用することに対応します。

$ helm chart save ./etherpad example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4

ref:     example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4
digest:  6850d9b21dd4b87cf20ad49f2e2c7def9655c52ea573e1ddb9d1464eeb6a46a6
size:    3.5 KiB
name:    etherpad
version: 0.0.4
0.0.4: saved

helm chart list コマンドを使用して、チャートのローカルインスタンスを表示します。

helm chart list

REF                                                                               NAME     VERSION DIGEST SIZE   CREATED
example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4 etherpad 0.0.4   ce0233f 3.5 KiB 23 seconds

チャートをプッシュする前に、helm registry login コマンドを使用してリポジトリーにログインします。

$ helm registry login example-registry-quay-quay-enterprise.apps.user1.example.com
Username: quayadmin
Password:
Login succeeded

helm chart push コマンドを使用してチャートをローカル Quay リポジトリーにプッシュします。

$ helm chart push example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4

The push refers to repository [example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad]
ref:     example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4
digest:  ce0233fd014992b8e27cc648cdabbebd4dd6850aca8fb8e50f7eef6f2f49833d
size:    3.5 KiB
name:    etherpad
version: 0.0.4
0.0.4: pushed to remote (1 layer, 3.5 KiB total)

プッシュが機能することをテストするには、ローカルコピーを削除してから、チャートをリポジトリーからプルします。

$ helm chart rm example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4
$ rm -rf etherpad
$ helm chart pull example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4

0.0.4: Pulling from example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad
ref:     example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4
digest:  6850d9b21dd4b87cf20ad49f2e2c7def9655c52ea573e1ddb9d1464eeb6a46a6
size:    3.5 KiB
name:    etherpad
version: 0.0.4
Status: Downloaded newer chart for example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4

helm chart export コマンドを使用してチャートファイルを展開します。

$ helm chart export example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4

ref:     example-registry-quay-quay-enterprise.apps.user1.example.com/helm/etherpad:0.0.4
digest:  ce0233fd014992b8e27cc648cdabbebd4dd6850aca8fb8e50f7eef6f2f49833d
size:    3.5 KiB
name:    etherpad
version: 0.0.4
Exported chart to etherpad/

2. OCI および Helm の設定

Helm および OCI アーティファクトのサポートが、Red Hat Quay 3 でデフォルトで有効にされるようになりました。機能を明示的に有効にする必要がある場合(機能が無効にされている場合や、デフォルトで有効にされていないバージョンからアップグレードした場合など) は、OCI アーティファクトの使用を有効にするために 2 つのプロパティーを Quay 設定に追加する必要があります。

FEATURE_GENERAL_OCI_SUPPORT: true
FEATURE_HELM_OCI_SUPPORT: true

表1 OCI および Helm の設定

フィールドタイプ詳細

FEATURE_GENERAL_OCI_SUPPORT

ブール値

OCI アーティファクトのサポートを有効にします

デフォルト: True

FEATURE_HELM_OCI_SUPPORT

ブール値

Helm アーティファクトのサポートを有効にします

デフォルト: True

第13章 Red Hat Quay API の使用

Red Hat Quay は、以下の完全な OAuth 2 RESTful API を提供します。

  • URL https://<yourquayhost>/api/v1 で各 Red Hat Quay インスタンスのエンドポイントから利用できます。
  • Swagger UI を有効にして Red Hat Quay 設定を取得し、削除し、送信し、配置できるようにブラウザーでエンドポイントに接続できます。
  • API 呼び出しを実行し、OAuth トークンを使用するアプリケーションからアクセスできます。
  • JSON としてデータを送受信します。

以下では、Red Hat Quay API にアクセスし、これを使用して Red Hat Quay クラスターで設定を表示し、変更する方法を説明します。付録 A には API エンドポイントが一覧表示され、これらについて説明されています。

13.1. Quay.io から Quay API へのアクセス

独自の Red Hat Quay クラスターがまだ実行中でない場合は、Web ブラウザーから Quay.io で利用可能な Red Hat Quay API を確認できます。

https://docs.quay.io/api/swagger/

表示される API Explorer には Quay.io API エンドポイントが表示されます。スーパーユーザー API エンドポイントや (リポジトリーミラーリングなど) Quay.io で有効にされていない Red Hat Quay 機能のエンドポイントは表示されません。

API Explorer から、以下の情報を取得したり、変更したりすることが可能です。

  • Billing (請求)、サブスクリプション、Plan (計画)
  • リポジトリービルドおよびビルドトリガー
  • エラーメッセージおよびグローバルメッセージ
  • リポジトリーイメージ、マニフェスト、パーミッション、通知、脆弱性およびイメージの署名
  • 使用ログ
  • 組織、メンバーおよび OAuth アプリケーション
  • ユーザーおよびロボットアカウント
  • その他

これを選択してエンドポイントを開き、エンドポイントの各部分の Model Schema を表示します。エンドポイントを開き、必要なパラメーター (リポジトリー名やイメージなど) を入力し、「Try it out!」ボタンを選択して Quay.io エンドポイントに関連する設定をクエリーするか、または変更します。

13.2. OAuth アクセストークンの作成

組織の API にアクセスできるように OAuth アクセストークンを作成するには、以下を実行します。

  1. Red Hat Quay にログインし、使用する組織を選択します (または新規の組織を作成します)。
  2. 左側のナビゲーションから「Applications」アイコンを選択します。
  3. 「Create New Application」を選択し、プロンプトが出されたら新しいアプリケーションに名前を付けます。
  4. 新規アプリケーションを選択します。
  5. 左側のナビゲーションから「Generate Token」を選択します。
  6. チェックボックスを選択してトークンのスコープを設定し、「Generate Access Token」を選択します。
  7. 許可するパーミッションを確認し、「Authorize Application」を選択してこれを承認します。
  8. API にアクセスするために使用する新規に生成されたトークンをコピーします。

13.3. Web ブラウザーから Quay API へのアクセス

Swagger を有効にすると、Web ブラウザーを使用して独自の Red Hat Quay インスタンスの API にアクセスできます。この URL を使用すると、Swagger UI と URL で Red Hat Quay API を公開できます。

https://<yourquayhost>/api/v1/discovery.

この API にアクセスする方法には、Red Hat Quay インストールで利用可能なスーパーユーザーエンドポイントは含まれません。以下は、swagger-ui コンテナーイメージを実行してローカルシステムで実行されている Red Hat Quay API インターフェースにアクセスする例です。

# export SERVER_HOSTNAME=<yourhostname>
# sudo podman run -p 8888:8080 -e API_URL=https://$SERVER_HOSTNAME:8443/api/v1/discovery docker.io/swaggerapi/swagger-ui

swagger-ui コンテナーが実行されている状態で、Web ブラウザーを localhost ポート 8888 で開き、swagger-ui コンテナーで API エンドポイントを表示します。

「API calls must be invoked with an X-Requested-With header if called from a browser」などのエラーがログに出されるのを防ぐには、以下の行を、クラスター内のすべてのノード上の config.yaml に追加し、Red Hat Quay を再起動します。

BROWSER_API_CALLS_XHR_ONLY: false

13.4. コマンドラインからの Red Hat Quay API へのアクセス

curl コマンドを、Red Hat Quay クラスターの API で GET、PUT、POST、または DELETE 設定に使用できます。<token> を、以下の例で設定を取得または変更するために作成した OAuth アクセストークンに置き換えます。

13.4.1. スーパーユーザー情報の取得

$ curl -X GET -H "Authorization: Bearer <token_here>" \
    "https://<yourquayhost>/api/v1/superuser/users/"

以下に例を示します。

$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq

{
  "users": [
    {
      "kind": "user",
      "name": "quayadmin",
      "username": "quayadmin",
      "email": "quayadmin@example.com",
      "verified": true,
      "avatar": {
        "name": "quayadmin",
        "hash": "357a20e8c56e69d6f9734d23ef9517e8",
        "color": "#5254a3",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    }
  ]
}

13.4.2. API を使用したスーパーユーザーの作成

  • 『Quay のデプロイ』で説明されているようにスーパーユーザーの名前を設定します。

    • 設定エディターの UI を使用します。または以下を実行します。
    • 設定 API を使用して更新された設定バンドルを検証(およびダウンロード)するオプションで、config.yaml ファイルを直接編集します。
  • スーパーユーザー名のユーザーアカウントを作成します。

    • 上記のように認証トークンを取得し、curl を使用してユーザーを作成します。

      $ curl -H "Content-Type: application/json"  -H "Authorization: Bearer Fava2kV9C92p1eXnMawBZx9vTqVnksvwNm0ckFKZ" -X POST --data '{
       "username": "quaysuper",
       "email": "quaysuper@example.com"
      }'  http://quay-server:8080/api/v1/superuser/users/ | jq
    • 返されるコンテンツには、新規ユーザーアカウント用に生成されたパスワードが含まれます。

      {
        "username": "quaysuper",
        "email": "quaysuper@example.com",
        "password": "EH67NB3Y6PTBED8H0HC6UVHGGGA3ODSE",
        "encrypted_password": "fn37AZAUQH0PTsU+vlO9lS0QxPW9A/boXL4ovZjIFtlUPrBz9i4j9UDOqMjuxQ/0HTfy38goKEpG8zYXVeQh3lOFzuOjSvKic2Vq7xdtQsU="
      }

ユーザーの一覧を要求すると、quaysuper がスーパーユーザーとして表示されるようになりました。

$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq

{
  "users": [
  {
      "kind": "user",
      "name": "quayadmin",
      "username": "quayadmin",
      "email": "quayadmin@example.com",
      "verified": true,
      "avatar": {
        "name": "quayadmin",
        "hash": "357a20e8c56e69d6f9734d23ef9517e8",
        "color": "#5254a3",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    },
    {
      "kind": "user",
      "name": "quaysuper",
      "username": "quaysuper",
      "email": "quaysuper@example.com",
      "verified": true,
      "avatar": {
        "name": "quaysuper",
        "hash": "c0e0f155afcef68e58a42243b153df08",
        "color": "#969696",
        "kind": "user"
      },
      "super_user": true,
      "enabled": true
    }
  ]
}

13.4.3. ディレクトリーの同期

LDAP の対応するグループ名が ldapgroup の、testadminorg 組織の newteam チームのディレクトリーの同期を有効にするには、以下を実行します。

$ curl -X POST -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
       -H "Content-type: application/json" \
       -d '{"group_dn": "cn=ldapgroup,ou=Users"}' \
       http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing

同じチームの同期を無効にするには、以下を実行します。

$ curl -X DELETE -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
       http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing

13.4.4. API を使用したリポジトリービルドの作成

指定された入力からリポジトリーをビルドし、カスタムタグでビルドにタグを付けるために、requestRepoBuild エンドポイントを使用できます。これには、以下のデータが使用されます。

{
"docker_tags": [
   "string"
],
"pull_robot": "string",
"subdirectory": "string",
"archive_url": "string"
}

archive_url パラメーターは、Dockerfile およびその他のビルドに必要なファイルが含まれる tar または zip アーカイブを参照する必要があります。file_id パラメーターは、古いビルドシステムから分離されました。これを使用することはできません。Dockerfile がサブディレクトリーにある場合は、Dockerfile も指定する必要があります。

アーカイブは一般にアクセスできる必要があります。OAuth アプリケーションには、「Administer Organization」(組織管理者) のスコープが設定されている必要があります。組織管理者のみがロボットのアカウントトークンにアクセスできるためです。それ以外の場合は、他のユーザーは (アクセスがなくても) ロボットにビルドアクセスを付与するだけでロボットパーミッションを取得でき、これを使用してイメージコンテンツを取得できる場合があります。エラーが発生した場合は、返される json ブロックを確認し、アーカイブの場所、プルロボットおよびその他のパラメーターが正しく渡されていることを確認します。個々のビルドページの右上にある「Download logs」をクリックし、ログで詳細なメッセージを確認できます。

13.4.5. 組織ロボットの作成

$ curl -X PUT https://quay.io/api/v1/organization/{orgname}/robots/{robot shortname} \
   -H 'Authorization: Bearer <token>''

13.4.6. ビルドのトリガー

$ curl -X POST https://quay.io/api/v1/repository/YOURORGNAME/YOURREPONAME/build/ \
   -H 'Authorization: Bearer <token>'

要求を使用する Python

import requests
r = requests.post('https://quay.io/api/v1/repository/example/example/image', headers={'content-type': 'application/json', 'Authorization': 'Bearer <redacted>'}, data={[<request-body-contents>})
print(r.text)

13.4.7. プライベートリポジトリーの作成

$ curl -X POST https://quay.io/api/v1/repository \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{"namespace":"yournamespace", "repository":"yourreponame",
    "description":"descriptionofyourrepo", "visibility": "private"}' | jq