Developer guide

The primary architectural documentation for Gafaelfawr is DMTN-224, the implementation tech note. This part of Gafaelfawr’s documentation contains some supplemental information primarily of interest to people doing development on Gafaelfawr itself.

The Gafaelfawr code structure follows the guidelines in SQR-072.

Architecture

• Design overview
• Phalanx-provided requirements
  • Client IP addresses
  • Error handling
• Configuration architecture
  • Pydantic and dataclasses
  • Passing secrets
• Authentication providers
  • OpenID Connect
  • GitHub
    • Groups from GitHub
• User metadata
  • UID
  • Primary GID
• Scopes
  • Overview
  • Reserved scopes
  • Scope inheritance
  • Scope naming
• Logging
  • Client IP addresses
• Kubernetes resources
  • Future CRD changes
    • Changes to GafaelfawrIngress
    • Changes to GafaelfawrServiceToken

Guides

• Development guide
  • Scope of contributions
  • Setting up a local development environment
  • Pre-commit hooks
  • Building the UI
  • Running tests
    • Testing the Kubernetes operator
  • Running a development server
  • Updating dependencies
    • Temporary Git dependencies
  • Creating database migrations
  • Building documentation
  • Updating the change log
  • Style guide
    • Code
    • Documentation
• Release procedure
  • Regular releases
    • 1. Change log and dependencies
    • 2. Tag the release
    • 3. Create a GitHub release
  • Backport releases
    • Creating a release branch
    • Developing on a release branch
    • Releasing from a release branch

Reference

• Glossary
  • Terms to avoid
• Python internal API
  • gafaelfawr Package
  • gafaelfawr.auth Module
  • gafaelfawr.cache Module
  • gafaelfawr.config Module
  • gafaelfawr.constants Module
  • gafaelfawr.dependencies.auth Module
  • gafaelfawr.dependencies.config Module
  • gafaelfawr.dependencies.context Module
  • gafaelfawr.dependencies.return_url Module
  • gafaelfawr.events Module
  • gafaelfawr.exceptions Module
  • gafaelfawr.factory Module
  • gafaelfawr.keypair Module
  • gafaelfawr.middleware.state Module
  • gafaelfawr.models.admin Module
  • gafaelfawr.models.auth Module
  • gafaelfawr.models.history Module
  • gafaelfawr.models.kubernetes Module
  • gafaelfawr.models.ldap Module
  • gafaelfawr.models.link Module
  • gafaelfawr.models.oidc Module
  • gafaelfawr.models.state Module
  • gafaelfawr.models.token Module
  • gafaelfawr.models.userinfo Module
  • gafaelfawr.operator Package
  • gafaelfawr.operator.health Module
  • gafaelfawr.operator.ingress Module
  • gafaelfawr.operator.startup Module
  • gafaelfawr.operator.tokens Module
  • gafaelfawr.providers.base Module
  • gafaelfawr.providers.github Module
  • gafaelfawr.providers.oidc Module
  • gafaelfawr.pydantic Module
  • gafaelfawr.services.admin Module
  • gafaelfawr.services.firestore Module
  • gafaelfawr.services.health Module
  • gafaelfawr.services.kubernetes Module
  • gafaelfawr.services.ldap Module
  • gafaelfawr.services.oidc Module
  • gafaelfawr.services.token Module
  • gafaelfawr.services.token_cache Module
  • gafaelfawr.services.userinfo Module
  • gafaelfawr.storage.admin Module
  • gafaelfawr.storage.firestore Module
  • gafaelfawr.storage.history Module
  • gafaelfawr.storage.kubernetes Module
  • gafaelfawr.storage.ldap Module
  • gafaelfawr.storage.oidc Module
  • gafaelfawr.storage.token Module
  • gafaelfawr.templates Module
  • gafaelfawr.util Module