How to use OpenTofu Exclude (vs Target)

Infrastructure automation is all about efficiency, precision, and risk reduction. As OpenTofu continues to mature as the open-source alternative to Terraform, it's introducing innovative features that address real-world operational challenges. One such feature introduced in OpenTofu 1.9 is the exclusion flag (-exclude), which offers a powerful complement to the traditional target flag approach that infrastructure teams have relied on for years.

The Problem: Targeting's Hidden Complexity

When managing complex infrastructure deployments, there are often scenarios where you need to apply changes to most—but not all—resources in your configuration. Traditionally, engineers have used the -target flag to specify which resources should be included in operations:

# Traditional targeting approach
tofu apply -target=aws_vpc.main -target=aws_subnet.public -target=aws_instance.web

While this works well for smaller infrastructures, it becomes increasingly cumbersome as your infrastructure grows. The target approach requires you to explicitly list every resource you want to include. In large environments with dozens or hundreds of resources, this introduces significant cognitive load and potential for error.

Enter the Exclusion Flag

OpenTofu 1.9 introduced the exclusion flag (-exclude) as a direct response to this challenge. Rather than specifying what to include, you simply specify what to exclude:

# Exclusion approach
tofu apply -exclude=aws_db_instance.main

This seemingly simple inversion creates a dramatic improvement in usability for many common infrastructure management scenarios.

Comparing the Approaches

Let's look at a practical example with a moderate-sized infrastructure:

# Infrastructure definition
provider "aws" {
  region = "us-west-2"
}

# Networking
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "public" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.1.0/24"
}

resource "aws_subnet" "private" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.2.0/24"
}

# Database layer
resource "aws_security_group" "db" {
  name   = "database-sg"
  vpc_id = aws_vpc.main.id
  
  ingress {
    from_port   = 5432
    to_port     = 5432
    protocol    = "tcp"
    cidr_blocks = [aws_subnet.private.cidr_block]
  }
}

resource "aws_db_instance" "main" {
  allocated_storage    = 10
  engine               = "postgres"
  instance_class       = "db.t3.micro"
  vpc_security_group_ids = [aws_security_group.db.id]
  skip_final_snapshot  = true
}

# Application resources
resource "aws_security_group" "app" {
  name   = "app-sg"
  vpc_id = aws_vpc.main.id
  
  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_instance" "app1" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  subnet_id     = aws_subnet.private.id
  vpc_security_group_ids = [aws_security_group.app.id]
}

resource "aws_instance" "app2" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
  subnet_id     = aws_subnet.private.id
  vpc_security_group_ids = [aws_security_group.app.id]
}

resource "aws_lb" "app" {
  name               = "app-lb"
  internal           = false
  load_balancer_type = "application"
  subnets            = [aws_subnet.public.id]
}

Now, imagine you need to apply all changes except those to the database, which is in a maintenance window. Here's how the two approaches compare:

Using target flag:

tofu apply \
  -target=aws_vpc.main \
  -target=aws_subnet.public \
  -target=aws_subnet.private \
  -target=aws_security_group.app \
  -target=aws_instance.app1 \
  -target=aws_instance.app2 \
  -target=aws_lb.app

Using exclusion flag:

tofu apply \
  -exclude=aws_db_instance.main \
  -exclude=aws_security_group.db

The difference is striking. With larger infrastructures spanning multiple modules and services, the benefit becomes even more pronounced.

Understanding Dependency Handling

Both flags respect OpenTofu's resource graph, but they handle dependencies differently:

• Target flag: Automatically includes resources that the targeted resources depend on (upstream dependencies), but not resources that depend on the targeted resources.
• Exclusion flag: Automatically excludes resources that depend on the excluded resources (downstream dependencies), preventing OpenTofu from attempting to create resources that depend on resources that won't be created.

This makes the exclusion flag particularly powerful for working with complex dependency chains. When you exclude a resource, you don't need to worry about identifying and excluding all of its dependents—OpenTofu handles this automatically.

Real-World Scenarios Where Exclusion Shines

1. Disaster Recovery

When you need to rebuild most of your infrastructure but keep certain critical components untouched:

# Rebuild everything except the database during DR
tofu apply -exclude=module.database

2. Staged Deployments

When rolling out changes in phases:

# Deploy everything except the public-facing components
tofu apply -exclude=module.public_endpoints -exclude=aws_lb.frontend

3. Working Around Problem Resources

When certain resources are causing issues but you need to proceed with other changes:

# Apply changes while skipping a resource with provider API issues
tofu apply -exclude=aws_api_gateway_deployment.problematic

4. System Maintenance

When part of your infrastructure is undergoing maintenance:

# Update platform while database maintenance is in progress
tofu apply -exclude=module.database

Target vs. Exclude: When to Use Each

Integrating with IaC Platforms

While these flags provide powerful functionality in OpenTofu's CLI, enterprise users often need more sophisticated controls and guardrails. This is where platforms like Scalr offer significant advantages by providing:

• UI-based resource selection for both target and exclude operations
• Audit logging of selective operations for compliance
• Approval workflows for targeted/excluded operations
• Cross-team visibility into infrastructure changes
• Standardized approaches to common scenarios

By integrating OpenTofu's powerful CLI capabilities with enterprise-grade management platforms, teams can combine the flexibility of these targeting mechanisms with the governance and visibility needed in production environments.

Best Practices

Regardless of which approach you choose, consider these best practices:

1. Always run a plan first to verify the scope of changes
2. Document usage of these flags in commit messages or change logs
3. Use selectively for exceptional circumstances, not routine operations
4. Periodically run full operations to ensure state consistency
5. Consider refactoring large configurations into smaller, manageable units

Conclusion

The introduction of the exclusion flag in OpenTofu 1.9 represents a significant improvement in infrastructure management workflows. For complex environments where selectively skipping resources is more practical than targeting all others, the exclusion flag often provides a simpler, more maintainable solution.

While both approaches have their place in the infrastructure engineer's toolkit, the exclusion flag addresses a long-standing pain point in day-to-day operations. As OpenTofu continues to evolve, features like this that respond directly to community needs demonstrate the value of the open-source model for infrastructure tooling.

Whether you're using OpenTofu directly via CLI or through an enterprise platform like Scalr, understanding when and how to leverage these powerful selective operation flags can significantly improve your infrastructure management capabilities and operational efficiency.