Control de diferencias entre entornos mediante parámetros de Bicep

7 minutos

Ya ha obtenido información sobre los parámetros de Bicep. Le ayudan a especificar valores que pueden cambiar entre implementaciones de los archivos de Bicep.

Los parámetros se usan normalmente para admitir las diferencias entre los entornos. Por ejemplo, en los entornos que no son de producción, a menudo se quieren implementar SKU asequibles de los recursos de Azure. En producción se quieren implementar SKU con un mejor rendimiento. Además, es posible que quiera usar nombres diferentes para los recursos de cada entorno.

Al implementar el archivo de Bicep, se proporcionan valores para cada parámetro. Hay varias opciones para la forma de especificar los valores de cada parámetro de la canalización y para la forma de especificar valores independientes para cada entorno. En esta unidad va a conocer los enfoques para especificar valores de parámetro de Bicep en una canalización de implementación.

Archivos de parámetros

Un archivo de parámetros es un archivo con formato JSON que indica los valores de parámetro que se quieren usar para cada entorno. El archivo de parámetros se envía a Azure Resource Manager al enviar la implementación.

Este es un archivo de parámetros de ejemplo:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "reviewApiUrl": {
      "value": "https://sandbox.contoso.com/reviews"
    }
  }
}

Los archivos de parámetros se pueden confirmar en el repositorio de Git junto con el archivo de Bicep. Luego se puede hacer referencia al archivo de parámetros en la plantilla de canalización donde se ejecuta la implementación.

Es buena idea establecer una estrategia coherente de nomenclatura de entornos para los archivos de parámetros. Por ejemplo, puede dar a los archivos de parámetros el nombre parameters.NOMBRE_ENTORNO.json, como parameters.Producción.json. Luego puede usar un parámetro de plantilla de canalización para seleccionar automáticamente el archivo de parámetros correcto.

parameters: 
- name: environmentType
  type: string
- name: serviceConnectionName
  type: string
- name: resourceGroupName
  type: string

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: ${{parameters.serviceConnectionName}}
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentType}}.json

Cuando se usan archivos de parámetros, los archivos YAML de canalización no necesitan contener una lista de parámetros que se deben pasar individualmente a los pasos de implementación. Esto resulta muy útil cuando se tiene un gran número de parámetros.

Un archivo de parámetros mantiene los valores de parámetro juntos en un único archivo JSON. Los archivos de parámetros también forman parte del repositorio de Git, por lo que pueden tener versiones igual que el resto del código.

Importante

Los archivos de parámetros no deben usarse para valores seguros. No hay forma de proteger los valores de los secretos en los archivos de parámetros, y nunca se deben confirmar secretos en el repositorio de Git.

Variables de canalización

Azure Pipelines permite almacenar variables de canalización, que son útiles para los valores que pueden diferir entre entornos. También son útiles para los valores que se quieren definir una sola vez y luego reutilizar en toda la canalización. Azure Pipelines admite varias maneras de definir variables.

Variables definidas en un archivo YAML

Puede definir variables y establecer sus valores en un archivo YAML. Esto resulta útil cuando es necesario reutilizar el mismo valor varias veces. Pero, al igual que los archivos de parámetros de Bicep, los archivos YAML no son adecuados para los secretos.

Variables definidas en la interfaz web

Puede definir variables mediante la interfaz web de Azure DevOps. Puede cambiar los valores de variable en cualquier momento; la canalización lee los valores actualizados la siguiente vez que se ejecuta.

Las variables definidas por medio de la interfaz web se pueden marcar como secretas, lo cual indica a Azure Pipelines que intente ocultar los valores de las variables en los registros de canalización. Esto significa que es posible almacenar valores que el archivo de Bicep acepta como parámetros con el decorador @secure().

Advertencia

De forma predeterminada, Azure Pipelines ofusca los valores de variable secretos en los registros de las canalizaciones, pero también debe seguir buenas prácticas. Los pasos de las canalizaciones tienen acceso a todos los valores de variable, incluidos los secretos. Si la canalización incluye un paso que no controla una variable protegida de forma segura, existe la posibilidad de que la variable secreta se pueda mostrar en los registros de la canalización.

Grupos de variables

También puede definir grupos de variables, que son conjuntos de variables. Al igual que las variables, estos grupos se definen mediante la interfaz web de Azure DevOps. También puede usar grupos de variables para almacenar secretos de forma segura. Los grupos de variables incluso se pueden reutilizar en varias canalizaciones del mismo proyecto de Azure DevOps.

A diferencia de otras variables, un grupo de variables se debe importar explícitamente en una canalización mediante la palabra clave group en una sección variables, así:

variables:
- group: MyVariableGroup

Al trabajar con plantillas de canalización, puede asignar nombre a los grupos de variables para poder cargarlos fácilmente mediante un parámetro de plantilla. Por ejemplo, imagine que la canalización se implementa en dos entornos y que debe definir un conjunto de variables para cada entorno. Puede asignar nombre a los grupos de variables con los nombres de entorno incluidos, así:

Nombre del entorno	Nombre del grupo de variables
Prueba	`ToyWebsiteTest`
Producción	`ToyWebsiteProduction`

En cada uno de estos grupos de variables se agregan variables con los mismos nombres pero con valores distintos para cada entorno.

El archivo de plantilla de canalización usa la macro {{ parameters.PARAMETER_NAME }} para seleccionar el grupo de variables correcto que se va a importar:

parameters: 
- name: environmentType
  type: string
  default: 'Test'

variables: 
- group: ToyWebsite${{ parameters.environmentType }}

Grupos de variables de Key Vault

Puede vincular grupos de variables a Azure Key Vault. Los secretos del almacén de claves quedan disponibles como variables en el grupo de variables. Entonces los secretos se pueden usar en las canalizaciones como si fueran variables normales.

Key Vault hace que la administración de los secretos sea más segura. También permite que el equipo de seguridad administre esos valores, y separar el acceso a las canalizaciones de los secretos que usa.

Se requieren más pasos para vincular un grupo de variables a un almacén de claves. Estos pasos incluyen la creación de una conexión de servicio que tenga permiso para leer los secretos del almacén de claves. En la unidad de resumen se proporciona un vínculo a más detalles sobre cómo configurar grupos de variables de Key Vault.

Uso de variables en la canalización

Independientemente de cómo se defina una variable, se puede acceder a su valor en la canalización mediante la sintaxis $(VariableName). Por ejemplo, al ejecutar una implementación de Bicep, puede usar una variable para especificar el valor de un parámetro:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group $(ResourceGroupName) \
                    --template-file deploy/main.bicep \
                    --parameters environmentType=$(EnvironmentType)

Enfoque óptimo

Ha aprendido varias maneras de controlar los parámetros que el archivo de Bicep necesita para la implementación. Resulta útil comprender cuándo se puede usar cada enfoque.

Omisión de parámetros innecesarios

Los parámetros ayudan a que los archivos de Bicep se puedan reutilizar, aunque es fácil definir demasiados parámetros. Al implementar un archivo de Bicep, debe proporcionar un valor para cada parámetro. En implementaciones complejas en varios entornos, resulta difícil administrar un gran conjunto de valores de parámetro individuales.

Considere la posibilidad de convertir los parámetros en opcionales donde pueda y de usar valores predeterminados que se apliquen a la mayoría de los entornos. Así puede evitar la necesidad de que las canalizaciones pasen valores para los parámetros.

Además, tenga en cuenta que los parámetros se suelen usar en Bicep cuando los recursos necesitan conectarse a otros recursos. Por ejemplo, si tiene un sitio web que necesita conectarse a una cuenta de almacenamiento, debe proporcionar el nombre de la cuenta de almacenamiento y la clave de acceso. Las claves son valores seguros. Pero tenga en cuenta estos otros enfoques al implementar esta combinación de recursos:

Use la identidad administrada del sitio web para acceder a la cuenta de almacenamiento. Al crear una identidad administrada, Azure genera y administra automáticamente sus credenciales. Este enfoque simplifica la configuración de la conexión. También significa que no hay que controlar los secretos en absoluto, por lo que es la opción más segura.
Implemente la cuenta de almacenamiento y el sitio web juntos en la misma plantilla de Bicep. Use módulos de Bicep para mantener juntos el sitio web y los recursos de almacenamiento. Luego puede buscar automáticamente los valores del nombre de la cuenta de almacenamiento y la clave en el código de Bicep, en lugar de pasar parámetros.
Agregue los detalles de la cuenta de almacenamiento a un almacén de claves como secreto. Luego el código del sitio web carga la clave de acceso directamente desde el almacén. Este enfoque evita totalmente la necesidad de administrar la clave en la canalización.

Uso de grupos de variables para conjuntos pequeños de parámetros

Si solo tiene unos cuantos parámetros para los archivos de Bicep, considere la posibilidad de usar un grupo de variables. Puede almacenar valores secretos y no secretos en grupos de variables.

Uso de archivos de parámetros para grandes conjuntos de parámetros

Si tiene un gran conjunto de parámetros para los archivos de Bicep, considere la posibilidad de usar archivos de parámetros para mantener juntos los valores no seguros para cada entorno. Luego, siempre que necesite cambiar los valores, puede actualizar un archivo de parámetros y confirmar el cambio.

Este enfoque hace que los pasos de canalización sean más sencillos, ya que no es necesario establecer explícitamente el valor de cada parámetro.

Almacenamiento de secretos de forma segura

Use un proceso adecuado para almacenar y controlar secretos. Si solo tiene unos pocos secretos que administrar, las variables y los grupos de variables de Azure Pipelines suelen funcionar bien. Pero es posible que tenga requisitos más complejos, como un gran número de secretos, muchos entornos diferentes o restricciones de control de acceso. En estas situaciones, considere la posibilidad de almacenar los secretos de cada entorno en almacenes de claves independientes. Use grupos de variables para vincular los almacenes a la canalización.

En el caso de los parámetros seguros, no olvide pasar explícitamente cada parámetro en los pasos de implementación.

Combinación de enfoques

Es habitual combinar varios enfoques para controlar los parámetros. Por ejemplo, puede almacenar la mayoría de los valores de parámetro en archivos de parámetros y, luego, establecer valores seguros mediante un grupo de variables. En el ejemplo siguiente se muestra la combinación:

variables:
- group: MyVariableGroup # This group imports a parameter named MySecureParameter.

stages:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentName}}.json \
                                 mySecureParameter=$(MySecureParameter)

Hay reglas especiales sobre cómo especificar nombres de conexión de servicio. Estas reglas pueden afectar a cómo se usan los nombres en las canalizaciones que se implementan en varios entornos. Por ejemplo, no puede usar una variable definida en un grupo de variables para especificar un nombre de conexión de servicio. Puede usar parámetros de plantilla de canalización para especificar el nombre de la conexión de servicio que se va a usar.