Просмотр исходного кода

Closes #23723: Add a public render_config() method for devices and virtual machines (#23726)

Jeremy Stretch 2 дней назад
Родитель
Сommit
ab81620adc

+ 40 - 0
docs/plugins/development/config-templates.md

@@ -115,3 +115,43 @@ The returned dict is merged into the template context, so `my_plugin` becomes av
 
 !!! note "No per-render context"
     `get_jinja_context()` receives no arguments — it has no access to the object being rendered or the caller-supplied context. It is intended for plugin-global namespaces (e.g. a lazily-evaluated query helper). Per-object logic belongs in the template itself or in a custom filter.
+
+---
+
+## Rendering Configurations
+
+!!! info "This feature was introduced in NetBox v4.8."
+
+Devices and virtual machines provide two methods for rendering their configuration outside of a web request, for example from a background job, a custom script, or a management command. For the same template and extra context, these produce the same output as the "Render Config" tab in the UI and the `render-config` REST API endpoint.
+
+### `render_config(config_template=None, extra_context=None)`
+
+Renders and returns the object's configuration as text. If `config_template` is not given, the template is resolved from the object, its role, or its platform (in that order). Returns `None` if no template applies. Rendering errors are raised to the caller.
+
+```python
+from dcim.models import Device
+
+device = Device.objects.get(name='router1')
+config = device.render_config(extra_context={'deploy_id': 42})
+```
+
+!!! tip "Rendering many objects"
+    Resolving each object's config template, and computing any config context that isn't cached, can take extra queries per object. When rendering many objects, preload the template relationships and annotate the queryset so that both are fetched in the same query:
+
+    ```python
+    devices = (
+        Device.objects
+        .select_related('config_template', 'role__config_template', 'platform__config_template')
+        .annotate_config_context_data(only_invalidated=True)
+    )
+
+    for device in devices:
+        config = device.render_config()
+    ```
+
+### `get_render_context(extra_context=None)`
+
+Returns the context used to render the object's config template: its [config context](../../features/context-data.md) data, then any extra context, then the object itself under its model name (`device` or `virtualmachine`). The object always takes precedence, so extra context can't replace it.
+
+!!! note "Permissions"
+    Neither method checks permissions. If you render a configuration on behalf of a user, confirm that the user has the `render_config` and `view` permissions for the object, as the UI and REST API do. If you pass a `config_template` the user selected, also confirm that they have `view` permission for that template.

+ 23 - 0
netbox/dcim/models/mixins.py

@@ -30,6 +30,9 @@ __all__ = (
 
 
 class RenderConfigMixin(models.Model):
+    """
+    Enables rendering an object's configuration from a ConfigTemplate. Must be combined with ConfigContextModel.
+    """
     config_template = models.ForeignKey(
         to='extras.ConfigTemplate',
         on_delete=models.PROTECT,
@@ -53,6 +56,26 @@ class RenderConfigMixin(models.Model):
             return self.platform.config_template
         return None
 
+    def get_render_context(self, extra_context=None):
+        """
+        Return the context for rendering this object's config template: its config context data, then any extra
+        context, then the object itself under its model name.
+        """
+        context = self.get_config_context()
+        context.update(extra_context or {})
+        context[self._meta.model_name] = self
+        return context
+
+    def render_config(self, config_template=None, extra_context=None):
+        """
+        Render this object's configuration using the given ConfigTemplate, or the one resolved by
+        get_config_template(). Returns None if no template applies; rendering errors propagate to the caller.
+        """
+        config_template = config_template or self.get_config_template()
+        if config_template is None:
+            return None
+        return config_template.render(context=self.get_render_context(extra_context))
+
 
 class CachedScopeMixin(models.Model):
     """

+ 26 - 0
netbox/dcim/tests/test_api.py

@@ -3200,6 +3200,32 @@ class DeviceTestCase(Mixins.FieldPrefetchMixin, APIViewTestCases.APIViewTestCase
         self.assertHttpStatus(response, status.HTTP_200_OK)
         self.assertEqual(response.data['content'], f'Config for device {device.name}')
 
+    def test_render_config_matches_model(self):
+        """
+        The rendered config returned by the REST API matches the output of Device.render_config().
+        """
+        device = Device.objects.first()
+        device.config_template = ConfigTemplate.objects.create(
+            name='Config Template 1',
+            template_code='hostname {{ device.name }}\nntp server {{ ntp_server }}\nsyslog {{ syslog_server }}\n'
+        )
+        device.local_context_data = {'ntp_server': '192.0.2.1'}
+        device.save()
+
+        self.add_permissions('dcim.render_config_device', 'dcim.view_device')
+        url = reverse('dcim-api:device-render-config', kwargs={'pk': device.pk})
+        data = {'syslog_server': '192.0.2.2', 'device': 'spoofed'}
+        response = self.client.post(url, data, format='json', **self.header)
+        self.assertHttpStatus(response, status.HTTP_200_OK)
+        self.assertEqual(
+            response.data['content'],
+            f'hostname {device.name}\nntp server 192.0.2.1\nsyslog 192.0.2.2'
+        )
+        self.assertEqual(
+            response.data['content'],
+            Device.objects.get(pk=device.pk).render_config(extra_context=data)
+        )
+
     def test_render_config_leaves_config_context_cache_unchanged(self):
         """
         A config template which mutates nested context data leaves the cached config context unchanged.

+ 48 - 1
netbox/dcim/tests/test_models.py

@@ -11,6 +11,7 @@ from django.db.models.signals import post_save
 from django.test import RequestFactory, TestCase, override_settings, tag
 from django.test.utils import CaptureQueriesContext
 from django.utils.text import slugify
+from jinja2 import TemplateSyntaxError
 from netaddr import EUI
 
 from circuits.models import *
@@ -20,7 +21,7 @@ from dcim.choices import *
 from dcim.models import *
 from dcim.utils import resolve_module_placeholder
 from extras.events import serialize_for_event
-from extras.models import CustomField
+from extras.models import ConfigTemplate, CustomField
 from ipam.models import IPAddress, Prefix
 from netbox.choices import DiameterUnitChoices, FlowRateUnitChoices, WeightUnitChoices
 from netbox.context_managers import event_tracking
@@ -1438,6 +1439,52 @@ class DeviceTestCase(TestCase):
         self.assertIn('primary_ip4', cm.exception.message_dict)
 
 
+class DeviceRenderConfigTestCase(TestCase):
+
+    @classmethod
+    def setUpTestData(cls):
+        cls.device = create_test_device('Device 1', local_context_data={'foo': 'context', 'bar': 'context'})
+
+    def test_render_config_without_template(self):
+        self.assertIsNone(self.device.render_config())
+
+    def test_render_config_resolves_template(self):
+        role = self.device.role
+        role.config_template = ConfigTemplate.objects.create(
+            name='Role Template', template_code='Role config for {{ device.name }}'
+        )
+        role.save()
+        self.device.config_template = ConfigTemplate.objects.create(
+            name='Device Template', template_code='Device config for {{ device.name }}'
+        )
+        self.device.save()
+        self.assertEqual(self.device.render_config(), 'Device config for Device 1')
+
+        self.device.config_template = None
+        self.device.save()
+        self.assertEqual(self.device.render_config(), 'Role config for Device 1')
+
+    def test_render_config_with_template_and_extra_context(self):
+        config_template = ConfigTemplate.objects.create(
+            name='Template 1', template_code='{{ device.name }} {{ foo }} {{ bar }} {{ baz }}'
+        )
+        self.assertEqual(
+            self.device.render_config(config_template, extra_context={'bar': 'extra', 'baz': 'extra'}),
+            'Device 1 context extra extra'
+        )
+
+    def test_get_render_context(self):
+        context = self.device.get_render_context({'bar': 'extra', 'device': 'spoofed'})
+        self.assertEqual(context['foo'], 'context')
+        self.assertEqual(context['bar'], 'extra')
+        self.assertEqual(context['device'], self.device)
+
+    def test_render_config_error_propagates(self):
+        config_template = ConfigTemplate.objects.create(name='Template 1', template_code='{{ device.name ')
+        with self.assertRaises(TemplateSyntaxError):
+            self.device.render_config(config_template)
+
+
 class DeviceBayTestCase(TestCase):
 
     @classmethod

+ 18 - 0
netbox/dcim/tests/test_views.py

@@ -3295,6 +3295,24 @@ class DeviceTestCase(ViewTestCases.PrimaryObjectViewTestCase):
         self.remove_permissions('dcim.view_device')
         self.assertHttpStatus(self.client.get(url), 403)
 
+    def test_device_renderconfig_matches_model(self):
+        """
+        The rendered config exported from the UI matches the output of Device.render_config().
+        """
+        device = Device.objects.first()
+        device.config_template = ConfigTemplate.objects.create(
+            name='Test Config Template',
+            template_code='hostname {{ device.name }}\nntp server {{ ntp_server }}\n'
+        )
+        device.local_context_data = {'ntp_server': '192.0.2.1'}
+        device.save()
+
+        self.add_permissions('dcim.view_device', 'dcim.render_config_device')
+        url = reverse('dcim:device_render-config', kwargs={'pk': device.pk})
+        response = self.client.get(url, {'export': 1})
+        self.assertHttpStatus(response, 200)
+        self.assertEqual(response.content.decode(), Device.objects.get(pk=device.pk).render_config())
+
     def test_device_renderconfig_with_config_template_id(self):
         default_template = ConfigTemplate.objects.create(
             name='Default Template',

+ 1 - 3
netbox/extras/api/mixins.py

@@ -141,8 +141,6 @@ class RenderConfigMixin(ConfigTemplateRenderMixin):
                 }, status=HTTP_400_BAD_REQUEST)
 
         # Compile context data
-        context_data = instance.get_config_context()
-        context_data.update({k: v for k, v in request.data.items() if k != 'config_template_id'})
-        context_data.update({object_type: instance})
+        context_data = instance.get_render_context({k: v for k, v in request.data.items() if k != 'config_template_id'})
 
         return self.render_configtemplate(request, configtemplate, context_data)

+ 2 - 2
netbox/extras/models/configs.py

@@ -368,8 +368,8 @@ class ConfigContextModel(models.Model):
         (`_config_context_data`), return a copy of it unless copy_data is False. Otherwise, fall
         back to rendering on demand.
 
-        By default, the returned dict is safe for callers to mutate (e.g. ObjectRenderConfigView merges
-        in additional context with .update()): the cached blob is deep-copied so mutations cannot
+        By default, the returned dict is safe for callers to mutate (e.g. RenderConfigMixin.get_render_context()
+        merges in additional context): the cached blob is deep-copied so mutations cannot
         leak back into this instance's in-memory cache, matching the fresh-dict guarantee of the
         on-demand render path. Read-only callers may pass copy_data=False to skip the copy. The
         cached blob is then returned as is and must not be modified.

+ 5 - 5
netbox/extras/views.py

@@ -1298,14 +1298,14 @@ class ObjectRenderConfigView(generic.ObjectView):
         )
 
     def get_extra_context_data(self, request, instance):
-        return {
-            f'{instance._meta.model_name}': instance,
-        }
+        """
+        Return additional context for rendering the config template. The object itself is always included.
+        """
+        return {}
 
     def get_extra_context(self, request, instance):
         # Compile context data
-        context_data = instance.get_config_context()
-        context_data.update(self.get_extra_context_data(request, instance))
+        context_data = instance.get_render_context(self.get_extra_context_data(request, instance))
 
         # Check for an optional config_template_id override in the query params
         config_template = None

+ 21 - 0
netbox/virtualization/tests/test_models.py

@@ -5,6 +5,7 @@ from django.test import TestCase, tag
 from netaddr import IPNetwork
 
 from dcim.models import Platform, Region, Site, SiteGroup
+from extras.models import ConfigTemplate
 from ipam.models import IPAddress
 from tenancy.models import Tenant
 from utilities.testing import create_test_device, create_test_virtualmachine
@@ -745,3 +746,23 @@ class VirtualMachineTestCase(TestCase):
                 with self.assertRaises(ValidationError) as context:
                     VirtualMachine(name='vm2', cluster=vm.cluster, **{field: ip}).full_clean()
                 self.assertIn(field, context.exception.message_dict)
+
+
+class VirtualMachineRenderConfigTestCase(TestCase):
+
+    def test_render_config(self):
+        vm = create_test_virtualmachine('VM 1')
+        vm.local_context_data = {'foo': 'context'}
+        vm.save()
+        self.assertIsNone(vm.render_config())
+
+        vm.platform = Platform.objects.create(
+            name='Platform 1',
+            slug='platform-1',
+            config_template=ConfigTemplate.objects.create(
+                name='Template 1', template_code='{{ virtualmachine.name }} {{ foo }} {{ bar }}'
+            ),
+        )
+        vm.save()
+        self.assertEqual(vm.render_config(extra_context={'bar': 'extra'}), 'VM 1 context extra')
+        self.assertEqual(vm.get_render_context({'virtualmachine': 'spoofed'})['virtualmachine'], vm)