Image Policy

You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see

You can control which images can be imported, tagged, and run in a cluster. There are two facilities for this purpose.

Allowed Registries for import is an image policy configuration that allows you to restrict image origins to particular set of external registries. This set of rules is applied to any image being imported or tagged into any image stream. Therefore any image referencing registry not matched by the rule set will be rejected.

lets you specify which images are allowed to be run on your cluster. This is currently considered beta. It allows you to control:

Image sources: which registries can be used to pull images
Image resolution: force pods to run with immutable digests to ensure the image does not change due to a re-tag
Container image label restrictions: limits or requires labels on an image
Image annotation restrictions: limits or requires the annotations on an image in the integrated container registry

You can configure registries allowed for import in master-config.yaml under section as demonstrated in the following example. If the setting is not present, all images are allowed, which is the default.

Example 1. Example Configuration of Registries Allowed for Import

Each rule is composed of the following attributes:

**domainName**: is a hostname optionally terminated by :<port> suffix where special wildcard characters (?, *) are recognized. The former matches a sequence of characters of any length while the later matches exactly one character. The wildcard characters can be present both before and after : separator. The wildcards apply only to the part before or after the separator regardless of separator’s presence.
**insecure**: is a boolean used to decide which ports are matched if the :<port> part is missing from **domainName**. If true, the **domainName** will match registries with :80 suffix or unspecified port as long as the insecure flag is used during import. If false, registries with :443 suffix or unspecified port will be matched.

Unqualified images references are qualified to docker.io before any rule evaluation. To whitelist them, use domainName: docker.io.

**domainName: *** rule matches any registry hostname, but port is still restricted to 443. To match arbitrary registry serving on arbitrary port, use **domainName: *:***.

Based on the rules established in Example Configuration of Registries Allowed for Import:

oc tag --insecure reg.mydomain.com/app:v1 app:v1 is whitelisted by the handling of the mydomain.com rule
oc import-image --from reg1.mydomain.com:80/foo foo:latest will be also whitelisted
oc tag local.registry.corp/bar bar:latest will be rejected because the port does not match 5000 in the third rule

Rejected image imports will generate error messages similar to the following text:

The ImageStream "bar" is invalid:
* spec.tags[latest].from.name: Forbidden: registry "local.registry.corp" not allowed by whitelist: "local.registry.corp:5000", "*.mydomain.com:80", "registry.access.redhat.com:443"
* status.tags[latest].items[0].dockerImageReference: Forbidden: registry "local.registry.corp" not allowed by whitelist: "local.registry.corp:5000", "*.mydomain.com:80", "registry.access.redhat.com:443"

To configure which images can run on your cluster, configure the ImagePolicy Admission plug-in in the ***master-config.yaml*** file. You can set one or more rules as required.

Reject images with a particular annotation:

Use this rule to reject all images that have a specific annotation set on them. The following rejects all images using the images.openshift.io/deny-execution annotation:

- name: execution-denied
  onResources:
  - resource: pods
  - resource: builds
  matchImageAnnotations:
  - key: images.openshift.io/deny-execution (1)
    value: "true"
  skipOnResolutionFailure: true

Following is an example configuration for setting multiple ImagePolicy addmission plugin rules in the ***master-config.yaml*** file:

After an image is pulled to a node, any Pod on that node from any user can use the image without an authorization check against the image. To ensure that Pods do not use images for which they do not have credentials, use the AlwaysPullImages admission controller.

This modifies every new Pod to force the image pull policy to Always, ensuring that private images can only be used by those who have the credentials to pull them, even if the Pod specification uses an image pull policy of Never.

To enable the AlwaysPullImages admission controller:

Add the following to the master-config.yaml:

admissionConfig:
  pluginConfig:
    AlwaysPullImages: (1)
      configuration:
        kind: DefaultAdmissionConfig
        apiVersion: v1
        disable: false (2)

Restart master services running in control plane static Pods using the master-restart command:
```
$ master-restart api
$ master-restart controllers
```

Use the openshift/image-policy-check to test your configuration.

For example, use the information above, then test like this:
Create a pod using this YAML. The pod should be created.

Create another pod pointing to a different registry. The pod should be rejected.

apiVersion: v1
kind: Pod
metadata:
  generateName: test-pod
spec:
  containers:
    name: first

Create a pod pointing to the internal registry using the imported image. The pod should be created and if you look at the image specification, you should see a digest in place of the tag.
```
apiVersion: v1
kind: Pod
metadata:
  generateName: test-pod
spec:
  containers:
  - image: <internal registry IP>:5000/<namespace>/image-policy-check:latest
    name: first
```

Create a pod pointing to the internal registry using the imported image. The pod should be created and if you look at the image specification, you should see the tag unmodified.

apiVersion: v1
kind: Pod
metadata:
  generateName: test-pod
spec:
  containers:
  - image: <internal registry IP>:5000/<namespace>/image-policy-check:v1
    name: first

Get the digest from oc get istag/image-policy-check:latest and use it for oc annotate images/<digest> images.openshift.io/deny-execution=true. For example:

apiVersion: v1
kind: Pod
metadata:
  generateName: test-pod
spec:
  containers:
    name: first