Saltar para o conteúdo principal
Versão 3.0

Kyverno e registry privado

Clusters que baixam imagens de um registry privado precisam de fornecer credenciais de acesso a cada workload.
Em um ambiente com muitos componentes — como o TDP Kubernetes — repetir essa configuração manualmente em cada chart é ineficiente e gera riscos de inconsistência.

O Kyverno resolve esse problema como um policy engine de cluster: ele intercepta a criação de Pods e injeta automaticamente o imagePullSecrets necessário, com base em uma ClusterPolicy centralizada.
Dessa forma, todos os componentes passam a usar as credenciais do registry sem que cada manifest precise declará-las individualmente.

Esse ajuste é condicional: só se aplica quando o ambiente exige autenticação para baixar imagens de um registry privado.
Ambientes que usam registries públicos ou que configuram imagePullSecrets diretamente em cada chart não necessitam desta etapa.

Quando considerar este ajuste​

Considere esta configuração quando:

  • as imagens são distribuídas por um registry privado
  • o cluster precisa reutilizar as mesmas credenciais em múltiplos componentes
  • a política de plataforma exige padronização do uso de imagePullSecrets
  • se deseja centralizar a manutenção dessas credenciais

Papel do Kyverno neste contexto​

O Secret continua sendo o objeto que armazena as credenciais do registry.
O papel do Kyverno é aplicar e padronizar o uso desse Secret no cluster por meio de uma ClusterPolicy.
Assim, novos Pods criados nos namespaces configurados podem receber automaticamente a referência ao imagePullSecrets.

imagePullSecrets e namespace

O Kubernetes só utiliza um imagePullSecrets se o Secret referenciado existir no mesmo namespace do Pod.
Se o Secret tdp-registry não existir no namespace onde o Pod será criado, o download da imagem falhará mesmo com a ClusterPolicy ativa.
Crie o Secret em cada namespace TDP antes de criar os Pods nesse namespace.

Mutação afeta apenas novos Pods

A ClusterPolicy do Kyverno atua no momento da criação de Pods.
Workloads já existentes não são afetados — apenas novos Pods criados após a aplicação da policy receberão o imagePullSecrets.
Para aplicar as credenciais a workloads existentes, é necessário recriá-los (ex.: kubectl rollout restart deployment/<NAME> -n <NAMESPACE>).

Visão geral da configuração​

O fluxo é composto por três etapas:

  1. Instalar o Kyverno no cluster
  2. Criar o Secret do registry em cada namespace TDP
  3. Criar uma ClusterPolicy que injeta imagePullSecrets automaticamente nos Pods

1. Instalar o Kyverno​

Terminal input
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update
helm install kyverno kyverno/kyverno --namespace kyverno --create-namespace

2. Criar o Secret do registry em cada namespace​

Não versione o Secret com credenciais no Git

O arquivo de Secret contém credenciais de acesso ao registry em texto simples.
Nunca versione esse arquivo no repositório Git.
Gerencie as credenciais via ferramenta especializada (Sealed Secrets, External Secrets Operator, HashiCorp Vault) ou crie o Secret manualmente em cada namespace.

Crie o Secret com as credenciais do registry em cada namespace TDP onde os componentes serão instalados:

Terminal input
kubectl create secret docker-registry tdp-registry \
  --docker-server=registry.tecnisys.com.br \
  --docker-username='<USERNAME>' \
  --docker-password='<PASSWORD>' \
  -n <NAMESPACE>

Repita o comando para cada namespace TDP (ex.: tdp, tdp-kafka, tdp-airflow, etc.) ou automatize com um script de bootstrap.

Alternativa: sincronizar via Kyverno CloneSecretPolicy

O Kyverno também suporta a cópia automática de Secrets entre namespaces por meio de uma ClusterPolicy do tipo clone.
Com essa abordagem, basta criar o Secret em um namespace de origem (ex.: kyverno) e o Kyverno o replica automaticamente nos namespaces de destino.
Consulte a documentação do Kyverno para detalhes sobre generate e clone.

3. Criar a policy para injetar imagePullSecrets​

Crie um arquivo policy-kyverno.yaml:

policy-kyverno.yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: inject-tecnisys-registry-secret
  annotations:
    policies.kyverno.io/title: Inject Image Pull Secrets
    policies.kyverno.io/description: Automatically adds the Tecnisys secret to all pods.
spec:
  background: false
  rules:
    - name: inject-secret
      match:
        any:
          - resources:
              kinds:
                - Pod
      mutate:
        patchStrategicMerge:
          spec:
            imagePullSecrets:
              - name: tdp-registry

Aplique a policy:

Terminal input
kubectl apply -f policy-kyverno.yaml

Resultado esperado​

Após a aplicação da ClusterPolicy, novos Pods criados no cluster passam a receber o imagePullSecrets com o nome tdp-registry, permitindo o download das imagens privadas do registry da Tecnisys.

O Secret precisa existir no namespace do Pod para que o Kubernetes o utilize — confirme a criação do Secret em todos os namespaces TDP antes de instalar os componentes.

Onde guardar no repositório GitOps​

Versione apenas o arquivo policy-kyverno.yaml no repositório GitOps dentro de uma pasta policies/:

tdp-gitops/
├── app-of-apps.yaml
├── apps/
├── values/
└── policies/
    └── kyverno-registry.yaml

Não versione o arquivo tdp-registry.yaml com as credenciais.
Esses arquivos de policy são aplicados com kubectl apply -f, como parte do bootstrap do ambiente — não são gerenciados diretamente pelo Argo CD como Applications.

Bootstrap vs. Argo CD

Os manifests da pasta policies/ são aplicados uma vez, durante o bootstrap do ambiente.
Eles não precisam ser gerenciados por uma Application do Argo CD, mas podem ser se houver uma Application de plataforma responsável pela gestão de políticas do cluster.