Documentation
¶
Overview ¶
Package oci is a minimal OCI Distribution Spec v2 client: enough to pull a manifest and its blobs (with optional bearer/basic auth), and to push a manifest with its blobs.
Index ¶
- Constants
- Variables
- func ClearSRVCache()
- func IsSRVHost(h string) bool
- type Client
- func (c *Client) DescribeManifest(ref *Ref) (ocispec.Descriptor, error)
- func (c *Client) PullBlob(ref *Ref, d digest.Digest, w io.Writer) (int64, error)
- func (c *Client) PullManifest(ref *Ref) (*ocispec.Manifest, []byte, error)
- func (c *Client) PullManifestForPlatform(ref *Ref, osName, arch string) (*ocispec.Manifest, []byte, error)
- func (c *Client) PushBlob(ref *Ref, data []byte) (digest.Digest, error)
- func (c *Client) PushIndex(ref *Ref, idx *ocispec.Index) (digest.Digest, error)
- func (c *Client) PushManifest(ref *Ref, m *ocispec.Manifest) (digest.Digest, error)
- type Endpoint
- type Ref
Constants ¶
const ( MediaTypeConfig = "application/vnd.cloud-boot.boot.config.v1+json" MediaTypeKernel = "application/vnd.cloud-boot.kernel.v1" MediaTypeInitrd = "application/vnd.cloud-boot.initrd.v1" MediaTypeCmdline = "application/vnd.cloud-boot.cmdline.v1" MediaTypeModules = "application/vnd.cloud-boot.modules.v1.cpio+gzip" // MediaTypeModloop carries a raw squashfs blob (Alpine's // modloop-virt or any distro equivalent). cloud-boot-init exposes // it as `modloop=<oci-blob-url>` on the target kernel's cmdline so // the init script can wget + loop-mount it. The squashfs stays in // the registry — no client-side download. MediaTypeModloop = "application/vnd.cloud-boot.modloop.v1+squashfs" // MediaTypeApkovl carries an Alpine apkovl (system overlay tar.gz). // cloud-boot-init injects `apkovl=<oci-blob-url>` into the target // kernel's cmdline so Alpine's init can wget + untar it over the // new root, then apk-installs the packages listed in // etc/apk/world. The overlay turns a barebones netboot kernel into // a fully-functional Alpine system at first boot. MediaTypeApkovl = "application/vnd.cloud-boot.apkovl.v1+tar.gz" // MediaTypeSquashfs carries Debian / Ubuntu live's // `filesystem.squashfs` (or any distro equivalent — Kali, Tails, // Mint use the same shape). cloud-boot-init exposes it as // `fetch=<oci-blob-url>` on the target kernel's cmdline so // live-boot's initrd (Debian's `live-boot` package) downloads it // at switch_root time and loop-mounts it as the read-only rootfs. // Squashfs stays in the registry — no client-side download. MediaTypeSquashfs = "application/vnd.cloud-boot.squashfs.v1" MediaTypePlan = "application/vnd.cloud-boot.plan.v1+hcl" )
Custom artifact media types for kernel/initrd/cmdline/modules/plan blobs.
Variables ¶
var SRVCacheTTL = 30 * time.Second
SRVCacheTTL controls how long resolved SRV results are cached. Zero disables caching. Modify via the package init or tests; it is not part of the public API.
Functions ¶
func ClearSRVCache ¶
func ClearSRVCache()
ClearSRVCache wipes the in-memory SRV cache. cloud-boot-init calls this after rewriting /etc/resolv.conf so the next ResolveEndpoints re-queries against the new resolver instead of returning a stale result resolved via the old DNS.
Types ¶
type Client ¶
type Client struct {
HTTP *http.Client
Username string
Password string
// BearerToken, when non-empty, is sent as
// `Authorization: Bearer <BearerToken>` on every request,
// short-circuiting the Docker Registry V2 token negotiation.
// Use case: the operator already has a token from an external
// auth flow (e.g. Keystone application-credential exchange)
// and wants the OCI client to reuse it across all registry
// hosts the plan references. Empty = fall through to the
// existing per-host fetchBearer / Basic auth paths.
BearerToken string
// contains filtered or unexported fields
}
Client is an OCI v2 client.
func NewClient ¶
func NewClient() *Client
NewClient builds a client with sensible defaults. Auth is read from env REGISTRY_USERNAME / REGISTRY_PASSWORD if not set explicitly.
HTTP/2 behaviour:
- https:// targets negotiate HTTP/2 via ALPN automatically (Go's default Transport already does this when h2 is offered by the peer). No code change required for HTTPS registries.
- http:// (plaintext) targets default to HTTP/1.1. Set the env var REGISTRY_HTTP2_CLEARTEXT=1 to opt into HTTP/2 over plaintext (h2c, RFC 7540 §3.4). This is what local cloud-boot test registries on 127.0.0.1:5000 typically run on; Docker Distribution v3.0+ accepts h2c connections.
The h2c transport keeps a tiny manual dialer that just dials TCP and returns the conn unwrapped — http2 then runs its own framing directly on the TCP stream (no TLS, no upgrade dance).
func (*Client) DescribeManifest ¶
func (c *Client) DescribeManifest(ref *Ref) (ocispec.Descriptor, error)
DescribeManifest returns a descriptor (mediaType, digest, size) for the manifest at ref — used to assemble an index from already-pushed manifests.
func (*Client) PullManifest ¶
PullManifest fetches and decodes the image manifest at ref. It will NOT dereference an index; use PullManifestForPlatform for multi-arch repos.
func (*Client) PullManifestForPlatform ¶
func (c *Client) PullManifestForPlatform(ref *Ref, osName, arch string) (*ocispec.Manifest, []byte, error)
PullManifestForPlatform fetches the manifest at ref; if it is an index it picks the manifest matching (osName, arch) and refetches it.
func (*Client) PushBlob ¶
PushBlob uploads a blob via POST(start) + PUT(complete) (monolithic upload).
type Endpoint ¶
type Endpoint struct {
Host string // "host" or "host:port"
}
Endpoint is one concrete OCI server endpoint resolved from an SRV record (or a passthrough for non-SRV hosts).
Source Files