Mulai cepat: Menentukan dan menetapkan Azure blueprints dengan Azure CLI

Artikel
09/07/2023

Penting

Pada 11 Juli 2026, Cetak Biru (Pratinjau) tidak akan digunakan lagi. Migrasikan definisi dan penugasan cetak biru yang ada ke Spesifikasi Templat dan Tumpukan Penyebaran. Artefak cetak biru akan dikonversi ke templat ARM JSON atau file Bicep yang digunakan untuk menentukan tumpukan penyebaran. Untuk mempelajari cara menulis artefak sebagai sumber daya ARM, lihat:

Dalam tutorial ini, Anda mempelajari cara menggunakan Azure Blueprints untuk melakukan beberapa tugas umum yang terkait dengan membuat, menerbitkan, dan menetapkan cetak biru dalam organisasi Anda. Keterampilan ini membantu Anda menentukan pola umum untuk mengembangkan konfigurasi yang dapat digunakan kembali dan disebarkan dengan cepat, berdasarkan templat, kebijakan, dan keamanan Azure Resource Manager (ARM).

Prasyarat

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Jika Anda belum pernah menggunakan Azure Blueprints sebelumnya, daftarkan penyedia sumber melalui Azure CLI dengan az provider register --namespace Microsoft.Blueprint.

Azure Cloud Shell

Azure meng-hosting Azure Cloud Shell, lingkungan shell interaktif yang dapat Anda gunakan melalui browser. Anda dapat menggunakan Bash atau PowerShell dengan Cloud Shell untuk bekerja dengan layanan Azure. Anda dapat menggunakan perintah Cloud Shell yang telah diinstal sebelumnya untuk menjalankan kode dalam artikel ini tanpa harus menginstal apa-apa di lingkungan lokal Anda.

Untuk memulai Azure Cloud Shell:

Opsi	Contoh/Tautan
Pilih Coba di pojok kanan atas blok kode atau perintah. Memilih Coba tidak otomatis menyalin kode atau perintah ke Cloud Shell.
Buka https://shell.azure.com, atau pilih tombol Luncurkan Cloud Shell untuk membuka Cloud Shell di browser Anda.
Pilih tombol Cloud Shell pada bilah menu di kanan atas di portal Microsoft Azure.

Untuk menggunakan Azure Cloud Shell:

Mulai Cloud Shell.
Pilih tombol Salin pada blok kode (atau blok perintah) untuk menyalin kode atau perintah.
Tempel kode atau perintah ke dalam sesi Cloud Shell dengan memilih Ctrl+Shift+V di Windows dan Linux, atau dengan memilih Cmd+Shift+V di macOS.
Pilih Masukkan untuk menjalankan kode atau perintah.

Menambahkan ekstensi blueprint

Untuk mengaktifkan Azure CLI guna mengelola definisi dan penetapan blueprint, Anda harus menambahkan ekstensi. Ekstensi ini berfungsi di mana pun Anda dapat menggunakan Azure CLI. Ini termasuk bash di Windows 10, Cloud Shell (baik versi mandiri dan yang ada di dalam portal), gambar Azure CLI Docker, atau ekstensi yang dipasang secara lokal.

Periksa apakah Azure CLI terbaru terinstal (setidaknya 2.0.76). Jika belum diinstal, ikuti petunjuk ini.

Di lingkungan Azure CLI pilihan Anda, impor ekstensi dengan perintah berikut:

# Add the Blueprint extension to the Azure CLI environment
az extension add --name blueprint

Validasi bahwa ekstensi telah dipasang dan merupakan versi yang diharapkan (setidaknya 0.1.0):

# Check the extension list (note that you might have other extensions installed)
az extension list

# Run help for extension options
az blueprint -h

Buat cetak biru

Langkah pertama dalam mendefinisikan pola standar untuk kepatuhan adalah menyusun cetak biru dari sumber daya yang tersedia. Mari buat cetak biru bernama MyBlueprint untuk mengonfigurasi penetapan peran dan kebijakan untuk langganan. Kemudian Anda menambahkan grup sumber daya, pola dasar ARM, dan penetapan peran pada grup sumber daya.

Catatan

Saat Anda menggunakan Azure CLI, objek blueprint dibuat terlebih dahulu. Untuk setiap artefak yang akan ditambahkan yang memiliki parameter, Anda menentukan parameter terlebih dahulu pada blueprint awal.

Membuat objek cetak biru awal. Parameter parameters mengambil file JSON yang mencakup semua parameter tingkat cetak biru. Anda mengatur parameter selama penugasan, dan parameter tersebut digunakan oleh artefak yang Anda tambahkan di langkah selanjutnya.

File JSON - blueprintparms.json

{
   "storageAccountType": {
       "type": "string",
       "defaultValue": "Standard_LRS",
       "allowedValues": [
           "Standard_LRS",
           "Standard_GRS",
           "Standard_ZRS",
           "Premium_LRS"
       ],
       "metadata": {
           "displayName": "storage account type.",
           "description": null
       }
   },
   "tagName": {
       "type": "string",
       "metadata": {
           "displayName": "The name of the tag to provide the policy assignment.",
           "description": null
       }
   },
   "tagValue": {
       "type": "string",
       "metadata": {
           "displayName": "The value of the tag to provide the policy assignment.",
           "description": null
       }
   },
   "contributors": {
       "type": "array",
       "metadata": {
           "description": "List of AAD object IDs that is assigned Contributor role at the subscription",
           "strongType": "PrincipalId"
       }
   },
   "owners": {
       "type": "array",
       "metadata": {
           "description": "List of AAD object IDs that is assigned Owner role at the resource group",
           "strongType": "PrincipalId"
       }
   }
}

Perintah Azure CLI

# Login first with az login if not using Cloud Shell

# Create the blueprint object
az blueprint create \
   --name 'MyBlueprint' \
   --description 'This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.' \
   --parameters blueprintparms.json

Catatan

Gunakan nama file blueprint.json saat Anda mengimpor definisi blueprint Anda. Nama file ini digunakan saat Anda memanggil az blueprint import.

Objek cetak biru dibuat di langganan default secara default. Untuk menentukan grup pengelolaan, gunakan parameter managementgroup. Untuk menentukan langganan, gunakan parameter subscription.

Tambahkan grup sumber daya untuk artefak penyimpanan ke definisi.

az blueprint resource-group add \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'storageRG' \
   --description 'Contains the resource template deployment and a role assignment.'

Tambahkan penetapan peran di tingkat langganan. Dalam contoh berikut, identitas utama yang mendapatkan peran tertentu dikonfigurasi ke parameter yang diatur selama penetapan cetak biru. Contoh ini menggunakan Contributor peran bawaan, dengan GUID b24988ac-6180-42a0-ab88-20f7382dd24c.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleContributor' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c' \
   --principal-ids "[parameters('contributors')]"
```

Menambahkan penugasan kebijakan di langganan. Contoh ini menggunakan Apply tag and its default value to resource groups kebijakan bawaan, dengan GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

File JSON - artefak\policyTags.json

{
   "tagName": {
      "value": "[parameters('tagName')]"
   },
   "tagValue": {
      "value": "[parameters('tagValue')]"
   }
}

Perintah Azure CLI

az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply tag and its default value to resource groups' \
   --description 'Apply tag and its default value to resource groups' \
   --parameters artifacts\policyTags.json

Catatan

Saat Anda menggunakan az blueprint di Mac, ganti \ dengan / untuk nilai parameter yang menyertakan jalur. Dalam hal ini, nilai untuk parameters menjadi artifacts/policyTags.json.

Menambahkan penugasan kebijakan lain untuk tag penyimpanan (dengan menggunakan kembali storageAccountType_ parameter) di langganan. Artefak penugasan kebijakan tambahan ini menunjukkan bahwa parameter yang ditentukan pada cetak biru dapat digunakan oleh lebih dari satu artefak. Dalam contoh, Anda menggunakan storageAccountType untuk menetapkan tag pada grup sumber daya. Nilai ini menyediakan informasi tentang akun penyimpanan yang Anda buat di langkah berikutnya. Contoh ini menggunakan Apply tag and its default value to resource groups kebijakan bawaan, dengan GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- JSON file - artefak\policyStorageTags.json
```
{
   "tagName": {
      "value": "StorageType"
   },
   "tagValue": {
      "value": "[parameters('storageAccountType')]"
   }
}
```
- Perintah Azure CLI
```
az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyStorageTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply storage tag to resource group' \
   --description 'Apply storage tag and the parameter also used by the template to resource groups' \
   --parameters artifacts\policyStorageTags.json
```
  Catatan
  
  Saat Anda menggunakan az blueprint di Mac, ganti \ dengan / untuk nilai parameter yang menyertakan jalur. Dalam hal ini, nilai untuk parameters menjadi artifacts/policyStorageTags.json.

Tambahkan pola dasar di bawah grup sumber daya. Parameter template untuk templat ARM mencakup komponen JSON normal templat. Templat juga menggunakan storageAccountTypekembali parameter cetak biru , tagName, dan tagValue dengan meneruskan masing-masing ke templat. Parameter blueprint tersedia untuk pola dasar dengan menggunakan parameter parameters, dan di dalam pola dasar JSON pasangan kunci-nilai digunakan untuk memasukkan nilai. Nama parameter blueprint dan pola dasar mungkin sama.

File pola dasar JSON ARM - artifacts\templateStorage.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "metadata": {
                "description": "Storage Account type"
            }
        },
        "tagNameFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag name from blueprint"
            }
        },
        "tagValueFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag value from blueprint"
            }
        }
    },
    "variables": {
        "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
    },
    "resources": [{
        "type": "Microsoft.Storage/storageAccounts",
        "name": "[variables('storageAccountName')]",
        "apiVersion": "2016-01-01",
        "tags": {
            "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
        },
        "location": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

File parameter pola dasar JSON ARM - artifacts\templateStorageParams.json

{
   "storageAccountTypeFromBP": {
      "value": "[parameters('storageAccountType')]"
   },
   "tagNameFromBP": {
      "value": "[parameters('tagName')]"
   },
   "tagValueFromBP": {
      "value": "[parameters('tagValue')]"
   }
}

Perintah Azure CLI
```
az blueprint artifact template create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'templateStorage' \
   --template artifacts\templateStorage.json \
   --parameters artifacts\templateStorageParams.json \
   --resource-group-art 'storageRG'
```
Catatan

Saat Anda menggunakan az blueprint di Mac, ganti \ dengan / untuk nilai parameter yang menyertakan jalur. Dalam hal ini, nilai untuk template menjadi artifacts/templateStorage.json, dan parameters menjadi artifacts/templateStorageParams.json.

Menambahkan penetapan peran di bawah grup sumber daya. Mirip dengan entri penetapan peran sebelumnya, contoh berikut menggunakan pengidentifikasi definisi untuk peran Owner, dan memberikannya parameter yang berbeda dari blueprint. Contoh ini menggunakan Owner peran bawaan, dengan GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleOwner' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635' \
   --principal-ids "[parameters('owners')]" \
   --resource-group-art 'storageRG'
```

Menerbitkan cetak biru

Sekarang setelah Anda menambahkan artefak ke blueprint, saatnya untuk menerbitkannya. Penerbitan membuat blueprint tersedia untuk ditetapkan ke langganan.

az blueprint publish --blueprint-name 'MyBlueprint' --version '{BlueprintVersion}'

Nilai untuk {BlueprintVersion} adalah rangkaian huruf, angka, dan tanda hubung (tanpa spasi atau karakter khusus lainnya). Panjang maksimum adalah 20 karakter. Gunakan sesuatu yang unik dan informatif, seperti v20200605-135541.

Menetapkan cetak biru

Setelah Anda menerbitkan blueprint dengan menggunakan Azure CLI, itu dapat ditetapkan ke langganan. Tetapkan cetak biru yang Anda buat pada salah satu langganan di bawah hierarki grup manajemen Anda. Jika cetak biru disimpan ke langganan, cetak biru hanya dapat ditetapkan ke langganan tersebut. Parameter blueprint-name menentukan cetak biru yang akan ditetapkan. Untuk menyediakan parameter name, location, identity, lock, dan blueprint, gunakan parameter Azure CLI yang cocok pada perintah az blueprint assignment create, atau berikan parameter tersebut di parameter file JSON.

Jalankan penyebaran cetak biru dengan menetapkannya ke langganan. Karena parameter contributors dan owners memerlukan array objectIds prinsipal untuk diberikan penetapan peran, gunakan Azure Active Directory Graph API untuk mengumpulkan objectIds untuk digunakan di parameters untuk pengguna, grup, atau prinsipal layanan Anda sendiri.
- File JSON - blueprintAssignment.json
```
{
   "storageAccountType": {
       "value": "Standard_GRS"
   },
   "tagName": {
       "value": "CostCenter"
   },
   "tagValue": {
       "value": "ContosoIT"
   },
   "contributors": {
       "value": [
           "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
           "38833b56-194d-420b-90ce-cff578296714"
       ]
   },
   "owners": {
       "value": [
           "44254d2b-a0c7-405f-959c-f829ee31c2e7",
           "316deb5f-7187-4512-9dd4-21e7798b0ef9"
       ]
   }
}
```
- Perintah Azure CLI
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
- Identitas terkelola yang ditetapkan pengguna
  
  Penetapan cetak biru juga dapat menggunakan identitas terkelola yang ditetapkan pengguna. Dalam hal ini, parameter identity-type diatur ke UserAssigned, dan parameter user-assigned-identities menentukan identitas. Ganti {userIdentity} dengan nama identitas terkelola yang ditetapkan pengguna Anda.
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --identity-type UserAssigned \
   --user-assigned-identities {userIdentity} \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
  Identitas terkelola yang ditetapkan pengguna dapat berada dalam langganan dan grup sumber daya apa pun yang izinnya dimiliki oleh pengguna yang menetapkan blueprint.
  
  Penting
  
  Azure Blueprints tidak mengelola identitas terkelola yang ditetapkan pengguna. Pengguna bertanggung jawab untuk menetapkan peran dan izin yang memadai, atau penugasan blueprint akan gagal.

Membersihkan sumber daya

Anda dapat menghapus cetak biru dari langganan. Penghapusan sering dilakukan ketika sumber daya artefak tidak lagi diperlukan. Ketika cetak biru dihapus, artefak yang ditetapkan sebagai bagian dari cetak biru tersebut akan tertinggal. Untuk menghapus penetapan cetak biru, gunakan perintah az blueprint assignment delete:

az blueprint assignment delete --name 'assignMyBlueprint'

Langkah berikutnya

Dalam mulai cepat ini, Anda membuat, menetapkan, dan menghapus blueprint dengan Azure CLI. Untuk mempelajari Azure Blueprints lebih lanjut, lanjutkan ke artikel siklus hidup cetak biru.

Pelajari siklus hidup cetak biru

Mulai cepat: Menentukan dan menetapkan Azure blueprints dengan Azure CLI

Prasyarat

Azure Cloud Shell

Menambahkan ekstensi blueprint

Buat cetak biru

Menerbitkan cetak biru

Menetapkan cetak biru

Membersihkan sumber daya

Langkah berikutnya

Sumber Daya Tambahan: