Exercício – Atualizar e versionar 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 muitas novas contas do Azure Cosmos DB. Assim, todos eles são configurados para usar o backup contínuo.

Sua equipe de segurança revisou recentemente os recursos de segurança do Azure Cosmos DB. Foi decidido que novas contas deveriam usar a autenticação Microsoft Entra e o controle de acesso baseado em função do Azure Cosmos DB.

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

Durante o processo, você:

  • Atualize seu modelo para reconfigurar a política de backup.
  • Publique uma nova versão da especificação do seu modelo.
  • Verifique se a especificação de modelo foi atualizada.
  • Teste a nova versão da 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 do modelo

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

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

    Captura de tela da interface do Portal do Azure para a especificação de template, mostrando a versão mais recente como 2.0.

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

    Captura de tela da interface do portal do Azure para a especificação de modelo, mostrando a lista de versões como 1.0 e 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 do modelo

  1. Obtenha a ID de recurso da nova versão de 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 o ID do recurso da versão da especificação do modelo.

  2. Sua nova versão de especificação de modelo tem um parâmetro para o ID principal do usuário. Use os seguintes comandos para obter a ID principal da sua 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 o ID do recurso da versão da especificação do modelo executando o seguinte comando da 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 bem-sucedidas.

    Captura de tela da interface do portal do Azure para a visão geral do grupo de recursos, com a seção de implantações mostrando que duas foram bem-sucedidas.

  3. Selecione a implantação mais recente.

    Captura de tela da interface do portal do Azure para as implantações, com duas implantações listadas.

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

    Captura de tela da interface do portal do Azure para a implantação específica, com os recursos do Azure Cosmos DB listados.