feat: monky-deployd v0.1.0 — pull agent over the mesh (ADR-0028)

Stdlib-only Python 3.12 agent for docker VMs and laptops: flock → checkin
(bearer = the agent's OpenBao token, bootstrapped from the install kit's
jwt-tenancy deploy grant) → action apply|none|down → bundle (sha256
verified) → refusal checks (unresolved ${VAR} names only, manifest paths
pinned to monky/data/<env>/see/, privileged/host-network, rollback, disk
need×1.5+headroom) → lease → POST /v1/auth/jwt-tenancy/login → KV reads →
.env 0600 → promote → compose pull/up → wait healthy → report; finally
renew-self / re-lease before max TTL, scrub. Exit 0/75/78/1. Redactor log
filter. Transports sdk (openziti) / proxy (ziti tunnel proxy 18443/18200) /
system. Laptop mode.

Packaging: hardened oneshot + 60 s timer + proxy unit, nfpm .deb with
/opt/monky-deployd/venv, install.sh for Ubuntu 26.04 (Gitea release
download, enrol, ACLs, bootstrap from stdin), ansible role skeleton for
osg1-07. CI: lint/test on every change; wheel (openziti on ubuntu:26.04) and
package (nfpm) allow_failure until runner egress is proven; GitLab release +
release:gitea on v* tags. Docs: README, PROTOCOL, OPERATIONS, CHANGELOG,
CLAUDE/AGENTS.

Divergence noted: monky-tenancy main (MR !15) still ships the AppRole lease
and kit; this agent implements the plan's Gate 1 RESULT (login_jwt, no
unwrap) and refuses an AppRole lease loudly (LEASE_SHAPE).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KLB7jieMNRkTsJ2epr4Ds1

ansible/roles/monky_deployd/README.md

@@ -0,0 +1,36 @@
+# role `monky_deployd`
+
+Installs and configures [monky-deployd](https://scm.tikali.ai/tikali/applications/monky/monky-deployd)
+(the Monky backend pull agent, MONKY-ADR-0028) on a docker host that already carries an enrolled
+host identity (`roles/ziti_tunneler`, run-host mode). Skeleton for **osg1-07**; copy it there.
+
+What it does: pin + download the `.deb` from the Gitea release (sha256 verified) → ACL
+`u:monky-deployd:r` on the identity (`rx` on the dir) → `/etc/monky-deployd/config.yaml` from the
+template → optional openbao-ca PEM → optional `monky-deployd-proxy.service` (`transport: proxy`)
+→ the **one-time bootstrap deploy grant** from a vault var (0600, `no_log`) → `monky-deployd.timer`
+→ first tick via handler (inside the grant's hour) → `monky-deployd status`.
+
+## Variables (see `defaults/main.yml`)
+
+| var | note |
+|---|---|
+| `monky_deployd_version` | pinned release, e.g. `0.1.0` |
+| `monky_deployd_env_id` / `_site` / `_transport` | per host (`env-dev-06`, `cbs`, `sdk`) |
+| `monky_deployd_bootstrap_grant` | tenancy-minted deploy grant (1 h) — `ansible-vault` or a lookup at play time; empty keeps the existing token |
+| `monky_deployd_bao_ca_pem` | the `openbao-ca` certificate (PEM) |
+| `monky_deployd_volumes_on_absent` | `keep` (default) or `purge` (never applied on prod by the agent) |
+
+## Example play
+
+```yaml
+- hosts: env-dev-06:env-dev-07:env-dev-08:env-dev-09
+  become: true
+  roles:
+    - role: ziti_tunneler        # enrol/verify monky-host.<env>; gains the ACL var + name assertion
+    - role: monky_deployd
+      vars:
+        monky_deployd_bootstrap_grant: "{{ lookup('pipe', 'tenancy-mint-grant ' ~ inventory_hostname) }}"
+```
+
+Rollout order (plan §E): pilot env-qa-02 → env-dev-06..09 → env-dev-01 last (after its live key moves into Bao).
+Verified on Ubuntu 26.04.

ansible/roles/monky_deployd/defaults/main.yml

@@ -0,0 +1,35 @@
+---
+# monky_deployd — install and configure the Monky backend pull agent (MONKY-ADR-0028 §D).
+# Copy this role into osg1-07 (roles/monky_deployd) and roll to env-dev-06..09 after the pilot.
+monky_deployd_version: "0.1.0"
+monky_deployd_base_url: "https://gitea.cbs.tikali.net/mdella/monky-deployd"
+monky_deployd_deb: "monky-deployd_{{ monky_deployd_version }}_amd64.deb"
+monky_deployd_deb_url: "{{ monky_deployd_base_url }}/releases/download/v{{ monky_deployd_version }}/{{ monky_deployd_deb }}"
+monky_deployd_deb_sha256_url: "{{ monky_deployd_deb_url }}.sha256"
+
+# per host (inventory / host_vars)
+monky_deployd_env_id: "{{ inventory_hostname }}"        # env-dev-06 ...
+monky_deployd_site: cbs
+monky_deployd_transport: sdk                            # sdk | proxy | system
+monky_deployd_identity: "/opt/openziti/etc/identities/monky-host.{{ monky_deployd_env_id }}.json"
+monky_deployd_laptop_mode: false
+monky_deployd_volumes_on_absent: keep
+monky_deployd_interval_s: 60
+monky_deployd_healthy_timeout_s: 300
+monky_deployd_disk_factor: 1.5
+monky_deployd_disk_headroom_bytes: 2147483648
+
+monky_deployd_tenancy_service: monky.tenancy.deploy
+monky_deployd_tenancy_port: 8081
+monky_deployd_bao_addr: "https://bao.cbs.tikali.net:8200"
+monky_deployd_bao_auth_mount: jwt-tenancy
+monky_deployd_bao_role: see-env
+monky_deployd_bao_kv_mount: monky
+# the openbao-ca certificate (PEM text) — from the vault (ansible-vault / OpenBao lookup)
+monky_deployd_bao_ca_pem: ""
+
+# ONE-TIME bootstrap deploy grant, minted by tenancy at playbook time (1 h): the role stages it
+# and runs the first tick inside the hour. Leave empty to keep an existing bao.token.
+monky_deployd_bootstrap_grant: ""
+monky_deployd_run_first_tick: true
+monky_deployd_timer_enabled: true

ansible/roles/monky_deployd/handlers/main.yml

@@ -0,0 +1,6 @@
+---
+- name: monky_deployd tick
+  ansible.builtin.systemd:
+    name: monky-deployd.service
+    state: started
+  when: monky_deployd_run_first_tick | bool

ansible/roles/monky_deployd/meta/main.yml

@@ -0,0 +1,13 @@
+---
+galaxy_info:
+  role_name: monky_deployd
+  author: Tikali platform
+  description: Monky backend pull agent (monky-deployd) on docker hosts
+  license: Proprietary
+  min_ansible_version: "2.15"
+  platforms:
+    - name: Ubuntu
+      versions: ["noble", "26.04"]
+collections:
+  - ansible.posix
+dependencies: []

ansible/roles/monky_deployd/tasks/main.yml

@@ -0,0 +1,130 @@
+---
+# Assumes: docker + compose plugin present, the host identity enrolled by roles/ziti_tunneler
+# (run-host mode) — that role gains the ACL var + a name assertion (plan §D).
+- name: monky_deployd | assert inputs
+  ansible.builtin.assert:
+    that:
+      - monky_deployd_env_id is match('^env-(dev|qa|stage|prod)-[0-9]{2,3}$')
+      - monky_deployd_site in ['cbs', 'pdx']
+      - monky_deployd_transport in ['sdk', 'proxy', 'system']
+    fail_msg: "env_id/site/transport out of grammar"
+
+- name: monky_deployd | prerequisites
+  ansible.builtin.apt:
+    name: [acl, ca-certificates]
+    state: present
+    update_cache: true
+    cache_valid_time: 3600
+
+- name: monky_deployd | installed version
+  ansible.builtin.command: dpkg-query -W -f='${Version}' monky-deployd
+  register: monky_deployd_installed
+  changed_when: false
+  failed_when: false
+
+- name: monky_deployd | download .deb + sha256 from the Gitea release
+  when: monky_deployd_installed.stdout != monky_deployd_version
+  block:
+    - name: monky_deployd | fetch sha256
+      ansible.builtin.uri:
+        url: "{{ monky_deployd_deb_sha256_url }}"
+        return_content: true
+      register: monky_deployd_sha
+    - name: monky_deployd | fetch .deb (checksum verified)
+      ansible.builtin.get_url:
+        url: "{{ monky_deployd_deb_url }}"
+        dest: "/var/cache/apt/archives/{{ monky_deployd_deb }}"
+        checksum: "sha256:{{ monky_deployd_sha.content.split()[0] }}"
+        mode: "0644"
+    - name: monky_deployd | install .deb
+      ansible.builtin.apt:
+        deb: "/var/cache/apt/archives/{{ monky_deployd_deb }}"
+
+- name: monky_deployd | identity present
+  ansible.builtin.stat:
+    path: "{{ monky_deployd_identity }}"
+  register: monky_deployd_id_stat
+  failed_when: not monky_deployd_id_stat.stat.exists
+
+- name: monky_deployd | ACL so the agent can read the identity
+  ansible.posix.acl:
+    path: "{{ item.path }}"
+    entity: monky-deployd
+    etype: user
+    permissions: "{{ item.perms }}"
+    state: present
+  loop:
+    - { path: "{{ monky_deployd_identity }}", perms: r }
+    - { path: "{{ monky_deployd_identity | dirname }}", perms: rx }
+
+- name: monky_deployd | directories
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    owner: "{{ item.owner }}"
+    group: monky-deployd
+    mode: "{{ item.mode }}"
+  loop:
+    - { path: /etc/monky-deployd, owner: root, mode: "0750" }
+    - { path: /var/lib/monky-deployd, owner: monky-deployd, mode: "0700" }
+
+- name: monky_deployd | openbao CA
+  ansible.builtin.copy:
+    content: "{{ monky_deployd_bao_ca_pem }}"
+    dest: /etc/monky-deployd/openbao-ca.pem
+    mode: "0644"
+  when: monky_deployd_bao_ca_pem | length > 0
+
+- name: monky_deployd | config.yaml
+  ansible.builtin.template:
+    src: config.yaml.j2
+    dest: /etc/monky-deployd/config.yaml
+    owner: root
+    group: monky-deployd
+    mode: "0640"
+  notify: monky_deployd tick
+
+- name: monky_deployd | proxy transport env
+  ansible.builtin.copy:
+    content: "ZITI_IDENTITY={{ monky_deployd_identity }}\n"
+    dest: /etc/monky-deployd/proxy.env
+    mode: "0644"
+  when: monky_deployd_transport == 'proxy'
+
+- name: monky_deployd | proxy service
+  ansible.builtin.systemd:
+    name: monky-deployd-proxy.service
+    enabled: "{{ monky_deployd_transport == 'proxy' }}"
+    state: "{{ 'started' if monky_deployd_transport == 'proxy' else 'stopped' }}"
+    daemon_reload: true
+
+- name: monky_deployd | bootstrap grant (one-time, from tenancy)
+  ansible.builtin.copy:
+    content: "{{ monky_deployd_bootstrap_grant }}\n"
+    dest: /etc/monky-deployd/bootstrap.jwt
+    owner: monky-deployd
+    group: monky-deployd
+    mode: "0600"
+  when: monky_deployd_bootstrap_grant | length > 0
+  no_log: true
+  notify: monky_deployd tick
+
+- name: monky_deployd | timer
+  ansible.builtin.systemd:
+    name: monky-deployd.timer
+    enabled: "{{ monky_deployd_timer_enabled }}"
+    state: "{{ 'started' if monky_deployd_timer_enabled else 'stopped' }}"
+    daemon_reload: true
+
+- name: monky_deployd | flush handlers (first tick inside the grant's hour)
+  ansible.builtin.meta: flush_handlers
+
+- name: monky_deployd | status
+  ansible.builtin.command: monky-deployd status
+  register: monky_deployd_status
+  changed_when: false
+  failed_when: false
+
+- name: monky_deployd | show status
+  ansible.builtin.debug:
+    msg: "{{ monky_deployd_status.stdout_lines }}"

ansible/roles/monky_deployd/templates/config.yaml.j2

@@ -0,0 +1,29 @@
+# {{ ansible_managed }} — monky-deployd {{ monky_deployd_version }} (role monky_deployd)
+env_id: {{ monky_deployd_env_id }}
+site: {{ monky_deployd_site }}
+transport: {{ monky_deployd_transport }}
+identity: {{ monky_deployd_identity }}
+tenancy:
+  service: {{ monky_deployd_tenancy_service }}
+  host: {{ monky_deployd_tenancy_service }}
+  port: {{ monky_deployd_tenancy_port }}
+  scheme: http
+  proxy_addr: 127.0.0.1:18443
+bao:
+  service: openbao
+  addr: {{ monky_deployd_bao_addr }}
+  proxy_addr: 127.0.0.1:18200
+  ca_bundle: {{ '/etc/monky-deployd/openbao-ca.pem' if monky_deployd_bao_ca_pem | length > 0 else 'none' }}
+  mount: {{ monky_deployd_bao_auth_mount }}
+  role: {{ monky_deployd_bao_role }}
+  kv_mount: {{ monky_deployd_bao_kv_mount }}
+state_dir: /var/lib/monky-deployd
+deploy_dir: /var/lib/monky-deployd/{{ monky_deployd_env_id }}
+bootstrap_path: /etc/monky-deployd/bootstrap.jwt
+interval_s: {{ monky_deployd_interval_s }}
+healthy_timeout_s: {{ monky_deployd_healthy_timeout_s }}
+disk:
+  factor: {{ monky_deployd_disk_factor }}
+  headroom_bytes: {{ monky_deployd_disk_headroom_bytes }}
+volumes_on_absent: {{ monky_deployd_volumes_on_absent }}
+laptop_mode: {{ 'true' if monky_deployd_laptop_mode else 'false' }}