Compiler Configuration Reference#

project.yml#

Inside any project the compiler expects a project.yml file that defines metadata about the project, the location to store modules, repositories where to find modules and possibly specific versions of modules.

For basic usage information, see Project creation guide.

The project.yml file defines the following settings:

class inmanta.module.ProjectMetadata(*, requires: List[str] = [], name: str, description: str | None = None, freeze_recursive: bool = False, freeze_operator: ConstrainedStrValue = '~=', author: str | None = None, author_email: NameEmail | None = None, license: str | None = None, copyright: str | None = None, modulepath: List[str] = [], repo: List[ModuleRepoInfo] = [], downloadpath: str | None = None, install_mode: InstallMode = InstallMode.release, relation_precedence_policy: List[ConstrainedStrValue] = [], strict_deps_check: bool = True, agent_install_dependency_modules: bool = False, pip: ProjectPipConfig = ProjectPipConfig(use_config_file=False, index_urls=[]))[source]#
Parameters:

  • name – The name of the project.

  • description – (Optional) An optional description of the project

  • author – (Optional) The author of the project

  • author_email – (Optional) The contact email address of author

  • license – (Optional) License the project is released under

  • copyright – (Optional) Copyright holder name and date.

  • modulepath – (Optional) This value is a list of paths where Inmanta should search for modules.

  • downloadpath – (Optional) This value determines the path where Inmanta should download modules from repositories. This path is not automatically included in the modulepath!

  • install_mode – (Optional) This key determines what version of a module should be selected when a module is downloaded. For more information see InstallMode.

  • repo –

    (Optional) A list (a yaml list) of repositories where Inmanta can find modules. Inmanta tries each repository in the order they appear in the list. Each element of this list requires a type and a url field. The type field can have the following values:

    • git: When the type is set to git, the url field should contain a template of the Git repo URL. Inmanta creates the git repo url by formatting {} or {0} with the name of the module. If no formatter is present it appends the name of the module to the URL.

    • package: [DEPRECATED] Setting up pip indexes should be done via the index_urls option of the pip section. See inmanta.module.ProjectPipConfig for more details.

    The old syntax, which only defines a Git URL per list entry is maintained for backward compatibility.

  • requires – (Optional) This key can contain a list (a yaml list) of version constraints for modules used in this project. Similar to the module, version constraints are defined using PEP440 syntax.

  • freeze_recursive – (Optional) This key determined if the freeze command will behave recursively or not. If freeze_recursive is set to false or not set, the current version of all modules imported directly in the main.cf file will be set in project.yml. If it is set to true, the versions of all modules used in this project will set in project.yml.

  • freeze_operator – (Optional) This key determines the comparison operator used by the freeze command. Valid values are [==, ~=, >=]. Default is ‘~=’

  • relation_precedence_policy – [EXPERIMENTAL FEATURE] A list of rules that indicate the order in which the compiler should freeze lists. The following syntax should be used to specify a rule <first-type>.<relation-name> before <then-type>.<relation-name>. With this rule in place, the compiler will first freeze first-type.relation-name and only then then-type.relation-name.

  • strict_deps_check – Determines whether the compiler or inmanta tools that install/update module dependencies, should check the virtual environment for version conflicts in a strict way or not. A strict check means that all transitive dependencies will be checked for version conflicts and that any violation will result in an error. When a non-strict check is done, only version conflicts in a direct dependency will result in an error. All other violations will only result in a warning message.

  • agent_install_dependency_modules –

    [EXPERT FEATURE] If true, when a module declares Python dependencies on other (v2) modules, the agent will install these dependency modules with pip. This option should only be enabled if the agent is configured with the appropriate pip related environment variables. The option allows to an extent for inter-module dependencies within handler code, even if the dependency module doesn’t have any handlers that would otherwise be considered relevant for this agent.

    Care should still be taken when you use inter-module imports. The current code loading mechanism does not explicitly order reloads. A general guideline is to use qualified imports where you can (import the module rather than objects from the module). When this is not feasible, you should be aware of Python’s reload semantics and take this into account when making changes to handler code.

    Another caveat is that if the dependency module does contain code that is relevant for the agent, it will be loaded like any other handler code and it will be this code that is imported by any dependent modules (though depending on the load order the very first import may use the version installed by pip). If at some point this dependency module’s handlers cease to be relevant for this agent, its code will remain stale. Therefore this feature should not be depended on in transient scenarios like this.

  • pip – A configuration section that holds information about the pip configuration that should be taken into account when installing Python packages (See: inmanta.module.ProjectPipConfig for more details).

class inmanta.module.ProjectPipConfig(*, use_config_file: bool = False, index_urls: List[str] = [])[source]#
Parameters:

  • use_config_file – Indicates whether the pip configuration files have to be taken into account when installing Python packages.

  • index_urls – List of pip indexes to use project-wide. These repositories should be PEP 503 (the simple repository API) compliant. If more than one index url is configured, they will all be passed to pip. This is generally only recommended if all configured indexes are under full control of the end user to protect against dependency confusion attacks. See the pip install documentation and PEP 708 (draft) for more information.

The code snippet below provides an example of a complete project.yml file:

name: quickstart
description: A quickstart project that installs a drupal website.
author: Inmanta
author_email: code@inmanta.com
license: Apache 2.0
copyright: Inmanta (2021)
modulepath: libs
downloadpath: libs
install_mode: release
repo:
  - url: https://github.com/inmanta/
    type: git
requires:
  - apache ~= 0.5.2
  - drupal ~= 0.7.3
  - exec ~= 1.1.4
  - ip ~= 1.2.1
  - mysql ~= 0.6.2
  - net ~= 1.0.5
  - php ~= 0.3.1
  - redhat ~= 0.9.2
  - std ~= 3.0.2
  - web ~= 0.3.3
  - yum ~= 0.6.2
freeze_recursive: true
freeze_operator: ~=
pip:
  use_config_file: false
  index_urls:
    - https://pypi.org/simple/

Specify locations from where V2 modules will be installed#

This section explains how to configure your project in order to download v2 modules from any python package repository. By default, a project created using the Project creation guide is configured to install packages from https://pypi.org/simple/. There are multiple ways to change this behaviour.

Using pip config file#

By setting the use_config_file option of the pip section to True, the project will use the pip config files.

pip:
  use_config_file: True

To specify the url of a pip repository, add the following to the pip config file of the inmanta user, located at /var/lib/inmanta/.config/pip/pip.conf:

[global]
timeout = 60
index-url = <url of a python package repository>

Alternatively, a pip config file can be used at a custom location. The index-url can be specified in this file as explained in the previous section. To make this work, the PIP_CONFIG_FILE environment variable needs to be set to the path of the newly created file (See: Environment variables). For more information see the Pip documentation.

Specify the index-urls in the project.yml file#

Another option is to use the index_urls option in the pip section of the project.yml file:

pip:
  use_config_file: False
  index_urls:
    - <url of a python package repository>

Note

The pip config file can also be used in combination with index-urls specified in the pip section of the project.yml file:

  • If the pip config is used (by setting use_config_file to true), the index-url specified in the pip config file will take precedence and the index-urls specified in the pip section of the project.yml file will be used as extra-index-urls when installing with pip.

  • If the pip config is not used (by setting use_config_file to False), then the first index_url specified in the project.yml will be used as an index_url and all the following ones will be used as extra-index-urls when installing with pip.

Module metadata files#

The metadata of a V1 module is present in the module.yml file. V2 modules keep their metadata in the setup.cfg file. Below sections describe each of these metadata files.

module.yml#

Inside any V1 module the compiler expects a module.yml file that defines metadata about the module.

The module.yml file defines the following settings:

class inmanta.module.ModuleMetadata(*, name: str, description: str | None = None, freeze_recursive: bool = False, freeze_operator: ConstrainedStrValue = '~=', version: str, license: str, deprecated: bool | None = None)[source]#

The code snippet below provides an example of a complete module.yml file:

name: openstack
description: A module to manage networks, routers, virtual machine, etc. on an Openstack cluster.
version: 3.7.1
license: Apache 2.0
compiler_version: 2020.2
requires:
  - ip
  - net
  - platform
  - ssh
  - std
freeze_recursive: false
freeze_operator: ~=

setup.cfg#

Inside any V2 module the compiler expects a setup.cfg file that defines metadata about the module.

The code snippet below provides an example of a complete setup.cfg file:

[metadata]
name = inmanta-module-openstack
description = A module to manage networks, routers, virtual machine, etc. on an Openstack cluster.
version = 3.7.1
license = Apache 2.0
compiler_version = 2020.2
freeze_recursive = false
freeze_operator = ~=

[options]
install_requires =
  inmanta-modules-ip
  inmanta-modules-net
  inmanta-modules-platform
  inmanta-modules-ssh
  inmanta-modules-std