Usar a ferramenta de linha de comando nomos

A ferramenta de linha de comando nomos é opcional no Config Sync. A ferramenta nomos fornece os seguintes comandos:

Uso do comando
nomos status Verificar o status do Config Sync
nomos vet Verificar se há erros no repositório
nomos hydrate Visualizar todas as configurações no repositório
nomos bugreport Criar um relatório do bug
nomos migrate Migrar do ConfigManagement para RootSync
nomos init Inicializar um repositório hierárquico

Prerequisites

Antes de usar a ferramenta nomos para interagir com um cluster, o Config Sync já precisa estar instalado no cluster de destino. Você também precisa configurar a ferramenta de linha de comando kubectl para autenticação no cluster de destino gerando uma entrada kubeconfig.

A ferramenta nomos é compatível com a visualização e validação de configurações do Kustomize e gráficos do Helm. Antes de usar esse recurso, instale o Kustomize e o Helm na sua estação de trabalho local. Se o repositório contiver apenas configurações totalmente renderizadas, o Kustomize e o Helm serão opcionais.

Instalar a ferramenta nomos

A ferramenta nomos é um binário compilado do código Go e pode ser instalada localmente, por exemplo, em uma estação de trabalho ou laptop.

A ferramenta nomos não está incluída quando você instala o Config Sync. É possível instalar a ferramenta nomos instalando o Google Cloud CLI. Se você usa o Cloud Shell, o Google Cloud CLI já vem pré-instalado.

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

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

Uso básico

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

nomos --help

A ferramenta nomos lê o clone local do seu repositório. Use a sinalização --path para especificar o local do nível superior do repositório. Por padrão, --path é definido como . ou o diretório atual. Exemplo:

nomos --path=PATH_TO_REPOSITORY vet

Verificar o status do Config Sync

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

A partir da versão 1.8.0 do nomos, também é possível usar nomos status para verificar se os recursos gerenciados pelo Config Sync estão prontos. O nomos status informa o status de cada recurso individual do repositório Git na coluna STATUS da seção Managed resources da saída.

O exemplo a seguir mostra algumas das diferentes condições que o comando nomos status pode informar:

nomos status

Exemplo de saída:

MANAGED_CLUSTER_1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
               k8snoexternalservices.constraints.gatekeeper.sh/no-internet-services   Current
               namespace/hello                                                        Current

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

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.

MANGED_CLUSTER_4
  --------------------
  NOT INSTALLED

MANAGED_CLUSTER_5
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
                namespace/gamestore                                                   Current
                namespace/monitoring                                                  Current
   gamestore    reposync.configsync.gke.io/repo-sync                                  Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-admin                 Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-webstore-admin        Current
   monitoring   deployment.apps/prometheus-operator                                   Current
   monitoring   prometheus.monitoring.coreos.com/acm                                  Current
   monitoring   service/prometheus-acm                                                Current
   monitoring   service/prometheus-operator                                           Current
   monitoring   serviceaccount/prometheus-acm                                         Current
   monitoring   serviceaccount/prometheus-operator                                    Current
   monitoring   servicemonitor.monitoring.coreos.com/acm-service                      Current
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8
  Managed resources:
   NAMESPACE   NAME                                 STATUS
   gamestore   configmap/store-inventory            Current
   gamestore   webstore.marketplace.com/gameplace   Current

Nesta saída:

  • MANAGED_CLUSTER_1 sincronizou a alteração mais recente no repositório e todos os recursos gerenciados têm status Current. O status Current significa que o estado do recurso corresponde ao estado que você quer.
  • MANAGED_CLUSTER_2 ainda está sincronizando.
  • MANAGED_CLUSTER_3 tem um erro que impediu a aplicação da alteração. Nesse exemplo, MANAGED_CLUSTER_3 tem o erro KNV1021, já que falta um CustomResourceDefinition (CRD) que os outros clusters instalaram.
  • MANAGED_CLUSTER_4 não tem o Config Sync instalado.
  • MANAGED_CLUSTER_5 está sincronizando 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.

Status de recursos gerenciados

O status dos recursos gerenciados pode ser 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 recursos 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 pretendido 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.

Sobre a última confirmação sincronizada

O comando nomos status exibe o hash de confirmação 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 papel de cluster que quer consultar.

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

sinalizações de status nomos

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

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 a sincronização tiver sido ativada em vários repositórios.
--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 no nível do recurso do repositório raiz ou de namespace ao sincronizar com vários repositórios. O valor padrão é true.
--timeout Tempo limite para se conectar a cada cluster. O valor padrão é 3s.

Permissões exigidas

Se você é proprietário de um projeto, tem o papel RBAC cluster-admin e pode usar nomos status para qualquer cluster do projeto sem adicionar outras permissões. Se você não tiver o papel cluster-admin, poderá usar nomos status criando o seguinte ClusterRole:

  1. Crie um arquivo chamado nomos-status-reader.yaml e copie o seguinte ClusterRole nele. As regras necessárias variam de acordo com o uso de objetos RootSync e RepoSync.

    Usar objetos RootSync e RepoSync

    # nomos-status-reader.yaml
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: nomos-status-reader
    rules:
    - apiGroups: ["configsync.gke.io"]
      resources: ["reposyncs", "rootsyncs"]
      verbs: ["get"]
    - nonResourceURLs: ["/"]
      verbs: ["get"]
    

    Não usar objetos RootSync e RepoSync

    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: nomos-status-reader
    rules:
    - apiGroups: ["configmanagement.gke.io"]
      resources: ["configmanagements", "repos"]
      verbs: ["get", "list"]
    - nonResourceURLs: ["/"]
      verbs: ["get"]
    
  2. Aplique o arquivo nomos-status-reader.yaml:

    kubectl apply -f nomos-status-reader.yaml
    

Verificar se há erros no repositório

Antes de confirmar uma configuração para o repositório, use o comando nomos vet para verificar a sintaxe e a validade das configurações no repositório:

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 do nomos vet

Para personalizar o comando nomos vet, adicione as seguintes sinalizações:

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 lado do servidor

Se o comando nomos vet não conseguir determinar se o tipo tem namespace, a ferramenta nomos se conectará ao servidor da API. Como, por padrão, a ferramenta nomos entende os principais tipos do Kubernetes e os CRDs do Config Sync, ela só tentará 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, o comando nomos vet retornará o error KNV1021. Para desativar essa verificação e suprimir erros de CRDs ausentes, transmita a sinalização --no-api- server-check.

Como armazenar em cache os metadados do servidor da API

Em vez de suprimir as verificações do servidor da API, você pode armazenar em cache os dados no servidor da API para o comando 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 ferramenta 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 repositório. 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 repositório (observe que .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 repositório, o nomos vet é executado automaticamente.

O conteúdo do diretório .git/ do repositório não é rastreado pelo repositório em si e não pode ser confirmado nele no mesmo local. É possível criar um diretório no repositório para hooks Git, e as pessoas que usam o repositório 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 no repositório

É possível usar o comando nomos hydrate para visualizar o conteúdo combinado do repositório 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 o comando nomos hydrate, adicione as seguintes sinalizações:

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

Quando o Config Sync importa configurações do repositório, ele as converte em 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 uma alteração ou depurar problemas com configurações que não sejam evidentes usando o comando nomos vet.

nomos view --path=PATH_TO_REPOSITORY

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.

Migrar de um objeto ConfigManagement para um objeto RootSync

É possível executar o comando nomos migrate para migrar do objeto ConfigManagement para um RootSync, para ativar as APIs RootSync e RepoSync. O comando está disponível na versão nomos 1.10.0 e posterior.

O nomos migrate é compatível com simulação para a visualização prévia do processo de migração.

nomos migrate --dry-run

Se o resultado de simulação parecer bom, será possível migrar o objeto ConfigManagement usando nomos migrate:

nomos migrate

A saída será assim:

--------------------
Enabling the multi-repo mode on cluster "my_managed_cluster-1" ...
- A RootSync object is generated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml".
- The original ConfigManagement object is saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-original.yaml".
- The ConfigManagement object is updated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml".
- Resources for the multi-repo mode have been saved in a temp folder. If the migration process is terminated, it can be recovered manually by running the following commands:
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml && \
  kubectl wait --for condition=established crd rootsyncs.configsync.gke.io && \
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml.
- Updating the ConfigManagement object ....
- Waiting for the RootSync CRD to be established ....
- The RootSync CRD has been established.
- Creating the RootSync object ....
- Waiting for the reconciler-manager Pod to be ready ....
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
- The reconciler-manager Pod is running.
- Waiting for the root-reconciler Pod to be ready ....
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
- The root-reconciler Pod is running.
- The migration process is done. Please check the sync status with `nomos status`.

Finished migration on all the contexts. Please check the sync status with `nomos status`.

sinalizações nomos migrate

Para personalizar o comando nomos migrate, adicione as seguintes sinalizações:

Sinalização Descrição
--connect-timeout Aceita uma duração. Duração do tempo limite para se conectar a cada cluster. O padrão é 3s.
--contexts Aceita uma lista separada por vírgulas de contextos para usar em ambientes de vários clusters. O padrão é o contexto atual. Use "all" para todos os contextos.
--dry-run Aceita um booleano. Se true, exibe apenas a saída da migração.
-h ou --help Ajuda para o comando nomos migrate.
--wait-timeout Aceita uma duração. Duração do tempo limite para aguardar que as condições dos recursos do Kubernetes sejam verdadeiras. O padrão é 10m.

Inicializar um repositório hierárquico

É possível organizar o repositório arbitrariamente se você usar um repositório não estruturado. Se você estiver usando um repositório hierárquico, você precisará executar 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/.

sinalizações nomos 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