이 문서에서는 Container Registry에서 pkg.dev Artifact Registry 저장소로 전환하는 데 필요한 단계를 설명합니다.
대부분의 Container Registry 사용자는 pkg.dev 저장소가 아닌 Artifact Registry에서 호스팅되는 gcr.io 저장소로 전환해야 하므로 Artifact Registry의 gcr.io 저장소와 pkg.dev 저장소의 차이점을 이해하는 경우에만 이 안내를 따르세요.
자동 마이그레이션 도구는 선택한 전환 경로에 따라 다음 작업을 수행할 수 있습니다.
해당 리전의 gcr.io 프로젝트에 대해 Artifact Registry에 pkg.dev 저장소를 만듭니다.
저장소에 대한 IAM 정책을 제안하고 사용자 환경설정에 따라 정책을 적용하거나 애플리케이션을 건너뜁니다.
Container Registry에 저장된 모든 컨테이너 이미지를 Artifact Registry pkg.dev 저장소에 복사합니다.
Artifact Registry 서비스 계정에 Container Registry에서 Artifact Registry로 이미지를 복사하는 데 필요한 권한이 있는지 확인하려면 관리자에게 Artifact Registry 서비스 계정에 Container Registry 프로젝트에 대한 스토리지 객체 뷰어 (roles/storage.objectViewer) IAM 역할을 부여해 달라고 요청하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis document provides instructions for migrating from Container Registry to \u003ccode\u003epkg.dev\u003c/code\u003e Artifact Registry repositories, a transition path that is specifically for users who understand the difference between \u003ccode\u003egcr.io\u003c/code\u003e and \u003ccode\u003epkg.dev\u003c/code\u003e repositories within Artifact Registry.\u003c/p\u003e\n"],["\u003cp\u003eThe automatic migration tool can create a \u003ccode\u003epkg.dev\u003c/code\u003e repository, suggest and optionally apply an IAM policy, and copy container images from Container Registry to the new Artifact Registry repository.\u003c/p\u003e\n"],["\u003cp\u003eBefore initiating the migration, you must install and initialize the Google Cloud CLI, and enable the Artifact Registry API.\u003c/p\u003e\n"],["\u003cp\u003eThe migration requires specific roles, including the Storage Object Viewer role for the Artifact Registry service account and the Artifact Registry Container Registry Migration Admin role for the user account, on the relevant projects or organization.\u003c/p\u003e\n"],["\u003cp\u003eYou can use the \u003ccode\u003egcloud artifacts docker upgrade migrate\u003c/code\u003e command to perform the migration, and if you only want to copy images, you can use the \u003ccode\u003e--copy-only\u003c/code\u003e flag for that specific purpose.\u003c/p\u003e\n"]]],[],null,["This document describes the steps necessary to transition from Container Registry\nto `pkg.dev` Artifact Registry repositories.\n\nMost Container Registry users should transition to\n[`gcr.io` repositories hosted on Artifact Registry](/artifact-registry/docs/transition/auto-migrate-gcr-ar), not\n`pkg.dev` repositories, so only follow these instructions if you understand the\ndifference between `gcr.io` repositories and `pkg.dev` repositories in\nArtifact Registry.\n\nThe automatic migration tool can perform the following actions depending on\nthe transition path you choose:\n\n- Create a `pkg.dev` repository in Artifact Registry for your `gcr.io` project in the corresponding region.\n- Suggest an IAM policy for the repository and apply the policy or skip application depending on user preference.\n- Copy all container images stored in Container Registry to your Artifact Registry `pkg.dev` repository.\n\nBefore you begin\n\n1. [Install](/sdk/docs/install) the Google Cloud CLI. After installation, [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command: \n\n```bash\ngcloud init\n```\n2. If you're using an external identity provider (IdP), you must first [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n| **Note:** If you installed the gcloud CLI previously, make sure you have the latest version by running `gcloud components update`.\n3.\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=artifactregistry.googleapis.com)\n\n The auto-migration tool prompts you to enable the Artifact Registry API if you skip this step. \n\nRequired roles\n\nThe following roles are required for all transition options using the automatic\nmigration tool.\n\n**Service account roles**:\n\nYou must grant the following roles to the\n[Artifact Registry service account](/artifact-registry/docs/ar-service-account) for each project you want to\nmigrate to Artifact Registry.\n\n\nTo ensure that the Artifact Registry service account has the necessary\npermissions to copy images from Container Registry to Artifact Registry,\n\nask your administrator to grant the Artifact Registry service account the\n\n\n[Storage Object Viewer](/iam/docs/roles-permissions/storage#storage.objectViewer) (`roles/storage.objectViewer`)\nIAM role on the Container Registry project.\n\n\n| **Important:** You must grant this role to the Artifact Registry service account, *not* to your user account. Failure to grant the role to the correct principal might result in permission errors.\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\u003cbr /\u003e\n\n\nYour administrator might also be able to give the Artifact Registry service account\nthe required permissions through [custom\nroles](/iam/docs/creating-custom-roles) or other [predefined\nroles](/iam/docs/roles-overview#predefined).\n\n**User roles**:\n\n\nTo get the permissions that\nyou need to transition to `pkg.dev` Artifact Registry repositories,\n\nask your administrator to grant you the\n\n\n[Artifact Registry Container Registry Migration Admin role](/iam/docs/roles-permissions/artifactregistry#artifactregistry.containerRegistryMigrationAdmin) (`roles/artifactregistry.containerRegistryMigrationAdmin`)\nIAM role on the Google Cloud organization or project you want to migrate.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nYou might also be able to get\nthe required permissions through [custom\nroles](/iam/docs/creating-custom-roles) or other [predefined\nroles](/iam/docs/roles-overview#predefined).\n\nMigrate to `pkg.dev` Artifact Registry repositories\n\n1. To migrate your `gcr.io` project to a `pkg.dev` Artifact Registry\n repository, run the following command:\n\n gcloud artifacts docker upgrade migrate \\\n --from-gcr=\u003cvar translate=\"no\"\u003eGCR_HOSTNAME\u003c/var\u003e/\u003cvar translate=\"no\"\u003eGCR_PROJECT\u003c/var\u003e \\\n --to-pkg-dev=\u003cvar translate=\"no\"\u003eAR_PROJECT\u003c/var\u003e/\u003cvar translate=\"no\"\u003eAR_REPOSITORY\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eGCR_HOSTNAME\u003c/var\u003e with the Container Registry hostname. The hostname\n depends on where your container images are stored:\n\n - `gcr.io` hosts the images in the United States.\n - `us.gcr.io` hosts the images in the United States, in a separate storage bucket from images hosted by `gcr.io`.\n - `eu.gcr.io` hosts the images within [member states](https://europa.eu/european-union/about-eu/countries_en) of the European Union.\n - `asia.gcr.io` hosts the images in Asia.\n - \u003cvar translate=\"no\"\u003eGCR_PROJECT\u003c/var\u003e with your Container Registry Google Cloud\n [project ID](/resource-manager/docs/creating-managing-projects#identifying_projects). If your project ID contains a colon (`:`),\n see [Domain-scoped projects](/artifact-registry/docs/docker/names#domain).\n\n - \u003cvar translate=\"no\"\u003eAR_PROJECT\u003c/var\u003e with the Google Cloud project ID where you enabled\n the Artifact Registry API.\n\n - \u003cvar translate=\"no\"\u003eAR_REPOSITORY\u003c/var\u003e with the name for your Artifact Registry repository.\n\nThe migration tool completes the following steps:\n\n- Creates the Artifact Registry repository if the repository doesn't already exist.\n- Suggests an IAM policy for the repository, and applies the policy or skips application depending on user preference.\n- Copies images in the specified Container Registry region and project to your Artifact Registry repository.\n\nIf you only want to copy images pulled from Container Registry in the last 30 to\n180 days, you can include the `--recent-images=`\u003cvar translate=\"no\"\u003eDAYS\u003c/var\u003e flag.\nReplace \u003cvar translate=\"no\"\u003eDAYS\u003c/var\u003e with the number of days, between 30 and 150, that the\ntool should check for pulls within.\n\nIf you encounter errors or timeouts, you can safely re-run the command, and\ncompleted steps are skipped.\n\nCopy images\n\nThe migration tool automatically copies your container images when you run it,\nbut if you want to skip all other steps of the automatic migration, and use the\ntool to copy images to Artifact Registry you can pass the `--copy-only`\nflag.\n\nTo copy images from Container Registry to a `pkg.dev` Artifact Registry repository,\nrun the following command: \n\n gcloud artifacts docker upgrade migrate \\\n --from-gcr=\u003cvar translate=\"no\"\u003eGCR_HOSTNAME\u003c/var\u003e/\u003cvar translate=\"no\"\u003eGCR_PROJECT\u003c/var\u003e \\\n --to-pkg-dev=\u003cvar translate=\"no\"\u003eAR_PROJECT\u003c/var\u003e/\u003cvar translate=\"no\"\u003eAR_REPOSITORY\u003c/var\u003e \\\n --copy-only\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eGCR_HOSTNAME\u003c/var\u003e with the Container Registry hostname. The hostname\n depends on where your container images are stored:\n\n - `gcr.io` hosts the images in the United States.\n - `us.gcr.io` hosts the images in the United States, in a separate storage bucket from images hosted by `gcr.io`.\n - `eu.gcr.io` hosts the images within [member states](https://europa.eu/european-union/about-eu/countries_en) of the European Union.\n - `asia.gcr.io` hosts the images in Asia.\n- \u003cvar translate=\"no\"\u003eGCR_PROJECT\u003c/var\u003e with your Container Registry Google Cloud\n [project ID](/resource-manager/docs/creating-managing-projects#identifying_projects). If your project ID contains a colon (`:`),\n see [Domain-scoped projects](/artifact-registry/docs/docker/names#domain).\n\n- \u003cvar translate=\"no\"\u003eAR_PROJECT\u003c/var\u003e with the Google Cloud project ID where you enabled\n the Artifact Registry API.\n\n- \u003cvar translate=\"no\"\u003eAR_REPOSITORY\u003c/var\u003e with the name for your Artifact Registry repository.\n\nThe tool skips all migration steps, and copies images from the specified\nlocation and project in Container Registry to your Artifact Registry repository.\n\nYou can also use the `--copy-only` flag to restart copying images if you have an\nerror or timeout during the process.\n\nWhat's next\n\n- [Learn about the differences between Container Registry and Artifact Registry for authenticating, pushing, and pulling images with Docker](/artifact-registry/docs/transition/changes-docker)."]]
