Lançar uma versão

Este documento descreve como lançar uma versão usando o ambiente de execução do SaaS.

O ambiente de execução do SaaS permite atualizações em várias unidades provisionadas usando lançamentos. Os lançamentos têm como destino unidades com base no UnitKind e podem, opcionalmente, aplicar filtros (unit_filter) para segmentar um subconjunto específico de unidades usando a Google Cloud CLI . Isso permite atualizações gerenciadas em toda a base implantada. Um reversão pode ser realizada fazendo upgrade das unidades para uma versão anterior.

Para operações em uma única unidade específica, use os controles disponíveis na página Detalhes da unidade.

Antes de começar

Antes de atualizar sua oferta de SaaS, faça o seguinte:

Criar uma versão

Antes de atualizar sua oferta de SaaS, crie uma versão. Uma versão representa uma versão específica do aplicativo de SaaS definida por um pacote de blueprint e as configurações associadas. Essencialmente, uma versão contém a atualização das unidades.

Console

  1. Acesse o ambiente de execução do SaaS.

    Acessar o ambiente de execução do SaaS

  2. Clique em Versões.

  3. Na página Versões, clique em Criar.

  4. Na página Criar versão:

    1. Na caixa Nome da versão, insira um nome exclusivo para a versão.
    2. Na caixa Tipo de unidade, selecione o tipo de unidade a que essa versão está associada.
    3. Na seção Somente upgrade da versão (opcional), selecione as versões das quais as unidades podem ser atualizadas para esta versão. Isso permite controlar os caminhos de upgrade.
    4. Nas etapas Criar blueprint e Armazenar blueprint, selecione ou crie o blueprint. Consulte a documentação de blueprints para informações detalhadas sobre as opções de criação de blueprints.

    5. Na seção Variáveis (opcional), você pode definir variáveis de entrada para esta versão. Consulte a documentação de variáveis para mais informações sobre como definir variáveis.

  5. Clique em Criar.

  6. Você criou uma versão. É possível conferir os detalhes da versão na página Detalhes da versão. Você poderá referenciar essa versão ao criar um lançamento.

gcloud

Para criar uma versão usando o Google Cloud console:

gcloud beta saas-runtime releases create RELEASE_NAME --blueprint-package=BLUEPRINT_PACKAGE_URI --unit-kind=UNIT_KIND [--location=LOCATION] [--labels=[KEY=VALUE,...]] [--upgradeable-from-releases=[RELEASE_NAME,...]] [--input-variable-defaults=[variable=VARIABLE,value=VALUE,type=TYPE,...]]

Substitua:

  • RELEASE_NAME: o ID da versão que você quer criar. Isso fará parte do nome completo do recurso da versão.
  • BLUEPRINT_PACKAGE_URI: o URI do pacote de blueprint a ser usado para esta versão. Os blueprints são imagens OCI hospedadas no Artifact Registry ou em outro registro OCI.
    • O pacote de blueprint contém os artefatos necessários para provisionar uma unidade e inclui metadados sobre o mecanismo usado (Terraform), bem como a versão.
    • Se você omitir o nome do host no URI, ele será definido como o caminho regional do Artifact Registry (us-east1-docker.pkg.dev, por exemplo).
    • Consulte a documentação de blueprints para mais informações sobre como criar blueprints.
  • UNIT_KIND: o ID ou o identificador totalmente qualificado do tipo de unidade a que essa versão corresponde. UNIT_KIND é imutável depois que você cria uma versão.
  • LOCATION: o local em que você quer criar a versão. Essa flag fornece um valor de fallback para o local da versão se o caminho completo do URI não for fornecido. O padrão é o local configurado no ambiente da Google Cloud CLI.
  • LABELS: (opcional) rótulos a serem aplicados à versão para categorização. Rótulos são pares de chave-valor.
    • As chaves precisam começar com um caractere minúsculo e conter apenas hifens, sublinhados, caracteres minúsculos e números.
    • Os valores precisam conter apenas hifens, sublinhados, caracteres minúsculos e números.
    • Por exemplo: --labels=environment=staging,team=saas-runtime
  • UPGRADEABLE_FROM_RELEASES: (opcional) uma lista separada por vírgulas de nomes de versões que especifica quais versões atuais podem ser atualizadas com o novo lançamento que você criar.
    • Se você deixar essa flag vazia, não haverá restrições sobre quais versões podem ser atualizadas para essa versão.
    • Quando fornecidas, as solicitações de atualização de unidade para essa versão vão aplicar essa restrição.
  • INPUT_VARIABLE_DEFAULTS: (opcional) valores padrão para variáveis de entrada exigidas pelo blueprint.
    • É possível especificar os padrões de variáveis inline ou referenciando um arquivo YAML ou JSON.
    • As variáveis definidas aqui podem ser substituídas durante a criação do lançamento.

Para mais informações sobre como definir variáveis, consulte a documentação de variáveis. Para mais informações sobre versões, consulte a referência da Google Cloud CLI Release.

Criar um tipo de lançamento

Antes de criar um lançamento, é necessário criar um tipo de lançamento que sirva como modelo de como a versão é implantada nas unidades.

Console

  1. Acesse o ambiente de execução do SaaS.

    Acessar o ambiente de execução do SaaS

  2. Clique em Tipos de lançamento.

  3. Na página Tipos de lançamento, clique em Criar.

  4. Na página Criar um tipo de lançamento:

    1. Na caixa Nome do tipo de lançamento, insira um nome para o tipo de lançamento.
    2. Na caixa Tipo de unidade, selecione o tipo de unidade que detalha o tipo de unidade em que você quer que a versão seja lançada.

    3. No menu suspenso Estratégia de lançamento, selecione a estratégia que você quer usar para implantar a versão nas unidades:

      • Um local por vez (simples): atualiza um local por vez (sem tempos de absorção). Atualiza até 20% das unidades simultaneamente.
      • Tudo de uma vez (simples): todos os locais começam a ser lançados simultaneamente (ideal para ambientes de desenvolvimento e cenários de emergência
      • Progressiva (gradual): lança atualizações gradualmente em lotes de porcentagem exponencialmente em vários locais (com tempos de absorção).
      • Progressiva (local único): atualiza unidades em lotes de porcentagem com tempos de absorção estendidos para detectar problemas em um único local.

      Para mais informações sobre estratégias de lançamento, consulte Estratégias de lançamento.

  5. Clique em Criar.

  6. Você criou um tipo de lançamento. Na página Detalhes do tipo de lançamento , é possível conferir e editar os parâmetros do tipo de lançamento.

gcloud

Para criar um tipo de lançamento usando o Google Cloud console:

  gcloud beta saas-runtime rollout-kinds create ROLLOUT_KIND_NAME --unit-kind=UNIT_KIND --location=LOCATION --rollout_strategy=ROLLOUT_STRATEGY --error_budget=ERROR_BUDGET --unit_filter=UNIT_FILTER --update_unit_kind_default=UPDATE_UNIT_KIND_DEFAULT

Substitua:

  • ROLLOUT_KIND_NAME: o nome do tipo de lançamento.
  • UNIT_KIND: define a quais unidades você quer aplicar versões. As versões são aplicadas a todas as unidades do tipo de unidade selecionado.
  • LOCATION: o local em que você quer criar o tipo de lançamento.

  • ROLLOUT_STRATEGY: define a estratégia de lançamento para o tipo de lançamento. Os valores possíveis incluem:

    • Google.Cloud.Simple.OneLocationAtATime: atualiza um local por vez (sem tempos de absorção). Atualiza até 20% das unidades simultaneamente.
    • Google.Cloud.Simple.AllAtOnce: todos os locais começam a ser lançados simultaneamente (ideal para ambientes de desenvolvimento e cenários de emergência).
    • Google.Cloud.Progressive.Gradual.v1: lança atualizações gradualmente em lotes de porcentagem exponencialmente em vários locais (com tempos de absorção).
    • Google.Cloud.Progressive.SingleLocation.v1: atualiza unidades em lotes de porcentagem com tempos de absorção estendidos para detectar problemas em um único local.

    Para mais informações sobre estratégias de lançamento, consulte Estratégias de lançamento.

  • ERROR_BUDGET: a configuração da margem de erro. Se o número de unidades com falha exceder o máximo de error_budget (definido por allowed_count, allowed_ratio * total_units), o lançamento será pausado. Se error_budget não estiver definido, o ambiente de execução do SaaS vai tentar atualizar todas as unidades, independentemente do número de falhas encontradas.

  • UNIT_FILTER: CEL string de filtro formatada usada em unidades. O filtro será aplicado para determinar a população de unidades qualificada. Esse filtro só pode reduzir o escopo do lançamento. Ele não pode expandir o escopo do lançamento.

  • UPDATE_UNIT_KIND_DEFAULT: a configuração para atualizar o tipo de unidade. Por padrão, o tipo de unidade será atualizado no início do lançamento. Os valores possíveis incluem:

    • UPDATE_UNIT_KIND_STRATEGY_UNSPECIFIED: a estratégia de atualização do tipo de unidade não foi especificada.
    • UPDATE_UNIT_KIND_STRATEGY_ON_START: atualize a estratégia de tipo de unidade no início do lançamento.
    • UPDATE_UNIT_KIND_STRATEGY_NEVER: nunca atualize a estratégia de tipo de unidade.

Para mais informações, consulte a referência da Google Cloud CLI RolloutKind.

Recurso de margem de erro

O ambiente de execução do SaaS inclui um recurso de margem de erro (ErrorBudget em RolloutKind) como uma proteção. Isso pode pausar automaticamente um lançamento se o número ou a porcentagem de falhas de atualização da unidade (durante a aplicação da infraestrutura, por exemplo) exceder um limite configurado, ajudando a limitar o impacto de possíveis problemas durante uma atualização.

Criar um lançamento

Depois de criar um tipo de lançamento, é possível criar um lançamento que especifique a versão com que você quer atualizar as unidades.

Depois que o lançamento é criado, o ambiente de execução do SaaS atualiza as unidades de acordo com a estratégia definida no tipo de unidade.

Console

  1. Acesse o ambiente de execução do SaaS.

    Acessar o ambiente de execução do SaaS

  2. Clique em Lançamentos.

  3. Na página Lista de lançamentos, clique em Criar.

  4. Na página Criar um lançamento:

    1. Na caixa Tipo de lançamento, selecione o tipo de lançamento que detalha como lançar a versão para as unidades especificadas.
    2. Na caixa Versão, especifique a versão para atualizar as unidades.
    3. Na caixa Nome do lançamento, insira um nome para o lançamento.

  5. Clique em Criar.

  6. O lançamento foi criado.

    Na página Detalhes do lançamento global, é possível monitorar os detalhes do lançamento, incluindo o estado, o progresso (por contagem de unidades) e as falhas do lançamento.

gcloud

Para criar um lançamento usando o Google Cloud console:

  gcloud beta saas-runtime rollouts create ROLLOUT_NAME --rollout-kind=ROLLOUT_KIND_NAME --release=RELEASE_NAME --location=LOCATION

Substitua:

  • ROLLOUT_NAME: o nome do lançamento.
  • ROLLOUT_KIND_NAME: define qual tipo de lançamento você quer usar para aplicar versões às unidades. As versões são aplicadas a todas as unidades do tipo de unidade definido no tipo de lançamento.
  • RELEASE_NAME: define o binário de versão que você quer implantar nas unidades.
  • LOCATION: o local em que você quer criar o lançamento.

Para mais informações, consulte Rollout referência da Google Cloud CLI.

A seguir