Iniciar sessãoAgendar apresentação

Capítulo 2.28

Lançar a sua extensão

Como um plugin ou pacote passa de uma compilação bem-sucedida para as unidades que o executam, e como volta a sair. Versões, revisão de lançamento, canais e instalações, assinatura, aprovações de alterações, o registo de identidade de entrega, migrações, reversão e descontinuação de uma versão.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

18 minutos de leitura

O Cold chain 0.4.0 foi a primeira versão nossa que pediu mais do que a anterior. Acrescentou o envio de correio e um endereço externo, para alertas de contentores refrigerados. A compilação estava verde, os testes passaram nos três ramos sintéticos, e mesmo assim ficou dois dias no espaço de desenvolvimento enquanto duas pessoas liam o que pedia e uma terceira aprovava o endereço. É assim que se pretende que seja lançar uma versão no Nexus: o código é a parte fácil, e as evidências e as aprovações são a versão.

Este capítulo abrange tudo o que se passa entre uma compilação verde e uma versão em execução para todas as unidades, bem como as formas de recuar. O próprio percurso de promoção, do espaço de desenvolvimento para staging, para uma unidade piloto e para todas as unidades, é apresentado no capítulo 2.24, Construir uma vertical personalizada de ponta a ponta, e não repetirei aqui as suas barreiras. Uma regra enquadra tudo. A implementação faz-se apenas através dos canais de lançamento da instalação. Não existe porta lateral para uma correção urgente, e ninguém edita manualmente uma imagem em execução.

Versões

Num lançamento de pacote movem-se três números de versão, e compensa mantê-los separados na sua cabeça.

O quê Onde se encontra Exemplo Regra
O plugin version em nexus.manifest.json 0.4.0 Versão semântica; é permitido um sufixo de pré-lançamento como -rc.1
O pacote version em pack.json 0.4.0 Move-se com as lentes, as palavras e os clusters do pacote
O modelo de conhecimento A versão própria do modelo 1.3 a 1.4 Move-se apenas através de um pedido de alteração do grafo

Uma compilação de desenvolvimento tem um sufixo, 0.4.0-dev, até chegar a staging. Mantenha iguais as versões do plugin e do pacote quando são lançados em conjunto; isso evita, em cada revisão de versão, uma discussão sobre a que número pertencem as evidências.

Duas outras versões são fixadas em vez de escolhidas. A versão do modelo base do pacote (domain-pack@1.6.0 para o Cold chain) é fixada quando o pacote é criado e só se move como uma alteração revista. O SDK (kit de desenvolvimento de software) é instalado numa versão exata, nunca num intervalo, para que a mesma compilação dê o mesmo resultado no mês seguinte:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

As skills do Skills Engine também têm versões, e comportam-se de forma diferente. Cada versão publicada é fixa, e live, canary e shadow são etiquetas em versões. Reverter move uma etiqueta, e as execuções já em curso terminam na versão com que começaram.

Antes de pedir uma revisão: o manifesto

A página Manifesto e permissões compara o que esta versão declara com a versão anterior: os seus âmbitos, os seus armazenamentos, os seus endereços de saída e o seu perfil de sandbox. Leia-a antes de pedir a alguém que reveja, porque indica exatamente o que será pedido aos revisores que aceitem.

Manifesto e permissões
Manifesto e permissões
O que o Cold chain 0.4.0 declara face ao 0.3.2. Repare nas duas linhas marcadas como alargamento, o envio de correio e um endereço externo, e na placa que indica que a versão não avançará para além do espaço de desenvolvimento até que dois revisores as aceitem.

Uma versão que pede mais do que o seu manifesto declarava antes fica retida onde está, com MANIFEST_SCOPE_WIDENED, até que dois revisores aceitem o manifesto alargado. Um endereço externo precisa também da aprovação de quem gere os endereços externos no cliente; essa aprovação é dada por um prazo fixo, e a nossa foi por 12 meses. Tem duas formas de avançar: remover as linhas ou pedir revisão. A página oferece ambos os botões.

Cada linha dessa página é aplicada em tempo de execução, não apenas revista. Cada chamada de ferramenta é verificada face aos âmbitos declarados, um endereço externo é bloqueado a menos que esteja listado, e o perfil de sandbox não permite qualquer outra rede. Um plugin que tente chegar a algo que não declarou é recusado, e a única solução é uma nova versão que o declare.

Revisão de lançamento

A página Revisão de versão reúne numa só tabela as evidências de uma versão, para um revisor que não seja o autor.

Revisão de versão
Revisão de lançamento
A vista de um segundo revisor sobre o Cold chain 0.4.0, com a tabela de evidências, a diferença de âmbitos e os comentários. Repare na placa à direita: o autor não pode aprovar a sua própria versão.
Evidência O que mostrou para a 0.4.0
Testes 66 de 66, em três ramos sintéticos
Verificações de qualidade A documentação e o código estão de acordo
Política Cada lente apenas restringe; campos pessoais desativados por predefinição
Assinaturas Imagem e pacote assinados pelo pipeline
Diferença de âmbitos Acrescenta o envio de correio e um endereço externo, com a respetiva aprovação
Compatibilidade A versão da plataforma e a versão do pacote base com que foi testada
Alteração do modelo A execução de teste do pedido de alteração do grafo: 1284 ligações renomeadas, nada removido

Abaixo da tabela encontram-se os comentários sobre a alteração e a proveniência: que pipeline a compilou, a partir de que alteração, o digest da imagem e o modelo base. Os revisores aprovam com a sua passkey. Dois revisores que não sejam o autor aprovam, e o pipeline move então a versão para staging. O autor nunca conta como revisor, e uma tentativa é recusada com NEEDS_SECOND_PERSON. Um pedido de revisão caduca ao fim de 3 dias.

Responda às perguntas dos revisores nos comentários, não numa janela de chat. Durante a nossa revisão, o nosso responsável de conformidade perguntou porque é que o montante da reclamação estava classificado como comercial, e o segundo revisor pediu o plano de reversão para a alteração do modelo. Ambas as respostas fazem agora parte do registo da versão, que é onde o próximo revisor irá procurar.

Aprovações da política de alterações

A revisão de versão abrange a versão como um todo. O bloco changePolicy no manifesto vai mais longe: indica que classes de alteração aos componentes implementáveis do seu plugin precisam de aprovação, e de quantas pessoas.

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

As três classes são website (a aplicação web), bff (o backend for frontend) e migration (uma migração de base de dados). Cada classe indicada em classes tem de ter a sua própria contagem em approvals, de 1 a 10. Uma classe que omita fica sem governação, e o esquema obriga a escrevê-lo como uma escolha em vez de lá chegar por omissão. Pedimos duas aprovações para migrações porque uma migração é a única alteração difícil de desfazer.

As aprovações são contadas em pessoas distintas, e o proponente nunca é uma delas. Vale a pena conhecer as regras que o sustentam, porque cada uma tem uma recusa:

  • Uma aprovação da pessoa que propôs a alteração é recusada com TRUST_APPROVAL_SELF_APPROVAL.
  • Uma pessoa que não pode de todo fazer uma alteração dessa classe é recusada com CHANGE_CLASS_NOT_PERMITTED.
  • Quando qualquer commit da alteração está assinado pela identidade de agente da organização, o quórum é o mínimo habitual mais um, e o voto do próprio agente não conta.
  • Cada aprovação regista a diferença e o head que viu. Se a alteração mudar após a última aprovação, a integração é recusada com HASH_MISMATCH, e as aprovações têm de ser recolhidas novamente para o novo conteúdo.

Essa terceira regra é importante se desenvolver com uma ferramenta de programação com IA (inteligência artificial), como descreve o capítulo 2.26, Desenvolver com ferramentas de programação com IA. O trabalho escrito por um agente precisa de mais uma aprovação humana do que o trabalho escrito por uma pessoa. Planeie em conformidade.

Assinatura e verificação

Cada imagem e cada pacote são assinados pelo pipeline que os compilou, e uma imagem assinada é uma das barreiras de entrada em staging. Um espaço de desenvolvimento executa apenas imagens assinadas desde o início. Na Enterprise, um administrador define cada namespace para registar imagens não assinadas ou para as recusar, e passa os namespaces para recusa um de cada vez, para que a produção acabe por executar apenas imagens que o pipeline compilou e assinou. A assinatura faz parte da compilação, não é algo que se acrescenta antes de um lançamento.

A regra que atravessa tudo isto é que uma assinatura que falha é uma recusa, nunca um aviso. Uma verificação que recebe SIG_INVALID para. Não recorre à versão não assinada nem continua com uma nota num registo, porque um aviso num registo de compilação é uma aprovação para todos os que não o leram.

A mesma regra aplica-se a tudo o que entrega em suporte físico. Um pacote selado para um cliente air-gapped é verificado face à sua chave pública antes de qualquer coisa ser desempacotada, e o capítulo 2.25, Desenvolver para cada edição, mostra o comando.

Identidade de entrega

Um plugin é entregue através de vários elementos que têm, cada um, um nome: os seus repositórios, uma chave de assinatura, um namespace de implementação, um prefixo de registo, um esquema de base de dados, um conjunto de domínios e uma política de alterações. Qualquer um deles é um ponto onde dois plugins podem colidir, ou onde um plugin pode divergir. A identidade de entrega é um registo assinado por plugin que os contém a todos, para que cada verificação no percurso de lançamento leia a mesma resposta e recuse perante uma discrepância.

Contribui com a sua parte através do manifesto e de nada mais: schema, db, domains, changePolicy e o URL do repositório. A plataforma completa o registo com o resto e assina-o. Nunca indica o seu próprio namespace, prefixo de registo ou chave de assinatura. Estes são-lhe atribuídos, e um manifesto que tentasse declará-los estaria a fazer uma afirmação em que as verificações teriam depois de não acreditar.

O registo assinado contém onze campos: o slug do plugin, a organização proprietária, a organização que o compila, os seus repositórios, o nome da sua chave de assinatura, o seu namespace de implementação, o seu prefixo de registo, o seu esquema de base de dados, os seus domínios, a sua política de alterações e uma lista curta de nomes de imagem antigos que usava antes de o seu prefixo de registo existir. Esta última lista só pode diminuir. Por estar assinada, uma nova assinatura pode remover uma entrada e nada pode acrescentar uma de forma silenciosa. A assinatura é Ed25519 sobre a forma JSON canónica padrão desses onze campos, para que um registo com "Tomás" ou "Sinéad" seja verificado da mesma forma em todo o lado.

Quando uma versão não corresponde ao seu registo, prevalece a primeira recusa:

Código Quando HTTP
DELIVERY_IDENTITY_MISSING Não existe registo para o plugin 403
DELIVERY_PATH_REFUSED Um envio de imagem fora do prefixo de registo que não consta da lista assinada de nomes antigos 403
NAMESPACE_MISMATCH Uma implementação destinada a outro namespace 403
IMAGE_NAME_COLLISION Um nome de imagem já reivindicado por outro plugin 409
CHANGE_CLASS_NOT_PERMITTED Uma classe de alteração que a política não governa 403

IMAGE_NAME_COLLISION é a que surpreende as pessoas. Escolha outro nome e nunca reutilize um: um nome de imagem partilhado significa que a promoção de um plugin pode mover os pods de outro plugin.

Migrações, confirmadas e com âmbito definido

Uma migração é entregue dentro da imagem do seu plugin e é executada antes de a nova versão arrancar, através do único executor de migrações do SDK, nexus-migrate. Não escreve o seu próprio aplicador. Antes de qualquer versão poder avançar, o mesmo executor aplica as suas migrações um ficheiro de cada vez numa base de dados descartável, para que uma migração que falhe, falhe aí. A compilação shadow do modelo base chama o executor uma vez por ficheiro, por ordem, e regista cada ficheiro tal como a produção fará.

As regras do executor são as que as barreiras verificam, escritas como código:

  1. Liga-se com a função de migrador do seu esquema e executa cada ficheiro como proprietário do esquema. Qualquer outro início de sessão, a começar por um superutilizador, é recusado. Um ficheiro que tente mudar ele próprio de função é recusado antes de qualquer execução.
  2. O ficheiro de tenancy, numerado 0, nunca é editado depois de aplicado. Uma alteração à tenancy recebe o seu próprio ficheiro de revisão, 000_tenancy_r<N>.sql, que o nexus-tenancy render --revision <N> escreve por si.
  3. Normalmente, o executor detém a transação de cada ficheiro e recusa um BEGIN ou COMMIT dentro dela. Um ficheiro que gere as suas próprias transações declara que é executado por instrução, e então cada BEGIN que abre tem de ter correspondência.
  4. Mantém um livro de registo, com uma linha por ficheiro, com o SHA-256 do ficheiro e a forma como foi executado. Um ficheiro aplicado nunca é alterado no local; uma alteração é um novo ficheiro numerado.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Com âmbito significa que cada nova tabela tem organization_id, owner_user_id e business_unit_id, mais a coluna marcadora is_demo, a menos que gates/demo-exempt.json isente a tabela com uma justificação, com uma chave primária que começa pela organização e chaves estrangeiras que a transportam, e com segurança ao nível da linha imposta. A barreira migrations-are-scoped verifica essas regras em todos os ficheiros, e migrations-commit-what-they-open confirma que cada ficheiro faz commit do que abre. A segunda barreira existe porque, uma vez, uma migração que fez rollback silenciosamente terminou com 0, e a tabela que devia ter criado nunca existiu.

Há mais um ficheiro que pertence a cada versão. scripts/ci/required-env imprime as variáveis de ambiente de que o seu serviço precisa para arrancar, como uma matriz JSON obtida a partir do seu carregador de configuração. O percurso de lançamento executa-o e recusa uma versão cuja implementação não defina todas elas, para que uma variável em falta seja detetada antes do lançamento, e não por um pod que não arranca.

node scripts/ci/required-env

Lançar competências

Os dois tipos de skill chegam às pessoas por caminhos diferentes, por isso lance-os de forma diferente.

Uma skill de manifesto, uma linha tipada no skills[] do seu plugin, é entregue com o plugin e passa pela mesma promoção que o resto. A integração sincroniza todo o conjunto de skills com o registo a cada versão. Se deixar uma skill fora do conjunto, esta fica desativada, e na Enterprise uma sincronização com uma skill inválida não aplica nenhuma, pelo que a versão anterior continua em execução em vez de metade da nova.

Uma skill do Skills Engine é publicada a partir da biblioteca. No Enterprise, uma skill que adicione uma ferramenta de escrita aguarda que duas pessoas designadas a aprovem com as suas passkeys, e o proponente não pode ser uma delas. Uma versão aprovada é depois executada em modo sombra, depois em canary para uma unidade, sujeita a critérios designados, e depois para todos, e para automaticamente se um critério não for cumprido. Se o seu plugin e uma skill do Skills Engine dependerem um do outro, publique primeiro a skill e deixe-a chegar a todos antes de a versão do plugin que a invoca sair do piloto.

Canais e instalações

Depois de uma versão ter passado o piloto e chegado a todas as unidades, é disponibilizada num canal, e cada unidade escolhe o seu canal. O respetivo administrador aprova cada mudança. A página Canais e instalações mostra que unidades executam que versão, com as taxas de erro apenas em contagens: vê como a sua extensão se comporta, nunca o que alguém fez com ela.

Canais e instalações
Canais e instalações
Que unidades executam que versão do carrier-sync, com uma reversão aberta para uma unidade. Repare no que o modal indica que muda, no que se mantém, e que requer uma segunda pessoa, o próprio administrador da unidade.

O nosso plugin carrier-sync executa três versões em simultâneo, e isso é normal. A maioria das unidades está na versão atual, uma unidade mantém-se numa versão mais antiga num canal mantido até uma data indicada, e uma versão candidata está num canal que ainda ninguém escolheu. Não lute contra isso; uma unidade que precisa de estabilidade para uma auditoria tem direito a ela.

Os registos e métricas da sua extensão

A página de registos e métricas do seu pack está limitada às suas próprias cargas de trabalho, nas unidades onde tem permissão para consultar. Pode filtrar por unidade e ambiente, e vê contagens, tempos e estados.

Registos e métricas do seu pack
Registos e métricas do seu pack
Os registos e métricas do próprio Cold chain, filtrados para o piloto de Rotterdam. Observe as linhas de registo: a pessoa que comunicou uma excursão está oculta, e o texto da nota de reclamação nunca é registado.

Os campos pessoais são substituídos antes de uma linha ser escrita, e o conteúdo dos clientes, como o texto de reclamações, o correio ou o conteúdo de documentos, nunca é escrito nos registos. Os registos são conservados durante 14 dias. A organização é definida pelo gateway, nunca pela sua consulta, pelo que uma consulta que indique outra organização é recusada com TENANT_BOUNDARY. O assistente na barra lateral pode ler os mesmos registos consigo, e apenas esses: quando lhe perguntei por que razão os registos de excursão chegaram com atraso numa manhã, ele atribuiu 18 minutos de novas tentativas a leituras duplicadas provenientes da alimentação elétrica de um cais.

Reversão

Existem dois tipos de reversão, e ambos são alterações revistas e não interruptores.

A reversão de um ambiente utiliza a versão anterior. Cada ambiente conserva-a durante 30 dias. A reversão é preparada como uma alteração à versão, pré-visualiza o que irá fazer e requer uma segunda pessoa; depois de aprovada, o pipeline reverte em cerca de um minuto. Cada reversão é cronometrada, tal como cada simulacro, por isso pratique uma antes de precisar dela. A reversão de uma unidade utiliza a página Canais e instalações. O modal de reversão indica o que muda (essa unidade volta a executar a versão mais antiga, e a sua taxa de erro é monitorizada durante uma hora), o que se mantém (as outras unidades, bem como as definições e os registos da unidade), o motivo e quem é a segunda pessoa: o administrador dessa unidade.

As definições e os registos são mantidos durante uma reversão, por isso planeie cada versão partindo do princípio de que a versão anterior poderá voltar a ser executada sobre os dados que a mais recente escreveu. Essa é a razão prática para manter as migrações aditivas dentro de uma versão que possa ter de reverter, e a razão pela qual pedimos a duas pessoas que aprovem cada uma delas. Uma alteração ao modelo é igual: um revisor pode, e deve, pedir o plano de reversão de um pedido de alteração ao grafo antes de o aprovar.

As skills revertem de forma mais suave. Mover a etiqueta live de volta para uma versão anterior é um único passo, e as execuções já em curso terminam na versão com que começaram.

Descontinuar uma versão

Uma versão, depois de criada, nunca é editada. Uma versão que já não deve ser utilizada é retirada, e uma correção é lançada com um novo número de versão. Os próprios canais de lançamento do SDK seguem o mesmo hábito: uma versão defeituosa do SDK é retirada, nunca substituída por conteúdo diferente com o mesmo número. Siga este exemplo, porque um número de versão que pode corresponder a duas compilações diferentes torna inútil qualquer evidência sobre ele.

Retirar um plugin ou pack impede novas instalações. As unidades mantêm a versão que executam até mudarem, por isso a retirada é um sinal e um prazo, não um interruptor de desligar. Indique aos administradores das unidades para que versão devem mudar e até quando.

Descontinuar uma skill segue a mesma ideia, com um passo adicional. O Skills Engine move todos os chamadores restantes para uma substituta depois de executar os casos da substituta, impede novas execuções e conserva as versões, os casos e os registos de execução selados, para que a skill possa ser reposta caso a substituta se revele errada.

Uma lista de verificação de lançamento

Esta é a lista que lemos antes de cada versão do Cold chain. É curta porque a plataforma verifica a maior parte por nós.

  1. As versões coincidem: o manifesto, pack.json e o modelo de conhecimento, se tiver mudado.
  2. Todos os critérios estão verdes localmente, a partir de um estado limpo, e cada novo teste foi comprovado a falhar primeiro.
  3. A página Manifesto e permissões não mostra qualquer alargamento, ou o alargamento é o pretendido e os revisores sabem porquê.
  4. Cada migração é um novo ficheiro numerado, com âmbito definido, e aplicado sem erros numa base de dados descartável.
  5. scripts/ci/required-env lista todas as variáveis de que o serviço necessita, e a implementação define cada uma delas.
  6. O plano de reversão está escrito na alteração, incluindo para qualquer alteração ao modelo.
  7. Dois revisores que não sejam o autor estão disponíveis esta semana.

O último item parece trivial. É o que atrasou mais versões nossas do que todos os critérios juntos.