Esercizio - Aggiornare e assegnare una versione a una specifica di modello

  • 4 minuti

La specifica di modello di Azure Cosmos DB viene ora usata in tutta l'organizzazione per effettuare il provisioning di molti nuovi account di Azure Cosmos DB. Di conseguenza, tutti sono configurati per usare il backup continuo.

Il team di sicurezza di recente ha esaminato le funzionalità di sicurezza di Azure Cosmos DB Si è deciso che i nuovi account devono usare l'autenticazione Microsoft Entra e il controllo degli accessi in base al ruolo di Azure Cosmos DB.

In questo esercizio si aggiorna la specifica di modello con una nuova versione che include la configurazione dell'autenticazione aggiornata.

Durante il processo, si eseguiranno queste operazioni:

  • Aggiornare il modello per riconfigurare i criteri di backup.
  • Pubblicare una nuova versione della specifica di modello.
  • Verificare che la specifica di modello sia stata aggiornata.
  • Testare la nuova versione della specifica di modello distribuendo un altro account di Azure Cosmos DB.

Aggiornare il modello

  1. In Visual Studio Code aprire il file azuredeploy.json.

  2. Aggiornare il file azuredeploy.json per includere le modifiche seguenti:

    {
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "The Azure region into which the Cosmos DB resources should be deployed."
      }
    },
    "cosmosDBAccountName": {
      "type": "string",
      "defaultValue": "[concat('toy-', uniqueString(resourceGroup().id))]",
      "maxLength": 44,
      "minLength": 3,
      "metadata": {
        "description": "The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens."
      }
    },
    "roleDefinitionFriendlyName": {
      "type": "string",
      "defaultValue": "Read and Write",
      "metadata": {
        "description": "A descriptive name for the role definition."
      }
    },
    "roleDefinitionDataActions": {
      "type": "array",
      "defaultValue": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ],
      "metadata": {
        "description": "The list of actions that the role definition permits."
      }
    },
    "roleAssignmentPrincipalId": {
      "type": "string",
      "metadata": {
        "description": "The object ID of the Azure AD principal that should be granted access using the role definition."
      }
    }
  },
  "variables": {
    "roleDefinitionName": "[guid('sql-role-definition', resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName')))]",
    "roleAssignmentName": "[guid('sql-role-assignment', resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName')))]"
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2021-04-15",
      "name": "[parameters('cosmosDBAccountName')]",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "consistencyPolicy": {
          "defaultConsistencyLevel": "Session"
        },
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "enableAutomaticFailover": false,
        "enableMultipleWriteLocations": false,
        "backupPolicy": {
          "type": "Continuous"
        }
      }
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
      "apiVersion": "2021-04-15",
      "name": "[format('{0}/{1}', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]",
      "properties": {
        "roleName": "[parameters('roleDefinitionFriendlyName')]",
        "type": "CustomRole",
        "assignableScopes": [
          "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
        ],
        "permissions": [
          {
            "dataActions": "[parameters('roleDefinitionDataActions')]"
          }
        ]
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
      ]
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments",
      "apiVersion": "2021-04-15",
      "name": "[format('{0}/{1}', parameters('cosmosDBAccountName'), variables('roleAssignmentName'))]",
      "properties": {
        "roleDefinitionId": "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]",
        "principalId": "[parameters('roleAssignmentPrincipalId')]",
        "scope": "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]"
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', parameters('cosmosDBAccountName'))]",
        "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions', parameters('cosmosDBAccountName'), variables('roleDefinitionName'))]"
      ]
    }
  ]
}

  3. Salva il file.

  1. In Visual Studio Code aprire il file main.bicep.

  2. Aggiornare il file main.bicep per includere le modifiche seguenti:

    @description('The Azure region into which the Cosmos DB resources should be deployed.')
param location string = resourceGroup().location

@description('The name of the Cosmos DB account. This name must be globally unique, and it must only include lowercase letters, numbers, and hyphens.')
@minLength(3)
@maxLength(44)
param cosmosDBAccountName string = 'toy-${uniqueString(resourceGroup().id)}'

@description('A descriptive name for the role definition.')
param roleDefinitionFriendlyName string = 'Read and Write'

@description('The list of actions that the role definition permits.')
param roleDefinitionDataActions array = [
  'Microsoft.DocumentDB/databaseAccounts/readMetadata'
  'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
]

@description('The object ID of the Azure AD principal that should be granted access using the role definition.')
param roleAssignmentPrincipalId string

var roleDefinitionName = guid('sql-role-definition', cosmosDBAccount.id)
var roleAssignmentName = guid('sql-role-assignment', cosmosDBAccount.id)

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2021-04-15' = {
  name: cosmosDBAccountName
  kind: 'GlobalDocumentDB'
  location: location
  properties: {
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    locations: [
      {
        locationName: location
        failoverPriority: 0
        isZoneRedundant: false
      }
    ]
    databaseAccountOfferType: 'Standard'
    enableAutomaticFailover: false
    enableMultipleWriteLocations: false
  }
}

resource roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2021-04-15' = {
  parent: cosmosDBAccount
  name: roleDefinitionName
  properties: {
    roleName: roleDefinitionFriendlyName
    type: 'CustomRole'
    assignableScopes: [
      cosmosDBAccount.id
    ]
    permissions: [
      {
        dataActions: roleDefinitionDataActions
      }
    ]
  }
}

resource roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2021-04-15' = {
  parent: cosmosDBAccount
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinition.id
    principalId: roleAssignmentPrincipalId
    scope: cosmosDBAccount.id
  }
}

  3. Salva il file.

Pubblicare una nuova versione della specifica di modello

Pubblicare la specifica di modello usando questo cmdlet di Azure PowerShell nel terminale di Visual Studio Code:

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Version '2.0' `
  -VersionDescription 'Adds Cosmos DB role-based access control.' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Version '2.0' `
  -VersionDescription 'Adds Cosmos DB role-based access control.' `
  -TemplateFile azuredeploy.json

Pubblicare la specifica di modello usando questo comando dell'interfaccia della riga di comando di Azure nel terminale di Visual Studio Code:

az ts create \
  --name ToyCosmosDBAccount \
  --version 2.0 \
  --version-description "Adds Cosmos DB role-based access control." \
  --template-file main.bicep

az ts create \
  --name ToyCosmosDBAccount \
  --version 2.0 \
  --version-description "Adds Cosmos DB role-based access control." \
  --template-file azuredeploy.json

Verificare la specifica di modello

  1. Nel browser tornare al portale di Azure. Passare al gruppo di risorse in uso.

  2. Selezionare la specifica di modello. Si noti che l'ultima versione ora è elencata come 2.0.

    Screenshot of the Azure portal interface for the template spec, showing the latest version as 2.0.

  3. Selezionare la voce di menu Versioni. Si noti che ora sono elencate entrambe le versioni.

    Screenshot of the Azure portal interface for the template spec, showing the list of versions as 1.0 and 2.0.

    Le versioni delle specifiche di modello consentono di tornare alle versioni precedenti della specifica di modello, se necessario.

Distribuire la nuova versione della specifica di modello

  1. Ottenere l'ID risorsa della nuova versione della specifica di modello eseguendo il comando di Azure PowerShell seguente:

    $templateSpecVersionResourceId = ( `
   Get-AzTemplateSpec `
      -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
      -Name ToyCosmosDBAccount `
      -Version 2.0 `
   ).Versions[0].Id

    Si noti che si usa la proprietà Versions per ottenere l'ID risorsa della versione della specifica di modello.

  2. La nuova versione della specifica di modello ha un parametro per l'ID dell'entità utente. Usare i comandi seguenti per ottenere l'ID entità di sicurezza dell'account utente:

    $token = (Get-AzAccessToken -ResourceUrl "https://graph.windows.net/").Token
$userObjectId = (Invoke-RestMethod -Uri 'https://graph.windows.net/me?api-version=1.6' -Headers @{ 'Authorization' = "Bearer $token"}).objectID

    I comandi usano l'API Microsoft Graph per eseguire una query sul profilo utente.

  3. Pubblicare la specifica di modello usando questo cmdlet di Azure PowerShell nel terminale di Visual Studio Code:

    New-AzResourceGroupDeployment `
  -TemplateSpecId $templateSpecVersionResourceId `
  -roleAssignmentPrincipalId $userObjectId

  1. Ottenere l'ID risorsa della versione della specifica di modello eseguendo il comando dell'interfaccia della riga di comando di Azure seguente:

    id=$(az ts show \
 --name ToyCosmosDBAccount \
 --resource-group "<rgn>[sandbox resource group name]</rgn>" \
 --version "2.0" \
 --query "id")

  2. Distribuire la specifica di modello usando questo comando dell'interfaccia della riga di comando di Azure nel terminale di Visual Studio Code:

    az deployment group create \
 --template-spec $id \
 --parameters roleAssignmentPrincipalId="d68d19b3-d7ef-4ae9-9ee4-90695a4e417d"

Il completamento della distribuzione può richiedere un minuto o due.

Verificare la distribuzione

  1. Nel browser tornare al portale di Azure. Passare al gruppo di risorse in uso.

  2. Accanto a Distribuzioni selezionare 2 completate.

    Screenshot of the Azure portal interface for the resource group overview, with the deployments section showing that two succeeded.

  3. Selezionare la distribuzione più recente.

    Screenshot of the Azure portal interface for the deployments, with two deployments listed.

  4. Selezionare Dettagli distribuzione per espandere la sezione. Verificare che siano distribuite le risorse per il controllo degli accessi in base al ruolo di Azure Cosmos DB.

    Screenshot of the Azure portal interface for the specific deployment, with the Azure Cosmos DB resources listed.