Documentation
¶
Overview ¶
Package oci provides OCI artifact management for Kubernetes workloads.
This package handles building, packaging, and pushing Kubernetes manifests as OCI artifacts to container registries. It supports collecting YAML/JSON manifests from a directory, bundling them into an OCI-compliant layer, and pushing the resulting artifact to a registry endpoint.
Key functionality:
- Manifest collection from directories (.yaml, .yml, .json files)
- OCI artifact packaging using go-containerregistry
- Registry push operations with validation
- Build options validation and normalization
Example usage:
// Create a workload artifact builder
b := oci.NewWorkloadArtifactBuilder()
// Build and push an artifact
result, err := b.Build(ctx, oci.BuildOptions{
Name: "my-workload",
SourcePath: "./k8s/manifests",
RegistryEndpoint: "localhost:5000",
Repository: "ksail-workloads/app",
Version: "1.0.0",
})
if err != nil {
return err
}
// Access the resulting artifact metadata
fmt.Printf("Pushed artifact: %s/%s:%s\n",
result.Artifact.RegistryEndpoint,
result.Artifact.Repository,
result.Artifact.Tag)
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrSourcePathRequired indicates that no source path was provided in build options. ErrSourcePathRequired = errors.New("source path is required") // ErrSourcePathNotFound indicates that the provided source path does not exist. ErrSourcePathNotFound = errors.New("source path does not exist") // ErrSourcePathNotDirectory indicates that the provided source path is not a directory. ErrSourcePathNotDirectory = errors.New("source path must be a directory") // ErrRegistryEndpointRequired indicates that the registry endpoint is missing. ErrRegistryEndpointRequired = errors.New("registry endpoint is required") // ErrVersionRequired indicates that no version was provided. ErrVersionRequired = errors.New("version is required") // ErrNoManifestFiles indicates that the source directory does not contain manifest files. ErrNoManifestFiles = errors.New("no manifest files found in source directory") )
Build option validation errors.
Functions ¶
This section is empty.
Types ¶
type BuildOptions ¶
type BuildOptions struct {
// Name is the artifact name (defaults to repository's last segment if empty).
Name string
// SourcePath is the directory containing Kubernetes manifest files (required).
SourcePath string
// RegistryEndpoint is the registry host:port (required, protocol prefixes are stripped).
RegistryEndpoint string
// Repository is the repository path (defaults to source directory basename if empty).
Repository string
// Version is the artifact tag (required, can be any non-empty string such as "dev", "latest", or a semantic version).
Version string
// GitOpsEngine specifies the GitOps engine for which to optimize the artifact structure.
// When set to GitOpsEngineFlux, files are placed at the root.
// When set to GitOpsEngineArgoCD, files are placed under a prefix directory.
// When empty or GitOpsEngineNone, files are placed at both locations for compatibility (default).
GitOpsEngine v1alpha1.GitOpsEngine
}
BuildOptions capture user-supplied inputs for building an OCI artifact from manifest directories.
All fields are optional except SourcePath, RegistryEndpoint, and Version. Name and Repository default to source directory basename if not provided.
func (BuildOptions) Validate ¶
func (o BuildOptions) Validate() (ValidatedBuildOptions, error)
Validate normalizes and verifies the build options before artifact construction.
This method performs the following validation steps:
- Validates and resolves the source path to an absolute directory
- Normalizes and validates the registry endpoint
- Validates and normalizes the version (any non-empty string)
- Normalizes repository and artifact names using source path defaults
Returns ValidatedBuildOptions ready for use by the builder, or an error if validation fails.
type BuildResult ¶
type BuildResult struct {
// Artifact contains the complete OCI artifact metadata after successful push.
Artifact v1alpha1.OCIArtifact
}
BuildResult describes the outcome of a successful artifact build.
Contains the complete artifact metadata including registry coordinates and timestamps.
type ValidatedBuildOptions ¶
type ValidatedBuildOptions struct {
// Name is the normalized artifact name.
Name string
// SourcePath is the absolute path to the manifest directory.
SourcePath string
// RegistryEndpoint is the normalized registry host:port.
RegistryEndpoint string
// Repository is the normalized repository path.
Repository string
// Version is the validated version string.
Version string
// GitOpsEngine specifies the target GitOps engine for artifact structure optimization.
GitOpsEngine v1alpha1.GitOpsEngine
}
ValidatedBuildOptions represents sanitized inputs ready for use by the builder implementation.
All fields are guaranteed to be non-empty and properly formatted after validation.
type WorkloadArtifactBuilder ¶
type WorkloadArtifactBuilder interface {
// Build validates the supplied options, constructs an OCI artifact from manifests,
// and pushes it to the registry. Returns BuildResult with artifact metadata on success.
Build(ctx context.Context, opts BuildOptions) (BuildResult, error)
}
WorkloadArtifactBuilder packages Kubernetes manifests into OCI artifacts and pushes them to a registry.
Implementations validate build options, collect manifest files from the source directory, package them into an OCI-compliant image layer, and push the resulting artifact to the specified registry endpoint.
func NewWorkloadArtifactBuilder ¶
func NewWorkloadArtifactBuilder() WorkloadArtifactBuilder
NewWorkloadArtifactBuilder returns a concrete implementation backed by go-containerregistry.
The returned builder uses the go-containerregistry library to package manifests into OCI artifacts and push them to container registries.
Source Files