https://github.com/swisscom/korp
A command line tool for pushing docker images into a corporate registry based on Kubernetes yaml files
https://github.com/swisscom/korp
Last synced: about 1 year ago
JSON representation
A command line tool for pushing docker images into a corporate registry based on Kubernetes yaml files
- Host: GitHub
- URL: https://github.com/swisscom/korp
- Owner: swisscom
- License: mit
- Created: 2019-07-09T11:23:32.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-16T15:18:10.000Z (over 1 year ago)
- Last Synced: 2025-04-15T10:19:58.149Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 127 KB
- Stars: 16
- Watchers: 9
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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](https://github.com/swisscom/korp/releases) 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;
```
1. 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](https://github.com/istio/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
```