Ejercicio: creación e implementación de una especificación de plantilla

Completado

Nota:

La primera vez que active un espacio aislado y acepte los términos, la cuenta de Microsoft se asocia a un nuevo directorio de Azure denominado Espacio aislado de Microsoft Learn. Se le agrega también a una suscripción especial llamada Suscripción de Concierge.

En su empresa de juguetes, tu equipo ha estado trabajando con Azure durante un tiempo y has creado muchas plantillas que se usan a diario. Decide tomar una plantilla y crear una especificación de plantilla. Elige como punto de partida la plantilla que usa para crear cuentas de Azure Cosmos DB.

El equipo ha decidido que se debe configurar la copia de seguridad continua en todas las cuentas de Azure Cosmos DB. Por lo tanto, quiere incluir copias de seguridad en la configuración predeterminada de las cuentas de Azure Cosmos DB que se aprovisionan mediante la especificación de plantilla.

En este ejercicio, publicará la plantilla de Azure Cosmos DB como una especificación de plantilla.

Durante el proceso, hará lo siguiente:

• Crear una plantilla que usará como especificación de plantilla.
• Actualizar la plantilla para asegurarse de que los parámetros sean fáciles de entender y trabajar con ellos.
• Publicar la especificación de plantilla.
• Comprobar la especificación de plantilla mediante Azure Portal.
• Implementar la especificación de plantilla para probarla.
• Comprobación de la implementación.

En este ejercicio se usa la extensión de Bicep para Visual Studio Code. Asegúrese de instalar esta extensión en Visual Studio Code.

Crear la plantilla

Comienza con una de las plantillas que el equipo ha creado. La plantilla implementa una cuenta de Azure Cosmos DB y la configura para habilitar la copia de seguridad continua.

1. Abra Visual Studio Code.

2. Cree un archivo con el nombre main.bicep.

3. Guarde el archivo vacío para que Visual Studio Code cargue las herramientas de Bicep.

   Puede seleccionar Archivo>Guardar como o Ctrl+S en Windows (⌘+S en macOS). Asegúrese de recordar dónde guardó el archivo. Por ejemplo, podría crear una carpeta scripts para guardarlo ahí.

4. Copie el código siguiente en el archivo main.bicep:

   param location string = resourceGroup().location
   param cosmosDBAccountName string = 'toy-${uniqueString(resourceGroup().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
       backupPolicy: {
         type: 'Continuous'
       }
     }
   }
   

   Tenga en cuenta que ha establecido backupPolicy en Continuous. Este valor configura Azure Cosmos DB para realizar copias de seguridad de los datos de forma continua en lugar de periódicamente.

5. Guarde el archivo.

1. Abra Visual Studio Code.

2. Cree un archivo con el nombre azuredeploy.json.

3. Guarde el archivo vacío para que Visual Studio Code cargue las herramientas para la plantilla de Azure Resource Manager (plantilla de ARM).

   Puede seleccionar Archivo>Guardar como o Ctrl+S en Windows (⌘+S en macOS). Asegúrese de recordar dónde guardó el archivo. Por ejemplo, podría crear una carpeta scripts para guardarlo ahí.

4. Copie el código siguiente en el archivo azuredeploy.json:

   {
     "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
     "contentVersion": "1.0.0.0",
     "parameters": {
       "location": {
         "type": "string",
         "defaultValue": "[resourceGroup().location]"
       },
       "cosmosDBAccountName": {
         "type": "string",
         "defaultValue": "[concat('toy-', uniqueString(resourceGroup().id))]"
       }
     },
     "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"
           }
         }
       }
     ]
   }
   

   Tenga en cuenta que ha establecido backupPolicy en Continuous. Este valor configura Azure Cosmos DB para realizar copias de seguridad de los datos de forma continua en lugar de periódicamente.

5. Guarde el archivo.

Hacer que los parámetros sean más fáciles de entender

Cuando se trabaja con especificaciones de plantilla, es importante tener en cuenta cómo usan la plantilla otros usuarios. Esta revisión es especialmente importante para los parámetros, ya que son la forma principal en la que otras personas interactúan con el código. Los parámetros de la plantilla del equipo no incluyen descripciones ni otras sugerencias sobre cómo se deben usar, por lo que puede agregar esta información aquí.

1. Actualice la definición del parámetro location agregando una descripción:

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

2. Actualice la definición del parámetro cosmosDBAccountName para agregar una descripción y para especificar la longitud mínima y máxima del nombre:

   @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)}'
   

3. Guarde el archivo.

1. Actualice la definición del parámetro location agregando una descripción:

   "location": {
     "type": "string",
     "defaultValue": "[resourceGroup().location]",
     "metadata": {
       "description": "The Azure region into which the Cosmos DB resources should be deployed."
     }
   },
   

2. Actualice la definición del parámetro cosmosDBAccountName para agregar una descripción y para especificar la longitud mínima y máxima del nombre:

   "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."
     }
   }
   

3. Guarde el archivo.

Inicio de sesión en Azure

Para implementar esta plantilla en Azure, debe iniciar sesión en la cuenta de Azure desde el terminal de Visual Studio Code. Asegúrese de que tiene instalada la CLI de Azure y de que inicia sesión con la misma cuenta que utilizó para activar el espacio aislado.

1. En el menú Terminal, seleccione Nuevo terminal. Normalmente, la ventana de terminal se abre en la mitad inferior de la pantalla.

2. Si el shell que se muestra en el lado derecho de la ventana de terminal es Bash, el shell correcto está abierto y puede ir a la sección siguiente.

   

3. Si apareciera un shell distinto de Bash, seleccione la flecha de la lista desplegable del shell y, a continuación, seleccione Azure Cloud Shell (Bash).

   

4. En la lista de shells de terminal, seleccione Bash.

   

5. En el terminal, vaya al directorio donde ha guardado la plantilla. Por ejemplo, si ha guardado la plantilla en la carpeta templates, puede usar este comando:

   cd templates
   

Instalación de Bicep

Ejecute el comando siguiente para asegurarse de que tiene la versión más reciente de Bicep:

az bicep install && az bicep upgrade

Inicio de sesión en Azure

1. En el terminal de Visual Studio Code, inicie sesión en Azure mediante el siguiente comando:

   az login
   

2. En el explorador que se abre, inicie sesión en su cuenta de Azure.

   En el terminal de Visual Studio Code se muestra una lista de las suscripciones asociadas a esta cuenta.

3. Establezca la suscripción predeterminada para todos los comandos de la CLI de Azure que ejecute en esta sesión.

   az account set --subscription "Concierge Subscription"
   

   Nota:

   Si ha usado más de un espacio aislado recientemente, es posible que en el terminal se muestre más de una instancia de Suscripción de Concierge. En este caso, siga estos dos pasos para establecer una de las suscripciones como la predeterminada. Si el comando anterior se ha realizado correctamente y solo se muestra una Suscripción de Concierge, omita los dos pasos siguientes.

4. Obtenga los identificadores de la Suscripción de Concierge.

    az account list \
      --refresh \
      --query "[?contains(name, 'Concierge Subscription')].id" \
      --output table
   

5. Establezca la suscripción predeterminada con el identificador de la suscripción. Reemplace {identificador de su suscripción} por el identificador más reciente de la Suscripción de Concierge.

   az account set --subscription {your subscription ID}
   

Establecimiento del grupo de recursos predeterminado

Al usar la CLI de Azure, puede establecer el grupo de recursos predeterminado y omitir el parámetro del resto de los comandos de la CLI de Azure de este ejercicio. Establezca el valor predeterminado en el grupo de recursos que se ha creado de forma automática en el entorno del espacio aislado.

az configure --defaults group="<rgn>[sandbox resource group name]</rgn>"

Para implementar esta plantilla en Azure, inicie sesión en la cuenta de Azure desde el terminal de Visual Studio Code. Asegúrese de haber instalado Azure PowerShell e inicie sesión en la misma cuenta que ha activado el espacio aislado.

1. En el menú Terminal, seleccione Nuevo terminal. Normalmente, la ventana de terminal se abre en la mitad inferior de la pantalla.

2. Si el shell que se muestra en el lado derecho de la ventana de terminal es powershell o pwsh, el shell correcto está abierto y puede ir a la sección siguiente.

   

3. Si apareciera un shell distinto de powershell o pwsh, seleccione la flecha de la lista desplegable del shell y, a continuación, seleccione PowerShell.

   

4. En la lista de shells de terminal, seleccione powershell o pwsh.

   

5. En el terminal, vaya al directorio donde ha guardado la plantilla. Por ejemplo, si ha guardado la plantilla en la carpeta templates, puede usar este comando:

   Set-Location -Path templates
   

Instalación de la CLI de Bicep

Para usar Bicep desde Azure PowerShell, instale la CLI de Bicep.

Inicio de sesión en Azure mediante Azure PowerShell

1. En el terminal de Visual Studio Code, ejecute el comando siguiente:

   Connect-AzAccount
   

   Se abre un explorador para que pueda iniciar sesión en la cuenta de Azure.

2. Después de iniciar sesión, en el terminal se muestra una lista de las suscripciones asociadas a esta cuenta.

   Si ha activado el espacio aislado, se muestra una suscripción denominada Suscripción de Concierge. Úsela para el resto del ejercicio.

3. Establezca la suscripción predeterminada para todos los comandos de Azure PowerShell que ejecute en esta sesión.

   $context = Get-AzSubscription -SubscriptionName 'Concierge Subscription'
   Set-AzContext $context
   

   Nota:

   Si ha usado más de un espacio aislado recientemente, es posible que en el terminal se muestre más de una instancia de Suscripción de Concierge. En este caso, siga estos dos pasos para establecer una de las suscripciones como la predeterminada. Si el comando anterior se ha realizado correctamente y solo se muestra una Suscripción de Concierge, omita los dos pasos siguientes.

4. Obtenga el identificador de la suscripción. Al ejecutar el comando siguiente se mostrarán las suscripciones y sus identificadores. Busque Concierge Subscription y copie el identificador de la segunda columna. Tiene un aspecto similar a aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e.

   Get-AzSubscription
   

5. Cambie la suscripción activa a la Suscripción de Concierge. Asegúrese de reemplazar {identificador de la suscripción} por el que ha copiado.

   $context = Get-AzSubscription -SubscriptionId {Your subscription ID}
   Set-AzContext $context
   

Establecimiento del grupo de recursos predeterminado

Puede establecer el grupo de recursos predeterminado y omitir el parámetro del resto de los comandos de Azure PowerShell de este ejercicio. Establezca este valor predeterminado en el grupo de recursos que se ha creado de forma automática en el entorno del espacio aislado.

Set-AzDefault -ResourceGroupName <rgn>[sandbox resource group name]</rgn>

Para implementar esta plantilla en Azure, debe iniciar sesión en la cuenta de Azure desde el terminal de Visual Studio Code. Asegúrese de que tiene instalada la CLI de Azure y de que inicia sesión con la misma cuenta que utilizó para activar el espacio aislado.

1. En el menú Terminal, seleccione Nuevo terminal. Normalmente, la ventana de terminal se abre en la mitad inferior de la pantalla.

2. Si el shell que se muestra en el lado derecho de la ventana de terminal es Bash, el shell correcto está abierto y puede ir a la sección siguiente.

   

3. Si apareciera un shell distinto de Bash, seleccione la flecha de la lista desplegable del shell y, a continuación, seleccione Azure Cloud Shell (Bash).

   

4. En la lista de shells de terminal, seleccione Bash.

   

5. En el terminal, vaya al directorio donde ha guardado la plantilla. Por ejemplo, si ha guardado la plantilla en la carpeta templates, puede usar este comando:

   cd templates
   

Inicio de sesión en Azure

1. En el terminal de Visual Studio Code, inicie sesión en Azure mediante el siguiente comando:

   az login
   

2. En el explorador que se abre, inicie sesión en su cuenta de Azure.

   En el terminal de Visual Studio Code se muestra una lista de las suscripciones asociadas a esta cuenta.

3. Establezca la suscripción predeterminada para todos los comandos de la CLI de Azure que ejecute en esta sesión.

   az account set --subscription "Concierge Subscription"
   

   Nota:

   Si ha usado más de un espacio aislado recientemente, es posible que en el terminal se muestre más de una instancia de Suscripción de Concierge. En este caso, siga estos dos pasos para establecer una de las suscripciones como la predeterminada. Si el comando anterior se ha realizado correctamente y solo se muestra una Suscripción de Concierge, omita los dos pasos siguientes.

4. Obtenga los identificadores de la Suscripción de Concierge.

    az account list \
      --refresh \
      --query "[?contains(name, 'Concierge Subscription')].id" \
      --output table
   

5. Establezca la suscripción predeterminada con el identificador de la suscripción. Reemplace {identificador de su suscripción} por el identificador más reciente de la Suscripción de Concierge.

   az account set --subscription {your subscription ID}
   

Establecimiento del grupo de recursos predeterminado

Al usar la CLI de Azure, puede establecer el grupo de recursos predeterminado y omitir el parámetro del resto de los comandos de la CLI de Azure de este ejercicio. Establezca el valor predeterminado en el grupo de recursos que se ha creado de forma automática en el entorno del espacio aislado.

az configure --defaults group="<rgn>[sandbox resource group name]</rgn>"

Para implementar esta plantilla en Azure, inicie sesión en la cuenta de Azure desde el terminal de Visual Studio Code. Asegúrese de haber instalado Azure PowerShell e inicie sesión en la misma cuenta que ha activado el espacio aislado.

1. En el menú Terminal, seleccione Nuevo terminal. Normalmente, la ventana de terminal se abre en la mitad inferior de la pantalla.

2. Si el shell que se muestra en el lado derecho de la ventana de terminal es powershell o pwsh, el shell correcto está abierto y puede ir a la sección siguiente.

   

3. Si apareciera un shell distinto de powershell o pwsh, seleccione la flecha de la lista desplegable del shell y, a continuación, seleccione PowerShell.

   

4. En la lista de shells de terminal, seleccione powershell o pwsh.

   

5. En el terminal, vaya al directorio donde ha guardado la plantilla. Por ejemplo, si ha guardado la plantilla en la carpeta templates, puede usar este comando:

   Set-Location -Path templates
   

Inicio de sesión en Azure mediante Azure PowerShell

1. En el terminal de Visual Studio Code, ejecute el comando siguiente:

   Connect-AzAccount
   

   Se abre un explorador para que pueda iniciar sesión en la cuenta de Azure.

2. Después de iniciar sesión, en el terminal se muestra una lista de las suscripciones asociadas a esta cuenta.

   Si ha activado el espacio aislado, se muestra una suscripción denominada Suscripción de Concierge. Úsela para el resto del ejercicio.

3. Establezca la suscripción predeterminada para todos los comandos de Azure PowerShell que ejecute en esta sesión.

   $context = Get-AzSubscription -SubscriptionName 'Concierge Subscription'
   Set-AzContext $context
   

   Nota:

   Si ha usado más de un espacio aislado recientemente, es posible que en el terminal se muestre más de una instancia de Suscripción de Concierge. En este caso, siga estos dos pasos para establecer una de las suscripciones como la predeterminada. Si el comando anterior se ha realizado correctamente y solo se muestra una Suscripción de Concierge, omita los dos pasos siguientes.

4. Obtenga el identificador de la suscripción. Al ejecutar el comando siguiente se mostrarán las suscripciones y sus identificadores. Busque Concierge Subscription y copie el identificador de la segunda columna. Tiene un aspecto similar a aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e.

   Get-AzSubscription
   

5. Cambie la suscripción activa a la Suscripción de Concierge. Asegúrese de reemplazar {identificador de la suscripción} por el que ha copiado.

   $context = Get-AzSubscription -SubscriptionId {Your subscription ID}
   Set-AzContext $context
   

Establecimiento del grupo de recursos predeterminado

Puede establecer el grupo de recursos predeterminado y omitir el parámetro del resto de los comandos de Azure PowerShell de este ejercicio. Establezca este valor predeterminado en el grupo de recursos que se ha creado de forma automática en el entorno del espacio aislado.

Set-AzDefault -ResourceGroupName <rgn>[sandbox resource group name]</rgn>

Publicación de la plantilla como una 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 `
  -Location westus `
  -DisplayName 'Cosmos DB account' `
  -Description "This template spec creates a Cosmos DB account that meets our company's requirements." `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -ResourceGroupName <rgn>[sandbox resource group name]</rgn> `
  -Name ToyCosmosDBAccount `
  -Location westus `
  -DisplayName 'Cosmos DB account' `
  -Description "This template spec creates a Cosmos DB account that meets our company's requirements." `
  -Version '1.0' `
  -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 \
  --location westus \
  --display-name "Cosmos DB account" \
  --description "This template spec creates a Cosmos DB account that meets our company's requirements." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name ToyCosmosDBAccount \
  --location westus \
  --display-name "Cosmos DB account" \
  --description "This template spec creates a Cosmos DB account that meets our company's requirements." \
  --version 1.0 \
  --template-file azuredeploy.json

Uso de Azure Portal para comprobar la especificación de plantilla

1. Vaya a Azure Portal y asegúrese de que está en la suscripción de espacio aislado:

   1. Seleccione el avatar en la esquina superior derecha de la página.
   2. Seleccione Cambiar directorio. En la lista, seleccione el directorio Espacio aislado de Microsoft Learn.

2. En el panel izquierdo, seleccione Grupos de recursos.

3. Seleccione [nombre del grupo de recursos del espacio aislado]. Observe que la especificación de plantilla se incluye en la lista de recursos:

   

4. Seleccione ToyCosmosDBAccount para abrir la especificación de plantilla. Las versiones y el archivo de plantilla están visibles.

   

Implementación de la especificación de plantilla

Para que sea más sencillo, implementarás la especificación de plantilla en el mismo grupo de recursos de espacio aislado en el que se almacena la propia especificación de plantilla. Normalmente, se mantienen las especificaciones de plantilla en otro grupo de recursos. Sin embargo, los pasos son los mismos en ambos casos.

1. Para obtener el identificador de recurso de la 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 1.0 `
      ).Versions[0].Id
   

   Tenga en cuenta que usa la propiedad Versions. Al implementar una especificación de plantilla, debe hacer referencia al identificador de recurso de la versión específica de la especificación de plantilla que se va a usar.

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

   New-AzResourceGroupDeployment -TemplateSpecId $templateSpecVersionResourceId
   

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 "1.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
   

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 el vínculo 1 correcta para ver los detalles de la implementación.

   

3. Seleccione la implementación.

   

   El nombre de la implementación podría ser diferente al del ejemplo.

4. Seleccione Detalles de implementación para expandirlo. Confirma que se ha implementado una cuenta de Azure Cosmos DB.