FC Agent — private infrastructuur

De FC Agent is een kleine service die je in je eigen omgeving draait — doorgaans als één pod in je Kubernetes-cluster. Hij verbindt uitgaand met FixControl over HTTPS en voert getekende, aflopende, single-use operaties uit: een gepauzeerde CI-deployment goedkeuren of afwijzen, een gepauzeerde Argo-rollout promoten, of een validatie in je cluster draaien.

FixControl verbindt met private klantinfrastructuur via deze uitgaande agent. Kubernetes, Argo, Jenkins en GitLab hoeven niet publiek te worden blootgesteld aan FixControl.

De agent wordt aangeboden als onderdeel van pilot-onboarding: FixControl levert het installatiepakket, de agent-identiteit en de signing keys bij enrolment, en de opzet wordt samen met je team gevalideerd.

Architectuur

        FixControl Cloud
        (poorten, goedkeuringen, bewijs, audit)
                 ▲
                 │  uitgaand HTTPS (geïnitieerd door de agent)
                 │
             FC Agent          ← draait in jouw omgeving
            /    |    \
           /     |     \
   Kubernetes   Argo   Jenkins / GitLab
   (privé — geen van deze wordt blootgesteld aan FixControl)

De agent pollt FixControl met een kort, door de server geadverteerd interval. Er is geen push-kanaal, geen listener, geen inkomende socket: het manifest van de agent bevat geen Service, geen Ingress en geen inkomende network policy, en zijn health-endpoint bindt op localhost.
FixControl registreert een operatie — het verdict van een besliste poort, of een verzoek om een validatie te draaien. De agent haalt haar op bij zijn volgende poll, verifieert lokaal, voert uit, en meldt het resultaat terug — ook uitgaand. Elk uitvoerings-verdict (goedkeuren, afwijzen, promoten) is een vastgelegde menselijke beslissing.
Onder het agent-verbindingsmodel opent FixControl geen enkele verbinding richting je netwerk en bewaart het geen credential voor je infrastructuur.

Vereisten

Een Kubernetes-cluster (de agent draait als Deployment; het installatiepakket bestaat uit gewone Kubernetes-manifests gerenderd met Kustomize — geen Helm nodig).
Uitgaand HTTPS vanuit de agent-namespace naar FixControl (doorgaans poort 443), via je bestaande egress- of proxyregels.
De Kubernetes-integratie eerst verbonden — een agent-registratie hangt aan die verbinding, en enrolment weigert zonder.
Een ge-enrolde agent-identiteit: aangemaakt onder Settings → DevOps → fc-agents (of POST /api/integrations/devops/agents). Enrolment toont het agent-secret één keer en somt de te pinnen FixControl-signing-keys op.
De capability gearmd: agent-carriage staat uit totdat een admin Hand the verdict to an fc-agent armt onder Settings → Governance → Approvals → Deployment capabilities. Armen vraagt een reden en wordt ge-audit; ontwapenen is één klik. Tot het gearmd is, openen poorten en worden beslissingen vastgelegd, maar wordt er niets voor de agent geregistreerd.

Netwerk

De egress van de agent, volledig:

sta egress toe  agent-namespace → FixControl (HTTPS, 443)
                                   (voor de hosted dienst: api.fixcontrol.ai —
                                    het enrolment-paneel toont de exacte URL als
                                    "FixControl URL")
                agent-namespace → je manifests-git-remote
                                   (alleen met het standaard GitOps-promotiepad)
                agent-namespace → je private GitLab / Jenkins
                                   (alleen met CI-verdict-carriage)
                agent-namespace → kube-apiserver + cluster-DNS
                                   (de NetworkPolicy van de installer voegt deze
                                    zelf toe)
benodigde inkomende regels: geen

Het pipeline-event bereikt FixControl nog steeds via de eigen signed webhook van de CI-host — de agent draagt het verdict terug, niet het event naar binnen. Een private CI-host heeft dus zelf ook uitgaand HTTPS naar FixControl nodig (of een proxy die dat levert).

De agent weigert te starten tegen een onversleutelde http://-FixControl-URL. TLS wordt geverifieerd; er is bewust geen optie om TLS-verificatie over te slaan.
Standaard egress-proxy's werken zolang de agent de FixControl-origin kan bereiken; de operatie-handtekening dekt het request-pad, dus tussenstations kunnen een request niet ongemerkt omleiden.
Het eigen health-/metrics-endpoint van de agent bindt op 127.0.0.1 en wordt in de pod geprobed.

Authenticatie en operatie-ondertekening

Twee onafhankelijke mechanismen, met twee onafhankelijke sleutels:

Transportauthenticatie — elk request van de agent draagt een HMAC-SHA256-handtekening onder het eigen per-agent-secret, plus een tijdstempel met een begrensd skew-venster. Het secret wordt één keer getoond bij enrolment, door FixControl alleen versleuteld opgeslagen, en is op elk moment te roteren of in te trekken; intrekking werkt vanaf het eerstvolgende request.
Operatie-autoriteit — elke operatie wordt door FixControl getekend met een Ed25519-sleutel waarvan jij de publieke helft in de configuratie van de agent pint. De agent bevat geen signing-code voor deze sleutel — hij kan operaties verifiëren, nooit zelf uitgeven. Een gepinde agent weigert operaties die anders getekend zijn, zodat de bevoegdheid om een actie op te dragen cryptografisch gescheiden is van de mogelijkheid om met de API te praten.

Levenscyclus van een operatie

Elke operatie is single-use, aflopend en idempotent:

Vervaltijd — operaties verlopen minuten na registratie (standaard 5). Een goedkeuring van 10:00 kan nooit om 16:00 nog iets promoten omdat een agent plat lag; de verlopen operatie wordt zichtbaar als verlopen vastgelegd.
Replay-bescherming — elke operatie draagt een willekeurige nonce. De agent houdt een persistent nonce-grootboek bij in zijn eigen namespace en weigert een nonce die hij al zag, met terugmelding en reden replay in plaats van een stille drop.
Idempotente afhandeling — een operatie wordt één keer afgehandeld. Een strijdig tweede resultaat wordt als conflict vastgelegd en herschrijft het eerste niet.
Geadresseerd, niet uitgezonden — een operatie noemt één cluster en één capability, en CI-verdicts zijn bovendien gepind op de specifieke agent die op de koppeling staat. De pin reist binnen de handtekening mee.

Capabilities en lokale allowlists

Het operatie-vocabulaire is gesloten: een CI-deployment goedkeuren/afwijzen, een Argo-rollout promoten/afbreken/lezen, een validatie draaien/annuleren. Er bestaat geen "voer dit commando uit"-operatie.

Wat een agent werkelijk mag uitvoeren wordt op drie plekken bepaald, en de laatste is volledig van jou:

De registratie in FixControl kent de agent een capability-set toe.
Elke poll doorsnijdt die toekenning met wat de draaiende agent adverteert — geen van beide kanten kan de andere verbreden.
De lokale allowlists van de agent (FC_ALLOWED_NAMESPACES, FC_ALLOWED_ROLLOUTS en de FC_AGENT_CAPABILITIES-schakelaarset) leven in de configuratie in jouw cluster. FixControl stuurt ze nooit mee en kan ze niet overschrijven. Een lege namespace-allowlist betekent dat niets is toegestaan — de installer weigert een installatie die haar per ongeluk leeg laat.

Kubernetes-permissies (RBAC)

De agent draait onder een minimale Role, en validatie draait onder een apart ServiceAccount:

Agent — get/list op Argo Rollouts in de namespaces die jij toestaat, plus get/update op precies één benoemde ConfigMap (zijn nonce-grootboek). Standaard heeft hij helemaal geen schrijfrechten op rollouts: het standaard-promotiepad is een GitOps-markercommit die je eigen in-cluster tooling verifieert en toepast. De pod is gehard (non-root, read-only root filesystem, alle capabilities gedropt, digest-gepinde images).
Validatie-runner — een apart ServiceAccount in een eigen namespace dat kortlevende testnamespaces, deployments, services en jobs aanmaakt, en Argo-resources helemaal niet kan bereiken. Een ValidatingAdmissionPolicy (afgedwongen door de API-server, standaard toegepast door de installer) weigert elke schrijfactie van deze identiteit buiten de eigen fc-test-*-namespaces.

Compromittering van het onderdeel dat testcode draait mag nooit rollout-controle opleveren — daarom zijn het twee identiteiten.

Argo- en CI-connectiviteit

Argo Rollouts — de agent observeert rollout-status en promoot, na een goedgekeurde poort, via het geconfigureerde pad. De standaard is een GitOps-markercommit die je eigen promotietooling tegen de live rollout verifieert; de agent directe rollout-API-toegang geven is een aparte keuze die standaard uit staat.
Jenkins / GitLab (privé) — de CI-credential leeft in een secret in jouw cluster, bewust gescheiden van de FixControl-identiteit van de agent, zodat beide onafhankelijk roteren. De operatie-envelop voor CI-verdicts bevat geen doel-URL — de agent praat alleen met het CI-hostadres dat aan jouw kant is geconfigureerd, zodat een gecompromitteerde cloud de agent niet naar een willekeurig intern adres kan sturen.
Wat een poort per CI-host precies doet staat in DevOps & CI/CD.

Secrets

Secret	Leeft	Geroteerd door
Agent-transportsecret	Jouw cluster + versleuteld in FixControl	Jij, via rotatie (één keer getoond)
FixControl-signing-keys (publiek)	Gepind in de agent-configuratie	Bijgewerkt bij enrolment/rotatie
Kubernetes-toegang	Het in-cluster ServiceAccount van de agent	Kubernetes
GitLab-/Jenkins-credential	Een secret in jouw cluster	Jij
Secrets voor validatieruns	Verwezen bij naam; koppelingen worden tijdens pilot-onboarding zo ingericht dat waarden in jouw cluster blijven	Jij

Secret-waarden voor validatieruns verschijnen nooit in FixControls opslag, operatie-payloads, logs of bewijs.

Bewijs en health

Elk operatieresultaat — succes, falen, weigering, verval — wordt teruggemeld en sluit in één audittrail aan op de goedkeuring die het veroorzaakte.
Agent-connectiviteit is een volwaardige health-capability: een gemiste heartbeat verschijnt binnen minuten als gedegradeerd, per agent, in plaats van zich te verschuilen achter een generieke "connected"-status.
Validatieruns rapporteren hetzelfde bewijscontract als FixControls geïsoleerde Docker-validatie: omgevingshash, image-digests, uitgevoerd plan, resultaat. Zie Change-validatie.

Faalgedrag

FixControl onbereikbaar — je workloads blijven draaien; de agent haalt simpelweg geen nieuwe operaties op. Tijdelijke fouten worden met backoff opnieuw geprobeerd, elke poging opnieuw getekend met een verse tijdstempel; permanente (4xx-)fouten worden niet blind herhaald.
Agent plat — openstaande operaties verlopen zichtbaar; de goedkeuring op de poort blijft vastgelegd, en de tijdlijn toont dat uitvoering niet plaatsvond. Niets wordt te laat uitgevoerd.
Weigeringen — een operatie buiten de lokale allowlist, een onbekende capability, een herhaalde nonce of een downgrade-poging wordt geweigerd, en de weigering wordt teruggemeld en als governance-bevinding vastgelegd.
Gedegradeerde nonce-opslag — kan de agent zijn nonce-grootboek niet schrijven, dan valt hij terug op in-memory-registratie met een luide waarschuwing en een metric; het replay-venster is dan begrensd door de vervaltijd van de operatie (minuten).

Installeren, upgraden, verwijderen

Het installatiepakket (geleverd bij enrolment) bevat de manifests, een idempotente install.sh gedreven door één values.env, een verify.sh die het resultaat controleert, plus rotatie-/intrek-/verwijderscripts. Images zijn standaard digest-gepind. Upgraden is de installer opnieuw draaien met de nieuwe digests; verwijderen is het uninstall-script plus de agent intrekken onder Settings → DevOps, waarna zijn requests worden geweigerd.

Problemen oplossen

Agent direct na installatie unhealthy — de health-probe meldt pas ready na de eerste geslaagde poll; controleer de uitgaande bereikbaarheid naar FixControl en de enrolment-waarden.
Operaties verlopen zonder uitgevoerd te worden — de agent pollt niet (egress geblokkeerd, secret ingetrokken, pod plat) of is ge-enrold tegen een ander cluster-ID dan de operatie adresseert. Beide verschijnen in de connectiviteits-health en de audittrail.
Een verdict is goedgekeurd maar er bewoog niets — bekijk de operatie op de tijdlijn van de goedkeuring: een verval, een weigering (met reden) of een leveringsretry staat daar vastgelegd in plaats van verloren te gaan.

Zie ook: DevOps & CI/CD · Change-validatie · Security & audit.