Add context_template to workflow approval nodes (#578)

* Add context_template to workflow approval nodes for approver visibility

Approval nodes can now include a Jinja2 context_template that gets rendered
with upstream set_stats artifacts when the approval is created. The rendered
result is stored as context_message on the WorkflowApproval instance and
displayed to the approver in the UI detail view and in the pending approval
notification. This lets workflow authors surface relevant context (dry-run
output, planned changes, terraform plan summaries) directly to the person
who needs to approve, without them having to go find the previous job output.

* Harden approval context_template rendering against resource exhaustion

The Jinja2 sandbox blocks attribute escapes but not templates that burn
CPU or memory, so rendering now happens in a short lived forked process
with RLIMIT_CPU and RLIMIT_AS applied, and the task manager abandons and
kills it after a hard timeout instead of blocking the scheduler loop.
The rendered output is capped at 64KB.

Also render with the artifacts passed as a context dict instead of
**kwargs, so set_stats keys that are not valid identifiers cannot raise
TypeError, and allow static templates to render when a node has no
upstream artifacts. Any child process failure is logged and the approval
is simply created without a context message.

Adds functional tests covering rendering, static templates, weird
artifact keys, template errors, the render timeout, the CPU and memory
limits and output truncation.

* Keep context_message out of the workflow approval list serializer

The rendered context can be large, so only the detail endpoint returns
it. The UI detail view already reads it from the detail endpoint. Adds
an API test asserting the field shows up on detail and not on the list.

Author: fernandorocagonzalez

awx/api/serializers.py

@@ -3996,7 +3996,7 @@ class WorkflowApprovalSerializer(UnifiedJobSerializer):
 
     class Meta:
         model = WorkflowApproval
-        fields = ('*', '-controller_node', '-execution_node', 'can_approve_or_deny', 'approval_expiration', 'timed_out')
+        fields = ('*', '-controller_node', '-execution_node', 'can_approve_or_deny', 'approval_expiration', 'timed_out', 'context_message')
 
     def get_approval_expiration(self, obj):
         if obj.status != 'pending' or obj.timeout == 0:
@@ -4033,13 +4033,19 @@ class WorkflowApprovalActivityStreamSerializer(WorkflowApprovalSerializer):
 
 class WorkflowApprovalListSerializer(WorkflowApprovalSerializer, UnifiedJobListSerializer):
     class Meta:
-        fields = ('*', '-controller_node', '-execution_node', 'can_approve_or_deny', 'approval_expiration', 'timed_out')
+        fields = ('*', '-controller_node', '-execution_node', 'can_approve_or_deny', 'approval_expiration', 'timed_out', '-context_message')
+
+    def get_field_names(self, declared_fields, info):
+        field_names = super(WorkflowApprovalListSerializer, self).get_field_names(declared_fields, info)
+        # keep the potentially large rendered context out of list payloads,
+        # the detail view is the one that shows it
+        return tuple(x for x in field_names if x != 'context_message')
 
 
 class WorkflowApprovalTemplateSerializer(UnifiedJobTemplateSerializer):
     class Meta:
         model = WorkflowApprovalTemplate
-        fields = ('*', 'timeout', 'name')
+        fields = ('*', 'timeout', 'name', 'context_template')
 
     def get_related(self, obj):
         res = super(WorkflowApprovalTemplateSerializer, self).get_related(obj)
@@ -4365,7 +4371,7 @@ def build_relational_field(self, field_name, relation_info):
 class WorkflowJobTemplateNodeCreateApprovalSerializer(BaseSerializer):
     class Meta:
         model = WorkflowApprovalTemplate
-        fields = ('timeout', 'name', 'description')
+        fields = ('timeout', 'name', 'description', 'context_template')
 
     def to_representation(self, obj):
         return {}

awx/main/migrations/0205_approval_context_template.py

@@ -0,0 +1,35 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('main', '0204_job_slice_pinned_hosts'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='workflowapprovaltemplate',
+            name='context_template',
+            field=models.TextField(
+                blank=True,
+                default='',
+                help_text=(
+                    "A Jinja2 template rendered with upstream set_stats artifacts when the approval is created. "
+                    "The result is stored on the approval as context_message and shown to the approver."
+                ),
+            ),
+        ),
+        migrations.AddField(
+            model_name='workflowapproval',
+            name='context_message',
+            field=models.TextField(
+                blank=True,
+                default='',
+                help_text=(
+                    "The rendered context from the approval template's context_template, "
+                    "populated with upstream set_stats artifacts when the approval is created."
+                ),
+            ),
+        ),
+    ]

awx/main/models/workflow.py

@@ -4,6 +4,7 @@
 # Python
 import json
 import logging
+import multiprocessing
 from uuid import uuid4
 from copy import copy
 from urllib.parse import urljoin
@@ -1115,6 +1116,7 @@ class WorkflowApprovalTemplate(UnifiedJobTemplate, RelatedJobsMixin):
     FIELDS_TO_PRESERVE_AT_COPY = [
         'description',
         'timeout',
+        'context_template',
     ]
 
     class Meta:
@@ -1125,6 +1127,14 @@ class Meta:
         default=0,
         help_text=_("The amount of time (in seconds) before the approval node expires and fails."),
     )
+    context_template = models.TextField(
+        blank=True,
+        default='',
+        help_text=_(
+            "A Jinja2 template rendered with upstream set_stats artifacts when the approval is created. "
+            "The result is stored on the approval as context_message and shown to the approver."
+        ),
+    )
 
     @classmethod
     def _get_unified_job_class(cls):
@@ -1149,6 +1159,33 @@ def _get_related_jobs(self):
         return UnifiedJob.objects.filter(unified_job_template=self)
 
 
+# context_template is user-supplied Jinja2. The sandbox stops attribute escapes but
+# not resource exhaustion (e.g. {{ "x" * 10**9 }}, {{ 10 ** 10 ** 10 }} or a huge
+# loop), so rendering happens in a disposable forked process with CPU and memory
+# limits, and the parent abandons it after a hard timeout.
+CONTEXT_TEMPLATE_TIMEOUT = 10  # seconds
+CONTEXT_TEMPLATE_MEMORY_LIMIT = 256 * 1024 * 1024  # address space the render may allocate beyond what is already in use
+CONTEXT_MESSAGE_MAX_LENGTH = 65536
+
+
+def _render_context_template(conn, template_str, variables):
+    """Runs in a forked child process; must never touch the database and only
+    reports back through conn. The parent kills it if it outlives the timeout."""
+    try:
+        import resource
+
+        current = int(open('/proc/self/statm').read().split()[0]) * resource.getpagesize()
+        resource.setrlimit(resource.RLIMIT_AS, (current + CONTEXT_TEMPLATE_MEMORY_LIMIT, current + CONTEXT_TEMPLATE_MEMORY_LIMIT))
+        resource.setrlimit(resource.RLIMIT_CPU, (CONTEXT_TEMPLATE_TIMEOUT, CONTEXT_TEMPLATE_TIMEOUT))
+    except Exception:
+        pass  # limits are best effort, the parent still enforces the timeout
+    try:
+        rendered = sandbox.ImmutableSandboxedEnvironment().from_string(template_str).render(variables)
+        conn.send(('ok', rendered[:CONTEXT_MESSAGE_MAX_LENGTH]))
+    except Exception as e:
+        conn.send(('error', '{}: {}'.format(type(e).__name__, e)[:1024]))
+
+
 class WorkflowApproval(UnifiedJob, JobNotificationMixin):
     class Meta:
         app_label = 'main'
@@ -1181,6 +1218,13 @@ class Meta:
         editable=False,
         on_delete=models.SET_NULL,
     )
+    context_message = models.TextField(
+        blank=True,
+        default='',
+        help_text=_(
+            "The rendered context from the approval template's context_template, populated with upstream set_stats artifacts when the approval is created."
+        ),
+    )
 
     def _set_default_dependencies_processed(self):
         self.dependencies_processed = True
@@ -1202,6 +1246,40 @@ def get_ui_url(self):
     def _get_parent_field_name(self):
         return 'workflow_approval_template'
 
+    def render_context_message(self, ancestor_artifacts):
+        template_str = getattr(self.workflow_approval_template, 'context_template', '')
+        if not template_str:
+            return
+        rendered = None
+        ctx = multiprocessing.get_context('fork')
+        parent_conn, child_conn = ctx.Pipe(duplex=False)
+        worker = ctx.Process(target=_render_context_template, args=(child_conn, template_str, dict(ancestor_artifacts or {})))
+        try:
+            worker.start()
+            child_conn.close()
+            if parent_conn.poll(CONTEXT_TEMPLATE_TIMEOUT):
+                status, payload = parent_conn.recv()
+                if status == 'ok':
+                    rendered = payload
+                else:
+                    logger.warning('Failed to render context_template for approval %s: %s', self.pk, payload)
+            else:
+                logger.warning('Rendering context_template for approval %s did not finish within %s seconds', self.pk, CONTEXT_TEMPLATE_TIMEOUT)
+        except EOFError:
+            logger.warning('Rendering context_template for approval %s exited without producing output', self.pk)
+        except Exception:
+            logger.exception('Unexpected error rendering context_template for approval %s', self.pk)
+        finally:
+            parent_conn.close()
+            if worker.pid is not None:
+                worker.join(1)
+                if worker.is_alive():
+                    worker.kill()
+                    worker.join()
+        if rendered and rendered.strip():
+            self.context_message = rendered
+            self.save(update_fields=['context_message'])
+
     def save(self, *args, **kwargs):
         update_fields = list(kwargs.get('update_fields', []))
         if self.timeout != 0 and ((not self.pk) or (not update_fields) or ('timeout' in update_fields)):
@@ -1319,12 +1397,15 @@ def build_approval_notification_message(self, nt, approval_status):
 
     def context(self, approval_status):
         workflow_url = urljoin(settings.TOWER_URL_BASE, '/#/jobs/workflow/{}'.format(self.workflow_job.id))
-        return {
+        ctx = {
             'approval_status': approval_status,
             'approval_node_name': self.workflow_approval_template.name,
             'workflow_url': workflow_url,
             'job_metadata': json.dumps(self.notification_data(), indent=4),
         }
+        if self.context_message:
+            ctx['context_message'] = self.context_message
+        return ctx
 
     @property
     def workflow_job_template(self):

awx/main/notifications/custom_notification_base.py

@@ -9,7 +9,9 @@ class CustomNotificationBase(object):
 
     DEFAULT_APPROVAL_RUNNING_MSG = 'The approval node "{{ approval_node_name }}" needs review. This node can be viewed at: {{ workflow_url }}'
     DEFAULT_APPROVAL_RUNNING_BODY = (
-        'The approval node "{{ approval_node_name }}" needs review. This approval node can be viewed at: {{ workflow_url }}\n\n{{ job_metadata }}'
+        'The approval node "{{ approval_node_name }}" needs review. This approval node can be viewed at: {{ workflow_url }}'
+        '{% if context_message %}\n\nContext:\n{{ context_message }}{% endif %}'
+        '\n\n{{ job_metadata }}'
     )
 
     DEFAULT_APPROVAL_APPROVED_MSG = 'The approval node "{{ approval_node_name }}" was approved. {{ workflow_url }}'

awx/main/scheduler/task_manager.py

@@ -234,6 +234,8 @@ def spawn_workflow_graph_jobs(self):
                     if is_retry:
                         spawn_node.retry_attempts += 1
                     spawn_node.save()
+                    if isinstance(job, WorkflowApproval):
+                        job.render_context_message(spawn_node.ancestor_artifacts)
                     if is_retry:
                         # keep the superseded attempt linked to the node so it stays
                         # protected from deletion and traceable to this workflow

awx/main/tests/functional/api/test_workflow_node.py

@@ -243,6 +243,17 @@ def test_approval_node_cleanup(self, post, approval_node, admin_user, get):
         assert WorkflowApprovalTemplate.objects.count() == 0
         get(url, admin_user, expect=404)
 
+    def test_approval_context_message_detail_only(self, get, admin_user):
+        # context_message can be large, so the list endpoint leaves it out
+        # and only the detail endpoint exposes it
+        template = WorkflowApprovalTemplate.objects.create(name='approve deploy', timeout=0)
+        approval = WorkflowApproval.objects.create(workflow_approval_template=template, context_message='terraform plan output')
+        detail = get(reverse('api:workflow_approval_detail', kwargs={'pk': approval.pk}), user=admin_user, expect=200)
+        assert detail.data['context_message'] == 'terraform plan output'
+        listed = get(reverse('api:workflow_approval_list'), user=admin_user, expect=200)
+        assert listed.data['count'] == 1
+        assert 'context_message' not in listed.data['results'][0]
+
     def test_changed_approval_deletion(self, post, approval_node, admin_user, workflow_job_template, job_template):
         # This test verifies that when an approval node changes into something else
         # (in this case, a job template), then the previously-set WorkflowApprovalTemplate

awx/main/tests/functional/models/test_workflow.py

@@ -4,7 +4,10 @@
 import json
 
 # AWX
+from awx.main.models import workflow as workflow_models
 from awx.main.models.workflow import (
+    WorkflowApproval,
+    WorkflowApprovalTemplate,
     WorkflowJob,
     WorkflowJobNode,
     WorkflowJobTemplateNode,
@@ -945,3 +948,47 @@ def test_bad_data_with_artifacts(self, organization):
         WorkflowJobNode.objects.create(workflow_job=wfj, job=job)
         # mostly, we just care that this assertion finishes in finite time
         assert wfj.get_effective_artifacts() == {'foo': 'bar'}
+
+
+@pytest.mark.django_db
+class TestApprovalContextMessage:
+    @pytest.fixture
+    def approval(self):
+        template = WorkflowApprovalTemplate.objects.create(name='approve deploy', timeout=0)
+        return WorkflowApproval.objects.create(workflow_approval_template=template)
+
+    def _render(self, approval, template_str, artifacts):
+        approval.workflow_approval_template.context_template = template_str
+        approval.render_context_message(artifacts)
+        approval.refresh_from_db()
+        return approval.context_message
+
+    def test_renders_ancestor_artifacts(self, approval):
+        assert self._render(approval, 'plan: {{ plan_output }}', {'plan_output': '2 to add'}) == 'plan: 2 to add'
+
+    def test_static_template_without_artifacts(self, approval):
+        assert self._render(approval, 'review the plan attached to the ticket', None) == 'review the plan attached to the ticket'
+
+    def test_non_identifier_artifact_keys(self, approval):
+        # set_stats keys are arbitrary strings, they must not break rendering
+        assert self._render(approval, '{{ ok }}', {'not-an-identifier!': 1, 'ok': 'yes'}) == 'yes'
+
+    def test_template_error_does_not_raise(self, approval):
+        assert self._render(approval, '{% if %}', {'x': 1}) == ''
+
+    def test_render_timeout(self, approval, monkeypatch):
+        # the sandbox caps a single range() at MAX_RANGE, so burn CPU with nested loops
+        monkeypatch.setattr(workflow_models, 'CONTEXT_TEMPLATE_TIMEOUT', 1)
+        assert self._render(approval, '{% for i in range(100000) %}{% for j in range(100000) %}{% endfor %}{% endfor %}', {}) == ''
+
+    def test_render_cpu_limit(self, approval, monkeypatch):
+        # huge exponent gets the render process killed by its rlimits before it can reply
+        monkeypatch.setattr(workflow_models, 'CONTEXT_TEMPLATE_TIMEOUT', 1)
+        assert self._render(approval, '{{ 10 ** (10 ** 10) }}', {}) == ''
+
+    def test_render_memory_limit(self, approval):
+        assert self._render(approval, '{{ "x" * 999999999 }}', {}) == ''
+
+    def test_output_truncated(self, approval):
+        rendered = self._render(approval, '{{ "x" * 100000 }}', {})
+        assert len(rendered) == workflow_models.CONTEXT_MESSAGE_MAX_LENGTH

awx/ui/src/screens/Template/WorkflowJobTemplateVisualizer/Modals/NodeModals/NodeAddModal.js

@@ -70,6 +70,7 @@ function NodeAddModal() {
         description: approvalDescription,
         name: approvalName,
         timeout: Number(timeoutMinutes) * 60 + Number(timeoutSeconds),
+        context_template: values.contextTemplate || '',
         type: 'workflow_approval_template',
       };
     } else {

awx/ui/src/screens/Template/WorkflowJobTemplateVisualizer/Modals/NodeModals/NodeEditModal.js

@@ -37,6 +37,7 @@ function NodeEditModal() {
           description: approvalDescription,
           name: approvalName,
           timeout: Number(timeoutMinutes) * 60 + Number(timeoutSeconds),
+          context_template: values.contextTemplate || '',
           type: 'workflow_approval_template',
         },
         identifier,

awx/ui/src/screens/Template/WorkflowJobTemplateVisualizer/Modals/NodeModals/NodeModal.js

@@ -133,6 +133,7 @@ function NodeModalForm({
       delete values.approvalDescription;
       delete values.timeoutMinutes;
       delete values.timeoutSeconds;
+      delete values.contextTemplate;
     }
 
     if (
@@ -410,6 +411,7 @@ const NodeModal = ({ onSave, askLinkType, title }) => {
       initialValues={{
         approvalName: '',
         approvalDescription: '',
+        contextTemplate: '',
         daysToKeep: 30,
         identifier: nodeToEdit?.identifier || '',
         timeoutMinutes: 0,