Allocation V2

Allocation V2 is a new framework, similar to allocation (v1). It happens in the same lifecycle stage and serves the same purpose: filling up read-only values of a service instance.

It comes to fill some gaps in the functionalities of allocation (v1) and takes advantages of the experience and learnings that using allocation (v1) taught us. It is a more complete, functional, and elegant framework.

Example

The example below show you the use case where a single allocator is used the same way on both the service instance and an embedded entity.

main.cf

import lsm
import lsm::fsm


entity ValueService extends lsm::ServiceEntity:
    string                      name
    lsm::attribute_modifier     name__modifier="rw"

    int?                        first_value
    lsm::attribute_modifier     first_value__modifier="r"
end
ValueService.embedded_values [0:] -- EmbeddedValue

entity EmbeddedValue extends lsm::EmbeddedEntity:
    string                      id
    lsm::attribute_modifier     id__modifier="rw"

    int?                        third_value
    lsm::attribute_modifier     third_value__modifier="r"

    string[]? __lsm_key_attributes = ["id"]
end

index EmbeddedValue(id)

implement ValueService using parents
implement EmbeddedValue using std::none

binding = lsm::ServiceEntityBinding(
    service_entity="__config__::ValueService",
    lifecycle=lsm::fsm::simple,
    service_entity_name="value-service",
    allocation_spec="value_allocation",
    strict_modifier_enforcement=true,
)

for assignment in lsm::all(binding):
    attributes = assignment["attributes"]

    service = ValueService(
        instance_id=assignment["id"],
        entity_binding=binding,
        name=attributes["name"],
        first_value=attributes["first_value"],
    )

    for embedded_value in attributes["embedded_values"]:
        service.embedded_values += EmbeddedValue(
            **embedded_value
        )
    end
end

plugins/__init__.py

"""
    Inmanta LSM

    :copyright: 2022 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""
from inmanta.util import dict_path
from inmanta_plugins.lsm.allocation import AllocationSpecV2
from inmanta_plugins.lsm.allocation_v2.framework import AllocatorV2, ContextV2, ForEach


class IntegerAllocator(AllocatorV2):
    def __init__(self, value: int, attribute: str) -> None:
        self.value = value
        self.attribute = dict_path.to_path(attribute)

    def needs_allocation(self, context: ContextV2) -> bool:
        try:
            if not context.get_instance().get(self.attribute):
                # Attribute not present
                return True
        except IndexError:
            return True
        return False

    def allocate(self, context: ContextV2) -> None:
        context.set_value(self.attribute, self.value)


AllocationSpecV2(
    "value_allocation",
    IntegerAllocator(value=1, attribute="first_value"),
    ForEach(
        item="item",
        in_list="embedded_values",
        identified_by="id",
        apply=[
            IntegerAllocator(
                value=3,
                attribute="third_value",
            ),
        ],
    ),
)

Allocation V2 features

The two main additions to allocation v2 when compared to v1 are:

• The new ContextV2 object (replacement for AllocationContext object), which goes in pair with AllocatorV2 and AllocationSpecV2

• The support for allocating attributes in embedded entities.

Setting a read-only attribute on an embedded entity, like done in the above-mentioned example, is only possible when strict_modifier_enforcement is enabled. On legacy services, where strict_modifier_enforcement is not enabled, read-only attributes can be set on embedded entities using the workaround mentioned the Section Legacy: Set attributes on embedded entities.

Warning

To use allocation safely, allocators should not keep any state between invocations, but pass all state via the ContextV2 object.

ContextV2

A context object that will be passed to each allocator and that should be used to set values. This context always shows the attributes the allocator should have access to, based on its level in the allocators tree. This means a top level allocator will see all the attributes, but an allocator used on embedded entities will only see the attributes of such embedded entity (as if it was a standalone entity). The context object can also be used to store values at each “level of allocation”, reachable by all allocators at the same level.

In the example at the beginning of this page, the same allocator can be used to set a value on the service entity and an embedded entity. In needs_allocation, when calling context.get_instance(), we receive as dict the full service entity when allocating first_value and the embedded entity when allocating third_value.

AllocatorV2

A base class for all v2 allocators, they are provided with a ContextV2 object for those two methods: needs_allocation and allocate. The main difference with v1, is that the allocate method doesn’t return any value to allocate, it sets them using the context object: context.set_value(name, value).

AllocationSpecV2

The collector for all AllocatorV2.

Legacy: Set attributes on embedded entities

The server doesn’t have support to set read-only attributes on embedded entities when strict_modifier_enforcement is disabled. Thanks to the allocator ContextV2Wrapper and the plugin lsm::context_v2_unwrapper a workaround exists to do allocation on an embedded entity’s attributes with strict_modifier_enforcement disabled. This workaround saves all the allocated values in a dict, in an attribute of the service instance (added to the instance for this single purpose). That way, the server accepts the update.

The ContextV2Wrapper, which has to be used at the root of the allocation tree, will collect and save all the allocated value in a single dict. And when getting all the service instances in your model, with lsm::all, you can simply wrap the call to lsm::all with a call to lsm::context_v2_unwrapper, which will place all the allocated values saved in the dict, directly where they belong, in the embedded entities.

When using the ContextV2Wrapper and the lsm::context_v2_unwrapper plugin, you will have to specify in which attributes all the allocated values should be saved.

main.cf

import lsm
import lsm::fsm


entity ValueService extends lsm::ServiceEntity:
    string                      name
    lsm::attribute_modifier     name__modifier="rw"

    int?                        first_value
    lsm::attribute_modifier     first_value__modifier="r"

    dict?                       allocated
    lsm::attribute_modifier     allocated__modifier="r"
end
ValueService.embedded_values [0:] -- EmbeddedValue

entity EmbeddedValue extends lsm::EmbeddedEntity:
    string                      id
    lsm::attribute_modifier     id__modifier="rw"

    int?                        third_value
    lsm::attribute_modifier     third_value__modifier="r"
end

implement ValueService using parents
implement EmbeddedValue using std::none

binding = lsm::ServiceEntityBinding(
    service_entity="__config__::ValueService",
    lifecycle=lsm::fsm::simple,
    service_entity_name="value-service",
    allocation_spec="value_allocation",
)

for assignment in lsm::context_v2_unwrapper(
    assignments=lsm::all(binding),
    fallback_attribute="allocated",
):
    attributes = assignment["attributes"]

    service = ValueService(
        instance_id=assignment["id"],
        entity_binding=binding,
        name=attributes["name"],
        first_value=attributes["first_value"],
        allocated=attributes["allocated"],
    )

    for embedded_value in attributes["embedded_values"]:
        service.embedded_values += EmbeddedValue(
            **embedded_value
        )
    end
end

plugins/__init__.py

"""
    Inmanta LSM

    :copyright: 2022 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""
from inmanta.util import dict_path
from inmanta_plugins.lsm.allocation import AllocationSpecV2
from inmanta_plugins.lsm.allocation_v2.framework import (
    AllocatorV2,
    ContextV2,
    ContextV2Wrapper,
    ForEach,
)


class IntegerAllocator(AllocatorV2):
    def __init__(self, value: int, attribute: str) -> None:
        self.value = value
        self.attribute = dict_path.to_path(attribute)

    def needs_allocation(self, context: ContextV2) -> bool:
        try:
            if not context.get_instance().get(self.attribute):
                # Attribute not present
                return True
        except IndexError:
            return True
        return False

    def allocate(self, context: ContextV2) -> None:
        context.set_value(self.attribute, self.value)


AllocationSpecV2(
    "value_allocation",
    IntegerAllocator(value=1, attribute="first_value"),
    ContextV2Wrapper(
        "allocated",
        ForEach(
            item="item",
            in_list="embedded_values",
            identified_by="id",
            apply=[
                IntegerAllocator(
                    value=3,
                    attribute="third_value",
                ),
            ],
        ),
    ),
)

To facilitate allocation on embedded entities, the ForEach allocator can be used.

Deleting of Embedded entities

When you want to support deletion of embedded entities during updates, a slightly different configuration is needed. Because all allocated values are stored in a single attribute, the deleted entities will be recreated when unwrapping.

To prevent this, use track_deletes=true on both the the allocator ContextV2Wrapper and the plugin lsm::context_v2_unwrapper

Additionally, to re-trigger allocation when an item is deleted, use SetSensitiveForEach instead of ForEach.

main.cf

import lsm
import lsm::fsm


entity ValueService extends lsm::ServiceEntity:
    string                      name
    lsm::attribute_modifier     name__modifier="rw"

    int?                        first_value
    lsm::attribute_modifier     first_value__modifier="r"

    dict?                       allocated
    lsm::attribute_modifier     allocated__modifier="r"
end
ValueService.embedded_values [0:] lsm::__rwplus__ EmbeddedValue

entity EmbeddedValue extends lsm::EmbeddedEntity:
    string                      id
    lsm::attribute_modifier     id__modifier="rw"

    int?                        third_value
    lsm::attribute_modifier     third_value__modifier="r"

    string                      other_value
    lsm::attribute_modifier     other_value__modifier="rw"
end

index EmbeddedValue(id)

implement ValueService using parents
implement EmbeddedValue using std::none

binding = lsm::ServiceEntityBindingV2(
    service_entity="__config__::ValueService",
    lifecycle=lsm::fsm::simple,
    service_entity_name="value-service",
    allocation_spec="value_allocation",
)

for assignment in lsm::context_v2_unwrapper(
    assignments=lsm::all(binding),
    fallback_attribute="allocated",
    track_deletes=true,
):
    attributes = assignment["attributes"]

    service = ValueService(
        instance_id=assignment["id"],
        entity_binding=binding,
        name=attributes["name"],
        first_value=attributes["first_value"],
        allocated=attributes["allocated"],
    )

    for embedded_value in attributes["embedded_values"]:
        service.embedded_values += EmbeddedValue(
            **embedded_value
        )
    end
end

plugins/__init__.py

"""
    Inmanta LSM

    :copyright: 2020 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""
from inmanta.util import dict_path
from inmanta_plugins.lsm.allocation import AllocationSpecV2
from inmanta_plugins.lsm.allocation_v2.framework import (
    AllocatorV2,
    ContextV2,
    ContextV2Wrapper,
    SetSensitiveForEach,
)


class IntegerAllocator(AllocatorV2):
    def __init__(self, value: int, attribute: str) -> None:
        self.value = value
        self.attribute = dict_path.to_path(attribute)

    def needs_allocation(self, context: ContextV2) -> bool:
        try:
            if not context.get_instance().get(self.attribute):
                # Attribute not present
                return True
        except IndexError:
            return True
        return False

    def allocate(self, context: ContextV2) -> None:
        if self.needs_allocation(context):
            context.set_value(self.attribute, self.value)


AllocationSpecV2(
    "value_allocation",
    IntegerAllocator(value=1, attribute="first_value"),
    ContextV2Wrapper(
        "allocated",
        SetSensitiveForEach(
            item="item",
            in_list="embedded_values",
            identified_by="id",
            apply=[
                IntegerAllocator(
                    value=3,
                    attribute="third_value",
                ),
            ],
        ),
        track_deletes=True,
    ),
)