Skip to content
Atlas docs

Grant Atlas ontology + shapes write ACL

Grant Atlas ontology + shapes write ACL

Section titled “Grant Atlas ontology + shapes write ACL”

As of 2026-05-02, the production Atlas service account has this ACL and /health reports dependencies.ontology.ready=true. Keep this runbook for future rotations or new environments; a new 403 is a release-blocking regression unless an operator explicitly sets the emergency ATLAS_ONTOLOGY_ALLOW_ACL_GAP=1 override.

When make ship-ontology (or atlas-gateway --register-ontology) prints 403 — Keystone ACL gap (epic djed-9523), the Atlas service account authenticates correctly but is not authorised to write on the keystone-ontology (:8087) and keystone-shapes (:8088) services. Until the grant is in place every downstream feature that depends on the Atlas ontology degrades silently:

  • Studio classify can’t suggest pattern types it can’t validate against.
  • SHACL validation in the extractor is skipped because no shapes exist.
  • The clean-core scorecard returns deferred because no artifacts pass ontology-aware checks.

Symptoms

Section titled “Symptoms”
  • Gateway log: register ontology: 403 — Keystone ACL gap
  • make ship-ontology fails after printing Keystone ACL gap. If ATLAS_ONTOLOGY_ALLOW_ACL_GAP=1 is set, the deploy continues only for that explicit emergency override.
  • /health reports dependencies.ontology.ready=false.

Resolution

Section titled “Resolution”

The grant is applied on the Keystone side, not in this repo. Follow these steps with a Keystone admin role:

  1. Identify the Atlas service principal:
    • The principal subject is the sub claim on the JWT minted from KEYSTONE_MACHINE_KEY_FILE (default /run/secrets/keystone_machine_key). Decode it with cat /opt/djed/config/zitadel-keys/atlas-graphsync.key.json | jq .userId.
  2. Apply the ACL on keystone-ontology:
    Terminal window
    curl -X POST https://auth.naburis.cloud/api/keystone/ontology/v1/acls \
      -H "Authorization: Bearer $ADMIN_TOKEN" \
      -d '{"principal":"<sub>","actions":["create","update","delete"]}'
  3. Apply the ACL on keystone-shapes:
    Terminal window
    curl -X POST https://auth.naburis.cloud/api/keystone/shapes/v1/acls \
      -H "Authorization: Bearer $ADMIN_TOKEN" \
      -d '{"principal":"<sub>","actions":["create","update","delete"]}'
  4. Re-run from the Atlas root:
    Terminal window
    make ship-ontology
  5. Verify /health reports dependencies.ontology.ready=true.

Verification

Section titled “Verification”
Terminal window
curl -s http://127.0.0.1:58100/health | jq '.dependencies.ontology'

Expect "ready": true and detail ontology registered.

Section titled “Related”
  • Code: internal/ontology/register.go classifies the 403 and points back here.