Exercício – atualização e versão de uma especificação de modelo

  • 4 minutos

Sua especificação de modelo do Azure Cosmos DB agora é usada em toda a sua organização para provisionar várias novas contas do Azure Cosmos DB. Dessa forma, todos eles estão configurados para usar backup contínuo.

Sua equipe de segurança analisou recentemente os recursos de segurança do Azure Cosmos DB. Ele decidiu que novas contas devem usar a autenticação do Microsoft Entra e o controle de acesso baseado em função do Azure Cosmos DB.

Neste exercício, atualize sua especificação de modelo com uma nova versão que inclui a configuração da autenticação atualizada.

Durante o processo, você vai:

  • Atualize seu modelo para reconfigurar a política de backup.
  • Publique uma nova versão da especificação de modelo.
  • Verifique se a especificação de modelo foi atualizada.
  • Teste a nova versão de sua especificação de modelo implantando outra conta do Azure Cosmos DB.

Atualizar o modelo

  1. No Visual Studio Code, abra o arquivo azuredeploy.json.

  2. Atualize o arquivo azuredeploy.json para incluir as seguintes alterações:

    {
  "$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. Salve o arquivo.

  1. No Visual Studio Code, abra o arquivo main.bicep.

  2. Atualize o arquivo main.bicep para incluir as seguintes alterações:

    @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. Salve o arquivo.

Publicar uma nova versão da especificação de modelo

Publique a especificação de modelo usando este cmdlet do Azure PowerShell no terminal do 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

Publique a especificação de modelo usando este comando do CLI do Azure no terminal do 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

Verificar a especificação de modelo

  1. No navegador, retorne ao portal do Azure. Vá para o grupo de recursos.

  2. Selecione a especificação de modelo. Observe que a versão mais recente agora está listada como 2.0.

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

  3. Selecione o item de menu Versões. Observe que ambas as versões agora estão listadas.

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

    As versões de especificação de modelo permitem que você volte para versões anteriores da especificação de modelo, se necessário.

Implantar a nova versão de especificação de modelo

  1. Obtenha a nova ID de recurso da versão da especificação de modelo executando o seguinte comando do Azure PowerShell:

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

    Observe que você usa a propriedade Versions para obter a ID de recurso da versão da especificação de modelo.

  2. Sua nova versão de especificação de modelo tem um parâmetro para a ID da entidade de usuário. Use os seguintes comandos para obter a ID da entidade de usuário da sua própria conta de usuário:

    $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

    Os comandos usam a API do Microsoft Graph para consultar seu próprio perfil de usuário.

  3. Implante a especificação de modelo usando este comando do Azure PowerShell no terminal do Visual Studio Code:

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

  1. Obtenha a ID de recurso da versão da especificação de modelo executando o seguinte comando do CLI do Azure:

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

  2. Implante a especificação de modelo usando este comando do CLI do Azure no terminal do Visual Studio Code:

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

A implantação poderá levar alguns minutos para ser concluída.

Verificar a implantação

  1. No navegador, retorne ao portal do Azure. Vá para o grupo de recursos.

  2. Ao lado de Implantações, selecione 2 Êxito.

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

  3. Selecione a implantação mais recente.

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

  4. Selecione Detalhes da implantação para expandi-lo. Confirme se os recursos para o controle de acesso baseado em função do Azure Cosmos DB estão implantados.

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