Scrivi un modello di vincolo personalizzato

Questa pagina mostra come scrivere un modello di vincolo personalizzato e utilizzarlo per estendere Policy Controller se non riesci a trovare un modello di vincolo precompilato che soddisfi le tue esigenze.

I criteri di Policy Controller sono descritti mediante l'OPA Constraint Framework e sono scritti in Rego. Un criterio può valutare qualsiasi campo di un oggetto Kubernetes.

La scrittura dei criteri con Rego è una competenza specializzata. Per questo motivo, per impostazione predefinita è installata una libreria di modelli di vincoli comuni. Probabilmente puoi richiamare questi modelli di vincoli durante la creazione di vincoli. Se hai esigenze specifiche, puoi creare modelli di vincoli personalizzati.

I modelli di vincolo consentono di separare la logica di un criterio dai requisiti specifici per riusare e delegare. Puoi creare vincoli utilizzando modelli di vincoli sviluppati da terze parti, quali progetti open source, fornitori di software o esperti di normative.

Prima di iniziare

Esempio di modello di vincolo

Di seguito è riportato un esempio di modello di vincolo che nega tutte le risorse il cui nome corrisponde a un valore fornito dall'autore del vincolo. Il resto di questa pagina tratta i contenuti del modello, evidenziando concetti importanti durante il processo.

Se utilizzi Config Sync con un repository gerarchico, ti consigliamo di creare i vincoli nella directory cluster/.

apiVersion: templates.gatekeeper.sh/v1beta1
kind: ConstraintTemplate
metadata:
  name: k8sdenyname
spec:
  crd:
    spec:
      names:
        kind: K8sDenyName
      validation:
        # Schema for the `parameters` field
        openAPIV3Schema:
          properties:
            invalidName:
              type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8sdenynames
        violation[{"msg": msg}] {
          input.review.object.metadata.name == input.parameters.invalidName
          msg := sprintf("The name %v is not allowed", [input.parameters.invalidName])
        }

Vincolo di esempio

Di seguito è riportato un vincolo di esempio che potresti implementare per negare tutte le risorse denominate policy-violation:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sDenyName
metadata:
  name: no-policy-violation
spec:
  parameters:
    invalidName: "policy-violation"

Parti di un modello di vincolo

I modelli di vincolo sono costituiti da due parti importanti:

  • Lo schema del vincolo che vuoi che venga creato dagli utenti. Lo schema di un modello di vincolo viene archiviato nel campo crd.

  • Il codice sorgente di reCAPTCHA che viene eseguito quando viene valutato il vincolo. Il codice sorgente di reCAPTCHA per un modello viene archiviato nel campo targets.

Schema (campo crd)

Il campo CRD è un progetto per la creazione della definizione di risorse personalizzate Kubernetes, che definisce la risorsa vincolo per il server API Kubernetes. Devi solo compilare i seguenti campi.

Campo Descrizione
spec.crd.spec.names.kind Il tipo di vincolo. Se è minuscolo, il valore di questo campo deve essere uguale a metadata.name.
spec.crd.spec.validation.openAPIV3Schema

Lo schema per il campo spec.parameters della risorsa vincolo (Policy Controller definisce automaticamente il resto dello schema del vincolo). Segue le stesse convenzioni di una normale risorsa CRD.

L'aggiunta del nome K8s al modello di vincolo è una convenzione che consente di evitare collisioni con altri tipi di modelli di vincolo, ad esempio i modelli Forseti che hanno come target le risorse Google Cloud.

Ripeti codice sorgente (campo targets)

Le sezioni seguenti forniscono ulteriori informazioni sul codice sorgente di Rego.

Località

Il codice sorgente di Rego viene archiviato nel campo spec.targets, dove targets è un array di oggetti nel seguente formato:

{"target": "admission.k8s.gatekeeper.sh","rego": REGO_SOURCE_CODE, "libs": LIST_OF_REGO_LIBRARIES}
  • target: indica a Policy Controller quale sistema stiamo esaminando (in questo caso Kubernetes); è consentita una sola voce in targets.
  • rego: il codice sorgente per il vincolo.
  • libs: un elenco facoltativo di librerie di Rego code reso disponibile per il modello di vincolo, allo scopo di semplificare l'utilizzo delle librerie condivise e non rientra nell'ambito di questo documento.

Codice sorgente

Di seguito è riportato il codice sorgente di Rego per il vincolo precedente:

package k8sdenynames

violation[{"msg": msg}] {
   input.review.object.metadata.name == input.parameters.invalidName
   msg := sprintf("The name %v is not allowed", [input.parameters.invalidName])
}

Tieni presente quanto segue:

  • package k8sdenynames è richiesto dall'OPA (runtime di Rego). Il valore viene ignorato.
  • La regola di ripetizione che Policy Controller richiama per verificare se ci sono violazioni è denominata violation. Se questa regola ha delle corrispondenze, si è verificata una violazione del vincolo.
  • La regola violation ha la firma violation[{"msg": "violation message for the user"}], dove il valore di "msg" è il messaggio di violazione che viene restituito all'utente.
  • I parametri forniti al vincolo sono resi disponibili nella parola chiave input.parameters.
  • request-under-test viene memorizzato nella parola chiave input.review.

La parola chiave input.review ha i seguenti campi.

Campo Descrizione
uid L'ID univoco di questa richiesta specifica; non è disponibile durante l'audit.
kind

Le informazioni su Kind per object-under-test. Il formato è il seguente:

  • kind: il tipo di risorsa
  • group: gruppo di risorse
  • version: la versione della risorsa
name Nome della risorsa. Potrebbe essere vuoto se l'utente fa affidamento sul server API per generare il nome su una richiesta CREATE.
namespace Lo spazio dei nomi della risorsa (non fornito per le risorse con ambito cluster).
operation L'operazione richiesta (ad esempio CREATE o UPDATE); non è disponibile durante l'audit.
userInfo

Dati dell'utente che ha inviato la richiesta; non sono disponibili durante il controllo. Ha il seguente formato:

  • username: l'utente che ha effettuato la richiesta
  • uid: l'UID dell'utente
  • groups: un elenco di gruppi di cui l'utente è membro
  • extra: eventuali informazioni utente aggiuntive fornite da Kubernetes
object L'oggetto che l'utente sta tentando di modificare o creare.
oldObject Lo stato originale dell'oggetto; è disponibile solo per le operazioni UPDATE.
dryRun Se questa richiesta è stata richiamata con kubectl --dry-run; non è disponibile durante il controllo.

Scrivi modelli di vincoli referenziali

I modelli di vincoli referenziali sono modelli che consentono all'utente di limitare un oggetto rispetto ad altri. Un esempio potrebbe essere "Non consentire la creazione di un pod prima che esista un Ingress corrispondente". Un altro esempio potrebbe essere "non consentire a due servizi di avere lo stesso nome host".

Policy Controller consente di scrivere vincoli referenziali controllando il server API per un insieme di risorse fornite dall'utente. Quando una risorsa viene modificata, Policy Controller la memorizza nella cache localmente in modo che sia possibile farvi riferimento facilmente dal codice sorgente di Rego. Policy Controller rende disponibile questa cache per la parola chiave data.inventory.

Le risorse con ambito cluster vengono memorizzate nella cache nella seguente posizione:

data.inventory.cluster["GROUP_VERSION"]["KIND"]["NAME"]

Ad esempio, un nodo denominato my-favorite-node potrebbe essere trovato in

data.inventory.cluster["v1"]["Node"]["my-favorite-node"]

Le risorse con ambito di spazio dei nomi vengono memorizzate nella cache qui:

data.inventory.namespace["NAMESPACE"]["GROUP_VERSION"]["KIND"]["NAME"]

Ad esempio, un ConfigMap denominato production-variables nello spazio dei nomi shipping-prod potrebbe essere trovato in

data.inventory.namespace["shipping-prod"]["v1"]["ConfigMap"]["production-variables"]

L'intero contenuto dell'oggetto è archiviato in questa posizione della cache e può essere consultato nel codice sorgente di Rego come si ritiene opportuno.

Ulteriori informazioni su Rego

Le informazioni precedenti forniscono le funzionalità uniche di Policy Controller che semplificano la scrittura di vincoli sulle risorse Kubernetes in Rego. Un tutorial completo su come scrivere in Rego non rientra nell'ambito di questa guida. Tuttavia, la documentazione di Apri Policy Agent contiene informazioni sulla sintassi e sulle funzionalità del linguaggio Rego stesso.

Installa il modello di vincolo

Dopo aver creato il modello di vincolo, usa kubectl apply per applicarlo e Policy Controller si occupa di importarlo. Assicurati di controllare il campo status del modello di vincolo per assicurarti che non siano presenti errori che lo confermano. Una volta completata l'importazione, il campo status dovrebbe mostrare created: true, mentre il valore observedGeneration indicato nel campo status deve essere uguale al campo metadata.generation.

Dopo aver importato il modello, puoi applicare i vincoli come descritto in Creazione di vincoli.

Rimuovi un modello di vincolo

Per rimuovere un modello di vincolo, completa i seguenti passaggi:

  1. Verifica che nessun vincolo che vuoi conservare utilizzi il modello di vincoli:

    kubectl get TEMPLATE_NAME
    

    Se esiste un conflitto di denominazione tra il nome del modello di vincolo e un oggetto diverso nel cluster, utilizza il comando seguente:

    kubectl get TEMPLATE_NAME.constraints.gatekeeper.sh
    
  2. Rimuovi il modello di vincolo:

    kubectl delete constrainttemplate CONSTRAINT_TEMPLATE_NAME
    

Quando rimuovi un modello di vincolo, non puoi più creare vincoli che vi fanno riferimento.

Passaggi successivi