Documentation
¶
Overview ¶
Package oci handles pulling and pushing OCI plugin artifacts using ORAS.
Plugins are OCI artifacts containing skills, hooks, agents, and MCP server configurations. They are pulled to the local plugins directory before the klaus container is started, then bind-mounted into the container.
Index ¶
- Constants
- func IsCached(pluginDir string, digest string) bool
- func PluginDirs(plugins []config.Plugin) []string
- func PullPlugins(ctx context.Context, plugins []config.Plugin, pluginsDir string, w io.Writer) error
- func ShortPluginName(repository string) string
- func WriteCacheEntry(pluginDir string, entry CacheEntry) error
- type CacheEntry
- type Client
- func (c *Client) List(ctx context.Context, repository string) ([]string, error)
- func (c *Client) Pull(ctx context.Context, ref string, destDir string) (*PullResult, error)
- func (c *Client) Push(ctx context.Context, pluginDir string, ref string, meta PluginMeta) (*PushResult, error)
- func (c *Client) Resolve(ctx context.Context, ref string) (string, error)
- type ClientOption
- type PluginMeta
- type PullResult
- type PushResult
Constants ¶
const ( // MediaTypePluginConfig is the OCI media type for the plugin config blob. MediaTypePluginConfig = "application/vnd.giantswarm.klaus-plugin.config.v1+json" // MediaTypePluginContent is the OCI media type for the plugin content layer. MediaTypePluginContent = "application/vnd.giantswarm.klaus-plugin.content.v1.tar+gzip" )
Variables ¶
This section is empty.
Functions ¶
func IsCached ¶ added in v0.0.3
IsCached returns true if the plugin directory has a cache entry matching the given manifest digest.
func PluginDirs ¶
PluginDirs returns the container-internal mount paths for the given plugins. Each plugin is mounted at /var/lib/klaus/plugins/<shortName>.
func PullPlugins ¶
func PullPlugins(ctx context.Context, plugins []config.Plugin, pluginsDir string, w io.Writer) error
PullPlugins pulls all configured plugins to the local plugins directory. Each plugin is stored at <pluginsDir>/<shortName>/. Plugins are cached by digest and skipped if already up-to-date. Progress messages are written to w.
func ShortPluginName ¶
ShortPluginName extracts the last segment of a repository path. e.g. "gsoci.azurecr.io/giantswarm/klaus-plugins/gs-platform" -> "gs-platform"
func WriteCacheEntry ¶ added in v0.0.3
func WriteCacheEntry(pluginDir string, entry CacheEntry) error
WriteCacheEntry writes cache metadata to a plugin directory. The PulledAt timestamp is always set to the current time.
Types ¶
type CacheEntry ¶ added in v0.0.3
type CacheEntry struct {
// Digest is the OCI manifest digest.
Digest string `json:"digest"`
// Ref is the original OCI reference that was pulled.
Ref string `json:"ref"`
// PulledAt is when the plugin was last pulled.
PulledAt time.Time `json:"pulledAt"`
}
CacheEntry holds metadata about a cached plugin.
func ReadCacheEntry ¶ added in v0.0.3
func ReadCacheEntry(pluginDir string) (*CacheEntry, error)
ReadCacheEntry reads the cache metadata from a plugin directory.
type Client ¶ added in v0.0.3
type Client struct {
// contains filtered or unexported fields
}
Client is an ORAS-based client for interacting with OCI registries.
func NewClient ¶ added in v0.0.3
func NewClient(opts ...ClientOption) *Client
NewClient creates a new OCI client.
func (*Client) Pull ¶ added in v0.0.3
Pull downloads a plugin from an OCI registry and extracts it to destDir. If the plugin is already cached with a matching digest, the pull is skipped and PullResult.Cached is set to true.
func (*Client) Push ¶ added in v0.0.3
func (c *Client) Push(ctx context.Context, pluginDir string, ref string, meta PluginMeta) (*PushResult, error)
Push packages a plugin directory and pushes it to an OCI registry. The ref must include a tag (e.g. "registry.example.com/plugins/my-plugin:v1.0.0").
type ClientOption ¶ added in v0.0.3
type ClientOption func(*Client)
ClientOption configures the OCI client.
func WithPlainHTTP ¶ added in v0.0.3
func WithPlainHTTP(plain bool) ClientOption
WithPlainHTTP disables TLS for registry communication. This is useful for local testing with insecure registries.
type PluginMeta ¶ added in v0.0.3
type PluginMeta struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
Skills []string `json:"skills,omitempty"`
Commands []string `json:"commands,omitempty"`
}
PluginMeta holds metadata stored in the OCI config blob.
type PullResult ¶ added in v0.0.3
type PullResult struct {
// Digest is the resolved manifest digest.
Digest string
// Ref is the original reference string.
Ref string
// Cached is true if the pull was skipped because the local cache was fresh.
Cached bool
}
PullResult holds the result of a successful pull.
type PushResult ¶ added in v0.0.3
type PushResult struct {
// Digest is the manifest digest of the pushed artifact.
Digest string
}
PushResult holds the result of a successful push.
Source Files