References and Secrets

When a handler needs information that is not available to the compiler, references are used.

For example, to extract username and password from an environment variables:

leaf1 = nokia_srlinux::GnmiDevice(
    auto_agent=true,
    name="leaf1",
    mgmt_ip="172.30.0.210",
    yang_credentials=yang::Credentials(
        username=std::create_environment_reference("GNMI_USER"),
        password=std::create_environment_reference("GNMI_PASS"),
    ),
)

This means that the username and password will never be present in the compiler, but that they will be picked up by the handler when needed. This is very different from using std::get_env, which will resolve the environment variable in the compiler and store it in the database.

More advanced combination are also possible:

netbox_secret = netbox::create_netbox_reference(
    netbox_url=...,
    netbox_token=std::create_environment_reference("NETBOX_API_TOKEN"),
    device=leaf1.name,
    role="admin",
)

leaf1 = nokia_srlinux::GnmiDevice(
    auto_agent=true,
    name="leaf1",
    mgmt_ip="172.30.0.210",
    yang_credentials=yang::Credentials(
        username=netbox_secret.name,
        password=netbox_secret.password,
    ),
)

Here we get the root secret from the environment variable NETBOX_API_TOKEN, which we use to query the inventory for proper credentials for this device.

References can be used in the model and in resources transparently. However any attempt to perform an operation (e.g. addition, string formatting,… ) on a reference will result in an exception.

References will be automatically resolved before passing the resource into a handler. I.e. using references in handlers requires no special attention.

Creating new types of References

When you want to expose your own type of reference, the following steps are required:

  1. Create a subclass of inmanta.references.Reference, with a type parameter that is either a primitive type or a dataclass.

  2. Annotate it with inmanta.references.reference().

  3. Implement the resolve method, that will resolve the reference. This method can use self.resolve_others to resolve any reference received as an argument. The logger passed into this method is similar to the ctx argument passed into a handler. The logger will write the logs into the database as well, when resolving references for a handler.

  4. Create a plugin to construct the reference.

@reference("std::Environment")
class EnvironmentReference(Reference[str]):
    """A reference to fetch environment variables"""

    def __init__(self, name: str | Reference[str]) -> None:
        """
        :param name: The name of the environment variable.
        """
        super().__init__()
        # All fields will be serialized into the resources
        # i.e. it must be json serializable or a reference itself
        # Use `_` as a prefix to prevent serialization of the field
        self.name = name


    def resolve(self, logger: LoggerABC) -> str:
        """Resolve the reference"""
        # We call resolve_other to make sure that if self.name is also a reference
        # it will also be properly resolved
        env_var_name = self.resolve_other(self.name, logger)
        # It is good practice to log relevant steps
        logger.debug("Resolving environment variable %(name)s", name=self.name)
        # actual resolution
        value = os.getenv(env_var_name)
        # Validity check. Abort when not found.
        # Not special base exception is expected, exception handling follows the same rules as in handlers
        if value is None:
            raise LookupError(f"Environment variable {env_var_name} is not set")
        return value


@plugin
def create_environment_reference(name: str | Reference[str]) -> Reference[str]:
    """Create an environment reference

    :param name: The name of the variable to fetch from the environment
    :return: A reference to what can be resolved to a string
    """
    return EnvironmentReference(name=name)

Handling references in plugins

When a plugin supports references, it has to explicitly indicate this in the type annotation of the arguments and return value.

For example, to create a plugin that can concatenate two strings, where either one can be a reference, we would do the following:

from inmanta.plugins import plugin
from inmanta.references import Reference, reference

@reference("references::Concat")
class ConcatReference(Reference[str]):

    def __init__(self, one: str | Reference[str], other: str | Reference[str]) -> None:
        super().__init__()
        self.one = one
        self.other = other

    def resolve(self, logger) -> str:
        # do the actual resolution
        # First resolve the arguments, then concat them
        return self.resolve_other(self.one, logger) + self.resolve_other(self.other, logger)

@plugin
def concat(one: str | Reference[str], other: str | Reference[str]) -> str | Reference[str]:
    # Allow either str or Reference[str]
    # These types are enforced when entering the plugin, so it would not work with just str

    # Only construct the reference when required
    if isinstance(one, Reference) or isinstance(other, Reference):
        return ConcatReference(one, other)

    return one + other

import std::testing

one_value = std::create_environment_reference("test")
concat_value = concat(one_value, "b")
std::testing::NullResource(name="test", value=concat_value)

It is also possible to resolve reference in plugins, but this is not their intended use case:

import logging
from inmanta.agent.handler import PythonLogger
from inmanta.plugins import plugin
from inmanta.references import Reference

@plugin
def resolve(one: str | Reference[str]) -> str:
    if isinstance(one, Reference):
        # Construct a logger based on a python logger
        logger = PythonLogger(logging.getLogger("testing.resolver"))
        return one.resolve(logger)
    return one

one_value = std::create_environment_reference("test")
std::print(resolve(one_value)) # Will print the value of the 'test' environment variable