Unmanaged Resources

Unmanaged resources are resources that live in the network that are not yet managed by the orchestrator. They may be of the same type as other resources that are already managed, or something else entirely. The orchestrator can discover unmanaged resources in the network, given proper guidance. This discovery is driven by discovery resources in the model. They express the intent to discover resources of the associated type in the network.

Terminology

• Discovery resource: The category of resources that express the intent to discover resources in the network. This is an actual resource that is part of the configuration model.

• Discovered resource: This is the unit of data that is generated by the discovery process. Each time the discovery process discovers a resource, it creates a record in the inventory for discovered resources. This record contains the set of attributes that define the current state of the discovered resource. Discovered resources only exist in the discovered resources database. They don’t exist in the configuration model.

Example

The code snippet below defines a discovery resource called InterfaceDiscovery. Instances of this resource will discover the interfaces present on a specific host. A discovery resource must always inherit from std::DiscoveryResource. Note that discovery resources are defined in exactly the same way as a regular resource, except that they inherit from std::DiscoveryResource instead of std::PurgeableResource or std::Resource.

my_project/main.cf

import ip

entity InterfaceDiscovery extends std::DiscoveryResource:
    """
    A discovery resource that discovers interfaces on a specific host.

    :attr name_filter: If not null, only discover interfaces for which the name matches this regular expression.
                       Otherwise discover all the interfaces on the host.
    """
    string? name_filter = null
end

InterfaceDiscovery.host [1] -- ip::Host

index InterfaceDiscovery(host)

implement InterfaceDiscovery using parents, std::none

The associated handler code is shown below:

my_module/inmanta_plugins/__init__.py

import re
from collections import abc

import pydantic

from inmanta import resources
from inmanta.data.model import ResourceIdStr
from inmanta.agent.handler import provider, DiscoveryHandler, HandlerContext
from inmanta.resources import resource, DiscoveryResource


@resource("my_module::InterfaceDiscovery", agent="host.name", id_attribute="host")
class InterfaceDiscovery(DiscoveryResource):
    fields = ("host", "name_filter")

    host: str
    name_filter: str

    @staticmethod
    def get_host(exporter, resource):
        return resource.host.name


class UnmanagedInterface(pydantic.BaseModel):
    """
    Datastructure used by the InterfaceDiscoveryHandler to return the attributes
    of its discovered resources.
    """

    host: str
    interface_name: str
    ip_address: str


@provider("my_module::InterfaceDiscovery", name="interface_discovery_handler")
class InterfaceDiscoveryHandler(DiscoveryHandler[InterfaceDiscovery, UnmanagedInterface]):
    def discover_resources(
        self, ctx: HandlerContext, discovery_resource: InterfaceDiscovery
    ) -> dict[ResourceIdStr, UnmanagedInterface]:
        """
        Entrypoint that is called by the agent when the discovery resource is deployed.
        """
        discovered: abc.Iterator[UnmanagedInterface] = (
            UnmanagedInterface(**attributes)
            for attributes in self._get_discovered_interfaces(discovery_resource)
            if discovery_resource.name_filter is None or re.match(discovery_resource.name_filter, attributes["interface_name"])
        )
        return {
            resources.Id(
                entity_type="my_module::Interface",
                agent_name=res.host,
                attribute="interface_name",
                attribute_value=res.interface_name,
            ).resource_str(): res
            for res in discovered
        }

    def _get_discovered_interfaces(self, discovery_resource: InterfaceDiscovery) -> list[dict[str, object]]:
        """
        A helper method that contains the logic to discover the unmanaged interfaces in the network.
        It returns a list of dictionaries where each dictionary contains the attributes of an unmanaged resource.
        """
        raise NotImplementedError()

The handler code consists of three parts:

• Lines 12-21: The class that describes how the discovery resource InterfaceDiscovery should be serialized. This resource definition is analogous to the definition of a regular PurgeableResource or Resource, except that the class inherits from DiscoveryResource.

• Lines 24-31: A Pydantic BaseModel that represents the datastructure that will be used by the discovery handler to return the attributes of the discovered resources. This specific example uses a Pydantic BaseModel, but discovery handlers can use any json serializable datastructure.

• Line: 34-61: This is the handler for the discovery resource. A discovery handler class must satisfy the following requirements:

  • It must be annotated with the @provider annotation, like a regular CRUDHandler or ResourceHandler.

  • It must inherit from the DiscoveryHandler class. This is a generic class with two parameters. The first parameter is the class of the associated DiscoveryResource and the second parameter is the type of datastructure that the discovery handler will use to return the attributes of discovered resources.

  • It must implement a method called discover_resources that contains the logic to discover the resources in the network. This method returns a dictionary. The keys of this dictionary contain the resource ids of the discovered resources and the values the associated attributes.

Sharing attributes

In some situations there is a need to share behavior or attributes between a resource X and the discovery resource for X. For example, both might require credentials to authenticate to their remote host. This can be done by making both entities inherit from a shared parent entity. An example is provided below.

my_project/main.cf

import ip

entity Credentials:
    """
    An entity that holds the shared attributes between the Interface and InterfaceDiscovery entity.
    """
    string username
    string password
end

implement Credentials using std::none

entity InterfaceBase:
    """
    Base entity for the Interface and InterfaceDiscovery handler.
    """
end

InterfaceBase.credentials [1] -- Credentials
InterfaceBase.host [1] -- ip::Host

implement InterfaceBase using std::none

entity Interface extends InterfaceBase, std::PurgeableResource:
    """
    An entity that represents an interface that is managed by the Inmanta server.
    """
    string name
    std::ipv4_address ip_address
end

index Interface(host, name)

implement Interface using parents, std::none

entity InterfaceDiscovery extends InterfaceBase, std::DiscoveryResource:
    """
    A discovery resource used to discover interfaces that exist on a specific host.

    :attr name_filter: If not null, this resource only discovers the interfaces for which the name matches this
                       regular expression. Otherwise discover all the interfaces on the host.
    """
    string? name_filter = null
end

index InterfaceDiscovery(host)

implement InterfaceDiscovery using parents, std::none

The Credentials entity, in the above-mentioned snippet, contains the shared attributes between the PurgeableResource Interface and the DiscoveryResource InterfaceDiscovery.

The associated handler code is provided below:

my_module/inmanta_plugins/__init__.py

import re
from collections import abc
from typing import Optional

import pydantic

from inmanta import resources
from inmanta.data.model import ResourceIdStr
from inmanta.agent.handler import provider, DiscoveryHandler, HandlerContext, CRUDHandler
from inmanta.resources import resource, DiscoveryResource, PurgeableResource


class InterfaceBase:
    fields = ("host", "username", "password")

    host: str
    username: str
    password: str

    @staticmethod
    def get_host(exporter, resource):
        return resource.host.name

    @staticmethod
    def get_username(exporter, resource):
        return resource.credentials.username

    @staticmethod
    def get_password(exporter, resource):
        return resource.credentials.password


@resource("my_module::Interface", agent="host.name", id_attribute="name")
class Interface(InterfaceBase, PurgeableResource):
    fields = ("name", "ip_address")

    name: str
    ip_address: str


@resource("my_module::InterfaceDiscovery", agent="host.name", id_attribute="host")
class InterfaceDiscovery(InterfaceBase, DiscoveryResource):
    fields = ("name_filter",)

    name_filter: Optional[str]


class UnmanagedInterface(pydantic.BaseModel):
    """
    Datastructure used by the InterfaceDiscoveryHandler to return the attributes
    of the discovered resources.
    """

    host: str
    interface_name: str
    ip_address: str


class Authenticator:
    """
    Helper class that handles the authentication to the remote host.
    """

    def login(self, credentials: InterfaceBase) -> None:
        raise NotImplementedError()

    def logout(self, credentials: InterfaceBase) -> None:
        raise NotImplementedError()


@provider("my_module::Interface", name="interface_handler")
class InterfaceHandler(Authenticator, CRUDHandler[Interface]):
    """
    Handler for the interfaces managed by the orchestrator.
    """

    def pre(self, ctx: HandlerContext, resource: Interface) -> None:
        self.login(resource)

    def post(self, ctx: HandlerContext, resource: Interface) -> None:
        self.logout(resource)

    def read_resource(self, ctx: HandlerContext, resource: Interface) -> None:
        raise NotImplementedError()

    def create_resource(self, ctx: HandlerContext, resource: Interface) -> None:
        raise NotImplementedError()

    def delete_resource(self, ctx: HandlerContext, resource: Interface) -> None:
        raise NotImplementedError()

    def update_resource(self, ctx: HandlerContext, changes: dict, resource: Interface) -> None:
        raise NotImplementedError()


@provider("my_module::InterfaceDiscovery", name="interface_discovery_handler")
class InterfaceDiscoveryHandler(Authenticator, DiscoveryHandler[InterfaceDiscovery, UnmanagedInterface]):

    def pre(self, ctx: HandlerContext, resource: InterfaceDiscovery) -> None:
        self.login(resource)

    def post(self, ctx: HandlerContext, resource: InterfaceDiscovery) -> None:
        self.logout(resource)

    def discover_resources(
        self, ctx: HandlerContext, discovery_resource: InterfaceDiscovery
    ) -> abc.Mapping[ResourceIdStr, UnmanagedInterface]:
        """
        Entrypoint that is called by the agent when the discovery resource is deployed.
        """
        discovered: abc.Iterator[UnmanagedInterface] = (
            UnmanagedInterface(**attributes)
            for attributes in self._get_discovered_interfaces(discovery_resource)
            if discovery_resource.name_filter is None or re.match(discovery_resource.name_filter, attributes["interface_name"])
        )
        return {
            resources.Id(
                entity_type="my_module::Interface",
                agent_name=res.host,
                attribute="interface_name",
                attribute_value=res.interface_name,
            ).resource_str(): res
            for res in discovered
        }

    def _get_discovered_interfaces(self, discovery_resource: InterfaceDiscovery) -> list[dict[str, object]]:
        """
        A helper method that contains the logic to discover the unmanaged interfaces in the network.
        It returns a list of dictionaries where each dictionary contains the attributes of a discovered interface.
        """
        raise NotImplementedError()

In the above-mentioned code snippet the Credentials class contains the shared attributes between the Interface resource and the InterfaceDiscovery resource. The Authenticator class on the other hand contains the shared logic between the InterfaceHandler and the InterfaceDiscoveryHandler class.