Usar um repositório hierárquico

Nesta página, descrevemos como o Config Sync lê configs de uma fonte de verdade hierárquica e aplica a configuração resultante aos clusters automaticamente.

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

Para entender como o Config Sync usa um repositório hierárquico, é útil conhecer os repositórios do Git e a interface de linha de comando git.

Estrutura do diretório

No caso de origens hierárquicas, o Config Sync aproveita estruturas semelhantes a sistemas de arquivos e usa o diretório para determinar para quais clusters ou namespaces um config é 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 da verdade

A estrutura de diretórios a seguir demonstra como usar uma fonte hierárquica de verdade 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 alocações de recursos (para pods ou contêineres) nos dois namespaces.
  • O administrador do cluster também configura ClusterRoles e ClusterRoleBindings.

Uma fonte hierárquica válida 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 ConfigManagement 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 hierárquica de verdade, é 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 eles 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 hierárquica de verdade, 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 garantir que o namespace e as origens de namespaces abstratos tenham o tipo correto de configurações e estrutura, o erro KNV1003: IllegalNamespaceSubdirectoryError informa quando há um problema.

As configurações em um diretório de namespace só se aplicam a esse namespace. No entanto, 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 a NamespaceSelector de uma 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 na 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.

Fazendo mudanças em sua fonte de informações

Ao fazer uma mudança na sua fonte de verdade que cria ou exclui diretórios de namespace do diretório namespaces/, você 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 cria objetos do Kubernetes nesses namespaces para cada configuração que o diretório de namespace contém ou herda.
  • Exclusão de um diretório: a exclusão de 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 que contém diretórios de namespaces descendentes, todos esses namespaces e os respectivos conteúdos serão excluídos 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 ou os objetos dentro dele, exceto quando o namespace começa ou para de herdar uma configuração de um diretório de namespace abstrato devido a uma mudança na hierarquia.

A seguir