Exercício - Atualizar 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 muitas novas contas do Azure Cosmos DB. Assim, todos eles sã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 as 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, você atualiza a especificação do 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 modelo.
  • Verifique se a especificação do modelo foi atualizada.
  • Teste a nova versão da especificação do 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. Guarde o ficheiro.

  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. Guarde o ficheiro.

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

Publique a especificação do 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 do modelo usando este comando da 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, volte para o portal do Azure. Vá para o seu grupo de recursos.

  2. Selecione a especificação do 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ções de modelo permitem que você volte para versões anteriores de suas especificações de modelo, se necessário.

Implantar a nova versão de especificação de 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 Versions propriedade para obter o ID de recurso da versão de 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 o ID principal 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 de código do Visual Studio:

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

  1. Obtenha a ID de 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 do modelo usando este comando da 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 pode levar um ou dois minutos para ser concluída.

Verificar a implementação

  1. No navegador, volte para o portal do Azure. Vá para o seu grupo de recursos.

  2. Ao lado de Implantações, selecione 2 Bem-sucedidas.

    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-la. 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.