Desbloquear variables de Azure DevOps para automatización

Si has creado un Pipeline de Azure DevOps como solución para un pipeline de CI/CD, sin duda te has encontrado con situaciones que requieren gestionar dinámicamente los valores de configuración en compilaciones y lanzamientos. Ya sea proporcionando una versión de compilación a un script de PowerShell, pasando parámetros dinámicos a tareas de compilación o usando cadenas a lo largo de compilaciones y lanzamientos, necesitas variables.

Si alguna vez te has preguntado cosas como:

• ¿Cómo uso variables de Pipeline de compilación de Azure DevOps en un script de PowerShell?
• ¿Cómo comparto variables entre compilaciones y lanzamientos?
• ¿En qué se diferencian las variables predefinidas, definidas por el usuario y secretas?
• ¿Cómo funcionan los grupos de variables?

…¡entonces estás de suerte! En este artículo responderemos cada una de estas preguntas y más.

Al final de este artículo, ¡entenderás cómo funcionan las variables de compilación de Azure DevOps en los Pipelines de Azure!

¿Qué son las Variables de Pipeline de Azure DevOps?

Antes de adentrarnos en los detalles de las variables, ¿qué son y cómo te ayudan a construir y automatizar pipelines de compilación y lanzamiento eficientes?

Las variables te permiten pasar fragmentos de datos a varias partes de tus pipelines. Las variables son excelentes para almacenar texto y números que pueden cambiar a lo largo del flujo de trabajo de un pipeline. En un pipeline, puedes configurar y leer variables casi en cualquier lugar en lugar de codificar valores en scripts y definiciones YAML.

Nota: Este artículo se centrará únicamente en las canalizaciones YAML. No cubriremos ninguna información sobre las canalizaciones clásicas heredadas. Además, con algunas excepciones menores, no aprenderás cómo trabajar con variables a través de la interfaz web. Nos adheriremos estrictamente a YAML.

Las variables se hacen referencia y algunas se definen (consulta las variables definidas por el usuario) en tiempo de ejecución. Cuando una canalización inicia un trabajo, varios procesos gestionan estas variables y transmiten sus valores a otras partes del sistema. Este sistema proporciona una manera de ejecutar trabajos de canalización dinámicamente sin preocuparse por cambiar las definiciones de compilación y scripts cada vez.

No te preocupes si aún no comprendes el concepto de variables en este punto. El resto de este artículo te enseñará todo lo que necesitas saber.

Entornos de Variables

Antes de sumergirnos en las variables en sí, es importante cubrir los entornos de variables de la canalización de Azure. Verás varias referencias a este término a lo largo del artículo.

Dentro de una canalización, hay dos lugares llamados informalmente entornos donde puedes interactuar con variables. Puedes trabajar con variables dentro de una definición de compilación YAML llamada el entorno de canalización o dentro de un script ejecutado a través de una tarea llamada el entorno de script.

El Entorno del Pipeline

Cuando defines o lees variables de compilación desde una definición de compilación YAML, esto se llama el entorno del pipeline. Por ejemplo, a continuación puedes ver la sección de variables definida en una definición de compilación YAML estableciendo una variable llamada foo a bar. En este contexto, la variable está siendo definida dentro del entorno del pipeline

variables:
  foo: 'bar'

El Entorno del Script

También puedes trabajar con variables desde el código definido en la propia definición YAML o en scripts. Cuando no tienes un script existente creado, puedes definir y leer variables dentro de la definición YAML como se muestra a continuación. Aprenderás la sintaxis sobre cómo trabajar con estas variables en este contexto más adelante.

steps:
 - bash: ## Estableciendo y obteniendo variables aquí

Alternativamente, podrías permanecer en el entorno del script añadiendo esta misma sintaxis en un script de Bash y ejecutándolo. Este es el mismo concepto general.

Variables de Entorno

Dentro del entorno del script, cuando una variable de pipeline está disponible, se hace creando una variable de entorno. Estas variables de entorno luego pueden ser accedidas mediante los métodos típicos del lenguaje elegido.

Las variables de pipeline expuestas como variables de entorno siempre estarán en mayúsculas y cualquier punto será reemplazado con guiones bajos. Por ejemplo, verás a continuación cómo cada lenguaje de script puede acceder a la variable de pipeline foo como se muestra a continuación.

variables:
  foo: 'bar'

• Lote – %FOO%
• PowerShell – $env:FOO
• Script de Bash – $FOO

Fases de “Ejecución de Canalización”

Cuando una canalización “se ejecuta”, no simplemente “se ejecuta”. Al igual que las etapas que contiene, una canalización también pasa por varias fases cuando se ejecuta. Debido a la falta de un término oficial en la documentación de Microsoft, lo llamo “fases de ejecución”.

Cuando se activa una canalización, pasa por tres fases aproximadas: Cola, Compilación y Ejecución. Es importante comprender estos contextos porque si estás navegando por la documentación de Microsoft, verás referencias a estos términos.

Tiempo de Cola

La primera fase por la que pasa una canalización cuando se activa es la de estar en cola. En esta fase, la canalización aún no ha comenzado pero está en cola y lista para ejecutarse cuando el agente esté disponible. Cuando defines variables, puedes establecer que estén disponibles en el tiempo de cola al no definirlas en el archivo YAML.

Puedes definir variables en el tiempo de cola cuando la canalización se pone en cola inicialmente como se muestra a continuación. Cuando se agrega esta variable, entonces estará disponible como una variable global en la canalización y puede ser anulada por la misma variable en el archivo YAML.

Compilación

Finalmente, cuando un pipeline procesa un archivo YAML y llega a los pasos que requieren la ejecución de scripts, el pipeline se encuentra en la “fase” de compilación. En este contexto, el agente está ejecutando el código definido en los pasos del script.

Runtime

La siguiente fase es el tiempo de ejecución. En esta fase, se está procesando el archivo YAML. Durante esta fase, cada etapa, trabajo y paso se están procesando, pero no se están ejecutando scripts.

Expansión de Variables

Otro tema importante de entender es la expansión de variables. La expansión de variables, en términos más simples, ocurre cuando la variable devuelve un valor estático. La variable se expande para revelar el valor que contiene. Esto se hace automáticamente cuando lees una variable, pero esa expansión puede ocurrir en diferentes momentos durante la ejecución de un pipeline, lo que podría causar confusiones.

Este concepto de expansión de variables y compilación frente a tiempo de ejecución surgirá con frecuencia cuando empieces a entender la sintaxis de las variables.

Como aprendiste anteriormente, el pipeline abarca diferentes “fases” cuando se ejecuta. Es probable que necesites estar al tanto de estas fases, especialmente cuando estés solucionando problemas relacionados con la expansión de variables.

Puedes ver un ejemplo a continuación. El concepto de estas “fases” está estrechamente relacionado con los entornos de variables.

steps:
  # Establece FOO en "some value" en el script y los siguientes
  - bash: |
      FOO="runtime value"
      echo "##vso[task.setvariable variable=FOO]$FOO"

  # Utilizando la sintaxis $() durante "tiempo de compilación", el pipeline expande la variable
  - bash: |
      echo "$(FOO)"

  # Utilizando una variable de entorno en el contexto del script en "tiempo de ejecución", bash expande la variable
  - bash: |
      echo "$FOO"

Las variables se expanden una vez cuando se inicia la ejecución del pipeline, y nuevamente al comienzo de cada paso. A continuación, puedes ver un ejemplo simple de este comportamiento.

jobs:
- job: build
  variables:
  - foo: bar 
  steps:
    - bash: |
        echo $(foo)            # This will be bar
        echo '##vso[task.setvariable variable=foo]baz'
        echo $(foo)            # This will also be bar, $(foo) expands before the step
    - bash: echo $(foo)        # Esto será baz. La variable se expande justo antes del paso

Sintaxis de Variable

Como has aprendido, puedes establecer o leer variables en dos “entornos” diferentes: el pipeline y los entornos de script. Mientras estés en cada entorno, la forma en que haces referencia a las variables es un poco diferente. Hay bastantes matices que debes tener en cuenta.

Variables de Pipeline

Las variables de pipeline se hacen referencia en las definiciones de compilación YAML y se pueden hacer referencia mediante tres métodos de sintaxis diferentes: macro, expresión de plantilla y expresión de tiempo de ejecución.

Sintaxis de Macro

La sintaxis más común que encontrarás es la sintaxis de macro. La sintaxis de macro hace referencia a un valor para una variable en forma de $(foo). Los paréntesis representan una expresión que se evalúa en tiempo de ejecución.

Cuando Azure Pipelines procesa una variable definida como una expresión de macro, reemplazará la expresión con el contenido de la variable. Al definir variables con sintaxis de macro, siguen el patrón <nombre de la variable>: $(<valor de la variable>) por ejemplo, foo: $(bar).

Si intentas hacer referencia a una variable con sintaxis de macro y un valor no existe, la variable simplemente no existirá. Este comportamiento difiere un poco entre tipos de sintaxis.

Sintaxis de Expresión de Plantilla

Otro tipo de sintaxis de variable se llama expresión de plantilla. Definir variables de canalización de esta manera toma la forma de ${{ variables.foo }} : ${{ variables.bar }}. Como puedes ver, es un poco más largo que la sintaxis de macro.

La sintaxis de expresión de plantilla también tiene una característica adicional. Utilizando esta sintaxis, también puedes expandir parámetros de plantilla. Si se hace referencia a una variable definida con la sintaxis de expresión de plantilla, la canalización devolverá una cadena vacía en lugar de un valor nulo con la sintaxis de macro.

Las variables de expresión de plantilla se procesan en tiempo de compilación y luego se sobrescriben (si están definidas) en tiempo de ejecución.

Sintaxis de Expresión en Tiempo de Ejecución

Como tipo de sintaxis, se sugiere que las variables de expresión en tiempo de ejecución se expandan solo en tiempo de ejecución. Estos tipos de variables se representan mediante el formato $[variables.foo]. Al igual que las variables de sintaxis de expresión de plantilla, estos tipos de variables devolverán una cadena vacía si no se reemplazan.

Al igual que la sintaxis de macro, la sintaxis de expresión en tiempo de ejecución requiere el nombre de la variable en el lado izquierdo de la definición, como foo: $[variables.bar].

Variables de Script

Trabajar con variables dentro de scripts es un poco diferente que las variables de canalización. Definir y hacer referencia a variables de canalización expuestas en scripts de tarea se puede hacer de dos maneras; con sintaxis de comando de registro o variables de entorno.

Comandos de registro

Una forma de definir y hacer referencia a variables de canalización en scripts es utilizar la sintaxis de comandos de registro. Esta sintaxis es un poco complicada, pero aprenderás que es necesaria en ciertas situaciones. Las variables se definen de esta manera deben ser definidas como una cadena en el script.

Establecer una variable llamada foo con un valor de bar utilizando la sintaxis de comandos de registro se vería así.

"##vso[task.setvariable variable=foo;]bar"

I could not find a way to get the value of variables using logging commands. If this exists, let me know!

Variables de entorno

Cuando las variables de canalización se convierten en variables de entorno en scripts, los nombres de las variables cambian ligeramente. Descubrirás que los nombres de las variables se vuelven mayúsculas y los puntos se convierten en guiones bajos. Encontrarás que muchas variables predefinidas o del sistema tienen puntos en ellas.

Por ejemplo, si se definiera una variable de canalización llamada [foo.bar](<http://foo.bar>), referirías esa variable mediante el método de referencia de variable de entorno nativo del script, como $env:FOO_BAR en PowerShell o $FOO_BAR en Bash.

Cubrimos más sobre las variables de entorno en la sección Entorno de Script anterior.

Ámbito de la variable

A pipeline has various stages, tasks and jobs running. Many areas have predefined variable scopes. A scope is namespace where when a variable is defined, its value can be referenced.

Existen básicamente tres ámbitos de variables diferentes en una jerarquía. Se definen variables a nivel de:

• el nivel raíz, haciendo que las variables estén disponibles para todos los trabajos en la canalización
• el nivel de etapa, haciendo que las variables estén disponibles para una etapa específica
• el nivel de trabajo, haciendo que las variables estén disponibles para un trabajo específico

Variables definidas en los niveles “inferiores”, como un trabajo, anularán la misma variable definida en el nivel de etapa y raíz, por ejemplo. Las variables definidas a nivel de etapa anularán las variables definidas en el nivel “raíz”, pero serán anuladas por las variables definidas a nivel de trabajo.

A continuación, puedes ver un ejemplo de definición de construcción YAML en el que se utiliza cada ámbito.

variables:
  global_variable: value  # esta es una variable global disponible para todas las etapas y trabajos

stages:
- stage: Build
  variables:
    stage_variable1: value3 # disponible en la etapa de construcción y todos los trabajos
  jobs:
  - job: BuildJob
    variables:
      job_variable1: value1    # esto solo está disponible en BuildJob
    steps:
    - bash: echo $(stage_variable1) ## funciona
    - bash: echo $(global_variable) ## funciona
    - bash: echo $(job_variable1) ## funciona

Precedencia de Variables

A veces verás una situación en la que se establece una variable con el mismo nombre en varios ámbitos. Cuando esto sucede, el valor de esa variable se sobrescribirá según una secuencia específica dando precedencia a la “acción” más cercana.

A continuación, verás el orden en el que las variables se sobrescribirán comenzando con una variable establecida dentro de un trabajo. Esto tendrá la mayor precedencia.

1. Variable establecida a nivel de trabajo (establecida en el archivo YAML)
2. Variable establecida a nivel de etapa (establecida en el archivo YAML)
3. Variable establecida a nivel de canalización (global) (establecida en el archivo YAML)
4. Variable establecida en el momento de la cola
5. Variable de canalización establecida en la interfaz de configuración de la canalización

Por ejemplo, echa un vistazo a la definición YAML a continuación. En este ejemplo, la misma variable se establece en muchas áreas diferentes pero, al final, termina con el valor definido en el trabajo. Con cada acción, el valor de la variable se sobrescribe a medida que el oleoducto llega al trabajo.

variables:
  foo: 'global variable'

stages:
- stage: build
  variables:
   - name: foo
     value: 'defined at stage level'

  jobs:
  - job: compile
    variables:
    - name: foo
      value: 'defined at job level'
    steps:
      - bash: echo $(foo) # Esto se 'definirá a nivel de trabajo'

Tipos de Variables

Has aprendido sobre qué son las variables, cómo son, los contextos en los que se pueden ejecutar y más hasta ahora en este artículo. Pero lo que no hemos cubierto es que no todas las variables son iguales. Algunas variables ya existen cuando comienza un oleoducto y no se pueden cambiar, mientras que otras puedes crear, cambiar y eliminar a voluntad.

Existen cuatro tipos generales de variables: variables predefinidas o del sistema, variables definidas por el usuario, variables de salida y variables secretas. Profundicemos en cada una de ellas y comprendamos cada tipo de variable.

Variables Predefinidas

Dentro de todas las construcciones y despliegues, encontrarás muchas variables diferentes que existen por defecto. Estas variables se llaman predefinidas o variables del sistema. Las variables predefinidas son solo de lectura y, al igual que otros tipos de variables, representan cadenas y números simples.

Un oleoducto de Azure consta de muchos componentes, desde el agente de software que ejecuta la construcción, hasta los trabajos que se inician cuando se ejecuta un despliegue y otra información variada. Para representar todas estas áreas, las variables predefinidas o variables del sistema se dividen informalmente en cinco categorías distintas:

• Agente
• Construcción
• Oleoducto
• Trabajo de implementación
• Sistema

Hay docenas de variables distribuidas en cada una de estas cinco categorías. No vas a aprender sobre todas ellas en este artículo. Si deseas obtener una lista de todas las variables predefinidas, echa un vistazo a la documentación de Microsoft.

Variables Definidas por el Usuario

Cuando creas una variable en una definición YAML o a través de un script, estás creando una variable definida por el usuario. Las variables definidas por el usuario son simplemente todas las variables que tú, como usuario, defines y usas en una canalización. Puedes usar casi cualquier nombre que desees para estas variables con algunas excepciones.

No puedes definir variables que comiencen con la palabra endpoint, input, secret o securefile. Estas etiquetas están fuera de límites porque están reservadas para el uso del sistema y no distinguen entre mayúsculas y minúsculas.

Además, las variables que defines deben consistir solo en letras, números, puntos o guiones bajos. Si intentas definir una variable que no siga este formato, la definición de construcción YAML no funcionará.

Variables de Salida

A build definition contains one or more tasks. Sometimes a task sends a variable out to be made available to downstream steps and jobs within the same stage. These types of variables are called output variables.

Las variables de salida se utilizan para compartir información entre componentes de la canalización. Por ejemplo, si una tarea consulta un valor de una base de datos y las tareas posteriores necesitan el resultado devuelto, se puede utilizar una variable de salida. Entonces, no tienes que consultar la base de datos cada vez. En cambio, simplemente puedes hacer referencia a la variable.

Nota: Las variables de salida están limitadas a una etapa específica. No espere que una variable de salida esté disponible tanto en la etapa de “compilación” como en la etapa de “pruebas”, por ejemplo.

Variables Secretas

El último tipo de variable es la variable secreta. Técnicamente, no es su propio tipo independiente porque puede ser una variable definida por el sistema o el usuario. Pero las variables secretas deben estar en su propia categoría porque se tratan de manera diferente a otras variables.

A secret variable is a standard variable that’s encrypted. Secret variables typically contain sensitive information like API keys, passwords, etc. These variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for all tasks and scripts to use.

– NO defina variables secretas dentro de sus archivos YAML
– NO devuelva secretos como variables de salida o información de registro

Las variables secretas deben definirse en el editor de la canalización. Esto limita las variables secretas a nivel global, haciéndolas disponibles para las tareas en la canalización.

Los valores secretos están enmascarados en los registros, pero no completamente. Por eso es importante no incluirlos en un archivo YAML. También debe saber que no debe incluir ningún dato “estructurado” como un secreto. Si, por ejemplo, se establece { "foo": "bar" } como un secreto, bar no se enmascarará en los registros.

Los secretos no se descifran automáticamente ni se asignan a variables de entorno. Si define una variable secreta, no espere que esté disponible a través de $env:FOO en un script de PowerShell, por ejemplo.

Grupos de Variables

Finalmente, llegamos a los grupos de variables. Los grupos de variables, como podría esperar, son “grupos” de variables que se pueden referenciar como uno solo. El propósito principal de un grupo de variables es almacenar valores que desea poner a disposición en varias canalizaciones.

A diferencia de las variables, los grupos de variables no se definen en el archivo YAML. En su lugar, se definen en la página de Librería bajo Pipelines en la interfaz de usuario.

Use un grupo de variables para almacenar valores que desee controlar y hacer disponibles en múltiples pipelines. También puede utilizar grupos de variables para almacenar secretos y otros valores que puedan necesitarse en un pipeline YAML. Los grupos de variables se definen y administran en la página de Librería bajo Pipelines como se muestra a continuación.

Una vez definido en la librería de pipelines, puede acceder a ese grupo de variables en el archivo YAML utilizando la siguiente sintaxis.

variables:
- group: group1

Los grupos de variables no están, por defecto, disponibles para todos los pipelines. Esta configuración está disponible al crear el grupo. Los pipelines deben estar autorizados para usar un grupo de variables.

Una vez que un grupo de variables se haya accedido en el archivo YAML, entonces puede acceder a las variables dentro del grupo exactamente como lo haría con cualquier otra variable. El nombre del grupo de variables no se utiliza al hacer referencia a las variables en el grupo.

Por ejemplo, si ha definido un grupo de variables llamado group1 con una variable llamada foo dentro, haría referencia a la variable foo como cualquier otra, por ejemplo. $(foo).

Las variables secretas definidas en un grupo de variables no pueden accederse directamente mediante scripts. En su lugar, deben pasarse como argumentos a la tarea.

Si se realiza un cambio en una variable dentro de un grupo de variables, ese cambio estará automáticamente disponible para todos los pipelines autorizados a usar ese grupo.

Resumen

Deberías tener ahora un conocimiento sólido de las variables de Azure Pipelines. ¡Aprendiste prácticamente todos los conceptos relacionados con las variables en este artículo! Ahora, sal y aplica este conocimiento en tus Azure DevOps Pipelines ¡y automatiza todas las cosas!