korp

README

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

1. 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.

2. 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

1. 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

1. 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

1. Pull the istio-init images.

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

1. Pull the istio images.

cd $HOME/tmp/istio/istio
korp pull

Push the referenced images to your registry

1. 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

1. Push the istio images.

cd $HOME/tmp/istio/istio
korp push

Apply the patches to your yaml files and deploy the components

1. 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 .

1. 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