Hoe het werkt

De onderdelen van een installatie, wat er bij een start gebeurt, en waar gegevens worden bewaard

  1. Architectuur
    1. Gebouwd met
  2. Wat er gebeurt als je een formulier start
  3. Waar alles wordt opgeslagen

Architectuur

AnsibleForms is een Node.js-server die de webapplicatie en een REST API aanbiedt, ondersteund door een MySQL-database. Hij leest formulieren uit YAML-bestanden en voert zelf niets uit: hij geeft elke job aan een runner. Een playbook gaat naar een van je RTE-containers (runtime-omgeving), die ansible-playbook uitvoert, en een template of job gaat naar AWX, AAP, Ascender, Semaphore, Rundeck of Jenkins:

Architectuur van AnsibleForms De browser en een optionele MCP-client praten met de AnsibleForms-server. De server slaat zijn gegevens op in MySQL en in de persistente map, en maakt verbinding met gegevensbronnen, secret stores, git-repositories, aanmeldproviders, meldingskanalen, syslogservers en een optionele modelprovider. Zijn runners geven elk playbook aan een van een of meer RTE-containers, elk over een eigen WebSocket, die ansible-playbook uitvoeren en de uitvoer terugsturen naar de server, en elke template of job aan AWX, AAP, Ascender, Semaphore, Rundeck of Jenkins. Browser formulieren, designer, jobs, chat MCP-client optioneel AnsibleForms-server Node.js / Express Webapp en REST API Formulieren, expressies Workflows, planningen MCP-server (optioneel) Runners geven elke job aan zijn runner Gegevensbronnen databases, API's, bestanden Secret stores HashiCorp Vault, CyberArk Git-repositories formulieren, playbooks, config Aanmeldproviders LDAP, Entra ID, OIDC Meldingskanalen mail, Slack, Teams, webhooks Syslogservers het log, het audittrail Modelprovider optioneel, chat-assistent Persistente map config, formulieren, playbooks MySQL / MariaDB jobs, gebruikers, referenties RTE-containers draaien ansible-playbook AWX / AAP / Ascender Semaphore, Rundeck, Jenkins playbooks, WebSocket templates, jobs

De onderdelen in het diagram hebben elk een eigen rol:

Onderdeel Rol
Browser De Vue-webapplicatie: de formulieren, de Designer, de jobgeschiedenis en de instellingen
AnsibleForms-server Evalueert de formulieren, legt de jobs vast, voert de workflows en de planningen uit, geeft elke job aan zijn runner en volgt hem, en biedt de REST API aan
Runners Waar jobs draaien, toegevoegd onder Verbindingen > Runners: een formulier noemt er een met runner: <name>, of gebruikt de standaardrunner van zijn type (zie Runners)
RTE-containers Een of meer containers met een runtime-omgeving, dezelfde server gestart met AF_ROLE=rte: elk voert ansible-playbook uit voor ansible-formulieren, met de python-bibliotheken en collections van zijn image, en stuurt de uitvoer en de eindstatus terug naar de server over één WebSocket, zonder database-inloggegevens (zie Hoe de RTE draait)
AWX / AAP / Ascender, Semaphore, Rundeck, Jenkins Runners voor templates en jobs: AWX-formulieren starten een job- of workflowtemplate, formulieren voor Semaphore, Rundeck en Jenkins starten een van hun jobs, en de server volgt de uitvoer
MySQL / MariaDB Bevat de jobs en hun uitvoer, de gebruikers, de referenties en de verbindingen; alleen de server leest en schrijft erin
Persistente map Bevat config.yaml, de formulierbestanden, de playbooks, de logs en de back-ups
Gegevensbronnen Vullen de velden: databasequery’s, REST API’s, bestanden en andere functies
Secret stores Leveren de gebruiker en het wachtwoord van een referentie op het moment van gebruik, zie Secret stores
Git-repositories Houden de formulieren, de playbooks en config.yaml onder versiebeheer
Aanmeldproviders Melden de gebruikers aan: LDAP, Entra ID en OIDC, naast de lokale gebruikers
Meldingskanalen Brengen de meldingen en de goedkeuringsverzoeken over: mail, Slack, Microsoft Teams, Telegram of een webhook
Syslogservers Ontvangen het log en het audittrail terwijl ze worden geschreven, zie Syslog
MCP-client, chat Optioneel, beide standaard uit: de MCP-server en de chat-assistent, die een modelprovider nodig heeft

Standaard draait één container de server, de webapp en het achtergrondwerk samen, naast één RTE. Voor meerdere app-nodes achter een load balancer, een worker die het achtergrondwerk uitvoert, en meer RTE’s, zie Schalen.

Gebouwd met

De server en de webinterface zijn gebouwd op deze onderdelen:

Deel Technologie
Server Node.js en Express
Database MySQL of MariaDB
Webinterface Vue 3, met Bootstrap 5 en Font Awesome

Wat er gebeurt als je een formulier start

Een start doorloopt dezelfde stappen, of hij nu uit de browser komt of uit de REST API:

  1. Laden : de server stuurt alleen de formulieren die de rollen van de gebruiker toestaan, en evalueert de serverexpressies
  2. Verzenden : de browser zet de veldwaarden om in extravars en post ze naar POST /api/v2/job
  3. Controleren : de server laadt het formulier opnieuw voor de rollen van de gebruiker en controleert, met startvalidatie aan, de waarden
  4. Vastleggen : de job wordt opgeslagen met status running, en het id ervan wordt aan de extravars toegevoegd als __jobid__
  5. Goedkeuren : een formulier met een approval-punt wacht tot een goedkeurder de job accepteert
  6. Referenties : voor een playbook leest de app (nooit de RTE) de referenties van het formulier uit de database of een secret store
  7. Uitvoeren : de job gaat naar zijn runner, de runner die het formulier met runner: noemt of de standaard van zijn type. Voor een playbook stuurt de app de job naar zijn RTE over de WebSocket van de RTE, met de referenties voor die RTE verzegeld, en de RTE voert ansible-playbook uit (zie Hoe de RTE draait), en AWX, AAP, Ascender, Semaphore, Rundeck of Jenkins voert een template of een job uit. Een workflow voert zijn nodes uit, elk als een eigen job op een eigen runner
  8. Volgen : de server slaat de uitvoer in de database op zodra die binnenkomt, voor een playbook door de RTE over zijn socket gestuurd, of gelezen van de andere runners. De formulierpagina leest de job elke twee seconden opnieuw, en de pagina Taken volgt hem live terwijl de server elke wijziging aankondigt
  9. Einde : de job krijgt zijn eindstatus, en zijn notifications gaan per mail en naar zijn meldingskanalen als het formulier daarom vraagt

Waar alles wordt opgeslagen

AnsibleForms bewaart zijn toestand op twee plaatsen: de MySQL-database en de persistente map. Maak van beide een back-up.

In de database

De database, AnsibleForms, wordt bij de eerste start aangemaakt (tenzij ALLOW_SCHEMA_CREATION 0 is) en bevat:

  • de jobs, hun extravars en hun uitvoer, de planningen en de opgeslagen jobs
  • de lokale gebruikers, de groepen en de API-tokens
  • de referenties, versleuteld met ENCRYPTION_SECRET, en de verbindingen met secret stores
  • de runners, de meldingskanalen (mail inbegrepen), de syslogservers, en de instellingen voor LDAP, SSO, repositories en de chat-assistent
  • het auditlogboek

In de persistente map

Dat is /app/dist/persistent in de image en server/persistent vanuit de broncode; elk pad heeft een eigen variabele:

Standaardpad Variabele Inhoud
config.yaml CONFIG_PATH De categorieën, de rollen en de constanten
forms/ FORMS_FOLDER_PATH De formulierbestanden, .yaml of .yml, desgewenst in submappen
playbooks/ ANSIBLE_PATH De playbooks van ansible-formulieren, en hun werkmap
repositories/ REPO_PATH De clones van de git-repositories
forms_backups/ FORMS_BACKUP_PATH De kopieën die de Designer maakt voordat hij opslaat
backups/ BACKUP_PATH De databaseback-ups
uploads/ UPLOAD_PATH De bestanden die via file-velden zijn geüpload
logs/ LOG_PATH ansibleforms.log en ansibleforms.errors.log
certificates/ HTTPS_CERT, HTTPS_KEY Het certificaat en de sleutel, als HTTPS 1 is
.env   De omgevingsvariabelen die vanuit de instellingenpagina’s zijn opgeslagen (tenzij ALLOW_ENV_EDIT 0 is)

De gegenereerde SSH-sleutel staat in HOME_PATH, standaard buiten de persistente map.