ORAS Go

ORAS Go v3 introduces several significant architectural improvements and new capabilities:

• Unified configuration: registry/remote/config.LoadConfigs can load Docker credentials, containers auth.json, registries.conf, policy.json, registries.d, and certificate directories. It follows the containers/image default path strategy, with an experimental UAPI strategy also available.
• Configured clients: remote.ClientBuilder is used to construct clients, registries, and repositories with support for TLS, retries, credentials, token flow, warnings, logging, policy, and mirror settings.
• Registry mirrors: Repositories created from registry properties will attempt to use applicable mirrors for read operations, falling back to the primary registry if necessary. Writes always target the primary registry.
• Policy and signatures: The registry/remote/policy package enforces allow/deny policies, while registry/remote/signature verifies OpenPGP simple signatures using registries.d lookaside storage.
• Content caching: content/cache.CacheReadOnlyTarget wraps a read-only target with a content store. content/cache.NewFromEnv allows configuration via the ORAS_CACHE environment variable.
• Hierarchical credential matching: Setting credentials.StoreOptions.Hierarchical enables longest-prefix namespace matching when reading credentials from plaintext config files (compatible with containers auth.json used by Podman/Buildah).
• HTTP diagnostics: remote.NewLoggingTransport provides slog-based debug logging featuring sensitive-header redaction and bounded response bodies.
• Tag deletion: remote.Repository.Untag allows deleting a tag without deleting the referenced manifest.
• Copy diagnostics and policy: oras.CopyError.Descriptor identifies failing content during copy operations, and oras.CopyOptions.PolicyCheck can reject a copy before content transfer begins.

When an artifact is signed (e.g., using notation), a signature manifest is created. This signature manifest acts as a Referrer to the original artifact.

• Subject Field: The signature manifest contains a subject field that points to the digest of the target artifact manifest.
• Graph Relationship: In the resulting DAG, the signature manifest becomes the root for the combined graph, while the original artifact manifest remains the root of its own subgraph. They may share nodes (like config blobs) if they are identical.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.cncf.notary.signature",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  "layers": [
    {
      "mediaType": "application/jose+json",
      "digest": "sha256:37f88486592fd90ace303ee38f8d1ff698193e76c76d3c1fef8627a39e677696",
      "size": 2090
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "digest": "sha256:314c7f20dd44ee1cca06af399a67f7c463a9f586830d630802d9e365933da9fb",
    "size": 762
  },
  "annotations": {
    "io.cncf.notary.x509chain.thumbprint#S256": "[\"a9c85558943f197f41fe7cf3caf691f7df8d0088be426a33d895560717893962\"]",
    "org.opencontainers.image.created": "2025-02-01T09:50:52Z"
  }
}

In oras-go v2, artifacts are modeled as Directed Acyclic Graphs (DAGs) stored in Content-Addressable Storages (CASs).

Descriptors

Every node in the graph is a descriptor which must contain:

• mediaType: The media type of the referenced content.
• digest: The digest of the targeted content.
• size: The size in bytes of the raw content.

Core Interfaces

oras-go v2 uses four primary interfaces to manage these graphs and content:

1. Storage: A basic CAS for accessing content via descriptors.
2. GraphStorage: An extension of Storage that allows finding predecessors (nodes pointing to a specific node).
3. Target: A CAS that supports tagging (associating a tag string with a descriptor) and resolving tags to descriptors.
4. GraphTarget: The most comprehensive interface, combining GraphStorage and Target capabilities.

In v3, configuration is reorganized: a remote.Registry owns shared settings (like HTTP client, plain-HTTP, and metadata limits), while remote.Repository points to its parent registry and handles per-repository overrides (like media types and page sizes).

Key Changes:

• Shared settings like Client, PlainHTTP, MaxMetadataBytes, and HandleWarning move from remote.Repository to remote.Registry.
• repo.Reference is now a read-only method repo.Reference() that returns only the registry and repository name. It no longer holds tags or digests.
• To handle references with tags or digests, use properties.NewReference.
• Use remote.NewRegistryWithProperties or remote.NewRepositoryWithProperties when configuration comes from external files (e.g., registries.conf or Docker config).

Example Migration:

// v2 pattern
repo, err := remote.NewRepository("localhost:5000/example")
if err != nil {
	return err
}
repo.Client = client
repo.PlainHTTP = true
ref := repo.Reference

// v3 pattern
repo, err := remote.NewRepository("localhost:5000/example")
if err != nil {
	return err
}
repo.Registry.Client = client
repo.Registry.PlainHTTP = true
ref := repo.Reference()

Credential management has moved from registry/remote/auth to registry/remote/credentials.

Key Changes:

• auth.Credential $\rightarrow$ credentials.Credential.
• auth.StaticCredential $\rightarrow$ credentials.StaticCredentialFunc.
• auth.Client.Credential $\rightarrow$ auth.Client.CredentialFunc.
• Scope functions (e.g., WithScopes, AppendScopes, GetScopes) are now host-specific. You must pass the registry host (e.g., from properties.Reference.Host()) to these functions.
• credentials.Store methods now use credentials.Credential types.

Example Migration (Static Credentials):

// v2
client := &auth.Client{
	Credential: auth.StaticCredential("registry.example.com", auth.Credential{
		Username: "user",
		Password: "password",
	}),
}

// v3
client := &auth.Client{
	CredentialFunc: credentials.StaticCredentialFunc(
		"registry.example.com",
		credentials.Credential{
			Username: "user",
			Password: "password",
		},
	),
}