Como usar o comando nomos

O comando nomos (nomos.exe no Windows) é uma ferramenta de linha de comando opcional que pode ser instalada localmente, como em uma estação de trabalho ou em um laptop. Você pode usar o comando nomos para interagir com o Config Management Operator, verificar a sintaxe de configs antes de enviá-los para seu repo e depurar problemas com o Anthos Config Management, seu cluster ou seu repo.

Pré-requisitos

Para usar o comando nomos para interagir com um cluster, o Operator já precisa estar instalado no cluster de destino e o comando kubectl precisa ser configurado para se autenticar no cluster de destino. Consulte Como instalar o Anthos Config Management para mais informações.

Como instalar o comando nomos

O comando nomos é um binário compilado com base no código Go. Ele é opcional e não está incluído em uma instalação padrão do Anthos Config Management.

Para fazer o download do comando nomos para cada versão do Anthos Config Management, consulte Downloads.

Observação: o Anthos Config Management requer um direito ativo do Anthos. Caso contrário, o download falhará com um erro 404 File not found.
Para mais informações, consulte Preços do Anthos.

Etapas extras para clientes macOS e Linux

Depois de fazer o download o binário, configure-o para ser executável:

chmod +x /path/to/nomos

Mova o comando para um local onde seu sistema procure binários, como /usr/local/bin ou execute o comando usando o caminho totalmente qualificado.

Uso básico

Os comandos nomos e nomos.exe incluem subcomandos para inicializar o repo, verificar se há erros de sintaxe, saber o status de cada cluster registrado e visualizar o repo como uma série de CustomResourceDefinitions.

Para sintaxe de comando básica, use o argumento --help:

nomos --help

O comando nomos é lido pelo clone local do seu repo. Use a sinalização --path para especificar o local do nível superior do repo. Por padrão, --path é definido como . ou o diretório atual.

nomos --path=path/to/your/repo status

Como verificar o status da instalação

Você pode verificar se o Anthos Config Management está instalado e configurado corretamente em todos os seus clusters usando o comando nomos status. Ele relata quaisquer erros que impedem a execução do Anthos Config Management. Exemplo:

nomos status
Context             Status           Last Synced Token
-------             ------           -----------------
managed-cluster-1   NOT INSTALLED
managed-cluster-2   NOT CONFIGURED
managed-cluster-3   SYNCED           f52a11e4

Config Management Errors:
managed-cluster-2   missing git-creds Secret

Nesta saída, o Anthos Config Management não está instalado em managed-cluster-1. Ele está instalado, mas não está configurado em managed-cluster-2. Ele está instalado e em execução corretamente em managed-cluster-3.

Além disso, o motivo para managed-cluster-2 não estar configurado é que o secret git-creds não está presente.

Como inicializar um novo repo

Para inicializar um novo repo do Anthos Config Management, crie um diretório vazio, mude para ele, inicialize um novo repositório Git e execute o comando nomos init:

mkdir my-repo
cd my-repo
git init
nomos init

Isso cria a estrutura de diretórios básica do seu repo, inclusive os diretórios system/, cluster/ e namespaces/.

Como verificar erros no repo

Para confirmar uma configuração para o repo, use o comando nomos vet para verificar a sintaxe e a validade das configurações no repo:

nomos vet

Se forem encontrados erros de sintaxe, o comando nomos vet sairá com um status diferente de zero e registrará mensagens de erro em STDERR.

Se nomos vet não puder determinar se o tipo está no namespace, nomos se conectará ao API Server. Como nomos entende os principais tipos de Kubernetes e os CRDs do Anthos Config Management, ele só tenta se conectar à API Server se houver respostas automática que não tenham CRD declarado correspondente. Nesse caso, se o servidor da API não tiver o CRD aplicado, nomos vet retornará um erro. Para desativar essa verificação e suprimir erros de CRDs ausentes, transmita a sinalização --no-api-server-check.

Como verificar automaticamente erros de sintaxe ao confirmar

Se você confirmar um arquivo com erros JSON ou YAML, o Anthos Config Management não aplicará a alteração. No entanto, é possível evitar que esses tipos de erros entrem no repo usando os hooks do lado do cliente ou do lado do servidor.

Como usar nomos vet em um hook de pré-confirmação do Git

É possível configurar um hook de pré-confirmação que executa nomos vet para verificar se há erros de sintaxe quando você faz uma alteração no clone do Git local do seu repo. Se um hook de pré-confirmação sair com um status diferente de zero, a operação git commit falhará.

Para executar o comando nomos vet como um hook de pré-confirmação, edite o arquivo .git/hooks/pre-commit no repo. .git começa com um caractere .. Talvez seja necessário criar o arquivo manualmente. Adicione o comando nomos vet a uma nova linha no script. O argumento --path é opcional.

nomos vet --path=/path/to/repo

Verifique se o arquivo pre-commit é executável:

chmod +x .git/hooks/pre-commit

Agora, quando você executa um comando git commit no clone do seu repo, o nomos vet é executado automaticamente.

O conteúdo do diretório .git/ do repo não é rastreado pelo próprio repo e não pode ser confirmado para ele no mesmo local. É possível criar um diretório no repo para hooks Git, e as pessoas que usam o repo podem copiar os hooks para o local apropriado em seu clone local.

Como usar nomos vet em um hook do lado do servidor

O Git fornece um mecanismo para executar verificações no servidor, e não no cliente, durante uma operação de git push. Se a verificação falhar, o git push também falhará. Esses hooks do lado do servidor não podem ser ignorados pelo cliente. O método para configurar os ganchos do lado do servidor depende de como seu servidor Git está hospedado. Consulte um dos links a seguir para mais informações ou consulte a documentação do serviço de hospedagem do Git.

Como visualizar o resultado de todas as configurações no repo

É possível usar o comando nomos hydrate para visualizar o conteúdo combinado do seu repo em cada cluster registrado.

Se você executar nomos hydrate sem opções, ele criará um diretório compiled/ no diretório de trabalho atual. Nesse diretório, um subdiretório é criado para cada cluster registrado, com as configurações totalmente resolvidas que o Operator aplicaria ao cluster.

Especifique o nome do diretório de saída oferecendo um caminho de diretório como o argumento do comando:

nomos hydrate [/path/to/directory]

Para limitar a saída a um único cluster ou a uma lista de clusters, use a sinalização --clusters e forneça uma lista separada por vírgulas de nomes de cluster.

Para emular o comportamento de nomos view e salvar a configuração efetiva em um único arquivo, use a sinalização --flat.

Para mais informações, use a sinalização --help:

nomos hydrate --flat

nomos view

Quando o Anthos Config Management importa configs do repo, ele as converte em CustomResourceDefinitions (CRDs) do tipo ClusterConfig ou NamespaceConfig. O comando nomos view permite visualizar os CRDs resultantes do estado atual do repo no formato JSON. Isso pode ser útil para confirmar a alteração ou depurar problemas com configs que não são óbvios usando o comando nomos vet.

nomos view --path=/path/to/your/repo

Verificar se há erros nos clusters

Sempre que você envia por push uma confirmação do Git para o repo, o Operator detecta a alteração e aplica as novas configurações a todos os clusters registrados. Você pode monitorar o status do Anthos Config Management em todos os clusters registrados usando o comando nomos status. Para cada cluster, ele informa o hash da confirmação do Git que foi aplicado pela última vez ao cluster, bem como todos os erros que ocorreram durante a tentativa de aplicar alterações recentes. Exemplo:

nomos status
Context                 Status      Last Synced Token
-------                 ------      -----------------
managed-cluster-1       SYNCED      f52a11e4
managed-cluster-2       PENDING     9edf8444
managed-cluster-3       ERROR       9edf8444
managed-cluster-4       NOT INSTALLED
managed-cluster-5       SYNCED      f52a11e4

Config Management Errors:
managed-cluster-3       KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

Veja que dois dos clusters sincronizaram a alteração mais recente, um cluster ainda está sincronizando e um cluster tem um erro que impediu a aplicação da alteração. Nesse caso, aparentemente, managed-cluster-3 não tem um CRD instalado pelos outros clusters.

Por padrão, o comando nomos status imprimirá o status de cada cluster e sairá. No entanto, é possível usar a sinalização poll para executar o comando continuamente e solicitar que ele reimprima a tabela de status em um intervalo regular.

nomos status --poll 2s

Sobre o último token sincronizado

nomos status exibe o hash de commit do Git mais recente aplicado ao cluster na saída em Last Synced Token. Para receber esse valor, consulte o objeto Repo e observe o campo status.sync:

kubectl get repos.configmanagement.gke.io -o yaml
apiVersion: v1
kind: Repo
items:
- status:
    sync:
      lastUpdate: "2019-09-26T10:17:57Z"
      latestToken: f1739af550912034139aca51e382dc50c4036ae0

Essa confirmação representa a confirmação mais recente no cluster. No entanto, nem todos os namespaces no cluster são afetados por cada confirmação. Para ver o commit mais recente em um namespace específico, consulte o objeto NamespaceConfig específico e observe o campo status. Exemplo:

kubectl get namespaceconfigs.configmanagement.gke.io my-namespace -o yaml
apiVersion: configmanagement.gke.io/v1
kind: NamespaceConfig
status:
  syncState: synced
      lastUpdate: "2019-09-26T08:24:32Z"
      latestToken: 1850bad9419d3baec8af220c15d5e952dbeb3b25

Mesmo que um namespace possa ser afetado por uma confirmação, nem todos os recursos no namespace podem ter sido afetados. Para encontrar a confirmação mais recente sincronizada de um recurso específico, consulte o recurso específico e consulte metadata.annotations.configmanagement.gke.io/token. Exemplo:

kubectl get clusterrolebindings.rbac.authorization.k8s.io my-role-binding -o yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/token: e56b09554ca8004a2c38185a4ed11364fd6986c4

Como criar um relatório de bugs

Se você tiver um problema com o Anthos Config Management que exija ajuda do suporte do Google Cloud, poderá fornecer-lhes informações valiosas de depuração usando o comando nomos bugreport.

nomos bugreport

Este comando gera um arquivo zip com carimbo de data e hora com informações sobre o cluster Kubernetes definido no seu contexto kubectl.

O arquivo contém logs dos pods do Anthos Config Management. Ele não contém informações dos recursos sincronizados com o Anthos Config Management.

Resolver problemas

No Linux, talvez você veja o seguinte erro ao executar um comando nomos:

failed to create client configs: while getting config path: failed to get current user: user: Current not implemented on linux/amd64

Crie uma variável de ambiente USER para corrigir esse problema:

export USER=$(whoami)

A seguir