design.rst

Architecture Design

The principles

• RSTUF uses The Update Framework (TUF).
  • It enables RSTUF to be artifact agnostic.
• RSTUF is easy to deploy.
• RSTUF has an API-first design.
  • RSTUF is language agnostic, allowing integration by any programming language
• RSTUF is process agnostic.
  • Add/Remove artifacts doesn't interfere with the existing organizational processes for release/publish.
• RSTUF focuses on scalability and Metadata consistency.
• RSTUF guides users on TUF processes.

The architecture design principles

The Repository Service for TUF (RSTUF) has two services (repository-service-tuf-api, repository-service-tuf-worker) and one command line tool (repository-service-cli), as described in :ref:`guide/general/introduction:RSTUF Components`.

Note

Other services can be added as optional or required

RSTUF also requires some third-party services described in :ref:`guide/deployment/planning/deployment:Required Infrastructure Services`.

The below definitions allow RSTUF API and RSTUF Worker scalability.

RSTUF is Asynchronous

• RSTUF uses Celery.
• Every API request is a task.
• RSTUF centralizes all tasks in the :ref:`devel/design:Message Queue`.
• RSTUF stores all task results in the :ref:`devel/design:Backend Result`.
• :ref:`devel/design:Repository Service TUF API` publishes RSTUF tasks.
• :ref:`devel/design:Repository Service TUF Worker` consumes RSTUF tasks.

RSTUF Repository Settings/Configuration

• :ref:`guide/general/introduction:RSTUF Components` are stateless.
  • Components are configured by runtime environment variables.
  • Components uses runtime :ref:`devel/design:TUF Repository Settings`.
• :ref:`devel/design:Redis` stores the :ref:`devel/design:TUF Repository Settings` using Dynaconf.
• :ref:`devel/design:Repository Service TUF Worker` reads and writes :ref:`devel/design:TUF Repository Settings`.
• :ref:`devel/design:Repository Service TUF API` reads :ref:`devel/design:TUF Repository Settings` and writes only during bootstrap process in two stages:
  • Start a bootstrap process: BOOTSTRAP to pre-<taskid>.
  • If detects a failure during bootstrap: BOOTSTRAP to None

TUF Repository Settings

TUF Repository Settings are key configurations for the Metadata Repository operations.

RSTUF reserved settings/configuration

Key	Value(s)	Description
BOOTSTRAP	None <task id> pre-<task id> signing-<task id>	RSTUF bootstrap state None: No bootstrap <task id>: Finished pre-<task id>: Initial process signing-<task id>: Signing process The <task-id> is the initial bootstrap task
<ROLE NAME>_EXPIRATION	int	Role Metadata expiration policy in days It uses the role name uppercase Example: ROOT_EXPIRATION
<ROLE NAME>_NUM_KEYS	int	Role number of keys It uses the role name uppercase Example: ROOT_NUM_KEYS
<ROLE NAME>_THRESHOLD	int	Role key threshold It uses the role name uppercase Example: ROOT_THRESHOLD
NUMBER_OF_DELEGATED_BINS	int	Number of delegated hash bin roles
<ROLE NAME>_SIGNING	None <json>	None: No pending signature(s) json: TUF Metadata pending signature It uses the role name uppercase Example ROOT_SIGNING

Target Files and Target Roles

• The TUF top-level Targets Role is only used for delegation. This role does not register target files (artifacts).
• :ref:`devel/design:PostgreSQL` stores the artifacts (TargetFiles) and Targets delegated roles.
• :ref:`devel/design:Repository Service TUF Worker` manages the :ref:`devel/design:PostgreSQL` database.

Key Vault and TUF Metadata Storage

• :ref:`devel/design:Repository Service TUF Worker` implements and manages the Key Vault and Storage Services.
  • Access to the Key Vault Service is restricted to :ref:`devel/design:Repository Service TUF Worker` (read-only).
  • Writing the TUF Metadata in the Storage Service is limited to :ref:`devel/design:Repository Service TUF Worker`.
  • The Storage Service is the only public data.

RSTUF Components Design

Repository Service TUF API

• Integration (add/remove artifacts)
• TUF metadata process (bootstrap, sign, update, etc)

Note

The service can implement other features without interfering with the RSTUF principles and architecture design principles.

See API component development documentation.

Repository Service TUF Worker

• Manages the TUF metadata
• Manages the Key Vault and Storage Services

Note

The service can implement other features without interfering with the RSTUF principles and architecture design principles.

See Worker component development documentation.

Repository Service TUF CLI

• Command Line Interface for the API
• Guide users in the processes

Note

The service can implement other features without interfering with the RSTUF principles and architecture design principles.

See component development documentation.

RSTUF Infrastructure Services Design

The Infrastructure Services supports the RSTUF Components operation.

Message Queue

• It is a centralized queue service for tasks.
• This queue is used as Broker by Celery.
• :ref:`devel/design:Repository Service TUF Worker` and :ref:`devel/design:Repository Service TUF API` define the supported Queue servers.

Backend Result

• It is a centralized backend result used by Celery for task results.
• :ref:`devel/design:Repository Service TUF Worker` and :ref:`devel/design:Repository Service TUF API` define the supported Queue servers.

Redis

• It is a centralized key/cache service.

• Stores :ref:`devel/design:RSTUF Repository Settings/Configuration`

• Optional:

  • Used as :ref:`devel/design:Message Queue`.

  • Used as :ref:`devel/design:Backend Result`.

    Note

    See :ref:`guide/deployment/planning/deployment:Required Infrastructure Services`

PostgreSQL

• Stores :ref:`devel/design:Target Files and Target Roles`