[[["容易理解","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-02 (世界標準時間)。"],[[["\u003cp\u003eThe automatic migration tool facilitates a seamless transition from Container Registry to \u003ccode\u003egcr.io\u003c/code\u003e repositories on Artifact Registry without service interruptions.\u003c/p\u003e\n"],["\u003cp\u003eThis tool automates the creation of \u003ccode\u003egcr.io\u003c/code\u003e repositories in Artifact Registry, suggests and optionally applies IAM policies, redirects traffic, and copies container images.\u003c/p\u003e\n"],["\u003cp\u003eTo initiate migration, users need to install and initialize the Google Cloud CLI, and ensure the Artifact Registry API is enabled.\u003c/p\u003e\n"],["\u003cp\u003eBoth service accounts and users require specific IAM roles, such as Storage Object Viewer and Artifact Registry Container Registry Migration Admin, to perform the migration.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egcloud artifacts docker upgrade migrate\u003c/code\u003e command can migrate single or multiple projects, with options to copy only recently pulled or uploaded images.\u003c/p\u003e\n"]]],[],null,["# Automatically migrate from Container Registry to Artifact Registry\n\nUse the automatic migration tool to transition from Container Registry to\n`gcr.io` repositories hosted on Artifact Registry.\n\nMigration to Artifact Registry `gcr.io` repositories can be performed on\nContainer Registry endpoints receiving traffic without requiring any downtime or\nservice disruption.\n\nThe automatic migration tool can perform the following actions:\n\n- Create `gcr.io` repositories in Artifact Registry for each of your listed `gcr.io` projects in the corresponding region.\n- Suggest an IAM policy for each repository and apply the policy or skip application depending on user preference.\n- Redirect all traffic from `gcr.io` endpoints to Artifact Registry.\n- Copy all container images stored in Container Registry to your Artifact Registry `gcr.io` repositories, even if you have already enabled redirection.\n\nBefore you begin\n----------------\n\n1.\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n | **Note:** If you installed the gcloud CLI previously, make sure you have the latest version by running `gcloud components update`.\n2. If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n\n3.\n To [initialize](/sdk/docs/initializing) the gcloud CLI, run the following command:\n\n ```bash\n gcloud init\n ```\n4. \n5.\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=artifactregistry.googleapis.com)\n\nThe auto-migration tool prompts you to enable the Artifact Registry API if you skip this step. \n\n### Required roles\n\nThe following roles are required for transitioning to `gcr.io` repositories\nin Artifact Registry using the automatic migration tool.\n\n**Service account roles**:\n\nYou can use the `gcr.io` migration service account with the email address of\n`artifact-registry-same-project-copier@system.gserviceaccount.com`\nor the [Artifact Registry service account](/artifact-registry/docs/ar-service-account) to transition to `gcr.io`\nrepositories in Artifact Registry.\n\n\nTo ensure that the service account you are using for the migration has the necessary\npermissions to copy images from Container Registry to Artifact Registry,\n\nask your administrator to grant the service account you are using for the migration the\n\n\n[Storage Object Viewer](/iam/docs/roles-permissions/storage#storage.objectViewer) (`roles/storage.objectViewer`)\nIAM role on the Container Registry project, folder, or organization.\n\n\n| **Important:** You must grant this role to the service account you are using for the migration, *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 service account you are using for the migration\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 `gcr.io` repositories hosted on Artifact Registry,\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 `gcr.io` repositories hosted on Artifact Registry\n------------------------------------------------------------\n\nYou can migrate a single Google Cloud project, or multiple Google Cloud projects\nat the same time using the\n[`gcloud artifacts docker upgrade migrate`](/sdk/gcloud/reference/artifacts/docker/upgrade/migrate) command.\n\nTo migrate to `gcr.io` repositories, run the following command. \n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e\n\nWhere \u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e is the project ID of a single project you want to\nmigrate to `gcr.io` repositories hosted on Artifact Registry, or a comma-separated\nlist of project IDs that you want to migrate to `gcr.io` repositories hosted on\nArtifact Registry.\n\nThe migration tool completes the following steps:\n\n- Creates `gcr.io` repositories in Artifact Registry for each of your listed `gcr.io` projects in the corresponding region.\n- Suggests an IAM policy for each repository, and applies the policy or skips application depending on user preference.\n- Redirects all traffic from `gcr.io` endpoint to Artifact Registry. Artifact Registry temporarily serves missing images by copying them from Container Registry at request time until all container images are copied to Artifact Registry.\n- Copies all container images stored in your `gcr.io` buckets to the newly created `gcr.io` repositories hosted on Artifact Registry.\n- Disables request-time copying. The `gcr.io` repository hosted on Artifact Registry no longer depends on Container Registry.\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 180, that the\ntool should check for pulls within.\n\nIf you want to copy a specific number of recently uploaded version of each\nimage, you can include the `--last-uploaded-versions=`\u003cvar translate=\"no\"\u003eVERSIONS\u003c/var\u003e\nflag. Replace \u003cvar translate=\"no\"\u003eVERSIONS\u003c/var\u003e with the number of versions you want to copy\nfor each image. If new images are uploaded during copying, more than the number\nof versions specified might be copied.\n\nThe `--recent-images` flag and the `--last-uploaded-versions` flag are mutually\nexclusive and can't be used together.\n\nIf you encounter errors or timeouts, you can safely re-run the command, and\ncompleted steps are skipped.\n\nMigrate slower with canary reads\n--------------------------------\n\nYou can use the `--canary-reads` flag to rollout only a percent of reads,\nand no writes, to Artifact Registry. Missing images pulled from\nArtifact Registry are copied from Container Registry at request time.\n\nMigrating with canary reads has two advantages:\n\n- The rollout to Artifact Registry can be tested on a much smaller number of requests first.\n- Images are still pushed to Container Registry during most of the process, so it's safer to rollback.\n\nWe recommend the following procedure:\n\n1. To set the percentage of canary reads to 1 percent, run the following\n command:\n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e \\\n --canary-reads=1\n\n2. Confirm that everything is still working correctly.\n\n3. To set the percentage of canary reads to 10 percent, run the following\n command :\n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e \\\n --canary-reads=10\n\n4. Confirm that everything is still working correctly.\n\n5. To set canary reads to 100 percent, run the following command:\n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e \\\n --canary-reads=100\n\nAt this point, all reads are sent to Artifact Registry and all writes are\nstill sent to Container Registry.\n\nTo complete the migration, send writes to Artifact Registry as well by\nrunning the `artifacts docker upgrade migrate` command without the\n`--canary-reads` flag: \n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e\n\nRollback canary reads\n---------------------\n\nTo rollback canary reads, run the following command: \n\n gcloud artifacts docker upgrade migrate \\\n --projects=\u003cvar translate=\"no\"\u003ePROJECTS\u003c/var\u003e \\\n --canary-reads=0\n\nCanary reads is also disabled when running the `gcloud artifacts settings disable-upgrade-redirection` or `gcloud artifacts settings enable-upgrade-redirection` commands.\n\nAnalyzeIamPolicy Quota\n----------------------\n\nIf you are migrating large numbers of projects and run out of\n[AnalyzeIamPolicy quota](/policy-intelligence/docs/quotas#policy-analyzer-quotas),\nthen you can use the `--no-use-analyze-iam` flag. Using the\n`--no-use-analyze-iam` flag for migration is slower than without using it,\nbut avoids sending requests against the AnalyzeIamPolicy quota.\n\nWhat's next\n-----------\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)."]]
