Skip to main content

How to generate configuration artifacts from Jinja2 templates

Generate configuration files and other artifacts by combining Infrahub data with templates. This guide shows you how to create artifacts that automatically update when your infrastructure data changes.

Prerequisites​

Before starting this guide, ensure you have:

  • A working Infrahub instance
  • An existing transformation (either Jinja2 or Python)
  • Access to create and modify schemas
  • A Git repository connected to Infrahub

Step 1: Enable artifact generation for your nodes​

To generate artifacts for specific nodes, modify your schema to inherit from CoreArtifactTarget.

---
version: "1.0"
nodes:
  - name: Device
    namespace: Network
    display_labels:
      - name__value
    inherit_from:
      - CoreArtifactTarget
    attributes:
      - name: name
        kind: Text
        label: Name
        optional: false
        unique: true
      - name: description
        kind: Text
        label: Description
        optional: true

Load the modified schema into Infrahub:

infrahubctl schema load /tmp/schema.yml

Step 2: Create a target group​

Create a Standard Group to define which objects will generate artifacts.

  1. Navigate to the Groups section in the web interface
  2. Create a new Standard Group named DeviceGroup
  3. Add your target devices (switch1, switch2, switch3) as members

For detailed group creation steps, see Creating a group.

Step 3: Define the artifact generation​

Add an artifact definition to your repository's .infrahub.yml file:

artifact_definitions:
  - name: "device_configuration"
    artifact_name: "Device configuration file"
    parameters:
      name: "name__value"
    content_type: "text/plain"
    targets: "DeviceGroup"
    transformation: "device_config_transform"

This configuration specifies:

  • name: Machine identifier (no spaces)
  • artifact_name: Human-readable label
  • parameters: Values passed to the transformation query
  • content_type: MIME type of the generated artifact
  • targets: Group containing target objects
  • transformation: Name of the Jinja2 or Python transformation

For complete .infrahub.yml syntax, see .infrahub.yml reference.

Step 4: Deploy the artifact definition​

Commit and push your changes to activate the artifact generation:

git add .
git commit -m "add device_configuration artifact definition"
git push origin main

The task workers will detect the repository change and create the artifact definition in the database.

Step 5: Verify artifact generation​

Check that your artifacts are being generated correctly.

Through the web interface​

  1. Navigate to Object Management → Artifacts
  2. Locate your generated artifacts in the list

Artifact view

  1. Click on an artifact to view its content

Artifact detail

Through object details​

  1. Navigate to a specific device (for example, switch1)
  2. Select the Artifacts tab
  3. View all artifacts generated for this object

Step 6: Access generated artifacts​

Download or retrieve your artifacts using these methods:

Web interface download​

Click the download button on any artifact detail page.

REST API access​

Download artifacts using the storage object endpoint (authentication required):

curl -H "X-INFRAHUB-KEY: <your-api-token>" \
  http://<INFRAHUB_HOST:INFRAHUB_PORT>/api/storage/object/<storage_identifier>

Copy the Artifact ID from the artifact menu:

Artifact menu

Programmatic access​

Query artifacts through the GraphQL API for automation workflows.

Validation​

Confirm your artifact generation is working:

  • ✓ Artifact definitions appear in the web interface
  • ✓ Artifacts are generated for all group members
  • ✓ Generated content matches your template expectations
  • ✓ Artifacts update when source data changes

Troubleshooting​

If artifacts aren't generating:

  1. Check task worker logs for processing errors
  2. Verify the transformation name matches exactly
  3. Ensure group members inherit from CoreArtifactTarget
  4. Confirm the Git repository sync is working

Next steps​