Admiral

Concepts

Sources

A source is one upstream location with a standing grant: a git repository, a Helm repository, an OCI namespace or a Terraform registry namespace, what it may publish, and whether it publishes on push.

A source is one upstream location Admiral may read: a git repository, a Helm repository, an OCI registry namespace or a Terraform registry namespace, with the grant that reaches it and a bound on what may come in. An organization's sources are curated by its admins. Importing a component through a source, or publishing one on push, is what the source is for.

One location, one grant

A source has:

  • a kind, the protocol: git, helm, oci or terraform
  • a location, the narrowest thing the protocol addresses: one repository, one chart repository, one registry namespace. Never a bare host or a whole GitHub organization. The location is immutable, because a published version records the source it came through.
  • exactly one grant: a credential the organization holds, or for a GitHub repository, Admiral's GitHub App installed on the account
  • allows, the artifacts or paths that may come in: exact names, or a prefix with a trailing *; * alone allows everything
  • a trigger: on request, when someone imports through it; or on push, when the GitHub App publishes what the repository declares
KindLocationArtifacts are
githttps://github.com/acme/paymentspaths in the repository; versions are its tags and branches
helmhttps://charts.jetstack.iocharts the repository's index lists
ocioci://ghcr.io/argoproj/argo-helmnames under the namespace
terraformregistry.opentofu.org/terraform-aws-modulesname/provider under the namespace

Only a git repository reached through the GitHub App can publish on push, and a push source names the branches it listens to. One push source per repository.

A source is ready while its grant reaches its location. When the App is uninstalled, the repository leaves the installation, or a credential is rotated away, the source needs attention and says why; it is fixed in place, never recreated.

What a source offers

A source answers what its upstream offers: a Helm repository or registry namespace lists its artifacts within what the source allows, a container registry takes a name, and a git repository lists its tags and branches. Admiral reads the upstream through a cache and refreshes it on read when it is older than two hours. A read says when the upstream was last read, and after a failure, what it offered before and why the refresh failed. Nothing polls an upstream in the background.

Importing through a source

Adding a component from a source picks the source, then an artifact, then a version exactly as the source lists it. No credential rides the request: picking the source is picking the grant. The version is exact; latest on an import is a tag literally named latest, never a keyword. A branch is imported at its tip, and the version does not follow it.

admiral component import --from jetstack cert-manager --version v1.16.2
admiral component import --from infra modules/vpc --version v2.1.0

In a terminal, a missing artifact or version is asked from the source's list, with nothing pre-selected. The published version records the source it came through.

A component can also be imported by address, without a source, naming the credentials that import may present. See Registry.

Publishing on push

A push source publishes every component its repository's admiral.yaml declares when a listened branch is pushed, and plans a pull request's head where its base branch is followed. See Branches & Pull Requests.

# admiral.yaml at the repository root
components:
  - path: modules/payments
  - path: modules/network_hub
    name: network-hub

A declared path outside what the source allows is refused, component by component; the push goes on. A push source publishes to an existing name only when that name was first published through it.

Credentials

A credential is a stored, encrypted secret the organization holds. It is one of a source's two grants, and an import by address may present it. Credentials are typed by mechanism, not by provider:

TypeHoldsFits
SSH keya private key, and optionally its passphrasea git repository over SSH
Basic autha username and passworda Helm repository, an OCI registry
Bearer tokena tokena Helm repository, an OCI registry, a Terraform registry
GitHub Appan App of your own, its installation and keya git repository over HTTPS

A credential may name the hosts it is allowed to reach, and it is presented only to those. A fetch that reaches a host no attached credential covers fails naming the host. Secrets are encrypted at rest with envelope encryption, decrypted only to fetch, and never shipped to an agent.

A credential or integration a source names cannot be deleted while the source exists.

Where to go next

On this page