Kubernetes - Images

A Kubernetes image is a container image used to run an application inside a Kubernetes Pod. The image contains the application code, runtime, libraries, and other dependencies required to run the application. Kubernetes uses container images to:

• Package applications with their dependencies.
• Provide consistent application environments.
• Deploy applications across different nodes.
• Start containers inside Pods.
• Scale applications by creating multiple Pod replicas.

Container images are usually stored in a container registry such as Docker Hub, Amazon ECR, Google Artifact Registry, or Azure Container Registry.

Container Image

A container image is a ready-to-run package that contains everything required to run an application. A container image can include:

• Application source code.
• Runtime environment.
• System libraries.
• Application dependencies.
• Configuration defaults.

Kubernetes does not directly run an image. Instead, a container in a Pod references the image, and the container runtime pulls and runs it when required. The basic workflow is:

Working of Container Images in Kubernetes

Kubernetes uses the image field in a Pod specification to identify the container image.

The process works as follows:

• A container image is built for the application.
• The image is pushed to a container registry.
• The image name is specified in the Kubernetes manifest.
• Kubernetes schedules the Pod on a suitable node.
• The kubelet asks the container runtime to obtain the image.
• The container runtime pulls the image if required.
• The container is created and started.

For example:

apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod
spec:
  containers:
    - name: nginx
      image: nginx:latest

Here, nginx:latest specifies the image that Kubernetes should use for the container.

Image Names

A Kubernetes container image is generally specified using the following format:

[registry-host/]repository/image[:tag]

For example:

docker.io/library/nginx:latest

A fully qualified image name can also include a registry hostname and port:

registry.example.com:5000/myapp:v1

An image reference can contain:

• Registry: Identifies the container registry.
• Repository: Identifies the image repository.
• Image name: Identifies the application image.
• Tag: Identifies a particular version of the image.

For example:

registry.example.com/myapp/frontend:v2

Here:

• registry.example.com → Registry
• myapp → Repository
• frontend → Image name
• v2 → Image tag

If no registry hostname is specified, Kubernetes uses the default container registry behavior for the image reference.

Image Tags

An image tag identifies a particular version or variant of an image. For example:

nginx:1.27
nginx:1.28
myapp:v1
myapp:v2

Tags are useful for:

• Versioning images.
• Identifying releases.
• Updating applications.
• Managing different environments.

The latest tag is commonly used during development, but it can make deployments harder to reproduce because the tag can point to different image content over time.

For production workloads, using a specific version tag or an image digest provides more predictable deployments.

Image Digests

An image digest provides an immutable reference to a specific image.

For example:

nginx@sha256:abc123...

Unlike tags, which can be moved to different image versions, a digest identifies a specific image content.

Using image digests can help with:

• Reproducible deployments.
• Version consistency.
• Image verification.
• Preventing unexpected image changes.

Image Configuration in Kubernetes

The image field is specified inside the container definition.

Example:

apiVersion: v1
kind: Pod
metadata:
  name: gfg-pod
spec:
  containers:
    - name: gfg-container
      image: nginx:1.28
      imagePullPolicy: IfNotPresent

Here:

• name: Specifies the name of the Pod.
• containers: Defines the containers inside the Pod.
• name: Specifies the container name.
• image: Specifies the container image.
• imagePullPolicy: Defines when Kubernetes should pull the image.

Image Pull Policy

The imagePullPolicy field controls when the kubelet attempts to pull an image from the registry.

Kubernetes supports three main values:

For Always, Kubernetes resolves the image reference to a digest and can use a locally cached image when that exact digest is already available.

Default Image Pull Policy

If imagePullPolicy is not specified:

• :latest → Always
• No tag specified → Always
• Any tag other than :latest → IfNotPresent
• An image specified by digest → IfNotPresent

For example:

image: nginx:latest

will normally use:

imagePullPolicy: Always

Whereas:

image: nginx:1.28

will normally use:

imagePullPolicy: IfNotPresent

Pulling Images from a Container Registry

Kubernetes pulls images from a container registry when the required image is not available locally or when the configured pull policy requires it.

The registry can be:

• Docker Hub.
• Amazon ECR.
• Google Artifact Registry.
• Azure Container Registry.
• A private container registry.

The container runtime on the Kubernetes node performs the actual image pull.

Using Private Container Images

Private registries require authentication before Kubernetes can pull an image. Kubernetes supports image pull Secrets for authenticating with private registries.

Create a registry Secret using:

kubectl create secret docker-registry regcred \
  --docker-server=<your-registry-server> \
  --docker-username=<your-username> \
  --docker-password=<your-password>

The Secret can then be referenced using imagePullSecrets:

apiVersion: v1
kind: Pod
metadata:
  name: private-app
spec:
  containers:
    - name: app
      image: registry.example.com/myapp:v1
  imagePullSecrets:
    - name: regcred

The Secret must exist in the same namespace as the Pod.

Updating Container Images

Container images can be updated by changing the image reference in a Kubernetes workload.

For example:

image: nginx:1.27

can be changed to:

image: nginx:1.28

For a Deployment, use:

kubectl set image deployment/my-app my-container=nginx:1.28

Check the rollout using:

kubectl rollout status deployment/my-app

View the updated Pods using:

kubectl get pods

Kubernetes creates new Pods using the updated image according to the Deployment's rollout strategy.

Image Updating and Image Tags

Using mutable tags can cause unexpected image versions to run.

For example, suppose:

myapp:latest

initially points to version 1 of an application.

Later, the registry updates the same tag to version 2.

New Pods may then use different image content depending on when and where they are started.

Using version-specific tags is generally easier to manage:

myapp:v1
myapp:v2
myapp:v3

Using an image digest provides an even more specific reference:

myapp@sha256:<digest>

This helps ensure that workloads use the intended image content.

Image Commands

Create a Pod from an Image

Create a Pod using a YAML manifest:

kubectl apply -f pod.yaml

Check the Pod

kubectl get pods

View Pod Details

kubectl describe pod <pod-name>

View Container Logs

kubectl logs <pod-name>

For a Pod with multiple containers:

kubectl logs <pod-name> -c <container-name>

View the Image Used by a Pod

kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'

Common Image Pull Errors

Kubernetes may encounter errors while pulling or starting container images. Common errors include:

ImagePullBackOff

Indicates that Kubernetes is repeatedly failing to pull the required image.

Possible causes:

• Incorrect image name.
• Incorrect image tag.
• Private registry authentication failure.
• Registry unavailable.
• Image does not exist.

Check the Pod events using:

kubectl describe pod <pod-name>

ErrImagePull

Indicates that Kubernetes failed to pull the specified image.

Check:

• Image name.
• Image tag.
• Registry access.
• Registry credentials.
• Network connectivity.

Image Not Found

This usually occurs when the specified image or tag does not exist in the registry.

For example:

image: myapp:invalid-version

Verify that the image and tag exist in the registry.

Best Practices

• Use small and optimized images.
• Use specific image tags instead of relying on latest.
• Use image digests when strict version consistency is required.
• Store production images in a trusted registry.
• Use private registries for sensitive applications.
• Use imagePullSecrets for private registry authentication.
• Scan images for security vulnerabilities.
• Regularly update base images and dependencies.
• Avoid storing secrets inside container images.
• Use immutable image references for production deployments.

Kubernetes Images vs Containers