Creating Guardrail Rules

Related Guides and Examples:

Firefly Guardrails are a powerful feature for enforcing policies and best practices within your Infrastructure as Code (IaC) workspaces. By establishing specific rules, Guardrails ensure your Terraform and OpenTofu deployments adhere to organizational standards, preventing non-compliant changes from being applied. Guardrails can block deployments that violate these rules, thereby maintaining the integrity, security, cost-efficiency, and compliance of your cloud infrastructure.

This document provides a comprehensive guide on how to create and configure Guardrail rules in Firefly.

Introduction to Guardrails

Guardrails act as automated checks and balances for your IaC deployments. They provide a way to codify your organization's governance policies and apply them consistently across your workspaces.

Key Benefits of Using Guardrails:

  • Policy Enforcement: Ensure that all deployments comply with security policies, cost management strategies, tagging standards, and resource configuration best practices.

  • Risk Reduction: Prevent accidental or malicious changes that could lead to security vulnerabilities, cost overruns, or operational instability.

  • Compliance: Help meet internal and external regulatory compliance requirements by enforcing specific configurations.

  • Consistency: Maintain a consistent and standardized cloud environment across all projects and teams.

  • Automated Prevention: Block non-compliant deployments before they are applied, saving time and resources on remediation.

Guardrail Rule Types

Firefly offers several types of rules to enforce various policies in your Workspaces. Understanding these types is key to creating effective Guardrails:

  1. Cost Rules:

    • Function: Manage and control cloud costs by setting limits on estimated cost changes resulting from a terraform plan.

    • Use Case: Monitor potential cost increases or decreases and block deployments that exceed a specified monetary amount or percentage threshold.

    • Example: A Cost rule can be set to block any deployment that results in an estimated cost increase of more than $100 or 10% of the current cost.

  2. Policy Rules:

    • Function: Ensure adherence to predefined security, compliance, or operational best practices. These rules leverage a policy engine (like Open Policy Agent - OPA, or built-in Firefly policies) to evaluate the planned changes.

    • Use Case: Verify that planned resources meet specific criteria (e.g., encryption enabled, public access restricted, specific instance types used/disallowed). Prevent deployments that violate these organizational standards.

    • Example: A Policy rule can ensure that all new S3 buckets have server-side encryption enabled. If a deployment attempts to create an S3 bucket without encryption, the Guardrail blocks it.

  3. Resource Rules:

    • Function: Control modifications (create, update, delete, import) to cloud resources based on their type, region, specific address (identifier), or other attributes.

    • Use Case: Block specific actions on certain resources to enforce architectural standards, regional policies, or prevent accidental deletion of critical infrastructure.

    • Example: A Resource rule can prevent the creation of new resources in a restricted region (e.g., us-west-2) or block the deletion of a critical database instance.

  4. Tag Rules:

    • Function: Enforce consistent tagging standards across all your resources. Ensure that resources have required tags, specific tag names, and/or approved tag values.

    • Use Case: Improve resource management, cost allocation, and automation by ensuring all deployed resources are correctly tagged according to organizational policies.

    • Example: A Tag rule can block any deployment where resources are missing a mandatory Environment tag or if the CostCenter tag uses a value not in an approved list. It can also ensure specific tags are present on all resources or specific types of resources.

Creating a New Guardrail Rule: Step-by-Step

Follow the wizard in the Firefly UI to create a new Guardrail rule.

Procedure:

  1. Navigate to Guardrails:

    • In the Firefly UI, select Workflows from the main navigation menu.

    • Then, select the Guardrails tab or sub-section.

  2. Add New Guardrail Rule:

    • Click on the + Add New (or similar, e.g., "Create Rule") button.

  3. Select the Rule Type:

    • Choose one of the available rule types based on the policy you want to enforce:

      • Cost

      • Policy

      • Resource

      • Tag

    • The subsequent configuration options will vary based on the selected rule type.

  4. Enter Rule Name:

    • Provide a clear, descriptive name for your Guardrail rule.

    • Example: Block High Cost Increases, Enforce S3 Encryption, Prevent us-west-2 Deployments, Require Environment Tag.

  5. Configure Violation Behavior: Choose how Firefly should behave when this Guardrail rule is violated:

    • Strict Block:

      • Prevents any override of the violation.

      • If this rule is violated, the deployment is definitively blocked, and cannot proceed unless the underlying IaC or the rule itself is changed to resolve the violation.

      • Use for critical policies where no exceptions are allowed.

    • Flexible Block:

      • Blocks the deployment by default but allows authorized users (with appropriate permissions in Firefly) to override the violation.

      • This provides a balance between enforcement and operational flexibility for exceptional cases.

      • Overrides can be one-time (for the current run only) or permanent (exempting the specific violation instance from future checks for this rule until revoked).

  6. Define the Scope of Your Guardrail: Specify which Workspaces, Repositories, Branches, and Labels this Guardrail rule should apply to. This allows for granular control over where your policies are enforced.

    • Workspaces:

      • Enter specific Workspace names or patterns.

      • Use wildcards (*) to match multiple Workspaces (e.g., prod-*, *-database).

      • Leave blank to apply to all Workspaces by default (within the further constraints of Repository, Branch, etc.).

    • Repositories:

      • Enter specific repository names or patterns (e.g., org/app-*, */*-infra).

      • Use wildcards (*) for matching.

      • Leave blank to apply to all repositories associated with the selected Workspaces.

    • Branches:

      • Enter specific branch names or patterns (e.g., main, features/*, release-*).

      • Use wildcards (*).

      • Leave blank to apply to all branches within the selected repositories/workspaces.

    • Labels:

      • Filter by Workspace labels (key-value pairs).

      • Specify labels that Workspaces must have for this rule to apply (e.g., env:production, compliance:pci).

    Note: The scope acts as a set of AND conditions. A deployment must match all specified scope criteria for the Guardrail rule to be evaluated against it. Usually, if a field is left blank, it means "applies to all" for that specific dimension of the scope.

  7. Define Rule-Specific Criteria: The options here depend on the Rule Type selected in Step 3.

    • For Cost Rules:

      • Trigger Condition: Specify the cost change threshold that, if exceeded, triggers this Guardrail.

        • Choose between an Exact Amount (e.g., $USD) or a Percentage (%).

      • Amount/Percentage Value: Define the actual limit.

        • Example (Amount): 100 (meaning if cost change > $100, block).

        • Example (Percentage): 10 (meaning if cost change > 10%, block).

      • You might also have options to specify if it applies to cost increases, decreases, or both.

    • For Policy Rules:

      • Select Policies to Apply:

        • Choose one or more specific policies from Firefly's policy library (these could be built-in policies or custom policies your organization has defined, possibly based on OPA).

        • Leave blank to apply to all relevant policies (less common, usually you select specific policies).

      • Policies to Exclude (Optional):

        • Select any policies that should be explicitly excluded from this Guardrail rule, even if they match the selection criteria above.

      • Minimum Severity Level:

        • Select the minimum severity level (e.g., Critical, High, Medium, Low) of policy violation that this Guardrail should enforce.

        • For example, if set to High, the Guardrail will only block for policy violations flagged as High or Critical.

    • For Resource Rules: This rule type allows you to block specific actions (create, update, delete, import) based on resource attributes.

      • Actions to Block: Select the actions you want to restrict (e.g., check Create, Delete).

      • Asset Types (Resource Types):

        • Specify the Terraform/OpenTofu resource types this rule applies to (e.g., aws_s3_bucket, google_compute_instance, azurerm_virtual_machine).

        • Use wildcards if supported (e.g., aws_db_*).

        • Leave blank to apply to all resource types (use with caution).

      • Regions:

        • Specify cloud provider regions where these actions on these asset types should be blocked (e.g., us-west-2, eu-central-1).

      • Resource Addresses (Specific Identifiers):

        • Specify particular resource addresses or patterns to target specific instances (e.g., aws_instance.my_critical_server, module.vpc.aws_nat_gateway.this).

      • You may have options to combine these conditions (e.g., block Delete action for aws_db_instance resources in the eu-west-1 region whose names match prod-*).

    • For Tag Rules:

      • Tag Enforcement Type:

        • Block if Missing Any Tags (Tag Missing Entirely): The deployment is blocked if any resource in the plan is missing any tags at all.

        • Block if Specific Tag Name Missing: The deployment is blocked if resources are missing one or more specified tag keys.

        • Block if Specific Tag Value Invalid (Advanced): (This might be part of Policy rules or an advanced Tag rule option) Block if a specific tag key has a value that is not in an approved list.

      • Required Tag Keys (if "Specific Tag Missing" selected):

        • Specify the list of tag keys that must be present on resources.

        • Example: Environment, CostCenter, Owner.

        • Use wildcards (*) if supported for tag key patterns.

      • You might also have options to specify that all resources must have at least one tag, or that specific tags must have specific values (though value validation often falls under Policy rules).

  8. Configure Notifications (Optional): Set up notifications to alert relevant teams or individuals when this Guardrail rule is violated or overridden.

    • Select Notification Destination(s):

      • Choose from available notification channels configured in Firefly (e.g., Slack, Email, PagerDuty, Webhooks).

    • Notification Events: Specify for which events related to this rule you want to send notifications (e.g., on violation, on override).

    • The system will automatically send alerts to the specified channels, ensuring timely visibility into policy enforcement actions.

  9. Review and Save:

    • Carefully review all the configured settings for your Guardrail rule.

    • Ensure the scope, criteria, and violation behavior are correctly defined to achieve your intended policy enforcement.

    • Click Save (or Create, Done) to create and activate the Guardrail rule.

After Creating a Guardrail Rule

  • Activation: The rule becomes active immediately or as per its configuration and will be evaluated against new terraform plan operations that fall within its defined scope.

  • Evaluation: When a terraform plan is executed for a Workspace covered by the Guardrail rule:

    1. Firefly analyzes the plan output.

    2. It checks if the planned changes violate any criteria of applicable Guardrail rules.

  • Guardrails Step in Workflow: If a deployment violates one or more Guardrails:

    • The deployment process in Firefly pauses at a "Guardrails Step" (or similar stage).

    • Firefly displays the specific violations, details of the rules that were checked (both passed and failed), and often provides feedback or remediation guidance.

    • AI-Generated Remediation: Look for a "Tinkerbell" icon (or similar) next to violation messages. Clicking this may provide AI-generated suggestions, explanations, and proposed code changes to fix the violation.

  • Pull Request (PR) Comment: If the deployment is associated with a PR, Firefly usually posts a comment to the PR detailing all Guardrail violations. This informs the development team directly within their VCS workflow.

  • Overrides (for Flexible Block): If the rule's violation behavior is set to "Flexible Block" and a violation occurs:

    • Authorized users will see an option to Override the violation within the Guardrails Step in Firefly.

    • Override Types:

      • One-time Override: Grants an exception for the current pipeline run only. The violation will still be enforced in future deployments unless overridden again.

      • Permanent Override: Exempts this specific instance of the violation from this rule in future deployments. The exception remains unless manually revoked or the Guardrail rule is modified.

    • After applying an override, users can choose to Rerun Pipeline (or proceed with the apply) to continue the deployment.

  • Tracking Overrides: Overridden violations are tracked and visible in:

    • The Guardrails Step for the specific run.

    • PR comments (if applicable).

    • A dedicated section in the Workspace or Guardrail settings (e.g., "Workspace Overridden Violations") where permanent overrides can be reviewed and revoked.

    • Notifications are often sent for override actions if configured.

Managing Guardrail Rules

Once created, you can manage your Guardrail rules:

  • Viewing and Filtering: The Guardrails page lists all configured rules. You can use filters to find specific rules based on:

    • Text Search: Search by rule name or keywords.

    • Creator: Filter by the user who created the rule.

    • Type: Filter by rule type (Policy, Cost, Resource, Tag).

    • Scope: Filter by Labels, Repositories, or Workspaces the rules apply to.

  • Editing: Modify existing rules (name, scope, criteria, behavior, notifications).

  • Deleting: Remove rules that are no longer needed.

  • Disabling/Enabling: Temporarily disable a rule without deleting it.

Examples of Guardrail Rules

Here are some practical examples based on the rule types:

  • Policy Rule Example:

    • Rule Name: Enforce Encryption on All S3 Buckets

    • Rule Type: Policy

    • Violation Behavior: Strict Block

    • Scope: All Workspaces (*)

    • Criteria:

      • Select Policy: S3 Buckets Must Have Server-Side Encryption Enabled (assuming this is a predefined policy in Firefly)

      • Minimum Severity: High

  • Resource Rule Example:

    • Rule Name: Disallow Resource Creation in us-west-2

    • Rule Type: Resource

    • Violation Behavior: Flexible Block

    • Scope: All Workspaces (*) except a specific development Workspace (e.g., by explicitly excluding it or using label-based scope like env:!dev).

    • Criteria:

      • Actions to Block: Create

      • Asset Types: * (all resource types)

      • Regions: us-west-2

  • Tag Rule Example:

    • Rule Name: Ensure Environment Tag on All Compute Instances

    • Rule Type: Tag

    • Violation Behavior: Strict Block

    • Scope: Workspaces with label project:critical-apps

    • Criteria:

      • Tag Enforcement Type: Block if Specific Tag Name Missing

      • Required Tag Keys: Environment

      • (Further criteria could be added to apply this only to compute instance resource types if the Resource Rule criteria can be combined or if Tag rules have Asset Type scope).

  • Cost Rule Example:

    • Rule Name: Limit Development Cost Increases to $50

    • Rule Type: Cost

    • Violation Behavior: Flexible Block

    • Scope: Workspaces with label env:development

    • Criteria:

      • Trigger Condition: Exact Amount

      • Amount Value: 50 (USD)

      • Applies to: Cost Increases

Best Practices for Creating Guardrails

  • Start Small and Iterate: Begin with a few critical Guardrails and gradually expand your rule set as your organization's needs evolve and mature.

  • Be Specific with Scope: Clearly define the scope of each Guardrail to avoid unintended consequences. Use labels and patterns effectively.

  • Use Flexible Block Wisely: While Flexible Block provides operational leeway, ensure that overrides are properly governed and reviewed.

  • Clear Naming Conventions: Use descriptive names for your Guardrail rules so their purpose is easily understood.

  • Regularly Review and Update: Policies and infrastructure change. Periodically review your Guardrail rules to ensure they are still relevant and effective.

  • Involve Stakeholders: Collaborate with security, finance, and operations teams when defining Guardrail rules to ensure they align with overall business objectives.

  • Document Your Guardrails: Maintain internal documentation explaining the purpose and rationale behind each Guardrail rule.

By thoughtfully creating and managing Guardrail rules, you can significantly enhance the security, compliance, and operational stability of your cloud infrastructure deployed via Firefly Workflows.

PreviousCreating WorkflowsNextCodification

Last updated

Was this helpful?