Ejercicio: actualización y creación de versiones de una especificación de plantilla

  • 4 minutos

La especificación de plantilla para Azure Cosmos DB ahora se usa en toda la organización para aprovisionar una gran cantidad de nuevas cuentas de Azure Cosmos DB. En consecuencia, todas ellas están configuradas para usar la copia de seguridad continua.

El equipo de seguridad ha revisado recientemente las funcionalidades de seguridad de Azure Cosmos DB. Han decidido que las nuevas cuentas deben usar la autenticación de Microsoft Entra y el control de acceso basado en rol de Azure Cosmos DB.

En este ejercicio, actualiza la especificación de plantilla con una nueva versión que incluye la configuración de autenticación actualizada.

Durante el proceso, hará lo siguiente:

  • Actualizar la plantilla para volver a configurar la directiva de copia de seguridad.
  • Publicar una nueva versión de la especificación de plantilla.
  • Comprobar que la especificación de plantilla se haya actualizado.
  • Probar la nueva versión de la especificación de plantilla mediante la implementación de otra cuenta de Azure Cosmos DB.

Actualización de la plantilla

  1. En Visual Studio Code, abra el archivo azuredeploy.json.

  2. Actualice el archivo azuredeploy.json para incluir los siguientes cambios:

    {
  "$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 el archivo.

  1. En Visual Studio Code, abra el archivo main.bicep.

  2. Actualice el archivo main.bicep para incluir los cambios siguientes:

    @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 el archivo.

Publicación de una nueva versión de la especificación de plantilla

Publique la especificación de plantilla mediante este cmdlet de Azure PowerShell en el terminal de 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 la especificación de plantilla mediante este comando de la CLI de Azure en el terminal de 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

Comprobación de la especificación de plantilla

  1. En el explorador, vuelva a Azure Portal. Vaya a su grupo de recursos.

  2. Seleccione la especificación de plantilla. Observe que la versión más reciente aparece ahora como 2.0.

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

  3. Seleccione el elemento de menú Versiones. Observe que ahora aparecen ambas versiones en la lista.

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

    Las versiones de la especificación de plantilla le permiten volver a versiones anteriores de la especificación de plantilla si es necesario.

Implementación de la nueva versión de la especificación de plantilla

  1. Para obtener el identificador de recurso de la nueva versión de la especificación de plantilla, ejecute el siguiente comando de Azure PowerShell:

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

    Observe que se usa la propiedad Versions para obtener el identificador de recurso de la versión de la especificación de plantilla.

  2. La nueva versión de la especificación de plantilla tiene un parámetro para el identificador de la entidad de seguridad de usuario. Use los siguientes comandos para obtener el identificador de la entidad de seguridad de su propia cuenta de usuario:

    $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

    Los comandos usan Microsoft Graph API para consultar su propio perfil de usuario.

  3. Implemente la especificación de plantilla mediante este comando de Azure PowerShell en el terminal de Visual Studio Code:

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

  1. Para obtener el identificador de recurso de la versión de la especificación de plantilla, ejecute el siguiente comando de la CLI de Azure:

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

  2. Implemente la especificación de plantilla mediante este comando de la CLI de Azure en el terminal de Visual Studio Code:

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

La implementación puede tardar uno o dos minutos en completarse.

Comprobación de la implementación

  1. En el explorador, vuelva a Azure Portal. Vaya a su grupo de recursos.

  2. Junto a Implementaciones, seleccione 2 Correctas.

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

  3. Seleccione la implementación más reciente.

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

  4. Seleccione Detalles de implementación para expandirlo. Confirme que se implementan los recursos para el control de acceso basado en rol de Azure Cosmos DB.

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