# What is imgpkg

Carvel's imgpkg (pronounced, 'image package') addresses a problem of packaging and distributing a set of files which works well with Kubernetes resource configurations. It creates, relocates, and inspects what we call a bundle. A bundle is an OCI image which acts as an abstraction that enables users to manage their manifests and any referenced images as if they were a single artifact. It includes:

* bundle metadata (e.g. name, authors)
* bundle contents which is a set of files (e.g. kubernetes manifests)
* optionally, list of image references that are considered to be part of a bundle

## Benefits
* Supports copying (aka relocating) of bundles or generic images between two registries.
* Produces a tarball supporting distribution to air gapped environments
* Uses OCI registry for storage
* Does not concern itself with how package contents are configured/installed
* Works well with most registries

## Use Cases
### Making a Bundle
`imgpkg push -f my-kubernetes-config -b gcr.io/.../my-bundle:v1`
### Generic Bundle Relocation

`imgpkg copy --bundle gcr.io/.../my-bundle:v1 --to-repo docker.io/k8slt/bundle --lock-output image.lock.yml`

Key constraint: bundle image must always retain its digest when copied around.

### Consuming a Bundle
`imgpkg pull -o ~/k8s-config -b docker.io/k8slt/bundle:v1`

## Release Plan
### MVP (v.0.3.0)
Features:
* Push bundle/image
* Pull bundle/image
* Relocating bundle (relocates bundle image as well as reference images)
* Relocation of generic images

Target Date: Mid-December, 2020

## Supported Registries
* Docker
* GCR
* ECR
* Microsoft
* Harbor
* Red Hat
* Artifactory

## Glossary

An **air-gapped system** is a system with no network access to or from the internet.

A **tarball** is one or more packages serialized in a file format suitable for transporting into an air-gapped system.