Allocation V3¶

Allocation V3 is a new framework that changes significantly compared to Allocation V2. The purpose is the same as V2: filling up the read-only values of a service instance during the first validation compile of the lifecycle. Allocation is now performed via a plugin call.

The advantage of this approach is that it simplifies greatly the process: you don’t need anymore to write allocator classes and all the required functions (needs_allocation, allocate, etc.). You also don’t need to instantiate many AllocationSpecV2 with your allocators inside. Instead, you just need to write one plugin per attribute you want to allocate and register it as an allocator, it is less verbose and a much more straightforward approach. LSM comes with build-in allocators that can be used out of the box, e.g. get_first_free_integer.

Create an allocator¶

In the allocation V3 framework, an allocator is a python function returning the value to be set for a specific read-only attribute on a specific service instance. To register this function as an allocator, use the allocation_helpers.allocator() decorator:

from inmanta_plugins.lsm.allocation_helpers import allocator

@allocator()
def get_service_id(
    service: "lsm::ServiceEntity",
    attribute_path: "string",
) -> "int":
    return 5

An allocator must accept exactly two positional arguments:

service, the service instance for which the value is being allocated.

2. attribute_path, the attribute of the service instance in which the allocated value should be saved, as a DictPath expression. The decorated function can define a default value.

After those two positional arguments, the function is free of accepting any keyword argument it needs from the model and they will be passed transparently. The function can also define default values, that will be passed transparently as well.

Once an allocator is registered, it can be reused for other instances and attributes that require the same type of allocation by passing the appropriate parameters to the plugin call.

It is also possible to enforce an order in the allocators call by passing values that are returned by other plugins in the model:

main.cf (Plugin call ordering)¶

"""
    Inmanta LSM
    :copyright: 2024 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""


import lsm
import lsm::fsm

entity ServiceWithOrderedAllocation extends lsm::ServiceEntity:
    """
    This service entity demonstrates how to enforce a specific order during
    the allocation process. Here we want to allocate some attributes in a
    specific order: value_allocated_first and then value_allocated_last.

    :attr name: The name identifying the service instance.
    :attr value_allocated_first: A read-only value, automatically assigned by the api
        before value_allocated_last.
    :attr value_allocated_last: A read-only value, automatically assigned by the api
        after value_allocated_first.
    """

    string                      name
    lsm::attribute_modifier     name__modifier="rw"
    string?                     value_allocated_first=null
    lsm::attribute_modifier     value_allocated_first__modifier="r"
    string?                     value_allocated_last=null
    lsm::attribute_modifier     value_allocated_last__modifier="r"
end

# Inherit parent entity's implementations
implement ServiceWithOrderedAllocation using parents


# Create a binding to enable service creation through the service catalog
ordered_allocation_binding = lsm::ServiceEntityBindingV2(
    service_entity="allocatorv3_demo::ServiceWithOrderedAllocation",
    lifecycle=lsm::fsm::simple,
    service_entity_name="allocation_order_enforcement",
)

# Collect all service instances
for assignment in lsm::all(ordered_allocation_binding):
    service = ServiceWithOrderedAllocation(
        instance_id=assignment["id"],
        entity_binding=ordered_allocation_binding,
        name=assignment["attributes"]["name"],

        # Regular allocation:
        value_allocated_first=ordered_allocation(
            service,
            "value_allocated_first"
        ),

        # Passing value_allocated_first as a parameter to this allocator
        # will enforce the ordering:
        value_allocated_last = ordered_allocation(
            service,
            "value_allocated_last",
            requires=[service.value_allocated_first]
        )

    )
end

On the plugin side, add an optional argument to enforce ordering:

__init__.py (Plugin call ordering)¶

"""
    Copyright 2024 Inmanta

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

    Contact: code@inmanta.com
"""

from datetime import datetime

from inmanta_plugins.lsm.allocation_helpers import allocator


@allocator()
def ordered_allocation(
    service: "lsm::ServiceEntity",
    attribute_path: "string",
    *,
    requires: "list?" = None
) -> "string":
    """
    For demonstration purposes, this allocator returns the current time.

    :param service: The service instance for which the attribute value
        is being allocated.
    :param attribute_path: DictPath to the attribute of the service
        instance in which the allocated value will be stored.
    :param requires: Optional list containing the results of allocator calls
        that should happen before the current call.
    """
    return str(datetime.now())

V2 to V3 migration¶

Moving from allocation V2 to allocation V3 boils down to the following steps:

In the plugins directory:

Create a specific allocator for each property of the service that requires allocation.
Make sure to register these allocators by decorating them with the @allocator() decorator.

In the model:

Call the relevant allocator plugin for each value requiring allocation in the lsm::all unwrapping.

Basic example¶

Here is an example of a V2 to V3 migration. For both the model and the plugin, first the old V2 version is shown and then the new version using V3 framework:

Plugin¶

Baseline V2 allocation in the plugins directory:

__init__.py (V2 allocation)¶

"""
    Copyright 2024 Inmanta

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

    Contact: code@inmanta.com
"""

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):
    """
    Custom allocator class to set an integer value for an attribute.
    """

    def __init__(self, value: int, attribute: str) -> None:
        """
        :param value: The value to store for this attribute of this service.
        :param attribute: Attribute of the service instance in which the
            value will be stored.
        """
        self.value = value
        self.attribute = dict_path.to_path(attribute)

    def needs_allocation(self, context: ContextV2) -> bool:
        """
        Determine if this allocator has any work to do or if all
        values have already been allocated correctly for the instance
        exposed through the context object.

        :param context: Interface with the current instance
        being unwrapped in an lsm::all call.
        """
        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:
        """
        Allocate the value for the attribute via the context object.

        :param context: Interface with the current instance
            being unwrapped in an lsm::all call.
        """
        context.set_value(self.attribute, self.value)


# In the allocation V2 framework, AllocationSpecV2 objects
# are used to configure the allocation process:
AllocationSpecV2(
    "value_allocation",
    IntegerAllocator(value=1, attribute="top_level_value"),
    ForEach(
        item="item",
        in_list="embedded_services",
        identified_by="id",
        apply=[
            IntegerAllocator(
                value=3,
                attribute="embedded_value",
            ),
        ],
    ),
)

When moving to V3, register an allocator in the plugin:

__init__.py (V3 allocation)¶

"""
    Copyright 2024 Inmanta

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

    Contact: code@inmanta.com
"""

from inmanta_plugins.lsm.allocation_helpers import allocator


@allocator()
def get_value(
    service: "lsm::ServiceEntity",
    attribute_path: "string",
    *,
    value: "any",
) -> "any":
    """
    Store a given value in the attributes of a service.

    :param service: The service instance for which the attribute value
        is being allocated.
    :param attribute_path: DictPath to the attribute of the service
        instance in which the allocated value will be stored.
    :param value: The value to store for this attribute of this service.
    """

    return value

Model¶

Baseline V2 allocation in the model:

main.cf (V2 allocation)¶

"""
    Inmanta LSM
    :copyright: 2024 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""

import lsm
import lsm::fsm

entity TopLevelService extends lsm::ServiceEntity:
    """
    Top-level service to demonstrate V2 allocation.

    :attr name: The name identifying the service instance.
    :attr top_level_value: A read-only value, automatically assigned by the api.
    """
    string                      name
    lsm::attribute_modifier     name__modifier="rw"
    int?                        top_level_value=null
    lsm::attribute_modifier     top_level_value__modifier="r"
end

# Uniquely identify top level services through their name attribute
index TopLevelService(name)

# Each top level service may have zero or more embedded services attached to it
TopLevelService.embedded_services [0:] -- EmbeddedService

entity EmbeddedService extends lsm::EmbeddedEntity:
    """
    An embedded service, attached to a TopLevelService instance.

    :attr id: Identifier for this embedded service instance.
    :attr embedded_value: A read-only value, automatically assigned by the api.
    """
    string                      id
    lsm::attribute_modifier     id__modifier="rw"
    int?                        embedded_value=null
    lsm::attribute_modifier     embedded_value__modifier="r"
    string[]? __lsm_key_attributes = ["id"]
end

# Uniquely identify embedded services through their id attribute
index EmbeddedService(id)

# Inherit parent entity's implementations
implement TopLevelService using parents

implement EmbeddedService using parents

# Create a binding to enable service creation through the service catalog
value_binding = lsm::ServiceEntityBindingV2(
    service_entity="allocatorv3_demo::TopLevelService",
    lifecycle=lsm::fsm::simple,
    service_entity_name="value-service",
    # V2 allocation requires passing the allocation_spec argument.
    # The value_allocation is defined in the plugin:
    allocation_spec="value_allocation",
    service_identity="name",
    service_identity_display_name="Name",
)

# Collect all service instances
for assignment in lsm::all(value_binding):
    attributes = assignment["attributes"]

    service = TopLevelService(
        instance_id=assignment["id"],
        entity_binding=value_binding,
        name=attributes["name"],
        top_level_value=attributes["top_level_value"],
        embedded_services=[
            EmbeddedService(
                **embedded_service
            )
            for embedded_service in attributes["embedded_services"]
        ],
    )
end

When moving to V3 allocation, on the model side, call the allocators for the values requiring allocation:

main.cf (V3 allocation)¶

"""
    Inmanta LSM
    :copyright: 2024 Inmanta
    :contact: code@inmanta.com
    :license: Inmanta EULA
"""

import lsm
import lsm::fsm

entity TopLevelService extends lsm::ServiceEntity:
    """
    This service entity demonstrates how a single allocator
    can be used for both a service entity and its embedded
    entities.

    :attr name: The name identifying the service instance.
    :attr top_level_value: A read-only value, automatically assigned by the api.
    """

    string                      name
    lsm::attribute_modifier     name__modifier="rw"
    int?                        top_level_value=null
    lsm::attribute_modifier     top_level_value__modifier="r"
end

# Uniquely identify top level services through their name attribute
index TopLevelService(name)

# Each top level service may have zero or more embedded services attached to it
TopLevelService.embedded_services [0:] -- EmbeddedService


entity EmbeddedService extends lsm::EmbeddedEntity:
    """
    An embedded service, attached to a TopLevelService instance.

    :attr id: Identifier for this embedded service instance.
    :attr embedded_value: A read-only value, automatically assigned by the api.
    """
    string                      id
    lsm::attribute_modifier     id__modifier="rw"
    int?                        embedded_value=null
    lsm::attribute_modifier     embedded_value__modifier="r"
    string[]? __lsm_key_attributes = ["id"]
end

# Uniquely identify embedded services through their id attribute
index EmbeddedService(id)

# Inherit parent entity's implementations
implement TopLevelService using parents

implement EmbeddedService using parents


# Create a binding to enable service creation through the service catalog
top_level_service_binding = lsm::ServiceEntityBindingV2(
    service_entity="allocatorv3_demo::TopLevelService",
    lifecycle=lsm::fsm::simple,
    service_entity_name="top-level-service",
    service_identity="name",
    service_identity_display_name="Name",
)


# Collect all service instances
for assignment in lsm::all(top_level_service_binding):
    attributes = assignment["attributes"]
    service = TopLevelService(
        instance_id=assignment["id"],
        entity_binding=top_level_service_binding,
        name=attributes["name"],
        # Allocator call
        top_level_value=get_value(service, "top_level_value", value=1),
        embedded_services=[
            EmbeddedService(
                id=embedded_service["id"],
                # Allocator call
                embedded_value=get_value(
                    service,
                    lsm::format(
                        "embedded_services[id={id}].embedded_value",
                        args=[],
                        kwargs=embedded_service,
                    ),
                    value=3,
                ),
            )
            for embedded_service in attributes["embedded_services"]
        ],
    )
end

In-depth example¶

This is a more complex example ensuring uniqueness for an attribute across instances within a given range of values: