ImageStream

OpenShift ImageStream resource for managing container image references

Overview

The ImageStream class represents an OpenShift ImageStream object, which provides an abstraction for referencing container images. ImageStreams enable you to track and manage images from multiple registries, automatically trigger builds and deployments when images change, and provide a stable reference to images that may change over time.

Source: ocp_resources/image_stream.py:5

API Reference: OpenShift ImageStream API

Class Definition

from ocp_resources.image_stream import ImageStream

class ImageStream(NamespacedResource):
    api_group = NamespacedResource.ApiGroup.IMAGE_OPENSHIFT_IO

Constructor

ImageStream(
    name=None,
    namespace=None,
    client=None,
    lookup_policy=False,
    tags=None,
    teardown=True,
    yaml_file=None,
    delete_timeout=TIMEOUT_4MINUTES,
    **kwargs
)

Parameters

name · str · default: "None"

Name of the ImageStream resource. If not provided, it must be specified in the YAML file.

namespace · str · default: "None"

Namespace where the ImageStream will be created. Required for namespaced resources.

client · DynamicClient · default: "None"

Kubernetes dynamic client for API communication. If not provided, the default client will be used.

lookup_policy · bool · default: "False"

Controls whether image references can use the ImageStream name directly in pod specs. When set to True (local lookup enabled), pods can reference images using the ImageStream name instead of the full registry path.

Example: With local lookup, you can use my-app:latest instead of image-registry.openshift-image-registry.svc:5000/myproject/my-app:latest

tags · list[dict[str, Any]] · default: "None"

List of image tags to track in this ImageStream. Each tag can reference images from external registries or from builds.

Example:

[
    {
        "name": "latest",
        "from": {
            "kind": "DockerImage",
            "name": "docker.io/library/nginx:latest"
        },
        "importPolicy": {"scheduled": True}
    }
]

teardown · bool · default: "True"

If True, the resource will be automatically deleted when used as a context manager.

yaml_file · str · default: "None"

Path to a YAML file containing the ImageStream definition. If provided, the ImageStream will be created from this file.

delete_timeout · int · default: "TIMEOUT_4MINUTES"

Timeout in seconds for delete operations. Defaults to 4 minutes.

**kwargs · Any

Additional keyword arguments passed to the parent NamespacedResource class. Common options include label and annotations.

Usage Examples

Basic ImageStream

Create a simple ImageStream without tags:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    name="my-app",
    namespace="default",
    lookup_policy=True
)
image_stream.deploy()

ImageStream with External Image

Create an ImageStream that tracks an external Docker image:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    name="nginx",
    namespace="default",
    lookup_policy=True,
    tags=[
        {
            "name": "latest",
            "from": {
                "kind": "DockerImage",
                "name": "docker.io/library/nginx:latest"
            },
            "importPolicy": {
                "scheduled": True  # Periodically check for updates
            },
            "referencePolicy": {
                "type": "Local"  # Store image in internal registry
            }
        }
    ]
)
image_stream.deploy()

Multiple Tags

Create an ImageStream with multiple version tags:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    name="python-app",
    namespace="default",
    lookup_policy=True,
    tags=[
        {
            "name": "3.9",
            "from": {
                "kind": "DockerImage",
                "name": "registry.access.redhat.com/ubi8/python-39:latest"
            }
        },
        {
            "name": "3.11",
            "from": {
                "kind": "DockerImage",
                "name": "registry.access.redhat.com/ubi9/python-311:latest"
            }
        },
        {
            "name": "latest",
            "from": {
                "kind": "ImageStreamTag",
                "name": "python-app:3.11"  # Point to another tag
            }
        }
    ]
)
image_stream.deploy()

ImageStream for Build Output

Create an ImageStream to store build outputs:

from ocp_resources.image_stream import ImageStream

# This ImageStream will be populated by BuildConfig output
image_stream = ImageStream(
    name="my-build-output",
    namespace="default",
    lookup_policy=True,
    tags=[
        {
            "name": "latest",
            "annotations": {
                "description": "Latest build of my application"
            }
        }
    ]
)
image_stream.deploy()

Scheduled Image Import

Create an ImageStream that periodically checks for image updates:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    name="auto-updated",
    namespace="default",
    lookup_policy=True,
    tags=[
        {
            "name": "latest",
            "from": {
                "kind": "DockerImage",
                "name": "quay.io/example/app:latest"
            },
            "importPolicy": {
                "scheduled": True,  # Enable periodic import
                "insecure": False   # Require TLS verification
            },
            "referencePolicy": {
                "type": "Local"     # Import to internal registry
            }
        }
    ]
)
image_stream.deploy()

Creating from YAML

Create an ImageStream from a YAML file:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    namespace="default",
    yaml_file="imagestream.yaml"
)
image_stream.deploy()

Using Context Manager

Automatically clean up the ImageStream after use:

from ocp_resources.image_stream import ImageStream

with ImageStream(
    name="temp-images",
    namespace="default",
    lookup_policy=True
) as img_stream:
    print(f"ImageStream created: {img_stream.name}")
    # ImageStream is automatically deleted when exiting

Accessing ImageStream Tags

Query ImageStream tags and image information:

from ocp_resources.image_stream import ImageStream

image_stream = ImageStream(
    name="my-app",
    namespace="default"
)

if image_stream.exists:
    # Access status information
    status = image_stream.instance.status
    
    # List all tags
    if hasattr(status, 'tags'):
        for tag in status.tags:
            print(f"Tag: {tag.tag}")
            if hasattr(tag, 'items') and tag.items:
                latest_image = tag.items[0]
                print(f"  Image: {latest_image.dockerImageReference}")
                print(f"  Created: {latest_image.created}")

Tag Configuration

Import Policy

Controls how images are imported:

"importPolicy": {
    "scheduled": True,    # Periodically re-import image
    "insecure": False     # Require TLS for registry
}

Reference Policy

Controls how image references are stored:

"referencePolicy": {
    "type": "Local"  # Options: "Local" or "Source"
}

• Local: Images are imported to the internal OpenShift registry
• Source: References point to the original external registry

Tag Annotations

Add metadata to tags:

"annotations": {
    "description": "Production-ready image",
    "version": "1.0.0",
    "supports": "Python 3.9"
}

Image Reference Types

Docker Image

Reference an external container image:

"from": {
    "kind": "DockerImage",
    "name": "registry.example.com/org/image:tag"
}

ImageStreamTag

Reference another tag within the same or different ImageStream:

"from": {
    "kind": "ImageStreamTag",
    "name": "another-stream:tag",
    "namespace": "other-namespace"  # Optional
}

ImageStreamImage

Reference a specific image by digest:

"from": {
    "kind": "ImageStreamImage",
    "name": "my-app@sha256:abc123..."
}

Common Use Cases

Build Output Storage

ImageStreams are commonly used as build output destinations:

# In BuildConfig
output={
    "to": {
        "kind": "ImageStreamTag",
        "name": "my-app:latest"
    }
}

Deployment Triggers

ImageStreams trigger automatic deployments when images change:

# In DeploymentConfig
triggers=[
    {
        "type": "ImageChange",
        "imageChangeParams": {
            "automatic": True,
            "containerNames": ["app"],
            "from": {
                "kind": "ImageStreamTag",
                "name": "my-app:latest"
            }
        }
    }
]

Image Mirroring

Mirror external images to the internal registry:

ImageStream(
    name="mirrored-image",
    namespace="default",
    tags=[
        {
            "name": "v1.0",
            "from": {
                "kind": "DockerImage",
                "name": "external-registry.com/app:v1.0"
            },
            "referencePolicy": {"type": "Local"},
            "importPolicy": {"scheduled": True}
        }
    ]
)

OpenShift Internal Registry

ImageStreams automatically integrate with OpenShift’s internal registry:

Registry URL Format:

image-registry.openshift-image-registry.svc:5000/<namespace>/<imagestream>:<tag>

Example:

image-registry.openshift-image-registry.svc:5000/default/my-app:latest

Lookup Policy

When lookup_policy is enabled:

lookup_policy=True

Pods can reference images using short names:

# Instead of:
image: "image-registry.openshift-image-registry.svc:5000/default/my-app:latest"

# You can use:
image: "my-app:latest"

Related Resources

• BuildConfig - Uses ImageStreams for output
• DeploymentConfig - Uses ImageStreams for triggers
• ImageStreamTag - Individual tag within an ImageStream
• OpenShift ImageStream Documentation

See Also

• Working with Images Guide
• Core Concepts: Resources
• NamespacedResource Base Class