Inicio rápido: Definición y asignación de un plano técnico de Azure con PowerShell

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 aún no se ha instalado, siga las instrucciones en Adición del módulo Az.Blueprint para instalar y validar el módulo Az.Blueprint desde la Galería de PowerShell.
Si es la primera vez que usa Azure Blueprints, registre el proveedor de recursos mediante Azure PowerShell con Register-AzResourceProvider -ProviderNamespace 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 Intro para ejecutar el código o comando.

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 usa PowerShell, el objeto blueprint se crea en primer lugar. 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 BlueprintFile toma un archivo JSON que incluye las propiedades sobre el plano técnico, cualquier grupo de recursos que se vaya a crear y todos los parámetros en el nivel del plano técnico. Los parámetros se establecen durante la asignación y los usan los artefactos que agregue en pasos posteriores.

Archivo JSON: blueprint.json

{
    "properties": {
        "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.",
        "targetScope": "subscription",
        "parameters": {
            "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"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

Comando de PowerShell
```
# Login first with Connect-AzAccount if not using Cloud Shell

# Get a reference to the new blueprint object, we'll use it in subsequent steps
$blueprint = New-AzBlueprint -Name 'MyBlueprint' -BlueprintFile .\blueprint.json
```
Nota

Use el nombre de archivo blueprint.json al crear las definiciones de plano técnico mediante programación. Este nombre de archivo se usa cuando se llama a Import-AzBlueprintWithArtifact.

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

Agregue una asignación de roles a la suscripción: El elemento ArtifactFile define el tipo de artefacto, las propiedades se alinean con el identificador de definición de rol y las identidades principales se pasan como una matriz de valores. 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.
- Archivo JSON: \artifacts\roleContributor.json
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```
- Comando de PowerShell
```
# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json
```

Agregue una asignación de directiva a la suscripción: El elemento ArtifactFile define el tipo de artefacto, las propiedades se alinean con una definición de directiva o iniciativa, y la asignación de directivas se configura para usar los parámetros del plano técnico definidos durante la asignación del plano técnico. 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

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply tag and its default value to resource groups",
        "description": "Apply tag and its default value to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "[parameters('tagName')]"
            },
            "tagValue": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

Comando de PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\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

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply storage tag to resource group",
        "description": "Apply storage tag and the parameter also used by the template to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "StorageType"
            },
            "tagValue": {
                "value": "[parameters('storageAccountType')]"
            }
        }
    }
}

Comando de PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json

Agregue una plantilla en el grupo de recursos. El valor de TemplateFile de una plantilla de ARM incluye el componente JSON normal 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 TemplateParameterFile 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

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "value": "[parameters('storageAccountType')]"
        },
        "tagNameFromBP": {
            "value": "[parameters('tagName')]"
        },
        "tagValueFromBP": {
            "value": "[parameters('tagValue')]"
        }
    }
}

Comando de PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'templateStorage' -TemplateFile .\artifacts\templateStorage.json -TemplateParameterFile .\artifacts\templateStorageParams.json -ResourceGroupName storageRG

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.

Archivo JSON: \artifacts\roleOwner.json

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

Comando de PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleOwner' -ArtifactFile .\artifacts\roleOwner.json

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.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -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 v20180622-135541.

Asignación de un plano técnico

Cuando haya publicado un plano técnico con PowerShell, 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 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 PowerShell correspondientes en el cmdlet New-AzBlueprintAssignment o proporciónelos en el archivo JSON del parámetro AssignmentFile.

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 AssignmentFile para sus propios usuarios, grupos o entidades de servicio.

Archivo JSON: blueprintAssignment.json

{
    "properties": {
        "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint",
        "resourceGroups": {
            "storageRG": {
                "name": "StorageAccount",
                "location": "eastus2"
            }
        },
        "parameters": {
            "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"
                ]
            }
        }
    },
    "identity": {
        "type": "systemAssigned"
    },
    "location": "westus"
}

Comando de PowerShell

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\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, la parte identity del archivo de asignación JSON cambia del modo siguiente. Reemplace {tenantId}, {subscriptionId}, {yourRG} y {userIdentity} por los valores del identificador de inquilino, el identificador de suscripción, el nombre del grupo de recursos y el nombre de su identidad administrada asignada por el usuario, respectivamente.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
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 cmdlet Remove-AzBlueprintAssignment:

assignMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Pasos siguientes

En este inicio rápido, ha creado, asignado y eliminado un plano técnico con PowerShell. 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

Inicio rápido: Definición y asignación de un plano técnico de Azure con PowerShell

Requisitos previos

Azure Cloud Shell

Creación de un plano técnico

Publicación de un plano técnico

Asignación de un plano técnico

Limpieza de recursos

Pasos siguientes

Recursos adicionales