Variables y asignación de variables con el entorno de ejecución de SaaS

En este documento, se explica cómo funcionan las variables, la asignación de variables y las dependencias en el entorno de ejecución de SaaS.

El entorno de ejecución de SaaS te permite implementar y administrar aplicaciones de SaaS complejas organizándolas en unidades modulares. Estas unidades, definidas por las configuraciones de Terraform dentro de los planos, se pueden interconectar a través de dependencias, lo que permite una organización sofisticada y un aprovisionamiento automatizado. Un aspecto clave de la administración de estas unidades y sus interacciones se realiza a través de variables y la asignación de variables.

Puedes crear implementaciones complejas, modulares y escalables con aprovisionamiento automatizado, comunicación entre unidades y opciones de configuración flexibles. Considera cuidadosamente la jerarquía de variables, las relaciones de dependencia y las asignaciones de variables para optimizar tu arquitectura de SaaS y los flujos de trabajo de administración dentro del entorno de ejecución de SaaS.

Unidades y variables

Las unidades son el núcleo de SaaS Runtime. Las unidades utilizan variables para personalizar su implementación y comportamiento. Estas variables son, básicamente, variables de Terraform que puedes definir en el archivo variables.tf de tu blueprint. Te permiten parametrizar tus configuraciones de Terraform, lo que las hace reutilizables y adaptables en diferentes entornos y en diferentes implementaciones.

Variables obligatorias para el aprovisionamiento de unidades

Si bien puedes definir variables personalizadas para tus unidades, el entorno de ejecución de SaaS también se basa en un conjunto de variables obligatorias. SaaS Runtime reconoce y controla automáticamente estas variables, incluso si no están definidas de forma explícita en tu configuración de Terraform.

Las variables obligatorias son las siguientes:

  • project_id y project_number (o tenant_project_id y tenant_project_id): Esta variable especifica el ID del proyecto de Google Cloud donde se implementarán los recursos de tu unidad. Puedes usar project_id y project_number, o bien tenant_id y tenant_project_id. Este campo es necesario para la creación y administración de recursos dentro del proyecto Google Cloud correcto.

    Puedes encontrar el ID de tu proyecto en la consola de Google Cloud , en la página del panel. Busca el campo ID del proyecto en la tarjeta Información del proyecto dentro de la sección Descripción general de Cloud.

  • project_number o tenant_project_number: Similar a project_id, esta variable representa el número de proyecto Google Cloud . Puedes usar project_number o tenant_project_number indistintamente.

    Puedes encontrar el número de tu proyecto junto con el ID del proyecto en la tarjeta Información del proyecto dentro de la sección Descripción general de Cloud de la Google Cloud consola página del panel.

  • actuation_sa: Esta variable representa la dirección de correo electrónico de la cuenta de servicio de activación. Esta cuenta de servicio es una cuenta de servicio administrada por el usuario que el entorno de ejecución de SaaS usa (a través de Infrastructure Manager) para ejecutar tus configuraciones de Terraform cuando se aprovisionan, actualizan o desaprovisionan unidades.

    Te recomendamos que uses una cuenta de servicio de activación dedicada por arrendatario (o unidad) para implementar el principio de privilegio mínimo. Esto limita el posible impacto de las violaciones de seguridad y proporciona un mejor aislamiento entre tus implementaciones.

    Para obtener más información sobre cómo configurar y otorgar permisos a las cuentas de servicio de activación, consulta la Descripción general del producto.

Jerarquía de variables de unidades

Las variables de unidades se pueden definir y obtener de varias ubicaciones. Cuando usas el entorno de ejecución de SaaS, es importante comprender la jerarquía de los valores de las variables que se usan durante las operaciones de unidades.

El orden es el siguiente (de menor a mayor prioridad):

SaaS Runtime resuelve los valores de las variables en este orden:

  1. Variables de entrada existentes en la unidad: Si ya se definió una variable en el recurso de la unidad (por ejemplo, a partir de una operación o configuración anterior), este valor tiene la precedencia más baja. Si se establece un valor de variable directamente en la unidad, se anulará si se encuentra un valor de fuentes más altas en la jerarquía.

  2. Valores predeterminados de la versión: Los valores predeterminados de la versión se aplican si una variable aún no está establecida en la unidad, pero anularán las variables existentes de la unidad.

  3. Operaciones de unidades: Cuando realizas una operación de unidades, como provision o upgrade, puedes proporcionar variables de entrada de forma explícita como parte de la solicitud de operación. Las variables proporcionadas en una operación de unidad anularán los valores predeterminados de la versión y las variables de unidad existentes.

  4. Asignaciones de variables de entrada de dependencias: Cuando una unidad tiene dependencias de otras unidades, las asignaciones de variables definidas en el tipo de unidad pueden obtener valores de variables de las variables de salida de las unidades de dependencia. Esta es la fuente de precedencia más alta. Las variables obtenidas a través de las asignaciones de dependencia anularán los valores de las operaciones de unidades, los valores predeterminados de la versión y las variables de unidades existentes.

Este enfoque jerárquico proporciona flexibilidad y control sobre la administración de tus variables. Puedes establecer configuraciones persistentes directamente en la unidad (prioridad más baja), definir valores predeterminados de referencia con versiones, personalizar para operaciones específicas y obtener de forma dinámica los valores más importantes y de anulación de las dependencias de la unidad (prioridad más alta).

Dependencias de unidades

El entorno de ejecución de SaaS te permite definir dependencias entre unidades. Esto es importante para compilar aplicaciones SaaS complejas en las que los diferentes componentes dependen entre sí. Las dependencias garantizan que las unidades relacionadas se aprovisionen y administren de manera coordinada.

Defines las dependencias dentro de un tipo de unidad. Cuando creas una unidad de un tipo de unidad en particular, SaaS Runtime administra automáticamente sus dependencias.

Definición de dependencia en el tipo de unidad

En la definición de UnitKind, especificas una lista de dependencias, cada una de las cuales hace referencia a otro UnitKind y le asigna un alias. Este alias se usa para hacer referencia a la dependencia en las asignaciones de variables:

  message UnitKind {
    // ... other fields ...

    // List of other unit kinds that this release will depend on.
    repeated Dependency dependencies = 4
        [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }

  message Dependency {
    // The unit kind of the dependency.
    string unit_kind = 1 [
      (.google.api.field_behavior) = REQUIRED,
      (.google.api.field_behavior) = IMMUTABLE,
      (.google.api.resource_reference) = {
        type: "saasservicemgmt.googleapis.com/UnitKind"
      }
    ];

    // An alias for the dependency. Used for input variable mapping.
    string alias = 2 [(.google.api.field_behavior) = REQUIRED];
  }

Aprovisionamiento automático de dependencias

Cuando solicitas aprovisionar una unidad que tiene dependencias definidas en su UnitKind, el entorno de ejecución de SaaS verifica automáticamente la existencia de esas unidades de dependencia.

Si no se encuentra una unidad de dependencia, SaaS Runtime la aprovisionará automáticamente antes de aprovisionar la unidad dependiente.

El entorno de ejecución de SaaS garantiza que las unidades de dependencia se aprovisionen antes que sus unidades dependientes, lo que mantiene el orden correcto de las operaciones.

Asignación de variables

El mapeo de variables es el mecanismo para pasar datos (valores de variables) entre las unidades dependientes y sus dependencias. Esto es fundamental para configurar unidades dependientes según los resultados de sus dependencias.

La asignación de variables se define dentro del tipo de unidad dependiente y usa FromMapping y ToMapping:

  • FromMapping: FromMapping se usa para recuperar variables de salida de una unidad de dependencia y asignarlas a variables de entrada de la unidad dependiente. Así es como una unidad dependiente puede obtener información de sus dependencias, como extremos de conexión o IDs de recursos.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // Output variables which will get their values from dependencies
    FromMapping from = 2 [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }
}

message FromMapping {
  // Alias of the dependency that the outputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the outputVariable on the dependency
  string output_variable = 2 [(.google.api.field_behavior) = REQUIRED];
}

    En el ejemplo del codelab proporcionado, el App UnitKind tiene un FromMapping para recuperar la variable de salida cluster_endpoint de la dependencia Cluster UnitKind. Esto permite que la aplicación se conecte al clúster de Kubernetes aprovisionado recientemente.

  • ToMapping: ToMapping se usa para pasar variables de entrada de la unidad dependiente a las variables de entrada de una unidad de dependencia. Esto te permite configurar unidades de dependencia según los parámetros proporcionados para la unidad dependiente.

    message VariableMapping {
  // ...
  oneof mapping_type {
    // ...
    // Input variables whose values will be passed on to dependencies.
    ToMapping to = 3 [(.google.api.field_behavior) = OPTIONAL];
  }
}

message ToMapping {
  // Alias of the dependency that the inputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the inputVariable on the dependency
  string input_variable = 2 [(.google.api.field_behavior) = REQUIRED];

  // Tells EasySaaS if this mapping should be used during lookup or not
  bool ignore_for_lookup = 3 [(.google.api.field_behavior) = OPTIONAL];
}

    En el codelab, App UnitKind usa ToMapping para pasar las variables de entrada tenant_project_id y tenant_project_number a la dependencia Cluster UnitKind. Esto garantiza que el clúster de Kubernetes se cree en el proyecto correcto.

  • ignore_for_lookup en ToMapping: El campo ignore_for_lookup en ToMapping controla el comportamiento de búsqueda de dependencias. Es un valor booleano:

    • false (o no especificado): Cuando se establece en false, el entorno de ejecución de SaaS usará las variables de entrada especificadas en ToMapping como claves de búsqueda para encontrar una unidad de dependencia existente. Si se encuentra una unidad con variables de entrada coincidentes, se reutilizará como dependencia. Si no se encuentra ninguna unidad coincidente, se aprovisionará una nueva unidad de dependencia. Esto es útil para reutilizar recursos compartidos, como clústeres.
    • true: Cuando se establece en true, la variable de entrada en ToMapping no se usará para la búsqueda de dependencias. Esto significa que siempre se aprovisionará una nueva unidad de dependencia, incluso si ya existen unidades con las mismas variables de entrada. Esto es útil cuando necesitas dependencias dedicadas y no compartidas para cada unidad dependiente.

Ejemplo: Clúster de Kubernetes compartido

Si deseas reutilizar un clúster de Kubernetes para varias unidades de aplicación dentro del mismo proyecto, usarías ToMapping con ignore_for_lookup establecido en false y asignarías variables como tenant_project_id y region al tipo de unidad de clúster. Las unidades del mismo proyecto y región reutilizarían el mismo clúster.

Ejemplo: Clúster de Kubernetes dedicado por aplicación

Si necesitas un clúster de Kubernetes dedicado para cada unidad de aplicación, usarías ToMapping con ignore_for_lookup establecido en true o evitarías por completo las variables de búsqueda de ToMapping. Cada unidad de aplicación activaría el aprovisionamiento de un clúster de Kubernetes nuevo y aislado.

Administra secretos

Las variables de SaaS Runtime no están diseñadas para almacenar información sensible, como contraseñas, claves de API o certificados. Almacenar secretos directamente en variables plantea riesgos de seguridad. Los valores de las variables se pueden registrar y, potencialmente, exponer a través de las salidas del sistema, lo que aumenta la probabilidad de acceso no autorizado.

Para administrar secretos de forma segura en tus aplicaciones del entorno de ejecución de SaaS, te recomendamos que uses Secret Manager.

¿Qué sigue?