From 73d4ce888e4c657079a98678ca0c1a668e110664 Mon Sep 17 00:00:00 2001 From: Devanshu Date: Fri, 17 Jan 2025 00:07:05 +0530 Subject: [PATCH] Release vendir docs v0.43.x Signed-off-by: Devanshu --- site/config.yaml | 5 +- site/content/vendir/docs/v0.42.x/_index.md | 2 +- .../vendir/docs/v0.42.x/github-release.md | 2 +- site/content/vendir/docs/v0.42.x/install.md | 2 +- site/content/vendir/docs/v0.42.x/security.md | 2 +- site/content/vendir/docs/v0.42.x/sync.md | 2 +- .../vendir/docs/v0.42.x/vendir-lock-spec.md | 2 +- .../vendir/docs/v0.42.x/vendir-spec.md | 2 +- site/content/vendir/docs/v0.42.x/versions.md | 2 +- site/content/vendir/docs/v0.43.x/_index.md | 25 ++ .../vendir/docs/v0.43.x/github-release.md | 17 ++ site/content/vendir/docs/v0.43.x/install.md | 58 ++++ site/content/vendir/docs/v0.43.x/security.md | 8 + site/content/vendir/docs/v0.43.x/sync.md | 76 +++++ .../vendir/docs/v0.43.x/vendir-lock-spec.md | 69 +++++ .../vendir/docs/v0.43.x/vendir-spec.md | 275 ++++++++++++++++++ site/content/vendir/docs/v0.43.x/versions.md | 112 +++++++ site/data/vendir/docs/toc-mapping.yml | 1 + site/data/vendir/docs/vendir-v0-43-x-toc.yml | 29 ++ 19 files changed, 681 insertions(+), 10 deletions(-) create mode 100644 site/content/vendir/docs/v0.43.x/_index.md create mode 100644 site/content/vendir/docs/v0.43.x/github-release.md create mode 100644 site/content/vendir/docs/v0.43.x/install.md create mode 100644 site/content/vendir/docs/v0.43.x/security.md create mode 100644 site/content/vendir/docs/v0.43.x/sync.md create mode 100644 site/content/vendir/docs/v0.43.x/vendir-lock-spec.md create mode 100644 site/content/vendir/docs/v0.43.x/vendir-spec.md create mode 100644 site/content/vendir/docs/v0.43.x/versions.md create mode 100644 site/data/vendir/docs/vendir-v0-43-x-toc.yml diff --git a/site/config.yaml b/site/config.yaml index c02cd67e3..91f1b585d 100644 --- a/site/config.yaml +++ b/site/config.yaml @@ -202,15 +202,16 @@ params: name: vendir short_name: vendir root_link: /vendir/ - latest_docs_link: /vendir/docs/v0.42.x/ + latest_docs_link: /vendir/docs/v0.43.x/ github_url: https://github.com/carvel-dev/vendir search: true search_index_name: carvel-vendir search_api_key: a38560864c2e9128ae57d5734df438ff versioning: true - version_latest: v0.42.x + version_latest: v0.43.x versions: - develop + - v0.43.x - v0.42.x - v0.41.x - v0.40.x diff --git a/site/content/vendir/docs/v0.42.x/_index.md b/site/content/vendir/docs/v0.42.x/_index.md index c0d5f62e0..891f6e346 100644 --- a/site/content/vendir/docs/v0.42.x/_index.md +++ b/site/content/vendir/docs/v0.42.x/_index.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/] + title: "About vendir" toc: "false" cascade: diff --git a/site/content/vendir/docs/v0.42.x/github-release.md b/site/content/vendir/docs/v0.42.x/github-release.md index 827addfe8..54204e7d2 100644 --- a/site/content/vendir/docs/v0.42.x/github-release.md +++ b/site/content/vendir/docs/v0.42.x/github-release.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/github-release] + title: Github Release --- diff --git a/site/content/vendir/docs/v0.42.x/install.md b/site/content/vendir/docs/v0.42.x/install.md index 0c0d5399f..9174c19df 100644 --- a/site/content/vendir/docs/v0.42.x/install.md +++ b/site/content/vendir/docs/v0.42.x/install.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/install] + title: Install --- diff --git a/site/content/vendir/docs/v0.42.x/security.md b/site/content/vendir/docs/v0.42.x/security.md index 0e42ae4c1..73663e269 100644 --- a/site/content/vendir/docs/v0.42.x/security.md +++ b/site/content/vendir/docs/v0.42.x/security.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/security] + title: Security --- diff --git a/site/content/vendir/docs/v0.42.x/sync.md b/site/content/vendir/docs/v0.42.x/sync.md index fbb5703ef..8dcedeb44 100644 --- a/site/content/vendir/docs/v0.42.x/sync.md +++ b/site/content/vendir/docs/v0.42.x/sync.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/sync] + title: Sync command --- diff --git a/site/content/vendir/docs/v0.42.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.42.x/vendir-lock-spec.md index 027838675..6276527b6 100644 --- a/site/content/vendir/docs/v0.42.x/vendir-lock-spec.md +++ b/site/content/vendir/docs/v0.42.x/vendir-lock-spec.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/vendir-lock-spec] + title: vendir.lock.yml spec --- diff --git a/site/content/vendir/docs/v0.42.x/vendir-spec.md b/site/content/vendir/docs/v0.42.x/vendir-spec.md index f80c12f74..cb59bf28a 100644 --- a/site/content/vendir/docs/v0.42.x/vendir-spec.md +++ b/site/content/vendir/docs/v0.42.x/vendir-spec.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/vendir-spec] + title: vendir.yml spec --- diff --git a/site/content/vendir/docs/v0.42.x/versions.md b/site/content/vendir/docs/v0.42.x/versions.md index 3a5791f62..be4df2288 100644 --- a/site/content/vendir/docs/v0.42.x/versions.md +++ b/site/content/vendir/docs/v0.42.x/versions.md @@ -1,5 +1,5 @@ --- -aliases: [/vendir/docs/latest/versions] + title: Versions --- diff --git a/site/content/vendir/docs/v0.43.x/_index.md b/site/content/vendir/docs/v0.43.x/_index.md new file mode 100644 index 000000000..33b11a5f3 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/_index.md @@ -0,0 +1,25 @@ +--- +aliases: [/vendir/docs/latest/] +title: "About vendir" +toc: "false" +cascade: + version: v0.43.x + toc: "true" + type: docs + layout: docs +--- + +vendir allows to declaratively state what should be in a directory. It was designed to easily manage libraries for [ytt](/ytt); however, it is a generic tool and does not care how files within managed directories are used. + +Supported sources for fetching: + +- git +- hg (Mercurial) +- http +- image (image from OCI registry) +- imgpkgBundle (bundle from OCI registry) +- githubRelease +- helmChart +- directory + +Examples could be found in [carvel-vendir's `examples/` directory](https://github.com/carvel-dev/vendir/tree/develop/examples). diff --git a/site/content/vendir/docs/v0.43.x/github-release.md b/site/content/vendir/docs/v0.43.x/github-release.md new file mode 100644 index 000000000..827addfe8 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/github-release.md @@ -0,0 +1,17 @@ +--- +aliases: [/vendir/docs/latest/github-release] +title: Github Release +--- + +vendir supports downloading software stored as a Github release. See [`vendir.yml` spec](vendir-spec.md) for how to configure. + +## Github API Rate Limiting + +If your public IP address is shared by multiple machines (e.g. workstations in an office), you may run into [Github rate limiting errors](https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#rate-limiting). vendir as of v0.8.0 supports providing "Personal access token" to increase Github API rate limits. You can specify it via an environment variable: + +```bash +$ export VENDIR_GITHUB_API_TOKEN=ghp_8c0a3... +$ vendir sync +``` + +To obtain personal access token go to [Github.com: Settings / Developer Settings / Personal access tokens](https://github.com/settings/tokens). During token creation, you will be prompted for selection of scopes, and in most cases there is no need to select any scopes because this token only used to identify API usage. For organizations that enable SSO, you will need to "Enable SSO" for created token. diff --git a/site/content/vendir/docs/v0.43.x/install.md b/site/content/vendir/docs/v0.43.x/install.md new file mode 100644 index 000000000..0c0d5399f --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/install.md @@ -0,0 +1,58 @@ +--- +aliases: [/vendir/docs/latest/install] +title: Install +--- + +## Via script (macOS or Linux) + +(Note that `install.sh` script installs other Carvel tools as well.) + +Install binaries into specific directory: + +```bash +$ mkdir local-bin/ +$ curl -L https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR=local-bin bash + +$ export PATH=$PWD/local-bin/:$PATH +$ vendir version +``` + +Or system wide: + +```bash +$ wget -O- https://carvel.dev/install.sh > install.sh + +# Inspect install.sh before running... +$ sudo bash install.sh +$ vendir version +``` + +## Via Homebrew (macOS or Linux) + +Based on [github.com/carvel-dev/homebrew](https://github.com/carvel-dev/homebrew). + +```bash +$ brew tap carvel-dev/carvel +$ brew install vendir +$ vendir version +``` + +## Specific version from a GitHub release + +To download, click on one of the assets in a [chosen GitHub release](https://github.com/carvel-dev/vendir/releases), for example for 'vendir-darwin-amd64'. + +```bash +# **Compare binary checksum** against what's specified in the release notes +# (if checksums do not match, binary was not successfully downloaded) +$ shasum -a 256 ~/Downloads/vendir-darwin-amd64 +08b25d21675fdc77d4281c9bb74b5b36710cc091f30552830604459512f5744c /Users/pivotal/Downloads/vendir-darwin-amd64 + +# Move binary next to your other executables +$ mv ~/Downloads/vendir-darwin-amd64 /usr/local/bin/vendir + +# Make binary executable +$ chmod +x /usr/local/bin/vendir + +# Check its version +$ vendir version +``` diff --git a/site/content/vendir/docs/v0.43.x/security.md b/site/content/vendir/docs/v0.43.x/security.md new file mode 100644 index 000000000..0e42ae4c1 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/security.md @@ -0,0 +1,8 @@ +--- +aliases: [/vendir/docs/latest/security] +title: Security +--- + +## Vulnerability Disclosure + +If you believe you have found a security issue in `vendir`, please privately and responsibly disclose it by following the directions in our [security policy](/shared/docs/latest/security-policy). diff --git a/site/content/vendir/docs/v0.43.x/sync.md b/site/content/vendir/docs/v0.43.x/sync.md new file mode 100644 index 000000000..fbb5703ef --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/sync.md @@ -0,0 +1,76 @@ +--- +aliases: [/vendir/docs/latest/sync] +title: Sync command +--- + +## Overview + +`vendir sync` command looks for [`vendir.yml`](vendir-spec.md) file in current directory for its configuration. `vendir.yml` specifies source of files for each managed directory. + +``` +# Run to sync directory contents as specified by vendir.yml +$ vendir sync +``` + +See [`vendir.yml` spec](vendir-spec.md) for its schema. + +## Sync with local changes override + +As of v0.7.0 you can use `--directory` flag to override contents of particular directories by pointing them to local directories. When this flag is specified other directories will not be synced (hence lock config is not going to be updated). + +``` +$ vendir sync --directory vendor/local-dir=local-dir-dev +``` + +## Sync with locks + +`vendir sync` writes [`vendir.lock.yml`](vendir-lock-spec.md) (next to `vendir.yml`) that contains resolved references: + +- for `git`, resolved SHAs are recorded +- for `hg`, resolved SHAs are recorded +- for `http`, nothing is recorded +- for `image`, resolved URL as a digest reference +- for `githubRelease`, permanent links are recorded +- for `helmChart`, resolved version +- for `directory`, nothing is recorded +- for `manual`, nothing is recorded + +To use these resolved references on top of `vendir.yml`, use `vendir sync -l`. + +## Syncing from different directory + +As of v0.22.0, you can use `--chdir` flag with `vendir sync` command to change current working directory of vendir before any syncing occurs. All other paths provided to `vendir sync` should be relative to the changed directory. + +## Caching + +`vendir` allows the users to cache OCI Images in their disk so as not to rely on access to the registry all the time. +To activate this feature the users need to set the environment variable `VENDIR_CACHE_DIR`. This variable should point +to the path where they want to store the OCI Images. + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ vendir sync +``` + +**Note:** Not all images can be cached. Only images that are referenced by SHA can be cached. + +The user can also specify what is the maximum size of the content to be cached, by setting the environment variable +`VENDIR_MAX_CACHE_SIZE`. The default value, when the variable is not provided is `1Mi` (1 Megabyte). + +The following are some accepted values: +``` +1 = 1 Byte +1Ki = 1 Kilobyte +1Mi = 1 Megabyte +1Gi = 1 Gigabyte +``` + +Example of usage: + +```bash-plain +$ mkdir -p ~/.vendir/cache +$ export VENDIR_CACHE_DIR=~/.vendir/cache +$ export VENDIR_MAX_CACHE_SIZE=1Ki +$ vendir sync +``` diff --git a/site/content/vendir/docs/v0.43.x/vendir-lock-spec.md b/site/content/vendir/docs/v0.43.x/vendir-lock-spec.md new file mode 100644 index 000000000..027838675 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/vendir-lock-spec.md @@ -0,0 +1,69 @@ +--- +aliases: [/vendir/docs/latest/vendir-lock-spec] +title: vendir.lock.yml spec +--- + +Lock file is generated by `vendir sync` and is placed next to related `vendir.yml`. + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: LockConfig + +directories: +- path: config/_ytt_lib + contents: + - path: github.com/cloudfoundry/cf-k8s-networking + + # present if this is managed manually + manual: {} + + # present if git + git: + # resolved checked out commit SHA + sha: 2b009b61fa8afb330a4302c694ee61b11104c54c + # resolved checked out commit title + commitTitle: 'feat: add /metrics prometheus scrapable endpoint...' + # resolved to a set of tags pointing to sha (v0.11.0+) + tags: + - "4.0.0" + + # present if hg (v0.22.0+) + hg: + # resolved checked out change SHA + sha: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # resolved checked out change title + changeSetTitle: 'Prevent wrapping filenames to preserve whitespace' + + # present if github release + githubRelease: + # resolved release url + url: https://api.github.com/repos/pivotal/kpack/releases/22747441 + + # present if helm chart (v0.11.0+) + helmChart: + appVersion: "5.0.7" + version: "10.5.7" + + # present if http + http: {} + + # present if image (v0.11.0+) + image: + # fully resolve image URL with digest + url: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if imgpkgBundle (v0.16.0+) + imgpkgBundle: + # fully resolve image URL with digest + image: index.docker.io/dkalinin/consul-helm@sha256:d1cdbd46561a144332f0744302d45f27583fc0d75002cba473d840f46630c9f7 + # included if image URL included a tag (v0.22.0+) + tag: "some-tag" + + # present if inline (v0.11.0+) + inline: {} + + # present if this was sourced from local directory + directory: {} +``` diff --git a/site/content/vendir/docs/v0.43.x/vendir-spec.md b/site/content/vendir/docs/v0.43.x/vendir-spec.md new file mode 100644 index 000000000..f80c12f74 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/vendir-spec.md @@ -0,0 +1,275 @@ +--- +aliases: [/vendir/docs/latest/vendir-spec] +title: vendir.yml spec +--- + +```yaml +apiVersion: vendir.k14s.io/v1alpha1 +kind: Config + +# declaration of minimum required vendir binary version (optional) +minimumRequiredVersion: 0.8.0 + +# one or more directories to manage with vendir +directories: +- # path is relative to `vendir` CLI working directory + path: config/_ytt_lib + + # set the permissions for this directory (optional; v0.33.0+) + # by default directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 + + contents: + - # path lives relative to directory path # (required) + path: github.com/cloudfoundry/cf-k8s-networking + + # skip fetching if the config for this path has not changed since the last sync + # optional, `false` by default, available since v0.36.0 + # use `vendir sync --lazy=false` to forcefully sync when needed + lazy: true + + # uses git to clone Git repository (optional) + git: + # http or ssh urls are supported (required) + url: https://github.com/cloudfoundry/cf-k8s-networking + # branch, tag, commit; origin is the name of the remote (required) + # optional if refSelection is specified (available in v0.11.0+) + ref: origin/master + # depth of commits to fetch; 0 (default) means everything (optional; v0.29.0+) + depth: 1 + # specifies a strategy to resolve to an explicit ref (optional; v0.11.0+) + refSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # skip downloading lfs files (optional) + lfsSkipSmudge: false + # skip SSL/TLS verification (optional) + dangerousSkipTLSVerify: false + # skip initializing any git submodules (optional; v0.28.0+) + skipInitSubmodules: false + # verify gpg signatures on commits or tags (optional; v0.12.0+) + verification: + publicKeysSecretRef: + name: my-git-gpg-auth + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-git-auth + # when this flag set to true it will set the Basic Auth header directly + # in git configuration to ensure that it does not try to use NTLM + forceHTTPBasicAuth: false + + # uses hg to clone Mercurial repository (optional; v0.22.0+) + hg: + # http or ssh urls are supported (required) + url: https://hg.sr.ht/~sircmpwn/hg.sr.ht + # branch, tag, commit (required) + ref: 180c776fe29448afa8c756ab572bab7a1cf17a06 + # specifies name of a secret with auth details; + # secret may include 'ssh-privatekey', 'ssh-knownhosts', + # 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-hg-auth + + # fetches asset over HTTP (optional) + http: + # asset URL (required) + url: + # verification checksum (optional) + sha256: "" + # specifies name of a secret with basic auth details; + # secret may include 'username', 'password' keys (optional) + secretRef: + # (required) + name: my-http-auth + # skip unpacking tar, tgz, and zip files; by default files are unpacked (optional) + disableUnpack: false + + # fetches asset from an image registry (optional; v0.11.0+) + image: + # image URL; could be plain, tagged or digest reference (required) + url: gcr.io/repo/image:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in url key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match url + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerousSkipTLSVerify: false + # specify the response timeout in seconds for imgpkg when querying the registry; defaults to 30 (optional; v0.40.0+) + responseHeaderTimeout: 30 + + # fetches imgpkg bundle from an image registry (optional; v0.16.0+) + imgpkgBundle: + # could be plain, tagged or digest reference (required) + image: gcr.io/repo/bundle:v1.0.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + # if specified, do not include a tag in image key + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # specifies name of a secret with registry auth details; + # secret may include 'username', 'password' and/or 'token' keys; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # of of v0.22.0+, multiple registry credentials are supported and + # are passed to imgpkg via env. registry hostname must match image + # for auth information to be chosen by imgpkg. + # (https://carvel.dev/imgpkg/docs/latest/auth/#via-environment-variables) + secretRef: + # (required) + name: my-image-auth + # specify wether to skip TLS verification; defaults to false (optional;v0.18.0+) + dangerousSkipTLSVerify: false + # specify the response timeout in seconds for imgpkg when querying the registry; defaults to 30 (optional; v0.40.0+) + responseHeaderTimeout: 30 + # paths to PEM files containing additional CA certificates required to securely connect to registries + additionalCACertificates: [] + + # fetches assets from a github release (optional) + githubRelease: + # slug for repository (org/repo) (required) + slug: k14s/kapp-controller + # use release tag (optional) + # optional if tagSelection is specified (available in v0.22.0+) + tag: v0.1.0 + # specifies a strategy to choose a tag (optional; v0.22.0+) + tagSelection: + semver: + # list of semver constraints (see versions.md for details) (required) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional; v0.12.0+) + prereleases: + # select prerelease versions that include given identifiers (optional; v0.12.0+) + identifiers: [beta, rc] + # use latest published version (optional) + latest: true + # use exact release URL (optional) + url: https://api.github.com/repos/k14s/kapp-controller/releases/21912613 + # only download specific assets (optional; v0.12.0+) + assetNames: ["release*.yml"] + # checksums for downloaded files (optional) + # (if release text body contains checksums, it's not necessary + # to manually specify them here) + checksums: + release.yml: 26bf09c42d72ae448af3d1ee9f6a933c87c4ec81d04d37b30e1b6a339f5983a7 + # disables checking auto-found checksums for downloaded files (optional) + # (checksums are extracted from release's text body + # based on following format ` `) + disableAutoChecksumValidation: true + # specifies which archive to unpack for contents (optional) + unpackArchive: + # (required) + path: release.tgz + # specifies name of a secret with github auth details; + # secret may include 'token' key (optional) + secretRef: + # (required) + name: my-gh-auth + # Used to create the URL of the asset to download the metadata + # from the Github Release. (optional) + http: + # The url parameter of http can interpolate the tag of the GitHub release using the {tag} token. + url: https://dl.k8s.io/release/{tag}/bin/linux/amd64/kubectl + + # fetch Helm chart contents (optional; v0.11.0+) + helmChart: + # chart name (required) + name: stable/redis + # use specific chart version (string; optional) + version: "1.2.1" + # specifies Helm repository to fetch from (optional) + repository: + # repository url; supports exprimental oci helm fetch via + # oci:// scheme (required) + url: https://... + # specifies name of a secret with helm repo auth details; + # secret may include 'username', 'password'; + # as of v0.19.0+, dockerconfigjson secrets are also supported (optional) + # as of v0.22.0+, 0 or 1 auth credential is expected within dockerconfigjson secret + # if >1 auth creds found, error will be returned. (currently registry hostname + # is not used when found in provide auth credential.) + secretRef: + # (required) + name: my-helm-auth + # specify helm binary version to use; + # '3' means binary 'helm3' needs to be on the path (optional) + helmVersion: "3" + + # copy contents from local directory (optional) + directory: + # local file system path relative to vendir.yml + path: some-path + + # states that directory specified by above path + # is managed by hand; nothing to do for vendir (optional) + manual: {} + + # specify contents inline within this file (optional; v0.11.0+) + inline: + # specifies mapping of paths to their content (optional) + paths: + dir/file.ext: file-content + # specifies content via secrets and config maps (optional) + pathsFrom: + - secretRef: + # (required) + name: secret-name + # specifies where to place files found in secret (optional) + directoryPath: dir + - configMapRef: + # (required) + name: cfgmap-name + # specifies where to place files found in config map (optional) + directoryPath: dir + + # includes paths specify what should be included. by default + # all paths are included (optional) + includePaths: + - cfroutesync/crds/**/* + - install/ytt/networking/**/* + + # exclude paths are "placed" on top of include paths (optional) + excludePaths: [] + + # specifies paths to files that need to be includes for + # legal reasons such as LICENSE file. Defaults to few + # LICENSE, NOTICE and COPYRIGHT variations (optional) + legalPaths: [] + + # make subdirectory to be new root path within this asset (optional; v0.11.0+) + newRootPath: cfroutesync + + # set the permissions for this content directory (optional; v0.33.0+) + # by default content directories will be created with 0700 + # can be provided as octal, in which case it needs to be prefixed with a `0` + permissions: 0700 +``` diff --git a/site/content/vendir/docs/v0.43.x/versions.md b/site/content/vendir/docs/v0.43.x/versions.md new file mode 100644 index 000000000..3a5791f62 --- /dev/null +++ b/site/content/vendir/docs/v0.43.x/versions.md @@ -0,0 +1,112 @@ +--- +aliases: [/vendir/docs/latest/versions] +title: Versions +--- + +Available in v0.12.0+. + +Vendir uses version selection in following places: + +- git source type for selection of `ref` based on Git tags +- image source type for selection of `tag` based on registry tags +- imgpkgBundle source type for selection of `tag` based on registry tags +- githubRelease source type for selection of `tag` based on tags + +--- +## VersionSelection type + +`VersionSelection` type may be used by other projects (such as kbld) for selection of versions in different contexts. All usage follows same spec: + +```yaml +# interpret versions according to semantic version spec. +# see semver section below for further details (required) +semver: + # list of semver constraints (optional) + constraints: ">0.4.0" + # by default prerelease versions are not included (optional) + prereleases: + # select prerelease versions that include given identifiers (optional) + identifiers: [beta, rc] +``` + +--- +## Semver + +[github.com/k14s/semver/v4 package](https://github.com/k14s/semver) is used for parsing "semver" versions. +It's a fork of [k14s/semver](https://github.com/k14s/semver). + +For valid semver syntax refer to . (Commonly-used `v` prefix will be ignored during parsing) + +For constraints syntax refer to [k14s/semver's Ranges section](https://github.com/k14s/semver#ranges). + +By default prerelease versions are not included in selection. See examples for details. + +### Examples + +Any version greater than 0.4.0 _without_ prereleases. + +```yaml +semver: + constraints: ">0.4.0" +``` + +Any version greater than 0.4.0 _with_ all prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: {} +``` + +Any version greater than 0.4.0 _with_ only beta or rc prereleases. + +```yaml +semver: + constraints: ">0.4.0" + prereleases: + identifiers: [beta, rc] +``` + +### sort-semver command + +`vendir tools sort-semver` command is included to showcase how vendir parses versions. + +- `--version` (`-v`) specifies one or more versions +- `--constraint` (`-c`) specifies zero or more constraints +- `--prerelease` specifies to include prereleases +- `--prerelease-identifier` specifies zero or more identifiers to match prereleases + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.1 v0.2.0 v0.3.0" +Versions + +Version +v0.0.1 +v0.1.0 +v0.2.0-pre.20 +v0.2.0+build.1 +v0.2.0 +v0.2.1 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` + +Note that by default prerelease versions are not included. Use configuration or flag to include them. + +```bash +$ vendir tools sort-semver -v "v0.0.1 v0.1.0 v0.2.0-pre.20 v0.2.0+build.1 v0.2.0 v0.3.0" -c ">=0.1.0" +Versions + +Version +v0.1.0 +v0.2.0+build.1 +v0.2.0 +v0.3.0 + +Highest version: v0.3.0 + +Succeeded +``` diff --git a/site/data/vendir/docs/toc-mapping.yml b/site/data/vendir/docs/toc-mapping.yml index a81485637..0d04f0cfb 100644 --- a/site/data/vendir/docs/toc-mapping.yml +++ b/site/data/vendir/docs/toc-mapping.yml @@ -17,3 +17,4 @@ v0.39.x: vendir-v0-39-x-toc v0.40.x: vendir-v0-40-x-toc v0.41.x: vendir-v0-41-x-toc v0.42.x: vendir-v0-42-x-toc +v0.43.x: vendir-v0-43-x-toc diff --git a/site/data/vendir/docs/vendir-v0-43-x-toc.yml b/site/data/vendir/docs/vendir-v0-43-x-toc.yml new file mode 100644 index 000000000..428a67fb5 --- /dev/null +++ b/site/data/vendir/docs/vendir-v0-43-x-toc.yml @@ -0,0 +1,29 @@ +toc: + - title: Introduction + subfolderitems: + - page: About vendir + url: / + - page: Install + url: /install + - title: Reference + subfolderitems: + - page: Sync command + url: /sync + - page: vendir.yml Spec + url: /vendir-spec + - page: vendir.lock.yml Spec + url: /vendir-lock-spec + - page: Versions + url: /versions + - page: Github Release + url: /github-release + - title: FAQ + subfolderitems: + - page: Code of Conduct + shared_url: /code-of-conduct + - page: Contributing + shared_url: /contributing + - page: Carvel Development Guidelines + shared_url: /development_guidelines + - page: Security + shared_url: /security-policy