本頁說明如何使用 Managed Service for Microsoft Active Directory 中的自動網域加入功能，將 Windows Compute Engine VM 執行個體加入網域。
自動將 Windows VM 加入網域的 Microsoft AD 管理服務
如要使用受管理的 Microsoft AD 驗證在 VM 上執行的應用程式，您必須將 VM 加入受管理的 Microsoft AD 網域。網域加入程序通常需要執行一些手動步驟。
建立或更新 Windows Compute Engine VM 時，您可以使用指令碼自動執行手動方法，將 VM 加入 Managed Microsoft AD 網域。不過，如要在 Compute Engine VM 上執行這些指令碼，您需要 AD 憑證 (需要安全地儲存及維護)，以及可佈建及執行這些指令碼的環境。如要避免使用憑證和額外服務，您可以使用 Managed Microsoft AD 提供的現成指令碼，自動執行網域加入程序。
建立 Compute Engine VM 時，您可以使用指令碼將 VM 自動加入 Managed Microsoft AD 網域。Compute Engine 建立 VM 後，受管理的 Microsoft AD 會啟動網域加入要求，並嘗試將 VM 加入您的網域。如果網域加入要求成功，Managed Microsoft AD 就會將建立的 VM 加入網域。如果網域加入要求失敗，則已建立的 VM 會繼續執行。為了安全或帳單目的，您可以自訂這項行為，而 Managed Microsoft AD 可以在網域加入要求失敗時停止 VM。
更新 Compute Engine VM 時，您可以使用指令碼自動將現有 VM 加入 Managed Microsoft AD 網域。為了讓網域加入要求成功，Managed Microsoft AD 會在執行指令碼後重新啟動 VM。
在 Managed Microsoft AD 網域和 VM 網路之間設定網域對等互連，或是讓 Managed Microsoft AD 網域和 VM 位於同一個網路中。
在設有 Managed Microsoft AD 網域的專案中，建立具備 Google Cloud Managed Identities Domain Join (roles/managedidentities.domainJoin) IAM 角色的服務帳戶。詳情請參閱「Cloud 管理式身分識別資訊角色」。
使用這個中繼資料鍵，以 projects/PROJECT_ID/locations/global/domains/DOMAIN_NAME 的格式指定要加入的受管理 Microsoft AD 網域完整資源名稱：例如：projects/my-project-123/locations/global/domains/my-domain.example.com。
managed-ad-domain-join-failure-stop
選用：根據預設，即使網域加入要求失敗，VM 仍會繼續執行。如果您想在要求失敗時停止 VM，可以將這個中繼資料鍵值設為 TRUE。設定這個中繼資料鍵值後，受管理的 Microsoft AD 可以停止 VM，但不會刪除 VM。
enable-guest-attributes
選用：根據預設，VM 會停用訪客屬性。如果您想在執行開機指令碼後，使用 VM 的訪客屬性記錄網域加入狀態，可以將此中繼資料鍵設為 TRUE。
Managed Microsoft AD 會在 guest-attributes 的 managed-ad 命名空間下，將網域加入狀態寫入下列索引鍵：
選用：根據預設，受管理的 Microsoft AD 會將 VM 加入 GCE Instances 機構單位 (OU)，該單位是在 Cloud 機構單位下預先建立，以便更妥善地管理政策。如要進一步瞭解 Cloud 機構單位，請參閱「機構單位」。
如果您想將 VM 加入自訂 OU，請在受管理的 Microsoft AD 中，在 GCE Instances OU 或 Cloud OU 底下建立自訂 OU，然後使用這個中繼資料鍵來指定自訂 OU。受管理的 Microsoft AD 不支援您在 Cloud OU 或 GCE Instances OU 以外的任何位置建立的自訂 OU。
如果您在 Cloud OU 下建立自訂 OU，請使用以下格式指定自訂 OU 的路徑：/cloud/SUB_OU1/SUB_OU2/…/CUSTOM_OU。例如：/cloud/my-sub-ou/my-custom-ou。
[[["容易理解","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 (世界標準時間)。"],[],[],null,["# Join a Windows VM automatically to a domain\n\nThis page explains how to join a Windows Compute Engine VM instance to a domain using the automated domain join feature in Managed Service for Microsoft Active Directory.\n\nHow Managed Microsoft AD joins a Windows VM automatically to a domain\n---------------------------------------------------------------------\n\nTo use Managed Microsoft AD for authenticating the applications running on your VMs, you need to join the VMs to your Managed Microsoft AD domain. The domain join process usually involves performing some manual steps.\n\nWhen you create or update a Windows Compute Engine VM, you can join the VM to your Managed Microsoft AD domain by automating [the manual approach](/managed-microsoft-ad/docs/quickstart-domain-join-windows) using scripts. However, to execute these scripts on a Compute Engine VM, you require AD credentials that need to be securely stored and maintained, and an environment to provision and run these scripts. To eliminate the need for credentials and an additional service, you can automate the domain join process with ready-made scripts that are available from Managed Microsoft AD.\n\nWhen you create Compute Engine VMs, you can use scripts to automatically join the VMs to your Managed Microsoft AD domain. After Compute Engine creates the VMs, Managed Microsoft AD initiates the domain join request and attempts to join the VMs with your domain. If the domain join request succeeds, Managed Microsoft AD joins the created VMs to your domain. If the domain join request fails, the created VMs continue to run. For security or billing purposes, you can customize this behavior and Managed Microsoft AD can stop the VMs when the domain join request fails.\n\nWhen you update Compute Engine VMs, you can use scripts to automatically join the existing VMs to your Managed Microsoft AD domain. For the domain join request to succeed, Managed Microsoft AD restarts the VMs after running the scripts.\n\nBefore you begin\n----------------\n\n1. [Create a Managed Microsoft AD domain](/managed-microsoft-ad/docs/create-domain).\n\n2. Make sure that the VM name has a maximum of 15 characters.\n\n3. Make sure that the VM runs on a [Windows version that Managed Microsoft AD supports](/managed-microsoft-ad/docs/os-versions#windows-domain-join).\n\n4. [Configure domain peering](/managed-microsoft-ad/docs/quickstart-domain-peering) between the Managed Microsoft AD domain and the VM's network, or have both the Managed Microsoft AD domain and the VM in the same network.\n\n5. Create a service account with the Google Cloud Managed Identities Domain Join (`roles/managedidentities.domainJoin`) IAM role on the project that has the Managed Microsoft AD domain. For more information, see [Cloud Managed Identities roles](/iam/docs/understanding-roles#cloud-managed-identities-roles).\n\n - For more information about granting roles, see [Grant a single role](/iam/docs/manage-access-service-accounts#grant-single-role).\n\n - For information about creating a service account, see [Authenticate workloads using service accounts](/compute/docs/access/create-enable-service-accounts-for-instances).\n\n6. Set the full `cloud-platform` access scope on the VM. For more information, see [Authorization](/compute/docs/access/service-accounts#authorization).\n\nMetadata\n--------\n\nYou need the following metadata keys to join a Windows VM to a domain.\n\nJoin the Windows VM\n-------------------\n\nYou can use these [metadata keys](/managed-microsoft-ad/docs/seamless-domain-join-gce#metadata) when you either create a Windows VM or update an existing VM.\nThe following sections illustrate how to use these metadata keys in gcloud CLI commands when you create a VM or update a VM.\n\nHowever, you can use these metadata keys with a VM using the other available options as well. For more information about using metadata with a Windows Compute Engine VM, see [Set custom metadata](/compute/docs/metadata/setting-custom-metadata).\n\n### Join a Windows VM during creation\n\nTo create and join a Windows Compute Engine VM, run the following gcloud CLI command: \n\n```\ngcloud compute instances create INSTANCE_NAME \\\n --metadata=windows-startup-script-url=URL,managed-ad-domain=DOMAIN_RESOURCE_PATH,managed-ad-domain-join-failure-stop=TRUE,enable-guest-attributes=TRUE \\\n --service-account=SERVICE_ACCOUNT \\\n --scopes=https://www.googleapis.com/auth/cloud-platform \\\n --image-project windows-cloud \\\n --image-family IMAGE_FAMILY\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eINSTANCE_NAME\u003c/var\u003e: Name of the Windows Compute Engine VM to create. For example, `my-instance-1`.\n- \u003cvar translate=\"no\"\u003eURL\u003c/var\u003e: A publicly-accessible location of the Windows startup script that the VM executes during the startup process.\n- \u003cvar translate=\"no\"\u003eDOMAIN_RESOURCE_PATH\u003c/var\u003e: Full resource name of your Managed Microsoft AD domain to join. For example, `projects/my-project-123/locations/global/domains/my-domain.example.com`.\n- \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e: A service account that you want to attach to the VM. For example, `my-sa-123@my-project-123.iam.gserviceaccount.com`.\n- `--scopes`: The default access scopes configured in the VM restricts the domain join request. You need to set the full `cloud-platform` access scope on the VM. For more information, see [Authorization](/compute/docs/access/service-accounts#authorization).\n- `--image-project`: You need to set this flag as `windows-cloud` to create a Windows VM. For more information, see [`gcloud compute instances create`](/sdk/gcloud/reference/compute/instances/create).\n- \u003cvar translate=\"no\"\u003eIMAGE_FAMILY\u003c/var\u003e: Specify one of the [public image families](/compute/docs/images#os-compute-support) that has images for the [supported Windows versions](/managed-microsoft-ad/docs/os-versions#windows-domain-join). For example, `windows-2019-core`.\n\nFor more information about adding metadata during VM creation, see [Set metadata during VM creation](/compute/docs/metadata/setting-custom-metadata#set_during_creation).\n\n### Join an existing Windows VM\n\nYou can update the [metadata keys](/managed-microsoft-ad/docs/seamless-domain-join-gce#metadata) on an existing Windows Compute Engine VM and join the VM to your domain. After you add these metadata keys to the VM, restart the VM so that the domain join request succeeds.\n| **Caution:** If you already have a startup script that is passed to the VM using the `windows-startup-script-url` metadata key, the following approach can replace the existing startup script with the automated domain join startup script. Instead, you can use any other suitable [metadata key](/compute/docs/instances/startup-scripts/windows#metadata-keys) to pass the existing startup script, except the `windows-startup-script-url` metadata key. For example, `windows-startup-script-ps1`. For information about the script execution sequence, see [Order of execution of Windows startup scripts](/compute/docs/instances/startup-scripts/windows#order_of_execution_of_windows_startup_scripts).\n\nTo join an existing Windows Compute Engine VM, run the following gcloud CLI command: \n\n```\ngcloud compute instances add-metadata INSTANCE_NAME \\\n --metadata=windows-startup-script-url=URL,managed-ad-domain=DOMAIN_RESOURCE_PATH,managed-ad-domain-join-failure-stop=TRUE,enable-guest-attributes=TRUE \\\n --service-account=SERVICE_ACCOUNT \\\n --scopes=https://www.googleapis.com/auth/cloud-platform\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eINSTANCE_NAME\u003c/var\u003e: Name of the Windows Compute Engine VM that you want to join. For example, `my-instance-1`.\n- \u003cvar translate=\"no\"\u003eURL\u003c/var\u003e: A publicly-accessible location of the Windows startup script that the VM executes after restart.\n- \u003cvar translate=\"no\"\u003eDOMAIN_RESOURCE_PATH\u003c/var\u003e: Full resource name of your Managed Microsoft AD domain to join. For example, `projects/my-project-123/locations/global/domains/my-domain.example.com`.\n- \u003cvar translate=\"no\"\u003eSERVICE_ACCOUNT\u003c/var\u003e: The service account that you have attached the VM during creation. For example, `my-sa-123@my-project-123.iam.gserviceaccount.com`.\n- `--scopes`: The default access scopes configured in the VM restricts the domain join request. You need to set the full `cloud-platform` access scope on the VM. For more information, see [Authorization](/compute/docs/access/service-accounts#authorization).\n\nFor more information about adding metadata to an existing VM, see [Updating metadata on a running VM](/compute/docs/metadata/setting-custom-metadata#update_metadata).\n\nClean up unjoined VMs\n---------------------\n\nWe recommend to delete the computer account manually from Managed Microsoft AD in the following scenarios:\n\n- If you delete a VM that you have joined with the Managed Microsoft AD domain.\n- If a VM has failed to join with the Managed Microsoft AD domain.\n\nView debug logs\n---------------\n\nIf the domain join request fails, you can check the logs for the startup script to identify and troubleshoot the issue. To check the logs for the startup script, you can [view Serial port 1 output](/compute/docs/troubleshooting/viewing-serial-port-output#viewing_serial_port_output). If you have enabled guest attributes on the VM, you can [get the guest attributes](/compute/docs/metadata/manage-guest-attributes#get_guest_attributes) to view the logs.\n\nFor information about the common errors that you can encounter while joining a VM to a domain, see [Unable to join a Windows VM automatically to a domain](/managed-microsoft-ad/docs/troubleshooting#domain-join-windows).\n\nWhat's next\n-----------\n\n- [Join GKE Windows Server nodes automatically to a\n Managed Microsoft AD domain](/managed-microsoft-ad/docs/automated-domain-join-gke)."]]
