fricklerhandwerk 82a86f4515 add configuration-to-deployment dataflow diagram

side note: the pile of documents in this directory would benefit from some cleanup,
because it tends to get confusing to navigate it. e.g. we can render images programmatically
from the source rather than checking them in.

currently we're conflating or inconsistently separating two document types:
- meeting notes and design decisions (capturing point-in-time discussion that is append-only)
- technical specification such as architecture diagrams (which change over time to reflect current understanding)

we'll keep piling up for now, but ultimately if we need to do onboarding or hand-over
to new developers or contributors, this should be sorted out.

2025-07-08 12:57:26 +02:00

4.4 KiB

Raw Blame History

2025-06-24 Fediversity configuration data flow

This data flow diagram refines the global architecture diagram with respect to how a deployment is obtained from an operator's application configuration and a hosting provider's runtime setup.

Legend

Circle: actor
Angled box: type
Rectangle: value
Rounded box: function
Diamond: state
Arrow: points towards dependant

Description

An application module specifies operator-facing application options, and a resource mapping which determines the application's underlying implementation in terms of which resources it requires to be deployed. Application modules can be supplied by external contributors, which would package applications against that interface.

For its runtime environment, a hosting provider has to supply a policy mapping that would take their self-declared resource configuration (which determines available resources, i.e. a description of the infrastructure on which to run the applications) and the output of an application's resource mapping (which determines resource requirements) and produce the description of a deployment.

An operator can supply an application configuration and request the hosting provider to let the resulting deployment take effect, such that it will accumulate application state, which can later be migrated to other hosting providers.

Applications and runtime environments thus interface through resources, the properties of which are curated by Fediversity maintainers.

flowchart

subgraph configuration
  application-config
end
subgraph resource[resource module]
  resource-options
  provider-options
end
subgraph application[application module]
  application-options{{application-options}} --> application-config
  application-config --> config-mapping
  resource-options{{consumer-options}} --> config-mapping
  config-mapping(resource-mapping)
end
subgraph fediversity[runtime-environment]
  config-mapping -->|required resources| resource-mapping(policy-mapping)

  provider-options{{resource-options}} --> resource-config --> |available resources| resource-mapping -->|configured resources| deployment[deployment]
  deployment --> |deploy| state{application state}

end

maintainer((maintainer)) -->|curates| resource


contributor((contributor)) -->|packages| application
operator((operator)) -->|enters| configuration


hosting-provider((hosting provider)) -->|maintains| fediversity

Discussion

Decoupling of operator-facing application configuration and resource use allows for portability at the infrastructure level: hosting providers determine how applications are deployed to available resources through policies which are agnostic to applications. Additionally it allows hosting providers to isolate applications from each other depending on their deployment model, leveraging the entire toolkit provided by the Nix ecosystem. This puts single-machine and cluster deployments on equal footing, since policies are simply Nix language functions.

At first glance this is an increase in complexity as opposed to configuring NixOS directly, since it adds a layer of indirection. It also requries Fediversity maintainers to declare resource types for use by application packagers and hosting providers. But the layering drastically simplifies application composition over what NixOS can currently offer, frees the hosting provider to choose how to implement required services, and enables security-conscious deployments at very fine granularity.

Next steps

Versioning: Each of the components can change; model all supported interactions such that deployments will always be correct.

Primarily, both applications and runtime environments depend on the resource API, and need to be versioned against it. Application packages can be updated on top of that, and will need to provide facilities to migrate between both application versions and resource API versions, both in terms of configurations and application state.
Provider migrations: Prototype an application-agnostic migration workflow.

Since state migration is application-specific, application packages will need to ship with instructions for how to move their data between hosting providers, also taking version migrations into account. This will likely require extending the resource API with ways to express where state is located, and give hosting providers the tools to expose interfaces though which migrations will take place.

4.4 KiB Raw Blame History