Configuration¶

The configuration is managed via the config file .k8s-image-swapper.yaml. Some options can be overriden via parameters, e.g. --dry-run.

Dry Run¶

The option dryRun allows to run the webhook without executing the actions, e.g. repository creation, image download and manifest mutation.

Example

dryRun: true

Log Level & Format¶

The option logLevel & logFormat allow to adjust the verbosity and format (e.g. json, console).

Example

logLevel: debug
logFormat: console

ImageSwapPolicy¶

The option imageSwapPolicy (default: exists) defines the mutation strategy used.

always: Will always swap the image regardless of the image existence in the target registry. This can result in pods ending in state ImagePullBack if images fail to be copied to the target registry.
exists: Only swaps the image if it exits in the target registry. This can result in pods pulling images from the source registry, e.g. the first pod pulls from source registry, subsequent pods pull from target registry.

ImageCopyPolicy¶

The option imageCopyPolicy (default: delayed) defines the image copy strategy used.

delayed: Submits the copy job to a process queue and moves on.
immediate: Submits the copy job to a process queue and waits for it to finish (deadline defined by imageCopyDeadline).
force: Attempts to immediately copy the image (deadline defined by imageCopyDeadline).
none: Do not copy the image.

ImageCopyDeadline¶

The option imageCopyDeadline (default: 8s) defines the duration after which the image copy if aborted.

This option only applies for immediate and force image copy strategies.

Source¶

This section configures details about the image source.

Registries¶

The option source.registries describes a list of registries to pull images from, using a specific configuration.

AWS¶

By providing configuration on AWS registries you can ask k8s-image-swapper to handle the authentication using the same credentials as for the target AWS registry. This authentication method is the default way to get authorized by a private registry if the targeted Pod does not provide an imagePullSecret.

Registries are described with an AWS account ID and region, mostly to construct the ECR domain [ACCOUNT_ID].dkr.ecr.[REGION].amazonaws.com.

Example

source:
  registries:
    - type: aws
      aws:
        accountId: 123456789
        region: ap-southeast-2
    - type: aws
      aws:
        accountId: 234567890
        region: us-east-1

Filters¶

Filters provide control over what pods will be processed. By default, all pods will be processed. If a condition matches, the pod will NOT be processed.

JMESPath is used as query language and allows flexible rules for most use-cases.

Info

The data structure used for JMESPath is as follows:

StructureExample

obj:
  <Object Spec>
container:
  <Container Spec>

obj:
  metadata:
    name: static-web
    labels:
      role: myrole
  spec:
    containers:
      - name: web
        image: nginx
        ports:
          - name: web
            containerPort: 80
            protocol: TCP
container:
  name: web
  image: nginx
  ports:
    - name: web
      containerPort: 80
      protocol: TCP

Below you will find a list of common queries and/or ideas:

List of common queries/ideas

Do not process if namespace equals kube-system (Helm chart default)

source:
  filters:
    - jmespath: "obj.metadata.namespace == 'kube-system'"

Only process if namespace equals playground

source:
  filters:
    - jmespath: "obj.metadata.namespace != 'playground'"

Only process if namespace ends with -dev

source:
  filters:
    - jmespath: "ends_with(obj.metadata.namespace,'-dev')"

Do not process AWS ECR images

source:
  filters:
    - jmespath: "contains(container.image, '.dkr.ecr.') && contains(container.image, '.amazonaws.com')"

k8s-image-swapper will log the filter data and result in debug mode. This can be used in conjunction with JMESPath.org which has a live editor that can be used as a playground to experiment with more complex queries.

Target¶

This section configures details about the image target. The option target allows to specify which type of registry you set as your target (AWS, GCP...). At the moment, aws and gcp are the only supported values.

AWS¶

The option target.aws holds details about the target registry storing the images. The AWS Account ID and Region is primarily used to construct the ECR domain [ACCOUNTID].dkr.ecr.[REGION].amazonaws.com.

Example

target:
  type: aws
  aws:
    accountId: 123456789
    region: ap-southeast-2

ECR Options¶

Tags¶

This provides a way to add custom tags to newly created repositories. This may be useful while looking at AWS costs. It's a slice of Key and Value.

Example

target:
  type: aws
  aws:
    ecrOptions:
      tags:
        - key: cluster
          value: myCluster

GCP¶

The option target.gcp holds details about the target registry storing the images. The GCP location, projectId, and repositoryId are used to constrct the GCP Artifact Registry domain [LOCATION]-docker.pkg.dev/[PROJECT_ID]/[REPOSITORY_ID].

Example

target:
  type: gcp
  gcp:
    location: us-central1
    projectId: gcp-project-123
    repositoryId: main