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. Use o comando nomos para interagir com o Config Sync Operator, verificar a sintaxe de configs antes de confirmá-los no repo e depurar problemas com o Config Sync, o cluster ou o repo.

Pré-requisitos

Para usar o comando nomos para interagir com um cluster, o operador 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 Config Sync 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 Config Sync.

Para fazer o download do comando nomos de cada versão do Config Sync, consulte Downloads.

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

Verifique se o Config Sync está instalado e configurado corretamente em todos os clusters usando o comando nomos status. Ele informa todos os erros que impedem a execução do Config Sync. Exemplo:

nomos status
my_managed_cluster-1
  --------------------
  NOT INSTALLED

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR
  Error:   git-creds not found. Create git-creds secret in config-management-system namespace.

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

Nesta resposta, o Config Sync não está instalado em managed-cluster-1. Ele está instalado, mas não está configurado corretamente 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 corretamente é que o secret git-creds não está presente.

Como inicializar um novo repo

Para inicializar um novo repo do Config Sync, crie um diretório vazio, mude para ele, inicialize um novo repositório do 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á com namespace, nomos se conectará ao servidor de API. Como nomos entende os tipos principais do Kubernetes e os CRDs do Config Sync, ele só tenta se conectar ao servidor da API se houver CRs que não têm 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 Config Sync não aplicará a alteração. No entanto, é possível evitar que esses tipos de erros entrem no repositório 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

Ao importar configurações do repositório, o Config Sync os converte em CustomResourceDefinitions (CRDs) do tipo ClusterConfig ou NamespaceConfig. O comando nomos view permite visualizar os CRDs resultantes do estado atual do repositório no formato JSON. Isso pode ser útil para confirmar a alteração ou depurar problemas com configurações 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. Monitore o status do Config Sync 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
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  PENDING  9edf8444

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

my_managed_cluster-4
  --------------------
  NOT INSTALLED

my_managed_cluster-5
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

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 imprime o status de cada cluster e sai. 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

Verifique se há erros nos clusters (vários repositórios)

Se você tiver ativado a opção de vários repositórios para seu cluster, será possível sincronizar a partir de vários repositórios Git. O comando nomos status imprime o status de cada repositório, agrupado por cluster. Exemplo:

nomos status
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

Observe que cada um dos clusters está configurado com dois repositórios Git. O repositório <root> pertence ao administrador do cluster, e o repositório bookstore pode pertencer a uma equipe de desenvolvimento de aplicativos.

Por padrão, o comando nomos status imprime o status de todos os repositórios no cluster. No entanto, é possível usar a sinalização namespace para limitar o comando a um repositório com namespace específico. Isso permite que a equipe de aplicativo use nomos status para seu repositório:

nomos status --namespace bookstore

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 Config Sync que requer ajuda do suporte do Google Cloud, forneça informações valiosas de depuração usando o comando nomos bugreport.

nomos bugreport

Esse comando gera um arquivo zip com carimbo de data / hora com informações sobre o cluster do Kubernetes definido no contexto kubectl.

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

Solução de 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