Remote Sources

The package_sources field can be used to define additional locations to include when processing a configuration file. The locations can either be a local file path or a network accessible location.

By defining these additional sources you are able to extend your $PATH to make more resources accessible or even merge multiple configuration files into the current configuration file.

class cfngin.package_sources

There are three different types of package sources - git repository, local, and AWS S3.

git: list[cfngin.package_source.git] = []

A list of git repositories to include when processing the configuration file.

See Git Repository for detailed information.

package_sources:
  git:
    ...

local: list[cfngin.package_source.local] = []

A list of additional local directories to include when processing the configuration file.

See Local for detailed information.

package_sources:
  local:
    ...

s3: list[cfngin.package_source.s3] = []

A list of AWS S3 objects to include when processing the configuration file.

See AWS S3 for detailed information.

package_sources:
  s3:
    ...

Git Repository

class cfngin.package_source.git

Package source located in a git repository.

Cloned repositories are cached locally between runs. The cache location is defined by cfngin.config.cfngin_cache_dir.

branch: str | None = None

Name of a branch to checkout after cloning the git repository.

Only one of branch, commit, or tag can be defined.

Example

package_sources:
  git:
    - branch: master

commit: str | None = None

After cloning the git repository, reset HEAD to the given commit hash.

Only one of branch, commit, or tag can be defined.

Example

package_sources:
  git:
    - commit: 5d83f7ff1ad6527233be2c27e9f68816599b6c57

configs: list[str] = []

Configuration files from this source location can also be used by specifying a list of file paths.

These configuration files are merged into the current configuration file with the current file taking precedence. When using this usage pattern, it is advised to use dictionary definitions for everything that supports it to allow for granular overriding.

Example

package_sources:
  git:
    - configs:
      - example-01.yml
      - example-02.yml

paths: list[str] = []

A list of subdirectories within the source location that should be added to $PATH.

Example

package_sources:
  git:
    - paths:
      - some/directory/
      - another/

tag: str | None = None

After cloning the git repository, reset HEAD to the given tag.

Only one of branch, commit, or tag can be defined.

Example

package_sources:
  git:
    - tag: v1.0.0

uri: str

The protocol and URI address of the git repository.

Example

package_sources:
  git:
    - uri: git@github.com:rackspace/runway.git  # ssh
    - uri: https://github.com/rackspace/runway.git  # https

Local

class cfngin.package_source.local

Package source located on a local disk.

configs: list[str] = []

Configuration files from this source location can also be used by specifying a list of file paths.

These configuration files are merged into the current configuration file with the current file taking precedence. When using this usage pattern, it is advised to use dictionary definitions for everything that supports it to allow for granular overriding.

Example

package_sources:
  local:
    - configs:
      - example-01.yml
      - example-02.yml

paths: list[str] = []

A list of subdirectories within the source location that should be added to $PATH.

Example

package_sources:
  local:
    - paths:
      - some/directory/
      - another/

source: str

Path relative to the current configuration file that is the root of the local package source. Can also be provided as an absolute path but this is not recommended as it will be bound to your system.

Example

package_sources:
  local:
    - source: ./../example_code

AWS S3

class cfngin.package_source.s3

Package source located in AWS S3.

S3 objects are cached locally between runs. The cache location is defined by cfngin.config.cfngin_cache_dir.

bucket: str

Name of the AWS S3 bucket.

Example

package_sources:
  s3:
    - bucket: example-bucket

configs: list[str] = []

Configuration files from this source location can also be used by specifying a list of file paths.

These configuration files are merged into the current configuration file with the current file taking precedence. When using this usage pattern, it is advised to use dictionary definitions for everything that supports it to allow for granular overriding.

Example

package_sources:
  s3:
    - configs:
      - example-01.yml
      - example-02.yml

key: str

Key for an S3 object within the bucket. The object should be an archived file that can be unzipped.

Example

package_sources:
    s3:
      - key: path/to/example.zip

paths: list[str] = []

A list of subdirectories within the source location that should be added to $PATH.

Example

package_sources:
  s3:
    - paths:
      - some/directory/
      - another/

requester_pays: bool = False

Confirms that the requester knows that they will be charged for the request

Example

package_sources:
  s3:
    - requester_pays: true

use_latest: bool = True

Update the local copy if the last modified date in AWS S3 changes.

Example

package_sources:
  s3:
    - use_latest: true