Validação descomplicada no cluster Kubernetes: conheça as Validating Admission Policies

Para usar esse recurso, são necessários dois componentes principais:

1. ValidatingAdmissionPolicy — define a política de falha, os matches de requisições e as expressões de validação CEL. Ou seja, a política em si
2. ValidatingAdmissionPolicyBinding — define o escopo da política; vincula a política a um conjunto de recursos correspondentes

Embora esse recurso esteja em Alfa desde a v1.26, alguns recursos só aparecem a partir da v1.27 ( audit annotation, validation actions), então todos os manifestos a seguir foram testados em um cluster Kubernetes rodando v1.27.1 (com recursos alfa e o feature gate ValidatingAdmissionPolicy habilitados).

Todos os exemplos deste post também estão disponíveis em um repositório no GitHub criado para esse fim.

O primeiro exemplo vem direto da documentação. Vamos criar e usar o namespace demo para rodar todos os exemplos deste post:

$ echo 'apiVersion: v1
kind: Namespace
metadata:
  labels:
    environment: demo
  name: demo' | k apply -f-
namespace/demo created

$ k config set-context --current --namespace demo

Em seguida, vamos criar uma política que impede que Deployments tenham mais de cinco réplicas:

apiVersion: admissionregistration.k8s.io/v1alpha1
kind: ValidatingAdmissionPolicy
metadata:
 name: "demo-policy.example.com"
spec:
 failurePolicy: Fail
 matchConstraints:
   resourceRules:
     - apiGroups:   ["apps"]
       apiVersions: ["v1"]
       operations:  ["CREATE", "UPDATE"]
       resources:   ["deployments"]
 validations:
   - expression: "object.spec.replicas <= 5"

O campo failurePolicy aceita os seguintes valores:

• Fail significa que um erro ao chamar o ValidatingAdmissionPolicy faz com que a admissão falhe e a requisição da API seja rejeitada.
• Ignore significa que um erro ao chamar o ValidatingAdmissionPolicy é ignorado e a requisição da API segue adiante.

O campo matchConstraints é usado para fazer o match das requisições recebidas e está configurado para que a política se aplique apenas a requisições da API para Deployments na API apps/v1, e somente em requisições CREATE ou UPDATE de Deployment.

Por fim, o campo validations contém as expressões CEL que serão executadas contra as requisições correspondentes da API. Todas as expressões precisam ser avaliadas como true para que a requisição seja admitida.

Vamos criar o seguinte binding para concluir a configuração:

apiVersion: admissionregistration.k8s.io/v1alpha1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: "demo-binding-test.example.com"
spec:
  policyName: "demo-policy.example.com"
  validationActions: [Deny]
  matchResources:
    namespaceSelector:
      matchLabels:
        environment: demo

Estamos vinculando a política criada anteriormente a qualquer namespace que tenha a label environment=demo definida — isso é útil para configurar onde queremos aplicar a validação da política.

Existem outras opções para fazer o match de namespaces, como matchExpressions, para correspondências mais granulares, além de outras opções de configuração: excludeResourceRules para excluir determinados recursos e objectSelector para corresponder a determinados objetos (não recomendado, já que os desenvolvedores podem omitir uma label para escapar da auditoria). Vou abordar as opções mais interessantes em exemplos posteriores.

Depois que esses manifestos forem aplicados ao cluster, tentar criar um novo Deployment que viole a política gera um erro, como esperado:

$ k create deployment nginx — image=nginx — replicas=10
error: failed to create deployment: deployments.apps "nginx" is forbidden: ValidatingAdmissionPolicy 'demo-policy.example.com' with binding 'demo-binding-test.example.com' denied request: failed expression: object.spec.replicas <= 5

Isso também funciona ao tentar fazer um diff do recurso:

$ k create deployment nginx --image=nginx --replicas=10 --dry-run=client -oyaml | k diff -f -
The deployments "nginx" is invalid: : ValidatingAdmissionPolicy 'demo-policy.example.com' with binding 'demo-binding-test.example.com' denied request: failed expression: object.spec.replicas <= 5

Múltiplas expressões de validação

Às vezes você quer aplicar várias validações em um mesmo recurso. Veja, por exemplo, as seguintes expressões de validação para Deployments:

apiVersion: admissionregistration.k8s.io/v1alpha1
kind: ValidatingAdmissionPolicy
metadata:
  name: "demo-policy.example.com"
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      - apiGroups:   ["apps"]
        apiVersions: ["v1"]
        operations:  ["CREATE", "UPDATE"]
        resources:   ["deployments"]
  validations:
    # Deployments can't have more than 3 replicas
    - expression: "object.spec.replicas <= 3"
    # Deployment containers must be using images hosted in europe-west1 Artifact Registry in project test-eyal
    - expression: "object.spec.template.spec.containers.all(c, c.image.startsWith('europe-west1-docker.pkg.dev/test-eyal/'))"
    # Deployment cannot use emptyDir volumes
    - expression: "!has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(v, !has(v.emptyDir))"

Um Deployment correspondente a essa política precisará ter todas as expressões avaliadas como true para ser admitido no cluster.

Vale notar que as validações são executadas sequencialmente. Se uma expressão falhar, ela retorna a falha ao cliente na hora — ou seja, se o seu recurso violar mais de uma expressão de validação, será um processo iterativo: ser negado, corrigir a violação e tentar de novo.

Personalize a mensagem de validação

Também é possível fornecer uma message customizada para retornar ao cliente em caso de falha na validação. Você pode até fazer interpolação, se necessário, usando uma messageExpression. Uma message expression tem acesso a object, oldObject, request e params.

Vamos atualizar nossa última política com mensagens customizadas no lugar dos comentários:

apiVersion: admissionregistration.k8s.io/v1alpha1
kind: ValidatingAdmissionPolicy
metadata:
  name: "demo-policy.example.com"
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      - apiGroups:   ["apps"]
        apiVersions: ["v1"]
        operations:  ["CREATE", "UPDATE"]
        resources:   ["deployments"]
  validations:
    - expression: "object.spec.replicas <= 3"
      messageExpression: "'Deployments cannot have more than 3 replicas, this one has ' + string(object.spec.replicas)"
    - expression: "object.spec.template.spec.containers.all(c, c.image.startsWith('europe-west1-docker.pkg.dev/test-eyal/'))"
      message: "Deployment containers must be using images hosted in europe-west1 Artifact Registry in project test-eyal"
    - expression: "!has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(v, !has(v.emptyDir))"
      messageExpression: "'Deployment cannot use emptyDir volumes, change the following volume: ' + object.spec.template.spec.volumes.filter(v, has(v.emptyDir)).map(v, v.name)[0]"

Importante: qualquer valor interpolado no campo messageExpression precisa ser do tipo string, caso contrário a mensagem retorna um erro pela falha na avaliação.

Sem uma mensagem customizada, um deployment com volume emptyDir teria falhado com a seguinte mensagem:

The deployments "nginx" is invalid: : ValidatingAdmissionPolicy ‘demo-policy.example.com’ with binding ‘demo-binding-test.example.com’ denied request: failed expression: !has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(v, !has(v.emptyDir))

Isso pode ficar meio difícil de entender do lado do cliente. Já com a expressão de mensagem customizada, teríamos:

The deployments "nginx" is invalid: : ValidatingAdmissionPolicy ‘demo-policy.example.com’ with binding ‘demo-binding-test.example.com’ denied request: Deployment cannot use emptyDir volumes, change the following volumes: test

Note que estou usando uma messageExpression em vez de uma message comum nessa validação só para mostrar o poder da CEL. O fato de você poder fazer algo nem sempre significa que deveria!

• Validating Admission Policies in Kubernetes: Advanced Use Cases
• Repositório no GitHub validating-admission-policy-playground com exemplos completos e funcionais para Validating Admission Policies
• Validating Admission Policy na documentação oficial do Kubernetes
• Common Expression Language no Kubernetes
• Kubernetes Enhancement Proposal (KEP)-3488 CEL para Admission Control
• Palestra The Path to Self Contained CRDs, por Cici Huang