Documentation
¶
Overview ¶
Package oras - auth.go
registry への pull 時に使う credential を解決する。 優先順位:
- spec.manifests[].oras.auth の override (username/password どちらかが非空)
- docker config.json 由来の credential (credentials.NewStoreFromDocker)
- anonymous (auth.EmptyCredential)
Package oras はOCI registry (ORAS) からpullしたartifactを ローカルに展開し、helmfile / kustomize manager に委譲するための機能を提供します。
このファイルでは pullした tar.gz artifact を安全にローカルディレクトリへ 展開する `Extract` を実装します。詳細は docs/adr/004-oras-manager.md を参照。
Package oras - oras.go ¶
ORAS は OCI registry から artifact を pull し、tar.gz layer を展開した ローカルディレクトリを helmfile / kustomize manager に委譲する Manager 実装。
詳細は docs/adr/004-oras-manager.md および oras-manager-roadmap.md (commit 5) を参照。
Package oras - puller.go ¶
registry から OCI artifact を pull し、tar.gz layer を extractor で展開してローカルキャッシュに格納する。 digest ベースでキャッシュを共有するため、同一 digest の 2 回目以降の pull はネットワークアクセスを伴わない。
詳細は docs/adr/004-oras-manager.md および oras-manager-roadmap.md (commit 4) を参照。
Index ¶
- func Extract(r io.Reader, destDir string) error
- func ExtractWithLimits(r io.Reader, destDir string, limits Limits) error
- type CredentialResolver
- type DelegateManager
- type Limits
- type ORAS
- func (o *ORAS) Apply(ctx context.Context, logger *slog.Logger, m v1.Manifest) (objects []client.Object, retErr error)
- func (o *ORAS) Build(ctx context.Context, logger *slog.Logger, m v1.Manifest) (result string, retErr error)
- func (o *ORAS) Destroy(ctx context.Context, logger *slog.Logger, m v1.Manifest) (retErr error)
- type PullOptions
- type PullResult
- type Puller
- type RepositoryFactory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CredentialResolver ¶
type CredentialResolver struct {
// contains filtered or unexported fields
}
CredentialResolver は ORAS pull 時の認証解決を行います。 プロセス内で共有する auth.Cache を 1 個保持し、 複数 manifest の並列 pull 時に token 再取得を抑制する目的で利用します。
func NewCredentialResolver ¶
func NewCredentialResolver() (*CredentialResolver, error)
NewCredentialResolver は docker config.json を読み込む Resolver を返します。 $DOCKER_CONFIG 環境変数が設定されていれば oras-go がそちらを参照します。
func NewCredentialResolverWithStore ¶
func NewCredentialResolverWithStore(store credentials.Store) *CredentialResolver
NewCredentialResolverWithStore は任意の credentials.Store を注入した Resolver を返します。 テスト用、あるいは docker config を参照したくないケースで利用します。 store が nil の場合は常に anonymous を返します。
func (*CredentialResolver) Cache ¶
func (r *CredentialResolver) Cache() auth.Cache
Cache は manager 単位で共有する auth.Cache を返します。 Puller がこれを oras-go の auth.Client.Cache に渡すことで、 同一 registry への複数 pull で token 再取得を抑制します。
func (*CredentialResolver) Resolve ¶
func (r *CredentialResolver) Resolve(ctx context.Context, registry string, override *v1.ORASAuth) (auth.Credential, error)
Resolve は registry に対する credential を解決します。
優先順位:
- override が非 nil かつ Username/Password の少なくとも一方が非空 → override をそのまま返す
- store が非 nil → store.Get の結果を返す (該当エントリが無い場合は anonymous)
- それ以外 → anonymous (auth.EmptyCredential)
override が非 nil でも両フィールドが空の場合は意図しない anonymous 化を防ぐため store フォールバックに進みます。
type DelegateManager ¶
type DelegateManager interface {
Apply(ctx context.Context, logger *slog.Logger, m v1.Manifest) ([]client.Object, error)
Destroy(ctx context.Context, logger *slog.Logger, m v1.Manifest) error
Build(ctx context.Context, logger *slog.Logger, m v1.Manifest) (string, error)
}
DelegateManager は ORAS が委譲する先のサブマネージャが満たすべき interface。 pkg/manager.Manager と同一シグネチャのため、commit 6 で *manager.Helmfile / *manager.Kustomize をそのまま注入できる。
親パッケージ pkg/manager から pkg/manager/oras を import する想定 (commit 6) のため、 循環依存を避ける目的でローカルに interface を再定義している。
type Limits ¶
type Limits struct {
// MaxTotalBytes は展開後のファイル合計サイズの上限 (bytes) です。
MaxTotalBytes int64
// MaxEntries は tar entry 数の上限です。
MaxEntries int
}
Limits は extract 時のリソース上限を表します。 テストや統合テストから上書きできるよう構造体として公開しています。
type ORAS ¶
type ORAS struct {
// contains filtered or unexported fields
}
ORAS は OCI registry からの pull と委譲先 manager の呼び出しを束ねる Manager 実装。
func New ¶
func New(puller Puller, helmfile, kustomize DelegateManager) *ORAS
New は デフォルトの PullOptions で ORAS を生成します。
func NewWithOptions ¶
func NewWithOptions(puller Puller, helmfile, kustomize DelegateManager, opts PullOptions) *ORAS
NewWithOptions は明示的な PullOptions を伴う ORAS を生成します。 CLI フラグ (--no-cache / --offline / --cache-dir) からの値を渡すために使います。
func (*ORAS) Apply ¶
func (o *ORAS) Apply(ctx context.Context, logger *slog.Logger, m v1.Manifest) (objects []client.Object, retErr error)
Apply は artifact を pull し、委譲先 manager の Apply を呼びます。 委譲先が返す render 済みオブジェクトをそのまま透過的に返します。
type PullOptions ¶
type PullOptions struct {
// NoCache は true の場合、キャッシュを無視して必ず registry から再取得します。
NoCache bool
// Offline は true の場合、registry へのアクセスを禁止し、
// キャッシュミス時はエラーを返します。
Offline bool
// CacheDir は明示的なキャッシュディレクトリを指定します。
// 空の場合は $XDG_CACHE_HOME/tazuna/oras (未設定なら $HOME/.cache/tazuna/oras) を使用します。
CacheDir string
}
PullOptions は Pull の挙動を制御するオプションです。
type PullResult ¶
type PullResult struct {
// LocalPath は展開先ディレクトリの絶対パスです。
// 呼び出し側はこのパス配下に対して spec.Target でサブパスを解決します。
LocalPath string
// Digest は解決済みの manifest digest (例: "sha256:abc...") です。
Digest string
}
PullResult は Pull の成功時の戻り値です。
type Puller ¶
type Puller interface {
Pull(ctx context.Context, logger *slog.Logger, spec v1.ManifestORAS, opts PullOptions) (PullResult, error)
}
Puller は registry から artifact を pull するコンポーネントです。
func NewCachingPuller ¶
func NewCachingPuller(factory RepositoryFactory) Puller
NewCachingPuller は cachingPuller を返します。 limits は extractor のデフォルト (1 GiB / 10000 entries) を使用します。
func NewCachingPullerWithLimits ¶
func NewCachingPullerWithLimits(factory RepositoryFactory, limits Limits) Puller
NewCachingPullerWithLimits はテスト用に展開上限を差し替え可能にした cachingPuller を返します。
type RepositoryFactory ¶
type RepositoryFactory func(ctx context.Context, spec v1.ManifestORAS) (oras.ReadOnlyTarget, error)
RepositoryFactory は spec に対応する pull 対象 store を返します。 production では remote.Repository を、テストでは memory.Store などを返すことで Puller の単体テストを net/registry 非依存にします。
func NewRemoteRepositoryFactory ¶
func NewRemoteRepositoryFactory(resolver *CredentialResolver) RepositoryFactory
NewRemoteRepositoryFactory は remote.Repository を生成する production 用の RepositoryFactory を返します。CredentialResolver を共有することで、 複数 manifest にまたがる auth.Cache の再利用が可能になります。
resolver が nil の場合は anonymous アクセスのみ可能です。
Source Files