swisscom/korp

A command line tool for pushing docker images into a corporate registry based on Kubernetes yaml files

korp

A command line tool for pushing docker images referenced in Kubernetes yaml files into a custom Docker registry. The name korp derives from combining the customary shorthand for "corporation" with a k for Kubernetes. The name was chosen because corporate Docker registries are the main use case for the tool.

Versioning

Current version: 1.0.2

Installation

1. Download the latest release and unpack it
2. Add the korp binary to your PATH

Usage

korp has three commands for 1. scanning yaml files, 2. pulling the referenced images and 3. pushing them to the new registry. Patching the yaml files for deployment is delegated to kustomize and kubectl apply -k since this is a well-established tool set for last-mile customization of Kubernetes yaml files.

Scan

The scan command recursively scans a directory, collects all references to Docker images and creates a kustomization.yml file consisting of an images section.

Example

The following command will scan the templates directory (and its sub-directories) and create an images entry in kustomization.yml for each image reference found where the newName field is the normalized image name prefixed with my-registry.example.org.

korp scan -f ./templates -r my-registry.example.org

Pull

The pull command will read the kustomization.yml file generated by the scan command and pull all original images to the local Docker daemon i.e. the Docker daemon which is running on the machine where korp is executed.

Example

The following command pulls all images referenced by the name attribute of the elements of the images list in the kustomization.yml file in the current directory.

korp pull

Push

The push command will read the kustomization.yml file generated by the scan command, tag all referenced images with their new name (including the new registry) and push them. The command assumes that scan and pull have already been executed.

Example

The following command tags each image according to the newName attribute in the corresponding entry of the images list and pushes all images.

korp push

Patching your YAML files

korp delegates the actual patching of the image references in the YAML files to kustomize. You can use the following steps to apply the kustomization.yaml generated by korp to your YAML files.

1. Add the required resources to the kustomization.yaml. The set of resources depends on your use case. If you want to add all yaml files which were scanned by korp (excluding the kustomization.yaml itself) you can use the following glob pattern.

   kustomize edit add resource **/!(kustomization).yaml;
   

2. Apply your YAML files with kubectl.

   kubectl apply -k .
   

A Complete Example

Let's look at how to use korp on a real world example. Let's assume you want to deploy Istio in a corporate environment which has its own Docker registry. These are the steps which you would need to execute.

Render the Istio Helm Charts

At the time of writing Istio is deployed using two Helm charts istio-init and istio. Since korp works with yaml files, you need to first render these two charts against your values.yml files using the command helm template.

1. Clone the Istio repo

git clone https://github.com/istio/istio.git
cd istio

2. Make the desired changes to install/kubernetes/helm/istio-init/values.yaml and install/kubernetes/helm/istio/values.yaml. You can ignore the fact that the hub attributes in these files point to public registries. This will be patched with the help of korp after the yaml files are rendered.

3. Render the Helm charts to two directories.

mkdir $HOME/tmp/istio-init
mkdir $HOME/tmp/istio
helm template install/kubernetes/helm/istio-init --name istio-init --namespace istio-system --output-dir $HOME/tmp/istio-init
helm template install/kubernetes/helm/istio --name istio --namespace istio-system --output-dir $HOME/tmp/istio

Scan the rendered yaml files for image references

4. Scan the istio-init yaml files. You will see a kustomization.yml file being created with one images entry.

cd $HOME/tmp/istio-init/istio-init
korp scan . -r your-registry.example.org

5. Scan the istio yaml files. You will see a kustomization.yml file being created with various images entries.

cd $HOME/tmp/istio/istio
korp scan . -r your-registry.example.org

Pull the referenced images

6. Pull the istio-init images.

cd $HOME/tmp/istio-init/istio-init
korp pull

7. Pull the istio images.

cd $HOME/tmp/istio/istio
korp pull

Push the referenced images to your registry

8. Push the istio-init images. Depending on your network and proxy setup, you might need to change your network connection.

cd $HOME/tmp/istio-init/istio-init
korp push

9. Push the istio images.

cd $HOME/tmp/istio/istio
korp push

Apply the patches to your yaml files and deploy the components

10. Apply the yaml files for istio-init using kustomize

cd $HOME/tmp/istio-init/istio-init
kubectl create ns istio-system
kustomize edit add resource **/!(kustomization).yaml
kubectl apply -k .

11. Apply the yaml files for istio using kustomize

cd $HOME/tmp/istio/istio
kustomize edit add resource **/!(kustomization).yaml
kubectl apply -k .

Autocompletion

Source the autocomplete-scripts/*_autocomplete file in your .bashrc | .zshrc file while setting the PROG variable to the name of your program.

Method 1

go build .
source <(./korp autocompletion zsh)
./korp
# now play with tab

Method 2

go build .
PROG=korp source autocomplete-scripts/zsh_autocomplete
./korp
# now play with tab

korp's Issues

Remove unimplemented "all" command

The command all is documented in the help text but it is not (yet) supported. Remove it instead of throwing an error.

korp producing invalid image names in certain cases

From this container spec

      containers:
      - name: splunk-defaults
        image: nginx
        ports:
        - containerPort: 80
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/nginx/conf.d
        - name: nginx-data-www
          mountPath: /data/www

korp produces this kustomization.yaml

kind: Kustomization
apiVersion: kustomize.config.k8s.io/v1beta1
images:
- name: nginx
  newName: eas-docker-local.artifactory.swisscom.com/nginx
resources:
- nginx-splunk-defaults-service.yaml
- nginx-splunk-defaults.yaml

which leads to this error when executing korp push:

ERRO[0000] Error tagging Docker image nginx: to nginx:: Error parsing reference: "eas-docker-local.artifactory.swisscom.com/nginx:" is not a valid repository/tag
INFO[0000] Total Docker images tagged: 0 - Total Docker images tag failed: 1
INFO[0000] Total Docker images pushed: 0 - Total Docker images push failed: 1

korp push is not working against a restricted registry

when you run korp push against a registry which requires authentication, an authentication error occurs even after a docker login.

Make scan support non-standard image references

Currently the scan command only retrieves standard image references via the image: attribute. Certain deployments reference images in other, non-standard ways. Examples are

• CRDs like the Prometheus operator uses where the image is referenced using baseImage:
• the deployment of the Prometheus operator itself, where some images are referenced via command line arguments to the main container

        - --kubelet-service=kube-system/kubelet
        - --logtostderr=true
        - --config-reloader-image=quay.io/coreos/configmap-reload:v0.0.1
        - --prometheus-config-reloader=quay.io/coreos/prometheus-config-reloader:v0.34.0

We should make the regex which is used during scan configurable via a command line option / environment variable in order to cover the scanning / pulling and pushing of such cases. For the patching we would need to instruct the user to create some custom overlays in Kustomize.

image naming convention not properly adopted in kustomization.yml

Running korp scan . -r eas-docker-local.artifactory.swisscom.com on a container spec

      containers:
      - name: splunk-defaults
        image: nginx
        ports:
        - containerPort: 80

produces the following kustomization.yml

kind: Kustomization
apiversion: kustomize.config.k8s.io/v1beta1
images:
- name: nginx
  newName: eas-docker-local.artifactory.swisscom.com/nginx

However, normalizing the image name nginx results in the name docker.io/library/nginx. Scan should already write the normalized name to kustomization.yml and push should use the normalized name when re-tagging.