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. É possível usar o comando nomos para verificar a sintaxe de configs antes de confirmá-los no repositório e depurar problemas com Config Sync, cluster e repo.

Pré-requisitos

Antes de usar o comando nomos para interagir com um cluster, o operador já precisa estar instalado no cluster de destino e você precisa configurar o comando kubectl para autenticar no cluster de destino por Como gerar uma entrada kubeconfig.

Instalar o comando nomos

O comando nomos é um binário compilado com base no código Go. Ele é opcional e não é incluído quando você instala o Config Sync. É possível instalar o comando nomos instalando o SDK do Cloud. Se você usa o Cloud Shell, o SDK do Cloud vem pré-instalado.

Se você não tiver o SDK do Cloud, recomendamos que use gcloud components install nomos para instalar a ferramenta de linha de comando nomos. A instalação de nomos com a ferramenta de linha de comando gcloud permite que você use gcloud components update para atualizar nomos para a versão mais recente.

Para informações sobre maneiras alternativas de instalar a ferramenta de linha de comando nomos, consulte Downloads do Anthos Config Management.

Uso básico

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. Exemplo:

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

Verificar o status da instalação

Monitore o status do Config Sync em todos os clusters registrados usando o comando nomos status. Para cada cluster, nomos status 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

Exemplo de saída:

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

Nesta saída:

  • my_managed_cluster-1 e my_managed_cluster-5 sincronizaram a alteração mais recente.
  • my_managed_cluster-2 ainda está sincronizando.
  • my_managed_cluster-3 tem um erro que impediu a aplicação da alteração. Nesse caso, managed-cluster-3 não tem um CRD que os outros clusters instalaram.
  • my-managed-cluster-4 não tem o Config Sync instalado.

Verificar o status da instalação (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

Exemplo de saída:

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.

Sobre a última confirmação sincronizada

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

Por exemplo, para consultar um objeto RootSync, execute o seguinte comando:

kubectl get rootsyncs.configsync.gke.io -n config-management-system root-sync -o yaml

Exemplo de saída:

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
status:
  sync:
    commit: f1739af550912034139aca51e382dc50c4036ae0
    lastUpdate: "2021-04-20T00:25:01Z"

Para consultar um objeto RepoSync, execute o seguinte comando:

kubectl get reposync.configsync.gke.io -n NAMESPACE repo-sync -o yaml

Substitua NAMESPACE pelo namespace em que você criou seu repositório de namespace.

Exemplo de saída:

apiVersion: configsync.gke.io/v1beta1
kind: RepoSync
status:
  sync:
    commit: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f
    lastUpdate: "2021-04-20T00:25:20Z"

Essa confirmação representa a confirmação mais recente no cluster. No entanto, nem todos os recursos no cluster são afetados por cada confirmação. Para ver a confirmação mais recente de um recurso específico, consulte o recurso específico e procure metadata.annotations.configmanagement.gke.io/token. Exemplo:

kubectl get clusterroles CLUSTER_ROLE_NAME -o yaml

Substitua CLUSTER_ROLE_NAME pelo nome do clusterrole que você quer consultar.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    configmanagement.gke.io/token: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f

sinalizações de status nomos

Para personalizar nomos status, adicione as sinalizações a seguir:

Sinalização Descrição
--contexts Aceita uma lista separada por vírgulas de contextos para usar em comandos de vários clusters. O padrão é todos os contextos. Não use "" para nenhum contexto.
-h ou --help Ajuda para o comando nomos status.
--namespace Aceita uma string. Use a sinalização namespace para limitar o comando a um repositório de namespaces específico. Deixe sem definir para receber todos os repositórios. Essa sinalização só estará disponível se o modo multirepo estiver ativado
--poll Use a sinalização poll para executar nomos status continuamente e solicitar que ela reimprima a tabela de status em um intervalo regular. Exemplo:3s Deixe essa sinalização não configurada para executar nomos status uma vez
--resources Aceita true ou false. Se true, nomos status mostrará o status do nível de recurso do repositório raiz ou de namespace ao sincronizar de vários repositórios O valor padrão é true.
--timeout Tempo limite para se conectar a cada cluster. O valor padrão é 3s.

Verificar o status de cada recurso

No nomos 1.8.0 ou em versões mais recentes, é possível verificar se os recursos gerenciados pelo Config Sync estão prontos usando o comando nomos status. Esse comando informa o status de cada recurso individual do repositório Git. Exemplo:

nomos status --contexts my_managed_cluster_4

Exemplo de saída:

my_managed_cluster_4
  --------------------
  <root>   https:/github.com/GITHUB_USERNAME/anthos-config-management-samples/namespace-specific-policy/configsync@main
  SYNCED   bf8655aa
  Managed resources:
     NAMESPACE   NAME                                                             STATUS
                 namespace/foo                                                    Current
                 namespace/istio-system                                           Current
                 namespace/tenant-a                                               Current
                 namespace/tenant-b                                               Current
                 namespace/tenant-c                                               Current
     tenant-a    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-a    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-a    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current
     tenant-b    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-b    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-b    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current
     tenant-c    networkpolicy.networking.k8s.io/deny-all                         Current
     tenant-c    role.rbac.authorization.k8s.io/tenant-admin                      Current
     tenant-c    rolebinding.rbac.authorization.k8s.io/tenant-admin-rolebinding   Current

Neste exemplo, todos os recursos têm o status Current, o que significa que o estado do recurso corresponde ao estado que você quer.

O status pode ter um dos seguintes valores:

  • InProgress: o estado real do recurso ainda não atingiu o estado especificado no manifesto do recurso. Isso significa que a reconciliação de recurso ainda não está concluída. Recursos recém-criados geralmente começam com esse status, embora alguns recursos, como ConfigMaps, sejam Current imediatamente.

  • Failed: o processo de reconciliar o estado real com o estado que você quer encontrou um erro ou fez progresso insuficiente.

  • Current: o estado real do recurso corresponde ao estado que você quer. O processo de reconciliação é considerado concluído até que haja alterações no estado desejado ou real.

  • Terminating: o recurso está em processo de exclusão.

  • NotFound: o recurso não existe no cluster.

  • Unknown: o Config Sync não determina o status do recurso.

Para desativar a exibição do status no nível do recurso, adicione --resources=false ao comando nomos status.

Verificar se há 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.

Sinalizações nomos vet

Para personalizar nomos vet, adicione as sinalizações a seguir:

Sinalização Descrição
--clusters Aceita uma lista separada por vírgulas de nomes de cluster para usar em comandos de vários clusters. O padrão para todos os clusters. Use "" para nenhum cluster.
-h ou --help Ajuda para o comando nomos vet.
--namespace Aceita uma string. Se definido, valida o repositório como um repositório de namespaces com o nome fornecido. Define --source-format=unstructured automaticamente.
--no-api-server-check Aceita um booleano. Se true, desativa a comunicação com o servidor da API para descoberta. Para mais informações sobre essa sinalização, consulte a seção Validação do lado do servidor.
--path Aceita uma string. O caminho para o diretório raiz do repositório do Config Sync. O padrão é ".".
--source-format Aceita hierarchy ou unstructured. Se hierarchy ou não definido, valida o repositório como um repositório hierárquico. Se unstructured, valida o repositório como um repositório não estruturado. Essa sinalização é necessária se você estiver usando um repositório não estruturado.
--keep-output Aceita um booleano. Se for true, a saída renderizada será salva no local que pode ser especificado com a sinalização --output. Essa sinalização está disponível nas versões 1.9.0 e posteriores.
--output Aceita uma string. Caminho para a saída renderizada. O padrão é o diretório compiled. Se --keep-output estiver definido como false, essa sinalização será ignorada. Essa sinalização está disponível nas versões 1.9.0 e posteriores.
--format Aceita yaml ou json. Formato da saída. O valor padrão é yaml. Essa sinalização está disponível nas versões 1.9.0 e posteriores.

Validação do servidor

Se nomos vet não puder determinar se o tipo está com namespace, nomos se conectará ao servidor de API. Como, por padrão, nomos entende os principais tipos do Kubernetes e os CRDs do Config Sync, ele só tenta se conectar ao servidor da API se houver respostas automáticas que não tenham um 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.

Armazenar em cache os metadados do servidor de API

Em vez de suprimir verificações de servidor da API, é possível armazenar os dados em cache no servidor de API para nomos vet. Para armazenar seu api-resources em cache, conclua as seguintes etapas:

  1. Conecte-se a um cluster que tenha todos os CRDs necessários para seu repositório. Ele não precisa ter o Config Sync ativado.
  2. Acesse o policyDir do seu repositório. Esse é o mesmo diretório especificado no recurso ConfigManagement ou RootSync.
  3. Execute o seguinte comando: kubectl api-resources > api-resources.txt. Ele cria um arquivo chamado api-resources.txt que contém a saída exata do kubectl api-resources.

A partir de agora, as execuções de nomos vet no repositório reconhecem essas definições de tipo. Se o arquivo api-resources.txt for removido ou renomeado, nomos vet não será capaz de encontrá-lo. nomos vet ainda tentará se conectar ao cluster se encontrar manifestos para tipos não declarados no api-resources.txt (a menos que --no-api-server-check seja transmitido).

O arquivo api-resources.txt afeta apenas o funcionamento da CLI do Nomos. Ele não modifica o comportamento do Config Sync de maneira alguma.

Não há problema em ter entradas extras no arquivo api-resources.txt de tipos que não estão sendo validados no repositório. nomos vet importa as definições, mas não faz nenhuma alteração.

Atualizar api-resources.txt

Depois de garantir que todos os CRDs que você quer inserir estão no cluster, execute o seguinte comando:

kubectl api-resources > api-resources.txt

Verificar automaticamente erros de sintaxe na confirmação

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.

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.

Visualizar todas as configurações do repositório

É 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.

Esse comando também pode ser usado para converter um repositório hierárquico em um ou mais repositórios não estruturados usando o conteúdo no diretório compiled/.

sinalizações nomos hydrate

Para personalizar nomos hydrate, adicione as sinalizações a seguir:

Sinalização Descrição
--clusters Aceita uma lista separada por vírgulas de nomes de cluster. Use esta sinalização para limitar a saída a um único cluster ou a uma lista de clusters. O padrão para todos os clusters. Use "" para nenhum cluster.
--flat Se ativado, imprimir toda a saída em um único arquivo. Use essa sinalização se quiser emular o comportamento de nomos view.
-h ou --help Ajuda para o comando nomos hydrate.
--format Aceita um yaml ou um json. Formato da saída. O valor padrão é yaml. Essa sinalização está disponível nas versões 1.9.0 e posteriores.
--no-api-server-check Aceita um booleano. Se true, desativa a comunicação com o servidor da API para descoberta. Para mais informações sobre essa sinalização, consulte a seção Validação do lado do servidor.
--output Aceita uma string. O local em que a configuração hidratada será gravada. O padrão é o diretório compiled. Se --flat não estiver ativado, gravará cada manifesto de recurso como um arquivo separado. Se --flat estiver ativado, gravará em um único arquivo que contenha todos os manifestos de recursos.
--path Aceita uma string. O caminho para o diretório raiz do repositório do Config Sync. O padrão é ".".
--source-format Aceita hierarchy ou unstructured. Se hierarchy ou não definido, valida o repositório como um repositório hierárquico. Se unstructured, valida o repositório como um repositório não estruturado. Essa sinalização é necessária se você estiver usando um repositório não estruturado e estiver disponível nas versões 1.9.0 e posteriores.

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

Criar um relatório do bug

Se você tiver um problema com o Config Sync que requer ajuda do suporte do Google Cloud, forneça informações importantes de depuração usando o comando nomos bugreport. Use esse comando para repositórios únicos e vários repositórios.

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.

Inicializar um repositório hierárquico

É possível organizar seu repo arbitrariamente se usar um repositório não estruturado. Se você estiver usando um repositório hierárquico, execute o comando nomos init para inicializar um diretório hierárquico:

nomos init

Isso cria a estrutura de diretórios básica de um repositório hierárquico, incluindo os diretórios system/, cluster/ e namespaces/.

nomos sinalizações init

Para personalizar nomos init, adicione as sinalizações a seguir:

Sinalização Descrição
--force Gravar no diretório mesmo se não estiver vazio, substituindo arquivos conflitantes
-h ou --help Ajuda para o comando nomos init.
--path Aceita uma string. O diretório raiz a ser usado para seu repositório do Anthos Config Management. O valor padrão é "."

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

Para corrigir esse problema, crie uma variável de ambiente USER:

export USER=$(whoami)

A seguir