Python client¶

The rest API endpoints described below are also available as a redoc spec.

You can interact with the API endpoints detailed below by using the inmanta.protocol.endpoints.Client python client:

client = inmanta.protocol.endpoints.Client(name="api", timeout=120)

result = await client.environment_list(details=True)

assert result.code == 200

for key, value in result.result["data"].items():
    ...

When calling a v2 endpoint, use the inmanta.protocol.common.Result.value() method to retrieve a fully typed object e.g.:

client = inmanta.protocol.endpoints.Client(name="api", timeout=120)

env_uuid = ...
env_object: inmanta.data.model.Environment = await client.environment_get(env_uuid).value()

assert isinstance(env_object, inmanta.data.model.Environment)

Paging, sorting and filtering¶

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

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.

start

Min boundary value (exclusive) for the requested page for the primary sort column, regardless of sorting order.

end

Max boundary value (exclusive) for the requested page for the primary sort column, regardless of sorting order.

first_id

Min boundary value (exclusive) for the requested page for the secondary sort column, if there is one, regardless of sorting order. When used along with the start parameter, the value of this parameter is used as a tiebreaker on the secondary sort column for records whose primary sort column is equal to the start parameter.

last_id

Max boundary value (exclusive) for the requested page for the secondary sort column, if there is one, regardless of sorting order. When used along with the end parameter, the value of this parameter is used as a tiebreaker on the secondary sort column for records whose primary sort column is equal to the end parameter.

(only one of the (start, first_id), (end, last_id) pairs should be specified at the same time).

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.

Note

The return value of these methods that support paging contains a links tag, with the urls of the next and prev pages. To iterate over all the results, the client can follow these links, or alternatively call the helper methods on the inmanta.protocol.common.PageableResult object:

# Iterate over all results by fetching pages of size 20

async for item in client.resource_list(tid=env.id, limit=20).all():
    ...


# Iterate over results on a single page

for item in await client.resource_list(tid=env.id, limit=20).value():
    ...

When calling an endpoint from a synchronous context, the inmanta.protocol.common.PageableResult.all_sync() method should be used instead of the all() method:

# Iterate over all results by fetching pages of size 20
for item in client.resource_list(tid=env.id, limit=20).all_sync():
    assert item == all_resources[idx]
    idx += 1

Static type checking¶

The inmanta mypy plugin provides static type checking on the methods called via the python client. Make sure you add the inmanta plugin to your mypy configuration, e.g. using the pyproject.toml file:

[tool.mypy]
plugins = 'inmanta.mypy'

And then use mypy for static type checking, e.g. given the following python file:

client = inmanta.protocol.endpoints.Client(name="api", timeout=120)

env_id: str = "123"
result = await client.resource_list(env_id)

Use mypy for type checking:

$ mypy <path/to/file.py>

(...) error: Argument 1 to "resource_list" has incompatible type "str"; expected "UUID"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

Endpoints¶

V1 endpoints¶

inmanta.protocol.methods.clear_environment(id: UUID)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Return a detailed report for a node

Parameters:: id – The session id of the agent
Returns:: The requested node

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

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

The returned compile run object may carry links to other objects, e.g. a service instance. The full list of supported links can be found here.

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_file(id: str)[source]¶

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)[source]¶

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_id: ResourceIdStr)[source]¶

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_id – The id of the resource to query the parameters from

inmanta.protocol.methods.get_project(id: UUID)[source]¶

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)[source]¶

Get a compile report from the server

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

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)[source]¶

Return compile reports newer then start

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

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, log_action: ResourceAction | None = None, log_limit: int = 0)[source]¶

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_server_status() → StatusResponse[source]¶: Get the status of the server

inmanta.protocol.methods.get_setting(tid: UUID, id: str)[source]¶

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)[source]¶

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()[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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

inmanta.protocol.methods.is_compiling(id: UUID)[source]¶

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)[source]¶

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)[source]¶

List all agent for an environment

[DEPRECATED] use the V2 get_agents or /agents endpoint instead

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()[source]¶: 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 = {})[source]¶

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()[source]¶: 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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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 = {})[source]¶

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)[source]¶

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, module_version_info: dict[str, InmantaModule], resource_state: dict[ResourceIdStr, Literal[ResourceState.available, ResourceState.undefined]] = {}, unknowns: Sequence[Mapping[str, UUID | bool | int | float | datetime | str | None]] | None = None, version_info: dict | None = None, compiler_version: str | None = None, resource_sets: dict[ResourceIdStr, str | None] = {}, pip_config: PipConfig | None = None, project_constraints: str | None = None)[source]¶

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
module_version_info – Map of (module name, module version) to InmantaModule
project_constraints – String of all the constraints set at the project level (if any) to be enforced during agent code install

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

Release version of the configuration model for deployment.

Parameters:

tid – The id of the environment
id – The version of the CM to deploy
push – [DEPRECATED] This argument is ignored.
agent_trigger_method – [DEPRECATED]: This argument is ignored.

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.set_param(tid: UUID, id: str, source: ParameterSource, value: str, resource_id: str | None = None, metadata: dict = {}, recompile: bool = False, expires: bool | None = None)[source]¶

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)[source]¶

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

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 | None, enabled: bool)[source]¶

Set the state of the agent.

Parameters:

agent – The name of the agent if it’s provided. None represents all agents
enabled – A boolean value indicating whether the agent should be paused (enabled=False) or unpaused (enabled=True).

inmanta.protocol.methods.stat_file(id: str)[source]¶

Does the file exist

Parameters:: id – The id of the file to check

inmanta.protocol.methods.stat_files(files: list)[source]¶

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: None | str, incremental_deploy: bool)[source]¶

When the <id> parameter is set: request this specific agent to reload resources. Otherwise, request ALL agents in the environment 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_read_version(tid: UUID) → int[source]¶

Notify the scheduler that a new version has been released

Parameters:: tid – The environment this agent is defined in

inmanta.protocol.methods.upload_file(id: str, content: str)[source]¶

Upload a new file

Parameters:

id – The sha1 hash of the content of the file.
content – The base64 encoded content of the file

V2 endpoints¶

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: AllAgentAction) → 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
- remove_all_agent_venvs: Remove all agent venvs in the given environment. During this
  process the agent operations in that environment are temporarily suspended. The removal of the agent venvs will happen asynchronously with respect to this API call. It might take a long time until the venvs are actually removed, because all executing agent operations will be allowed to finish first. As such, a long deploy operation might delay the removal of the venvs considerably.

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.assign_role(username: str, environment: UUID, role: str) → None¶

Assign a role to a certain user.

Parameters:

username – The name of the user the role will be assigned to.
environment – The environment scope of the role.
role – The name of the role that should be assigned to the user.

Raises:

BadRequest – Raised when server authentication is not enabled

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

The returned compile details object may carry links to other objects, e.g. a service instance. The full list of supported links can be found here.

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.create_role(name: str) → None¶

Create a new role.

Parameters:: name – The name of the role to create.
Raises:: BadRequest – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.delete_role(name: str) → None¶

Delete a role.

Parameters:: name – The name of the role to delete.
Raises:: BadRequest – Raised when server authentication is not enabled

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: Sequence[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: Mapping[str, Sequence[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’, ‘resource_type’, ‘agent’, ‘resource_id_value’. 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.
- filter.resource_type: filter by resource type.
- filter.agent: filter by agent.
- filter.resource_id_value: filter by resource id value.

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: Sequence[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

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

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

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, token: str | None = None) → 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
token – If provided, use this token to authorize the request instead of the value from the authorization header.

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: Mapping[str, Sequence[str]] | None = None, sort: str = 'requested.desc') → list[CompileReport]¶

Get the compile reports from an environment.

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

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_db_status() → DataBaseReport¶: Get a report of the DB connection pool status

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: Sequence[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

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

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: Mapping[str, Sequence[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_scheduler_status(tid: UUID) → SchedulerStatusReport¶

Inspect the scheduler state from the given environment.

Parameters:: tid – The id of the environment in which to inspect the scheduler.
Raises:: NotFound – No scheduler is running. For example because the environment is halted.

inmanta.protocol.methods_v2.graphql(query: str) → Any¶

GraphQL endpoint for Inmanta. Supports paging, filtering and sorting on certain attributes.

To check which queries are enabled, use the ‘GET /api/v2/graphql/schema’ endpoint.

inmanta.protocol.methods_v2.graphql_schema() → dict[str, Any]¶: Endpoint to retrieve schema details for the GraphQL endpoint. To actually execute a query, use ‘POST /api/v2/graphql’

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.health() → ReturnValue[None]¶

Returns a 200 response code if the server is healthy or a 500 if the server is not healthy.

In contrast to the ‘GET /api/v1/serverstatus’ endpoint, this endpoint does not require authentication.

inmanta.protocol.methods_v2.list_desired_state_versions(tid: UUID, limit: int | None = None, start: int | None = None, end: int | None = None, filter: Mapping[str, Sequence[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, ‘status’ and released are 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: Mapping[str, Sequence[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_roles() → list[str]¶: Returns the names of the roles that exist.

inmanta.protocol.methods_v2.list_roles_for_user(username: str) → RoleAssignmentsPerEnvironment¶

Returns the roles assigned to the given user.

Parameters:: username – The name of the user for which the roles are returned.

inmanta.protocol.methods_v2.list_users() → list[UserWithRoles]¶

List all users

Returns:: A list of all users

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

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.notify_timer_update(tid: UUID) → None¶: Notify the scheduler of a change in the timer settings

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 – [DEPRECATED] This argument is ignored.

inmanta.protocol.methods_v2.protected_environment_settings_set_batch(tid: UUID, settings: dict[str, bool | int | float | str | dict[str, str | int | bool]], protected_by: ProtectedBy) → None¶

Set the values for the given environment settings and mark them as protected. If any other environment setting in that environment was protected for the same reason, its protected status will be cancelled.

Parameters:

tid – The id of the environment from which to update the environment settings.
settings – The values for each environment setting that has to be updated.
protected_by – The reason why the environment settings must be protected.

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
module_version_info – Map of (module name, module version) to InmantaModule
allow_handler_code_update – [Expert] Allow handler code update during partial compile. This is otherwise only allowed for full compiles. Use with extreme caution, and only when confident that all code is compatible with previous versions.

Returns:

The newly stored version number.

inmanta.protocol.methods_v2.remove_executor_venvs() → None¶: Remove all the Python virtual environments.

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_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: Mapping[str, Sequence[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 ‘!’. The inverted status filter works as a separate filter from the normal status filter. For example: filter.status=!orphaned will return all the resources that are not in ‘orphaned’ state. If multiple values are provided to the inverted filter, resources are returned if they don’t match any of the filter values. For example: ?filter.status=!deployed&filter.status=!available returns all instances except those whose status is deployed or available. 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: Mapping[str, Sequence[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.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: Mapping[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_is_admin(username: str, is_admin: bool) → None¶

Set whether the given user is an admin or not.

Parameters:

username – The username of the user for which the admin status has to be updated.
is_admin – True iff the given user should be an admin user.

Raises:

BadRequest – Raised when server authentication is not enabled

inmanta.protocol.methods_v2.set_parameter(tid: UUID, name: str, source: ParameterSource, value: str, metadata: Mapping[str, str] | None = None, recompile: bool = False) → ReturnValue[Parameter]¶

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.trigger_get_status(tid: UUID) → SchedulerStatusReport¶

Get a snapshot of the scheduler state

Parameters:: tid – The id of the environment.

inmanta.protocol.methods_v2.unassign_role(username: str, environment: UUID, role: str) → None¶

Remove a role from a certain user.

Parameters:

username – The name of the user from which to unassign the role.
environment – The environment scope of the role.
role – The name of the role that should be unassigned from the user.

Raises:

BadRequest – If the user with the given username doesn’t have the given role assigned.
BadRequest – Raised when server authentication is not enabled

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