Instalar o controlador de hierarquia

Beta

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O controlador de hierarquia permite organizar namespaces do Kubernetes em hierarquias, aplicar políticas a eles (como RBAC e cotas de recursos hierárquicos), e observar as cargas de trabalho de namespaces relacionados.

Nesta página, mostramos como instalar, configurar e desinstalar o controlador de hierarquia.

Antes de começar

Antes de começar, veja se você realizou as seguintes tarefas:

• Instale e inicialize a Google Cloud CLI, que fornece os comandos gcloud e kubectl usados nestas instruções. Se você usa o Cloud Shell, a Google Cloud CLI já vem pré-instalada.

• Ter um cluster executando a versão 1.16.x ou superior do Kubernetes.

O controlador de hierarquia foi projetado para funcionar em conjunto com o Config Sync e permite gerenciar namespaces e políticas hierárquicos em um repositório Git. Se você optar por fazer isso, recomendamos que selecione um repositório não estruturado ao instalar o Config Sync, que permite organizar o repositório da maneira que você preferir, mantendo os benefícios das políticas hierárquicas. Por outro lado, um repositório hierárquico pode entrar em conflito com o controlador de hierarquia. Não é recomendável usar os dois juntos.

Como alternativa, é possível instalar o controlador de hierarquia sem configurar um repositório do Config Sync. Os namespaces hierárquicos podem ser totalmente definidos no cluster usando a API Kubernetes. Se você não pretende usar o Git, não é necessário conceder acesso ao operator acesso ao Git, nem configurá-lo de qualquer outra forma, exceto conforme descrito na seção a seguir.

Ativar o controlador de hierarquia

Siga estas etapas de configuração do Config Sync para instalar o controlador de hierarquia.

Observação: o controlador de hierarquia não é compatível com clusters do Autopilot.

gcloud

Observação: o formato de arquivo do comando apply da CLI gcloud foi alterado na versão 1.8.0. Atualize a CLI gcloud para a versão mais recente.

Siga estas etapas de configuração do Config Sync para instalar o controlador de hierarquia, incluindo todos os componentes opcionais. Se você não quiser ativar a observabilidade hierárquica ou as cotas de recursos hierárquicos, insira um comentário nas linhas indicadas.

1. (Opcional) Se você estiver usando clusters particulares, adicione regras de firewall aos projetos de cada cluster para permitir que os planos de controle do cluster do GKE se conectem aos webhooks do controlador de hierarquia na porta 9443:

    gcloud compute firewall-rules create allow-cluster-control-plane-tcp-9443 \
      --allow tcp:9443 \
      --network default \
      --source-ranges CONTROL_PLANE_CIDR \
      --target-tags NODE_TAG
   

   Substitua:

   • CONTROL_PLANE_CIDR: o intervalo de IP do plano de controle do cluster do GKE. Por exemplo, 172.16.0.16/28.
   • NODE_TAG: uma tag aplicada a todos os nós no cluster do GKE.

2. Defina os seguintes valores no objeto spec.hierarchyController como true no arquivo de configuração gcloud:

   # apply-spec.yaml
   
   applySpecVersion: 1
   spec:
     hierarchyController:
       # Set to true to enable hierarchical namespaces
       enabled: true
       # Comment to disable hierarchical quota:
       enableHierarchicalResourceQuota: true
       # Comment to disable hierarchical observability:
       enablePodTreeLabels: true
     # ...other fields...
   

3. Aplique o arquivo apply-spec.yaml:

    gcloud beta container fleet config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Substitua:

   • CLUSTER_NAME: adicione o cluster registrado ao qual você quer aplicar essa configuração.
   • CONFIG_YAML: adicione o caminho para seu arquivo apply-spec.yaml.
   • PROJECT_ID: adicione o ID do projeto.

   Várias cargas de trabalho são implantadas e o controlador de hierarquia se torna utilizável no cluster. Esse processo pode levar até um minuto para ser concluído.

kubectl

Siga estas etapas de configuração do Config Sync para instalar o controlador de hierarquia, incluindo todos os componentes opcionais. Se você não quiser ativar a observabilidade hierárquica ou as cotas de recursos hierárquicos, comente nas linhas indicadas.

1. (Opcional) Se você estiver usando clusters particulares, adicione regras de firewall aos projetos de cada cluster para permitir que os planos de controle do cluster do GKE se conectem aos webhooks do controlador de hierarquia na porta 9443:

    gcloud compute firewall-rules create allow-cluster-control-plane-tcp-9443 \
      --allow tcp:9443 \
      --network default \
      --source-ranges CONTROL_PLANE_CIDR \
      --target-tags NODE_TAG
   

   Substitua:

   • CONTROL_PLANE_CIDR: o intervalo de IP do plano de controle do cluster do GKE. Por exemplo, 172.16.0.16/28.
   • NODE_TAG: uma tag aplicada a todos os nós no cluster do GKE.

2. No arquivo de configuração do operador, no objeto spec.hierarchyController, defina o valor de enabled como true:

   # config-management.yaml
   
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # Set to true to enable hierarchical namespaces
     hierarchyController:
       enabled: true
       # Comment to disable hierarhical quota:
       enableHierarchicalResourceQuota: true
       # Comment to disable hierarchical observability:
       enablePodTreeLabels: true
      # ...other fields...
   

3. Aplique a configuração:

     kubectl apply -f config-management.yaml
   

   Várias cargas de trabalho são implantadas e o controlador de hierarquia se torna utilizável no cluster. Esse processo pode levar até um minuto para ser concluído.

Instalar o plug-in kubectl

É possível interagir com o controlador de hierarquia exclusivamente por meio de ferramentas de cliente do Kubernetes, como kubectl. No entanto, o Plug-in do kubectl kubectl-hns de código aberto simplifica várias tarefas. Esse plug-in faz parte do controlador de namespace hierárquico (HNC, na sigla em inglês), que é um componente do controlador de hierarquia.

Ele é distribuído pela comunidade do OSS e está disponível no momento para Linux e macOS. Para instalá-lo na estação de trabalho, consulte Instalar o plug-in kubectl na documentação do Config Sync.

Verificar a instalação

Depois de instalar o controlador de hierarquia, verifique se a instalação foi concluída com sucesso.

gcloud

Execute este comando:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto.

O resultado será semelhante a:

Name          ...other columns... Hierarchy_Controller
CLUSTER_NAME  ...other fields ... INSTALLED

Uma instalação bem-sucedida tem um status de INSTALLED na coluna Hierarchy_Controller. Pode levar vários minutos para que o status apareça depois que você ativar o Hierarchy Controller.

kubectl

Se o controlador de hierarquia estiver instalado corretamente, os pods dele serão executados. Os pods podem ser reiniciados várias vezes antes de estarem disponíveis.

Como os pods do controlador de hierarquia são executados no namespace hnc-system, é possível visualizar o status deles executando o seguinte comando:

kubectl get pods -n hnc-system

O resultado será semelhante a:

NAME                                         READY   STATUS    RESTARTS   AGE
gke-hc-controller-manager-6f4dbb484d-t8tdm   2/2     Running   1          1m
hnc-controller-manager-7b75655894-tzqvx      2/2     Running   1          1m

Fazer upgrade do controlador de hierarquia

O controlador de hierarquia é atualizado sempre que você faz upgrade do Config Sync. Para saber mais, consulte Fazer upgrade do Config Sync.

Desinstalar o controlador de hierarquia

Siga estas etapas para desinstalar o controlador de hierarquia dos clusters.

gcloud

Para desinstalar o controlador de hierarquia:

1. Edite a configuração do controlador de hierarquia no arquivo apply-spec.yaml e defina hierarchyController.enabled como false.

2. Aplique as alterações no arquivo apply-spec.yaml:

    gcloud beta container fleet config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Substitua:

   • CLUSTER_NAME: adicione o cluster registrado ao qual você quer aplicar essa configuração.
   • CONFIG_YAML: adicione o caminho para seu arquivo apply-spec.yaml.
   • PROJECT_ID: adicione o ID do projeto.

Depois que o controlador de hierarquia remover o finalizador hierarchycontroller.configmanagement.gke.io, a desinstalação está concluída.

Observação: a desinstalação do controlador de hierarquia não remove namespaces nem quaisquer objetos que foram propagados de namespaces ancestrais para os descendentes deles. No entanto, outras alterações nos objetos não serão propagadas.

kubectl

Para desinstalar o controlador de hierarquia, edite a configuração do Config Sync no arquivo config-management.yaml e defina hierarchyController.enabled como false. Depois que o Config Sync remover o finalizador hierarchycontroller.configmanagement.gke.io, a desinstalação estará concluída.

Observação: a desinstalação do controlador de hierarquia não remove namespaces nem quaisquer objetos que foram propagados de namespaces ancestrais para os descendentes deles. No entanto, outras alterações nos objetos não serão propagadas.

Se você quiser desinstalar totalmente o Config Sync, consulte Desinstalar o Config Sync de um cluster.

A seguir

• Saiba mais sobre o controlador de hierarquia
• Aplique cotas de recursos hierárquicos
• Observe cargas de trabalho hierárquicas.
• Conheça os recursos fundamentais dos namespaces hierárquicos
• Conheça os recursos avançados de namespaces hierárquicos