Skip to content

Reconcile stale Dragonfly staging docs and runtime contracts #156

Description

@import-pandas-as-numpy

Summary

Several Dragonfly infrastructure docs and READMEs are stale or internally inconsistent, which made
the staging deployment and auth investigation materially harder than it should have been.

This issue is to reconcile the documented runtime contract with the actual manifests and current
staging auth model.

Problems found

1. Mainframe secret name mismatch

Files:

  • kubernetes/manifests/dragonfly/mainframe/deployment.yaml
  • kubernetes/manifests/dragonfly/mainframe/README.md

Current state:

  • manifest references dragonfly-mainframe-env
  • README documents dragonfly-mainframe-secrets
  • live staging deployment consumes dragonfly-mainframe-env
  • dragonfly-mainframe-secrets does not exist in staging

Required fix:

  • update the README to match the manifest and live deployment
  • audit for any other references to dragonfly-mainframe-secrets and remove or correct them

2. Loader runtime docs still describe Auth0-only staging assumptions

Files:

  • kubernetes/manifests/dragonfly/loader/README.md
  • possibly related Dragonfly runtime docs in this repo

Current state:

  • loader README only documents the Auth0-based env contract
  • staging now uses Cloudflare Access for the public mainframe path
  • the documentation does not explain the current or intended service-to-service auth model for loader

Required fix:

  • update docs to reflect the intended loader auth model
  • if the migration is not yet complete, document the current state and the intended end state clearly
  • make it explicit whether loader should call the public Cloudflare-protected hostname or the in-cluster origin

3. Staging auth/environment documentation is ambiguous relative to live runtime

Files:

  • docs/auth0-tenant-configuration.md
  • Dragonfly runtime/manifests READMEs where relevant

Current state:

  • docs describe staging values around https://dragonfly-staging.vipyrsec.com
  • live loader/mainframe envs were still using .local audience/base-url conventions and Auth0 values
  • this made it unclear whether staging was intentionally mixed-mode or simply partially migrated

Required fix:

  • document the actual supported staging auth architecture
  • document whether Auth0 is deprecated in staging
  • document the expected environment variables for:
    • browser clients
    • service-to-service clients
    • in-cluster callers, if any

Acceptance criteria

  • mainframe secret name docs match the manifest and live runtime
  • loader runtime docs clearly describe its supported auth contract
  • staging auth docs describe a single unambiguous source of truth for Dragonfly service auth
  • obsolete or contradictory references are removed

Notes

  • This issue is documentation and contract cleanup only.
  • The actual loader Cloudflare migration work is tracked separately in vipyrsec/dragonfly-loader#97.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions