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,ociorterraform - 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
| Kind | Location | Artifacts are |
|---|---|---|
git | https://github.com/acme/payments | paths in the repository; versions are its tags and branches |
helm | https://charts.jetstack.io | charts the repository's index lists |
oci | oci://ghcr.io/argoproj/argo-helm | names under the namespace |
terraform | registry.opentofu.org/terraform-aws-modules | name/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.0In 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-hubA 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:
| Type | Holds | Fits |
|---|---|---|
| SSH key | a private key, and optionally its passphrase | a git repository over SSH |
| Basic auth | a username and password | a Helm repository, an OCI registry |
| Bearer token | a token | a Helm repository, an OCI registry, a Terraform registry |
| GitHub App | an App of your own, its installation and key | a 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
Projects & Components
Admiral's ownership hierarchy: projects group environments like dev and prod, and each component is the per-environment desired state you own and change.
Registry
Publish a repository you own, or pull a copy of an artifact you do not. Revisions are content-addressed, and tags are labels on those revisions.