Package types

This page contains documentation and metadata for all package types that come with bring. The 'Args' section in each item lists the argument each package type supports in the source part of a package description. For more details on how package descritions are build, check here

type: `git_files`¶

A package type to retrieve one or several files from a git repository.

Arguments¶

Name	Description	Type	Required
url	The git repo url.	string	yes
files	The list of files to retrieve.	list	yes
tag_filter	if provided, is used as regex to select wanted tags	string	no

Description¶

Under the hood, this uses the git archive command to retrieve a zipped archive of the requested files, so when specifying the git url, make sure to either use the git or ssh protocol, or, if using https, that the remote server supports Smart HTTP (GitHub, for example, does not as far as I know).

To filter out certain tags you don't want to end up as 'version's, you can use the tag_filter key, and specify a regular explression of 'allowed' tags.

Templated file paths are not supported currently, but will be in the future.

type: `git_repo`¶

A package that represents a git repository and its content.

Arguments¶

Name	Description	Type	Required	Default
url	The git repo url.	string	yes
use_commits_as_versions	Whether to use commit hashes as version strings.	boolean	no

Description¶

The only argument required is the git repository url. bring will download and cache (unless otherwise configured) the whole repo.

Depending on the repository size this might or might not be desirable. If the repository is large, and only one or a few files are wanted, it is probably better to use the git_files (or github_files, gitlab_files, ...) package type, as this only downloads the files needed. If one git repository is the shared source for multiple packages, this package type might be the better choice though, since it will be only downloaded and cached once, and retrieval of each of those packages is quicker (since the git repository is cached locally, and only a git checkout is necessary to retrieve a specific version).

By default, all tags and branches will be used as version names. If 'use_commits_as_versions' is set to 'true', also the commit hashes will be used. An alias 'latest' will be added, pointing to the latest tag, or, in case no tags exist, to the 'master' branch.

Examples¶

`scripts.bashtop`¶

Package description:

source:
  type: git_repo
  url: https://github.com/aristocratos/bashtop.git
  transform:
  - bashtop

type: `github_files`¶

A package type to retrieve one or several files from a git repository that is hosted on GitHub.

Arguments¶

Name	Description	Type	Required
user_name	The github user name.	string	yes
repo_name	The github repo name.	string	yes
files	The list of files to retrieve.	string	yes
tag_filter	if provided, is used as regex to select wanted tags	string	no
template_values	An (optional) map with the possible template var names in the value for 'files' as keys, and all allowed values for each key as value.	dict	no

Description¶

This package type directly downloads the required files from GitHub, without downloading the repository itself first.

This way of accessing files is advantageous if you only need a few, small files, and the repository itself is on the larger side. If this is not the case, consider using the 'git_repo' package type.

File-paths specified in the files argument can contain template place-holders (like: deploy/${provider}/config.json). If that is the case, you need to provide a list of possible values for each of the included placeholders in the template_values key (check the example below).

Examples¶

`kubernetes.ingress-nginx`¶

Package description:

source:
  use_commits_as_versions: false
  type: github_files
  user_name: kubernetes
  repo_name: ingress-nginx
  tag_filter: ingress-nginx-.*
  files:
  - deploy/static/provider/${provider}/deploy.yaml
  args:
    provider:
      doc: The provider to deploy to.
      default: cloud
      type: string
  template_values:
    provider:
    - cloud
    - baremetal
    - aws
    - do
  transform:
  - path: deploy.yaml
    from: deploy/static/provider/${provider}/deploy.yaml

type: `github_release`¶

A package type that tracks GitHub release artefacts.

Arguments¶

Name	Description	Type	Required
user_name	The github user name.	string	yes
repo_name	The github repo name.	string	yes
url_regex	The url regex to parse the release urls.	string	no

Description¶

To be able to get a list of all releases and their metadata, a package needs to specify the github user- and repo-names, as well as a regex to parse the release urls and compute the variables (version, architecture, os, etc.) involved to assemble a list of versions for a package.

This is a barebones example for a source definition for the fd application:

  source:
    type: github-release
    user_name: sharkdp
    repo_name: fd

    url_regex: 'https://github.com/.*/releases/download/v(?P<version>.*)/.*-v(?P=version)-(?P<arch>[^-]*)-(?P<os>[^.]*)\..*$'

More than one such regular expressions can be provided (in which case the value for url_regex should be a list), all matches for all regexes will be added to the resulting list.

Most of the regexes for different packages look fairly similar, but unfortunately Github release-urls don't follow a standard, which makes it impossible to come up with one that can be used for all of them. bring comes with a default regex that works for quite a few Github projects (and almost for a lot of others). In fact, the regex in the example above is the default regex that will be used if no 'url_regex' value is provided, and it so happens that it works for 'fd' (which means we could have omitted it for that particular application).

Nonetheless, whoever creates a new package manifest needs to manually verify whether the default regex works, and then adjust or create a totally different one if necessary.

Examples¶

`binaries.k3d`¶

Package description:

source:
  type: github_release
  user_name: rancher
  repo_name: k3d
  url_regex:
  - https://github.com/.*/releases/download/v(?P<version>.*)/k3d-(?P<os>[^-]*)-(?P<arch>[^.]*)$
  aliases:
    arch:
      x86_64: amd64
  artefact:
    type: file
  transform:
  - path: k3d
    from: k3d-${ os }-amd64
    mode: 755

`kubernetes.cert-manager`¶

Package description:

source:
  type: github_release
  user_name: jetstack
  repo_name: cert-manager
  url_regex:
  - https://github.com/jetstack/cert-manager/releases/download/v(?P<version>.*)/cert-manager.yaml$

type: `gitlab_files`¶

A package type to retrieve one or several files from a git repository that is hosted on GitLab.

Arguments¶

Name	Description	Type	Required
user_name	The gitlab user name.	string	yes
repo_name	The gitlab repo path (not internal name, which is different in some cases).	string	yes
files	The list of files to retrieve.	string	yes
tag_filter	if provided, is used as regex to select wanted tags	string	no
template_values	An (optional) map with the possible template var names in the value for 'files' as keys, and all allowed values for each key as value.	dict	no

Description¶

This package type directly downloads the required files from GitLab, without retrieving the repository itself first.

This way of accessing files is advantageous if you only need a few, small files, and the repository itself is on the larger side. If this is not the case, consider using the 'git_repo' package type.

File-paths specified in the files argument can contain template place-holders (like: deploy/${provider}/config.json). If that is the case, you need to provide a list of possible values for each of the included placeholders in the template_values key (check the example below).

Examples¶

`gitlab.bring-indexes.example-index.example_file1`¶

Package description:

source:

  type: gitlab_files


  user_name: bring-indexes        # required
  repo_name: example-source-repo        # required
  files: [some-files/file1.md]          # required

type: `template_url`¶

A package type to resolve packages whose artifacts are published with static urls that can be templated.

Arguments¶

Name	Description	Type	Required	Default
template_values	A map with the possible template var names as keys, and all allowed values for each key as value.	dict	yes
url	The templated url string, using '	string	yes

Description¶

All values of all template variables are combined with each of the other template variables to create a matrix of possible combinations. In some cases some of those combinations are not valid, and lead to a url that does not resolve to a file to download. At this time, there is nothing that can be done about it and the user will see an error message.

Examples¶

`binaries.kubectl`¶

Package description:

source:
  type: template_url
  url: https://storage.googleapis.com/kubernetes-release/release/v${version}/bin/${os}/${arch}/kubectl
  template_values:
    version:
    - 1.18.6
    - 1.18.5
    - 1.18.4
    - 1.18.3
    - 1.18.2
    - 1.18.1
    - 1.18.0
    - 1.17.9
    - 1.17.8
    - 1.17.7
    - 1.17.6
    - 1.17.5
    - 1.17.4
    - 1.17.3
    - 1.17.2
    - 1.17.1
    - 1.17.0
    - 1.16.13
    - 1.16.12
    os:
    - darwin
    - linux
    - windows
    arch:
    - amd64
    - arm
    - i386
  aliases:
    arch:
      x86_64: amd64
  transform:
    kubectl:
      mode: 755

`binaries.helm`¶

Package description:

source:
  type: template_url
  url: https://get.helm.sh/helm-v${version}-${os}-${arch}.tar.gz
  template_values:
    version:
    - 3.2.4
    - 3.2.3
    - 3.2.2
    - 3.2.1
    - 3.2.0
    - 3.1.3
    - 3.1.2
    - 3.1.1
    - 3.1.0
    - 3.0.3
    - 3.0.2
    - 3.0.1
    - 3.0.0
    - 2.16.9
    - 2.16.8
    - 2.16.7
    - 2.16.6
    - 2.16.5
    - 2.16.4
    - 2.16.3
    os:
    - darwin
    - linux
    - windows
    arch:
    - amd64
    - arm
    - i386
  aliases:
    arch:
      x86_64: amd64
  transform:
  - helm

Package types

type: git_files¶

Arguments¶

Description¶

type: git_repo¶

Arguments¶

Description¶

Examples¶

scripts.bashtop¶

type: github_files¶

Arguments¶

Description¶

Examples¶

kubernetes.ingress-nginx¶

type: github_release¶

Arguments¶

Description¶

Examples¶

binaries.k3d¶

kubernetes.cert-manager¶

type: gitlab_files¶

Arguments¶

Description¶

Examples¶

gitlab.bring-indexes.example-index.example_file1¶

type: template_url¶

Arguments¶

Description¶

Examples¶

binaries.kubectl¶

binaries.helm¶

type: `git_files`¶

type: `git_repo`¶

`scripts.bashtop`¶

type: `github_files`¶

`kubernetes.ingress-nginx`¶

type: `github_release`¶

`binaries.k3d`¶

`kubernetes.cert-manager`¶

type: `gitlab_files`¶

`gitlab.bring-indexes.example-index.example_file1`¶

type: `template_url`¶

`binaries.kubectl`¶

`binaries.helm`¶