oci

README

oci

Name

oci - pull OCI artifacts from repositories

Description

oci pulls an OCI artifact into the site using the oras Go SDK. This makes it possible to deploy your zones with a simple oci pull.

The oci plugin starts a service routine that runs during the lifetime of the server. When the service starts, it pulls the artifacts from the repository.

If a pull fails, the service will retry up to three time. Each request will additionally try 3 times if certain response are returned by the repository.

NOTE: This plugin makes use of oras' retry client and will attempt additional retries for each attempt. See oras/registry/remote/retry for the default retry policy.

If the pull was not successful by then, it won't try again until the next interval.

This plugin is inspired by MiekG's git plugin and borrows some syntax and logic.

Syntax

oci REPO [PATH]

• REPO is the URL to the repository

• PATH is the path, relative to site root, to pull the artifacts into; default is site root

This simplified syntax pulls the latest tag every 3600 seconds (1 hour) and only works for public repositories.

For more control or to use a private repository, use the following syntax:

oci [REPO PATH] {
  repo              REPO
  path              PATH
  username      USERNAME
  password      PASSWORD
  interval         INTERVAL
}

• REPO is the URL to the repository; only HTTP/S URLs (http(s):// must be ommitted) are supported.

• PATH is the path to pull the artifacts into; default is site root (if set). It can be absolute or relative (to site root). See the root plugin.

• INTERVAl is the number of seconds between pulls; default is 3600 (1 hour), minimum 5.

• USERNAME is the username to log into the remote repository.

• PASSWORD is the password to log into the remote repository`

• IMSECURE if set to "true" connects to the repository with plain HTTP

Examples

Public repository pulled into site root every hour:

example.org {
    root /etc/zones
    oci registry-1.docker.io/ganawaj/demo:0.0.2
}

Private repository pulled into "example.org" directory or /etc/zones/example.org

example.org {
    root /etc/zones
    oci registry-1.docker.io/ganawaj/demo:0.0.2 {
      path example.org
      username ganawaj
      password dckr_pat_THISISANEXAMPLE
      interval 10
    }
}

Local private repository with no authentication using plain HTTP. Tag latest is assummed.

example.org {
    root /etc/zones
    oci localhost:5000/ganawaj/demo {
      path example.org
      insecure true
    }
}

Full example using file plugin assuming demo pulls a db.example.org artifact

example.org {
    root /etc/zones

    oci registry-1.docker.io/ganawaj/demo:0.0.2 {
      path example.org
      username ganawaj
      password dckr_pat_THISISANEXAMPLE
      interval 10
    }

    file example.org/db.example.org
}

Also See

The root plugin for setting the root.

The git plugin for inspiration for this plugin.

The auto or file plugin for reading zone files from disk.

Documentation

Index

• Constants
• Variables
• func Start(a *Artifact, ctx context.Context)
• type Artifact
  • func (a *Artifact) Login(c context.Context) error
  • func (a *Artifact) Prepare() error
  • func (a *Artifact) Pull(c context.Context) error
  • func (a *Artifact) Setup() error
• type OCI
  • func (o OCI) Artifact(i int) *Artifact

Constants

const (

	// DefaultInterval is the minimum interval to delay before
	// requesting another oci fetch
	DefaultInterval time.Duration = time.Hour
)

Variables

var (
	DefaultBackoff = time.Second * 30
)

Functions

func Start

func Start(a *Artifact, ctx context.Context)

Start starts the artifact pull process in the background.

To attempt to respect the rate limits of the registry, a backoff of 30 seconds is used between retries if the pull fails or returns any errors.

Types

type Artifact

type Artifact struct {
	URL      string
	Interval time.Duration
	Path     string

	// registry, repository, and reference of the artifact
	Registry   string
	Repository string

	// tag or digest of the artifact
	// see https://pkg.go.dev/oras.land/oras-go/v2@v2.5.0/registry#ParseReference
	// for the format of the reference
	Reference string

	// credentials
	Credential auth.Credential
	// contains filtered or unexported fields
}

func (*Artifact) Login

func (a *Artifact) Login(c context.Context) error

Logs in to the registry if required

func (*Artifact) Prepare

func (a *Artifact) Prepare() error

Prepare prepares the artifact for use

func (*Artifact) Pull

func (a *Artifact) Pull(c context.Context) error

Pulls the artifact from the remote repository.

A background context is created with a default timeout of 30 seconds. The artifact is pulled with this context with a max retry count of 10.

During the pull the artifact is copied from the remote repository to a temporary memory store and then to a file store.

The artifact is pulled only if the user defined interval has passed since the last pull.

Users should be careful to respect the rate limits of the remote repository.

func (*Artifact) Setup

func (a *Artifact) Setup() error

Parses and creates the remote repository based on the URL

type OCI

type OCI []*Artifact

func (OCI) Artifact

func (o OCI) Artifact(i int) *Artifact