Variáveis e mapeamento de variáveis com o ambiente de execução de SaaS

Este documento explica como variáveis, mapeamento de variáveis e dependências funcionam no ambiente de execução de SaaS.

O ambiente de execução de SaaS permite implantar e gerenciar aplicativos SaaS complexos organizando-os em unidades modulares. Essas unidades, definidas por configurações do Terraform em blueprints, podem ser interconectadas por dependências, permitindo uma orquestração sofisticada e um provisionamento automatizado. Um aspecto importante do gerenciamento dessas unidades e das interações delas é o uso de variáveis e mapeamento de variáveis.

É possível criar implantações complexas, modulares e escalonáveis com provisionamento automatizado, comunicação entre unidades e opções de configuração flexíveis. Considere cuidadosamente a hierarquia de variáveis, as relações de dependência e os mapeamentos de variáveis para otimizar a arquitetura de SaaS e os fluxos de trabalho de gerenciamento no ambiente de execução do SaaS.

Unidades e variáveis

No centro do ambiente de execução de SaaS estão as unidades. As unidades usam variáveis para personalizar a implantação e o comportamento. Essas variáveis são essencialmente variáveis do Terraform que podem ser definidas no arquivo variables.tf do blueprint. Elas permitem parametrizar as configurações do Terraform, tornando-as reutilizáveis e adaptáveis em diferentes ambientes e implantações.

Variáveis obrigatórias para provisionamento de unidades

Embora seja possível definir variáveis personalizadas para suas unidades, o ambiente de execução do SaaS também depende de um conjunto de variáveis obrigatórias. Essas variáveis são reconhecidas e processadas automaticamente pelo ambiente de execução do SaaS, mesmo que não estejam definidas explicitamente na configuração do Terraform.

As variáveis obrigatórias são:

  • project_id e project_number (ou tenant_project_id e tenant_project_id): essa variável especifica o ID do projeto Google Cloud em que os recursos da unidade serão implantados. É possível usar project_id e project_number ou tenant_id e tenant_project_id. Esse campo é necessário para a criação e o gerenciamento de recursos no projeto Google Cloud correto.

    Encontre o ID do projeto no console Google Cloud na página "Painel". Procure o campo ID do projeto no card Informações do projeto na seção Visão geral do Cloud.

  • project_number ou tenant_project_number: semelhante a project_id, essa variável representa o número do projeto Google Cloud . É possível usar project_number ou tenant_project_number de forma intercambiável.

    O número do projeto está ao lado do ID do projeto no card Informações do projeto, na seção Visão geral do Cloud da página do painel do Google Cloud console.

  • actuation_sa: essa variável representa o endereço de e-mail da conta de serviço de ação. Essa conta de serviço é gerenciada pelo usuário e usada pelo ambiente de execução do SaaS (via Gerente de infraestrutura) para executar suas configurações do Terraform ao provisionar, atualizar ou desprovisionar unidades.

    Recomendamos que você use uma conta de serviço de ativação dedicada por locatário (ou unidade) para implementar o princípio de privilégio mínimo. Isso limita o impacto potencial de violações de segurança e oferece um isolamento melhor entre as implantações.

    Para mais informações sobre como configurar e conceder permissões a contas de serviço de ativação, consulte Visão geral do produto.

Hierarquia de variáveis de unidade

As variáveis de unidade podem ser definidas e originadas de vários locais. Ao usar o ambiente de execução do SaaS, é importante entender a hierarquia dos valores de variáveis usados durante as operações de unidade.

A ordem é a seguinte (da prioridade mais baixa à mais alta):

O ambiente de execução de SaaS resolve os valores das variáveis nesta ordem:

  1. Variáveis de entrada atuais na unidade: se uma variável já estiver definida no recurso da unidade (de uma operação ou configuração anterior, por exemplo), esse valor terá a menor precedência. Se um valor de variável for definido diretamente na unidade, ele será substituído se um valor for encontrado em fontes mais altas na hierarquia.

  2. Padrões de lançamento: os valores padrão de lançamento são aplicados se uma variável ainda não estiver definida na unidade, mas substituem as variáveis de unidade atuais.

  3. Operações de unidade: ao realizar uma operação de unidade, como provision ou upgrade, é possível fornecer explicitamente variáveis de entrada como parte da solicitação de operação. As variáveis fornecidas em uma operação de unidade substituem os padrões de lançamento e as variáveis de unidade atuais.

  4. Mapeamentos de variáveis de entrada de dependências: quando uma unidade tem dependências de outras unidades, os mapeamentos de variáveis definidos no tipo de unidade podem originar valores de variáveis das variáveis de saída das unidades de dependência. Essa é a fonte de precedência mais alta. As variáveis obtidas por mapeamentos de dependência vão substituir os valores das operações de unidade, os padrões de lançamento e as variáveis de unidade atuais.

Essa abordagem hierárquica oferece flexibilidade e controle sobre o gerenciamento de variáveis. É possível estabelecer configurações persistentes diretamente na unidade (prioridade mais baixa), definir padrões de base usando versões, personalizar para operações específicas e buscar dinamicamente os valores mais importantes e substitutos das dependências da unidade (prioridade mais alta).

Dependências da unidade

O ambiente de execução de SaaS permite definir dependências entre unidades. Isso é importante para criar aplicativos SaaS complexos em que diferentes componentes dependem uns dos outros. As dependências garantem que as unidades relacionadas sejam provisionadas e gerenciadas de maneira coordenada.

Você define dependências em um tipo de unidade. Quando você cria uma unidade de um tipo específico, o ambiente de execução de SaaS gerencia automaticamente as dependências dela.

Definição de dependência no tipo de unidade

Na definição de UnitKind, você especifica uma lista de dependências, cada uma referenciando outro UnitKind e atribuindo a ele um alias. Esse alias é usado para referenciar a dependência em mapeamentos de variáveis:

  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];
  }

Provisionamento automático de dependências

Quando você solicita o provisionamento de uma unidade com dependências definidas no UnitKind, o ambiente de execução do SaaS verifica automaticamente a existência dessas unidades de dependência.

Se uma unidade de dependência não for encontrada, o ambiente de execução do SaaS vai provisioná-la automaticamente antes de provisionar a unidade dependente.

O ambiente de execução de SaaS garante que as unidades de dependência sejam provisionadas antes das unidades dependentes, mantendo a ordem correta das operações.

Mapeamento de variáveis

O mapeamento de variáveis é o mecanismo para transmitir dados (valores de variáveis) entre unidades dependentes e as dependências delas. Isso é essencial para configurar unidades dependentes com base nas saídas das dependências.

O mapeamento de variáveis é definido no tipo de unidade dependente e usa FromMapping e ToMapping:

  • FromMapping: FromMapping é usado para extrair variáveis de saída de uma unidade de dependência e mapeá-las para variáveis de entrada da unidade dependente. É assim que uma unidade dependente pode receber informações das dependências dela, como endpoints de conexão ou 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];
}

    No exemplo de codelab fornecido, o App UnitKind tem um FromMapping para recuperar a variável de saída cluster_endpoint da dependência Cluster UnitKind. Isso permite que o aplicativo se conecte ao cluster do Kubernetes recém-provisionado.

  • ToMapping: ToMapping é usado para transmitir variáveis de entrada da unidade dependente para as variáveis de entrada de uma unidade de dependência. Isso permite configurar unidades de dependência com base em parâmetros fornecidos para a unidade dependente.

    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];
}

    No codelab, o App UnitKind usa ToMapping para transmitir as variáveis de entrada tenant_project_id e tenant_project_number à dependência Cluster UnitKind. Isso garante que o cluster do Kubernetes seja criado no projeto correto.

  • ignore_for_lookup em ToMapping: o campo ignore_for_lookup em ToMapping controla o comportamento de pesquisa de dependências. É um valor booleano:

    • false (ou não especificado): quando definido como false, o ambiente de execução do SaaS usa as variáveis de entrada especificadas no ToMapping como chaves de pesquisa para encontrar uma unidade de dependência existente. Se uma unidade com variáveis de entrada correspondentes for encontrada, ela será reutilizada como a dependência. Se nenhuma unidade correspondente for encontrada, uma nova unidade de dependência será provisionada. Isso é útil para reutilizar recursos compartilhados, como clusters.
    • true: quando definido como true, a variável de entrada em ToMapping não será usada para pesquisa de dependência. Isso significa que uma nova unidade de dependência será sempre provisionada, mesmo que já existam unidades com as mesmas variáveis de entrada. Isso é útil quando você precisa de dependências dedicadas e não compartilhadas para cada unidade dependente.

Exemplo: cluster compartilhado do Kubernetes

Se você quiser reutilizar um cluster do Kubernetes para várias unidades de aplicativo no mesmo projeto, use ToMapping com ignore_for_lookup definido como false e mapeie variáveis como tenant_project_id e region para o tipo de unidade de cluster. As unidades no mesmo projeto e região reutilizariam o mesmo cluster.

Exemplo: cluster dedicado do Kubernetes por aplicativo

Se você precisar de um cluster do Kubernetes dedicado para cada unidade de aplicativo, use ToMapping com ignore_for_lookup definido como true ou evite completamente as variáveis de pesquisa ToMapping. Cada unidade de aplicativo acionaria o provisionamento de um novo cluster isolado do Kubernetes.

Gerenciar secrets

As variáveis do ambiente de execução do SaaS não são destinadas ao armazenamento de informações sensíveis, como senhas, chaves de API ou certificados. Armazenar secrets diretamente em variáveis apresenta riscos de segurança. Os valores das variáveis podem ser registrados e potencialmente expostos por saídas do sistema, aumentando a chance de acesso não autorizado.

Para um gerenciamento seguro de secrets nos seus aplicativos do ambiente de execução de SaaS, recomendamos usar o Secret Manager.

A seguir