Usar um repositório hierárquico

Esta página descreve como o Config Sync lê configurações de uma fonte da verdade hierárquica e aplica a configuração resultante aos clusters automaticamente.

Se você quiser mais flexibilidade estrutural (por exemplo, criar subpastas de recursos), crie uma fonte de verdade não estruturada. As fontes de verdade não estruturadas são recomendadas para a maioria dos casos de uso. Se você já estiver usando uma fonte de verdade hierárquica, converta-a em uma fonte de verdade não estruturada.

Para entender como o Config Sync usa um repositório hierárquico, é útil que você esteja familiarizado com os repositórios Git e a interface de linha de comando git.

Estrutura do diretório

Para fontes hierárquicas, o Config Sync aproveita estruturas semelhantes a sistemas de arquivos e usa o diretório para determinar para quais clusters ou namespaces uma configuração é relevante.

namespaces/

O diretório namespaces/ contém configurações para namespaces e objetos com escopo de namespace. A estrutura em namespaces/ é o mecanismo que impulsiona a herança de namespace. É possível limitar quais namespaces podem herdar um config usando um NamespaceSelector.

cluster/

O diretório cluster/ contém configurações que se aplicam a clusters inteiros, em vez de namespaces. Por padrão, qualquer configuração no diretório cluster/ se aplica a todos os clusters inscritos no Config Sync. É possível limitar quais clusters um config pode afetar usando ClusterSelector.

clusterregistry/

O diretório clusterregistry/ é opcional e contém configurações ClusterSelectors. ClusterSelectors limitam os clusters aos quais um config se aplica. Eles são referenciados nos configs encontrados nos diretórios cluster/ e namespaces/.

system/

O diretório system/ contém configs para o operador.

Exemplo de fonte hierárquica de verdade

A estrutura de diretórios a seguir demonstra como usar uma fonte de verdade hierárquica do Config Sync para configurar um cluster do Kubernetes compartilhado por duas equipes diferentes, team-1 e team-2.

  • Cada equipe tem o próprio namespace do Kubernetes, a conta de serviço do Kubernetes, as cotas de recursos, as políticas de rede e os RoleBindings.
  • O administrador do cluster configura uma política em namespaces/limit-range.yaml para restringir as alocações de recursos (para pods ou contêineres) nos dois namespaces.
  • O administrador do cluster também configura ClusterRoles e ClusterRoleBinidngs.

Um repositório raiz hierárquico do Config Sync precisa incluir três subdiretórios: cluster/, namespaces/ e system/.

O diretório cluster/ contém configurações que se aplicam a clusters inteiros (como ClusterRole, ClusterRoleBinding) e não a namespaces.

O diretório namespaces/ contém configs para os objetos de namespace e os objetos com escopo de namespace. Cada subdiretório em namespaces/ inclui as configurações de um objeto de namespace e todos os objetos com escopo de namespace no namespace. O nome de um subdiretório precisa ser igual ao nome do objeto de namespace. Os objetos com escopo de namespace que precisam ser criados em cada namespace podem ser colocados diretamente em namespaces/ (por exemplo, namespaces/limit-range.yaml).

O diretório system/ contém configurações para o Config Sync Operator.

├── cluster
│   ├── clusterrolebinding-namespace-reader.yaml
│   ├── clusterrole-namespace-reader.yaml
│   ├── clusterrole-secret-admin.yaml
│   └── clusterrole-secret-reader.yaml
├── namespaces
│   ├── limit-range.yaml
│   ├── team-1
│   │   ├── namespace.yaml
│   │   ├── network-policy-default-deny-egress.yaml
│   │   ├── resource-quota-pvc.yaml
│   │   ├── rolebinding-secret-reader.yaml
│   │   └── sa.yaml
│   └── team-2
│       ├── namespace.yaml
│       ├── network-policy-default-deny-all.yaml
│       ├── resource-quota-pvc.yaml
│       ├── rolebinding-secret-admin.yaml
│       └── sa.yaml
├── README.md
└── system
    └── repo.yaml

Usar herança de namespace e namespaces abstratos

Com uma fonte de verdade hierárquica, é possível usar o conceito de herança de namespace para aplicar automaticamente configurações a grupos de namespaces em todos os clusters em que esses namespaces existem (ou deveriam existir).

A herança de namespace se aplica ao diretório namespaces/ do repositório hierárquico e a todos os subdiretórios dele. As configurações em outros diretórios no repositório, como cluster/, não estão sujeitas à herança.

Em uma fonte de verdade hierárquica, o diretório namespaces/ pode conter dois tipos diferentes de subdiretórios:

  • Um diretório de namespace contém uma configuração de um namespace. O nome do arquivo que contém a configuração não é importante, mas essa configuração precisa conter kind: Namespace. Um diretório de namespace também pode conter configs para outros tipos de objetos do Kubernetes. Um diretório de namespace não pode conter subdiretórios. Uma configuração de namespace representa um namespace real em um cluster.

  • Um diretório de namespace abstrato que contém diretórios de namespace. Ele também pode conter configurações para outros objetos do Kubernetes, mas não pode conter diretamente uma configuração para um namespace. Um diretório de namespace abstrato não representa um objeto em um cluster do Kubernetes. Já os diretórios de namespace descendente, sim.

Para ajudar a garantir que o namespace e as fontes de namespaces abstratos tenham o tipo correto de configurações e estrutura, informe o erro KNV1003: IllegalNamespaceSubdirectoryErrorquando houver um problema.

As configurações em um diretório de namespace aplicam-se apenas a esse namespace. Já as configurações em um diretório de namespace abstrato são aplicadas a todos os diretórios de namespaces descendentes do namespace abstrato ou aos descendentes que correspondem ao NamespaceSelector da configuração, se houver.

A herança de uma configuração no diretório namespaces/ é baseada em grande parte na localização dela na árvore de diretórios da fonte da verdade. Para entender quais configurações estão sendo aplicadas a um determinado namespace em um determinado cluster, procure o repositório de exemplos de herança de namespace.

Namespace restrito

config-management-system é um namespace restrito. Não é possível usá-lo como um diretório de namespace abstrato. É possível definir um namespace config-management-system, mas o único tipo de recurso permitido para o namespace config-management-system é RootSync.

Fazer mudanças na sua fonte da verdade

Quando você faz uma mudança na sua fonte da verdade que cria ou exclui diretórios de namespace no diretório namespaces/, pode receber resultados inesperados, dependendo da ação:

  • Criação de um diretório: quando uma hierarquia namespaces/ válida é confirmada na fonte de verdade, o Config Sync cria namespaces e, em seguida, gera objetos do Kubernetes nesses namespaces para cada configuração que o diretório de namespace contém ou herda.
  • Excluir um diretório: excluir um diretório de namespace é uma operação destrutiva. O namespace e o conteúdo dele são excluídos em todos os clusters gerenciados pelo Config Sync em que o namespace existe. Se você excluir um diretório de namespace abstrato com diretórios de namespaces descendentes, todos esses namespaces e seus respectivos conteúdos serão removidos de todos os clusters gerenciados pelo Config Sync.

  • Renomear um diretório: renomear um diretório de namespace é uma exclusão, seguida por uma criação, e é considerada uma operação destrutiva. Renomear um diretório de namespace abstrato não tem efeito visível externamente.

  • Mover um diretório: mover um namespace ou um diretório de namespace abstrato em namespaces/ não exclui o namespace nem os objetos nele. No entanto, isso não é aplicável quando o namespace começa ou para de herdar uma configuração de um diretório de namespace abstrato devido a uma alteração na hierarquia.

A seguir