varakh/upda
1
0
Fork 0
Code Issues 1 Pull requests 4 Releases 10 Packages 1 Activity Actions
upda/_doc/Concepts.md
Varakh 3f654a1229
All checks were successful
/ build (pull_request) Successful in 5m27s
Details
feat(embedded_ui): fully integrate UI into GoLang binary
2024-10-25 08:27:58 +02:00

2.9 KiB
Raw Blame History

Concepts, a deeper dive

The following section goes into a deeper look into upda's internals.

  1. Create a webhook in upda.
  2. Use the webhook's URL in a 3rd party application to start tracking an update or use upda-cli to report an update.
  3. Enjoy visualization and state management of tracked updates in one place.
  4. Optionally, define Actions for tracked updates as they arrive

upda retrieves new updates when webhooks of upda are invoked, e.g., duin invokes it or any other application which can reach the instance. Tracked updates are unique for the attributes (application,provider,host) which means that subsequent updates for an identical application, provider and host simply updates the version and metadata attributes for that tracked update (regardless if the version or metadata payload actually changed - reasoning behind this is to get reflected metadata updates independent if version attribute has changed).

State management of tracked updates:

  • On first creation, state is set to pending.
  • When an update is in approved state, an invocation for it resets its state to pending.
  • Ignored updates are skipped entirely and no attribute is updated.
The application attribute

The application attribute is an arbitrary identifier, name or label of a subject you like to track, e.g., docker.io/varakh/upda for an OCI image.

The provider attribute

The provider attribute is an arbitrary name or label. During webhook invocation the provider attribute is derived in priority:

For the generic webhook:

  1. If the incoming payload contains a non-blank provider attribute, it's taken from the request.
  2. If the incoming payload contains a blank or missing provider attribute, the issuing webhook's label is taken.

For the diun webhook:

  1. If the issuing webhook's label is blank, then oci is used.
  2. In any other case, the webhook's label is used.

Because the first priority is the issuing webhook's label, setting the same label for all webhooks results in a grouping. Also see the ignore host setting for host below.

Remember that changing a webhook's label won't be reflected in already created/tracked updates!

The host attribute

host should be set to the originating host name a webhook has been issued from. The host attribute can also be "ignored" (a setting in each webhook). If set to ignored, upda sets host to global, thus update versions can be grouped independent of the originating host. If set for all webhooks, you'll end up with a host independent update dashboard.

The version attribute

The version attribute is an arbitrary name or label and subject to change across invocations of webhooks. This can be a version number, a number of total updates, anything.

The metadata attribute

An update can hold any additional metadata information provided by request payload metadata. Metadata can be inspected via web interface or API.