Ga naar inhoud
monsys.ai

Mass provisioning

Het probleem

Per-agent tokens zijn one-shot — één klik in de dashboard levert één token op voor één registratie. Dat schaalt niet wanneer je 20 of 100 VMs in parallel opspint vanuit Terraform of een autoscaling group. Je wil één geheim dat alle hosts mogen gebruiken, met een ingebouwde teller en vervaltijd.

Enrolment tokens

Een enrolment token (prefix enrl_) is een meervoudig bruikbaar secret met:

  • max_uses — harde plafond op het aantal registraties
  • expires_at — TTL van 1 uur tot 30 dagen
  • default_tags + default_role — automatisch toegekend aan elke geregistreerde agent
  • allowed_cidrs (optioneel) — bron-IP allowlist voor extra hardening
  • revoked_at — instant kill switch vanuit de dashboard

De hub bewaart alleen de SHA-256; het raw token wordt één keer getoond en mag je daarna alleen nog in je secret store stoppen.

Token aanmaken

  1. Dashboard → Settings → Enrolment tokens
  2. Naam: bijv. production-cluster-eu-west
  3. TTL: 72 uur, max uses: 50, default tags: prod,eu-west,web, role: web
  4. (Optioneel) Allowed CIDRs: bijv. 10.0.0.0/8 als de hosts in je VPC zitten
  5. Create — kopieer het enrl_… token meteen

Gebruik in cloud-init

#cloud-config
runcmd:
  - bash -c '
      export MONSYS_TOKEN="enrl_xxxxx"
      export MONSYS_TAGS="$(curl -fsS http://169.254.169.254/latest/meta-data/placement/availability-zone)"
      curl -fsSL https://get.monsys.ai/install.sh | sudo -E bash
    '

De installer detecteert de enrl_ prefix, roept POST /api/v1/agents/enrol aan op de hub, en krijgt een vers per-agent token (agt_…) terug. Dat token komt in /etc/monsys/agent.toml. Het enrolment token wordt niet bewaard op de host — de agent gebruikt vanaf nu alleen zijn eigen one-shot token.

Gebruik in Terraform

module "monsys" {
  source       = "git::https://github.com/gotrust/monsys.git//agent/packaging/terraform"
  monsys_token = var.monsys_enrolment_token  # uit Vault / SOPS
  tags         = ["shard-${count.index}"]
  role         = "web"
}


resource "aws_instance" "web" {
  count         = 50
  ami           = "ami-..."
  instance_type = "t4g.small"
  user_data     = module.monsys.cloud_init
}

50 instances, één secret. Elke host komt online met zijn eigen agt_… token plus de tags prod,eu-west,web,shard-N.

Gebruik in Ansible

- name: install monsys agent
  hosts: all
  become: true
  vars:
    monsys_token: "{{ lookup('hashi_vault', 'secret/monsys/enrolment') }}"
  tasks:
    - shell: |
        export MONSYS_TOKEN="{{ monsys_token }}"
        export MONSYS_TAGS="{{ group_names | join(',') }}"
        export MONSYS_ROLE="{{ ansible_role | default('') }}"
        curl -fsSL https://get.monsys.ai/install.sh | bash
      args:
        creates: /etc/monsys/agent.toml

Tag merging

Tags van het token (default_tags) komen eerst; tags die je via MONSYS_TAGS of de Terraform tags variabele meegeeft worden eraan toegevoegd (geen duplicates). Hetzelfde voor role: token default wint, behalve als de installer een expliciete MONSYS_ROLE mee krijgt.

Audit

Elke registratie wordt geregistreerd in enrolment_uses met:

  • token id
  • nieuw agent id
  • bron-IP
  • timestamp

Wanneer 100 agents binnen 5 minuten verschijnen, zie je in de enrolment-tokens lijst direct welke token dat heeft geautoriseerd, en kan je via één klik revoken als er een rare host tussen zit.

Failure modes

Alle onderstaande gevallen geven 401 terug — bewust geen onderscheid om attackers niet te helpen:

  • token bestaat niet (verkeerde hash)
  • token verlopen (expires_at voorbij)
  • token revoked
  • max_uses bereikt
  • bron-IP buiten de allowed_cidrs

Operator-feedback krijg je via de dashboard (uses counter, expiry, status).

Token rotatie

Tokens worden niet hernieuwd — je maakt simpelweg een nieuwe aan en revoked de oude wanneer je klaar bent met de batch. Geregistreerde agents blijven werken; alleen nieuwe registraties via dat token worden geblokkeerd.