ここでは、Container Registry と Docker の一般的な問題のトラブルシューティング方法について説明します。
ドメインをスコープとするプロジェクト
エラー invalid reference format
が表示された場合、ドメインをスコープとするプロジェクトがある可能性があります。
プロジェクトでドメインをスコープとしている場合、プロジェクト ID にドメインとコロンが含まれます(例: example.com:my-project
)。ドメインが含まれるプロジェクト ID の処理方法については、ドメインをスコープとするプロジェクトをご覧ください。
エラー: ステータス 405: v1 Registry API is disabled.
イメージを pull または push するときに「v1 Registry API is disabledv」などのエラーが連続して発生する場合は、ホスト名、プロジェクト ID、イメージ名、タグ、ダイジェストのスペルが正しいことを確認してください。
イメージのタグとダイジェストを表示するには、次のコマンドを実行します。
gcloud container images list-tags [HOSTNAME]/[PROJECT-ID]/[IMAGE]
例:
gcloud container images list-tags gcr.io/my-project/my-image
イメージのタグとダイジェストを表示する方法について詳しくは、イメージの管理をご覧ください。
権限の問題
以下のセクションでは、特定の権限の問題が発生した場合の解決方法を説明します。push または pull に必要な権限があることを必ず確認してください。権限と役割をご覧ください。
均一なバケットレベルのアクセスに関連する権限の問題
Container Registry で使用されているストレージ バケットで均一なバケットレベルのアクセスを有効にしている場合、Container Registry に対して push または pull を行うときにアクセス権の問題が生じることがあります。
アクセス権の問題を解決するには、push または pull に必要な権限を取得する必要があります。必要な権限については、権限と役割をご覧ください。
ローカルマシン上での Docker 設定に関する権限の問題
次の例のように、permission denied
エラーが発生した場合:
FATA[0000] Post http://var/run/docker.sock/v1.17/images/gcr.io/container-engine-docs/example/push?tag=: dial unix /var/run/docker.sock: permission denied
ERROR: (gcloud.docker) A Docker command did not run successfully.
Tried to run: 'docker push gcr.io/container-engine-docs/example'
Exit code: 1
この問題は、docker
ユーザー グループに自分のユーザー名を追加すると解決する可能性があります。
シェルまたはターミナル ウィンドウで次のコマンドを実行します。
sudo usermod -a -G docker ${USER}
docker
ユーザー グループに自分のユーザー名を追加したら、システムを再起動します。
Container Registry と通信する際の権限の問題
以下のような権限エラーが発生することがあります。
Permission denied: Unable to create the repository, please check that you have access to do so
プロジェクトで課金が有効になっていることを確認します。
アクセス権を確認します。
次のコマンドを実行して、
gcloud
で認証されていることを確認します。gcloud init
次のコマンドを実行して、Container Registry 認証情報ヘルパーとして
gcloud
を使用するように Docker が構成されていることを確認します。gcloud auth configure-docker
docker-credential-gcloud
を実行できることを確認します。docker-credential-gcloud list
キーの 1 つとしてターゲット レジストリがある JSON オブジェクトが表示されます。例:
{ "https://asia.gcr.io": "oauth2accesstoken", "https://eu.gcr.io": "oauth2accesstoken", "https://gcr.io": "oauth2accesstoken", "https://us.gcr.io": "oauth2accesstoken" }
次に、push 先のプロジェクトで Cloud Storage に対する書き込み権限があることを確認します。書き込み権限がない場合は、管理者にこの権限を付与してもらってから、もう一度お試しください。
適切な権限が付与されても問題が解決されない場合は、アクセス トークンを取得する際に、次のいずれかのスコープが使用されていない可能性があります。
https://www.googleapis.com/auth/devstorage.read_write
https://www.googleapis.com/auth/devstorage.full_control
これがエラーの原因となっているかどうかを確認するには、まず、自分でアクセス トークンを取得します。アプリケーションによって異なりますが、たとえば Compute Engine のデフォルト サービス アカウントから取得したアクセス トークンを使用している場合は、アクセス トークンを取得するための手順に従います。
アクセス トークンを取得した後、次のコマンドを使用することで、アクセス トークンを取得する際に使用されたスコープを確認できます。
curl -H "Authorization: Bearer <your access token>" https://www.googleapis.com/oauth2/v1/tokeninfo
上述のスコープが含まれていない場合、問題を解決するには、コードでアクセス トークンを取得する際にスコープが含まれるようにしてください。たとえば、Compute Engine 仮想マシン上でデフォルト サービス アカウント専用に生成されたトークンの場合、その仮想マシンのスコープ設定を修正してからトークンを再作成する必要があります。
イメージの push と pull に関する権限の問題
Container Registry ストレージ バケットにアクセスするには、イメージを push または pull する VM インスタンスに、必要な IAM 権限とアクセス スコープを構成する必要があります。必要な設定については、Google Cloud での Container Registry の使用をご覧ください。
Google Kubernetes Engine からの ImagePullBackoff エラー
レジストリからイメージを pull できない場合、GKE は ImagePullBackoff
エラーを返します。このエラーは、イメージが見つからないか、レジストリから pull する権限がノードにないために発生することがあります。デフォルトでは、レジストリがノードと同じ Google Cloud プロジェクトにある場合、Container Registry からイメージを pull する権限が GKE ノードに付与されます。
GKE のドキュメントには、その根本原因を特定し、問題を解決するための手順が記載されています。
組織のポリシーの適用
組織のポリシーの制約が、Container Registry が使用するサービスに適用されると、Container Registry の使用に影響する可能性があります。これには、顧客管理の暗号鍵(CMEK)の使用を必要とする制約が含まれます。
イメージを push する際の不正なリクエスト エラー
Cloud Storage API が制約 constraints/gcp.restrictNonCmekServices
の Deny
ポリシーリストに含まれている場合、基盤となるストレージ バケットが CMEK で暗号化されていないと、イメージを Container Registry に push できません。次のメッセージが返されます。
unknown: Bad Request
constraints/gcp.restrictCmekCryptoKeyProjects
が構成されている場合は、許可されたプロジェクト、フォルダ、または組織の CryptoKey を使用してストレージ バケットを暗号化する必要があります。遵守していない既存のバケットは、デフォルトで必要な鍵を使用するように構成する必要があります。
ストレージ バケットを暗号化するには、Cloud Storage の手順をご覧ください。レジストリ ホストのバケット名の形式は、次のいずれかです。
artifacts.PROJECT-ID.appspot.com
(イメージがホストgcr.io
に保存されている場合)asia.gcr.io
、eu.gcr.io
、us.gcr.io
に保存されているイメージの場合はSTORAGE-REGION.artifacts.PROJECT-ID.appspot.com
。
gcr Pub/Sub トピックは自動的に作成されませんでした
Google Cloud プロジェクトで Container Registry API を有効にすると、Container Registry は Google が管理する暗号鍵を使用して、トピック ID が gcr
である Pub/Sub トピックを自動的に作成しようとします。
Pub/Sub API が制約 constraints/gcp.restrictNonCmekServices
の Deny
ポリシーリストに含まれている場合、トピックは CMEK で暗号化する必要があります。CMEK 暗号化なしでトピックを作成するリクエストは失敗します。
CMEK 暗号化を使用して gcr
トピックを作成するには、Pub/Sub のトピックを暗号化する手順をご覧ください。
割り当て上限
Container Registry の割り当て上限を超えると、次のようなエラー メッセージが表示されることがあります。
Error: Status 429 trying to pull repository [...] "Quota Exceeded."
固定割り当て上限を超えるのを避けるには、次のようにします。
- Container Registry と通信する IP アドレスの数を増やします。割り当ては IP アドレス単位です。
- 遅延を導入する再試行を追加します。たとえば、指数バックオフを使用できます。
boot2docker での無効なレジストリ エンドポイント
boot2docker 環境から Container Registry に到達する際に問題が発生したときは、次のようにします。
docker push gcr.io/example/sample
Error response from daemon: invalid registry endpoint https://gcr.io/v0/:
unable to ping registry endpoint https://gcr.io/v0/
v2 ping attempt failed with error: Get https://gcr.io/v2/:
x509: certificate has expired or is not yet valid
v1 ping attempt failed with error: Get https://gcr.io/v1/_ping:
x509: certificate has expired or is not yet valid.
If this private registry supports only HTTP or HTTPS with an unknown CA
certificate, please add `--insecure-registry gcr.io` to the daemon's
arguments. In the case of HTTPS, if you have access to the registry's CA
certificate, no need for the flag; simply place the CA certificate at
/etc/docker/certs.d/gcr.io/ca.crt
boot2docker の再起動が必要になることがあります。
boot2docker stop
boot2docker start
ルートレベルのイメージの push に関するエラー
コンテナ イメージを push しようとすると、以下のようなメッセージが表示されて push が失敗します。
Pushing to root-level images is disabled
このメッセージは、イメージにホスト名とイメージでタグを付けしたが、プロジェクト ID が指定されていなかったことを示しています。
次のような正しいイメージパス形式を使用してイメージにタグ付けします。
HOSTNAME/PROJECT-ID/IMAGE:TAG
例: gcr.io/web-project/web-app:1.0
。
Mac 上の Docker
Mac 上の Docker で問題が発生した場合は、回避策を試すことが必要になる場合があります。Mac 上では、Docker push/pull 操作に応答していないことが原因のエラーや、または次のようなネットワーク エラーが発生する場合があります。
Post https://us.gcr.io/v2/[repo name]/blobs/uploads/: dial tcp xx.xxx.xx.xx:xxx: i/o timeout
このようなエラーが発生した場合の手順は次のとおりです。
Mac ターミナルで
docker-machine restart default
コマンドを実行して、Docker デーモンを再起動します。Docker の [設定] メニューで [macOS キーチェーンに Docker ログインを安全に保存する] が有効になっていないことを確認します。
最新の Docker バージョンを実行していることを確認します。