Skip to content

Import a snapshot from a tar archive

Record a tar archive as an AWC snapshot. The manifest stores the source kind as tar and records the imported directory path as the locator.

AWC does not ingest a tar stream

--source-type tar only sets the source kind in the manifest. AWC does not read, extract, or stream a tar archive today. The import code path is the same as a directory import. You MUST extract the archive yourself first.

The source.locator points at the extracted directory, not at the archive. source.immutable_revision is always null. Record the archive name or digest in a label instead.

Before you start

  • Set AWC_TENANT and AWC_PROJECT, or pass --tenant and --project. Snapshot create requires both (spec §13.3).
  • Configure an object store. Export AWC_CAS_URL, or pass --object-store-endpoint. The value must start with memory:// or s3://.

Procedure

  1. Extract the archive to a local directory.
mkdir extracted
tar -xf backend-build-42.tar -C extracted

The directory is what AWC imports. The archive itself is not recorded as a path in the manifest.

  1. Import the directory and record Tar provenance.
awcctl snapshot create \
  --from-dir extracted \
  --source-type tar \
  --name backend-build-42 \
  --label archive=backend-build-42.tar

--source-type tar sets the manifest source kind to tar. The default normalization is source-normalized (spec §9.8). It zeroes owner, group, and mtime, and keeps file type plus the executable bit. Pass --normalization environment-preserving to keep captured modes and mtimes. The command prints the snapshot id and a state of VALIDATING.

  1. Poll the snapshot until it reaches READY.
awcctl snapshot inspect snap_01J...

A worker validates object closure, then advances the state VALIDATING -> READY (spec §13.5, §12.1). The snapshot is mountable only at READY.

  1. Confirm the manifest records the Tar source kind.
awcctl snapshot inspect snap_01J...

Read the source line. It shows kind: tar and locator set to the extracted directory path. immutable_revision is null today.

See also