DOCSEARCHbyAlgolia
Submit Docs

imgpkg

repository·develop·Indexed 43 days ago

https://github.com/carvel-dev/imgpkg

A tool for storing arbitrary sets of files, such as Kubernetes YAML or Helm templates, as OCI images. It uses 'bundles' to manage files and their dependent images as a single unit, facilitating movement across registries and air-gapped environments. Features include commands for pushing, pulling, copying, and describing bundles, as well as support as a Go library via carvel.dev/imgpkg.

Tokens
8.6K
Snippets
41
Records
44
Agent score
52%

What's inside imgpkg

  1. What is an imgpkg bundle?

    develop

    The primary concept in imgpkg is a bundle. A bundle is an OCI image that contains zero or more arbitrary files and zero or more references to dependent OCI images.

    This abstraction allows imgpkg to manage complex dependencies, enabling the copying of bundles and all their referenced images across different registries, whether they are online or in air-gapped/offline environments.

  2. Basic imgpkg usage: push, pull, copy, and list

    develop

    Use the following commands to perform common tasks with bundles:

    • Push a bundle: Create a bundle from a local directory and push it to a registry.
    • Copy a bundle: Perform a 'thick' copy of a bundle (including the bundle image and all referenced images) to another repository or a tarball.
    • Pull a bundle: Download a bundle and extract its files to a local directory.
    • List tags: List the tags associated with a specific image.
    # Push a bundle from a directory to a registry
imgpkg push -b your-user/app1-config:0.1.1 -f config/

# Copy a bundle and its dependencies to another repository
imgpkg copy -b your-user/app1-config:0.1.1 --to-repo other-user/app1

# Pull a bundle and extract files to a directory
imgpkg pull -b your-user/app1-config:0.1.1 -o /tmp/app1-config

# List tags for an image
imgpkg tag ls -i your-user/app1-config

  3. Build and test imgpkg (Development)

    develop

    If you are contributing to the imgpkg repository, use the following commands to build and test the project:

    Build

    ./hack/build.sh

    Test

    All tests require a local registry and Docker. Run them using:

    ./hack/test-all-local-registry.sh 5000

    To avoid Docker Hub rate limiting, you can use a proxy registry by setting the DOCKERHUB_PROXY environment variable:

    export DOCKERHUB_PROXY=<my-registry.local.sometld/my-dockerhub-proxy> && ./hack/test-all-local-registry.sh 5000
    # Build the project
./hack/build.sh

# Run all tests with a local registry on port 5000
./hack/test-all-local-registry.sh 5000

  6. Use imgpkg as a Go library

    develop

    To integrate imgpkg into your Go project, add it as a dependency to your Go module.

    Important Migration Note: Older versions of the library used the module path github.com/k14s/imgpkg. While GitHub currently re-routes these requests, you should use the new canonical module path carvel.dev/imgpkg for all new development and future-proofing.

    go get carvel.dev/imgpkg

  7. Use the imgpkg CLI

    develop

    The imgpkg CLI allows you to store configuration and image references as OCI artifacts. It provides commands for pushing, pulling, copying, describing, and managing tags for these artifacts.

    Core Commands:

    • push: Upload an artifact to an OCI registry.
    • pull: Download an artifact from an OCI registry.
    • copy: Copy an artifact between registries or locations.
    • describe: View metadata or details about an artifact.
    • tag: Manage tags associated with an artifact. This command includes subcommands:
      • tag list: List tags for an artifact.
      • tag resolve: Resolve a tag to a specific reference.
    • version: Display the current version of imgpkg.
    • completion: Generate shell completion scripts.
    # Example usage pattern
imgpkg push ...
imgpkg pull ...
imgpkg tag list ...

  9. Copy bundles and images with `imgpkg copy`

    develop

    The imgpkg copy command allows you to move bundles or images between different locations, such as from a registry to a local tarball, or from one registry to another.

    Common Tasks

    Copy a bundle to a local tarball: Use the -b (or --bundle) flag to specify the source bundle and --to-tar to specify the destination file.

    Copy a bundle to another registry: Use the -b flag for the source and --to-repo for the destination repository.

    Copy an image to another registry: Use the -i (or --image) flag for the source and --to-repo for the destination repository.

    Shallow-copy a bundle image: If you want to copy an image that is actually a bundle without performing a full bundle check, use the --ignore-bundle-check flag with the -i flag.

    Use repository-based tags: When copying images, you can use the --repo-based-tags flag. This allows imgpkg to generate new tags in the destination repository based on the source repository's structure. For example, if a source tag is a SHA digest, the new tag will be a truncated version of that digest prefixed by the application name.

    # Copy bundle dkalinin/app1-bundle to local tarball at /Volumes/app1-bundle.tar
imgpkg copy -b dkalinin/app1-bundle --to-tar /Volumes/app1-bundle.tar

# Copy bundle dkalinin/app1-bundle to another registry
imgpkg copy -b dkalinin/app1-bundle --to-repo internal-registry/app1-bundle

# Copy image dkalinin/app1-image to another registry
imgpkg copy -i dkalinin/app1-image --to-repo internal-registry/app1-image

# Copy using image --repo-based-tags flag
imgpkg copy -i registry.foo.bar/some/application/app --to-repo other-reg.faz.baz/my-app --repo-based-tags

  10. Configure PowerShell completion for imgpkg

    develop

    To enable tab-completion for imgpkg in PowerShell, you can source the output directly or save it to a script file to be loaded by your PowerShell profile.

    Current session only:

    imgpkg completion powershell | Out-String | Invoke-Expression

    Persistent setup:

    1. Generate the script file:
    imgpkg completion powershell > imgpkg.ps1
    1. Source this file from your PowerShell profile.

  11. Configure Zsh completion for imgpkg

    develop

    To enable tab-completion for imgpkg in Zsh, ensure shell completion is enabled in your environment, then save the generated script to your fpath.

    1. Enable completion in ~/.zshrc (if not already enabled):

    echo "autoload -U compinit; compinit" >> ~/.zshrc

    2. Persistent setup:

    imgpkg completion zsh > "${fpath[1]}/_imgpkg"

    Note: You must start a new shell for the changes to take effect.

    Current session only:

    imgpkg completion zsh

  12. Configure Bash completion for imgpkg

    develop

    To enable tab-completion for imgpkg in Bash, you can either source the output directly for the current session or save it to a system directory to persist it.

    Current session only:

    source <(imgpkg completion bash)

    Persistent setup:

    • Linux:
    imgpkg completion bash > /etc/bash_completion.d/imgpkg
    • macOS:
    imgpkg completion bash > /usr/local/etc/bash_completion.d/imgpkg