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 del flujo de trabajo 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 un flujo de trabajo 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 flujo de trabajo 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. Después, puede usar una entrada de plantilla de flujo de trabajo para seleccionar automáticamente el archivo de parámetros correcto en función de un valor de entrada.

on:
  workflow_call:
    inputs:
      environmentType:
        required: true
        type: string
      # ...

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # ...
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json

Cuando se usan archivos de parámetros, los archivos YAML de flujo de trabajo no necesitan contener una lista de parámetros que se deben pasar individualmente a los pasos de implementación. Esto resulta especialmente ú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 flujo de trabajo

Acciones de GitHub permite almacenar variables de flujo de trabajo, 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 reutilizar después en todo el flujo de trabajo.

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. Puede definir una variable para todo un flujo de trabajo, un trabajo o un solo paso:

env:
  MyVariable1: value1

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyVariable2: value2
    steps:
    - run: echo Hello world!
      env:
        MyVariable3: value3

Secretos definidos en la interfaz web

Al igual que los archivos de parámetros de Bicep, los archivos YAML no son adecuados para los secretos. Puede definir secretos mediante la interfaz web de GitHub. Puede cambiar los valores de variable en cualquier momento; el flujo de trabajo lee los valores actualizados la siguiente vez que se ejecuta. Acciones de GitHub intenta ocultar los valores de los secretos en los registros de flujo de trabajo. Esto significa que es posible almacenar valores que el archivo de Bicep acepta como parámetros con el decorador @secure().

Advertencia

De forma predeterminada, Acciones de GitHub ofusca los valores de variable secretos en los registros de los flujos de trabajo, pero también debe seguir buenas prácticas. Los pasos del flujo de trabajo tienen acceso a los valores de los secretos. Si el flujo de trabajo incluye un paso que no controla un secreto de forma segura, existe la posibilidad de que el valor del secreto se muestre en los registros del flujo de trabajo. Siempre debe revisar atentamente los cambios que se realicen en el archivo de definición de un flujo de trabajo para comprobar que los secretos no se traten incorrectamente.

Cuando se crea un secreto, GitHub permite elegir si se establece como ámbito todo el repositorio de Git o un entorno específico. Los secretos con ámbito de entorno respetan las reglas de protección que configure en los entornos, por lo que si configura una regla de revisor necesaria, un flujo de trabajo no puede acceder a los valores de secretos hasta que el usuario de GitHub especificado haya aprobado la canalización para implementar en ese entorno.

Los secretos con ámbito de entorno pueden ser útiles, pero no funcionan fácilmente con la validación preparatoria de Azure Resource Manager u operaciones hipotéticas. Estas operaciones deben comunicarse con Azure, lo que significa que necesitan una identidad de carga de trabajo. Por lo general, le interesa proporcionar la aprobación de la implementación después de que se completen las operaciones hipotéticas o la validación preparatoria, de modo que tenga un alto grado de confianza en los cambios que va a implementar. Por lo tanto, si usa secretos con ámbito de entorno, el proceso de revisión humana se produce demasiado pronto en el flujo de trabajo.

Por esta razón, en los ejercicios de este módulo no se usan secretos con ámbito de entorno. En su lugar, creará secretos con ámbito de repositorio con nombres predecibles que incluyan el nombre del entorno. Esto permite que el flujo de trabajo identifique el secreto correcto que se usará para cada entorno. En sus propios flujos de trabajo, puede optar por usar secretos con ámbito de repositorio, secretos con ámbito de entorno o incluso una combinación de ambos.

Nota:

También puede establecer el ámbito de los secretos en organizaciones de GitHub. Aunque esto no lo contempla este módulo, incluimos vínculos a más información en el resumen.

Uso de variables en el flujo de trabajo

La forma de acceder al valor de una variable en el flujo de trabajo depende del tipo de variable.

Tipo Sintaxis
Variables definidas en el mismo archivo ${{ env.VARIABLE_NAME }}
Entradas a un flujo de trabajo llamado ${{ inputs.INPUT_NAME }}
Secretos ${{ secrets.SECRET_NAME }}

Por ejemplo, al ejecutar una implementación de Bicep, podría usar secretos para especificar la identidad de carga de trabajo de Azure que se usará, una entrada de flujo de trabajo llamado para especificar el nombre del grupo de recursos y una variable para especificar el valor de un parámetro:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyParameter: value-of-parameter
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: myParameter=${{ env.MyParameter }}

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 los flujos de trabajo 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 el flujo de trabajo.

Uso de variables de flujo de trabajo para conjuntos pequeños de parámetros

Si solo tiene unos pocos parámetros para los archivos de Bicep, considere la posibilidad de definir variables en el archivo YAML.

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 del flujo de trabajo 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. Use secretos de GitHub para almacenar secretos en el repositorio GitHub, o bien use Key Vault para almacenar secretos en Azure.

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

GitHub puede examinar automáticamente el repositorio en busca de secretos que se hayan confirmado accidentalmente, de modo que reciba una notificación. Después, puede quitar y rotar los secretos. En el resumen se incluye un vínculo a más información sobre esta característica.

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 secreto. En el ejemplo siguiente se muestra la combinación:

on:
  workflow_dispatch:
    inputs:
      environmentType:
        required: true
        type: string
      resourceGroupName:
        required: true
        type: string
    secrets:
      AZURE_CLIENT_ID:
        required: true
      AZURE_TENANT_ID:
        required: true
      AZURE_SUBSCRIPTION_ID:
        required: true
      MySecureParameter:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: >
          ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json
          mySecureParameter=${{ secrets.MySecureParameter }}

Sugerencia

Al final de este ejemplo, el valor parameters se proporciona como una cadena multilínea YAML mediante el carácter >. Esto facilita la lectura del archivo YAML. Es equivalente a incluir todo el valor en una sola línea.