Inicio rápido: Definición y asignación de una instancia de Azure Blueprints con la CLI de Azure

Artículo
09/07/2023

Importante

El 11 de julio de 2026, Blueprints (versión preliminar) quedará en desuso. Migre las definiciones y asignaciones de planos técnicos existentes a Especificaciones de plantilla y Pilas de implementación. Los artefactos de plano técnico se convertirán en plantillas JSON de ARM o archivos de Bicep que se usan para definir pilas de implementación. Para obtener información sobre cómo crear un artefacto como un recurso de ARM, consulte:

En este tutorial, aprenderá a usar planos técnicos de Azure Blueprints para realizar algunas de las tareas más comunes relacionadas con la creación, publicación y asignación de planos técnicos en toda la organización. Esta aptitud ayuda a definir patrones comunes para desarrollar configuraciones reutilizables y que se pueden implementar rápidamente, basadas en plantillas, directivas y seguridad de Azure Resource Manager (ARM).

Requisitos previos

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Si es la primera vez que usa Azure Blueprints, registre el proveedor de recursos a través de la CLI de Azure con az provider register --namespace Microsoft.Blueprint.

Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.

Para iniciar Azure Cloud Shell:

Opción	Ejemplo o vínculo
Seleccione Pruébelo en la esquina superior derecha de un bloque de código o de comandos. Solo con seleccionar Pruébelo no se copia automáticamente el código o comando en Cloud Shell.
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.

Para usar Azure Cloud Shell:

Inicie Cloud Shell.
Seleccione el botón Copiar en un bloque de código (o bloque de comandos) para copiar el código o comando.
Pegue el código o comando en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.
Seleccione Entrar para ejecutar el código o comando.

Adición de la extensión de plano técnico

Para habilitar la CLI de Azure para administrar definiciones y asignaciones de planos técnicos, debe agregar la extensión. Esta extensión funcionará siempre que se pueda usar la CLI de Azure. Incluye Bash en Windows 10, Cloud Shell (tanto la versión independiente como la del portal), la imagen de Docker de la CLI de Azure o una extensión instalada localmente.

Compruebe que está instalada la versión más reciente de la CLI de Azure (al menos la 2.0.76). Si todavía no está instalado, siga estas instrucciones.

En el entorno que prefiera de la CLI de Azure, importe la extensión con el siguiente comando:

# Add the Blueprint extension to the Azure CLI environment
az extension add --name blueprint

Compruebe que la extensión se ha instalado y que es la versión esperada (al menos 0.1.0):

# Check the extension list (note that you might have other extensions installed)
az extension list

# Run help for extension options
az blueprint -h

Creación de un plano técnico

El primer paso para definir un patrón estándar de cumplimiento es elaborar un plano técnico a partir de los recursos disponibles. Vamos a crear un plano técnico llamado MyBlueprint para configurar las asignaciones de roles y directivas de la suscripción. A continuación, agregará un grupo de recursos, una plantilla de Resource Manager y una asignación de roles en el grupo de recursos.

Nota

Cuando se usa la CLI de Azure, el objeto plano técnico se crea primero. Para cada artefacto que se agregue y que tenga parámetros, defina los parámetros de antemano en el plano técnico inicial.

Cree el objeto blueprint inicial. El parámetro parameters toma un archivo JSON que incluye todos los parámetros de nivel de plano técnico. Los parámetros se establecen durante la asignación y los usan los artefactos que agregue en pasos posteriores.

Archivo JSON: blueprintparms.json

{
   "storageAccountType": {
       "type": "string",
       "defaultValue": "Standard_LRS",
       "allowedValues": [
           "Standard_LRS",
           "Standard_GRS",
           "Standard_ZRS",
           "Premium_LRS"
       ],
       "metadata": {
           "displayName": "storage account type.",
           "description": null
       }
   },
   "tagName": {
       "type": "string",
       "metadata": {
           "displayName": "The name of the tag to provide the policy assignment.",
           "description": null
       }
   },
   "tagValue": {
       "type": "string",
       "metadata": {
           "displayName": "The value of the tag to provide the policy assignment.",
           "description": null
       }
   },
   "contributors": {
       "type": "array",
       "metadata": {
           "description": "List of AAD object IDs that is assigned Contributor role at the subscription",
           "strongType": "PrincipalId"
       }
   },
   "owners": {
       "type": "array",
       "metadata": {
           "description": "List of AAD object IDs that is assigned Owner role at the resource group",
           "strongType": "PrincipalId"
       }
   }
}

Comando de la CLI de Azure
```
# Login first with az login if not using Cloud Shell

# Create the blueprint object
az blueprint create \
   --name 'MyBlueprint' \
   --description 'This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.' \
   --parameters blueprintparms.json
```
Nota

Use el nombre de archivo blueprint.json al importar las definiciones de plano técnico. Este nombre de archivo se usa al llamar a az blueprint import.

El objeto blueprint se crea en la suscripción predeterminada de forma predeterminada. Para especificar el grupo de administración, use el parámetro managementgroup. Para especificar la suscripción, use el parámetro subscription.

Agregue el grupo de recursos para los artefactos de almacenamiento a la definición.

az blueprint resource-group add \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'storageRG' \
   --description 'Contains the resource template deployment and a role assignment.'

Agregue una asignación de roles a la suscripción. En el siguiente ejemplo, las identidades de la entidad de servicio a las que se ha asignado el rol especificado se configuran con un parámetro que se establece durante la asignación de planos técnicos. En este ejemplo se usa el rol integrado Contributor con el GUID de b24988ac-6180-42a0-ab88-20f7382dd24c.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleContributor' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c' \
   --principal-ids "[parameters('contributors')]"
```

Agregue una asignación de directiva a la suscripción. En este ejemplo se usa la directiva integrada Apply tag and its default value to resource groups con el GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

Archivo JSON: artifacts\policyTags.json

{
   "tagName": {
      "value": "[parameters('tagName')]"
   },
   "tagValue": {
      "value": "[parameters('tagValue')]"
   }
}

Comando de la CLI de Azure

az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply tag and its default value to resource groups' \
   --description 'Apply tag and its default value to resource groups' \
   --parameters artifacts\policyTags.json

Nota

Si usa az blueprint en un equipo Mac, reemplace \ por / cuando se usen valores de parámetro que incluyan la ruta de acceso. En este caso, el valor de parameters se convierte en artifacts/policyTags.json.

Agregue otra asignación de directiva para la etiqueta de almacenamiento (mediante la reutilización de storageAccountType_ parameter) en la suscripción. Este artefacto de asignación de directivas adicional muestra que un parámetro definido en el plano técnico lo puede utilizar más de un artefacto. En el ejemplo, se usa storageAccountType para establecer una etiqueta en el grupo de recursos. Este valor proporciona información acerca de la cuenta de almacenamiento que crea en el paso siguiente. En este ejemplo se usa la directiva integrada Apply tag and its default value to resource groups con el GUID de 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- Archivo JSON: artifacts\policyStorageTags.json
```
{
   "tagName": {
      "value": "StorageType"
   },
   "tagValue": {
      "value": "[parameters('storageAccountType')]"
   }
}
```
- Comando de la CLI de Azure
```
az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyStorageTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply storage tag to resource group' \
   --description 'Apply storage tag and the parameter also used by the template to resource groups' \
   --parameters artifacts\policyStorageTags.json
```
  Nota
  
  Si usa az blueprint en un equipo Mac, reemplace \ por / cuando se usen valores de parámetro que incluyan la ruta de acceso. En este caso, el valor de parameters se convierte en artifacts/policyStorageTags.json.

Agregue una plantilla en el grupo de recursos. El parámetro template de una plantilla de Resource Manager incluye los componentes JSON normales de la plantilla. La plantilla también reutiliza los parámetros de plano técnico storageAccountType, tagName y tagValue pasando cada uno a la plantilla. Los parámetros del plano técnico se ponen a disposición de la plantilla mediante el parámetro parameters y dentro de la plantilla JSON en la que se utiliza el par clave-valor para insertar el valor. Los nombres de los parámetros blueprint y template podrían ser los mismos.

Archivo de la plantilla de Resource Manager de JSON: artifacts\templateStorage.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "metadata": {
                "description": "Storage Account type"
            }
        },
        "tagNameFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag name from blueprint"
            }
        },
        "tagValueFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag value from blueprint"
            }
        }
    },
    "variables": {
        "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
    },
    "resources": [{
        "type": "Microsoft.Storage/storageAccounts",
        "name": "[variables('storageAccountName')]",
        "apiVersion": "2016-01-01",
        "tags": {
            "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
        },
        "location": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

Archivo de parámetros de la plantilla de Resource Manager de JSON: artifacts\templateStorageParams.json

{
   "storageAccountTypeFromBP": {
      "value": "[parameters('storageAccountType')]"
   },
   "tagNameFromBP": {
      "value": "[parameters('tagName')]"
   },
   "tagValueFromBP": {
      "value": "[parameters('tagValue')]"
   }
}

Comando de la CLI de Azure
```
az blueprint artifact template create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'templateStorage' \
   --template artifacts\templateStorage.json \
   --parameters artifacts\templateStorageParams.json \
   --resource-group-art 'storageRG'
```
Nota

Si usa az blueprint en un equipo Mac, reemplace \ por / cuando se usen valores de parámetro que incluyan la ruta de acceso. En este caso, el valor de template se convierte en artifacts/templateStorage.json y parameters en artifacts/templateStorageParams.json.

Agregue la asignación de roles en el grupo de recursos. Igual que con la entrada anterior de asignación de roles, en el ejemplo siguiente se usa el identificador de definición para el rol Owner y se proporciona un parámetro diferente del plano técnico. En este ejemplo se usa el rol integrado Owner con el GUID de 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleOwner' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635' \
   --principal-ids "[parameters('owners')]" \
   --resource-group-art 'storageRG'
```

Publicación de un plano técnico

Ahora que ha agregado los artefactos al plano técnico, es hora de publicarlo. La publicación hace que el plano técnico esté disponible para asignarse a una suscripción.

az blueprint publish --blueprint-name 'MyBlueprint' --version '{BlueprintVersion}'

El valor de {BlueprintVersion} es una cadena de letras, números y guiones (sin espacios ni otros caracteres especiales). La longitud máxima es de 20 caracteres. Utilice un nombre único e informativo, como v20200605-135541.

Asignación de un plano técnico

Cuando haya publicado un plano técnico con la CLI de Azure, se puede asignar a una suscripción. Asigne el plano técnico que ha creado a una de las suscripciones de la jerarquía de su grupo de administración. Si el proyecto se guarda en una suscripción, solo se puede asignar a dicha suscripción. El parámetroblueprint-name especifica el plano técnico que se va a asignar. Para proporcionar los parámetros name, location, identity, lock y blueprint, use los parámetros de la CLI de Azure correspondientes en el comando az blueprint assignment create o proporciónelos en el archivo JSON de parámetros.

Ejecute la implementación del plano técnico asignándolo a una suscripción. Dado que los parámetros contributors y owners requieren una matriz de objectIds de las entidades de servicio para que se les conceda la asignación de roles, utilice Graph API de Azure Active Directory para recopilar los elementos objectIds que se utilizarán en el archivo parameters para sus propios usuarios, grupos o entidades de servicio.
- Archivo JSON: blueprintAssignment.json
```
{
   "storageAccountType": {
       "value": "Standard_GRS"
   },
   "tagName": {
       "value": "CostCenter"
   },
   "tagValue": {
       "value": "ContosoIT"
   },
   "contributors": {
       "value": [
           "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
           "38833b56-194d-420b-90ce-cff578296714"
       ]
   },
   "owners": {
       "value": [
           "44254d2b-a0c7-405f-959c-f829ee31c2e7",
           "316deb5f-7187-4512-9dd4-21e7798b0ef9"
       ]
   }
}
```
- Comando de la CLI de Azure
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
- Identidad administrada asignada por el usuario
  
  Una asignación de plano técnico también puede usar una identidad administrada asignada por el usuario. En este caso, el parámetro identity-type se establece en UserAssigned y el parámetro user-assigned-identities especifica la identidad. Reemplace {userIdentity} por el nombre de la identidad administrada asignada por el usuario.
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --identity-type UserAssigned \
   --user-assigned-identities {userIdentity} \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
  La identidad administrada asignada por el usuario puede estar en cualquier suscripción y grupo de recursos para los que tenga permiso el usuario que asigna el plano técnico.
  
  Importante
  
  Azure Blueprints no administra la identidad administrada asignada por el usuario. Los usuarios son responsables de asignar los roles y permisos necesarios o la asignación del plano técnico producirá un error.

Limpieza de recursos

Puede eliminar un plano de una suscripción. A menudo, la eliminación se realiza cuando ya no son necesarios los recursos de artefacto. Cuando se quita un plano técnico, se omiten los artefactos que se asignaron como parte de ese plano técnico. Para eliminar una asignación de plano técnico, use el comando az blueprint assignment delete:

az blueprint assignment delete --name 'assignMyBlueprint'

Pasos siguientes

En este inicio rápido, ha creado, asignado y eliminado un plano técnico con la CLI de Azure. Para más información sobre Azure Blueprints, vaya el artículo sobre el ciclo de vida de los planos técnicos.

Más información acerca del ciclo de vida del plano técnico