Installare l'operator

Obiettivo: installare l'operator AgentFlowEngine e avviare un motore da una sola custom resource.

Prerequisiti

• Un cluster su cui puoi fare kubectl apply, con un kubeconfig.
• L'immagine afe caricata o pubblicata dove il cluster può scaricarla.
• kubectl sulla tua macchina.

L'operator è limitato a un namespace e riferimento-prima. Crea e possiede gli oggetti stateless: i Deployment serve e worker, i Service, la ConfigMap di configurazione, l'Ingress e lo ScaledObject. I namespace, l'RBAC del worker, l'envSecret, i Secret dei dati e le classi di storage, runtime e ingress sono i tuoi manifest. Arrivano come esempi sotto deploy/operator/admin/.

Passi

1. Applica i tuoi manifest admin:

   kubectl apply -f deploy/operator/admin/namespace.yaml
   kubectl apply -f deploy/operator/admin/rbac.yaml
   kubectl apply -f deploy/operator/admin/env-secret.yaml
   kubectl apply -f deploy/operator/admin/data-secrets.yaml
   kubectl apply -f deploy/operator/admin/classes.yaml

   Riempi i Secret prima. Il repository committa valori vuoti, mai una credenziale. Tieni le classi che il cluster fornisce già.

2. Installa l'operator, le sue CRD e il suo RBAC:

   make operator-install        # kubectl apply -k deploy/operator
   kubectl -n afe rollout status deployment/afe-operator

3. Crea la ConfigMap sorgente dalla cartella dei flow. Un prompt deve essere testo inline o un file nella stessa ConfigMap, perché una ConfigMap non ha cartelle:

   kubectl -n afe create configmap afe-source --from-file=config/

4. Scrivi l'AgentFlowEngine e applicalo. Ogni segreto è un riferimento, mai un valore:

   apiVersion: afe.dev/v1alpha1
   kind: AgentFlowEngine
   metadata:
     name: afe
     namespace: afe
   spec:
     config:
       configMapRef:
         name: afe-source
     afe:
       store:
         external:
           secretRef:
             name: afe-postgres
             key: dsn
       broker:
         external:
           secretRef:
             name: afe-redis
             key: AFE_REDIS_URL
       sandbox:
         namespace: afe-sandbox
         envSecret: afe-sandbox-env
     deployment:
       image:
         repository: ghcr.io/agentflowengine/afe
         tag: "0.7.0"
       api:
         replicas: 2
         apiTokenSecretRef:
           name: afe-secrets
           key: AFE_API_TOKEN
       workers:
         replicas: 2
         concurrency: 4
          # La chiave del modello e il token Git restano entrambi solo al worker; serve non
          # detiene credenziali.
          envSecretRefs:
           - { name: afe-secrets, key: OPENROUTER_API_KEY }
           - { name: afe-secrets, key: GITHUB_TOKEN }

5. Guarda l'installazione diventare pronta:

   kubectl -n afe get agentflowengine afe -o wide
   kubectl -n afe get pods
   kubectl -n afe get agentflowengine afe \
     -o jsonpath='{.status.conditions[*].type}{"\n"}'

   La condition Ready è l'AND di quelle richieste. status.revision è la revisione della configurazione che i workload eseguono.

6. Raggiungi l'API. Senza un Ingress, fai il forward del Service:

   kubectl -n afe port-forward svc/afe-api 8765:8765
   export AFE_API_TOKEN=$(kubectl -n afe get secret afe-secrets \
     -o jsonpath='{.data.AFE_API_TOKEN}' | base64 -d)
   afe tickets

Risoluzione dei problemi

ConfigValidated=False L'operator non ha potuto validare la cartella costruita dalla ConfigMap e dal Runtime generato. Il messaggio della condition porta gli stessi messaggi per campo che stampa afe validate. Correggi i manifest nella ConfigMap e riapplica, oppure aggiorna la CR se l'errore è in spec.afe.

RevisionPinned=False, reason RevisionMismatch spec.config.revision non corrisponde alla revisione calcolata. L'operator nomina entrambi gli hash e non pubblica nulla, quindi i workload in esecuzione restano come sono. Metti il pin sulla revisione calcolata, oppure rimuovilo.

Ready=False, reason ResourceConflict Un oggetto con un nome desiderato esiste senza l'ownerReference dell'operator. L'operator non adotta nulla. Cancella l'oggetto estraneo, o rinominalo, poi lascia girare il reconcile successivo.

StoreReady=False, reason CloudNativePGMissing La CR chiede uno store managed ma la CRD postgresql.cnpg.io non è installata. Installa CloudNativePG, oppure passa spec.afe.store a external.

Il Pod worker va in CrashLoop con invalid configuration: model '…': set … Il worker risolve i provider dei modelli, quindi ha bisogno di ogni chiave dei modelli. Indica la chiave in deployment.workers.envSecretRefs: l'operator la proietta solo sui worker. serve non esegue alcun harness e non chiama alcun provider, quindi nessuna credenziale arriva a lui, né le chiavi dei modelli né il token Git.

Vedi anche

• Kubernetes
• Operations