Programmatic API reference

This page describes parts of inmanta code base that provide a stable API that could be used from modules or extensions.

Warning

Only those parts explicitly mentioned here are part of the API. They provide a stable interface. Other parts of the containing modules provide no such guarantees.

Constants

class inmanta.const.LogLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Log levels used for various parts of the inmanta orchestrator.

CRITICAL = 'CRITICAL'

DEBUG = 'DEBUG'

ERROR = 'ERROR'

INFO = 'INFO'

TRACE = 'TRACE'

WARNING = 'WARNING'

property to_int: int

class inmanta.const.ResourceAction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Enumeration of all resource actions.

deploy = 'deploy'

dryrun = 'dryrun'

getfact = 'getfact'

other = 'other'

pull = 'pull'

push = 'push'

store = 'store'

inmanta_lsm.const.LSM_ENV_VARS : Sequence[str]

This sequence contains all environment variables passed to the compiler by inmanta-lsm

Compiler exceptions

class inmanta.ast.CompilerException(msg: str)

Bases: Exception, Exportable

Base class for exceptions generated by the compiler

class inmanta.parser.ParserException(location: Location, value: object, msg: str | None = None)

Bases: CompilerException

Exception occurring during the parsing of the code

class inmanta.ast.RuntimeException(stmt: Locatable | None, msg: str)

Bases: CompilerException

Baseclass for exceptions raised by the compiler after parsing is complete.

class inmanta.ast.ExternalException(stmt: Locatable | None, msg: str, cause: Exception)

Bases: RuntimeException

When a plugin call produces an exception that is not a RuntimeException, it is wrapped in an ExternalException to make it conform to the expected interface

class inmanta.ast.ExplicitPluginException(stmt: Locatable | None, msg: str, cause: PluginException)

Bases: ExternalException

Base exception for wrapping an explicit inmanta.plugins.PluginException raised from a plugin call.

Plugins

class inmanta.plugins.Context(resolver: Resolver, queue: QueueScheduler, owner: FunctionCall, plugin: Plugin, result: ResultVariable)

An instance of this class is used to pass context to the plugin

get_client() → Client

get_compiler() → Compiler

get_data_dir() → str

Get the path to the data dir (and create if it does not exist yet

get_environment_id() → str

get_queue_scheduler() → QueueScheduler

get_resolver() → Resolver

get_sync_client() → SyncClient

get_type(name: LocatableString) → Type

Get a type from the configuration model.

run_sync(function: Callable[[], Awaitable[T]], timeout: int = 5) → T

Execute the async function and return its result. This method uses this thread’s current (not running) event loop if there is one, otherwise it creates a new one. The main use for this function is to use the inmanta internal rpc to communicate with the server.

Parameters:

• function – The async function to execute. This function should return a yieldable object.

• timeout – A timeout for the async function.

Returns:

The result of the async call.

Raises:

ConnectionRefusedError – When the function timeouts this exception is raised.

inmanta.plugins.plugin(function: Callable | None = None, commands: list[str] | None = None, emits_statements: bool = False, allow_unknown: bool = False) → Callable

Python decorator to register functions with inmanta as plugin

Parameters:

• function – The function to register with inmanta. This is the first argument when it is used as decorator.

• commands – A list of command paths that need to be available. Inmanta raises an exception when the command is not available.

• emits_statements – Set to true if this plugin emits new statements that the compiler should execute. This is only required for complex plugins such as integrating a template engine.

• allow_unknown – Set to true if this plugin accepts Unknown values as valid input.

class inmanta.plugins.PluginException(message: str)

Base class for custom exceptions raised from a plugin.

class inmanta.plugins.PluginMeta(name: str, bases: tuple[type, ...], dct: dict[str, object])

Bases: type

A metaclass that keeps track of concrete plugin subclasses. This class is responsible for all plugin registration.

classmethod add_function(plugin_class: type[Plugin]) → None

Add a function plugin class

classmethod clear(inmanta_module: str | None = None) → None

Clears registered plugin functions.

Parameters:

inmanta_module – Clear plugin functions for a specific inmanta module. If omitted, clears all registered plugin functions.

classmethod get_functions() → dict[str, Type[Plugin]]

Get all functions that are registered

Resources

inmanta.resources.resource(name: str, id_attribute: str, agent: str)

A decorator that registers a new resource. The decorator must be applied to classes that inherit from Resource

Parameters:

• name – The name of the entity in the configuration model it creates a resources from. For example std::testing::NullResource

• id_attribute – The attribute of this resource that uniquely identifies a resource on an agent. This attribute can be mapped.

• agent – This string indicates how the agent of this resource is determined. This string points to an attribute, but it can navigate relations (this value cannot be mapped). For example, the agent argument could be host.name

class inmanta.resources.Resource(_id: Id)

Plugins should inherit resource from this class so a resource from a model can be serialized and deserialized.

Such as class is registered when the resource() decorator is used. Each class needs to indicate the fields the resource will have with a class field named “fields”. A metaclass merges all fields lists from the class itself and all superclasses. If a field it not available directly in the model object the serializer will look for static methods in the class with the name “get_$fieldname”.

clone(**kwargs: Any) → T

Create a clone of this resource. The given kwargs can be used to override attributes.

Returns:

The cloned resource

class inmanta.resources.PurgeableResource(_id: Id)

See std::PurgeableResource for more information.

class inmanta.resources.ManagedResource(_id: Id)

See std::ManagedResource for more information.

class inmanta.resources.IgnoreResourceException

Throw this exception when a resource should not be included by the exported. Typically resources use this to indicate that they are not managed by the orchestrator.

class inmanta.resources.Id(entity_type: str, agent_name: str, attribute: str, attribute_value: str, version: int = 0)

A unique id that identifies a resource that is managed by an agent

classmethod parse_id(resource_id: ResourceVersionIdStr | ResourceIdStr, version: int | None = None) → Id

Parse the resource id and return the type, the hostname and the resource identifier.

Parameters:

version – If provided, the version field of the returned Id will be set to this version.

resource_str() → ResourceIdStr

String representation for this resource id with the following format:

<type>[<agent>,<attribute>=<value>]

• type: The resource type, as defined in the configuration model.

  For example std::testing::NullResource.

• agent: The agent responsible for this resource.

• attribute: The key attribute that uniquely identifies this resource on the agent

• value: The corresponding value for this key attribute.

Returns:

Returns a inmanta.data.model.ResourceIdStr

class inmanta.execute.util.Unknown(source: object)

An instance of this class is used to indicate that this value can not be determined yet.

Parameters:

source – The source object that can determine the value

Handlers

inmanta.agent.handler.cache(func: T_FUNC | None = None, ignore: list[str] = [], timeout: int = 5000, for_version: bool = True, cache_none: bool = True, cacheNone: bool | None = None, call_on_delete: Callable[[Any], None] | None = None) → T_FUNC | Callable[[T_FUNC], T_FUNC]

decorator for methods in resource handlers to provide caching

this decorator works similar to memoization: when the decorate method is called, its return value is cached, for subsequent calls, the cached value is used instead of the actual value

The name of the method + the arguments of the method form the cache key

If an argument named version is present and for_version is True, the cache entry is flushed after this version has been deployed If an argument named resource is present, it is assumed to be a resource and its ID is used, without the version information

Parameters:

• timeout – the number of second this cache entry should live

• for_version – if true, this value is evicted from the cache when this deploy is ready

• ignore – a list of argument names that should not be part of the cache key

• cache_none – cache returned none values

• call_on_delete – A callback function that is called when the value is removed from the cache, with the value as argument.

inmanta.agent.handler.provider(resource_type: str, name: str) → None

A decorator that registers a new handler.

Parameters:

• resource_type – The type of the resource this handler is responsible for. For example, std::testing::NullResource

• name – A name to reference this provider.

class inmanta.agent.handler.SkipResource

Bases: Exception

A handler should raise this exception when a resource should be skipped. The resource will be marked as skipped instead of failed.

class inmanta.agent.handler.ResourcePurged

If the read_resource() method raises this exception, the agent will mark the current state of the resource as purged.

class inmanta.agent.handler.HandlerContext(resource: Resource, dry_run: bool = False, action_id: UUID | None = None, logger: Logger | None = None)

Context passed to handler methods for state related “things”

add_change(name: str, desired: object, current: object = None) → None

Report a change of a field. This field is added to the set of updated fields

Parameters:

• name – The name of the field that was updated

• desired – The desired value to which the field was updated (or should be updated)

• current – The value of the field before it was updated

add_changes(**kwargs: BaseModel | UUID | bool | int | float | datetime | str) → None

Report a list of changes at once as kwargs

Parameters:

• key – The name of the field that was updated. This field is also added to the set of updated fields

• value – The desired value of the field.

To report the previous value of the field, use the add_change method

fields_updated(fields: str) → None

Report that fields have been updated

is_dry_run() → bool

Is this a dryrun?

set_fact(fact_id: str, value: str, expires: bool = True) → None

Send a fact to the Inmanta server.

Parameters:

• fact_id – The name of the fact.

• value – The actual value of the fact.

• expires – Whether this fact expires or not.

set_status(status: ResourceState) → None

Set the status of the handler operation.

update_changes(changes: dict[str, AttributeStateChange]) → None

update_changes(changes: dict[str, dict[str, BaseModel | UUID | bool | int | float | datetime | str | None]]) → None

update_changes(changes: dict[str, tuple[BaseModel | UUID | bool | int | float | datetime | str, BaseModel | UUID | bool | int | float | datetime | str]]) → None

Update the changes list with changes

Parameters:

changes – This should be a dict with a value a dict containing “current” and “desired” keys

class inmanta.agent.handler.ResourceHandler(agent: inmanta.agent.agent.AgentInstance, io: IOBase | None = None)

A class that handles resources.

_abc_impl = <_abc._abc_data object>

_diff(current: TResource, desired: TResource) → dict[str, dict[str, Any]]

Calculate the diff between the current and desired resource state.

Parameters:

• current – The current state of the resource

• desired – The desired state of the resource

Returns:

A dict with key the name of the field and value another dict with “current” and “desired” as keys for fields that require changes.

check_facts(ctx: HandlerContext, resource: TResource) → dict[str, object]

This method is called by the agent to query for facts. It runs pre() and post(). This method calls facts() to do the actual querying.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to query facts for.

Returns:

A dict with fact names as keys and facts values.

check_resource(ctx: HandlerContext, resource: TResource) → TResource

Check the current state of a resource

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

Returns:

A resource to represents the current state. Use the clone() to create clone of the given resource that can be modified.

do_changes(ctx: HandlerContext, resource: TResource, changes: Mapping[str, Mapping[str, object]]) → None

Do the changes required to bring the resource on this system in the state of the given resource.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

• changes – The changes that need to occur as reported by list_changes()

execute(ctx: HandlerContext, resource: TResource, dry_run: bool = False) → None

Enforce a resource’s intent and inform the handler context of any relevant changes (e.g. set deployed status, report attribute changes). Called only when all of its dependencies have successfully deployed.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to deploy.

• dry_run – If set to true, the intent is not enforced, only the set of changes it would bring is computed.

list_changes(ctx: HandlerContext, resource: TResource) → dict[str, dict[str, Any]]

Returns the changes required to bring the resource on this system in the state described in the resource entry. This method calls check_resource()

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

Returns:

A dict with key the name of the field and value another dict with “current” and “desired” as keys for fields that require changes.

class inmanta.agent.handler.CRUDHandler(agent: inmanta.agent.agent.AgentInstance, io: IOBase | None = None)

This handler base class requires CRUD methods to be implemented: create, read, update and delete. Such a handler only works on purgeable resources.

available(resource: TResource) → bool

Kept for backwards compatibility, new handler implementations should never override this.

Parameters:

resource – Resource for which to check whether this handler is available.

calculate_diff(ctx: HandlerContext, current: TPurgeableResource, desired: TPurgeableResource) → dict[str, dict[str, Any]]

Calculate the diff between the current and desired resource state.

Parameters:

• ctx – Context can be used to get values discovered in the read method. For example, the id used in API calls. This context should also be used to let the handler know what changes were made to the resource.

• current – The current state of the resource

• desired – The desired state of the resource

Returns:

A dict with key the name of the field and value another dict with “current” and “desired” as keys for fields that require changes.

can_reload() → bool

Can this handler reload?

Returns:

Return true if this handler needs to reload on requires changes.

check_facts(ctx: HandlerContext, resource: TResource) → dict[str, object]

This method is called by the agent to query for facts. It runs pre() and post(). This method calls facts() to do the actual querying.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to query facts for.

Returns:

A dict with fact names as keys and facts values.

check_resource(ctx: HandlerContext, resource: TResource) → TResource

Check the current state of a resource

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

Returns:

A resource to represents the current state. Use the clone() to create clone of the given resource that can be modified.

close() → None

Override this method to implement custom logic called by the agent on handler deactivation. i.e. when the instantiated handler will no longer be used by the agent.

create_resource(ctx: HandlerContext, resource: TPurgeableResource) → None

This method is called by the handler when the resource should be created.

Parameters:

• context – Context can be used to get values discovered in the read method. For example, the id used in API calls. This context should also be used to let the handler know what changes were made to the resource.

• resource – The desired resource state.

delete_resource(ctx: HandlerContext, resource: TPurgeableResource) → None

This method is called by the handler when the resource should be deleted.

Parameters:

• ctx – Context can be used to get values discovered in the read method. For example, the id used in API calls. This context should also be used to let the handler know what changes were made to the resource.

• resource – The desired resource state.

deploy(ctx: HandlerContext, resource: TResource, requires: Mapping[ResourceIdStr, ResourceState]) → None

Main entrypoint of the handler that will be called by the agent to deploy a resource on the server. The agent calls this method for a given resource as soon as all its dependencies (requires relation) are ready. It is always called, even when one of the dependencies failed to deploy.

Takes appropriate action based on the state of its dependencies. Calls execute iff the handler should actually execute, i.e. enforce the intent represented by the resource. A handler may choose not to proceed to this execution stage, e.g. when one of the resource’s dependencies failed.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to deploy

• requires – A dictionary mapping the resource id of each dependency of the given resource to its resource state.

do_changes(ctx: HandlerContext, resource: TResource, changes: Mapping[str, Mapping[str, object]]) → None

Do the changes required to bring the resource on this system in the state of the given resource.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

• changes – The changes that need to occur as reported by list_changes()

do_reload(ctx: HandlerContext, resource: TResource) → None

Perform a reload of this resource.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to reload.

execute(ctx: HandlerContext, resource: TPurgeableResource, dry_run: bool = False) → None

Enforce a resource’s intent and inform the handler context of any relevant changes (e.g. set deployed status, report attribute changes). Called only when all of its dependencies have successfully deployed.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to deploy.

• dry_run – If set to true, the intent is not enforced, only the set of changes it would bring is computed.

facts(ctx: HandlerContext, resource: TResource) → dict[str, object]

Override this method to implement fact querying. A queried fact can be reported back in two different ways: either via the return value of this method or by adding the fact to the HandlerContext via the set_fact() method. pre() and post() are called before and after this method.

Parameters:

• ctx – Context object to report changes, logs and facts to the agent and server.

• resource – The resource to query facts for.

Returns:

A dict with fact names as keys and facts values.

get_client() → SessionClient

Get the client instance that identifies itself with the agent session.

Returns:

A client that is associated with the session of the agent that executes this handler.

get_file(hash_id: str) → bytes | None

Retrieve a file from the fileserver identified with the given id.

Parameters:

hash_id – The id of the content/file to retrieve from the server.

Returns:

The content in the form of a bytestring or none is the content does not exist.

list_changes(ctx: HandlerContext, resource: TResource) → dict[str, dict[str, Any]]

Returns the changes required to bring the resource on this system in the state described in the resource entry. This method calls check_resource()

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource to check the current state of.

Returns:

A dict with key the name of the field and value another dict with “current” and “desired” as keys for fields that require changes.

post(ctx: HandlerContext, resource: TResource) → None

Method executed after a handler operation. Override this method to run after an operation.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource being handled.

pre(ctx: HandlerContext, resource: TResource) → None

Method executed before a handler operation (Facts, dryrun, real deployment, …) is executed. Override this method to run before an operation.

Parameters:

• ctx – Context object to report changes and logs to the agent and server.

• resource – The resource being handled.

read_resource(ctx: HandlerContext, resource: TPurgeableResource) → None

This method reads the current state of the resource. It provides a copy of the resource that should be deployed, the method implementation should modify the attributes of this resource to the current state.

Parameters:

• ctx – Context can be used to pass value discovered in the read method to the CUD methods. For example, the id used in API calls

• resource – A clone of the desired resource state. The read method need to set values on this object.

Raises:

• SkipResource – Raise this exception when the handler should skip this resource

• ResourcePurged – Raise this exception when the resource does not exist yet.

run_sync(func: Callable[[], Awaitable[T]]) → T

Run the given async function on the ioloop of the agent. It will block the current thread until the future resolves.

Parameters:

func – A function that returns a yieldable future.

Returns:

The result of the async function.

set_cache(cache: AgentCache) → None

The agent calls this method when it has deemed this handler suitable for a given resource. This cache will be used for methods decorated with @cache.

Parameters:

cache – The AgentCache to use.

stat_file(hash_id: str) → bool

Check if a file exists on the server.

Parameters:

hash_id – The id of the file on the server. The convention is the use the sha1sum of the content as id.

Returns:

True if the file is available on the server.

update_resource(ctx: HandlerContext, changes: dict[str, dict[str, Any]], resource: TPurgeableResource) → None

This method is called by the handler when the resource should be updated.

Parameters:

• ctx – Context can be used to get values discovered in the read method. For example, the id used in API calls. This context should also be used to let the handler know what changes were made to the resource.

• changes – A map of resource attributes that should be changed. Each value is a tuple with the current and the desired value.

• resource – The desired resource state.

upload_file(hash_id: str, content: bytes) → None

Upload a file to the server

Parameters:

• hash_id – The id to identify the content. The convention is to use the sha1sum of the content to identify it.

• content – A byte string with the content

class inmanta.agent.io.local.LocalIO(uri: str, config: Dict[str, str | None])

This class provides handler IO methods

This class is part of the stable API.

chmod(path: str, permissions: str) → None

Change the permissions

Parameters:

• path (str) – The path of the file or directory to change the permission of.

• permissions (str) – An octal string with the permission to set.

chown(path: str, user: str | None = None, group: str | None = None) → None

Change the ownership of a file.

Parameters:

• path (str) – The path of the file or directory to change the ownership of.

• user (str) – The user to change to

• group (str) – The group to change to

close() → None

Close any resources

file_exists(path: str) → bool

Check if a given file exists

Parameters:

path (str) – The path to check if it exists.

Returns:

Returns true if the file exists

Return type:

bool

file_stat(path: str) → Dict[str, int | str]

Do a stat call on a file

Parameters:

path (str) – The file or direct to stat

Returns:

A dict with the owner, group and permissions of the given path

Return type:

dict[str, str]

hash_file(path: str) → str

Return the sha1sum of the file at path

Parameters:

path (str) – The path of the file to hash the content of

Returns:

The sha1sum in a hex string

Return type:

str

is_remote() → bool

Are operation executed remote

Returns:

Returns true if the io operations are remote.

Return type:

bool

is_symlink(path: str) → bool

Is the given path a symlink

Parameters:

path (str) – The path of the symlink

Returns:

Returns true if the given path points to a symlink

Return type:

str

mkdir(path: str) → None

Create a directory

Parameters:

path (str) – Create this directory. The parent needs to exist.

put(path: str, content: str) → None

Put the given content at the given path

Parameters:

• path (str) – The location where to write the file

• content (bytes) – The binarystring content to write to the file.

read(path: str) → str

Read in the file in path and return its content as string

Parameters:

path (str) – The path of the file to read.

Returns:

The string content of the file

Return type:

string

read_binary(path: str) → bytes

Read in the file in path and return its content as a bytestring

Parameters:

path (str) – The path of the file to read.

Returns:

The byte content of the file

Return type:

bytes

readlink(path: str) → str

Return the target of the path

Parameters:

path (str) – The symlink to get the target for.

Returns:

The target of the symlink

Return type:

str

remove(path: str) → None

Remove a file

Parameters:

path (str) – The path of the file to remove.

rmdir(path: str) → None

Remove a directory

Parameters:

path (str) – The directory to remove

run(command: str, arguments: List[str] = [], env: Dict[str, str] | None = None, cwd: str | None = None, timeout: int | None = None) → Tuple[str, str, int]

Execute a command with the given argument and return the result

Parameters:

• command (str) – The command to execute.

• arguments (list) – The arguments of the command

• env (dict) – A dictionary with environment variables.

• cwd (str) – The working dir to execute the command in.

• timeout (int) – The timeout for this command. This parameter is ignored if the command is executed remotely with a python 2 interpreter.

Returns:

A tuple with (stdout, stderr, returncode)

Return type:

tuple

symlink(source: str, target: str) → None

Symlink source to target

Parameters:

• source (str) – Create a symlink of this path to target

• target (str) – The path of the symlink to create

Export

@inmanta.export.dependency_manager(function: Callable[[dict[str, Entity], dict[Id, Resource]], None]) → None

Register a function that manages dependencies in the configuration model that will be deployed.

Attributes

class inmanta.ast.attribute.Attribute(entity: Entity, value_type: Type, name: str, location: Location, multi: bool = False, nullable: bool = False)

The attribute base class for entity attributes.

Parameters:

entity – The entity this attribute belongs to

get_type() → Type

Get the type of this attribute.

property type: Type

Get the type of this attribute.

validate(value: object) → None

Validate a value that is going to be assigned to this attribute. Raises a inmanta.ast.RuntimeException if validation fails.

class inmanta.ast.attribute.RelationAttribute(entity: Entity, value_type: Type, name: str, location: Location)

Bases: Attribute

An attribute that is a relation

Modules

class inmanta.module.InstallMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

The module install mode determines what version of a module should be selected when a module is downloaded.

master = 'master'

For V1 modules: Use the module’s master branch. For V2 modules: Equivalent to InstallMode.prerelease

prerelease = 'prerelease'

Similar to InstallMode.release but prerelease versions are allowed as well.

release = 'release'

Only use a released version that is compatible with the current compiler and any version constraints defined in the requires lists for the project or any other modules (see ProjectMetadata, ModuleV1Metadata and ModuleV2Metadata).

A module is considered released in the following situations:

• For V1 modules: There is a tag on a commit. This tag is a valid, pep440 compliant version identifier and it’s not a

  prelease version.

• For V2 modules: The python package was published on a Python package repository, the version identifier is pep440

  compliant and is not a prerelease version.

inmanta.module.INSTALL_OPTS: list[str] = ['release', 'prerelease', 'master']

List of possible module install modes, kept for backwards compatibility. New code should use InstallMode instead.

class inmanta.module.InvalidModuleException(msg: str)

This exception is raised if a module is invalid.

class inmanta.module.InvalidMetadata(msg: str, validation_error: ValidationError | None = None)

This exception is raised if the metadata file of a project or module is invalid.

class inmanta.module.ModuleLike(path: str)

Bases: ABC, Generic[TMetadata]

Commons superclass for projects and modules, which are both versioned by git

Variables:

name – The name for this module like instance, in the context of the Inmanta DSL.

abstract classmethod from_path(path: str) → ModuleLike | None

Get a concrete module like instance from a path. Returns None when no project or module is present at the given path.

property metadata: TMetadata

class inmanta.module.Module(project: Project | None, path: str)

Bases: ModuleLike[TModuleMetadata], ABC

This class models an inmanta configuration module

abstract classmethod from_path(path: str) → Module | None

Get a concrete module like instance from a path. Returns None when no project or module is present at the given path.

get_plugin_files() → Iterator[tuple[Path, ModuleName]]

Returns a tuple (absolute_path, fq_mod_name) of all python files in this module.

unload() → None

Unloads this module instance from the project, the registered plugins and the loaded Python modules.

inmanta.module.ModuleName = inmanta.module.ModuleName

NewType creates simple unique types with almost zero runtime overhead.

NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy callable that simply returns its argument.

Usage:

UserId = NewType('UserId', int)

def name_by_id(user_id: UserId) -> str:
    ...

UserId('user')          # Fails type check

name_by_id(42)          # Fails type check
name_by_id(UserId(42))  # OK

num = UserId(5) + 1     # type: int

class inmanta.module.ModuleV1(project: Project | None, path: str)

Bases: Module[ModuleV1Metadata], ModuleLikeWithYmlMetadataFile

classmethod from_path(path: str) → TModule | None

Get a concrete module like instance from a path. Returns None when no project or module is present at the given path.

class inmanta.module.ModuleV2(project: Project | None, path: str, is_editable_install: bool = False, installed_version: Version | None = None)

Bases: Module[ModuleV2Metadata]

classmethod from_path(path: str) → TModule | None

Get a concrete module like instance from a path. Returns None when no project or module is present at the given path.

is_editable() → bool

Returns True iff this module has been installed in editable mode.

class inmanta.module.ModuleSource

Bases: Generic[TModule]

get_installed_module(project: Project | None, module_name: str) → TModule | None

Returns a module object for a module if it is installed.

Parameters:

• project – The project associated with the module.

• module_name – The name of the module.

class inmanta.module.ModuleV2Source(urls: Sequence[str] = [])

Bases: ModuleSource[ModuleV2]

inmanta.module.Path = inmanta.module.Path

NewType creates simple unique types with almost zero runtime overhead.

NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns a dummy callable that simply returns its argument.

Usage:

UserId = NewType('UserId', int)

def name_by_id(user_id: UserId) -> str:
    ...

UserId('user')          # Fails type check

name_by_id(42)          # Fails type check
name_by_id(UserId(42))  # OK

num = UserId(5) + 1     # type: int

class inmanta.loader.PluginModuleFinder(modulepaths: list[str])

Bases: MetaPathFinder

Custom module finder which handles V1 Inmanta modules. V2 modules are handled using the standard Python finder. This finder is stored as the last entry in meta_path, as such that the default Python Finders detect V2 modules first.

classmethod reset() → None

Remove the PluginModuleFinder from sys.meta_path.

inmanta.loader.unload_inmanta_plugins(inmanta_module: str | None = None) → None

Unloads Python modules associated with inmanta modules (inmanta_plugins submodules).

Parameters:

inmanta_module – Unload the Python modules for a specific inmanta module. If omitted, unloads the Python modules for all inmanta modules.

Project

class inmanta.module.Project(path: str, autostd: bool = True, main_file: str = 'main.cf', venv_path: str | VirtualEnv | None = None, attach_cf_cache: bool = True, strict_deps_check: bool | None = None)

Bases: ModuleLike[ProjectMetadata], ModuleLikeWithYmlMetadataFile

An inmanta project

Variables:

• modules – The collection of loaded modules for this project.

• module_source – The v2 module source for this project.

classmethod get(main_file: str = 'main.cf', strict_deps_check: bool | None = None) → Project

Get the instance of the project

install_modules(*, bypass_module_cache: bool = False, update_dependencies: bool = False) → None

Installs all modules, both v1 and v2.

Parameters:

• bypass_module_cache – Fetch the module data from disk even if a cache entry exists.

• update_dependencies – Update all Python dependencies (recursive) to their latest versions.

load(install: bool = False) → None

Load this project’s AST and plugins.

Parameters:

install – Whether to install the project’s modules before attempting to load it.

classmethod set(project: Project, *, clean: bool = True) → None

Set the instance of the project.

Parameters:

clean – Clean up all side effects of any previously loaded projects. Clears the registered plugins and loaded Python plugins packages.

class inmanta.module.ProjectNotFoundException(msg: str)

Bases: CompilerException

This exception is raised when inmanta is unable to find a valid project

Python Environment

inmanta.env.mock_process_env(*, python_path: str | None = None, env_path: str | None = None) → None

Overrides the process environment information. This forcefully sets the environment that is recognized as the outer Python environment. This function should only be called when a Python environment has been set up dynamically and this environment should be treated as if this process was spawned from it, and even then with great care. :param python_path: The path to the python binary. Only one of python_path and env_path should be set. :param env_path: The path to the python environment directory. Only one of python_path and env_path should be set.

When using this method in a fixture to set and reset virtualenv, it is preferable to use store_venv()

class inmanta.env.VirtualEnv(env_path: str)

Creates and uses a virtual environment for this process. This virtualenv inherits from the previously active one.

init_env() → None

Initialize the virtual environment.

use_virtual_env() → None

Activate the virtual environment.

Variables

class inmanta.ast.variables.Reference(name: LocatableString)

This class represents a reference to a value

Variables:

name – The name of the Reference as a string.

name

Typing

The inmanta.ast.type module contains a representation of inmanta types, as well as validation logic for those types.

class inmanta.ast.type.Type

This class is the abstract base class for all types in the Inmanta DSL that represent basic data. These are types that are not relations. Instances of subclasses represent a type in the Inmanta language.

get_base_type() → Type

Returns the base type for this type, i.e. the plain type without modifiers such as expressed by [] and ? in the DSL.

is_primitive() → bool

Returns true iff this type is a primitive type, i.e. number, string, bool.

type_string() → str | None

Returns the type string as expressed in the Inmanta DSL, if this type can be expressed in the DSL. Otherwise returns None.

validate(value: object | None) → bool

Validate the given value to check if it satisfies the constraints associated with this type. Returns true iff validation succeeds, otherwise raises a inmanta.ast.RuntimeException.

with_base_type(base_type: Type) → Type

Returns the type formed by replacing this type’s base type with the supplied type.

class inmanta.ast.type.NullableType(element_type: Type)

Bases: Type

Represents a nullable type in the Inmanta DSL. For example NullableType(Number()) represents number?.

class inmanta.ast.type.Primitive

Bases: Type

Abstract base class representing primitive types.

cast(value: object | None) → object

Cast a value to this type. If the value can not be cast, raises a inmanta.ast.RuntimeException.

class inmanta.ast.type.Number

Bases: Primitive

This class represents an integer or a float in the configuration model.

class inmanta.ast.type.Integer

Bases: Number

An instance of this class represents the int type in the configuration model.

class inmanta.ast.type.Bool

Bases: Primitive

This class represents a simple boolean that can hold true or false.

class inmanta.ast.type.String

Bases: Primitive

This class represents a string type in the configuration model.

class inmanta.ast.type.Union(types: List[Type])

Bases: Type

Instances of this class represent a union of multiple types.

class inmanta.ast.type.Literal

Bases: Union

Instances of this class represent a literal in the configuration model. A literal is a primitive or a list or dict where all values are literals themselves.

class inmanta.ast.type.List

Bases: Type

Instances of this class represent a list type containing any types of values. This class refers to the list type used in plugin annotations. For the list type in the Inmanta DSL, see LiteralList.

class inmanta.ast.type.TypedList(element_type: Type)

Bases: List

Instances of this class represent a list type containing any values of type element_type. For example TypedList(Number()) represents number[].

class inmanta.ast.type.LiteralList

Bases: TypedList

Instances of this class represent a list type containing only Literal values. This is the list type in the DSL

class inmanta.ast.type.Dict

Bases: Type

Instances of this class represent a dict type with any types of values.

class inmanta.ast.type.TypedDict(element_type: Type)

Bases: Dict

Instances of this class represent a dict type containing only values of type element_type.

class inmanta.ast.type.LiteralDict

Bases: TypedDict

Instances of this class represent a dict type containing only Literal values. This is the dict type in the DSL

class inmanta.ast.type.ConstraintType(namespace: Namespace, name: str)

Bases: NamedType

A type that is based on a primitive type but defines additional constraints on this type. These constraints only apply on the value of the type.

inmanta.ast.type.TYPES

Maps Inmanta DSL types to their internal representation. For each key, value pair, value.type_string() is guaranteed to return key.

Note

The type classes themselves do not represent inmanta types, their instances do. For example, the type representation for the inmanta type number is Number(), not Number.

Protocol

class inmanta.protocol.common.Result(code: int = 0, result: dict[str, Any] | None = None)

A result of a method call

code

The result code of the method call.

property result: dict[str, Any] | None

Data

Warning

In contrast to the rest of this section, the data API interface is subject to change. It is documented here because it is currently the only available API to interact with the data framework. A restructure of the data framework is expected at some point. Until then, this API should be considered unstable.

inmanta.data.TBaseDocument : typing.TypeVar

TypeVar with BaseDocument bound.

class inmanta.data.BaseDocument(from_postgres: bool = False, **kwargs: object)

A base document in the database. Subclasses of this document determine collections names. This type is mainly used to bundle query methods and generate validate and query methods for optimized DB access. This is not a full ODM.

Fields are modelled using type annotations similar to protocol and pydantic. The following is supported:

• Attributes are defined at class level with type annotations

• Attributes do not need a default value. When no default is provided, they are marked as required.

• When a value does not have to be set: either a default value or making it optional can be used. When a field is optional without a default value, none will be set as default value so that the field is available.

• Fields that should be ignored, can be added to __ignore_fields__ This attribute is a tuple of strings

• Fields that are part of the primary key should be added to the __primary_key__ attributes. This attribute is a tuple of strings.

async classmethod get_by_id(doc_id: UUID, connection: Connection | None = None) → TBaseDocument | None

Get a specific document based on its ID

Returns:

An instance of this class with its fields filled from the database.

async classmethod get_list(*, order_by_column: str | None = None, order: str | None = None, limit: int | None = None, offset: int | None = None, no_obj: bool | None = None, lock: RowLockMode | None = None, connection: Connection | None = None, **query: object) → list[TBaseDocument]

Get a list of documents matching the filter args

class inmanta.data.Compile(from_postgres: bool = False, **kwargs: object)

Bases: BaseDocument

A run of the compiler

Parameters:

• environment – The environment this resource is defined in

• requested – Time the compile was requested

• started – Time the compile started

• completed – Time to compile was completed

• do_export – should this compile perform an export

• force_update – should this compile definitely update

• metadata – exporter metadata to be passed to the compiler

• requested_environment_variables – environment variables requested to be passed to the compiler

• mergeable_environment_variables – environment variables to be passed to the compiler. These env vars can be compacted over multiple compiles. If multiple values are compacted, they will be joined using spaces.

• used_environment_variables – environment variables passed to the compiler, None before the compile is started

• success – was the compile successful

• handled – were all registered handlers executed?

• version – version exported by this compile

• remote_id – id as given by the requestor, used by the requestor to distinguish between different requests

• compile_data – json data as exported by compiling with the –export-compile-data parameter

• substitute_compile_id – id of this compile’s substitute compile, i.e. the compile request that is similar to this one that actually got compiled.

• partial – True if the compile only contains the entities/resources for the resource sets that should be updated

• removed_resource_sets – indicates the resource sets that should be removed from the model

• exporter_plugin – Specific exporter plugin to use

• notify_failed_compile – if true use the notification service to notify that a compile has failed. By default, notifications are enabled only for exporting compiles.

• failed_compile_message – Optional message to use when a notification for a failed compile is created

• soft_delete – Prevents deletion of resources in removed_resource_sets if they are being exported.

async classmethod get_substitute_by_id(compile_id: UUID, connection: Connection | None = None) → Compile | None

Get a compile’s substitute compile if it exists, otherwise get the compile by id.

Parameters:

compile_id – The id of the compile for which to get the substitute compile.

Returns:

The compile object for compile c2 that is the substitute of compile c1 with the given id. If c1 does not have a substitute, returns c1 itself.

to_dto() → CompileRun

class inmanta.data.ConfigurationModel(**kwargs: object)

Bases: BaseDocument

A specific version of the configuration model.

Parameters:

• version – The version of the configuration model, represented by a unix timestamp.

• environment – The environment this configuration model is defined in

• date – The date this configuration model was created

• partial_base – If this version was calculated from a partial export, the version the partial was applied on.

• released – Is this model released and available for deployment?

• deployed – Is this model deployed?

• result – The result of the deployment. Success or error.

• version_info – Version metadata

• total – The total number of resources

• is_suitable_for_partial_compiles – This boolean indicates whether the model can later on be updated using a partial compile. In other words, the value is True iff no cross resource set dependencies exist between the resources.

async classmethod get_versions(environment: UUID, start: int = 0, limit: int = 100000, connection: Connection | None = None) → list[ConfigurationModel]

Get all versions for an environment ordered descending

class inmanta.data.Environment(from_postgres: bool = False, **kwargs: object)

Bases: BaseDocument

A deployment environment of a project

Parameters:

• id – A unique, machine generated id

• name – The name of the deployment environment.

• project – The project this environment belongs to.

• repo_url – The repository url that contains the configuration model code for this environment.

• repo_branch – The repository branch that contains the configuration model code for this environment.

• settings –

  Key/value settings for this environment. This dictionary does not necessarily contain a key for every environment setting known by the server. This is done for backwards compatibility reasons. When a setting was renamed, we need to determine whether the old or the new setting has to be taken into account. The logic to decide that is the following:

  • When the name of the new setting is present in this settings dictionary or when the name of the old setting is not present in the settings dictionary, use the new setting.

  • Otherwise, use the setting with the old name.

• last_version – The last version number that was reserved for this environment

• description – The description of the environment

• icon – An icon for the environment

class inmanta.data.Report(from_postgres: bool = False, **kwargs: object)

Bases: BaseDocument

A report of a substep of compilation

Parameters:

• started – when the substep started

• completed – when it ended

• command – the command that was executed

• name – The name of this step

• errstream – what was reported on system err

• outstream – what was reported on system out

class inmanta.data.Resource(from_postgres: bool = False, **kwargs: object)

Bases: BaseDocument

A specific version of a resource. This entity contains the desired state of a resource.

Parameters:

• environment – The environment this resource version is defined in

• rid – The id of the resource and its version

• resource – The resource for which this defines the state

• model – The configuration model (versioned) this resource state is associated with

• attributes – The state of this version of the resource

• attribute_hash – hash of the attributes, excluding requires, provides and version, used to determine if a resource describes the same state across versions

• resource_id_value – The attribute value from the resource id

async classmethod get_resources_for_version(environment: UUID, version: int, agent: str | None = None, no_obj: bool = False, *, connection: Connection | None = None) → list[Resource]

class inmanta.data.ResourceAction(from_postgres: bool = False, **kwargs: object)

Bases: BaseDocument

Log related to actions performed on a specific resource version by Inmanta.

Parameters:

• environment – The environment this action belongs to.

• version – The version of the configuration model this action belongs to.

• resource_version_ids – The resource version ids of the resources this action relates to.

• action_id – This id distinguishes the actions from each other. Action ids have to be unique per environment.

• action – The action performed on the resource

• started – When did the action start

• finished – When did the action finish

• messages – The log messages associated with this action

• status – The status of the resource when this action was finished

• changes – A dict with key the resource id and value a dict of fields -> value. Value is a dict that can contain old and current keys and the associated values. An empty dict indicates that the field was changed but not data was provided by the agent.

• change – The change result of an action

async classmethod get_logs_for_version(environment: UUID, version: int, action: str | None = None, limit: int = 0, connection: Connection | None = None) → list[ResourceAction]

class inmanta.data.model.BaseModel

Bases: DateTimeNormalizerModel

Base class for all data objects in Inmanta

inmanta.data.model.ResourceIdStr = inmanta.data.model.ResourceIdStr

The resource id without the version

inmanta.data.model.ResourceVersionIdStr = inmanta.data.model.ResourceVersionIdStr

The resource id with the version included.

class inmanta.db.util.PGRestore(script: list[str], postgresql_client: Connection)

Bases: object

Class that offers support to restore a database dump.

This class assumes that the names of schemas, tables and columns in the dump don’t contain a dot, double quote or whitespace character.

async inmanta.db.util.clear_database(postgresql_client: Connection) → None

Remove all content from the database. Removes functions, tables and data types.

Domain conversion

This section describes methods for converting values between the plugin domain and the internal domain. This conversion is performed automatically for plugin arguments and return values so it is only required when bypassing the usual plugin workflow by calling internal methods directly.

class inmanta.execute.proxy.DynamicProxy

This class wraps an object and makes sure that a model is never modified by native code.

classmethod return_value(value: object) → None | str | tuple[object, ...] | int | float | bool | DynamicProxy

Converts a value from the internal domain to the plugin domain.

classmethod unwrap(item: object) → object

Converts a value from the plugin domain to the internal domain.

Rest API

The rest API is also available as a swagger spec

The (v2) API endpoints that offer paging, sorting and filtering follow a convention. They share the following parameters:

limit

specifies the page size, so the maximum number of items returned from the query

start and first_id

These parameters define the lower limit for the page,

end and last_id

These parameters define the upper limit for the page (only one of the (start, first_id), (end, last_id) pairs should be specified at the same time).

Note

The return value of these methods contain a links tag, with the urls of the next and prev pages, so for simply going through the pages a client only needs to follow these links.

filter

The filter parameter is used for filtering the result set.

Filters should be specified with the syntax ?filter.<filter_key>=value.

It’s also possible to provide multiple values for the same filter, in this case results are returned, if they match any of these filter values: ?filter.<filter_key>=value&filter.<filter_key>=value2

Multiple different filters narrow the results however (they are treated as an ‘AND’ operator). For example ?filter.<filter_key>=value&filter.<filter_key2>=value2 returns results that match both filters.

The documentation of each method describes the supported filters.

sort

The sort parameter describes how the result set should be sorted.

It should follow the pattern ?<attribute_to_sort_by>.<order>, for example ?value.desc (case insensitive).

The documentation of each method describes the supported attributes to sort by.

Module defining the v1 rest api

inmanta.protocol.methods.clear_environment(id: UUID)

Clears an environment by removing most of its associated data. This method deletes various components associated with the specified environment from the database, including agents, compile data, parameters, notifications, code, resources, and configuration models. However, it retains the entry in the Environment table itself and settings are kept. The environment will be temporarily halted during the decommissioning process.

Parameters:

id – The id of the environment to be cleared.

Raises:

• NotFound – The given environment doesn’t exist.

• Forbidden – The given environment is protected.

inmanta.protocol.methods.create_environment(project_id: UUID, name: str, repository: str | None = None, branch: str | None = None, environment_id: UUID | None = None)

Create a new environment

Parameters:

• project_id – The id of the project this environment belongs to

• name – The name of the environment.

• repository – Optional. The URL of the repository.

• branch – Optional. The name of the branch in the repository.

• environment_id – Optional. A unique environment id, if none an id is allocated by the server.

inmanta.protocol.methods.create_project(name: str, project_id: UUID | None = None)

Create a new project

Parameters:

• name – The name of the project

• project_id – Optional. A unique uuid, when it is not provided the server generates one

inmanta.protocol.methods.create_token(tid: UUID, client_types: list, idempotent: bool = True)

Create or get a new token for the given client types.

Parameters:

• tid – The environment id.

• client_types – The client types for which this token is valid (api, agent, compiler).

• idempotent – Optional. The token should be idempotent, meaning it does not have an expire or issued at set, so its value will not change.

inmanta.protocol.methods.delete_environment(id: UUID)

Delete the given environment and all related data.

Parameters:

id – The id of the environment to be deleted.

Raises:

• NotFound – The given environment doesn’t exist.

• Forbidden – The given environment is protected.

inmanta.protocol.methods.delete_param(tid: UUID, id: str, resource_id: str | None = None)

Delete a parameter on the server

Parameters:

• tid – The id of the environment

• id – The name of the parameter

• resource_id – Optional. The resource id of the parameter

inmanta.protocol.methods.delete_project(id: UUID)

Delete the given project and all related data.

Parameters:

id – The id of the project to be deleted.

inmanta.protocol.methods.delete_setting(tid: UUID, id: str)

Restore the given setting to its default value.

Parameters:

• tid – The id of the environment from which the setting is to be deleted.

• id – The key of the setting to delete.

inmanta.protocol.methods.delete_version(tid: UUID, id: int)

Delete a particular version and resources

Parameters:

• tid – The id of the environment

• id – The id of the version to retrieve

inmanta.protocol.methods.deploy(tid: UUID, agent_trigger_method: AgentTriggerMethod = AgentTriggerMethod.push_full_deploy, agents: list | None = None)

Notify agents to perform a deploy now.

Parameters:

• tid – The id of the environment.

• agent_trigger_method – Indicates whether the agents should perform a full or an incremental deploy.

• agents – Optional, names of specific agents to trigger

inmanta.protocol.methods.diff(file_id_1: str, file_id_2: str)

Returns the diff of the files with the two given ids

Parameters:

• file_id_1 – The identifier of the first file.

• file_id_2 – The identifier of the second file.

Returns:

A string representing the diff between the two files.

inmanta.protocol.methods.do_dryrun(tid: UUID, id: UUID, agent: str, version: int)

Do a dryrun on an agent

Parameters:

• tid – The environment id

• id – The id of the dryrun

• agent – The agent to do the dryrun for

• version – The version of the model to dryrun

inmanta.protocol.methods.dryrun_list(tid: UUID, version: int | None = None)

Get the list of dry runs for an environment. The results are sorted by dry run id.

Parameters:

• tid – The id of the environment

• version – Optional. Only for this version

inmanta.protocol.methods.dryrun_report(tid: UUID, id: UUID)

Create a dryrun report

Parameters:

• tid – The id of the environment

• id – The version dryrun to report

inmanta.protocol.methods.dryrun_request(tid: UUID, id: int)

Do a dryrun

Parameters:

• tid – The id of the environment

• id – The version of the CM to deploy

inmanta.protocol.methods.dryrun_update(tid: UUID, id: UUID, resource: str, changes: dict)

Store dryrun results at the server

Parameters:

• tid – The id of the environment

• id – The version dryrun to report

• resource – The id of the resource

• changes – The required changes

inmanta.protocol.methods.get_agent_process(id: UUID)

Return a detailed report for a node

Parameters:

id – The session id of the agent

Returns:

The requested node

inmanta.protocol.methods.get_code(tid: UUID, id: int, resource: str)

Retrieve the source code associated with a specific version of a configuration model for a given resource in an environment.

Parameters:

• tid – The id of the environment to which the code belongs.

• id – The version number of the configuration model.

• resource – The identifier of the resource. This should be a resource ID, not a resource version ID.

inmanta.protocol.methods.get_compile_queue(tid: UUID) → list[CompileRun]

Get the current compiler queue on the server, ordered by increasing requested timestamp.

Parameters:

tid – The id of the environment for which to retrieve the compile queue.

Returns:

A list of CompileRun objects representing the current state of the compiler queue, with each entry detailing a specific compile run.

inmanta.protocol.methods.get_environment(id: UUID, versions: int | None = None, resources: int | None = None)

Get an environment and all versions associated.

Parameters:

• id – The id of the environment to return.

• versions – Optional. If provided and greater than 0, include this many of the most recent versions for this environment, ordered in descending order of their version number. If not provided or 0, no version information is included.

• resources – Optional. If provided and greater than 0, include a summary of the resources in the environment.

inmanta.protocol.methods.get_file(id: str)

Retrieve a file

Parameters:

id – The id of the file to retrieve

inmanta.protocol.methods.get_param(tid: UUID, id: str, resource_id: str | None = None)

Get a parameter from the server.

Parameters:

• tid – The id of the environment

• id – The name of the parameter

• resource_id – Optional. scope the parameter to resource (fact), if the resource id should not contain a version, the latest version is used

Returns:

Returns the following status codes:

• 200: The parameter content is returned

• 404: The parameter is not found and unable to find it because its resource is not known to the server

• 410: The parameter has expired

• 503: The parameter is not found but its value is requested from an agent

inmanta.protocol.methods.get_parameter(tid: UUID, agent: str, resource: dict)

Get all parameters/facts known by the agents for the given resource

This method will not actually return them. This call wil register the request with the agent and return, The agent will push the parameters back to the server when they are available.

Parameters:

• tid – The environment

• agent – The agent to get the parameters from

• resource – The resource to query the parameters from

inmanta.protocol.methods.get_project(id: UUID)

Get a project and a list of the ids of all environments.

Parameters:

id – The id of the project to retrieve.

inmanta.protocol.methods.get_report(id: UUID)

Get a compile report from the server

Parameters:

id – The id of the compile and its reports to fetch.

inmanta.protocol.methods.get_reports(tid: UUID, start: str | None = None, end: str | None = None, limit: int | None = None)

Return compile reports newer then start

Parameters:

• tid – The id of the environment to get a report from

• start – Optional. Reports after start

• end – Optional. Reports before end

• limit – Optional. Maximum number of results, up to a maximum of 1000 If None, a default limit (set to 1000) is applied.

inmanta.protocol.methods.get_resource(tid: UUID, id: str, logs: bool | None = None, status: bool | None = None, log_action: ResourceAction | None = None, log_limit: int = 0)

Return a resource with the given id.

Parameters:

• tid – The id of the environment this resource belongs to

• id – Get the resource with the given resource version id

• logs – Optional. Include the logs in the response

• status – Optional. Only return the status of the resource

• log_action – Optional. The log action to include, leave empty/none for all actions. Valid actions are one of the action strings in const.ResourceAction

• log_limit – Optional. Limit the number of logs included in the response, up to a maximum of 1000. To retrieve more entries, use /api/v2/resource_actions (get_resource_actions()) If None, a default limit (set to 1000) is applied.

inmanta.protocol.methods.get_resources_for_agent(tid: UUID, agent: str, sid: UUID | None = None, version: int | None = None, incremental_deploy: bool = False)

Return the most recent state for the resources associated with agent, or the version requested

Parameters:

• tid – The environment ID this resource belongs to.

• agent – The agent name.

• sid – Optional. Session id of the agent (transparently added by agent client).

• version – Optional. The version to retrieve. If none, the latest available version is returned. With a specific version that version is returned, even if it has not been released yet.

• incremental_deploy – Optional. Indicates whether the server should only return the resources that changed since the previous deployment.

inmanta.protocol.methods.get_server_status() → StatusResponse

Get the status of the server

inmanta.protocol.methods.get_setting(tid: UUID, id: str)

Get the value of a setting.

Parameters:

• tid – The id of the environment.

• id – The id of the setting to retrieve.

inmanta.protocol.methods.get_state(tid: UUID, sid: UUID, agent: str)

Get the state for this agent.

Parameters:

• tid – The id of the environment.

• sid – The session ID associated with this agent.

• agent – The name of the agent.

Returns:

A map with key enabled and value a boolean.

inmanta.protocol.methods.get_status()

A call from the server to the agent to report its status to the server

Returns:

A map with report items

inmanta.protocol.methods.get_version(tid: UUID, id: int, include_logs: bool | None = None, log_filter: str | None = None, limit: int | None = None)

Get a particular version and a list of all resources in this version

Parameters:

• tid – The id of the environment

• id – The id of the version to retrieve

• include_logs – Optional. If true, a log of all operations on all resources is included

• log_filter – Optional. Filter log to only include actions of the specified type

• limit – Optional. The maximal number of actions to return per resource (starting from the latest), up to a maximum of 1000. To retrieve more entries, use /api/v2/resource_actions (get_resource_actions()) If None, a default limit (set to 1000) is applied.

inmanta.protocol.methods.heartbeat(sid: UUID, tid: UUID, endpoint_names: list, nodename: str, no_hang: bool = False)

Send a heartbeat to the server

Parameters:

• sid – The session ID used by this agent at this moment

• tid – The environment this node and its agents belongs to

• endpoint_names – The names of the endpoints on this node

• nodename – The name of the node from which the heart beat comes

• no_hang – Optional. don’t use this call for long polling, but for connectivity check

also registered as API method, because it is called with an invalid SID the first time

inmanta.protocol.methods.heartbeat_reply(sid: UUID, reply_id: UUID, data: dict)

Send a reply back to the server

Parameters:

• sid – The session ID used by this agent at this moment

• reply_id – The id data is a reply to

• data – The data as a response to the reply

async inmanta.protocol.methods.ignore_env(obj: Any, metadata: dict) → Any

This mapper only adds an env all for authz

inmanta.protocol.methods.is_compiling(id: UUID)

Is a compiler running for the given environment

Parameters:

id – The environment id

inmanta.protocol.methods.list_agent_processes(environment: UUID | None = None, expired: bool = True, start: UUID | None = None, end: UUID | None = None, limit: int | None = None)

Return a list of all nodes and the agents for these nodes

Parameters:

• environment – Optional. An optional environment. If set, only the agents that belong to this environment are returned

• expired – Optional. if true show expired processes, otherwise only living processes are shown. True by default

• start – Optional. Agent processes after start (sorted by sid in ASC)

• end – Optional. Agent processes before end (sorted by sid in ASC)

• limit – Optional. Maximum number of results, up to a maximum of 1000 If None, a default limit (set to 1000) is applied.

Raises:

• BadRequest – limit parameter can not exceed 1000

• NotFound – The given environment id does not exist!

Returns:

A list of nodes

inmanta.protocol.methods.list_agents(tid: UUID, start: str | None = None, end: str | None = None, limit: int | None = None)

List all agent for an environment

Parameters:

• tid – The environment the agents are defined in

• start – Optional. Agent after start (sorted by name in ASC)

• end – Optional. Agent before end (sorted by name in ASC)

• limit – Optional. Maximum number of results, up to a maximum of 1000. If None, a default limit (set to 1000) is applied.

Raises:

• BadRequest – limit parameter can not exceed 1000

• NotFound – The given environment id does not exist!

inmanta.protocol.methods.list_environments()

Returns a list of environments. The results are sorted by (project id, environment name, environment id).

inmanta.protocol.methods.list_params(tid: UUID, query: dict = {})

List/query parameters in this environment. The results are ordered alphabetically by parameter name.

Parameters:

• tid – The id of the environment

• query – Optional. A query to match against metadata

inmanta.protocol.methods.list_projects()

Returns a list of projects ordered alphabetically by name. The environments within each project are also sorted by name.

inmanta.protocol.methods.list_settings(tid: UUID)

List the settings in the current environment ordered by name alphabetically.

Parameters:

tid – The id of the environment to list settings for.

inmanta.protocol.methods.list_versions(tid: UUID, start: int | None = None, limit: int | None = None)

Returns a list of all available versions, ordered by version number, descending

Parameters:

• tid – The id of the environment

• start – Optional. parameter to control the amount of results that are returned. 0 is the latest version.

• limit – Optional. parameter to control the amount of results returned, up to a maximum of 1000. If None, a default limit (set to 1000) is applied.

inmanta.protocol.methods.modify_environment(id: UUID, name: str, repository: str | None = None, branch: str | None = None)

Modify the given environment.

Parameters:

• id – The id of the environment to modify.

• name – The new name for the environment.

• repository – Optional. The URL of the repository.

• branch – Optional. The name of the branch in the repository.

If ‘repository’ or ‘branch’ is provided as None, the corresponding attribute of the environment remains unchanged.

inmanta.protocol.methods.modify_project(id: UUID, name: str)

Modify the given project.

Parameters:

• id – The id of the project to modify.

• name – The new name for the project.

inmanta.protocol.methods.notify_change(id: UUID, update: bool = True, metadata: dict = {})

Notify the server that the repository of the environment with the given id, has changed.

Parameters:

• id – The id of the environment

• update – Optional. Update the model code and modules. Default value is true

• metadata – Optional. The metadata that indicates the source of the compilation trigger.

inmanta.protocol.methods.notify_change_get(id: UUID, update: bool = True)

Simplified GET version of the POST method

Parameters:

• id – The id of the environment.

• update – Optional. Indicates whether to update the model code and modules. Defaults to true.

inmanta.protocol.methods.put_version(tid: UUID, version: int, resources: list, resource_state: dict[ResourceIdStr, Literal[ResourceState.available, ResourceState.undefined]] = {}, unknowns: list[dict[str, UUID | bool | int | float | datetime | str]] | None = None, version_info: dict | None = None, compiler_version: str | None = None, resource_sets: dict[ResourceIdStr, str | None] = {}, pip_config: PipConfig | None = None)

Store a new version of the configuration model

The version number must be obtained through the reserve_version call

Parameters:

• tid – The id of the environment

• version – The version of the configuration model

• resources – A list of all resources in the configuration model (deployable)

• resource_state – A dictionary with the initial const.ResourceState per resource id. The ResourceState should be set to undefined when the resource depends on an unknown or available when it doesn’t.

• unknowns – Optional. A list of unknown parameters that caused the model to be incomplete

• version_info – Optional. Module version information

• compiler_version – Optional. version of the compiler, if not provided, this call will return an error

• resource_sets – Optional. a dictionary describing which resource belongs to which resource set

• pip_config – Optional. Pip config used by this version

inmanta.protocol.methods.release_version(tid: UUID, id: int, push: bool = False, agent_trigger_method: AgentTriggerMethod | None = None)

Release version of the configuration model for deployment.

Parameters:

• tid – The id of the environment

• id – The version of the CM to deploy

• push – Notify all agents to deploy the version

• agent_trigger_method – Optional. Indicates whether the agents should perform a full or an incremental deploy when push is true.

Returns:

Returns the following status codes: 200: The version is released 404: The requested version does not exist 409: The requested version was already released

inmanta.protocol.methods.resource_action_update(tid: UUID, resource_ids: list, action_id: UUID, action: ResourceAction, started: datetime | None = None, finished: datetime | None = None, status: ResourceState | DeprecatedResourceState | None = None, messages: list = [], changes: dict = {}, change: Change | None = None, send_events: bool = False)

Send a resource update to the server

Parameters:

• tid – The id of the environment this resource belongs to

• resource_ids – The resource with the given resource_version_id id from the agent

• action_id – A unique id to indicate the resource action that has be updated

• action – The action performed

• started – Optional. The timestamp when this action was started. When this action (action_id) has not been saved yet, started has to be defined.

• finished – Optional. The timestamp when this action was finished. Afterwards, no changes with the same action_id can be stored. The status field also has to be set.

• status – Optional. The current status of the resource (if known)

• messages – Optional. A list of log entries to add to this entry.

• changes – Optional. A dict of changes to this resource. The key of this dict indicates the attributes/fields that have been changed. The value contains the new value and/or the original value.

• change – Optional. The result of the changes

• send_events – Optional. [DEPRECATED] The value of this field is not used anymore.

inmanta.protocol.methods.resource_event(tid: UUID, id: str, resource: str, send_events: bool, state: ResourceState, change: Change, changes={})

Tell an agent a resource it waits for has been updated

Parameters:

• tid – The environment this agent is defined in

• id – The name of the agent

• resource – The resource ID of the resource being updated

• send_events – [DEPRECATED] The value of this field is not used anymore.

• state – State the resource acquired (deployed, skipped, canceled)

• change – The change that was made to the resource

• changes – Optional. The changes made to the resource

inmanta.protocol.methods.set_param(tid: UUID, id: str, source: ParameterSource, value: str, resource_id: str | None = None, metadata: dict = {}, recompile: bool = False, expires: bool | None = None)

Set a parameter on the server. If the parameter is an tracked unknown, it will trigger a recompile on the server. Otherwise, if the value is changed and recompile is true, a recompile is also triggered. [DEPRECATED] Please use the new endpoints /facts/<name> and /parameters/<name> instead.

Parameters:

• tid – The id of the environment

• id – The name of the parameter

• source – The source of the parameter.

• value – The value of the parameter

• resource_id – Optional. Scope the parameter to resource (fact)

• metadata – Optional. Metadata about the parameter

• recompile – Optional. Whether to trigger a recompile

• expires – When setting a new parameter/fact: if set to None, then a sensible default will be provided (i.e. False for parameter and True for fact). When updating a parameter or fact, a None value will leave the existing value unchanged.

inmanta.protocol.methods.set_parameters(tid: UUID, parameters: list)

Set a parameter on the server

Parameters:

• tid – The id of the environment

• parameters –

  A list of dicts with the following keys:

  • id The name of the parameter

  • source The source of the parameter. Valid values are defined in the ParameterSource enum (see: inmanta/const.py)

  • value The value of the parameter

  • resource_id Optionally, scope the parameter to resource (fact)

  • expires Defaults to true. Set to false to create a never expiring fact

  • metadata metadata about the parameter

inmanta.protocol.methods.set_setting(tid: UUID, id: str, value: UUID | bool | int | float | datetime | str | dict[str, Any])

Set a value for a setting.

Parameters:

• tid – The id of the environment.

• id – The id of the setting to set.

• value – The value to set for the setting.

inmanta.protocol.methods.set_state(agent: str, enabled: bool)

Set the state of the agent.

Parameters:

• agent – The name of the agent.

• enabled – A boolean value indicating whether the agent should be paused (enabled=False) or unpaused (enabled=True).

inmanta.protocol.methods.stat_file(id: str)

Does the file exist

Parameters:

id – The id of the file to check

inmanta.protocol.methods.stat_files(files: list)

Check which files exist in the given list

Parameters:

files – A list of file ids to check

Returns:

A list of files that do not exist.

inmanta.protocol.methods.trigger(tid: UUID, id: str, incremental_deploy: bool)

Request an agent to reload resources

Parameters:

• tid – The environment this agent is defined in

• id – The name of the agent

• incremental_deploy – Indicates whether the agent should perform an incremental deploy or a full deploy

inmanta.protocol.methods.trigger_agent(tid: UUID, id: str)

Request the server to reload an agent

Parameters:

• tid – The environment this agent is defined in

• id – The name of the agent

Returns:

The requested node

inmanta.protocol.methods.upload_code_batched(tid: UUID, id: int, resources: dict)

Upload batches of code for various resources associated with a specific version of a configuration model in an environment.

Parameters:

• tid – The id of the environment to which the code belongs.

• id – The version number of the configuration model.

• resources – A dictionary where each key is a string representing a resource type. For each resource type, the value is a dictionary. This nested dictionary’s keys are file hashes, and each key maps to a tuple. This tuple contains three elements: the file name, the module name, and a list of requirements.

The endpoint validates that all provided file references are valid and checks for conflicts with existing code entries.

inmanta.protocol.methods.upload_file(id: str, content: str)

Upload a new file

Parameters:

• id – The id of the file

• content – The base64 encoded content of the file

Module defining the v2 rest api

inmanta.protocol.methods_v2.add_user(username: str, password: str) → User

Add a new user to the system

Parameters:

• username – The username of the new user. The username cannot be an empty string.

• password – The password of this new user. The password should be at least 8 characters long.

Raises:

• Conflict – Raised when there is already a user with this user_name

• BadRequest – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.agent_action(tid: UUID, name: str, action: AgentAction) → None

Execute an action on an agent

Parameters:

• tid – The environment this agent is defined in.

• name – The name of the agent.

• action – The type of action that should be executed on an agent. Pause and unpause can only be used when the environment is not halted, while the on_resume actions can only be used when the environment is halted. * pause: A paused agent cannot execute any deploy operations. * unpause: A unpaused agent will be able to execute deploy operations. * keep_paused_on_resume: The agent will still be paused when the environment is resumed * unpause_on_resume: The agent will be unpaused when the environment is resumed

Raises:

Forbidden – The given environment has been halted and the action is pause/unpause, or the environment is not halted and the action is related to the on_resume behavior

inmanta.protocol.methods_v2.all_agents_action(tid: UUID, action: AgentAction) → None

Execute an action on all agents in the given environment.

Parameters:

• tid – The environment of the agents.

• action – The type of action that should be executed on the agents. Pause and unpause can only be used when the environment is not halted, while the on_resume actions can only be used when the environment is halted. * pause: A paused agent cannot execute any deploy operations. * unpause: A unpaused agent will be able to execute deploy operations. * keep_paused_on_resume: The agents will still be paused when the environment is resumed * unpause_on_resume: The agents will be unpaused when the environment is resumed

Raises:

Forbidden – The given environment has been halted and the action is pause/unpause, or the environment is not halted and the action is related to the on_resume behavior

inmanta.protocol.methods_v2.compile_details(tid: UUID, id: UUID) → CompileDetails

Parameters:

• tid – The id of the environment in which the compilation process occurred.

• id – The id of the compile for which the details are being requested.

Returns:

The details of a compile

Raises:

NotFound – This exception is raised when the referenced environment or compile is not found

inmanta.protocol.methods_v2.delete_user(username: str) → None

Delete a user from the system with given username.

Parameters:

username – The username to delete

Raises:

• NotFound – Raised when the user does not exist

• BadRequest – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.discovered_resource_create(tid: UUID, discovered_resource_id: str, discovery_resource_id: str, **kwargs: object) → None

create a discovered resource.

Parameters:

• tid – The id of the environment this resource belongs to

• discovered_resource_id – The id of the discovered_resource

• discovery_resource_id – The id of the discovery resource responsible for discovering this resource

• **kwargs –

  The following arguments are supported: values: The values associated with the discovered_resource

inmanta.protocol.methods_v2.discovered_resource_create_batch(tid: UUID, discovered_resources: list[LinkedDiscoveredResource]) → None

create multiple discovered resource in the DB :param tid: The id of the environment this resource belongs to :param discovered_resources: List of discovered_resources containing the discovered_resource_id and values for each resource

inmanta.protocol.methods_v2.discovered_resources_get(tid: UUID, discovered_resource_id: ResourceIdStr) → DiscoveredResource

Get a single discovered resource.

Parameters:

• tid – the id of the environment in which to get the discovered resource.

• discovered_resource_id – The id of the discovered resource

inmanta.protocol.methods_v2.discovered_resources_get_batch(tid: UUID, limit: int | None = None, start: str | None = None, end: str | None = None, sort: str = 'discovered_resource_id.asc', filter: dict[str, list[str]] | None = None) → list[DiscoveredResource]

Get a list of discovered resources.

The discovery resource responsible for discovering each resource is included. For resources that the orchestrator is already managing, a link to the corresponding resource is provided. The full list of supported links can be found here.

Parameters:

• tid – The id of the environment this resource belongs to

• limit – Limit the number of instances that are returned

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• sort – Return the results sorted according to the parameter value. The following sorting attributes are supported: ‘discovered_resource_id’. The following orders are supported: ‘asc’, ‘desc’

• filter –

  Filter the list of returned resources. Default behavior: return all discovered resources. Filtering by ‘managed’ is supported:

  • filter.managed=true: only return discovered resources that the orchestrator is already aware of i.e. resources that are present in any released configuration model of environment tid.

  • filter.managed=false: only return discovered resources that the orchestrator is unaware of i.e. resources that are not part of any released configuration model of environment tid.

Returns:

A list of all matching released resources

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.dryrun_trigger(tid: UUID, version: int) → UUID

Trigger a new dryrun

Parameters:

• tid – The id of the environment

• version – The version of the configuration model to execute the dryrun for

Raises:

NotFound – This exception is raised when the referenced environment or version is not found

Returns:

The id of the new dryrun

inmanta.protocol.methods_v2.environment_clear(id: UUID) → None

Clear all data from this environment. The environment will be temporarily halted during the decommissioning process.

Parameters:

id – The uuid of the environment.

Raises:

• NotFound – The given environment doesn’t exist.

• Forbidden – The given environment is protected.

inmanta.protocol.methods_v2.environment_create(project_id: UUID, name: str, repository: str | None = None, branch: str | None = None, environment_id: UUID | None = None, description: str = '', icon: str = '') → Environment

Create a new environment

Parameters:

• project_id – The id of the project this environment belongs to

• name – The name of the environment. The name should be unique for each project.

• repository – The url (in git form) of the repository

• branch – The name of the branch in the repository

• environment_id – A unique environment id, if none an id is allocated by the server

• description – The description of the environment, maximum 255 characters

• icon – The data-url of the icon of the environment. It should follow the pattern <mime-type>;base64,<image>, where <mime-type> is one of: ‘image/png’, ‘image/jpeg’, ‘image/webp’, ‘image/svg+xml’, and <image> is the image in the format matching the specified mime-type, and base64 encoded. The length of the whole string should be maximum 64 kb.

Raises:

BadRequest – When the parameters supplied are not valid.

inmanta.protocol.methods_v2.environment_create_token(tid: UUID, client_types: list[str], idempotent: bool = True) → str

Create or get a new token for the given client types. Tokens generated with this call are scoped to the current environment.

Parameters:

• tid – The environment id

• client_types – The client types for which this token is valid (api, agent, compiler)

• idempotent – The token should be idempotent, such tokens do not have an expire or issued at set so their value will not change.

inmanta.protocol.methods_v2.environment_delete(id: UUID) → None

Delete the given environment and all related data.

Parameters:

id – The uuid of the environment.

Raises:

• NotFound – The given environment doesn’t exist.

• Forbidden – The given environment is protected.

inmanta.protocol.methods_v2.environment_get(id: UUID, details: bool = False) → Environment

Get an environment and all versions associated

Parameters:

• id – The id of the environment to return

• details – Whether to include the icon and description of the environment

inmanta.protocol.methods_v2.environment_list(details: bool = False) → list[Environment]

Returns a list of environments

Parameters:

details – Whether to include the icon and description of the environments in the results

inmanta.protocol.methods_v2.environment_modify(id: UUID, name: str, repository: str | None = None, branch: str | None = None, project_id: UUID | None = None, description: str | None = None, icon: str | None = None) → Environment

Modify the given environment The optional parameters that are unspecified will be left unchanged by the update.

Parameters:

• id – The id of the environment

• name – The name of the environment

• repository – The url (in git form) of the repository

• branch – The name of the branch in the repository

• project_id – The id of the project the environment belongs to

• description – The description of the environment, maximum 255 characters

• icon – The data-url of the icon of the environment. It should follow the pattern <mime-type>;base64,<image> , where <mime-type> is one of: ‘image/png’, ‘image/jpeg’, ‘image/webp’, ‘image/svg+xml’, and <image> is the image in the format matching the specified mime-type, and base64 encoded. The length of the whole string should be maximum 64 kb. The icon can be removed by setting this parameter to an empty string.

Raises:

• BadRequest – When the parameters supplied are not valid.

• NotFound – The given environment doesn’t exist.

inmanta.protocol.methods_v2.environment_setting_delete(tid: UUID, id: str) → ReturnValue[None]

Reset the given setting to its default value.

Parameters:

• tid – The id of the environment from which the setting is to be deleted.

• id – The identifier of the setting to be deleted.

inmanta.protocol.methods_v2.environment_setting_get(tid: UUID, id: str) → EnvironmentSettingsReponse

Retrieve a specific setting from an environment’s configuration.

Parameters:

• tid – The id of the environment from which the setting is being retrieved.

• id – The id of the setting to be retrieved.

inmanta.protocol.methods_v2.environment_settings_list(tid: UUID) → EnvironmentSettingsReponse

List the settings in the current environment ordered by name alphabetically.

Parameters:

tid – The id of the environment for which the list of settings is being requested.

inmanta.protocol.methods_v2.environment_settings_set(tid: UUID, id: str, value: bool | int | float | str | dict[str, str | int | bool]) → ReturnValue[None]

Set a specific setting in an environment’s configuration.

Parameters:

• tid – The id of the environment where the setting is to be set or updated.

• id – The id of the setting to be set or updated.

• value – The new value for the setting.

inmanta.protocol.methods_v2.get_agent_process_details(tid: UUID, id: UUID, report: bool = False) → AgentProcess

Get the details of an agent process

Parameters:

• tid – Id of the environment

• id – The id of the specific agent process

• report – Whether to include a report from the agent or not

Returns:

The details of an agent process

Raises:

NotFound – This exception is raised when the referenced environment or agent process is not found

inmanta.protocol.methods_v2.get_agents(tid: UUID, limit: int | None = None, start: datetime | bool | str | None = None, end: datetime | bool | str | None = None, first_id: str | None = None, last_id: str | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'name.asc') → list[Agent]

Get all of the agents in the given environment

Parameters:

• tid – The id of the environment the agents should belong to.

• limit – Limit the number of agents that are returned.

• start – The lower limit for the order by column (exclusive).

• first_id – The name to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values.

• last_id – The name to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values. Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned agents. Filtering by ‘name’, ‘process_name’ and ‘status’ is supported.

• sort – Return the results sorted according to the parameter value. Sorting by ‘name’, ‘process_name’, ‘status’, ‘paused’ and ‘last_failover’ is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching agents

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.get_all_facts(tid: UUID, limit: int | None = None, first_id: UUID | None = None, last_id: UUID | None = None, start: str | None = None, end: str | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'name.asc') → list[Fact]

List the facts in an environment.

Parameters:

• tid – The id of the environment

• limit – Limit the number of facts that are returned

• first_id – The fact id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The fact id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned facts. The following options are available: name: filter by the name of the fact resource_id: filter by the resource_id of the fact expires: filter on whether the fact expires or not

• sort – Return the results sorted according to the parameter value. The following sorting attributes are supported: ‘name’, ‘resource_id’. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching facts

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.get_api_docs(format: ApiDocsFormat | None = ApiDocsFormat.swagger) → ReturnValue[OpenAPI | str]

Get the OpenAPI definition of the API

Parameters:

format – Use ‘openapi’ to get the schema in json format, leave empty or use ‘swagger’ to get the Swagger-UI view

inmanta.protocol.methods_v2.get_compile_data(id: UUID) → CompileData | None

Get the compile data for the given compile request.

Parameters:

id – The id of the compile.

inmanta.protocol.methods_v2.get_compile_reports(tid: UUID, limit: int | None = None, first_id: UUID | None = None, last_id: UUID | None = None, start: datetime | None = None, end: datetime | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'requested.desc') → list[CompileReport]

Get the compile reports from an environment.

Parameters:

• tid – The id of the environment

• limit – Limit the number of instances that are returned

• first_id – The id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter –

  Filter the list of returned compile reports. Filters should be specified with the syntax ?filter.<filter_key>=value, for example ?filter.success=True It’s also possible to provide multiple values for the same filter, in this case resources are returned, if they match any of these filter values. For example: ?filter.requested=ge:2021-08-18T09:21:30.568353&filter.requested=lt:2021-08-18T10:21:30.568353 returns compile reports that were requested between the specified dates. Multiple different filters narrow the results however (they are treated as an ‘AND’ operator). For example ?filter.success=True&filter.completed=True returns compile reports that are completed and successful. The following options are available: success: whether the compile was successful or not started: whether the compile has been started or not completed: whether the compile has been completed or not

  requested: return the logs matching the timestamp constraints. Valid constraints are of the form

  ”<lt|le|gt|ge>:<x>”. The expected format is YYYY-MM-DDTHH:mm:ss.ssssss, so an ISO-8601 datetime string, in UTC timezone. Specifying microseconds is optional. For example: ?filter.requested=ge:2021-08-18T09:21:30.568353&filter.requested=lt:2021-08-18T10:21:30. Multiple constraints can be specified, in which case only compile reports that match all constraints will be returned.

• sort – Return the results sorted according to the parameter value. It should follow the pattern ?sort=<attribute_to_sort_by>.<order>, for example ?sort=requested.desc (case insensitive). Only sorting by the requested timestamp is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching compile reports

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.get_current_user() → CurrentUser

Get the current logged in user (based on the provided JWT) and server auth settings

Raises:

NotFound – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.get_diff_of_versions(tid: UUID, from_version: int, to_version: int) → list[ResourceDiff]

Compare two versions of desired states, and provide the difference between them, with regard to their resources and the attributes of these resources. Resources that are the same in both versions are not mentioned in the results.

A resource diff describes whether the resource was ‘added’, ‘modified’ or ‘deleted’, and what the values of their attributes were in the versions. The values are also returned in a stringified, easy to compare way, which can be used to calculate a git diff-like summary of the changes.

Parameters:

• tid – The id of the environment

• from_version – The (lower) version number to compare

• to_version – The other (higher) version number to compare

Returns:

The resource diffs between from_version and to_version

Raises:

• NotFound – This exception is raised when the referenced environment or versions are not found

• BadRequest – When the version parameters are not valid

inmanta.protocol.methods_v2.get_dryrun_diff(tid: UUID, version: int, report_id: UUID) → DryRunReport

Get the report of a dryrun, describing the changes a deployment would make, with the difference between the current and target states provided in a form similar to the desired state diff endpoint.

Parameters:

• tid – The id of the environment

• version – The version of the configuration model the dryrun belongs to

• report_id – The dryrun id to calculate the diff for

Raises:

NotFound – This exception is raised when the referenced environment or version is not found

Returns:

The dryrun report, with a summary and the list of differences.

inmanta.protocol.methods_v2.get_environment_metrics(tid: UUID, metrics: list[str], start_interval: datetime, end_interval: datetime, nb_datapoints: int, round_timestamps: bool = False) → EnvironmentMetricsResult

Obtain metrics about the given environment for the given time interval.

Parameters:

• tid – The id of the environment for which the metrics have to be collected.

• metrics – List of names of metrics that have to be returned.

• start_interval – The start of the time window for which the metrics should be returned.

• end_interval – The end of the time window for which the metrics should be returned.

• nb_datapoints – The amount of datapoint that will be returned within the given time interval for each metric.

• round_timestamps –

  If this parameter is set to True, the timestamps in the reply will be rounded to a full hour. All time windows in the reply will have an equal size. To achieve this the start_interval, end_interval and nb_datapoint in the reply may differ from the ones requested.

  • The start_interval may be smaller than requested

  • The end_interval may be larger than requested

  • The nb_datapoints may be larger than requested

Raises:

• BadRequest – start_interval >= end_interval

• BadRequest – nb_datapoints < 0

• BadRequest – The provided metrics list is an empty list.

• BadRequest – The start_interval and end_interval are not separated from each other by at least nb_datapoints minutes separated from each other.

• BadRequest – The round_timestamps parameter is set to True and the amount of hours between start_interval and end_interval is less than the requested number of datapoints.

inmanta.protocol.methods_v2.get_fact(tid: UUID, rid: ResourceIdStr, id: UUID) → Fact

Get one specific fact :param tid: The id of the environment :param rid: The id of the resource :param id: The id of the fact :return: A specific fact corresponding to the id :raise NotFound: This status code is returned when the referenced environment or fact is not found

inmanta.protocol.methods_v2.get_facts(tid: UUID, rid: ResourceIdStr) → list[Fact]

Get the facts related to a specific resource. The results are sorted alphabetically by name. :param tid: The id of the environment :param rid: Id of the resource :return: The facts related to this resource :raise NotFound: This status code is returned when the referenced environment is not found

inmanta.protocol.methods_v2.get_notification(tid: UUID, notification_id: UUID) → Notification

Get a single notification

Parameters:

• tid – The id of the environment

• notification_id – The id of the notification

Returns:

The notification with the specified id

Raises:

NotFound – When the referenced environment or notification is not found

inmanta.protocol.methods_v2.get_parameters(tid: UUID, limit: int | None = None, first_id: UUID | None = None, last_id: UUID | None = None, start: datetime | str | None = None, end: datetime | str | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'name.asc') → list[Parameter]

List the parameters in an environment

Parameters:

• tid – The id of the environment

• limit – Limit the number of parameters that are returned

• first_id – The parameter id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The parameter id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter –

  Filter the list of returned parameters.

  The following options are available:

  • name: filter by the name of the parameter

  • source: filter by the source of the parameter

  • updated: filter by the updated time of the parameter

• sort – Return the results sorted according to the parameter value. The following sorting attributes are supported: ‘name’, ‘source’, ‘updated’. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching parameters

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.get_pip_config(tid: UUID, version: int) → PipConfig | None

Get the pip config for the given version

Parameters:

• tid – The id of the environment

• version – The id of the model version

Raises:

NotFound – Raised when the version or environment is not found

inmanta.protocol.methods_v2.get_resource_actions(tid: UUID, resource_type: str | None = None, agent: str | None = None, attribute: str | None = None, attribute_value: str | None = None, log_severity: str | None = None, limit: int | None = 0, action_id: UUID | None = None, first_timestamp: datetime | None = None, last_timestamp: datetime | None = None, exclude_changes: list[Change] | None = None) → ReturnValue[list[ResourceAction]]

Return resource actions matching the search criteria.

Parameters:

• tid – The id of the environment this resource belongs to

• resource_type – The resource entity type that should be queried

• agent – Agent name that is used to filter the results

• attribute – Attribute name used for filtering

• attribute_value – Attribute value used for filtering. Attribute and attribute value should be supplied together.

• log_severity – Only include ResourceActions which have a log message with this severity.

• limit – Limit the number of resource actions included in the response, up to 1000

• action_id – Start the query from this action_id. To be used in combination with either the first or last timestamp.

• first_timestamp – Limit the results to resource actions that started later than the value of this parameter (exclusive)

• last_timestamp – Limit the results to resource actions that started earlier than the value of this parameter (exclusive). Only the first_timestamp or last_timestamp parameter should be supplied

• exclude_changes – only return ResourceActions where the change type is different from the one in this list.

Returns:

The list of matching Resource Actions. The order is ascending if first_timestamp is provided, otherwise descending. If a limit is specified, also return links to the next and previous pages. The “next” page refers to actions that started earlier, while the “prev” page refers to actions that started later.

Raises:

BadRequest – When the supplied parameters are not valid.

inmanta.protocol.methods_v2.get_resource_events(tid: UUID, rvid: ResourceVersionIdStr, exclude_change: Change | None = None) → dict[ResourceIdStr, list[ResourceAction]]

Return relevant events for a resource, i.e. all deploy actions for each of its dependencies since this resources’ last successful deploy or all deploy actions if this resources hasn’t been deployed before. The resource actions are sorted in descending order according to their started timestamp. If exclude_change is set, exclude all resource actions with this specific type of change.

This method searches through all versions of this resource. This method should only be called when a deploy is in progress.

Parameters:

• tid – The id of the environment this resource belongs to

• rvid – The id of the resource to get events for.

• exclude_change – Exclude all resource actions with this specific type of change.

Raises:

BadRequest – When this endpoint in called while the resource with the given resource version is not in the deploying state.

inmanta.protocol.methods_v2.get_resources_in_version(tid: UUID, version: int, limit: int | None = None, first_id: ResourceVersionIdStr | None = None, last_id: ResourceVersionIdStr | None = None, start: str | None = None, end: str | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'resource_type.desc') → list[VersionedResource]

Get the resources that belong to a specific version.

Parameters:

• tid – The id of the environment

• version – The version number

• limit – Limit the number of resources that are returned

• first_id – The resource_version_id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The resource_version_id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned resources. The following options are available: agent: filter by the agent name of the resource resource_type: filter by the type of the resource resource_id_value: filter by the attribute values of the resource

• sort – Return the results sorted according to the parameter value. The following sorting attributes are supported: ‘resource_type’, ‘agent’, ‘resource_id_value’. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching resources

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.get_source_code(tid: UUID, version: int, resource_type: str) → list[Source]

Get the code for the given version and the given resource :param tid: The id of the environment :param version: The id of the model version :param resource_type: The type name of the resource :raises NotFound: Raised when the version or type is not found

inmanta.protocol.methods_v2.halt_environment(tid: UUID) → None

Halt all orchestrator operations for an environment. The environment will enter a state where all agents are paused and can not be unpaused. Incoming compile requests will still be queued but compilation will halt. Normal operation can be restored using the resume_environment endpoint.

Parameters:

tid – The environment id

Raises:

NotFound – The given environment doesn’t exist.

inmanta.protocol.methods_v2.list_desired_state_versions(tid: UUID, limit: int | None = None, start: int | None = None, end: int | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'version.desc') → list[DesiredStateVersion]

Get the desired state versions from an environment.

Parameters:

• tid – The id of the environment

• limit – Limit the number of versions that are returned

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned desired state versions. Filtering by ‘version’ range, ‘date’ range and ‘status’ is supported.

• sort – Return the results sorted according to the parameter value. Only sorting by ‘version’ is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching compile reports

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.list_dryruns(tid: UUID, version: int) → list[DryRun]

Query a list of dry runs for a specific version

Parameters:

• tid – The id of the environment

• version – The configuration model version to return dryruns for

Raises:

NotFound – This exception is raised when the referenced environment or version is not found

Returns:

The list of dryruns for the specified version in descending order by date

inmanta.protocol.methods_v2.list_notifications(tid: UUID, limit: int | None = None, first_id: UUID | None = None, last_id: UUID | None = None, start: datetime | None = None, end: datetime | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'created.desc') → list[Notification]

List the notifications in an environment.

The returned notification objects may carry links to other objects, e.g. a compile report. The full list of supported links can be found here.

Parameters:

• tid – The id of the environment

• limit – Limit the number of notifications that are returned

• first_id – The notification id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The notification id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned notifications. The following options are available: read: Whether the notification was read or not cleared: Whether the notification was cleared or not severity: Filter by the severity field of the notifications title: Filter by the title of the notifications message: Filter by the message of the notifications

• sort – Return the results sorted according to the parameter value. Only sorting by the ‘created’ date is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching notifications

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering or paging are not valid

inmanta.protocol.methods_v2.list_users() → list[User]

List all users

Returns:

A list of all users

inmanta.protocol.methods_v2.login(username: str, password: str) → ReturnValue[LoginReturn]

Login a user.

When the login succeeds an authentication header is returned with the Bearer token set.

Parameters:

• username – The user to login

• password – The password of this user

Raises:

UnauthorizedException – Raised when the login failed or if server authentication is not enabled

inmanta.protocol.methods_v2.project_create(name: str, project_id: UUID | None = None) → Project

Create a new project

Parameters:

• name – The name of the project

• project_id – A unique uuid, when it is not provided the server generates one

inmanta.protocol.methods_v2.project_delete(id: UUID) → None

Delete the given project and all related data

Parameters:

id – The id of the project to be deleted.

inmanta.protocol.methods_v2.project_get(id: UUID, environment_details: bool = False) → Project

Get a project and a list of the environments under this project

Parameters:

• id – The id for which the project’s details are being requested.

• environment_details – Whether to include the icon and description of the environments in the results

inmanta.protocol.methods_v2.project_list(environment_details: bool = False) → list[Project]

Returns a list of projects ordered alphabetically by name. The environments within each project are also sorted by name.

Parameters:

environment_details – Whether to include the icon and description of the environments in the results

inmanta.protocol.methods_v2.project_modify(id: UUID, name: str) → Project

Rename the given project

Parameters:

• id – The id of the project to be modified.

• name – The new name for the project. This string value will replace the current name of the project.

inmanta.protocol.methods_v2.promote_desired_state_version(tid: UUID, version: int, trigger_method: PromoteTriggerMethod | None = None) → None

Promote a desired state version, making it the active version in the environment.

Parameters:

• tid – The id of the environment

• version – The number of the version to promote

• trigger_method – If set to ‘push_incremental_deploy’ or ‘push_full_deploy’, the agents will perform an incremental or full deploy, respectively. If set to ‘no_push’, the new version is not pushed to the agents. If the parameter is not set (or set to null), the new version is pushed and the environment setting ‘environment_agent_trigger_method’ decides if the deploy should be full or incremental

inmanta.protocol.methods_v2.put_partial(tid: UUID, resource_state: dict[ResourceIdStr, Literal[ResourceState.available, ResourceState.undefined]] | None = None, unknowns: list[dict[str, UUID | bool | int | float | datetime | str]] | None = None, resource_sets: dict[ResourceIdStr, str | None] | None = None, removed_resource_sets: list[str] | None = None, pip_config: PipConfig | None = None, **kwargs: object) → ReturnValue[int]

Store a new version of the configuration model after a partial recompile. The partial is applied on top of the latest version. Dynamically acquires a new version and serializes concurrent calls. Python code for the new version is copied from the base version.

Concurrent put_partial calls are safe from race conditions provided that their resource sets are disjunct. A put_version call concurrent with a put_partial is not guaranteed to be safe. It is the caller’s responsibility to appropriately serialize them with respect to one another. The caller must ensure the reserve_version + put_version operation is atomic with respect to put_partial. In other words, put_partial must not be called in the window between reserve_version and put_version. If not respected, either the full or the partial export might be immediately stale, and future exports will only be applied on top of the non-stale one.

Parameters:

• tid – The id of the environment

• resource_state – A dictionary with the initial const.ResourceState per resource id. The ResourceState should be set to undefined when the resource depends on an unknown or available when it doesn’t.

• unknowns – A list of unknown parameters that caused the model to be incomplete

• resource_sets – a dictionary describing which resources belong to which resource set

• removed_resource_sets – a list of resource_sets that should be deleted from the model

• **kwargs –

  The following arguments are supported: * resources: a list of resource objects. Since the version is not known yet resource versions should be set to 0. * version_info: Model version information

• pip_config – Pip config used by this version

Returns:

The newly stored version number.

inmanta.protocol.methods_v2.reserve_version(tid: UUID) → int

Reserve a version number in this environment.

Parameters:

tid – The id of the environment in which the version number is to be reserved.

inmanta.protocol.methods_v2.resource_deploy_done(tid: UUID, rvid: ResourceVersionIdStr, action_id: UUID, status: ResourceState, messages: list[LogLine] = [], changes: dict[str, AttributeStateChange] = {}, change: Change | None = None) → None

Report to the server that an agent has finished the deployment of a certain resource.

Parameters:

• tid – The id of the environment the resource belongs to

• rvid – The resource version id of the resource for which the deployment is finished.

• action_id – A unique ID associated with this resource deployment action. This should be the same ID that was passed to the /resource/<resource_id>/deploy/start API call.

• status – The current status of the resource (if known)

• messages – A list of log entries produced by the deployment action.

• changes – A dict of changes to this resource. The key of this dict indicates the attributes/fields that have been changed. The value contains the new value and/or the original value.

• change – The type of change that was done the given resource.

inmanta.protocol.methods_v2.resource_deploy_start(tid: UUID, rvid: ResourceVersionIdStr, action_id: UUID) → dict[ResourceVersionIdStr, ResourceState]

Report to the server that the agent will start the deployment of the given resource.

Parameters:

• tid – The id of the environment the resource belongs to

• rvid – The resource version id of the resource for which the deployment will start

• action_id – A unique id used to track the action of this deployment

Returns:

A dict mapping the resource version id of each dependency of resource_id to the last deployment status of that resource.

inmanta.protocol.methods_v2.resource_details(tid: UUID, rid: ResourceIdStr) → ReleasedResourceDetails

Parameters:

• tid – The id of the environment from which the resource’s details are being requested.

• rid – The unique identifier (ResourceIdStr) of the resource. This value specifies the particular resource for which detailed information is being requested.

Returns:

The details of the latest released version of a resource

Raises:

NotFound – This exception is raised when the referenced environment or resource is not found

inmanta.protocol.methods_v2.resource_did_dependency_change(tid: UUID, rvid: ResourceVersionIdStr) → bool

Returns True iff this resources’ events indicate a change in its dependencies since the resource’s last deployment.

This method searches through all versions of this resource. This method should only be called when a deploy is in progress.

Parameters:

• tid – The id of the environment this resource belongs to

• rvid – The id of the resource.

Raises:

BadRequest – When this endpoint in called while the resource with the given resource version is not in the deploying state.

inmanta.protocol.methods_v2.resource_history(tid: UUID, rid: ResourceIdStr, limit: int | None = None, first_id: str | None = None, last_id: str | None = None, start: datetime | None = None, end: datetime | None = None, sort: str = 'date.desc') → list[ResourceHistory]

Parameters:

• tid – The id of the environment this resource belongs to

• rid – The id of the resource

• limit – Limit the number of instances that are returned

• first_id – The attribute_hash to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The attribute_hash to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• sort – Return the results sorted according to the parameter value. It should follow the pattern <attribute_to_sort_by>.<order>, for example date.desc (case insensitive). Sorting by date is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

The history of a resource, according to its attributes

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for sorting or paging are not valid

inmanta.protocol.methods_v2.resource_list(tid: UUID, limit: int | None = None, first_id: ResourceVersionIdStr | None = None, last_id: ResourceVersionIdStr | None = None, start: str | None = None, end: str | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'resource_type.desc', deploy_summary: bool = False) → list[LatestReleasedResource]

Parameters:

• tid – The id of the environment this resource belongs to

• limit – Limit the number of instances that are returned

• first_id – The resource_version_id to use as a continuation token for paging, in combination with the ‘start’ value, because the order by column might contain non-unique values

• last_id – The resource_version_id to use as a continuation token for paging, in combination with the ‘end’ value, because the order by column might contain non-unique values

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter – Filter the list of returned resources. Filters should be specified with the syntax ?filter.<filter_key>=value, for example ?filter.status=deployed It’s also possible to provide multiple values for the same filter, in this case resources are returned, if they match any of these filter values. For example: ?filter.status=deployed&filter.status=available returns instances with either of the statuses deployed or available. Multiple different filters narrow the results however (they are treated as an ‘AND’ operator). For example filter.status=deployed&filter.agent=internal returns resources with ‘deployed’ status, where the ‘agent’ is set to ‘internal_agent’. The following options are available: agent: filter by the agent of the resource resource_type: filter by the type of the resource resource_id_value: filter by the attribute values of the resource status: filter by the current status of the resource. For status filters it’s also possible to invert the condition with ‘!’, for example filter.status=!orphaned will return all the resources that are not in ‘orphaned’ state The values for the ‘agent’, ‘resource_type’ and ‘value’ filters are matched partially.

• sort – Return the results sorted according to the parameter value. It should follow the pattern <attribute_to_sort_by>.<order>, for example resource_type.desc (case insensitive). The following sorting attributes are supported: ‘resource_type’, ‘agent’, ‘resource_id_value’, ‘status’. The following orders are supported: ‘asc’, ‘desc’

• deploy_summary – If set to true, returns a summary of the deployment status of the resources in the environment in the metadata, describing how many resources are in each state as well as the total number of resources. The summary does not take into account the current filters or paging parameters. Orphaned resources are not included in the summary

Returns:

A list of all matching released resources

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.resource_logs(tid: UUID, rid: ResourceIdStr, limit: int | None = None, start: datetime | None = None, end: datetime | None = None, filter: dict[str, list[str]] | None = None, sort: str = 'timestamp.desc') → list[ResourceLog]

Get the logs of a specific resource.

Parameters:

• tid – The id of the environment this resource belongs to

• rid – The id of the resource

• limit – Limit the number of instances that are returned

• start – The lower limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• end – The upper limit for the order by column (exclusive). Only one of ‘start’ and ‘end’ should be specified at the same time.

• filter –

  Filter the list of returned logs. Filters should be specified with the syntax ?filter.<filter_key>=value, for example ?filter.minimal_log_level=INFO. It’s also possible to provide multiple values for the same filter, in this case resources are returned, if they match any of these filter values.

  For example: ?filter.action=pull&filter.action=deploy returns logs with either of the actions pull or deploy. Multiple different filters narrow the results however (they are treated as an ‘AND’ operator). For example filter.minimal_log_level=INFO&filter.action=deploy returns logs with ‘deploy’ action, where the ‘log_level’ is at least ‘INFO’.

  The following options are available:

  • action: filter by the action of the log

  • timestamp: return the logs matching the timestamp constraints. Valid constraints are of the form “<lt|le|gt|ge>:<x>”. The expected format is YYYY-MM-DDTHH:mm:ss.ssssss, so an ISO-8601 datetime string, in UTC timezone.

  For example: ?filter.timestamp=ge:2021-08-18T09:21:30.568353&filter.timestamp=lt:2021-08-18T10:21:30.568353. Multiple constraints can be specified, in which case only log messages that match all constraints will be returned.

  • message: filter by the content of the log messages. Partial matches are allowed. (case-insensitive)

  • minimal_log_level: filter by the log level of the log messages. The filter specifies the minimal level, so messages with either this level, or a higher severity level are going to be included in the result.

  For example, for filter.minimal_log_level=INFO, the log messages with level INFO, WARNING, ERROR, CRITICAL all match the query.

• sort – Return the results sorted according to the parameter value. It should follow the pattern <attribute_to_sort_by>.<order>, for example timestamp.desc (case insensitive). Only sorting by timestamp is supported. The following orders are supported: ‘asc’, ‘desc’

Returns:

A list of all matching resource logs

Raises:

• NotFound – This exception is raised when the referenced environment is not found

• BadRequest – When the parameters used for filtering, sorting or paging are not valid

inmanta.protocol.methods_v2.resources_status(tid: UUID, version: int, rids: list[ResourceIdStr]) → dict[ResourceIdStr, ResourceState]

Get the deployment status for a batch of resource ids

Parameters:

• tid – The id of the environment the resources belong to

• version – Version of the model to get the status for

• rids – List of resource ids to fetch the status for.

inmanta.protocol.methods_v2.resume_environment(tid: UUID) → None

Resume all orchestrator operations for an environment. Resumes normal environment operation and unpauses all agents that were active when the environment was halted.

Parameters:

tid – The environment id

Raises:

NotFound – The given environment doesn’t exist.

inmanta.protocol.methods_v2.set_fact(tid: UUID, name: str, source: ParameterSource, value: str, resource_id: str, metadata: dict[str, str] | None = None, recompile: bool = False, expires: bool | None = True) → ReturnValue[Fact]

Set a fact on the server. If the fact is a tracked unknown, it will trigger a recompile on the server. Otherwise, if the value is changed and recompile is true, a recompile is also triggered.

Parameters:

• tid – The id of the environment

• name – The name of the fact

• source – The source of the fact

• value – The value of the fact

• resource_id – The resource this fact belongs to

• metadata – Optional. Metadata about the fact

• recompile – Optional. Whether to trigger a recompile if the value of the fact changed.

• expires – Optional. If the fact should expire or not. By default, facts expire.

inmanta.protocol.methods_v2.set_parameter(tid: UUID, name: str, source: ParameterSource, value: str, metadata: dict[str, str] | None = None, recompile: bool = False) → ReturnValue[Parameter]

Set a parameter on the server. If the parameter is an tracked unknown, it will trigger a recompile on the server. Otherwise, if the value is changed and recompile is true, a recompile is also triggered.

Parameters:

• tid – The id of the environment

• name – The name of the parameter

• source – The source of the parameter.

• value – The value of the parameter

• metadata – Optional. Metadata about the parameter

• recompile – Optional. Whether to trigger a recompile if the value of the parameter changed.

inmanta.protocol.methods_v2.set_password(username: str, password: str) → None

Change the password of a user

Parameters:

• username – The username of the user

• password – The password of this new user. The password should be at least 8 characters long.

Raises:

• NotFound – Raised when the user does not exist

• BadRequest – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.update_agent_map(agent_map: dict[str, str]) → None

Notify an agent about the fact that the autostart_agent_map has been updated.

Parameters:

agent_map – The content of the new autostart_agent_map

inmanta.protocol.methods_v2.update_notification(tid: UUID, notification_id: UUID, read: bool | None = None, cleared: bool | None = None) → Notification

Update a notification by setting its flags

Parameters:

• tid – The id of the environment

• notification_id – The id of the notification to update

• read – Whether the notification has been read

• cleared – Whether the notification has been cleared

Returns:

The updated notification

Raises:

NotFound – When the referenced environment or notification is not found

inmanta.protocol.methods_v2.versioned_resource_details(tid: UUID, version: int, rid: ResourceIdStr) → VersionedResourceDetails

Parameters:

• tid – The id of the environment

• version – The version number of the resource

• rid – The id of the resource

Returns:

The details of a specific version of a resource

Raises:

NotFound – This exception is raised when the referenced environment or resource is not found

Server

class inmanta.server.extensions.ApplicationContext

Bases: object

class inmanta.server.bootloader.InmantaBootloader(configure_logging: bool = False)

Bases: object

The inmanta bootloader is responsible for: - discovering extensions - loading extensions - loading core and extension slices - starting the server and its slices in the correct order