imagequalify

Documentation

Overview

Package imagequalify contains the OpenShift ImageQualify admission control plugin. This plugin allows administrators to set a policy for bare image names. A "bare" image name is a docker image reference that contains no domain component (e.g., "repository.io", "docker.io", etc).

The preferred domain component to use, and hence pull from, for a bare image name is computed from a set of path-based pattern matching rules in the admission configuration:

admissionConfig:

pluginConfig:
  openshift.io/ImageQualify:
    configuration:
      kind: ImageQualifyConfig
      apiVersion: admission.config.openshift.io/v1
      rules:
        - pattern: "openshift*/*"
          domain:  "access.redhat.registry.com"

        - pattern: "*"
          domain:  "access.redhat.registry.com"

        - pattern: "nginx"
          domain:  "nginx.com"

        - pattern: "repo/jenkins"
          domain:  "jenkins-ci.org"

Rule Ordering -------------

Rules are sorted into the set of all explicit patterns (i.e., those with no wildcards) and the set of wildcard patterns. In each set, the natural order is lexicographically by pattern {depth,digest,tag,path}. Pattern matching is first attempted against the explicit rules, then the wildcard rules.

As we use path-based pattern matching you should be aware of what looks like a fallback pattern to cover any bare image reference:

• pattern: "*"
• domain: "access.redhat.registry.com"

This pattern would not match "repo/jenkins" as the pattern contains no path segments (i.e., '/'). To match both cases you should list wildcard patterns that cover just image names and images in any repository.

• pattern: "*"

• domain: "access.redhat.registry.com"

• pattern: "*/*"

• domain: "access.redhat.registry.com"

Additionally, patterns can also reference tags:

• pattern: "nginx:latest" domain: "nginx-dev.com"

• pattern: "nginx:*" domain: "nginx-prod.com"

• pattern: "nginx:v1.2.*" domain: "nginx-prod.com"

• pattern: "next/nginx:v2*" domain: "next/nginx-next.com"

Additionally, patterns can also reference digests:

• pattern: "nginx@sha256:abc*" domain: "nginx-staging.com"

• pattern: "reppo/nginx:latest@sha256:abc*" domain: "nginx-staging.com"

The plugin is configured via the ImageQualifyConfig object in the origin and kubernetes master configs:

kubernetesMasterConfig:

admissionConfig:
  pluginConfig:
    openshift.io/ImageQualify:
      configuration:
        kind: ImageQualifyConfig
        apiVersion: admission.config.openshift.io/v1
        rules:
          - pattern: nginx
            domain: localhost:5000

Index

• func Register(plugins *admission.Plugins)
• type PatternParts
• type Plugin
  • func NewPlugin(rules []imagequalify.ImageQualifyRule) *Plugin
  • func (p *Plugin) Admit(attributes admission.Attributes) error
  • func (p *Plugin) Validate(attributes admission.Attributes) error

Functions

func Register

func Register(plugins *admission.Plugins)

Register creates and registers the new plugin but only if there is non-empty and a valid configuration.

Types

type PatternParts

type PatternParts struct {
	Depth  int
	Digest string
	Path   string
	Tag    string
}

PatternParts captures the decomposed parts of an image reference.

type Plugin

type Plugin struct {
	*admission.Handler
	// contains filtered or unexported fields
}

Plugin is an implementation of admission.Interface.

func NewPlugin

func NewPlugin(rules []imagequalify.ImageQualifyRule) *Plugin

NewPlugin creates a new admission handler.

func (*Plugin) Admit

func (p *Plugin) Admit(attributes admission.Attributes) error

Admit makes an admission decision based on the request attributes. If the attributes are valid then any container image names that are unqualified (i.e., have no domain component) will be qualified with domain according to the set of rules. If no rule matches then the name can still remain unqualified.

func (*Plugin) Validate

func (p *Plugin) Validate(attributes admission.Attributes) error

Validate makes an admission decision based on the request attributes. It checks that image names that got qualified in Admit() remain qualified, returning an error if this condition no longer holds true.