DOCSEARCHbyAlgolia
Submit Docs

vendir

repository·develop·Indexed 18 days ago

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

A tool to declaratively state and synchronize the contents of a directory, primarily used for vendoring software from sources such as Git, GitHub releases, HTTP, Docker images, and Helm charts. It features support for lock files to ensure reproducible builds, path filtering, local overrides for development, and a `sort-semver` utility for sorting semantic versions.

Tokens
2.8K
Snippets
18
Records
23
Agent score
64%

What's inside vendir

  1. Overview of vendir features and sources

    develop

    vendir is a tool for declaratively stating what should be in a directory. It supports a wide range of source types and content management features:

    Supported Sources

    • Git repositories: Includes support for semver tag resolution and GPG verification.
    • GitHub releases: Pull assets from GitHub releases with semver tag resolution.
    • HTTP assets: Pull files directly via HTTP.
    • Docker images: Extract contents from Docker images.
    • Helm charts: Pull and extract Helm chart contents.

    Content Management

    • Path Filtering: Use includePaths, excludePaths, or newRootPath to keep only specific portions of the pulled content.
    • Local Overrides: Override a remote source with a local directory for rapid development.
    • Manual Management: Specify which directories are managed manually rather than by vendir.
    • Inline Content: Define content directly within the configuration.
    • Lock Files: Automatically generates a lock file to ensure reproducible builds.
    • Legal Files: Capability to keep common legal files like LICENSE.

  3. Sync a directory using vendir

    develop

    To declaratively sync the contents of a directory based on a vendir.yml configuration file, run the sync command from within the directory containing that file.

    vendir ensures the directory contains exactly what is specified in your configuration, allowing you to vendor software from various sources.

    $ vendir sync

  5. Override specific directories with local content

    develop

    As of v0.7.0, you can use the --directory flag to override the contents of specific directories in your vendor folder by pointing them to local directories.

    Note: When this flag is specified, other directories will not be synced, and the lock configuration will not be updated.

    $ vendir sync --directory vendor/local-dir=local-dir-dev

  6. Run e2e tests with GitHub API token

    develop

    To prevent GitHub rate-limiting during end-to-end (e2e) testing, you must generate a Personal Access Token (PAT) and export it as the VENDIR_GITHUB_API_TOKEN environment variable before running the e2e test script.

    export VENDIR_GITHUB_API_TOKEN=<pat-token-here>
./hack/test-e2e.sh

  7. Run vendir tests

    develop

    Vendir provides several scripts for running different types of tests. Use ./hack/build.sh and ./hack/test-all.sh to run the full test suite, or use the specific scripts for unit or e2e testing.

    # Run all tests
./hack/build.sh
./hack/test-all.sh

# Run unit tests
./hack/test.sh

# Run e2e tests
export VENDIR_GITHUB_API_TOKEN=<pat-token-here>
./hack/test-e2e.sh

  9. Use the vendir CLI

    develop

    The vendir CLI allows you to declaratively state what should be in a directory. It is used to manage directory contents by synchronizing them with defined sources.

    Available subcommands include:

    • sync: Synchronize directory contents.
    • version: Display the current version of vendir.
    • tools: A grouping command for various utility tools.
      • tools sort-semver: Sorts semantic versions.
    # General usage
vendir [command] [flags]

# Example: check version
vendir version

  10. Use lock files for reproducible syncs

    develop

    To ensure that your environment is reproducible, use the --locked flag. When this flag is provided, Vendir reads the existing lock file (default: vendir.lock.yml) and uses the exact references (such as specific Git commit SHAs) stored there instead of following branch names or tags which might change.

    If you are running a sync that updates references, Vendir will automatically update the lock file with the new exact references after a successful sync.

    vendir sync --locked

  11. Sync specific directories or override with local paths

    develop

    You can use the --directory flag to target specific directories for synchronization or to override a remote directory with a local one.

    Syntax: dir/sub-dir[=local-dir]

    • Targeting a directory: --directory path/to/dir will sync only that directory.
    • Overriding with a local directory: --directory path/to/dir=./my-local-path tells Vendir to use the content from ./my-local-path instead of fetching it from the remote source defined in the configuration.
    vendir sync --directory some/remote/dir=./local/override/dir

  12. Sync content using ytt-generated configuration

    develop

    When iterating on code, you can use ytt to build a temporary configuration by merging multiple files (e.g., a base vendir.yml and a local-override.yml) and passing the result to vendir via process substitution using the --file flag.

    $ vendir sync --file <(ytt -f vendir.yml -f local-override.yml)