Skip to main content

Artifact Kinds

An artifact kind says what the content means. Every kind publishes through the same command, the same repositories, and the same signatures; a kind only adds the validation and the default exclusions that suit its content.

Experimental

Choose the kind with atmos artifacts publish --kind=<kind>. Convenience commands supply their own kind, so atmos scaffold publish needs no --kind. The kind is independent of the repository kind: a scaffold publishes equally to a local directory, an S3 bucket, or an OCI registry.

files (default)

Any file or directory. Nothing is validated and nothing is excluded, which makes it the right kind for backups, configuration, modules, and any tree that no other kind describes. Generic publishing never inherits the exclusions of another kind.

scaffold

A scaffold template directory. The producer validates scaffold.yaml at the source root without generating output or running scaffold hooks, and takes the default name, version, and description from the manifest. It excludes nothing.

component/terraform

A Terraform root module. The producer leaves out Terraform working directories, state, and saved plans, and records the component type in the Record's kind data. Publishing never runs Terraform and needs no stack.

Scaffolds​

atmos scaffold publish ./scaffolds/landing-zone --repository=shared validates the manifest and publishes the directory. See atmos scaffold publish for the name and version precedence, the two README roles, and the errors.

The root README.md is part of the scaffold and keeps its generation behavior. The reserved .atmos/artifact/ directory holds the package README.md and CHANGELOG.md. It is distribution metadata, so scaffold generation and updates never write it, from a published release or from a plain directory.

Terraform Components​

atmos artifacts publish ./components/terraform/vpc \
--repository=shared --name=components/terraform/vpc --version=1.2.0 --kind=component/terraform

The component/terraform producer applies these default exclusions at any depth below the source:

.terraform/**
Every .terraform directory and its contents: downloaded providers and modules, and backend initialization data.
*.tfstate and *.tfstate.*
State files and their backups, including the terraform.tfstate.d workspace directory.
*.tfplan and *.tfplan.*
Saved plan files and their JSON renderings.

The dependency lock file .terraform.lock.hcl stays in the payload, because it belongs to the component. Scripts keep their executable bits. A root README.md is ordinary content, and .atmos/artifact/README.md and .atmos/artifact/CHANGELOG.md become the package documents.

Every exclusion is visible. A dry run, like a real publication, reports each excluded entry with the rule that excluded it as an excluded entry in the result's diagnostics, so you see what the package leaves out before anything is written:

atmos artifacts publish ./components/terraform/vpc --repository=shared \
--name=components/terraform/vpc --version=1.2.0 --kind=component/terraform --dry-run

The exclusions belong to the component/terraform kind only. Publish the same directory with the default files kind, for example as a backup of a working directory, and every requested file is kept.

The component name has no default beyond the source basename, and the version is always explicit. The metadata.name in a component.yaml names the vendoring manifest and its source.version is the upstream version, so neither describes the component you are publishing.

Other Trees​

Terraform modules, stack and configuration trees, and any other directory publish as files. Atmos does not add provider-cache, module-cache, or export adapters for them.

Consuming Published Packages​

Existing consumers read a published package through its oci:// reference, for example oci://registry.example.com/acme/atmos/components/terraform/vpc:1.2.0:

  • Component source provisioning (a component source with an oci:// URI), vendoring, and atmos scaffold generate fetch the package's payload layer and nothing else. The README and CHANGELOG blobs are never unpacked, and the .atmos/artifact/ distribution files never reach the provisioned component or the generated project.
  • Executable bits survive, and .terraform.lock.hcl arrives with the component.
  • Images published before artifacts existed, such as single-layer component images and OpenTofu module packages, extract exactly as they did.
  • atmos artifacts show reads a package README or CHANGELOG from its own blob without downloading the payload.