Red Hat Quay の使用
はじめに
Red Hat Quay コンテナーイメージレジストリーは、コンテナーイメージを保存する一元的なハブとして機能します。Red Hat Quay のユーザーは、リポジトリーを作成してイメージを効果的に管理し、必要に応じてリポジトリーに特定の読み取り (プル) および書き込み (プッシュ) 権限を付与できます。管理者権限を付与すると、これらの権限が拡張され、ユーザーはユーザーの追加やデフォルト設定の制御など、より広範なタスクを実行できるようになります。
このガイドでは、Red Hat Quay のユーザーと組織、テナンシーモデル、ユーザー、組織、リポジトリーの作成と削除、アクセスの処理、タグの操作などの基本操作の概要を説明します。UI と API の両方の操作について説明します。
このドキュメントの API エンドポイントには、Red Hat Quay API ガイド の関連エントリーへのリンクがあります。「Red Hat Quay API ガイド」には、応答コードやオプションのクエリーパラメーターなど、各エンドポイントに関する詳細情報が記載されています。
第1章 Red Hat Quay のテナンシーモデル
Red Hat Quay でコンテナーイメージを追加するリポジトリーを作成する前に、そのリポジトリーをどのように構成するかを検討する必要があります。Red Hat Quay では、各リポジトリーを 組織 または ユーザー と関係付ける必要があります。この関係により、リポジトリーの所有権とアクセス制御が定義されます。
1.1. テナンシーモデル
- 組織 は、単一のユーザーに属さない共通の名前空間のもとでリポジトリーを共有する方法を提供します。このようなリポジトリーは、会社などの共有設定内の複数のユーザーに属します。
- チーム は、組織から権限を委任する方法を提供します。権限は、グローバルレベル (たとえば、すべてのリポジトリー全体) で設定することも、特定のリポジトリーに対して設定することもできます。特定のユーザーのセットまたはグループに対して設定することもできます。
-
ユーザー は、Web UI を介してレジストリーにログインすることも、Podman などのクライアントを使用して、それぞれのログインコマンド
($ podman login
など) を使用してレジストリーにログインすることもできます。各ユーザーには、ユーザー名前空間が自動的に割り当てられます。たとえば、<quay-server.example.com>/<user>/<username>
、Quay.io を使用している場合はquay.io/<username>
です。 - スーパーユーザー は、ユーザーインターフェイスの Super User Admin Panel を通じて、強化されたアクセス権と特権を持ちます。スーパーユーザー API 呼び出しも利用できます。通常のユーザーは、これを表示することもアクセスすることもできません。
- ロボットアカウント は、パイプラインツールなどの人間以外のユーザーにリポジトリーへの自動アクセスを提供します。ロボットアカウントは OpenShift Container Platform の サービスアカウント に似ています。リポジトリー内のロボットアカウントに権限を付与するには、そのアカウントを他のユーザーやチームと同様に追加します。
第2章 Red Hat Quay のユーザーアカウントの概要
ユーザーアカウント は、プラットフォームの機能への認証アクセス権を持つ個人を表します。ユーザーアカウントは、リポジトリーの作成と管理、コンテナーイメージのアップロードと取得、これらのリソースへのアクセス権の制御を行う権限を提供します。このアカウントは、Red Hat Quay 内でコンテナーイメージ管理を体系化および監視するうえで極めて重要です。
Red Hat Quay UI または Red Hat Quay API を使用して、新しいユーザーを作成および削除できます。
2.1. UI を使用したユーザーアカウントの作成
UI を使用して Red Hat Quay リポジトリーの新しいユーザーを作成するには、次の手順に従います。
前提条件
- スーパーユーザーとして Red Hat Quay デプロイメントにログインしている。
手順
- Red Hat Quay リポジトリーにスーパーユーザーとしてログインします。
- ナビゲーションウィンドウでアカウント名を選択し、Super User Admin Panel をクリックします。
- 列の Users アイコンをクリックします。
- Create User ボタンをクリックします。
- 新しいユーザーのユーザー名とメールアドレスを入力し、Create User ボタンをクリックします。
Users ページにリダイレクトされ、別の Red Hat Quay ユーザーが表示されます。
注記追加したユーザーを表示するには、Users ページを更新する必要がある場合があります。
Users ページで、新しいユーザーに関連する Options の歯車をクリックします。下図のようなドロップダウンメニューが表示されます。
- Change Password をクリックします。
新しいパスワードを追加し、Change User Password をクリックします。
新しいユーザーが、そのユーザー名とパスワードを使用して、Web UI または Podman などの希望するコンテナークライアントを通じてログインできるようになります。
2.2. Red Hat Quay API を使用したユーザーアカウントの作成
API を使用して Red Hat Quay リポジトリーの新しいユーザーを作成するには、次の手順に従います。
前提条件
- スーパーユーザーとして Red Hat Quay デプロイメントにログインしている。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
POST /api/v1/superuser/users/
エンドポイントを使用して新しいユーザーを作成します。$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "username": "newuser", "email": "newuser@example.com" }' "https://<quay-server.example.com>/api/v1/superuser/users/"
出力例
{"username": "newuser", "email": "newuser@example.com", "password": "IJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1", "encrypted_password": "9Q36xF54YEOLjetayC0NBaIKgcFFmIHsS3xTZDLzZSrhTBkxUc9FDwUKfnxLWhco6oBJV1NDBjoBcDGmsZMYPt1dSA4yWpPe/JKY9pnDcsw="}
Red Hat Quay レジストリーエンドポイント (例:
quay-server.example.com
) に移動し、API 呼び出しから生成されたユーザー名とパスワードを使用してログインします。この場合、ユーザー名はnewuser
、パスワードはIJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1
です。または、CLI を使用してレジストリーにログインすることもできます。以下に例を示します。$ podman login <quay-server.example.com>
出力例
username: newuser password: IJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1
オプション:
GET /api/v1/superuser/users/
エンドポイントを使用して、スーパーユーザーを含むすべてのユーザーのリストを取得できます。$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"
出力例
{"users": [{"kind": "user", "name": "quayadmin", "username": "quayadmin", "email": "quay@quay.com", "verified": true, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}, "super_user": true, "enabled": true}, {"kind": "user", "name": "newuser", "username": "newuser", "email": "newuser@example.com", "verified": true, "avatar": {"name": "newuser", "hash": "f338a2c83bfdde84abe2d3348994d70c34185a234cfbf32f9e323e3578e7e771", "color": "#9edae5", "kind": "user"}, "super_user": false, "enabled": true}]}
2.3. UI を使用したユーザーの削除
UI を使用して Red Hat Quay リポジトリーからユーザーを削除するには、次の手順に従います。ユーザーを削除すると、そのユーザーのプライベートアカウントにあるリポジトリーがすべて使用できなくなることに注意してください。
場合によっては、Red Hat Quay UI の Superuser Admin Panel の Users タブにアクセスすると、ユーザーがリスト表示されないことがあります。代わりに、Red Hat Quay が外部認証を使用するように設定されていて、ユーザーはそのシステムでのみ作成できることを示すメッセージが表示されます。
このエラーは、次の 2 つの理由のいずれかで発生します。
- ユーザーを読み込むときに Web UI がタイムアウトします。この問題が発生すると、ユーザーはアクセスして操作を実行できなくなります。
- LDAP 認証: userID が変更されたが、関連付けられたメールアドレスが変更されていない場合。現在、Red Hat Quay では、古いメールアドレスを使用して新しいユーザーを作成することはできません。
このような場合は、Red Hat Quay API を使用してユーザーを削除する必要があります。
前提条件
- スーパーユーザーとして Red Hat Quay デプロイメントにログインしている。
手順
- Red Hat Quay リポジトリーにスーパーユーザーとしてログインします。
- ナビゲーションウィンドウでアカウント名を選択し、Super User Admin Panel をクリックします。
- ナビゲーションペインの Users アイコンをクリックします。
- 削除するユーザーの横にある Options の歯車をクリックします。
- Delete User をクリックし、Delete User をクリックして削除を確定します。
2.4. Red Hat Quay API を使用したユーザーの削除
API を使用して Red Hat Quay からユーザーを削除するには、次の手順に従います。
ユーザーを削除すると、このユーザーが自分のプライベートアカウントにあったリポジトリーはすべて使用できなくなります。
前提条件
- スーパーユーザーとして Red Hat Quay デプロイメントにログインしている。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
コマンドラインから次の
DELETE /api/v1/superuser/users/{username}
コマンドを入力し、ユーザーを削除します。$ curl -X DELETE -H "Authorization: Bearer <insert token here>" https://<quay-server.example.com>/api/v1/superuser/users/<username>
CLI からユーザーを削除する場合、CLI は情報を返しません。削除を確認するには、Superuser Admin Panel → Users に移動するか、次の
GET /api/v1/superuser/users/
コマンドを入力して、Red Hat Quay UI を確認します。すると、ユーザーが存在するかどうかを確認できます。$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"
第3章 Red Hat Quay の組織の概要
Red Hat Quay の組織は、ユーザー、リポジトリー、およびチームのグループです。レジストリー内のアクセス制御と権限を整理および管理する手段として機能します。組織を使用すると、管理者はユーザーとチームにロールと権限を割り当てることができます。組織に関するその他の有用な情報を以下に示します。
- 組織を別の組織内に組み込むことはできません。組織を細分化するには、チームを使用します。
組織にユーザーを直接含めることはできません。まずチームを追加してから、各チームに 1 人以上のユーザーを追加する必要があります。
注記個々のユーザーは、組織内の特定のリポジトリーに追加できます。そのため、これらのユーザーは、Repository Settings ページのどのチームのメンバーでもありません。Teams and Memberships ページの Collaborators View に、特に組織に所属する必要がなく、その組織内の特定のリポジトリーに直接アクセスできるユーザーが表示されます。
- チームは、リポジトリーおよび関連イメージを使用する単なるメンバーとして、または組織を管理するための特別な権限を持つ管理者として、組織内に設定できます。
ユーザーは自分の組織を作り、コンテナーイメージのリポジトリーを共有できます。これは、Red Hat Quay UI を通じて実行できます。OAuth トークンがある場合は、Red Hat Quay API によって実行することもできます。
3.1. UI を使用した組織の作成
UI を使用して新しい組織を作成するには、次の手順に従います。
手順
- Red Hat Quay レジストリーにログインします。
- ナビゲーションペインで Organization をクリックします。
- Create Organization をクリックします。
-
Organization Name (
testorg
など) を入力します。 - Organization Email を入力します。
- Create をクリックします。
これで、サンプルの組織が Organizations ページの下に表示されます。
3.2. Red Hat Quay API を使用した組織の作成
Red Hat Quay API を使用して新しい組織を作成するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
POST /api/v1/organization/
エンドポイントを使用して新しい組織を作成します。$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{ "name": "<new_organization_name>" }' "https://<quay-server.example.com>/api/v1/organization/"
出力例
"Created"
3.3. 組織の設定
Red Hat Quay では、UI を使用していくつかの基本的な組織設定を調整できます。これには、組織に関連付けられたメールアドレスなどの一般設定の調整や、タグが完全に削除された後にガベージコレクションされるタイミングを管理者が調整できる タイムマシン 設定が含まれます。
v2 UI を使用して組織の設定を変更するには、次の手順に従います。
手順
- v2 UI で、Organizations をクリックします。
-
ロボットアカウントを作成する組織の名前をクリックします (例:
test-org
)。 - Settings タブをクリックします。
- オプション: 組織に関連付けられたメールアドレスを入力します。
オプション: Time Machine 機能に割り当てられた時間を以下のいずれかに設定します。
- A few seconds
- A day
- 7 days
- 14 days
- A month
- Save をクリックします。
3.4. UI を使用した組織の削除
v2 UI を使用して組織を削除するには、次の手順を実行します。
手順
-
Organizations ページで、削除する組織の名前 (
testorg
など) を選択します。 - More Actions ドロップダウンメニューをクリックします。
Delete をクリックします。
注記Delete ページには、Search 入力ボックスがあります。このボックスを使用すると、ユーザーは特定の組織を検索して、削除が適切にスケジュールされていることを確認できます。たとえば、ユーザーが 10 の組織を削除していて、特定の組織が削除されたことを確認したい場合、Search 入力ボックスを使用して、その組織が削除対象としてマークされていることを確認できます。
- ボックスに confirm と入力して、組織を完全に削除することを確定します。
Delete をクリックします。
削除後、Organizations ページに戻ります。
注記複数の組織を選択してから、More Actions → Delete をクリックすると、一度に複数の組織を削除できます。
3.5. Red Hat Quay API を使用した組織の削除
Red Hat Quay API を使用して組織を削除するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
DELETE /api/v1/organization/{orgname}
エンドポイントを使用して組織を削除します。$ curl -X DELETE \ -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" \ "https://<quay-server.example.com>/api/v1/organization/<organization_name>"
CLI から組織を削除する場合、CLI は情報を返しません。削除を確認するには、Red Hat Quay UI を確認するか、
GET /api/v1/organization/{orgname}
コマンドを入力して、削除した組織の詳細が返されるかどうかを確認します。$ curl -X GET \ -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" \ "<quay-server.example.com>/api/v1/organization/<organization_name>"
出力例
{"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://<quay-server.example.com>/api/v1/error/not_found", "status": 404}
第4章 Red Hat Quay のリポジトリーの概要
リポジトリーは、関連するコンテナーイメージのセットを一元的に保存するための場所を提供します。これらのイメージを使用して、アプリケーションとその依存関係を標準化された形式で構築できます。
リポジトリーは名前空間を使用して整理します。名前空間には、それぞれ複数のリポジトリーを含めることができます。たとえば、個人プロジェクト用の名前空間、会社用の名前空間、または組織内の特定のチーム用の名前空間を設定できます。
Red Hat Quay では、ユーザーがリポジトリーへのアクセスを制御できます。リポジトリーをパブリックにすると、誰でもリポジトリーからイメージをプルまたはダウンロードできるようになります。リポジトリーをプライベートにすると、許可されたユーザーまたはチームのみにアクセスが制限されます。
Red Hat Quay でリポジトリーを作成するには、適切な podman
コマンドを使用してイメージをプッシュする方法、Red Hat Quay UI を使用する方法、Red Hat Quay API を使用する方法の 3 つがあります。同様に、リポジトリーの削除も、UI または適切な API エンドポイントを使用して実行できます。
4.1. UI を使用したリポジトリーの作成
Red Hat Quay UI を使用してリポジトリーを作成するには、次の手順を実行します。
手順
v2 UI を使用してリポジトリーを作成するには、次の手順を実行します。
手順
- ナビゲーションペインで Repositories をクリックします。
- Create Repository をクリックします。
名前空間 (例: quayadmin) を選択し、リポジトリー名 (例:
testrepo
) を入力します。重要リポジトリー名には単語 *
build
*trigger
*tag
を使用しないでください。これらの単語をリポジトリー名に使用すると、ユーザーがリポジトリーにアクセスできなくなり、リポジトリーを完全に削除できなくなります。このようなリポジトリーを削除しようとすると、
Failed to delete repository <repository_name>, HTTP404 - Not Found.
エラーが返されます。Create をクリックします。
これで、サンプルリポジトリーが Repositories ページの下に表示されるはずです。
- オプション: リポジトリーを非公開に設定するには、Settings → Repository visibility → Make private をクリックします。
4.2. Podman を使用したリポジトリーの作成
適切な認証情報がある場合は、Red Hat Quay インスタンスにまだ存在しないイメージを Podman を使用してリポジトリーに プッシュ できます。イメージのプッシュとは、ローカルシステムまたは開発環境から Red Hat Quay などのコンテナーレジストリーにコンテナーイメージをアップロードするプロセスを指します。イメージをレジストリーにプッシュすると、リポジトリーが作成されます。
イメージをプッシュしてイメージリポジトリーを作成するには、次の手順を実行します。
前提条件
-
podman
CLI をダウンロードしてインストールしている。 - レジストリーにログインしている。
- イメージ (busybox など) をプルしている。
手順
サンプルレジストリーからサンプルページを取得します。以下に例を示します。
$ sudo podman pull busybox
出力例
Trying to pull docker.io/library/busybox... Getting image source signatures Copying blob 4c892f00285e done Copying config 22667f5368 done Writing manifest to image destination Storing signatures 22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9
ローカルシステム上のイメージに、新しいリポジトリーとイメージ名をタグ付けします。以下に例を示します。
$ sudo podman tag docker.io/library/busybox quay-server.example.com/quayadmin/busybox:test
イメージをレジストリーにプッシュします。この手順の後に、ブラウザーを使用して、リポジトリーでタグ付けされたイメージを確認できます。
$ sudo podman push --tls-verify=false quay-server.example.com/quayadmin/busybox:test
出力例
Getting image source signatures Copying blob 6b245f040973 done Copying config 22667f5368 done Writing manifest to image destination Storing signatures
4.3. API を使用したリポジトリーの作成
Red Hat Quay API を使用してイメージリポジトリーを作成するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
POST /api/v1/repository
エンドポイントを使用してリポジトリーを作成します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{ "repository": "<new_repository_name>", "visibility": "<public>", "description": "<This is a description of the new repository>." }' \ "https://quay-server.example.com/api/v1/repository"
出力例
{"namespace": "quayadmin", "name": "<new_repository_name>", "kind": "image"}
4.4. UI を使用したリポジトリーの削除
UI 上で直接リポジトリーを削除できます。
前提条件
- リポジトリーが作成済みである。
手順
-
v2 UI の Repositories ページで、削除するリポジトリーのボックスをチェックします (例:
quayadmin/busybox
)。 - Actions ドロップダウンメニューをクリックします。
- Delete をクリックします。
ボックスに confirm と入力してから、Delete をクリックします。
削除後、Repositories ページに戻ります。
4.5. Red Hat Quay API を使用したリポジトリのを削除
Red Hat Quay API を使用してリポジトリーを削除するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
DELETE /api/v1/repository/{repository}
エンドポイントを使用してリポジトリーを削除します。$ curl -X DELETE -H "Authorization: Bearer <bearer_token>" "quay-server.example.com/api/v1/repository/<namespace>/<repository_name>"
CLI からリポジトリーを削除する場合、CLI は情報を返しません。削除を確認するには、Red Hat Quay UI を確認するか、次の
GET /api/v1/repository/{repository}
コマンドを入力して、削除したリポジトリーの詳細が返されるかどうかを確認します。$ curl -X GET -H "Authorization: Bearer <bearer_token>" "quay-server.example.com/api/v1/repository/<namespace>/<repository_name>"
出力例
{"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://quay-server.example.com/api/v1/error/not_found", "status": 404}
第5章 Red Hat Quay のロボットアカウントの概要
ロボットアカウントは、Red Hat Quay レジストリー内のリポジトリーへの自動アクセスを設定するのに使用します。ロボットアカウントは OpenShift Container Platform のサービスアカウントに似ています。
ロボットアカウントを設定すると、以下が実行されます。
- ロボットアカウントに関連付けられた認証情報が生成されます。
- ロボットアカウントがイメージをプッシュおよびプルできるリポジトリーとイメージが特定されます。
- 生成された認証情報をコピー/ペーストして、Docker、Podman、Kubernetes、Mesos などのさまざまなコンテナークライアントで使用し、定義された各リポジトリーにアクセスできます。
各ロボットアカウントは、1 つのユーザー名前空間または組織に制限されます。たとえば、ロボットアカウントは、ユーザー quayadmin
にすべてのリポジトリーへのアクセスを提供できます。しかし、ユーザーのリポジトリーリストにないリポジトリーへのアクセスは提供できません。
ロボットアカウントは、Red Hat Quay UI を使用して作成することも、Red Hat Quay API を使用して CLI 経由で作成することもできます。
5.1. UI を使用したロボットアカウントの作成
v2 UI を使用してロボットアカウントを作成するには、次の手順を実行します。
手順
- v2 UI で、Organizations をクリックします。
-
ロボットアカウントを作成する組織の名前をクリックします (例:
test-org
)。 - Robot accounts タブ → Create robot account をクリックします。
-
Provide a name for your robot account ボックスに、
robot1
などの名前を入力します。ロボットアカウントの名前は、ユーザー名とロボットの名前を組み合わせたものになります (例:quayadmin+robot1
)。 オプション: 必要に応じて、以下のオプションを使用できます。
- ロボットアカウントをチームに追加します。
- ロボットアカウントをリポジトリーに追加します。
- ロボットアカウントの権限を調整します。
Review and finish ページで、入力した情報を確認してから、Review and finish をクリックします。Successfully created robot account with robot name: <organization_name> + <robot_name> というアラートが表示されます。
また、別のロボットアカウントと同じ名前でロボットアカウントを作成しようとすると、Error creating robot account というエラーメッセージが表示される場合があります。
- オプション: Expand または Collapse をクリックすると、ロボットアカウントの説明情報を表示できます。
- オプション: 縦の省略記号メニュー → Set repository permissions をクリックして、ロボットアカウントのパーミッションを変更できます。Successfully updated repository permission というメッセージが表示されます。
オプション: ロボットアカウントの名前をクリックすると、次の情報を取得できます。
- Robot Account: ロボットアカウントのトークンを取得するには、これを選択します。Regenerate token now をクリックすると、トークンを再生成できます。
- Kubernetes Secret: Kubernetes プルシークレット YAML ファイルの形式で認証情報をダウンロードするには、これを選択します。
-
Podman: 認証情報を含む完全な
podman login
コマンドラインをコピーするには、これを選択します。 -
Docker Configuration: 認証情報を含む完全な
docker login
コマンドラインをコピーするには、これを選択します。
5.2. Red Hat Quay API を使用したロボットアカウントの作成
Red Hat Quay API を使用してロボットアカウントを作成するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
PUT /api/v1/organization/{orgname}/robots/{robot_shortname}
エンドポイントを使用して組織の新しいロボットアカウントを作成します。$ curl -X PUT -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots/<robot_name>"
出力例
{"name": "orgname+robot-name", "created": "Fri, 10 May 2024 15:11:00 -0000", "last_accessed": null, "description": "", "token": "WB4FUG4PP2278KK579EN4NDP150CPYOG6DN42MP6JF8IAJ4PON4RC7DIOH5UEFBP", "unstructured_metadata": null}
次のコマンドを入力し、
PUT /api/v1/user/robots/{robot_shortname}
エンドポイントを使用して現在のユーザーの新しいロボットアカウントを作成します。$ curl -X PUT -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/user/robots/<robot_name>"
出力例
{"name": "quayadmin+robot-name", "created": "Fri, 10 May 2024 15:24:57 -0000", "last_accessed": null, "description": "", "token": "MXFE7NSOWPN33O7UC3THY0BN03DW940CMWTLRBE2EPTI8JPX0B0CWIIDGTI4YTJ6", "unstructured_metadata": null}
5.3. ロボットアカウントのリポジトリーアクセスの一括管理
Red Hat Quay v2 UI を使用してロボットアカウントのリポジトリーアクセスを一括管理するには、次の手順を実行します。
前提条件
- ロボットアカウントを作成している。
- 1 つの組織に複数のリポジトリーを作成している。
手順
- Red Hat Quay v2 UI ランディングページで、ナビゲーションペインの Organizations をクリックします。
- Organizations ページで、複数のリポジトリーを持つ組織の名前を選択します。単一組織内のリポジトリーの数は、Repo Count 列で確認できます。
- 組織のページで、Robot accounts をクリックします。
- 複数のリポジトリーにロボットアカウントを追加する場合は、縦の省略記号アイコン → Set repository permissions をクリックします。
Set repository permissions ページで、ロボットアカウントを追加するリポジトリーのチェックボックスをオンにします。以下に例を示します。
- ロボットアカウントの権限を設定します (例: None、Read、Write、Admin)。
- Save をクリックします。Success alert: Successfully updated repository permission というアラートが Set repository permissions ページに表示され、変更が確認されます。
- Organizations → Robot accounts ページに戻ります。これで、ロボットアカウントの Repositories 列に、ロボットアカウントが追加されたリポジトリーの数が表示されます。
5.4. UI を使用したロボットアカウントの無効化
Red Hat Quay 管理者は、ユーザーに新しいロボットアカウントの作成を禁止することでロボットアカウントを管理できます。
リポジトリーのミラーリングにはロボットアカウントが必要です。ROBOTS_DISALLOW
設定フィールドを true
に設定すると、ミラーリング設定が破棄されます。リポジトリーをミラーリングするユーザーは、config.yaml
ファイルで ROBOTS_DISALLOW
を true
に設定しないでください。これは既知の問題であり、Red Hat Quay の今後のリリースで修正される予定です。
ロボットアカウントの作成を無効にするには、次の手順を実行します。
前提条件
- 複数のロボットアカウントを作成している。
手順
config.yaml
フィールドを更新してROBOTS_DISALLOW
変数を追加します。次に例を示します。ROBOTS_DISALLOW: true
- Red Hat Quay デプロイメントを再起動します。
検証: 新しいロボットアカウントの作成
- Red Hat Quay リポジトリーに移動します。
- リポジトリーの名前をクリックします。
- ナビゲーションウィンドウで、Robot Accounts をクリックします。
- Create Robot Account をクリックします。
-
ロボットアカウントの名前を入力します (例:
<organization-name/username>+<robot-name>)
。 -
Create robot account をクリックして作成を確定します。次のメッセージが表示されます。
Cannot create robot account.Robot accounts have been disabled.Please contact your administrator.
検証: ロボットアカウントへのログイン
コマンドラインインターフェイス (CLI) で、次のコマンドを入力してロボットアカウントの 1 つとしてログインを試みます。
$ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" <quay-server.example.com>
次のエラーメッセージが返されます。
Error: logging into "<quay-server.example.com>": invalid username/password
log-level=debug
フラグを渡すと、ロボットアカウントが無効化されたことを確認できます。$ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" --log-level=debug <quay-server.example.com>
... DEBU[0000] error logging into "quay-server.example.com": unable to retrieve auth token: invalid username/password: unauthorized: Robot accounts have been disabled. Please contact your administrator.
5.5. Red Hat Quay API を使用したロボットアカウントトークンの再生成
Red Hat Quay API を使用してロボットアカウントトークンを再生成するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
POST /api/v1/organization/{orgname}/robots/{robot_shortname}/regenerate
エンドポイントを使用して組織のロボットアカウントトークンを再生成します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ "quay-server.example.com/api/v1/organization/<orgname>/robots/<robot_shortname>/regenerate"
出力例
{"name": "test-org+test", "created": "Fri, 10 May 2024 17:46:02 -0000", "last_accessed": null, "description": "", "token": "MXZ9DATUWRD8WCMT8AZIPYE0IEZHJJ1B8P8ZEIXC0W552DUMMTNJJH02HFGXTOVG"}
次のコマンドを入力し、
POST /api/v1/user/robots/{robot_shortname}/regenerate
エンドポイントを使用して現在のユーザーのロボットアカウントトークンを再生成します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ "quay-server.example.com/api/v1/user/robots/<robot_shortname>/regenerate"
出力例
{"name": "quayadmin+test", "created": "Fri, 10 May 2024 14:12:11 -0000", "last_accessed": null, "description": "", "token": "CWLBVAODE61IXNDJ40GERFOZPB3ARZDRCP4X70ID1NB28AI0OOJBTR9S4M0ACYMD"}
5.6. UI を使用したロボットアカウントの削除
Red Hat Quay UI を使用してロボットアカウントを削除するには、次の手順に従います。
手順
- Red Hat Quay レジストリーにログインします。
- ロボットアカウントがある組織の名前をクリックします。
- Robot accounts をクリックします。
- 削除するロボットアカウントのボックスをチェックします。
- 縦の省略記号メニューをクリックします。
- Delete をクリックします。
-
テキストボックスに
confirm
と入力し、Delete をクリックします。
5.7. Red Hat Quay API を使用したロボットアカウントの削除
Red Hat Quay API を使用してロボットアカウントを削除するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
DELETE /api/v1/organization/{orgname}/robots/{robot_shortname}
エンドポイントを使用して組織のロボットアカウントを削除します。curl -X DELETE \ -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" \ "quay-server.example.com/api/v1/organization/<organization_name>/robots/<robot_shortname>"
API を使用してロボットアカウントを削除する場合、CLI は情報を返しません。削除を確認するには、Red Hat Quay UI を確認するか、次の
GET /api/v1/organization/{orgname}/robots
コマンドを入力して、ロボットアカウントの詳細が返されるかどうかを確認します。$ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots"
出力例
{"robots": []}
次のコマンドを入力し、
DELETE /api/v1/user/robots/{robot_shortname}
エンドポイントを使用して現在のユーザーのロボットアカウントを削除します。curl -X DELETE \ -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" \ "quay-server.example.com/api/v1/user/robots/<robot_shortname>"
API を使用して現在のユーザーのロボットアカウントを削除する場合、CLI は情報を返しません。削除を確認するには、Red Hat Quay UI を確認するか、次の
GET /api/v1/user/robots/{robot_shortname}
コマンドを入力して、ロボットアカウントの詳細が返されるかどうかを確認します。$ curl -X GET \ -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" \ "quay-server.example.com/api/v1/user/robots/<robot_shortname>"
出力例
{"message":"Could not find robot with specified username"}
第6章 Red Hat Quay のアクセス管理
Red Hat Quay ユーザーは、独自のリポジトリーを作成し、インスタンスに含まれる他のユーザーにそのリポジトリーへのアクセスを許可できます。または、組織を作成し、その組織にリポジトリーのセット (これは 組織リポジトリー と呼ばれます) を直接関連付けることもできます。
組織リポジトリーは、組織がユーザーのグループを通じて共有リポジトリーをセットアップすることを目的としているという点で、基本的なリポジトリーとは異なります。Red Hat Quay では、ユーザーのグループは、チーム、同じ権限を持つユーザーのセット、または 個々のユーザー のいずれかです。また、ロボットアカウントに関連付けられた認証情報を作成することで、ユーザーリポジトリーと組織リポジトリーへのアクセスを許可することもできます。ロボットアカウントを使用すると、Red Hat Quay ユーザーアカウントを持っていないさまざまなコンテナークライアント (Docker や Podman など) がリポジトリーに簡単にアクセスできるようになります。
6.1. Red Hat Quay のチームの概要
Red Hat Quay の チーム は、権限を共有するユーザーのグループであり、プロジェクトの効率的な管理とコラボレーションを可能にするものです。チームは、組織およびリポジトリー内のアクセス制御とプロジェクト管理を効率化するのに役立ちます。指定の権限をチームに割り当てることで、メンバーの役割と責任に基づいて、リポジトリーへの適切なレベルのアクセス権を付与できます。
6.1.1. UI を使用したチームの作成
組織のためにチームを作成する際に、チーム名を選択し、チームが利用できるリポジトリーを選択し、チームのアクセスレベルを決定できます。
組織リポジトリー用のチームを作成するには、次の手順に従います。
前提条件
- 組織を作成している。
手順
- Red Hat Quay v2 UI で、組織の名前をクリックします。
- 組織のページで、Teams and membership をクリックします。
- Create new team ボックスをクリックします。
- Create team ポップアップウィンドウで、新しいチームの名前を入力します。
- オプション: 新しいチームの説明を入力します。
- Proceed をクリックします。新しいポップアップウィンドウが表示されます。
オプション: このチームをリポジトリーに追加し、権限を次のいずれかに設定します。
- None。チームメンバーにリポジトリーに対する権限は付与されません。
- Read。チームメンバーがリポジトリーの表示とリポジトリーからのプルを行えるようになります。
- Write。チームメンバーがリポジトリーの読み取り (プル) とリポジトリーへの書き込み (プッシュ) を行えるようになります。
- Admin。プルおよびプッシュを行うためのリポジトリーへのフルアクセスに加えて、リポジトリーに関連する管理作業を行う権限を付与します。
- オプション: チームメンバーまたはロボットアカウントを追加します。チームメンバーを追加するには、Red Hat Quay アカウントの名前を入力します。
- 情報を確認し、Review and Finish をクリックします。新しいチームが Teams and membership ページに表示されます。
6.1.2. API を使用したチームの作成
API を使用して組織のチームを作成する際に、チーム名を選択し、チームが利用できるリポジトリーを選択し、チームのアクセスレベルを決定できます。
組織リポジトリー用のチームを作成するには、次の手順に従います。
前提条件
- 組織を作成している。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、組織のチームを作成します。
$ ------------------------------ $ curl -k -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -H "Authorization: Bearer <bearer_token>" --data '{"role": "creator"}' https://<quay-server.example.com>/api/v1/organization/<organization_name>/team/<team_name>
出力例
{"name": "example_team", "description": "", "can_view": true, "role": "creator", "avatar": {"name": "example_team", "hash": "dec209fd7312a2284b689d4db3135e2846f27e0f40fa126776a0ce17366bc989", "color": "#e7ba52", "kind": "team"}, "new_team": true}
6.1.3. UI を使用したチームの管理
チームを作成したら、UI を使用してチームメンバーを管理したり、リポジトリー権限を設定したり、チームを削除したり、チームに関するより一般的な情報を表示したりできます。
6.1.3.1. UI を使用したチームへのユーザーの追加
組織に対する管理者権限を持っていれば、ユーザーとロボットアカウントをチームに追加できます。ユーザーを追加すると、Red Hat Quay はそのユーザーにメールを送信します。そのユーザーが招待を受け入れるまで、ユーザーは保留状態のままになります。
ユーザーまたはロボットアカウントをチームに追加するには、次の手順を実行します。
手順
- Red Hat Quay のランディングページで、組織の名前をクリックします。
- ナビゲーションウィンドウで、Teams and Membership をクリックします。
- ユーザーまたはロボットアカウントを追加するチームの縦の省略記号メニューを選択します。Manage team members をクリックします。
- Add new member をクリックします。
テキストボックスに、次のいずれかの情報を入力します。
- レジストリー上のアカウントからのユーザー名。
- レジストリー上のユーザーアカウントのメールアドレス。
ロボットアカウントの名前。名前は、<組織名>+<ロボット名> の形式である必要があります。
注記ロボットアカウントはすぐにチームに追加されます。ユーザーアカウントの場合、参加の招待がユーザーにメールで送信されます。ユーザーがその招待を受け入れるまで、ユーザーは INVITED TO JOIN 状態のままになります。ユーザーがチームへの参加招待メールを受け入れると、INVITED TO JOIN リストから組織の MEMBERS リストに移動します。
- Add member をクリックします。
6.1.3.2. UI を使用したチームのロールの設定
チームを作成したら、そのチームの組織内でのロールを設定できます。
前提条件
- チームを作成している。
手順
- Red Hat Quay のランディングページで、組織の名前をクリックします。
- ナビゲーションウィンドウで、Teams and Membership をクリックします。
次の図に示すように、TEAM ROLE ドロップダウンメニューを選択します。
選択したチームについて、以下のロールのいずれかを選択します。
- Admin。チームの作成、メンバーの追加、権限の設定など、組織への完全な管理アクセス権を付与します。
- Member。チームに設定されているすべての権限を継承します。
- Creator。メンバーのすべての権限に加えて、新しいリポジトリーを作成する権限を付与します。
6.1.3.2.1. チームメンバーとリポジトリー権限の管理
チームメンバーを管理し、リポジトリー権限を設定するには、次の手順に従います。
組織の Teams and membership ページでは、チームメンバーを管理したり、リポジトリー権限を設定したりすることもできます。
- 縦の省略記号メニューをクリックし、次のいずれかのオプションを選択します。
- Manage Team Members。このページでは、すべてのメンバー、チームメンバー、ロボットアカウント、または招待したユーザーを表示できます。Add new member をクリックして、新しいチームメンバーを追加することもできます。
Set repository permissions。このページでは、リポジトリー権限を次のいずれかに設定できます。
- None。チームメンバーにリポジトリーに対する権限は付与されません。
- Read。チームメンバーがリポジトリーの表示とリポジトリーからのプルを行えるようになります。
- Write。チームメンバーがリポジトリーの読み取り (プル) とリポジトリーへの書き込み (プッシュ) を行えるようになります。
- Admin。プルおよびプッシュを行うためのリポジトリーへのフルアクセスに加えて、リポジトリーに関連する管理作業を行う権限を付与します。
- Delete。このポップアップウィンドウでは、Delete をクリックしてチームを削除できます。
6.1.3.2.2. チームに関する追加情報の表示
チームに関する一般情報を表示するには、次の手順に従います。
手順
組織の Teams and membership ページで、次のいずれかのオプションをクリックすると、チーム、メンバー、コラボレーターに関する詳細情報を表示できます。
- Team View。このメニューには、すべてのチーム名、メンバーの数、リポジトリーの数、および各チームのロールが表示されます。
- Members View。このメニューには、チームメンバーのすべてのユーザー名、メンバーが属しているチーム、ユーザーのリポジトリー権限が表示されます。
- Collaborators View。このメニューにはリポジトリーのコラボレーターが表示されます。コラボレーターは、組織内のどのチームにも属さないが、組織に属する 1 つ以上のリポジトリーに対する直接権限を持つユーザーです。
6.1.4. Red Hat Quay API を使用したチームの管理
チームを作成したら、API を使用して、チームの権限やチームメンバーに関する情報を取得したり、チームメンバーを追加、更新、削除したり (メールによる削除を含む)、組織のチームを削除したりできます。
次の手順では、Red Hat Quay API を使用してチームを管理する方法を説明します。
6.1.4.1. API を使用したチームメンバーとリポジトリー権限の管理
チームにメンバーを追加する (直接招待またはメールによる)、またはチームからメンバーを削除するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
PUT /api/v1/organization/{orgname}/team/{teamname}/members/{membername}
コマンドを入力し、既存のチームにメンバーを追加または招待します。$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"
出力例
{"name": "testuser", "kind": "user", "is_robot": false, "avatar": {"name": "testuser", "hash": "d51d17303dc3271ac3266fb332d7df919bab882bbfc7199d2017a4daac8979f0", "color": "#5254a3", "kind": "user"}, "invited": false}
DELETE /api/v1/organization/{orgname}/team/{teamname}/members/{membername}
コマンドを入力し、チームのメンバーを削除します。$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/members/<member_name>"
このコマンドは CLI に出力しません。メンバーが削除されたことを確認するには、
GET /api/v1/organization/{orgname}/team/{teamname}/members
コマンドを入力し、出力にメンバーが返されないことを確認します。$ curl -X GET \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/members"
出力例
{"name": "owners", "members": [{"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}, "invited": false}, {"name": "test-org+test", "kind": "user", "is_robot": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}, "invited": false}], "can_edit": true}
PUT /api/v1/organization/{orgname}/team/{teamname}/invite/{email}
コマンドを入力し、メールアドレスでユーザーを既存のチームに招待できます。$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/invite/<email>"
DELETE /api/v1/organization/{orgname}/team/{teamname}/invite/{email}
コマンドを入力し、チームに参加させるためのメールアドレスの招待を削除できます。以下に例を示します。$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/invite/<email>"
6.1.4.2. API を使用して組織内のチームのロールを設定する
API を使用して組織内のチームのロールを表示および設定するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
組織のチームのリポジトリー権限リストが返されるように、次のコマンドを入力します。このコマンドで情報を取得するには、チームがリポジトリーに追加されている必要があることに注意してください。
$ curl -X GET \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>/permissions"
出力例
{"permissions": [{"repository": {"name": "api-repo", "is_public": true}, "role": "admin"}]}
組織内のチームを作成または更新して、admin、member、または creator のロールを指定できます。以下に例を示します。
$ curl -X PUT \ -H "Authorization: Bearer <your_access_token>" \ -H "Content-Type: application/json" \ -d '{ "role": "<role>" }' \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>"
出力例
{"name": "testteam", "description": "", "can_view": true, "role": "creator", "avatar": {"name": "testteam", "hash": "827f8c5762148d7e85402495b126e0a18b9b168170416ed04b49aae551099dc8", "color": "#ff7f0e", "kind": "team"}, "new_team": false}
6.1.4.3. API を使用した組織内のチームの削除
API を使用して組織内のチームを削除するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
DELETE /api/v1/organization/{orgname}/team/{teamname}
コマンドを入力すると、組織内のチームを削除できます。$ curl -X DELETE \ -H "Authorization: Bearer <your_access_token>" \ "quay-server.example.com/api/v1/organization/<organization_name>/team/<team_name>"
このコマンドは CLI に出力を返しません。
6.2. UI を使用したデフォルトの権限の作成および管理
デフォルトの権限は、リポジトリーの作成者のデフォルトに加えて、リポジトリーの作成時にリポジトリーに自動的に付与される権限を定義します。権限は、リポジトリーを作成したユーザーに基づいて割り当てられます。
Red Hat Quay v2 UI を使用してデフォルトの権限を作成するには、次の手順を実行します。
手順
- 組織名をクリックします。
- Default permissions をクリックします。
- Create default permissions をクリックします。切り替え式のドロワーが表示されます。
リポジトリーの作成時にデフォルトの権限を作成するには、Anyone または Specific user を選択します。
Anyone を選択する場合は、次の情報を入力する必要があります。
- Applied to。ユーザー/ロボット/チームを検索、招待、または追加します。
- Permission。権限を Read、Write、または Admin のいずれかに設定します。
Specific user を選択する場合は、次の情報を指定する必要があります。
- Repository creator。ユーザーまたはロボットアカウントを指定します。
- Applied to。ユーザー名、ロボットアカウント、またはチーム名を入力します。
- Permission。権限を Read、Write、または Admin のいずれかに設定します。
- Create default permission をクリックします。確認ボックスが表示され、Successfully created default permission for creator というアラートが返されます。
6.3. API を使用したデフォルトの権限の作成および管理
Red Hat Quay API を使用してデフォルトの権限を管理するには、次の手順に従います。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
POST /api/v1/organization/{orgname}/prototypes
エンドポイントでデフォルトの権限を作成します。$ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" --data '{ "role": "<admin_read_or_write>", "delegate": { "name": "<username>", "kind": "user" }, "activating_user": { "name": "<robot_name>" } }' https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes
出力例
{"activating_user": {"name": "test-org+test", "is_robot": true, "kind": "user", "is_org_member": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}}, "delegate": {"name": "testuser", "is_robot": false, "kind": "user", "is_org_member": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}}, "role": "admin", "id": "977dc2bc-bc75-411d-82b3-604e5b79a493"}
次のコマンドを入力し、
PUT /api/v1/organization/{orgname}/prototypes/{prototypeid}
エンドポイントを使用してデフォルトの権限を更新します。これは権限タイプを変更する場合の例です。ポリシーを作成したときに返された ID を含める必要があります。$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "role": "write" }' \ https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes/<prototypeid>
出力例
{"activating_user": {"name": "test-org+test", "is_robot": true, "kind": "user", "is_org_member": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}}, "delegate": {"name": "testuser", "is_robot": false, "kind": "user", "is_org_member": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}}, "role": "write", "id": "977dc2bc-bc75-411d-82b3-604e5b79a493"}
DELETE /api/v1/organization/{orgname}/prototypes/{prototypeid}
コマンドを入力すると、権限を削除できます。curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes/<prototype_id>
このコマンドは出力を返しません。
GET /api/v1/organization/{orgname}/prototypes
コマンドを入力すると、すべての権限のリストを取得できます。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes
出力例
{"prototypes": []}
6.4. UI を使用したリポジトリーのアクセス設定の調整
v2 UI を使用してリポジトリーのユーザーまたはロボットアカウントのアクセス設定を調整するには、次の手順に従います。
前提条件
- ユーザーアカウントまたはロボットアカウントを作成した。
手順
- Red Hat Quay にログインします。
- v2 UI で、Repositories をクリックします。
-
リポジトリーの名前をクリックします (例:
quayadmin/busybox
)。 - Settings タブをクリックします。
オプション: User and robot permissions をクリックします。Permissions のドロップダウンメニューオプションをクリックすると、ユーザーまたはロボットアカウントの設定を調整できます。設定を Read、Write、または Admin に変更できます。
- Read。ユーザーまたはロボットアカウントが、リポジトリーを表示し、リポジトリーからプルできます。
- Write。ユーザーまたはロボットアカウントが、リポジトリーからの読み取り (プル) とリポジトリーへの書き込み (プッシュ) を実行できます。
- Admin。ユーザーアカウントまたはロボットアカウントに、リポジトリーからのプルとリポジトリーへのプッシュのアクセス権に加え、リポジトリーに関連する管理タスクを実行する権限を付与します。
6.5. API を使用したリポジトリーのアクセス設定の調整
API を使用してリポジトリーのユーザーアカウントまたはロボットアカウントのアクセス設定を調整するには、次の手順に従います。
前提条件
- ユーザーアカウントまたはロボットアカウントを作成した。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
ユーザーの権限を変更するには、次の
PUT /api/v1/repository/{repository}/permissions/user/{username}
コマンドを入力します。$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -d '{"role": "admin"}' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>
出力例
{"role": "admin", "name": "quayadmin+test", "is_robot": true, "avatar": {"name": "quayadmin+test", "hash": "ca9afae0a9d3ca322fc8a7a866e8476dd6c98de543decd186ae090e420a88feb", "color": "#8c564b", "kind": "robot"}}
現在の権限を削除するには、
DELETE /api/v1/repository/{repository}/permissions/user/{username}
コマンドを入力します。$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>
このコマンドは CLI に出力を返しません。
GET /api/v1/repository/{repository}/permissions/user/
コマンドを入力すると、権限が削除されたことを確認できます。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>/
出力例
{"message":"User does not have permission for repo."}
第7章 イメージタグの概要
イメージタグ は、コンテナーイメージの特定のバージョンまたはバリアントに割り当てられたラベルまたは識別子を指します。コンテナーイメージは通常、イメージのさまざまな部分を表す複数のレイヤーで構成されます。イメージタグは、異なるバージョンのイメージを区別したり、イメージに関する追加情報を提供したりするために使用します。
イメージタグには次の利点があります。
- バージョン管理とリリース: イメージタグを使用すると、アプリケーションまたはソフトウェアのさまざまなバージョンまたはリリースを示すことができます。たとえば、初期リリースを表すために v1.0 とイメージにタグ付けしたり、更新されたバージョンを表すために v1.1 とタグ付けしたりできます。これは、イメージのバージョンの明確な履歴を維持するのに役立ちます。
- ロールバックとテスト: 新しいイメージのバージョンで問題が発生した場合は、タグを指定することで以前のバージョンに簡単に戻すことができます。これは、デバッグ段階とテスト段階で役立ちます。
- 開発環境: イメージタグは、さまざまな環境で作業する場合に役立ちます。たとえば、開発バージョンには dev タグ、品質保証テストには qa、本番環境には prod タグを使用して、それぞれ機能と設定を異なるものにすることができます。
- 継続的インテグレーション/継続的デプロイメント (CI/CD): CI/CD パイプラインでは、イメージタグを使用してデプロイメントプロセスを自動化することがよくあります。新しいコードの変更により、特定のタグを持つ新しいイメージの作成をトリガーすることで、シームレスな更新が可能になります。
- 機能ブランチ: 複数の開発者が異なる機能やバグ修正に取り組んでいる場合は、変更ごとに個別のイメージタグを作成できます。これは、個々の機能を分離してテストするのに役立ちます。
- カスタマイズ: イメージタグを使用すると、各バリアントを追跡しながら、さまざまな設定、依存関係、または最適化を使用してイメージをカスタマイズできます。
- セキュリティーとパッチ適用: セキュリティーの脆弱性が発見された場合は、更新されたタグを使用して、パッチが適用されたバージョンのイメージを作成し、セキュアな最新バージョンをシステムで確実に使用できます。
- Dockerfile の変更: Dockerfile またはビルドプロセスを変更する場合は、イメージタグを使用して、以前の Dockerfile と更新された Dockerfile からビルドしたイメージを区別できます。
全体として、イメージタグはコンテナーイメージを管理および整理するための構造化された方法を提供し、開発、デプロイ、および保守の効率的なワークフローを可能にします。
7.1. UI を使用してイメージタグ情報を表示する
v2 UI を使用してイメージタグ情報を表示するには、次の手順を実行します。
前提条件
- イメージタグをリポジトリーにプッシュした。
手順
- v2 UI で、Repositories をクリックします。
- リポジトリーの名前をクリックします。
タグの名前をクリックします。そのタグの Details ページに移動します。このページには、次の情報が表示されます。
- 名前
- リポジトリー
- ダイジェスト
- 脆弱性
- 作成
- 修正済み
- サイズ
- ラベル
- イメージタグの取得方法
- Security Report をクリックして、タグの脆弱性を表示します。アドバイザリーの列を拡張して、CVE データを開くことができます。
- Packages をクリックして、タグのパッケージを表示します。
- リポジトリーの名前をクリックし、Tags ページに戻ります。
7.2. API を使用してイメージタグ情報を表示する
API を使用してイメージタグ情報を表示するには、次の手順に従います。
前提条件
- イメージタグを Red Hat Quay リポジトリーにプッシュした。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
タグ情報を取得するために、
GET /api/v1/repository/{repository}
API エンドポイントを使用し、includeTags
パラメーターを渡す必要があります。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>?includeTags=true
出力例
{"namespace": "quayadmin", "name": "busybox", "kind": "image", "description": null, "is_public": false, "is_organization": false, "is_starred": false, "status_token": "d8f5e074-690a-46d7-83c8-8d4e3d3d0715", "trust_enabled": false, "tag_expiration_s": 1209600, "is_free_account": true, "state": "NORMAL", "tags": {"example": {"name": "example", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "test": {"name": "test", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}}, "can_write": true, "can_admin": true}
または、
GET /api/v1/repository/{repository}/tag/
エンドポイントを使用することもできます。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/
出力例
{"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737029, "end_ts": 1718737153, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:57:09 -0000", "expiration": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737018, "end_ts": 1718737029, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:56:58 -0000", "expiration": "Tue, 18 Jun 2024 18:57:09 -0000"}, {"name": "sample_tag", "reversion": false, "start_ts": 1718736147, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:42:27 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1717680780, "end_ts": 1718737018, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000", "expiration": "Tue, 18 Jun 2024 18:56:58 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}
7.3. UI を使用してイメージに新しいイメージタグを追加する
Red Hat Quay のイメージに新しいタグを追加できます。
手順
- Red Hat Quay v2 UI ダッシュボードのナビゲーションペインで Repositories をクリックします。
- イメージタグのあるリポジトリーの名前をクリックします。
- 縦の省略記号メニューをクリックし、Add new tag をクリックします。
タグの名前を入力し、Create tag をクリックします。
新しいタグが Repository Tags ページにリストされます。
7.4. API を使用してイメージに新しいタグを追加する
API を使用して、イメージに新しいタグを追加したり、古いタグを復元したりできます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
PUT /api/v1/repository/{repository}/tag/{tag}
コマンドを使用すると、タグが参照するイメージを変更するか、新しいタグを作成できます。$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "manifest_digest": "<manifest_digest>" }' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
出力例
"Updated"
POST /api/v1/repository/{repository}/tag/{tag}/restore
コマンドを使用すると、リポジトリータグを以前のイメージに復元できます。以下に例を示します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "manifest_digest": <manifest_digest> }' \ quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore
出力例
{}
新しいタグを作成した後にタグのリストを表示するには、
GET /api/v1/repository/{repository}/tag/
コマンドを使用します。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
出力例
{"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
7.5. UI を使用してラベルを追加および管理する
管理者は、次の手順を使用してタグのラベルを追加および管理できます。
手順
- v2 UI ダッシュボードのナビゲーションペインで Repositories をクリックします。
- イメージタグのあるリポジトリーの名前をクリックします。
- イメージの縦の省略記号メニューをクリックし、Edit labels を選択します。
- Edit labels ウィンドウで、Add new label をクリックします。
key=value
形式を使用してイメージタグのラベルを入力します (例:com.example.release-date=2023-11-14
)。注記key=value
形式の使用に失敗すると、Invalid label format, must be key value separated by =
というエラーが返されます。- 空白のボックスをクリックしてラベルを追加します。
- オプション: 2 番目のラベルを追加します。
-
Save labels をクリックして、ラベルをイメージタグに保存します。
Created labels successfully
という通知が返されます。 - オプション: 同じイメージタグの縦の省略記号メニュー→ Edit labels → ラベルの X をクリックして削除します。または、テキストを編集することもできます。Save labels をクリックします。これでラベルが削除または編集されました。
7.6. API を使用してラベルを追加および管理する
Red Hat Quay 管理者は、以下の手順を使用して、API を使用してタグのラベルを追加および管理できます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
リポジトリー内にある特定のマニフェストの詳細を取得するには、
GET /api/v1/repository/{repository}/manifest/{manifestref}
コマンドを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>
特定のマニフェストのラベルのリストを取得するには、
GET /api/v1/repository/{repository}/manifest/{manifestref}/labels
コマンドを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels
出力例
{"labels": [{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}, {"id": "2d34ec64-4051-43ad-ae06-d5f81003576a", "key": "org.opencontainers.image.version", "value": "1.36.1-glibc", "source_type": "manifest", "media_type": "text/plain"}]}
特定のマニフェストに関する情報を取得するには、
GET /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid}
コマンドを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<label_id>
出力例
{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}
特定のリポジトリー内のマニフェストに追加のラベルを追加するには、
POST /api/v1/repository/{repository}/manifest/{manifestref}/labels
コマンドを使用します。以下に例を示します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "key": "<key>", "value": "<value>", "media_type": "<media_type>" }' \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels
出力例
{"label": {"id": "346593fd-18c8-49db-854f-4cb1fb76ff9c", "key": "example-key", "value": "example-value", "source_type": "api", "media_type": "text/plain"}}
ラベルを削除するには、
DELETE /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid}
コマンド (https://docs.redhat.com/en/documentation/red_hat_quay/3/html-single/red_hat_quay_api_guide/index#deletemanifestlabel) を使用します。$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<labelid>
このコマンドは CLI に出力を返しません。上記のコマンドのいずれかを使用して、正常に削除されたことを確認できます。
7.7. タグの有効期限を設定する
タグの有効期限 機能を使用すると、選択した日時に Red Hat Quay リポジトリーのイメージタグが期限切れになるように設定できます。この機能には次の特徴があります。
- イメージタグの有効期限が切れると、そのタグがリポジトリーから削除されます。特定のイメージに対する最後のタグであれば、そのイメージも削除するように設定されます。
- 有効期限はタグごとに設定されます。リポジトリー全体に対して設定されるものではありません。
- タグは期限切れになったり、削除されたりしても、レジストリーからすぐには削除されません。これは、タイムマシン 機能で設計された割り当て時間によって決まります。この時間により、タグを完全に削除するタイミング、またはガベージコレクションを行うタイミングが定義されます。デフォルトでは、この値は 14 日 に設定されていますが、管理者は複数のオプションから 1 つ選択することで、この時間を調整できます。ガベージコレクションが発生するまでは、タグの変更を元に戻すことができます。
Red Hat Quay のスーパーユーザーには、ユーザーリポジトリーからの期限切れイメージの削除に関する特別な権限はありません。スーパーユーザーがユーザーリポジトリーの情報を収集し、操作するための一元的なメカニズムはありません。有効期限やイメージ削除の管理は、各リポジトリーの所有者に委ねられています。
タグの有効期限は、次の 2 つの方法のいずれかで設定できます。
-
イメージの作成時に Dockerfile に
quay.expires-after=
ラベルを設定します。これは、イメージをビルドした時点からの有効期間を設定するものです。 Red Hat Quay UI で有効期限を選択する方法。以下に例を示します。
タグの有効期限を設定すると、古いタグや未使用のタグのクリーンアップを自動化できるため、ストレージ容量を削減できます。
7.7.1. リポジトリーからタグの有効期限を設定する
手順
- Red Hat Quay v2 UI ダッシュボードのナビゲーションペインで Repositories をクリックします。
- イメージタグのあるリポジトリーの名前をクリックします。
- イメージの縦の省略記号メニューをクリックし、Change expiration を選択します。
- オプション: または、複数のタグのボックスをクリックし、Actions → Set expiration を選択して有効期限を一括追加することもできます。
-
Change Tags Expiration ウィンドウで、曜日、月、日、年を指定して有効期限を設定します。たとえば、
Wednesday, November 15, 2023
に設定します。または、カレンダーボタンをクリックして日付を手動で選択することもできます。 -
時刻を
2:30 PM
などに設定します。 -
Change Expiration をクリックして日付と時刻を確認します。
Successfully set expiration for tag test to Nov 15, 2023, 2:26 PM
という通知が返されます。 Red Hat Quay v2 UI の Tags ページで、タグの有効期限の設定を確認できます。以下に例を示します。
7.7.2. Dockerfile からタグの有効期限を設定する
docker label
コマンドを使用してイメージタグにラベル (例: quay.expires-after=20h
) を追加すると、指定時間の経過後にタグが自動的に期限切れになります。以下に示す時間、日、または週の値を指定できます。
-
1h
-
2d
-
3w
有効期限は、イメージがレジストリーにプッシュされた時点から始まります。
手順
次の
docker label
コマンドを入力し、目的のイメージタグにラベルを追加します。タグが 20 時間後に期限切れになるよう指定するには、ラベルをquay.expires-after=20h
という形式にします。20h は希望の有効期限に置き換えます。以下に例を示します。$ docker label quay.expires-after=20h quay-server.example.com/quayadmin/<image>:<tag>
7.7.3. API を使用してタグの有効期限を設定する
API を使用してイメージタグの有効期限を設定できます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
PUT /api/v1/repository/{repository}/tag/{tag}
コマンドを使用して有効期限フィールドを渡すことで、イメージのタグの有効期限を設定できます。$ curl -X PUT \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "manifest_digest": "<manifest_digest>" }' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
出力例
"Updated"
7.8. タグやダイジェストによるイメージの取得
Red Hat Quay では、Docker クライアントと Podman クライアントを使用して、複数の方法でイメージをプルできます。
手順
- リポジトリーの Tags ページに移動します。
- Manifest で、Fetch Tag アイコンをクリックします。
ポップアップボックスが表示され、次のオプションが表示されます。
- Podman Pull (by tag)
- Docker Pull (by tag)
- Podman Pull (by digest)
Docker Pull (by digest)
4 つのオプションのいずれかを選択すると、イメージのプルに使用できる各クライアント用のコマンドが返されます。
Copy Command をクリックしてコマンドをコピーします。このコマンドはコマンドラインインターフェイス (CLI) で使用できます。以下に例を示します。
$ podman pull quay-server.example.com/quayadmin/busybox:test2
7.9. UI を使用して Red Hat Quay のタグ履歴を表示する
Red Hat Quay では、イメージとそれぞれのイメージタグの包括的な履歴を確認できます。
手順
- Red Hat Quay v2 UI ダッシュボードのナビゲーションペインで Repositories をクリックします。
- イメージタグのあるリポジトリーの名前をクリックします。
Tag History をクリックします。このページでは、次の操作を実行できます。
- タグ名での検索
- 日付範囲の選択
- タグの変更の表示
- タグの変更日と変更時刻の表示
7.10. API を使用して Red Hat Quay のタグ履歴を表示する
Red Hat Quay では、イメージとそれぞれのイメージタグの包括的な履歴を確認できます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次のコマンドを入力し、
GET /api/v1/repository/{repository}/tag/
コマンドを使用して次のいずれかのクエリーを渡して、タグ履歴を表示します。- onlyActiveTags=<true/false>: アクティブなタグだけに対象を絞り込みます。
- page=<number>: 取得する結果のページ番号を指定します。
- limit=<number>: ページあたりの結果数を制限します。
specificTag=<tag_name>: 対象とするタグを、指定した名前のタグだけに絞り込みます。
$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/tag/?onlyActiveTags=true&page=1&limit=10"
出力例
{"tags": [{"name": "test-two", "reversion": false, "start_ts": 1717680780, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}
specificTag=<tag_name>
クエリーを使用すると、特定のタグだけに結果を絞り込むことができます。以下に例を示します。$ curl -X GET -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" -H "Accept: application/json" "quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/?onlyActiveTags=true&page=1&limit=20&specificTag=test-two"
出力例
{"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}], "page": 1, "has_additional": false}
7.11. イメージタグの削除
イメージタグを削除すると、その特定のバージョンのイメージがレジストリーから削除されます。
イメージタグを削除するには、次の手順を実行します。
手順
-
v2 UI の Repositories ページで、削除するイメージの名前 (
quay/admin/busybox
など) をクリックします。 - More Actions ドロップダウンメニューをクリックします。
Delete をクリックします。
注記必要に応じて、Make Public または Make Private をクリックできます。
- ボックスに confirm と入力してから、Delete をクリックします。
削除後、Repositories ページに戻ります。
注記イメージタグの削除は、タイムマシン 機能に割り当てられている時間に基づいて元に戻すことができます。詳細は、「タグの変更を元に戻す」を参照してください。
7.12. API を使用してイメージを削除する
API を使用して古いイメージタグを削除できます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
DELETE /api/v1/repository/{repository}/tag/{tag}
コマンドを使用すると、イメージタグを削除できます。$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>
このコマンドは CLI に出力を返しません。タグのリストを返すには、次のステップに進みます。
タグを削除した後にタグのリストを表示するには、
GET /api/v1/repository/{repository}/tag/
コマンドを使用します。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
出力例
{"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
7.13. UI を使用してタグの変更を元に戻す
Red Hat Quay は、古いイメージタグを一定期間リポジトリーに保持できる包括的な タイムマシン 機能を備えており、タグに加えられた変更を元に戻すことができます。この機能を使用すると、タグの削除などのタグの変更を元に戻すことができます。
手順
- v2 UI の Repositories ページで、元に戻すイメージの名前をクリックします。
- Tag History タブをクリックします。
- タイムライン内でイメージタグが変更または削除された時点を見つけます。次に、Revert の下のオプションをクリックして、タグをイメージに戻します。
7.14. API を使用してタグの変更を元に戻す
Red Hat Quay は、古いイメージタグを一定期間リポジトリーに保持できる包括的な タイムマシン 機能を備えており、タグに加えられた変更を元に戻すことができます。この機能を使用すると、タグの削除などのタグの変更を元に戻すことができます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
POST /api/v1/repository/{repository}/tag/{tag}/restore
コマンドを使用すると、リポジトリータグを以前のイメージに復元できます。以下に例を示します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "manifest_digest": <manifest_digest> }' \ quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore
出力例
{}
古いタグを復元した後にタグのリストを表示するには、
GET /api/v1/repository/{repository}/tag/
コマンドを使用します。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag
出力例
{"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}
第8章 ログの表示とエクスポート
アクティビティーログは、Red Hat Quay のすべてのリポジトリーおよび名前空間について収集されます。
Red Hat Quay の使用状況ログを表示すると、運用とセキュリティーの両方の目的で貴重な洞察と利点を得ることができます。使用状況ログから次の情報が明らかになる可能性があります。
- リソースプランニング: 使用状況ログは、イメージのプル、プッシュの数、レジストリーへの全体的なトラフィックに関するデータを提供します。
- ユーザーアクティビティー: ログを使用すると、ユーザーアクティビティーを追跡し、どのユーザーがレジストリー内のイメージにアクセスして操作しているかを把握できます。これは、監査、ユーザー行動の理解、アクセス制御の管理に役立ちます。
- 使用パターン: 使用パターンを調査することで、よく使用されるイメージ、頻繁に使用されるバージョン、ほとんどアクセスされないイメージについて詳細な情報を得ることができます。この情報は、イメージのメンテナンスとクリーンアップの作業に優先順位を付けるのに役立ちます。
- セキュリティー監査: 使用状況ログにより、誰がいつイメージにアクセスしたかを追跡できます。これは、セキュリティー監査、コンプライアンス、および不正または不審なアクティビティーの調査にとって非常に重要です。
- イメージのライフサイクル管理: ログにより、どのイメージがプル、プッシュ、削除されているかが明らかになります。この情報は、古いイメージを廃止し、許可されたイメージだけを確実に使用させるなど、イメージのライフサイクル管理に不可欠です。
- コンプライアンスと規制要件: 多くの業界には、機密リソースへのアクセスの追跡と監査を義務付けるコンプライアンス要件があります。使用状況ログは、そのような規制への準拠を証明するのに役立ちます。
- 異常な動作の特定: 使用状況ログ内の正常でないパターンや異常なパターンは、潜在的なセキュリティー違反または悪意のあるアクティビティーを示している可能性があります。このログを監視すると、セキュリティーインシデントをより効果的に検出して対応することができます。
- 傾向分析: 使用状況ログは、レジストリーがどのように使用されているかに関する経時的な傾向と詳細情報を提供します。これは、リソースの割り当て、アクセス制御、イメージ管理戦略について、情報に基づいた意思決定を行うのに役立ちます。
ログファイルにアクセスする方法は、以下のように複数あります。
- Web UI によりログを閲覧する
- 外部に保存できるようにログをエクスポートする
- API を使用してログエントリーへのアクセスする
ログにアクセスするには、選択したリポジトリーまたは名前空間の管理者権限が必要です。
API を介して一度に利用できるログ結果は最大 100 件です。それ以上の結果を集めるには、この章で紹介するログエクスポーター機能を使う必要があります。
8.1. 使用ログの表示
ログは、レジストリーの使用方法に関する有用な情報を提供します。ログは、以下の手順を使用して v2 UI の組織、リポジトリー、または名前空間で表示できます。
手順
- Red Hat Quay レジストリーにログインします。
- 自分が管理者である組織、リポジトリーまたは名前空間に移動します。
Logs をクリックします。
- オプション: From ボックスと To ボックスに日付を追加して、ログエントリーを表示する日付範囲を設定します。
-
オプション: Export をクリックして、ログをエクスポートします。
http://
またはhttps://
で始まるメールアドレスまたは有効なコールバック URL を入力する必要があります。このプロセスは、ログの数に応じて 1 時間かかる場合があります。
8.2. API を使用した使用状況ログの表示す
API を使用して、組織またはリポジトリー別にログを表示できます。ログは、集約 (グループ化) したり、より詳細にリスト表示したりすることもできます。ユーザー別、特定の日付範囲別、またはページ別に表示することもできます。
8.2.1. 集約されたログの表示
集約されたログは、組織、リポジトリー、特定のユーザー、または現在のユーザー別に表示できます。結果をフィルタリングするために、performer
、starttime/endtime
、next_page
などのオプションのコマンドを渡すこともできます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
現在のユーザーの集約された (またはグループ化された) ログを返すには、
GET /api/v1/user/aggregatelogs
API エンドポイントを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "https://<quay-server.example.com>/api/v1/user/aggregatelogs"
出力例
{"aggregated": [{"kind": "create_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "manifest_label_add", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "push_repo", "count": 2, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}, {"kind": "revert_tag", "count": 1, "datetime": "Tue, 18 Jun 2024 00:00:00 -0000"}]}
また、
performer
とstarttime/endtime
クエリーを渡して、特定期間における特定のユーザーの集約されたログを取得することもできます。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/user/aggregatelogs?performer=<username>&starttime=<MM/DD/YYYY>&endtime=<MM/DD/YYYY>"
集約されたログは、
GET /api/v1/organization/{orgname}/aggregatelogs
を使用して組織別に表示することもできます。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/organization/{orgname}/aggregatelogs"
集約されたログは、
GET /api/v1/repository/{repository}/aggregatelogs
コマンドを使用してリポジトリー別に表示することもできます。次の例には、starttime/endtime
フィールドが含まれています。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "<quay-server.example.com>/api/v1/repository/<repository_name>/<namespace>/aggregatelogs?starttime=2024-01-01&endtime=2024-06-18""
8.2.2. 詳細なログの表示
詳細なログは、組織、リポジトリー、特定のユーザー、または現在のユーザー別に表示できます。結果をフィルタリングするために、performer
、starttime/endtime
、next_page
などのオプションのフィールドを渡すこともできます。
手順
ユーザーのログエントリーのリストを返すには、
GET /api/v1/user/logs
API エンドポイントを使用します。以下に例を示します。$ curl -X GET -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" -H "Accept: application/json" "quay-server.example.com/api/v1/user/logs"
また、
performer
とstarttime/endtime
クエリーを渡して、特定期間における特定のユーザーのログを取得することもできます。以下に例を示します。$ curl -X GET -H "Authorization: Bearer lfV4lVf9qRsyoFnrgEno1umIOrsdp8lPyMnfUDYY" -H "Accept: application/json" "http://quay-server.example.com/api/v1/user/logs?performer=quayuser&starttime=01/01/2024&endtime=06/18/2024"
出力例
--- {"start_time": "Mon, 01 Jan 2024 00:00:00 -0000", "end_time": "Wed, 19 Jun 2024 00:00:00 -0000", "logs": [{"kind": "revert_tag", "metadata": {"username": "quayuser", "repo": "busybox", "tag": "test-two", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "ip": "192.168.1.131", "datetime": "Tue, 18 Jun 2024 18:59:13 -0000", "performer": {"kind": "user", "name": "quayuser", "is_robot": false, "avatar": {"name": "quayuser", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, {"kind": "push_repo", "metadata": {"repo": "busybox", "namespace": "quayuser", "user-agent": "containers/5.30.1 (github.com/containers/image)", "tag": "test-two", "username": "quayuser", } ---
指定した組織のログを返すには、
GET /api/v1/organization/{orgname}/logs
エンドポイントを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "http://<quay-server.example.com>/api/v1/organization/{orgname}/logs"
指定したリポジトリーのログを返すには、
GET /api/v1/repository/{repository}/logs
エンドポイントを使用します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "http://<quay-server.example.com>/api/v1/repository/{repository}/logs"
8.3. UI を使用したリポジトリーログのエクスポート
Export Logs 機能を使用すると、より多くのログファイルを取得し、Red Hat Quay データベースの外部に保存できます。この機能には次の利点と制約があります。
- リポジトリーから収集するログの日付の範囲を選択できます。
- ログをメールの添付ファイルで送信するか、コールバック URL に移動することを要求できます。
- ログをエクスポートするには、リポジトリーまたは名前空間の管理者である必要があります。
- すべてのユーザーのログが 30 日分保持されます。
- Export Logs 機能は、過去に生成されたログデータのみを収集します。ログ取得中のデータのストリーミングは行いません。
- この機能を使用するには、Red Hat Quay インスタンスを外部ストレージ用に設定する必要があります。ローカルストレージはログのエクスポートには使用できません。
- ログが収集されて利用可能になったら、そのデータを保存する場合は、すぐにコピーする必要があります。デフォルトでは、データは 1 時間後に期限切れになります。
ログをエクスポートするには、次の手順を実行します。
手順
- 管理者権限のあるリポジトリーを選択します。
- Logs タブをクリックします。
- オプション: 特定の日付を指定する場合は、From ボックスと to ボックスに範囲を入力します。
Export Logs ボタンをクリックします。以下のような Export Usage Logs のポップアップが表示されます。
- エクスポートされたログを受信するメールアドレスまたはコールバック URL を入力します。コールバック URL には、指定ドメインへの URL (例: <webhook.site>) を使用できます。
- Confirm を選択して、選択したログエントリーを収集するプロセスを開始します。収集されるログデータの量に応じて、これが完了するまでに数分から数時間かかる場合があります。
ログのエクスポートが完了すると、次の 2 つのイベントのいずれかが発生します。
- 要求したエクスポート済みログエントリーが利用可能であることを通知するメールが受信されます。
- webhook URL からのログエクスポート要求の成功ステータスが返されます。さらに、エクスポートされたデータへのリンクを使用して、ログをダウンロードできるようになります。
URL は Red Hat Quay 外部ストレージ内の場所を指しており、1 時間以内に期限切れになるように設定されています。ログを保持する場合は、エクスポートされたログを有効期限が切れる前に必ずコピーしてください。
8.4. API を使用したログのエクスポート
詳細なログは、コールバック URL またはメールアドレスにエクスポートできます。
前提条件
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
現在のユーザーのログをエクスポートするには、
POST /api/v1/user/exportlogs
エンドポイントを使用します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "<MM/DD/YYYY>", "endtime": "<MM/DD/YYYY>", "callback_email": "your.email@example.com" }' \ "http://<quay-server.example.com>/api/v1/user/exportlogs"
出力例
{"export_id": "6a0b9ea9-444c-4a19-9db8-113201c38cd4"}
組織のログをエクスポートするには、
POST /api/v1/organization/{orgname}/exportlogs
エンドポイントを使用します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "<MM/DD/YYYY>", "endtime": "<MM/DD/YYYY>", "callback_email": "org.logs@example.com" }' \ "http://<quay-server.example.com>/api/v1/organization/{orgname}/exportlogs"
リポジトリーのログをエクスポートするには、
POST /api/v1/repository/{repository}/exportlogs
エンドポイントを使用します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "starttime": "2024-01-01", "endtime": "2024-06-18", "callback_url": "http://your-callback-url.example.com" }' \ "http://<quay-server.example.com>/api/v1/repository/{repository}/exportlogs"
第9章 Clair セキュリティースキャン
Clair セキュリティースキャナーは、デフォルトでは Red Hat Quay に対して有効になっていません。Clair を有効にするには、Red Hat Quay の Clair を参照してください。
Clair セキュリティースキャンは、UI または API で表示できます。
手順
- リポジトリーに移動し、ナビゲーションペインで Tags をクリックします。このページに、セキュリティースキャンの結果が表示されます。
- マルチアーキテクチャーイメージに関する詳細情報を表示するには、See Child Manifests をクリックして、展開されたビューでマニフェストのリストを確認します。
- See Child Manifests の下の関連リンクをクリックします。たとえば、1 Unknown をクリックすると、Security Scanner ページにリダイレクトされます。
- Security Scanner ページには、イメージがどの CVE の影響を受けるか、利用可能な修復オプションなど、タグに関する情報が表示されます。
イメージスキャンでは、Clair セキュリティースキャナーによって検出された脆弱性がリストされるだけです。発見された脆弱性への対処は、当該ユーザーに委ねられています。Red Hat Quay のスーパーユーザーが発見された脆弱性に対処することはありません。
9.1. UI を使用した Clair セキュリティースキャンの表示
Clair セキュリティースキャンは UI で表示できます。
手順
- リポジトリーに移動し、ナビゲーションペインで Tags をクリックします。このページに、セキュリティースキャンの結果が表示されます。
- マルチアーキテクチャーイメージに関する詳細情報を表示するには、See Child Manifests をクリックして、展開されたビューでマニフェストのリストを確認します。
- See Child Manifests の下の関連リンクをクリックします。たとえば、1 Unknown をクリックすると、Security Scanner ページにリダイレクトされます。
- Security Scanner ページには、イメージがどの CVE の影響を受けるか、利用可能な修復オプションなど、タグに関する情報が表示されます。
イメージスキャンでは、Clair セキュリティースキャナーによって検出された脆弱性がリストされるだけです。発見された脆弱性への対処は、当該ユーザーに委ねられています。Red Hat Quay のスーパーユーザーが発見された脆弱性に対処することはありません。
9.2. UI を使用した Clair セキュリティースキャンの表示
API を使用して Clair セキュリティースキャンを表示できます。
手順
リポジトリー内の特定のマニフェストに関するセキュリティー情報を取得するには、
GET /api/v1/repository/{repository}/manifest/{manifestref}/security
エンドポイントを使用します。以下に例を示します。$ curl -X GET \ -H "Authorization: Bearer <bearer_token>" \ -H "Accept: application/json" \ "https://quay-server.example.com/api/v1/repository/<namespace>/<repository>/manifest/<manifest_digest>/security?vulnerabilities=<true_or_false>"
出力例
{"status": "queued", "data": null}
第10章 通知の概要
Red Hat Quay では、リポジトリーのライフサイクルで発生するさまざまなイベントの 通知 をリポジトリーに追加できます。
10.1. 通知アクション
通知は Events and Notifications ページの Repository Settings セクションに追加されます。通知は Notifications ウィンドウにも追加されます。このウィンドウは Red Hat Quay のナビゲーションペインにある ベル アイコンをクリックすると表示されます。
Red Hat Quay の通知は、ユーザー、チーム、または組織 全体に送信するように設定できます。
メール通知
指定のイベントを説明するメールが、指定のアドレスに送信されます。メールアドレスは リポジトリーごとに 認証する必要があります。
Webhook POST 通知
HTTP POST
呼び出しは、イベントのデータを使用して、指定の URL に対して行われます。イベントデータの詳細は、「リポジトリーイベントの説明」を参照してください。
URL が HTTPS の場合、呼び出しには Red Hat Quay の SSL クライアント証明書が設定されます。この証明書を検証することで、Red Hat Quay からの呼び出しが証明されます。ステータスコードが 2xx
の範囲の応答は成功とみなされます。それ以外のステータスコードを持つ応答は失敗とみなされ、webhook 通知が再試行されます。
Flowdock 通知
Flowdock にメッセージを投稿します。
Hipchat 通知
HipChat にメッセージを投稿します。
Slack 通知
Slack にメッセージを投稿します。
10.2. UI を使用した通知の作成
通知を追加するには、次の手順を実行します。
前提条件
- リポジトリーが作成済みである。
- リポジトリーの管理者権限がある。
手順
- Red Hat Quay のリポジトリーに移動します。
- ナビゲーションペインで、Settings をクリックします。
- Events and Notifications カテゴリーで、Create Notification をクリックして、リポジトリーイベントの新しい通知を追加します。Create notification ポップアップボックスが表示されます。
Create repository ポップアップボックスで、When this event occurs ボックスをクリックしてイベントを選択します。次のタイプのイベントの通知を選択できます。
- リポジトリーへのプッシュ
- イメージビルドの失敗
- イメージビルドのキューへの追加
- イメージビルドの開始
- イメージビルドの成功
- イメージビルドのキャンセル
- イメージの有効期限トリガー
イベントの種類を選択したら、通知方法を選択します。次の方法を使用できます。
- Quay 通知
- メール通知
- Webhook POST
- Flowdock チーム通知
- HipChat ルーム通知
Slack 通知
選択した方法に応じて、追加情報を入力する必要があります。たとえば、E-mail を選択した場合は、メールアドレスと通知タイトル (省略可能) を入力する必要があります。
- イベントと通知方法を選択したら、Create Notification をクリックします。
10.2.1. イメージ有効期限の通知の作成
イメージ有効期限イベントのトリガーは、メール、Slack、Webhook などを通じてユーザーに通知するように設定でき、リポジトリーレベルで設定できます。トリガーは、任意の日数経過後に有効期限が切れるイメージに対して設定でき、自動プルーニング機能と連携して動作できます。
イメージの有効期限通知は、Red Hat Quay v2 UI か、createRepoNotification
API エンドポイントを使用して設定できます。
前提条件
-
FEATURE_GARBAGE_COLLECTION: true
がconfig.yaml
ファイルで設定されている。 -
オプション:
FEATURE_AUTO_PRUNE: true
がconfig.yaml
ファイルで設定されている。
手順
- Red Hat Quay v2 UI で、Repositories をクリックします。
- リポジトリーの名前を選択します。
- Settings → Events and notifications をクリックします。
- Create notification をクリックします。Create notification ポップアップボックスが表示されます。
- Select event… ボックスをクリックし、Image expiry trigger をクリックします。
-
When the image is due to expiry in days ボックスに、イメージの有効期限の何日前にアラートを受け取るかを入力します。たとえば、1 日の場合は
1
を使用します。 Select method… ボックスで、次のいずれかをクリックします。
- メール
- Webhook POST
- Flowdock チーム通知
- HipChat ルーム通知
- Slack 通知
-
選択した方法に応じて、必要なデータを入力します。たとえば、Webhook POST を選択した場合は、
Webhook URL
を入力します。 - オプション: POST JSON body template を指定します。
- オプション: 通知の Title を入力します。
- Submit をクリックします。Events and notifications ページに戻ると、通知が表示されます。
オプション: config.yaml ファイルで
NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES
変数を設定できます。このフィールドを設定すると、有効期限が切れるイメージがある場合に通知が自動的に送信されます。デフォルトでは300
(5 時間) に設定されていますが、必要に応じて調整できます。NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES: 300 1
- 1
- デフォルトでは、このフィールドは
300
、つまり 5 時間に設定されています。
検証
縦の省略記号メニュー→ Test Notification をクリックします。次のメッセージが返されます。
Test Notification Queued A test version of this notification has been queued and should appear shortly
選択した方法に応じて、メール、Webhook アドレス、Slack チャネルなどを確認します。送信される情報は次の例のようになります。
{ "repository": "sample_org/busybox", "namespace": "sample_org", "name": "busybox", "docker_url": "quay-server.example.com/sample_org/busybox", "homepage": "http://quay-server.example.com/repository/sample_org/busybox", "tags": [ "latest", "v1" ], "expiring_in": "1 days" }
10.3. API を使用した通知の作成
通知を追加するには、次の手順を実行します。
前提条件
- リポジトリーが作成済みである。
- リポジトリーの管理者権限がある。
- OAuth アクセストークンを作成 した。
-
config.yaml
ファイルでBROWSER_API_CALLS_XHR_ONLY: false
を設定した。
手順
次の
POST /api/v1/repository/{repository}/notification
コマンドを入力し、リポジトリーに関する通知を作成します。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "event": "<event>", "method": "<method>", "config": { "<config_key>": "<config_value>" }, "eventConfig": { "<eventConfig_key>": "<eventConfig_value>" } }' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/
このコマンドは CLI に出力を返しません。次の
GET /api/v1/repository/{repository}/notification/{uuid}
コマンドを入力すると、リポジトリー通知に関する情報を取得できます。{"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0}
次の
POST /api/v1/repository/{repository}/notification/{uuid}/test
コマンドを入力すると、リポジトリー通知をテストできます。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test
出力例
{}
次の
POST /api/v1/repository/{repository}/notification/{uuid}
コマンドを入力すると、リポジトリー通知の失敗を 0 にリセットできます。$ curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>
リポジトリー通知を削除するには、次の
DELETE /api/v1/repository/{repository}/notification/{uuid}
コマンドを入力します。$ curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid>
このコマンドは CLI に出力を返しません。次の
GET /api/v1/repository/{repository}/notification/{uuid}
コマンドを入力すると、すべての通知のリストを取得できます。$ curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/
出力例
{"notifications": []}
10.4. リポジトリーイベントの説明
次のセクションでは、リポジトリーイベントについて詳しく説明します。
リポジトリープッシュ
1 つまたは複数のイメージのリポジトリーへのプッシュが成功しました。
{ "name": "repository", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "homepage": "https://quay.io/repository/dgangaia/repository", "updated_tags": [ "latest" ] }
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" }
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" }
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" ], "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" ] }
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" }
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" }
脆弱性の検出
次の例は、リポジトリーで脆弱性を検出した Dockerfile ビルドからの応答です。
{ "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 } }
第11章 ビルドワーカーを使用した Dockerfile の自動ビルド
Red Hat Quay は、OpenShift または Kubernetes 上のワーカーノードのセットを使用した Dockerfile のビルドをサポートしています。GitHub webhook などのビルドトリガーを設定することで、新しいコードがコミットされたときに自動的に新しいバージョンのリポジトリーを構築できます。
このドキュメントでは、Red Hat Quay インストールでビルドを有効にし、Red Hat Quay からのビルドを受け入れるように OpenShift Container Platform または Kubernetes クラスターをもう 1 つセットアップする方法を説明します。
11.1. OpenShift Container Platform を使用した Red Hat Quay ビルダーのセットアップ
Red Hat Quay ビルダーを OpenShift Container Platform で使用する前に、事前設定する必要があります。
11.1.1. OpenShift Container Platform TLS コンポーネントの設定
tls
コンポーネントを使用すると、TLS 設定を制御できます。
TLS コンポーネントが Red Hat Quay Operator によって管理されている場合、Red Hat Quay は Builders をサポートしません。
tls
を unmanaged
に設定する場合は、独自の ssl.cert
ファイルと ssl.key
ファイルを提供します。このとき、クラスターで Builder をサポートする場合は、Quay
ルート名と Builder ルート名の両方を証明書の SAN リストに追加する必要があります。あるいは、ワイルドカードを使用することもできます。
ビルダールートを追加するには、次の形式を使用します。
[quayregistry-cr-name]-quay-builder-[ocp-namespace].[ocp-domain-name]
11.1.2. Red Hat Quay ビルダー用の OpenShift Container Platform の準備
次の手順を使用して、OpenShift Container Platform 用に Red Hat Quay ビルダーを準備します。
前提条件
- OpenShift Container Platform TLS コンポーネントが設定されている。
手順
次のコマンドを入力して、ビルドを実行するプロジェクト (
builder
など) を作成します。$ oc new-project builder
次のコマンドを入力して、
builder
namespace に新しいServiceAccount
を作成します。$ oc create sa -n builder quay-builder
次のコマンドを入力して、
builder
namespace 内のedit
ロールをユーザーに付与します。$ oc policy add-role-to-user -n builder edit system:serviceaccount:builder:quay-builder
次のコマンドを入力して、
builder
namespace のquay-builder
サービスアカウントに関連付けられたトークンを取得します。このトークンは、OpenShift Container Platform クラスターの API サーバーの認証と対話に使用されます。$ oc sa get-token -n builder quay-builder
- OpenShift Container Platform クラスターの API サーバーの URL を特定します。これは、OpenShift Container Platform Web コンソールで確認できます。
ビルド
jobs
をスケジュールするときに使用するワーカーノードラベルを特定します。ビルド pods はベアメタルのワーカーノードで実行する必要があるため、通常、これらは特定のラベルで識別されます。どのノードラベルを使用すべきかは、クラスター管理者に確認してください。
オプション: クラスターが自己署名証明書を使用している場合は、Kube API Server の認証局 (CA) を取得して Red Hat Quay の追加証明書に追加する必要があります。
次のコマンドを入力して、CA を含むシークレットの名前を取得します。
$ oc get sa openshift-apiserver-sa --namespace=openshift-apiserver -o json | jq '.secrets[] | select(.name | contains("openshift-apiserver-sa-token"))'.name
-
OpenShift Container Platform Web コンソールで、シークレットから
ca.crt
キーの値を取得します。値は "-----BEGIN CERTIFICATE-----"` で始まります。 -
CA を Red Hat Quay にインポートします。このファイルの名前が
K8S_API_TLS_CA
と一致することを確認します。
ServiceAccount
に対して次のSecurityContextConstraints
リソースを作成します。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
11.1.3. Red Hat Quay ビルダーの設定
Red Hat Quay ビルダーを有効にするには、次の手順を実行します。
手順
Red Hat Quay の
config.yaml
ファイルでビルドが有効になっていることを確認します。次に例を示します。FEATURE_BUILD_SUPPORT: True
以下の情報を Red Hat Quay の
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_certs/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
各設定フィールドの詳細は、を参照してください。
11.2. OpenShift Container Platform の ルート の制限事項
OpenShift Container Platform 上で Red Hat Quay Operator をマネージド route
コンポーネントとともに使用する場合、次の制限が適用されます。
- 現在、OpenShift Container Platform の ルート は、単一ポートへのトラフィックのみを処理できます。Red Hat Quay ビルドをセットアップするには追加の手順が必要です。
-
Red Hat Quay Operator がインストールされているクラスターで
kubectl
またはoc
CLI ツールが動作するように設定されていること、およびQuayRegistry
が存在することを確認します。QuayRegistry
は、Builders が実行されるのと同じベアメタルクラスター上にある必要はありません。 - こちらの手順 に従って、OpenShift クラスター上で HTTP/2 ingress が有効になっていることを確認します。
Red Hat Quay Operator は、既存の
Quay
Pod 内で実行されているビルドマネージャーサーバーに gRPC トラフィックを送信するRoute
リソースを作成します。カスタムホスト名、または<builder-registry.example.com>
などのサブドメインを使用する場合は、作成したRoute
リソースのstatus.ingress[0].host
を参照する DNS プロバイダーで CNAME レコードを作成してください。以下に例を示します。$ kubectl get -n <namespace> route <quayregistry-name>-quay-builder -o jsonpath={.status.ingress[0].host}
OpenShift Container Platform UI または CLI を使用して、
QuayRegistry
のspec.configBundleSecret
によって参照されるSecret
をビルドクラスター CA 証明書で更新します。キーにextra_ca_cert_build_cluster.cert
という名前を付けます。Red Hat Quay ビルダーの設定時に作成した Builder 設定で参照されている正しい値でconfig.yaml
ファイルのエントリーを更新し、BUILDMAN_HOSTNAME
CONFIGURATION FIELD を追加します。BUILDMAN_HOSTNAME: <build-manager-hostname> 1 BUILD_MANAGER: - ephemeral - ALLOWED_WORKER_COUNT: 1 ORCHESTRATOR_PREFIX: buildman/production/ JOB_REGISTRATION_TIMEOUT: 600 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 ...
- 1
- ビルドジョブがビルドマネージャーとの通信に使用する、外部からアクセス可能なサーバーのホスト名です。デフォルトは
SERVER_HOSTNAME
と同じです。OpenShiftRoute
の場合はstatus.ingress[0].host
、カスタムホスト名を使用している場合は CNAME エントリーのいずれかになります。BUILDMAN_HOSTNAME
にはポート番号を含める必要があります (たとえば、OpenShift Container Platform Route の場合はsomehost:443
)。これを省略すると、ビルドマネージャーとの通信に使用される gRPC クライアントがポートを推測しません。
11.3. ビルドのトラブルシューティング
ビルドマネージャーが起動した ビルダー インスタンスは、一時的なものです。これは、タイムアウトまたは失敗時に Red Hat Quay によってシャットダウンされるか、コントロールプレーン (EC2/K8s) によってガベージコレクションされることを意味します。ビルドログを取得するには、ビルドの実行中に取得する必要があります。
11.3.1. DEBUG 設定フラグ
DEBUG
フラグを true
に設定すると、完了または失敗後にビルダーのインスタンスがクリーンアップされるのを防ぐことができます。以下に例を示します。
EXECUTORS: - EXECUTOR: ec2 DEBUG: true ... - EXECUTOR: kubernetes DEBUG: true ...
true
に設定すると、デバッグ機能により、quay-builder
サービスの完了または失敗後にビルドノードがシャットダウンされなくなります。また、ビルドマネージャーが EC2 インスタンスを終了したり、Kubernetes ジョブを削除したりしてインスタンスをクリーンアップすることもなくなります。これにより、ビルダーノードの問題をデバッグできるようになります。
デバッグは実稼働サイクルでは設定しないでください。設定しても、ライフタイムサービスが残ります。そのため、たとえばインスタンスが約 2 時間後にシャットダウンします。これが発生すると、EC2 インスタンスが終了し、Kubernetes ジョブが完了します。
デバッグを有効にすると、終了していないインスタンスとジョブも実行中のワーカーの総数にカウントされるため、ALLOWED_WORKER_COUNT
にも影響します。そのため、ALLOWED_WORKER_COUNT
に達した場合、新しいビルドをスケジュールできるようにするには、既存のビルダーワーカーを手動で削除する必要があります。
DEBUG を設定すると、終了していないインスタンス/ジョブも実行中のワーカーの総数にカウントされるため、ALLOWED_WORKER_COUNT
にも影響します。このため、新しいビルドをスケジュールして、ALLOWED_WORKER_COUNT
に達した場合は、既存のビルダーワーカーを手動で削除する必要があります。
11.3.2. OpenShift Container Platform および Kubernetes ビルドのトラブルシューティング
OpenShift Container Platform Kubernetes ビルドのトラブルシューティングを行うには、次の手順を実行します。
手順
次のコマンドを入力して、ローカルマシンと OpenShift Container Platform クラスターまたは Kubernetes クラスターのいずれかで実行されている Pod の間にポート転送トンネルを作成します。
$ oc port-forward <builder_pod> 9999:2222
指定した SSH 鍵とポートを使用して、リモートホストへの SSH 接続を確立します。次に例を示します。
$ ssh -i /path/to/ssh/key/set/in/ssh_authorized_keys -p 9999 core@localhost
次のコマンドを入力して、
quay-builder
サービスログを取得します。$ systemctl status quay-builder
$ journalctl -f -u quay-builder
11.4. Github ビルドの設定
Github または Github Enterprise へのプッシュでビルドを行う場合は、GitHub での OAuth アプリケーションの作成 に進みます。
第12章 コンテナーイメージのビルド
コンテナーイメージをビルドするには、コンテナー化されたアプリケーションのブループリントを作成する必要があります。ブループリントは、アプリケーションのインストール方法と設定方法を定義する他のパブリックリポジトリーのベースイメージに依存します。
Red Hat Quay は、Docker および Podman コンテナーイメージをビルドする機能をサポートしています。この機能は、コンテナーとコンテナーオーケストレーションを利用する開発者や組織に役立ちます。
12.1. ビルドコンテキスト
Docker または Podman でイメージをビルドする際には、ビルドコンテキスト となるディレクトリーを指定します。これは手動ビルドとビルドトリガーの両方に当てはまります。Red Hat Quay によって作成されるビルドは、ローカルマシン上で docker build
または podman 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 のビルドコンテキストの一部です。そのため、Dockerfile を .dockerignore
ファイル内に含めることはできません。
12.2. ビルドトリガーのタグ命名
Red Hat Quay ではカスタムタグを使用できます。
1 つの方法として、ビルドした各イメージにタグとして割り当てる文字列を含める方法があります。または、ビルドトリガーの Configure Tagging セクションで次のタグテンプレートを使用して、各コミットからの情報でイメージにタグ付けすることもできます。
- ${commit}: 発行されたコミットの完全な SHA
- ${parsed_ref.branch}: ブランチ情報 (利用可能な場合)
- ${parsed_ref.tag}: タグ情報 (利用可能な場合)
- ${parsed_ref.remote}: リモート名
- ${commit_info.date}: コミットが発行された日付
- ${commit_info.author.username}: コミットの作成者のユーザー名
- ${commit_info.short_sha}: コミット SHA の最初の 7 文字
- ${committer.properties.username}: コミッターのユーザー名
以上がすべてではありませんが、これらはタグ付けに最も役立つタグテンプレートです。完全なタグテンプレートスキーマは、こちらのページ を参照してください。
詳細は、Set up custom tag templates in build triggers for Red Hat Quay and Quay.io を参照してください。
12.3. ソースコントロールをトリガーとしたビルドのスキップ
Red Hat Quay ビルドシステムがコミットを無視するように指定するには、コミットメッセージの任意の場所に [skip build]
または [build skip]
というテキストを追加します。
12.4. ビルドの表示および管理
リポジトリービルドは Red Hat Quay UI で表示および管理できます。
手順
- UI を使用して Red Hat Quay リポジトリーに移動します。
- ナビゲーションペインで、Builds を選択します。
12.5. 新しいビルドの作成
Red Hat Quay は、config.yaml
ファイルで FEATURE_BUILD_SUPPORT
が true
に設定されている限り、新しいビルドを作成できます。
前提条件
- リポジトリーの Builds ページに移動している。
-
config.yaml
ファイルでFEATURE_BUILD_SUPPORT
がtrue
に設定されている。
手順
- Builds ページで、Start New Build をクリックします。
- プロンプトが表示されたら、Upload Dockerfile をクリックして、ルートディレクトリーに Dockerfile または Dockerfile を含むアーカイブをアップロードします。
Start Build をクリックします。
注記- 現在、ユーザーは手動でビルドを開始するときに Docker ビルドコンテキストを指定できません。
- 現在、BitBucket は Red Hat Quay v2 UI ではサポートされていません。
- ビルドにリダイレクトされます。ビルドはリアルタイムで確認できます。Dockerfile ビルドが完了してプッシュされるまで待ちます。
- オプション: Download Logs をクリックしてログをダウンロードしたり、Copy Logs をクリックしてログをコピーしたりできます。
戻るボタンをクリックして Repository Builds ページに戻り、ビルド履歴を表示できます。
12.6. ビルドトリガー
ビルドトリガーは、ソースコントロールのプッシュ、Webhook 呼び出しの作成 など、トリガー条件が満たされるとビルドを呼び出します。
12.6.1. ビルドトリガーの作成
次の手順に従って、カスタム Git リポジトリーを使用してビルドトリガーを作成します。
以下の手順は、config.yaml
ファイルに Github 認証情報が含まれていないことを前提としています。
前提条件
- リポジトリーの Builds ページに移動している。
手順
- Builds ページで、Create Build Trigger をクリックします。
- Github、BitBucket、Gitlab などの目的のプラットフォームを選択するか、カスタム Git リポジトリーを使用します。この例では、Github のカスタム Git リポジトリーを使用しています。
-
カスタム Git リポジトリー名を入力します (例:
git@github.com:<username>/<repo>.git
)。Next をクリックします。 プロンプトが表示されたら、次のオプションのいずれかまたは両方を選択して、タグ付けオプションを設定します。
- Tag manifest with the branch or tag name。このオプションを選択すると、ビルドされたマニフェストにブランチの名前または git コミットのタグがタグ付けされます。
Add
latest
tag if on default branch。このオプションを選択すると、リポジトリーのデフォルトブランチでビルドが行われた場合に、ビルドされたマニフェストに latest がタグ付けされます。オプションで、カスタムのタグ付けテンプレートを追加できます。ここに入力できるタグテンプレートは複数あります。短い SHA ID、タイムスタンプ、作成者名、コミッター、コミットからのブランチ名をタグとして使用することもできます。詳細は、「ビルドトリガーのタグ命名」を参照してください。
タグ付けを設定したら、Next をクリックします。
- プロンプトが表示されたら、トリガーの呼び出し時にビルドする Dockerfile の場所を選択します。Dockerfile が git リポジトリーのルートにあり、Dockerfile という名前が付けられている場合は、Dockerfile パスとして /Dockerfile を入力します。Next をクリックします。
-
プロンプトが表示されたら、Docker ビルドのコンテキストを選択します。Dockerfile が Git リポジトリーのルートにある場合は、ビルドコンテキストディレクトリーとして
/
を入力します。Next をクリックします。 - オプション: 任意のロボットアカウントを選択します。これにより、ビルドプロセス中にプライベートのベースイメージをプルできます。プライベートベースイメージが使用されていないことを把握している場合は、この手順を省略できます。
- Next をクリックします。検証の警告がないか確認します。必要に応じて、Finish をクリックする前に問題を修正します。
トリガーが正常にアクティベートされたという警告が表示されます。このトリガーを使用するには、以下のアクションが必要になることに注意してください。
- 以下の公開鍵に git リポジトリーへの読み取りアクセス権を与える必要があります。
ビルドをトリガーするには、リポジトリーを
POST
に設定する必要があります。SSH 公開鍵を保存し、Return to <organization_name>/<repository_name> をクリックします。リポジトリーの Builds ページにリダイレクトされます。
Builds ページに、ビルドトリガーが表示されます。以下に例を示します。
12.6.2. ビルドの手動トリガー
次の手順を使用して、ビルドを手動でトリガーできます。
手順
- Builds ページで、Start new build をクリックします。
- プロンプトが表示されたら、Invoke Build Trigger を選択します。
Run Trigger Now をクリックして、プロセスを手動で開始します。
ビルドが開始したら、Repository Builds ページでビルド ID を確認できます。
12.7. カスタム Git トリガーの設定
カスタム Git トリガー は、Git サーバーをビルドトリガーとして機能させるための一般的な方法です。カスタム Git トリガーは SSH 鍵と webhook エンドポイントのみに依存します。それ以外の実装はユーザーに委ねられています。
12.7.1. トリガーの作成
カスタム Git トリガーの作成は、他のトリガーの作成と似ていますが、次の点が違います。
- Red Hat Quay は、トリガーで使用する適切なロボットアカウントを自動的に検出することはできません。これは、作成時に手動で行う必要があります。
- トリガーの作成後に追加の手順を実施する必要があります。この手順は、次のセクションで詳しく説明します。
12.7.2. カスタムトリガー作成の設定
カスタム Git トリガーを作成する場合は、次の 2 つの追加手順が必要です。
- トリガーの作成時に生成された SSH 公開鍵への読み取りアクセスを付与する必要があります。
- ビルドをトリガーする Red Hat Quay のエンドポイントに POST する webhook をセットアップする必要があります。
鍵と URL は、Settings または 歯車 アイコンから View Credentials を選択することで利用できます。
リポジトリーからのタグの表示および変更
12.7.2.1. SSH 公開鍵へのアクセス
Git サーバーの設定に応じて、Red Hat Quay がカスタム Git トリガー用に生成する SSH 公開鍵をインストールする方法はさまざまです。
たとえば、Git のドキュメント では、小規模なサーバーのセットアップを説明しています。この場合は、鍵を $HOME/.ssh/authorize_keys
に追加すると、ビルダーがリポジトリーをクローンするためのアクセス権が付与されます。公式にサポートされていない git リポジトリー管理ソフトウェアの場合は、通常、Deploy Keys というラベルが付いた、鍵を入力する場所があります。
12.7.2.2. Webhook
ビルドを自動的にトリガーするには、次の形式を使用して .json
ペイロードを webhook URL に POST
する必要があります。
これはサーバーの設定に応じてさまざまな方法で行うことができますが、ほとんどの場合は post-receive
Git フック で行うことができます。
このリクエストが有効であるためには、application/json
を含む Content-Type
ヘッダーが必要です。
webhook の例
{ "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 } } }
第13章 GitHub での OAuth アプリケーションの作成
Red Hat Quay レジストリーを GitHub OAuth アプリケーションとして登録することで、GitHub アカウントとそのリポジトリーへのアクセスを許可できます。
13.1. GitHub アプリケーションの新規作成
Github で OAuth アプリケーションを作成するには、次の手順を実行します。
手順
- Github Enterprise にログインします。
- ナビゲーションペインで、ユーザー名 → Your organizations を選択します。
- ナビゲーションペインで、Applications を選択します。
Register New Application をクリックします。
Register a new OAuth application
設定画面が表示されます。次に例を示します。- Application name テキストボックスにアプリケーションの名前を入力します。
Homepage URL テキストボックスに、Red Hat Quay URL を入力します。
注記公開されている GitHub を使用する場合、入力するホームページの URL は、ユーザーがアクセスできるものである必要があります。その URL が内部用のままである可能性があります。
- Authorization callback URL に、https://<RED_HAT_QUAY_URL>/oauth2/github/callback と入力します。
- Register application をクリックして設定を保存します。
- 新しいアプリケーションの概要が表示されたら、新しいアプリケーションに対して表示されたクライアント ID とクライアントシークレットを記録します。
第14章 Red Hat Quay クォータの管理と適用の概要
Red Hat Quay では、ユーザーは、設定されたストレージクォータ制限を確立することにより、ストレージ消費を報告し、レジストリーの増加を抑えることができます。オンプレミスの Red Hat Quay ユーザーには、環境の容量制限を管理するための次の機能が装備されるようになりました。
- Quota reporting: この機能を使用すると、スーパーユーザーはすべての組織のストレージ消費量を追跡できます。さらに、ユーザーは割り当てられた組織のストレージ消費量を追跡できます。
- Quota management: この機能を使用すると、スーパーユーザーは Red Hat Quay ユーザーのソフトチェックとハードチェックを定義できます。ソフトチェックは、組織のストレージ消費量が設定されたしきい値に達しているかどうかをユーザーに通知します。ハードチェックは、ストレージ消費量が設定された制限に達したときにユーザーがレジストリーにプッシュするのを防ぎます。
これらの機能を組み合わせることで、Red Hat Quay レジストリーのサービス所有者はサービスレベル契約を定義し、健全なリソース予算をサポートできるようになります。
14.1. クォータ管理アーキテクチャー
クォータ管理機能を有効にすると、個々の BLOB サイズがリポジトリーレベルと名前空間レベルで合計されます。たとえば、同じリポジトリー内の 2 つのタグが同じ BLOB を参照している場合、その BLOB のサイズはリポジトリーの合計に対して 1 回だけカウントされます。さらに、マニフェストリストの合計もリポジトリーの合計にカウントされます。
マニフェスト一覧の合計はリポジトリーの合計にカウントされるため、Red Hat Quay の以前のバージョンからアップグレードするときに消費される合計クォータは、Red Hat Quay 3.9 では大幅に異なる可能性があります。場合によっては、新しい合計がリポジトリーで以前に設定された制限を超える可能性があります。Red Hat Quay 管理者は、これらの変更を考慮して、リポジトリーに割り当てられたクォータを調整する必要がある場合があります。
クォータ管理機能は、バックフィルワーカーを使用して既存のリポジトリーと名前空間のサイズを計算し、その後プッシュまたはガベージコレクションされたすべてのイメージの合計を加算または減算することによって機能します。さらに、マニフェストがガベージコレクションされるときに、合計からの減算が行われます。
マニフェストがガベージコレクションされるときに合計から減算が発生するため、ガベージコレクションが可能になるまでサイズの計算に遅れが生じます。ガベージコレクションの詳細は、Red Hat Quay ガベージコレクション を参照してください。
以下のデータベーステーブルには、組織内の Red Hat Quay リポジトリーのクォータリポジトリーサイズ、クォータ名前空間サイズ、およびクォータレジストリーサイズ (バイト単位) が保持されます。
-
QuotaRepositorySize
-
QuotaNameSpaceSize
-
QuotaRegistrySize
組織のサイズは、重複しないようにバックフィル作業者によって計算されます。イメージプッシュが初期化されると、ユーザーの組織ストレージが検証され、設定されたクォータ制限を超えているかどうかがチェックされます。イメージプッシュが定義されたクォータ制限を超えると、ソフトチェックまたはハードチェックが発生します。
- ソフトチェックの場合は、ユーザーに通知されます。
- ハードチェックの場合は、プッシュが停止します。
ストレージ消費量が設定済みのクォータ制限内にある場合は、プッシュを続行できます。
イメージマニフェストの削除も同様のフローに従い、関連するイメージタグとマニフェストの間のリンクが削除されます。さらに、イメージマニフェストが削除された後、リポジトリーサイズが再計算され、QuotaRepositorySize
、QuotaNameSpaceSize
、および QuotaRegistrySize
テーブルで更新されます。
14.2. クォータ管理の制限
クォータ管理は、組織がリソース消費を維持するのに役立ちます。クォータ管理の制限の 1 つは、プッシュでリソース消費を計算すると、計算がプッシュのクリティカルパスの一部になることです。これがないと、使用状況データがドリフトする可能性があります。
最大ストレージクォータサイズは、選択したデータベースによって異なります。
変数 | 説明 |
---|---|
Postgres | 8388608 TB |
MySQL | 8388608 TB |
SQL Server | 16777216 TB |
14.3. クォータ管理設定フィールド
フィールド | 型 | 説明 |
---|---|---|
FEATURE_QUOTA_MANAGEMENT | ブール値 | クォータ管理機能の設定、キャッシュ、検証を有効にします。 **Default:** `False` |
DEFAULT_SYSTEM_REJECT_QUOTA_BYTES | 文字列 | すべての組織に対してシステムのデフォルトクォータ拒否バイト許容量を有効にします。 デフォルトでは、制限は設定されていません。 |
QUOTA_BACKFILL | ブール値 | クォータバックフィルワーカーが既存の BLOB のサイズを計算できるようにします。
デフォルト: |
QUOTA_TOTAL_DELAY_SECONDS | 文字列 | クォータバックフィルを開始するまでの遅延時間。ローリングデプロイメントでは、合計が不正確になる可能性があります。このフィールドは、ローリングデプロイメントが完了するまでにかかる時間よりも長い時間を設定する 必要があります。
デフォルト: |
PERMANENTLY_DELETE_TAGS | ブール値 | タイムマシンウィンドウからのタグの削除に関連する機能を有効にします。
デフォルト: |
RESET_CHILD_MANIFEST_EXPIRATION | ブール値 |
子マニフェストを対象とする一時タグの有効期限をリセットします。この機能を
デフォルト: |
14.3.1. クォータ管理設定の例
次の YAML は、クォータ管理を有効にするときに推奨される設定です。
クォータ管理 YAML 設定
FEATURE_QUOTA_MANAGEMENT: true FEATURE_GARBAGE_COLLECTION: true PERMANENTLY_DELETE_TAGS: true QUOTA_TOTAL_DELAY_SECONDS: 1800 RESET_CHILD_MANIFEST_EXPIRATION: true
14.4. Red Hat Quay API を使用したクォータの確立
組織が最初に作成されたとき、割り当ては適用されていません。/api/v1/organization/{organization}/quota エンドポイントを使用します。
サンプルコマンド
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota | jq
出力例
[]
14.4.1. クォータの設定
組織の割り当てを設定するには、データを /api/v1/organization/{orgname}/quota エンドポイントに POST します。以下はコマンド例です。
$ curl -k -X POST -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"limit_bytes": 10485760}' https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org/api/v1/organization/testorg/quota | jq
出力例
"Created"
14.4.2. クォータの表示
適用されたクォータを確認するには、/api/v1/organization/{orgname}/quota エンドポイントからデータを GET
します。
サンプルコマンド
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota | jq
出力例
[ { "id": 1, "limit_bytes": 10485760, "default_config": false, "limits": [], "default_config_exists": false } ]
14.4.3. クォータの変更
既存の割り当てを変更する (ここでは 10MB から 100MB に) には、データを /api/v1/organization/{orgname}/quota/{quota_id} エンドポイントに PUT します。
サンプルコマンド
$ curl -k -X PUT -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"limit_bytes": 104857600}' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota/1 | jq
出力例
{ "id": 1, "limit_bytes": 104857600, "default_config": false, "limits": [], "default_config_exists": false }
14.4.4. イメージのプッシュ
消費されたストレージを確認するには、さまざまなイメージを組織にプッシュします。
14.4.4.1. ubuntu:18.04 のプッシュ
コマンドラインから組織に ubuntu:18.04 をプッシュします。
サンプルコマンド
$ podman pull ubuntu:18.04 $ podman tag docker.io/library/ubuntu:18.04 example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/ubuntu:18.04 $ podman push --tls-verify=false example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/ubuntu:18.04
14.4.4.2. API を使用してクォータの使用状況の表示
消費されたストレージを表示するには、/api/v1/repository エンドポイントからデータを GET
します。
サンプルコマンド
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/repository?last_modified=true&namespace=testorg&popularity=true&public=true' | jq
出力例
{ "repositories": [ { "namespace": "testorg", "name": "ubuntu", "description": null, "is_public": false, "kind": "image", "state": "NORMAL", "quota_report": { "quota_bytes": 27959066, "configured_quota": 104857600 }, "last_modified": 1651225630, "popularity": 0, "is_starred": false } ] }
14.4.4.3. 別のイメージをプッシュ
2 番目のイメージをプル、タグ付け、プッシュします。たとえば、
nginx
です。サンプルコマンド
$ podman pull nginx $ podman tag docker.io/library/nginx example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/nginx $ podman push --tls-verify=false example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/nginx
組織内のリポジトリーのクォータレポートを表示するには、/api/v1/repository エンドポイントを使用します。
サンプルコマンド
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/repository?last_modified=true&namespace=testorg&popularity=true&public=true'
出力例
{ "repositories": [ { "namespace": "testorg", "name": "ubuntu", "description": null, "is_public": false, "kind": "image", "state": "NORMAL", "quota_report": { "quota_bytes": 27959066, "configured_quota": 104857600 }, "last_modified": 1651225630, "popularity": 0, "is_starred": false }, { "namespace": "testorg", "name": "nginx", "description": null, "is_public": false, "kind": "image", "state": "NORMAL", "quota_report": { "quota_bytes": 59231659, "configured_quota": 104857600 }, "last_modified": 1651229507, "popularity": 0, "is_starred": false } ] }
組織の詳細でクォータ情報を表示するには、/api/v1/organization/{orgname} エンドポイントを使用します。
サンプルコマンド
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' 'https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg' | jq
出力例
{ "name": "testorg", ... "quotas": [ { "id": 1, "limit_bytes": 104857600, "limits": [] } ], "quota_report": { "quota_bytes": 87190725, "configured_quota": 104857600 } }
14.4.5. クォータ制限を使用してプッシュの拒否
イメージプッシュが定義されたクォータ制限を超えると、ソフトチェックまたはハードチェックが発生します。
- ソフトチェックまたは 警告 の場合は、ユーザーに通知されます。
- ハードチェックまたは 拒否 の場合、プッシュは終了します。
14.4.5.1. 拒否および警告の制限の設定
拒否 および 警告 の制限を設定するには、データを /api/v1/organization/{orgname}/quota/{quota_id}/limit エンドポイントに POST します。
サンプル拒否制限コマンド
$ curl -k -X POST -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"type":"Reject","threshold_percent":80}' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota/1/limit
警告制限コマンドの例
$ curl -k -X POST -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"type":"Warning","threshold_percent":50}' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota/1/limit
14.4.5.2. 拒否および警告の制限の表示
拒否 および 警告 の制限を表示するには、/api/v1/Organization/{orgname}/quota エンドポイントを使用します。
クォータ制限の表示
$ curl -k -X GET -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' https://example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/api/v1/organization/testorg/quota | jq
クォータ制限のサンプル出力
[ { "id": 1, "limit_bytes": 104857600, "default_config": false, "limits": [ { "id": 2, "type": "Warning", "limit_percent": 50 }, { "id": 1, "type": "Reject", "limit_percent": 80 } ], "default_config_exists": false } ]
14.4.5.3. 拒否制限を超えたときにイメージをプッシュ
この例では、拒否制限 (80%) が現在のリポジトリーサイズ (~83%) 未満に設定されているため、次のプッシュは自動的に拒否されます。
コマンドラインからサンプルイメージを組織にプッシュします。
サンプルイメージプッシュ
$ podman pull ubuntu:20.04 $ podman tag docker.io/library/ubuntu:20.04 example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/ubuntu:20.04 $ podman push --tls-verify=false example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org/testorg/ubuntu:20.04
クォータを超えたときのサンプル出力
Getting image source signatures Copying blob d4dfaa212623 [--------------------------------------] 8.0b / 3.5KiB Copying blob cba97cc5811c [--------------------------------------] 8.0b / 15.0KiB Copying blob 0c78fac124da [--------------------------------------] 8.0b / 71.8MiB WARN[0002] failed, retrying in 1s ... (1/3). Error: Error writing blob: Error initiating layer upload to /v2/testorg/ubuntu/blobs/uploads/ in example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org: denied: Quota has been exceeded on namespace Getting image source signatures Copying blob d4dfaa212623 [--------------------------------------] 8.0b / 3.5KiB Copying blob cba97cc5811c [--------------------------------------] 8.0b / 15.0KiB Copying blob 0c78fac124da [--------------------------------------] 8.0b / 71.8MiB WARN[0005] failed, retrying in 1s ... (2/3). Error: Error writing blob: Error initiating layer upload to /v2/testorg/ubuntu/blobs/uploads/ in example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org: denied: Quota has been exceeded on namespace Getting image source signatures Copying blob d4dfaa212623 [--------------------------------------] 8.0b / 3.5KiB Copying blob cba97cc5811c [--------------------------------------] 8.0b / 15.0KiB Copying blob 0c78fac124da [--------------------------------------] 8.0b / 71.8MiB WARN[0009] failed, retrying in 1s ... (3/3). Error: Error writing blob: Error initiating layer upload to /v2/testorg/ubuntu/blobs/uploads/ in example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org: denied: Quota has been exceeded on namespace Getting image source signatures Copying blob d4dfaa212623 [--------------------------------------] 8.0b / 3.5KiB Copying blob cba97cc5811c [--------------------------------------] 8.0b / 15.0KiB Copying blob 0c78fac124da [--------------------------------------] 8.0b / 71.8MiB Error: Error writing blob: Error initiating layer upload to /v2/testorg/ubuntu/blobs/uploads/ in example-registry-quay-quay-enterprise.apps.docs.gcp.quaydev.org: denied: Quota has been exceeded on namespace
14.4.5.4. 制限を超えた場合の通知
制限を超えると、通知が表示されます。
クォータ通知
第15章 アップストリームレジストリーのプロキシーキャッシュとしての Red Hat Quay
コンテナー開発の人気が高まるにつれ、お客様はサービスを稼働させるために Docker や Google Cloud Platform などのアップストリームレジストリーからのコンテナーイメージにますます依存するようになっています。現在、レジストリーにはレート制限があり、ユーザーがこれらのレジストリーからプルできる回数が制限されています。
この機能により、Red Hat Quay は、アップストリームレジストリーからのプルレート制限を回避するためのプロキシーキャッシュとして機能します。キャッシュ機能を追加すると、アップストリームの依存関係ではなくキャッシュからイメージがプルされるため、プルのパフォーマンスも向上します。キャッシュされたイメージは、アップストリームのイメージダイジェストがキャッシュされたイメージと異なる場合にのみ更新され、レート制限と潜在的なスロットリングを削減します。
Red Hat Quay キャッシュプロキシーを使用すると、次の機能が利用可能になります。
- 特定の組織は、アップストリームレジストリーのキャッシュとして定義できます。
特定のアップストリームレジストリーのキャッシュとして機能する Quay 組織の設定。このリポジトリーは、Quay UI を使用して定義でき、次の設定を提供します。
- プライベートリポジトリーのアップストリームレジストリークレデンシャルまたはレート制限の強化。
- キャッシュ組織のサイズを超えないようにするための有効期限タイマー。
- 設定アプリケーションを介して設定可能なグローバルオン/オフ。
-
アップストリームレジストリー全体または単一の名前空間 (たとえば、すべての
docker.io
または単にdocker.io/library
のキャッシュ。 - すべてのキャッシュプルのログ。
- Clair によるキャッシュイメージのスキャン可能性。
15.1. プロキシーキャッシュアーキテクチャー
次のイメージは、プロキシーキャッシュ機能の予想される設計フローおよびアーキテクチャーを示しています。
ユーザーが Red Hat Quay のアップストリームリポジトリーからイメージ (postgres:14
など) をプルすると、リポジトリーはイメージが存在するかどうかを確認します。イメージが存在しない場合は、新しいプルが開始します。プルされた後、イメージレイヤーはキャッシュに保存され、サーバーに並行してユーザーに提供されます。次のイメージは、このシナリオのアーキテクチャーの概要を示しています。
キャッシュ内のイメージが存在する場合、ユーザーは Quay のキャッシュを利用してアップストリームソースを最新の状態に保ち、キャッシュから新しいイメージが自動的にプルされるようにできます。これは、元のイメージのタグがアップストリームレジストリーで上書きされた場合に発生します。次のイメージは、アップストリームイメージとキャッシュされたバージョンのイメージが異なる場合に何が起こるかを示すアーキテクチャーの概要を示しています。
アップストリームイメージとキャッシュされたバージョンが同じである場合、レイヤーはプルされず、キャッシュされたイメージがユーザーに配信されます。
場合によっては、アップストリームレジストリーがダウンしたときにユーザーがプルを開始します。設定された失効期間でこれが発生した場合は、キャッシュに保存されたイメージが配信されます。設定された失効期間の後にプルが発生すると、エラーはユーザーに伝播されます。次のイメージは、設定された失効期間の後にプルが発生した場合のアーキテクチャーの概要を示しています。
Quay 管理者は、組織の設定可能なサイズ制限を利用してキャッシュサイズを制限できるため、バックエンドストレージの消費量を予測できます。これは、イメージが使用される頻度に応じてキャッシュからイメージを破棄することで実現されます。次のイメージは、このシナリオのアーキテクチャーの概要を示しています。
15.2. プロキシーキャッシュの制限
Red Hat Quay を使用したプロキシーキャッシングには、次の制限があります。
- プロキシーキャッシュには、キャッシュするイメージ以上のサイズ制限が必要です。たとえば、プロキシーキャッシュ組織の最大サイズが 500 MB で、ユーザーがプルしたいイメージが 700 MB の場合、イメージはキャッシュされますが、設定された制限を超えてオーバーフローします。
- キャッシュされたイメージは、Quay リポジトリー上のイメージが持つ必要があるのと同じプロパティーを持っている必要があります。
- 現在、クライアントによって要求されたレイヤーのみがキャッシュされます。
15.3. Red Hat Quay を使用してリモートレジストリーをプロキシーする
次の手順では、Red Hat Quay を使用してリモートレジストリーをプロキシーする方法を説明します。この手順は、プロキシー quay.io に設定されています。これにより、ユーザーは podman
を使用して、quay.io 上の任意の名前空間から任意のパブリックイメージをプルできます。
前提条件
-
config.yaml の
FEATURE_PROXY_CACHE
がtrue
に設定されている。 - Member チームのロールが割り当てられている。チームのロールの詳細は、Red Hat Quay のユーザーおよび組織 を参照してください。
手順
-
UI の Quay 組織 (たとえば
cache-quayio
) で、左側のペインの Organization Settings をクリックします。 オプション: Add Storage Quota をクリックして、組織のクォータ管理を設定します。クォータ管理の詳細は、クォータ管理 を参照してください。
注記場合によっては、Podman を使用してイメージをプルすると、プル中にクォータ制限に達したときに
unable to pull image: Error parsing image configuration: Error fetching blob: invalid status code from registry 403 (Forbidden)
エラーが返されることがあります。エラー403
は不正確であり、Podman が正しい API エラーQuota has been exceeded on namespace
を非表示にしているために発生します。この既知の問題は、将来の Podman 更新で修正される予定です。Remote Registry に、キャッシュするリモートレジストリーの名前 (
quay.io
など) を入力し、Save をクリックします。注記Remote Registry に名前空間 (たとえば
quay.io/<namespace>
) を追加すると、組織内のユーザーはその名前空間からのみプロキシーできるようになります。オプション: Remote Registry Username および Remote Registry Password を追加します。
注記Remote Registry Username および Remote Registry Password を設定しない場合は、プロキシーキャッシュを削除して新しいレジストリーを作成しない限り、パスワードを追加できません。
オプション: Expiration フィールドに時間を設定します。
注記- プロキシー組織でキャッシュされたイメージのデフォルトのタグ Expiration フィールドは 86400 秒に設定されています。プロキシー組織では、タグがプルされるたびに、タグの有効期限が UI の Expiration フィールドに設定された値に更新されます。この機能は、Quay のデフォルトの 個別タグ有効期限 機能とは異なります。プロキシー組織では、個々のタグ機能をオーバーライドできます。これが発生すると、プロキシー組織の Expiration フィールドに従って、個々のタグの有効期限がリセットされます。
- 期限切れのイメージは、割り当てられた時間が経過すると消えますが、Quay に保存されます。イメージが完全に削除されるタイミング、またはコレクションされるタイミングは、組織の Time Machine の設定によって異なります。特に指定がない限り、ガベージコレクションのデフォルトの時間は 14 日です。
- Save をクリックします。
CLI で、プロキシーキャッシュとして機能するパブリックイメージ (quay.io など) をレジストリーからプルします。
$ podman pull <registry_url>/<organization_name>/<quayio_namespace>/<image_name>
重要組織がリモートレジストリー内の単一の名前空間からプルするように設定されている場合は、リモートレジストリーの名前空間を URL から省略する必要があります。たとえば、
podman pull <registry_url>/<organization_name>/<image_name>
です。
15.3.1. プロキシー組織でのストレージクォータ制限の活用
Red Hat Quay 3.8 では、プロキシーキャッシュ機能が強化され、タグ付きイメージの自動プルーニング機能が追加されました。イメージタグの自動プルーニングは、プロキシーされた名前空間にクォータ制限が設定されている場合にのみ使用できます。現在、イメージサイズが組織のクォータより大きい場合は、管理者が必要なスペースを作成するまで、イメージのアップロードはスキップされます。現在、割り当てられたスペースを超えるイメージがプッシュされると、自動プルーニングの機能強化により、使用頻度の最も低いタグが削除対象としてマークされます。その結果、新しいイメージタグが保存され、最も使用頻度の低いイメージタグが削除対象としてマークされます。
- 自動プルーニング機能の一部として、削除対象としてマークされたタグは、最終的にガベージコレクター (gc) ワーカープロセスによってガベージコレクションされます。そのため、この期間中はクォータサイズの制限が完全には適用されません。
- 現在、名前空間クォータサイズの計算では、マニフェストの子のサイズは考慮されていません。これは既知の問題であり、Red Hat Quay の今後のバージョンで修正される予定です。
15.3.1.1. プロキシー組織でのストレージクォータ制限機能のテスト
次の手順を使用して、プロキシーキャッシュとストレージクォータ制限が有効になっている組織の自動プルーニング機能をテストします。
前提条件
- 組織がプロキシー組織として機能するように設定されている。次の例では、quay.io からプロキシーします。
-
config.yaml
ファイルのFEATURE_PROXY_CACHE
がtrue
に設定されている。 -
config.yaml
ファイルでFEATURE_QUOTA_MANAGEMENT
がtrue
に設定されている。 -
組織には
150 MB
などのクォータ制限が設定されている。
手順
プロキシー組織からリポジトリーにイメージをプルします。以下に例を示します。
$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.7.9
リポジトリーに残っているスペースによっては、プロキシー組織から追加のイメージのプルが必要になる場合があります。以下に例を示します。
$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.6.2
Red Hat Quay レジストリー UI で、リポジトリーの名前をクリックします。
-
ナビゲーションペインで Tags をクリックし、
quay:3.7.9
とquay:3.6.2
がタグ付けされていることを確認します。
-
ナビゲーションペインで Tags をクリックし、
リポジトリーに割り当てられたクォータを超えるように、最後のイメージをプルします。次に例を示します。
$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.5.1
-
Red Hat Quay レジストリーの Tags ページを更新します。プッシュした最初のイメージ (
quay:3.7.9
など) は、自動プルーニングされているはずです。Tags ページにはquay:3.6.2
とquay:3.5.1
が表示されるはずです。
第16章 Red Hat Quay ビルドの機能強化
Red Hat Quay ビルドは仮想化プラットフォーム上で実行できます。以前のビルド設定を実行するための下位互換性も利用できます。
16.1. Red Hat Quay の拡張ビルドアーキテクチャー
以下のイメージは、拡張ビルド機能の想定される設計フローとアーキテクチャーを示しています。
この機能拡張により、ビルドマネージャーは最初に Job Object
を作成します。次に、Job Object
は quay-builder-image
を使用して Pod を作成します。quay-builder-image
には、quay-builder binary
サービスおよび Podman
サービスが含まれます。作成された Pod は unprivileged
として実行されます。次に、quay-builder binary
は、ステータスを通知してビルドマネージャーからビルド情報を取得しつつ、イメージをビルドします。
16.2. Red Hat Quay ビルドの制限
特権のないコンテキストで Red Hat Quay でビルドを実行すると、以前のビルド戦略で機能していた一部のコマンドが失敗する可能性があります。ビルド戦略を変更しようとすると、ビルドのパフォーマンスの問題と信頼性の問題が発生する可能性があります。
コンテナーでビルドを直接実行しても、仮想マシンを使用する場合と同じように分離されることはありません。ビルド環境を変更すると、以前は機能していたビルドが失敗する可能性もあります。
16.3. OpenShift Container Platform を使用した Red Hat Quay ビルダー環境の作成
このセクションの手順では、OpenShift Container Platform で Red Hat Quay 仮想ビルダー環境を作成する方法を説明します。
16.3.1. OpenShift Container Platform TLS コンポーネント
tls
コンポーネントを使用すると、TLS 設定を制御できます。
TLS コンポーネントが Operator によって管理されている場合、Red Hat Quay 3 はビルダーをサポートしません。
tls
を unmanaged
に設定する場合は、独自の ssl.cert
ファイルと ssl.key
ファイルを提供します。このとき、クラスターでビルダーをサポートする場合は、Quay ルートとビルダールート名の両方を証明書の SAN リストに追加するか、ワイルドカードを使用する必要があります。
ビルダールートを追加するには、次の形式を使用します。
[quayregistry-cr-name]-quay-builder-[ocp-namespace].[ocp-domain-name]:443
16.3.2. OpenShift Container Platform ビルダー向けの Red Hat Quay の使用
ビルダーには SSL/TLS 証明書が必要です。SSL/TLS 証明書の詳細は、SSL/TLS 証明書を使用した概念実証のデプロイメント を参照してください。
Amazon Webservice (AWS) S3 ストレージを使用している場合は、ビルダーを実行する前に、AWS コンソールでストレージバケットを変更する必要があります。必要なパラメーターは、次のセクションの「AWS S3 ストレージバケットの変更」を参照してください。
16.3.2.1. 仮想ビルダー向けの OpenShift Container Platform の準備
以下の手順を使用して、Red Hat Quay 仮想ビルダー用に OpenShift Container Platform を準備します。
- この手順は、クラスターがすでにプロビジョニングされており、Quay Operator が実行されていることを前提とします。
- この手順は、OpenShift Container Platform で仮想 namespace を設定するためのものです。
手順
- クラスター管理者アカウントを使用して Red Hat Quay クラスターにログインします。
次のコマンドを実行して、仮想ビルダーが実行される新しいプロジェクト (
virtual-builders
など) を作成します。$ oc new-project virtual-builders
次のコマンドを入力して、ビルドの実行に使用されるプロジェクトに
ServiceAccount
を作成します。$ oc create sa -n virtual-builders quay-builder
作成したサービスアカウントに編集権限を付与して、ビルドを実行できるようにします。
$ oc adm policy -n virtual-builders add-role-to-user edit system:serviceaccount:virtual-builders:quay-builder
次のコマンドを入力して、Quay ビルダーに
anyuid scc
権限を付与します。$ oc adm policy -n virtual-builders add-scc-to-user anyuid -z quay-builder
注記このアクションには、クラスター管理者特権が必要です。非特権ビルドまたはルートレスビルドを機能させるには、ビルダーを Podman ユーザーとして実行する必要があるため、これが必要です。
Quay ビルダーサービスアカウントのトークンを取得します。
OpenShift Container Platform 4.10 以前のバージョンを使用している場合は、以下のコマンドを入力します。
oc sa get-token -n virtual-builders quay-builder
OpenShift Container Platform 4.11 以降を使用している場合は、以下のコマンドを入力します。
$ oc create token quay-builder -n virtual-builders
注記トークンの有効期限が切れたら、新しいトークンを要求する必要があります。必要に応じて、カスタムの有効期限を追加することもできます。たとえば、トークンを 2 週間保持するには、
--duration 20160m
と指定します。出力例
eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ...
次のコマンドを入力してビルダールートを決定します。
$ oc get route -n quay-enterprise
出力例
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD ... example-registry-quay-builder example-registry-quay-builder-quay-enterprise.apps.docs.quayteam.org example-registry-quay-app grpc edge/Redirect None ...
次のコマンドを入力して、拡張子が .crt の自己署名 SSL/TlS 証明書を生成します。
$ oc extract cm/kube-root-ca.crt -n openshift-apiserver
出力例
ca.crt
次のコマンドを入力して、
ca.crt
ファイルの名前をextra_ca_cert_build_cluster.crt
に変更します。$ mv ca.crt extra_ca_cert_build_cluster.crt
Console で設定バンドルのシークレットを見つけ、Actions → Edit Secret を選択して、適切なビルダー設定を追加します。
FEATURE_USER_INITIALIZE: true BROWSER_API_CALLS_XHR_ONLY: false SUPER_USERS: - <superusername> FEATURE_USER_CREATION: false FEATURE_QUOTA_MANAGEMENT: true FEATURE_BUILD_SUPPORT: True BUILDMAN_HOSTNAME: <sample_build_route> 1 BUILD_MANAGER: - ephemeral - ALLOWED_WORKER_COUNT: 1 ORCHESTRATOR_PREFIX: buildman/production/ JOB_REGISTRATION_TIMEOUT: 3600 2 ORCHESTRATOR: REDIS_HOST: <sample_redis_hostname> 3 REDIS_PASSWORD: "" REDIS_SSL: false REDIS_SKIP_KEYSPACE_EVENT_SETUP: false EXECUTORS: - EXECUTOR: kubernetesPodman NAME: openshift BUILDER_NAMESPACE: <sample_builder_namespace> 4 SETUP_TIME: 180 MINIMUM_RETRY_THRESHOLD: 0 BUILDER_CONTAINER_IMAGE: <sample_builder_container_image> 5 # Kubernetes resource options K8S_API_SERVER: <sample_k8s_api_server> 6 K8S_API_TLS_CA: <sample_crt_file> 7 VOLUME_SIZE: 8G KUBERNETES_DISTRIBUTION: openshift CONTAINER_MEMORY_LIMITS: 300m 8 CONTAINER_CPU_LIMITS: 1G 9 CONTAINER_MEMORY_REQUEST: 300m 10 CONTAINER_CPU_REQUEST: 1G 11 NODE_SELECTOR_LABEL_KEY: "" NODE_SELECTOR_LABEL_VALUE: "" SERVICE_ACCOUNT_NAME: <sample_service_account_name> SERVICE_ACCOUNT_TOKEN: <sample_account_token> 12
- 1
- ビルドルートは、OpenShift Operators namespace の名前で
oc get route -n
を実行することにより取得されます。ルートの最後にポートを指定する必要があり、[quayregistry-cr-name]-quay-builder-[ocp-namespace].[ocp-domain-name]:443
の形式を使用する必要があります。 - 2
JOB_REGISTRATION_TIMEOUT
パラメーターの設定が低すぎると、failed to register job to build manager: rpc error: code = Unauthenticated desc = Invalid build token: Signature has expired
エラーが発生する可能性があります。このパラメーターは少なくとも 240 に設定することを推奨します。- 3
- Redis ホストにパスワードまたは SSL/TLS 証明書がある場合は、それに応じて更新する必要があります。
- 4
- 仮想ビルダーの namespace の名前と一致するように設定します (例:
virtual-builders
)。 - 5
- 早期アクセスの場合、
BUILDER_CONTAINER_IMAGE
は現在quay.io/projectquay/quay-builder:3.7.0-rc.2
です。ただし、早期アクセス期間中に変更される可能性があります。これが発生した場合は、顧客に警告が表示されます。 - 6
K8S_API_SERVER
は、oc cluster-info
を実行して取得します。- 7
- カスタム CA 証明書を手動で作成して追加する必要があります (例
K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build_cluster.crt
)。 - 8
- 指定しないと、デフォルトは
5120Mi
です。 - 9
- 仮想ビルドの場合は、クラスターに十分なリソースがあることを確認する必要があります。指定しないと、デフォルトは
1000m
です。 - 10
- 指定しないと、デフォルトは
3968Mi
です。 - 11
- 指定しないと、デフォルトは
500m
です。 - 12
oc create sa
の実行時に取得します。
設定サンプル
FEATURE_USER_INITIALIZE: true BROWSER_API_CALLS_XHR_ONLY: false SUPER_USERS: - quayadmin FEATURE_USER_CREATION: false FEATURE_QUOTA_MANAGEMENT: true FEATURE_BUILD_SUPPORT: True BUILDMAN_HOSTNAME: example-registry-quay-builder-quay-enterprise.apps.docs.quayteam.org:443 BUILD_MANAGER: - ephemeral - ALLOWED_WORKER_COUNT: 1 ORCHESTRATOR_PREFIX: buildman/production/ JOB_REGISTRATION_TIMEOUT: 3600 ORCHESTRATOR: REDIS_HOST: example-registry-quay-redis REDIS_PASSWORD: "" REDIS_SSL: false REDIS_SKIP_KEYSPACE_EVENT_SETUP: false EXECUTORS: - EXECUTOR: kubernetesPodman NAME: openshift BUILDER_NAMESPACE: virtual-builders SETUP_TIME: 180 MINIMUM_RETRY_THRESHOLD: 0 BUILDER_CONTAINER_IMAGE: quay.io/projectquay/quay-builder:3.7.0-rc.2 # Kubernetes resource options K8S_API_SERVER: api.docs.quayteam.org:6443 K8S_API_TLS_CA: /conf/stack/extra_ca_certs/build_cluster.crt VOLUME_SIZE: 8G KUBERNETES_DISTRIBUTION: openshift CONTAINER_MEMORY_LIMITS: 1G CONTAINER_CPU_LIMITS: 1080m CONTAINER_MEMORY_REQUEST: 1G CONTAINER_CPU_REQUEST: 580m NODE_SELECTOR_LABEL_KEY: "" NODE_SELECTOR_LABEL_VALUE: "" SERVICE_ACCOUNT_NAME: quay-builder SERVICE_ACCOUNT_TOKEN: "eyJhbGciOiJSUzI1NiIsImtpZCI6IldfQUJkaDVmb3ltTHZ0dGZMYjhIWnYxZTQzN2dJVEJxcDJscldSdEUtYWsifQ"
16.3.2.2. SSL/TLS 証明書の手動追加
設定ツールの既知の問題のため、ビルダーを適切に実行するには、カスタム SSL/TLS 証明書を手動で追加する必要があります。次の手順を使用して、カスタム SSL/TLS 証明書を手動で追加します。
SSL/TLS 証明書の作成の詳細は、SSL/TLS 証明書を使用した概念実証のデプロイメント を参照してください。
16.3.2.2.1. 証明書の作成と署名
SSL/TLS 証明書を作成して署名するには、次の手順を実行します。
手順
認証局を作成し、証明書に署名します。詳細は、認証局の作成を 参照してください。
openssl.cnf
[req] req_extensions = v3_req distinguished_name = req_distinguished_name [req_distinguished_name] [ v3_req ] basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectAltName = @alt_names [alt_names] DNS.1 = example-registry-quay-quay-enterprise.apps.docs.quayteam.org 1 DNS.2 = example-registry-quay-builder-quay-enterprise.apps.docs.quayteam.org 2
サンプルコマンド
$ openssl genrsa -out rootCA.key 2048 $ openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem $ openssl genrsa -out ssl.key 2048 $ openssl req -new -key ssl.key -out ssl.csr $ openssl x509 -req -in ssl.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out ssl.cert -days 356 -extensions v3_req -extfile openssl.cnf
16.3.2.2.2. TLS の管理対象外への設定
次の手順を使用して、king:tls
を管理対象外に設定します。
手順
Red Hat Quay Registry YAML で、
kind: tls
をmanaged: false
に設定します。- kind: tls managed: false
Events ページでは、適切な
config.yaml
ファイルを設定するまで変更がブロックされます。以下に例を示します。- lastTransitionTime: '2022-03-28T12:56:49Z' lastUpdateTime: '2022-03-28T12:56:49Z' message: >- required component `tls` marked as unmanaged, but `configBundleSecret` is missing necessary fields reason: ConfigInvalid status: 'True'
16.3.2.2.3. 一時的なシークレットの作成
次の手順を使用して、CA 証明書の一時的なシークレットを作成します。
手順
CA 証明書のデフォルトの namespace にシークレットを作成します。
$ oc create secret generic -n quay-enterprise temp-crt --from-file extra_ca_cert_build_cluster.crt
ssl.key
ファイルおよびssl.cert
ファイルのデフォルトの namespace にシークレットを作成します。$ oc create secret generic -n quay-enterprise quay-config-ssl --from-file ssl.cert --from-file ssl.key
16.3.2.2.4. シークレットデータの設定 YAML へのコピー
次の手順を使用して、シークレットデータを config.yaml
ファイルにコピーします。
手順
- コンソール UI の Workloads → Secrets で新しいシークレットを見つけます。
シークレットごとに、YAML ビューを見つけます。
kind: Secret apiVersion: v1 metadata: name: temp-crt namespace: quay-enterprise uid: a4818adb-8e21-443a-a8db-f334ace9f6d0 resourceVersion: '9087855' creationTimestamp: '2022-03-28T13:05:30Z' ... data: extra_ca_cert_build_cluster.crt: >- LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURNakNDQWhxZ0F3SUJBZ0l.... type: Opaque
kind: Secret apiVersion: v1 metadata: name: quay-config-ssl namespace: quay-enterprise uid: 4f5ae352-17d8-4e2d-89a2-143a3280783c resourceVersion: '9090567' creationTimestamp: '2022-03-28T13:10:34Z' ... data: ssl.cert: >- LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVaakNDQTA2Z0F3SUJBZ0lVT... ssl.key: >- LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcFFJQkFBS0NBUUVBc... type: Opaque
UI で Red Hat Quay レジストリー設定バンドルのシークレットを見つけるか、以下のようなコマンドを実行してコマンドラインから見つけます。
$ oc get quayregistries.quay.redhat.com -o jsonpath="{.items[0].spec.configBundleSecret}{'\n'}" -n quay-enterprise
OpenShift Container Platform コンソールで、設定バンドルのシークレットの YAML タブを選択し、作成した 2 つのシークレットからデータを追加します。
kind: Secret apiVersion: v1 metadata: name: init-config-bundle-secret namespace: quay-enterprise uid: 4724aca5-bff0-406a-9162-ccb1972a27c1 resourceVersion: '4383160' creationTimestamp: '2022-03-22T12:35:59Z' ... data: config.yaml: >- RkVBVFVSRV9VU0VSX0lOSVRJQUxJWkU6IHRydWUKQlJ... extra_ca_cert_build_cluster.crt: >- LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURNakNDQWhxZ0F3SUJBZ0ldw.... ssl.cert: >- LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVaakNDQTA2Z0F3SUJBZ0lVT... ssl.key: >- LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcFFJQkFBS0NBUUVBc... type: Opaque
- Save をクリックします。
次のコマンドを入力して、Pod が再起動しているかどうかを確認します。
$ oc get pods -n quay-enterprise
出力例
NAME READY STATUS RESTARTS AGE ... example-registry-quay-app-6786987b99-vgg2v 0/1 ContainerCreating 0 2s example-registry-quay-app-7975d4889f-q7tvl 1/1 Running 0 5d21h example-registry-quay-app-7975d4889f-zn8bb 1/1 Running 0 5d21h example-registry-quay-app-upgrade-lswsn 0/1 Completed 0 6d1h example-registry-quay-config-editor-77847fc4f5-nsbbv 0/1 ContainerCreating 0 2s example-registry-quay-config-editor-c6c4d9ccd-2mwg2 1/1 Running 0 5d21h example-registry-quay-database-66969cd859-n2ssm 1/1 Running 0 6d1h example-registry-quay-mirror-764d7b68d9-jmlkk 1/1 Terminating 0 5d21h example-registry-quay-mirror-764d7b68d9-jqzwg 1/1 Terminating 0 5d21h example-registry-quay-redis-7cc5f6c977-956g8 1/1 Running 0 5d21h
Red Hat Quay レジストリーが再設定されたら、次のコマンドを入力して、Red Hat Quay アプリの Pod が実行されているかどうかを確認します。
$ oc get pods -n quay-enterprise
出力例
example-registry-quay-app-6786987b99-sz6kb 1/1 Running 0 7m45s example-registry-quay-app-6786987b99-vgg2v 1/1 Running 0 9m1s example-registry-quay-app-upgrade-lswsn 0/1 Completed 0 6d1h example-registry-quay-config-editor-77847fc4f5-nsbbv 1/1 Running 0 9m1s example-registry-quay-database-66969cd859-n2ssm 1/1 Running 0 6d1h example-registry-quay-mirror-758fc68ff7-5wxlp 1/1 Running 0 8m29s example-registry-quay-mirror-758fc68ff7-lbl82 1/1 Running 0 8m29s example-registry-quay-redis-7cc5f6c977-956g8 1/1 Running 0 5d21h
ブラウザーで、レジストリーエンドポイントにアクセスし、証明書が適切に更新されていることを確認します。以下に例を示します。
Common Name (CN) example-registry-quay-quay-enterprise.apps.docs.quayteam.org Organisation (O) DOCS Organisational Unit (OU) QUAY
16.3.2.3. UI を使用してビルドトリガーを作成
UI を使用してビルドトリガーを作成するには、次の手順に従います。
手順
- Red Hat Quay リポジトリーにログインします。
-
Create New Repository をクリックして、
testrepo
などの新しいレジストリーを作成します。 Repositories ページで、ナビゲーションペインの Builds タブをクリックします。または、対応する URL を直接使用します。
https://example-registry-quay-quay-enterprise.apps.docs.quayteam.org/repository/quayadmin/testrepo?tab=builds
重要場合によっては、ビルダーでホスト名の解決に問題が発生することがあります。この問題は、ジョブオブジェクトで
default
に設定されているdnsPolicy
に関連している可能性があります。現在、この問題に対する回避策はありません。これは、Red Hat Quay の将来のバージョンで解決される予定です。- Create Build Trigger → Custom Git Repository Push をクリックします。
Git リポジトリーのクローン作成に使用する HTTPS または SSH スタイルの URL を入力し、Continue をクリックします。以下に例を示します。
https://github.com/gabriel-rh/actions_test.git
- Tag manifest with the branch or tag name を確認し、Continue をクリックします。
-
トリガーが呼び出されたときにビルドする Dockerfile の場所 (たとえば
/Dockerfile
) を入力し、Continue をクリックします。 -
Docker ビルドのコンテキストの場所 (たとえば
/
) を入力し、Continue をクリックします。 - 必要に応じて、ロボットアカウントを作成します。それ以外の場合は、Continue をクリックします。
- Continue をクリックして、パラメーターを確認します。
- Builds ページで、トリガー名の Options アイコンをクリックし、Run Trigger Now をクリックします。
- Git リポジトリーからコミット SHA を入力し、Start Build をクリックします。
ビルドのステータスを確認するには、Build History ページで commit をクリックするか、
oc get pods -n virtual-builders
を実行します。以下に例を示します。$ oc get pods -n virtual-builders
出力例
NAME READY STATUS RESTARTS AGE f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2 1/1 Running 0 7s
$ oc get pods -n virtual-builders
出力例
NAME READY STATUS RESTARTS AGE f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2 1/1 Terminating 0 9s
$ oc get pods -n virtual-builders
出力例
No resources found in virtual-builders namespace.
ビルドが完了したら、ナビゲーションペインのタグで Tags のステータスを確認できます。
注記早期アクセスにより、完全なビルドログとビルドのタイムスタンプは現在利用できません。
16.3.2.4. AWS S3 ストレージバケットの変更
AWS S3 ストレージを使用している場合は、ビルダーを実行する前に、AWS コンソールでストレージバケットを変更する必要があります。
手順
- s3.console.aws.com で AWS コンソールにログインします。
-
検索バーで
S3
を検索し、S3 をクリックします。 -
バケットの名前 (
myawsbucket
など) をクリックします。 - Permissions タブをクリックします。
Cross-origin resource sharing (CORS) の下に、次のパラメーターを含めます。
[ { "AllowedHeaders": [ "Authorization" ], "AllowedMethods": [ "GET" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [], "MaxAgeSeconds": 3000 }, { "AllowedHeaders": [ "Content-Type", "x-amz-acl", "origin" ], "AllowedMethods": [ "PUT" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [], "MaxAgeSeconds": 3000 } ]
16.3.2.5. Google Cloud Platform オブジェクトバケットの変更
現在、Google Cloud Platform オブジェクトバケットの変更は、IBM Power および IBM Z ではサポートされていません。
仮想ビルダーの Cross Origin Resource Sharing (CORS) を設定するには、次の手順を実行します。
CORS 設定がないと、ビルド Dockerfile のアップロードは失敗します。
手順
次のリファレンスを使用して、特定の CORS ニーズに合わせた JSON ファイルを作成します。以下に例を示します。
$ cat gcp_cors.json
出力例
[ { "origin": ["*"], "method": ["GET"], "responseHeader": ["Authorization"], "maxAgeSeconds": 3600 }, { "origin": ["*"], "method": ["PUT"], "responseHeader": [ "Content-Type", "x-goog-acl", "origin"], "maxAgeSeconds": 3600 } ]
次のコマンドを入力して、GCP ストレージバケットを更新します。
$ gcloud storage buckets update gs://<bucket_name> --cors-file=./gcp_cors.json
出力例
Updating Completed 1
次のコマンドを実行すると、GCP バケットの更新された CORS 設定を表示できます。
$ gcloud storage buckets describe gs://<bucket_name> --format="default(cors)"
出力例
cors: - maxAgeSeconds: 3600 method: - GET origin: - '*' responseHeader: - Authorization - maxAgeSeconds: 3600 method: - PUT origin: - '*' responseHeader: - Content-Type - x-goog-acl - origin
第17章 Red Hat Quay API の使用
Red Hat Quay は完全な OAuth 2、RESTful API を提供します。[OAuth 2] RESTful API には次の利点があります。
-
これは、Red Hat Quay ホストのエンドポイント
/api/v1
から利用できます。たとえば、https://<quay-server.example.com>/api/v1
です。 -
Swagger UI を有効にすると、ユーザーがブラウザー経由でエンドポイントに接続し、Red Hat Quay の設定を
GET
、POST
、DELETE
、PUT
できるようになります。 - API 呼び出しを実行して OAuth トークンを使用するアプリケーションからアクセスできます。
- データを JSON 形式で送受信します。
次のセクションでは、Red Hat Quay API にアクセスしてデプロイメントで使用できるようにする方法について説明します。
17.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 エンドポイントが表示されます。Quay.io で有効でない Red Hat Quay 機能のスーパーユーザー API エンドポイントまたはエンドポイント (リポジトリーミラーリングなど) は表示されません。
API Explorer から、以下に関する情報を取得し、変更できます。
- 請求、サブスクリプション、およびプラン
- リポジトリービルドおよびビルドトリガー
- エラーメッセージおよびグローバルメッセージ
- リポジトリーイメージ、マニフェスト、パーミッション、通知、脆弱性、およびイメージの署名
- 使用状況に関するログ
- 組織、メンバー、および OAuth アプリケーション
- ユーザーとロボットアカウント
- その他
エンドポイントを選択して開き、エンドポイントの各部分のモデルスキーマを表示します。エンドポイントを開き、必要なパラメーター (リポジトリー名またはイメージなど) を入力し、Try it out!
ボタンを選択して Quay.io エンドポイントに関連する設定を照会するか、変更します。
17.2. v1 OAuth アクセストークンの作成
OAuth アクセストークンは、保護されたリソースへのセキュアなアクセスを可能にする認証情報です。Red Hat Quay では、組織の API エンドポイントにアクセスする前に、OAuth アクセストークンを作成する必要があります。
OAuth アクセストークンを作成するには、次の手順を実行します。
前提条件
- Red Hat Quay に管理者としてログインしている。
手順
- メインページで、Organization を選択します。
- ナビゲーションペインで、Applications を選択します。
- Create New Application をクリックし、新しいアプリケーション名を入力して、Enter を押します。
- OAuth Applications ページで、アプリケーションの名前を選択します。
オプション: 以下の情報を入力します。
- Application Name
- Homepage URL
- Description
- Avatar E-mail
- Redirect/Callback URL prefix
- ナビゲーションペインで、Generate Token を選択します。
次のオプションのチェックボックスをオンにします。
- Administer Organization
- Administer Repositories
- Create Repositories
- View all visible repositories
- Read/Write to any accessible repositories
- Super User Access
- Administer User
- Read User Information
- Generate Access Token をクリックします。新しいページにリダイレクトされます。
- 許可する権限を確認し、Authorize Application をクリックします。Authorize Application をクリックして決定した内容を確定します。
Access Token ページにリダイレクトされます。アクセストークンをコピーして保存します。
重要これは、アクセストークンをコピーして保存する唯一の機会です。このページを離れると再取得できません。
17.3. OCI リファラー OAuth アクセストークンの作成
場合によっては、OCI リファラー OAuth アクセストークンを作成することを推奨します。このトークンは、リポジトリー配下にあるマニフェストの OCI リファラーをリスト表示するために使用します。
手順
config.yaml
ファイルを更新して、FEATURE_REFERRERS_API: true
フィールドを含めます。以下に例を示します。# ... FEATURE_REFERRERS_API: true # ...
次のコマンドを入力し、認証情報を Base64 でエンコードします。
$ echo -n '<username>:<password>' | base64
出力例
abcdeWFkbWluOjE5ODlraWROZXQxIQ==
次のコマンドを入力して、base64 でエンコードされた文字列を使用し、URL エンドポイントを Red Hat Quay サーバーに変更します。
$ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq
出力例
{ "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijl5RWNtWmdiZ0l6czBBZW16emhTMHM1R0g2RDJnV2JGUTdUNGZYand4MlUiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJxdWF5IiwiYXVkIjoicXVheS1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJuYmYiOjE3MjEzMzAzNDYsImlhdCI6MTcyMTMzMDM0NiwiZXhwIjoxNzIxMzMzOTQ2LCJzdWIiOiJxdWF5YWRtaW4iLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InF1YXkvbGlzdG9jaXJlZmVycnMiLCJhY3Rpb25zIjpbXX1dLCJjb250ZXh0Ijp7InZlcnNpb24iOjIsImVudGl0eV9raW5kIjoidXNlciIsImVudGl0eV9yZWZlcmVuY2UiOiJkZjI1M2QyNC0zZWUwLTRkODItOTcxYi1hZGYxMWYyNzBlM2IiLCJraW5kIjoidXNlciIsInVzZXIiOiJxdWF5YWRtaW4iLCJjb20uYXBvc3RpbGxlLnJvb3RzIjp7InF1YXkvbGlzdG9jaXJlZmVycnMiOiIkZGlzYWJsZWQifSwiY29tLmFwb3N0aWxsZS5yb290IjoiJGRpc2FibGVkIn19.sBR765ea-E41b2SfiIS36qoOmIZ6DEn9hvsCq3cszn6umlnKiBkc1jq6O1KlxtIhPdf8m8-xtLMJakxkKST4mJg5CHR5WG2AVExuT6nCHg9KuzOZTkafMJeUzC4lxRsrdgKXyGUaYONOALf6bW_IebSIOOVt55m83-KVz5NMHSov9VmQlPCfGnWS3pq3bG-nUaLhGRuSKc1EoGgnKlULNr9gAgzwBmB7-MGioP7NL5_IQtrbjFyBdckQuJcpcwNK78gb8MQIwI-e6WMvBT94pQkdD6bibo6zpFayFKSc6PsoO4Z4PjiON6vnD4kqEpX6rw5Yj7unv4RKjA_iHG-BoQ" }
17.4. OAuth アクセストークンの再割り当て
組織管理者は、特定の権限を持つ他のユーザーによって作成されるように OAuth API トークンを割り当てることができます。これにより、OAuth API トークンを作成する組織管理者権限を持たないユーザーがトークンを使用した場合でも、監査ログが正確に反映されるようになります。
次の手順は、現在の Red Hat Quay UI でのみ機能します。現在、Red Hat Quay v2 UI には実装されていません。
前提条件
組織管理者権限を持つユーザーとしてログインしており、OAuth API トークンを割り当てることができる。
注記OAuth API トークンは、認可ではなく認証に使用されます。たとえば、OAuth トークンを割り当てるユーザーは、管理 API エンドポイントを使用するために
Admin
チームロールを持っている必要があります。詳細は、リポジトリーへのアクセスの管理 を参照してください。
手順
オプション: まだ更新していない場合は、Red Hat Quay
config.yaml
ファイルを更新して、FEATURE_ASSIGN_OAUTH_TOKEN: true
フィールドを含めます。# ... FEATURE_ASSIGN_OAUTH_TOKEN: true # ...
- オプション: Red Hat Quay レジストリーを再起動します。
- 組織管理者として Red Hat Quay レジストリーにログインします。
- OAuth トークンを作成した組織の名前をクリックします。
- ナビゲーションペインで、Applications をクリックします。
- 適切なアプリケーション名をクリックします。
- ナビゲーションペインで、Applications をクリックします。
- Assign another user をクリックし、OAuth トークンを引き継ぐユーザーの名前を入力します。
新しいユーザーに付与する必要な権限のボックスをオンにします。たとえば、新しいユーザーにリポジトリーの作成のみを許可する場合は、Create Repositories クリックします。
重要権限の制御は、組織内のチームロールによって定義され、ここで選択したオプションに関係なく設定する必要があります。たとえば、OAuth トークンを割り当てるユーザーは、管理 API エンドポイントを使用するために
Admin
チームロールを持っている必要があります。Super User Access ボックスをオンにしただけでは、この権限がユーザーに実際に付与されるわけではありません。
config.yaml
ファイルでスーパーユーザーを設定する必要があり、かつ ここでボックスをオンにする必要があります。Assign token をクリックします。ポップアップボックスに、認可を確認する次のメッセージと、承認される権限が表示されます。
This will prompt user <username> to generate a token with the following permissions: repo:create
ポップアップボックスで Assign token をクリックします。新しいページにリダイレクトされ、次のメッセージが表示されます。
Token assigned successfully
検証
- OAuth トークンを再割り当てした後、割り当てられたユーザーがトークンを受け入れて、API エンドポイントの使用に必要なベアラートークンを受け取る必要があります。割り当てられたユーザーに、Red Hat Quay レジストリーにログインするよう依頼します。
- ユーザーは、ログインしたら、Users and Organizations の下にある自分のユーザー名をクリックする必要があります。
- ナビゲーションペインで、External Logins And Applications をクリックする必要があります。
- Authorized Applications の下で、Authorize Application をクリックしてアプリケーションを確認する必要があります。新しいページに移動し、Authorize Application をクリックして再確認する必要があります。
- ユーザーは、ベアラートークンが表示される新しいページにリダイレクトされます。このベアラートークンは再度表示することはできないため、保存する必要があります。
17.5. Web ブラウザーからの Quay API へのアクセス
Swagger を有効にし、Web ブラウザーを使用して独自の Red Hat Quay インスタンスの API にアクセスできます。この URL は、Red Hat Quay API を UI および以下の URL 経由で公開します。
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
17.6. コマンドラインでの Red Hat Quay API へのアクセス
curl
コマンドを使用して、Red Hat Quay クラスターの API を使用して GET、PUT、POST、または DELETE 操作を実行できます。<token>
は、以下の例の設定を取得または変更するために作成した OAuth アクセストークンに置き換えます。
第18章 Open Container Initiative のサポート
コンテナーレジストリーは、当初 Docker イメージ形式のコンテナーイメージをサポートするように設計されていました。Docker 以外で追加のランタイムの使用をプロモートするために、コンテナーランタイムとイメージ形式に関連する標準化を提供するために Open Container Initiative (OCI) が作成されました。ほとんどのコンテナーレジストリーは、Docker イメージマニフェスト V2、Schema 2 形式をベースとして OCI 標準化をサポートします。
コンテナーイメージのほかにも、個別のアプリケーションだけでなく、Kubernetes プラットフォームを全体としてサポートする各種のアーティファクトが新たに出現しました。これは、アプリケーションのデプロイメントを支援するセキュリティーおよびガバナンスの Open Policy Agent (OPA) ポリシーから Helm チャートおよび Operator に及びます。
Red Hat Quay は、コンテナーイメージを格納するだけでなく、コンテナーの管理を支援するツールのエコシステム全体もサポートするプライベートコンテナーレジストリーです。Red Hat Quay は、OCI 1.1 Image and Distribution specifications と可能な限り互換性を保つよう努めており、Helm チャート (OCI をサポートする Helm のバージョンを使用してプッシュされている場合に限る) などの一般的なメディアタイプや、コンテナーイメージのマニフェストまたはレイヤーコンポーネント内部のさまざまな任意のメディアタイプをサポートしています。OCI メディアタイプのサポートが、以前の Red Hat Quay のバージョンと異なる点です。以前のバージョンでは、受け入れるメディアタイプについてより厳しい制限がレジストリーに設けられていました。Red Hat Quay は、以前はサポート範囲外だったメディアタイプも含め、より幅広いメディアタイプに対応できるようになりました。そのため、標準のコンテナーイメージ形式だけでなく、新しいタイプや従来とは異なるタイプにも対応できるようになり、より多用途になりました。
新しいメディアタイプへのサポート拡張に加えて、Red Hat Quay は、V2_2 および V2_1 形式を含む Docker イメージとの互換性を確保しています。このような Docker V2_2 および V2_1 イメージとの互換性は、Docker ユーザーにシームレスなエクスペリエンスを提供するという Red Hat Quay の取り組みを表すものです。さらに、Red Hat Quay は、引き続き Docker V1 プルのサポートを拡張し、このような以前のバージョンの Docker イメージを現在も利用している可能性のあるユーザーに対応します。
OCI アーティファクトのサポートはデフォルトで有効になっています。次の例は、いくつかのメディアタイプの使用方法を示しています。これは、他の OCI メディアタイプを使用する際の例として使用できます。
18.1. Helm および OCI の前提条件
Helm は、アプリケーションのパッケージ化とデプロイの方法を簡素化します。Helm は、アプリケーションを表す Kubernetes リソースが含まれる チャート というパッケージ形式を使用します。Red Hat Quay は、OCI でサポートされているバージョンの Helm チャートをサポートします。
次の手順に従って、Helm およびその他の OCI メディアタイプを使用するようにシステムを事前設定します。
Helm の最新バージョンは、Helm リリース ページからダウンロードできます。Helm をダウンロードしたら、Red Hat Quay で使用される SSL/TLS 証明書をシステムが信頼できるようにする必要があります。
18.1.1. Red Hat Quay で使用される SSL/TLS 証明書をシステムが信頼できるようにする
Helm クライアントと Red Hat Quay の間の通信は、HTTPS 経由で促進されます。Helm 3.5 では、信頼できる証明書を使用して HTTPS 経由で通信するレジストリーのみがサポートされています。さらに、オペレーティングシステムはレジストリーで公開される証明書を信頼する必要があります。Red Hat Quay で使用される証明書を信頼するようにオペレーティングシステムが設定されていることを確認する必要があります。システムがカスタム証明書を信頼できるようにするには、次の手順を実行します。
手順
次のコマンドを入力して、
rootCA.pem
ファイルを/etc/pki/ca-trust/source/anchors/
フォルダーにコピーします。$ sudo cp rootCA.pem /etc/pki/ca-trust/source/anchors/
次のコマンドを入力して、CA トラストストアを更新します。
$ sudo update-ca-trust extract
18.2. Helm チャートの使用
以下の例を使用して、Red Hat Community of Practice (CoP) リポジトリーから etherpad チャートをダウンロードしてプッシュします。
前提条件
- Red Hat Quay にログインしている。
手順
次のコマンドを入力して、チャートリポジトリーを追加します。
$ 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 package ./etherpad
出力例
Successfully packaged chart and saved it to: /home/user/linux-amd64/etherpad-0.0.4.tgz
helm registry login
を使用して Red Hat Quay にログインします。$ helm registry login quay370.apps.quayperf370.perfscale.devcluster.openshift.com
helm push
コマンドを使用して、チャートをリポジトリーにプッシュします。$ helm push etherpad-0.0.4.tgz oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com
出力例:
Pushed: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4 Digest: sha256:a6667ff2a0e2bd7aa4813db9ac854b5124ff1c458d170b70c2d2375325f2451b
ローカルコピーを削除してから、リポジトリーからチャートをプルして、プッシュが機能したことを確認します。
$ rm -rf etherpad-0.0.4.tgz
$ helm pull oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad --version 0.0.4
出力例:
Pulled: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4 Digest: sha256:4f627399685880daf30cf77b6026dc129034d68c7676c7e07020b70cf7130902
18.3. アノテーション解析
一部の OCI メディアタイプではラベルが使用されないために、有効期限のタイムスタンプなどの重要な情報が含まれません。Red Hat Quay は、このようなメタデータ転送用のラベルを含まない OCI メディアタイプに対応するために、アノテーションを介して渡されるメタデータをサポートしています。ORAS (OCI Registry as Storage) などのツールを使用して、アーティファクトタイプに情報を埋め込むことができるようになり、失効などのイメージの適切な動作を確実に実行しやすくなりました。
次の手順では、ORAS を使用して OCI メディアアーティファクトに有効期限を追加します。
podman push
でイメージをプッシュしてから、oras
でアノテーションを追加すると、MIME タイプが変更されます。これにより、Podman がその MIME タイプを認識しなくなるため、podman pull
を使用して同じイメージをプルできなくなります。
前提条件
-
oras
CLI をダウンロードした。詳細は、Installation を参照してください。 - OCI メディアアーティファクトを Red Hat Quay リポジトリーにプッシュした。
手順
デフォルトでは、
application/vnd.oci.image.manifest.v1+json
などの一部の OCI メディアタイプは、有効期限のタイムスタンプなど、特定のラベルを使用しません。ORAS (oras
) などの CLI ツールを使用して、OCI メディアタイプにアノテーションを追加できます。以下に例を示します。$ oras push --annotation "quay.expires-after=2d" \ 1 --annotation "expiration = 2d" \ 2 quay.io/<organization_name>/<repository>/<image_name>:<tag>
出力例
✓ Exists application/vnd.oci.empty.v1+json 2/2 B 100.00% 0s └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a ✓ Uploaded application/vnd.oci.image.manifest.v1+json 561/561 B 100.00% 511ms └─ sha256:9b4f2d43b62534423894d077f0ff0e9e496540ec8b52b568ea8b757fc9e7996b Pushed [registry] quay.io/stevsmit/testorg3/oci-image:v1 ArtifactType: application/vnd.unknown.artifact.v1 Digest: sha256:9b4f2d43b62534423894d077f0ff0e9e496540ec8b52b568ea8b757fc9e7996b
検証
oras
でイメージをプルします。以下に例を示します。$ oras pull quay.io/<organization_name>/<repository>/<image_name>:<tag>
oras を
使用して変更を検査します。以下に例を示します。$ oras manifest fetch quay.io/<organization_name>/<repository>/<image_name>:<tag>
出力例
{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="}],"annotations":{"org.opencontainers.image.created":"2024-07-11T15:22:42Z","version ":" 8.11"}}
18.4. イメージタグへのリファラーの割り当て
次の手順では、oras
CLI を使用して、OCI ディストリビューション仕様 1.1 でサポートされているさまざまなスキーマを使用して、イメージタグにリファラーを割り当てる方法を示します。これは、コンテナーイメージへのリファラーなど、追加のメタデータを割り当ておよび管理するのに役立ちます。
前提条件
-
oras
CLI をダウンロードした。詳細は、Installation を参照してください。 - OCI メディアアーティファクトにアクセスできる。
手順
次のコマンドを入力して、OCI メディアアーティファクトにタグを付けます。
$ podman tag <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>
アーティファクトを Red Hat Quay レジストリーにプッシュします。以下に例を示します。
$ podman push <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>
oras
で OCI 1.1 リファラーのAPI
スキーマを使用してマニフェストを割り当てるには、次のコマンドを入力します。$ oras attach --artifact-type <MIME_type> --distribution-spec v1.1-referrers-api <myartifact_image> \ <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag> \ <example_file>.txt
出力例
-spec v1.1-referrers-api quay.io/testorg3/myartifact-image:v1.0 hi.txt ✓ Exists hi.txt 3/3 B 100.00% 0s └─ sha256:98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4 ✓ Exists application/vnd.oci.empty.v1+json 2/2 B 100.00% 0s └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a ✓ Uploaded application/vnd.oci.image.manifest.v1+json 723/723 B 100.00% 677ms └─ sha256:31c38e6adcc59a3cfbd2ef971792aaf124cbde8118e25133e9f9c9c4cd1d00c6 Attached to [registry] quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da Digest: sha256:31c38e6adcc59a3cfbd2ef971792aaf124cbde8118e25133e9f9c9c4cd1d00c6
OCI 1.1 リファラーの
tag
スキーマを使用してマニフェストを割り当てるには、次のコマンドを入力します。$ oras attach --artifact-type <MIME_type> --distribution-spec v1.1-referrers-tag \ <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag> \ <example_file>.txt
出力例
✓ Exists hi.txt 3/3 B 100.00% 0s └─ sha256:98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4 ✓ Exists application/vnd.oci.empty.v1+json 2/2 B 100.00% 0s └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a ✓ Uploaded application/vnd.oci.image.manifest.v1+json 723/723 B 100.00% 465ms └─ sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383 Attached to [registry] quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da Digest: sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383
tag
スキーマを使用してアーティファクトのリファラーを検出するには、次のコマンドを入力します。$ oras discover --insecure --distribution-spec v1.1-referrers-tag \ <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>
出力例
quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da └── doc/example └── sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383
API
スキーマを使用してアーティファクトのリファラーを検出するには、次のコマンドを入力します。$ oras discover --distribution-spec v1.1-referrers-api \ <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>
出力例
Discovered 3 artifacts referencing v1.0 Digest: sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da Artifact Type Digest sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383 sha256:22b7e167793808f83db66f7d35fbe0088b34560f34f8ead36019a4cc48fd346b sha256:bb2b7e7c3a58fd9ba60349473b3a746f9fe78995a88cb329fc2fd1fd892ea4e4
オプション:
/v2/<organization_name>/<repository_name>/referrers/<sha256_digest>
エンドポイントを使用してリファラーを検出することもできます。これを機能させるには、v2 API トークンを生成し、config.yaml
ファイルでFEATURE_REFERRERS_API: true
を設定する必要があります。config.yaml
ファイルを更新して、FEATURE_REFERRERS_API
フィールドを含めます。以下に例を示します。# ... FEATURE_REFERRERS_API: true # ...
次のコマンドを入力し、認証情報を Base64 でエンコードします。
$ echo -n '<username>:<password>' | base64
出力例
abcdeWFkbWluOjE5ODlraWROZXQxIQ==
次のコマンドを入力して、base64 でエンコードされたトークンを使用し、URL エンドポイントを Red Hat Quay サーバーに変更します。
$ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq
出力例
{ "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijl5RWNtWmdiZ0l6czBBZW16emhTMHM1R0g2RDJnV2JGUTdUNGZYand4MlUiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJxdWF5IiwiYXVkIjoicXVheS1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJuYmYiOjE3MjEzMzAzNDYsImlhdCI6MTcyMTMzMDM0NiwiZXhwIjoxNzIxMzMzOTQ2LCJzdWIiOiJxdWF5YWRtaW4iLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InF1YXkvbGlzdG9jaXJlZmVycnMiLCJhY3Rpb25zIjpbXX1dLCJjb250ZXh0Ijp7InZlcnNpb24iOjIsImVudGl0eV9raW5kIjoidXNlciIsImVudGl0eV9yZWZlcmVuY2UiOiJkZjI1M2QyNC0zZWUwLTRkODItOTcxYi1hZGYxMWYyNzBlM2IiLCJraW5kIjoidXNlciIsInVzZXIiOiJxdWF5YWRtaW4iLCJjb20uYXBvc3RpbGxlLnJvb3RzIjp7InF1YXkvbGlzdG9jaXJlZmVycnMiOiIkZGlzYWJsZWQifSwiY29tLmFwb3N0aWxsZS5yb290IjoiJGRpc2FibGVkIn19.sBR765ea-E41b2SfiIS36qoOmIZ6DEn9hvsCq3cszn6umlnKiBkc1jq6O1KlxtIhPdf8m8-xtLMJakxkKST4mJg5CHR5WG2AVExuT6nCHg9KuzOZTkafMJeUzC4lxRsrdgKXyGUaYONOALf6bW_IebSIOOVt55m83-KVz5NMHSov9VmQlPCfGnWS3pq3bG-nUaLhGRuSKc1EoGgnKlULNr9gAgzwBmB7-MGioP7NL5_IQtrbjFyBdckQuJcpcwNK78gb8MQIwI-e6WMvBT94pQkdD6bibo6zpFayFKSc6PsoO4Z4PjiON6vnD4kqEpX6rw5Yj7unv4RKjA_iHG-BoQ" }
リポジトリー配下のマニフェストの OCI リファラーをリスト表示するには、v2 API トークンを使用して次のコマンドを入力します。
$ GET https://<quay-server.example.com>/v2/<organization_name>/<repository_name>/referrers/sha256:0de63ba2d98ab328218a1b6373def69ec0d0e7535866f50589111285f2bf3fb8 --header 'Authorization: Bearer <v2_bearer_token> -k | jq
出力例
{ "schemaVersion": 2, "mediaType": "application/vnd.oci.image.index.v1+json", "manifests": [ { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383", "size": 793 }, ] }