DEV Community: John Reilly Pospos (JP)

The Curious Case of Terraform Workspaces

John Reilly Pospos (JP) — Wed, 12 Nov 2025 00:57:40 +0000

Why everyone thinks Terraform workspaces are bad, what the docs actually say, and how to use them properly. This is NOT a 'workspaces are supreme, use them for everything' post.

Introduction

A master programmer was asked: “What makes code elegant?” He replied: “When you remove what is not essential, what remains is truth.”

If you’ve spent any time in the Terraform community, you’ve likely encountered the heated debate around workspaces. Many developers read HashiCorp’s documentation and immediately conclude that Terraform workspaces should be avoided. But is this really what the documentation says? Or have we collectively misunderstood the nuanced guidance HashiCorp provides?

I used to be in the “workspaces are evil” camp myself. I’d built wrappers, used off-the-shelf abstraction layers, anything to avoid workspaces. Then I started working with larger teams and more complex deployments, and I began to see a different perspective. What if the guidance isn’t “never use workspaces,” but something more nuanced?

Sometimes the simplest solution is right in front of you.

Based on my experience and interpretation of the documentation, let’s dive deep into what Terraform workspaces actually are, what the documentation really says, and how to use them effectively as part of a broader infrastructure-as-code strategy that includes proper system decomposition and environment management.

Key Concepts

The ancient Unix wisdom teaches: “Understand your abstractions, or they will abstract you.”

Before we dive into the workspace debate, let’s establish a crucial concept that’s central to understanding the proper use of workspaces: composition layers.

Composition layers are logical groupings of related infrastructure components that naturally belong together and share similar lifecycle characteristics. They represent the fundamental architectural boundaries in your infrastructure-as-code approach.

Examples of composition layers include:

Network layer: VPCs, subnets, routing tables, NAT gateways, security groups
Storage layer: RDS databases, S3 buckets, EFS file systems, backup policies
Compute layer: EC2 instances, Auto Scaling groups, Load Balancers
Application layer: Specific applications or services with their dependencies

The key principle is that components within a composition layer typically:

Change at similar frequencies and for similar reasons
Have similar operational requirements and ownership
Share blast radius considerations (if one breaks, what else might be affected?)
Benefit from being deployed and managed together

For example, your VPC structure rarely changes, but your application deployments happen frequently. These belong in separate composition layers because they have different lifecycle needs.

This architectural pattern directly addresses many of the concerns raised about Terraform workspaces, as we’ll see throughout this post.

The Great Misunderstanding

A novice asked the master: “I have read the first page of the manual. Am I now wise?” The master replied: “A man who stops reading after the first page will spend his life debugging the last page.”

The infamous documentation section that causes so much confusion states:

“Important: Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to Use Cases in the Terraform CLI documentation for details and recommended alternatives.”

Many readers stop here and declare workspaces off-limits. But this interpretation might be missing some context. One way to read this is as guidance to not use workspaces as your only strategy for managing complex multi-environment deployments.

The community’s concerns about workspaces are valid. System decomposition, credential isolation, and blast radius control are critical challenges. The question is whether workspaces can be part of the solution when these other concerns are properly addressed.

But here’s what the docs actually recommend workspaces for:

“Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches.”

So which is it? Are workspaces problematic or convenient?

What Terraform Workspaces Actually Are

A student asked: “What is a workspace?” The master replied: “The same house with different keys to different rooms.”

At their core, Terraform workspaces are simply a way to manage multiple state files within a single configuration.

According to the official documentation:

“The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration.”

The important distinction is that workspaces let you switch between different states within the same configuration. You’re not duplicating your Terraform configuration files. Instead, you get isolated state contexts that all use the same infrastructure code, allowing you to deploy the same configuration to different environments or test different variations safely.

For example, within your network composition layer, you might have:

network-prod workspace (production VPC and subnets)
network-dev workspace (smaller dev environment VPC)
network-feature-zones workspace (testing additional availability zones)

All use the same Terraform configuration, but maintain completely separate state files.

They’re a built-in feature that allows you to:

Switch between different states using terraform workspace select- Maintain separate state files for the same composition layer configuration
Reference the current workspace name in your configuration using ${terraform.workspace}
Deploy multiple instances of the same composition layer safely

That’s it. No magic, no complex orchestration, no additional code to maintain. Just state file management with a convenient logical interface within composition layer boundaries. So why do so many developers avoid this simple, built-in feature?

The Statements That Scare People Away

An infrastructure architect reflected: “Tools are not good or bad. They are appropriate or inappropriate. Wisdom lies in knowing the difference.”

Now that we understand that workspaces actually manage multiple states within a composition layer, let’s examine what the documentation says about their appropriate usage.

Here are the statements that cause the most concern:

“Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls.”

“CLI workspaces use the same backend, so they are not a suitable isolation mechanism for this scenario.”

“Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend.”

“Workspaces can be helpful for specific use cases, but they are not required to use the Terraform CLI. We recommend using alternative approaches for complex deployments requiring separate credentials and access controls.”

“Instead of creating CLI workspaces, you can use one or more re-usable modules to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different backend.”

These are all valid concerns. System decomposition, credential isolation, team boundaries, deployment complexity, and code reusability are critical challenges in infrastructure management. The crucial point is that these are concerns that workspaces are NOT meant to solve!

There are other mechanisms to address these challenges. These include separate backends, different IAM roles, composition layer boundaries, reusable modules, remote state data sources, and orchestration tools. The question then becomes: what does the documentation actually recommend as the complete solution?

What The Documentation Actually Recommends

A student complained: “These tools are so complex!” The Unix master replied: “Complexity is what happens when you refuse to understand simplicity.”

Here’s what many people miss: the documentation doesn’t just tell you what workspaces aren’t good for, it also describes what you should do instead. When you read these statements together, they outline a complete architectural approach.

The documentation’s recommended approach includes:

System decomposition FIRST: Break infrastructure into logical composition layers with separate configurations
Separate backends: Use different backends for proper team and component isolation
Reusable modules: Create common patterns to avoid code duplication
Component communication: Use “paired resources and data sources” for composition layers to communicate
Alternative deployment strategies: Consider separate configurations over workspace-only approaches

The critical insight is in this statement:

“Instead of creating CLI workspaces, you can use one or more re-usable modules to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different backend.”

This isn’t saying “never use workspaces.” It’s describing the complete architecture that addresses all the concerns raised. The question becomes: where do workspaces fit within this recommended architecture?

The answer: Workspaces work safely within each properly isolated composition layer for managing different environments or feature branches of that same layer, once you have the proper foundation in place.

This interpretation suggests the documentation is actually describing a comprehensive approach where workspaces have their proper place as part of the solution, not as the entire solution.

Now let’s walk through how to implement this complete approach:

Building The Recommended Architecture

Step 1: System Decomposition FIRST

The wise system builder said: “First, architect your components. Then, let the tools serve the architecture. Never let tools dictate the architecture.”

The documentation emphasizes that workspaces are not appropriate for system decomposition, so this is where we address that concern before workspaces even come into play.

The first step is breaking your infrastructure into logical composition layers that make sense for your context. This could be based on your organization’s responsibility model, blast radius control, lifecycle velocities, or whatever boundaries work best for your team.

Note: Consider separating storage and stateful resources from compute and networking. Persistent resources like RDS databases, S3 buckets, and EFS file systems often have different lifecycle needs. They tend to change less frequently, require careful migration strategies, and often need to persist even when applications are rebuilt. You may find that mixing them with faster-changing compute resources creates operational complexity.

Option 1: Co-located Structure

infrastructure/
├── network/                        # Could be its own repo
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── dev.tfvars
│   ├── staging.tfvars
│   └── prod.tfvars
├── storage/                        # Could be its own repo
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── dev.tfvars
│   ├── staging.tfvars
│   └── prod.tfvars
└── workload-a/                     # Could be its own repo
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── dev.tfvars
    ├── staging.tfvars
    └── prod.tfvars

Option 2: Centralized Config Structure

infrastructure/
├── composition-layers/
│   ├── network/                    # Could be its own repo
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   ├── storage/                    # Could be its own repo
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── workload-a/                 # Could be its own repo
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── config/
    ├── network/
    │   ├── dev.tfvars
    │   ├── staging.tfvars
    │   └── prod.tfvars
    ├── storage/
    │   ├── dev.tfvars
    │   ├── staging.tfvars
    │   └── prod.tfvars
    └── workload-a/
        ├── dev.tfvars
        ├── staging.tfvars
        └── prod.tfvars

Option 3: Local Config Structure

infrastructure/
├── network/                        # Could be its own repo
│   ├── terraform/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── config/
│       ├── dev.tfvars
│       ├── staging.tfvars
│       └── prod.tfvars
├── storage/                        # Could be its own repo
│   ├── terraform/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── config/
│       ├── dev.tfvars
│       ├── staging.tfvars
│       └── prod.tfvars
└── workload-a/                     # Could be its own repo
    ├── terraform/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── config/
        ├── dev.tfvars
        ├── staging.tfvars
        └── prod.tfvars

This decomposition directly addresses the workspace concerns we discussed earlier. By properly separating composition layers, you get:

System decomposition solved: Each composition layer has clear boundaries and responsibilities
Credential isolation ready: Different teams can manage different composition layers with separate access controls
Blast radius control: Changes to workload-a don’t risk breaking the network or corrupting databases
Independent deployment cycles: Each composition layer can be deployed separately based on its change frequency
State isolation: Each composition layer has its own state file, preventing accidental dependencies
Operational safety: You can rebuild applications without touching persistent data stores
Team boundaries: The network team manages network/, the storage team manages storage/

Note: Infrastructure shifts and ebbs like the Sahara. You will be buried in sand if you stand still. What works for a 5-person startup won’t work for a 500-person enterprise. Be prepared to evolve your structure as your team and infrastructure mature.

This decomposition addresses the fundamental workspace concerns by establishing proper architectural boundaries. With these foundations in place, we can now add secure credential isolation.

Step 2: Separate Backends for Team Isolation

A security engineer asked: “How do I know my access controls work?” The master replied: “When teams work in one garden - each tends their own plot, but all may harvest what grows well.”

The documentation states that “CLI workspaces use the same backend, so they are not a suitable isolation mechanism” for team separation. This is where our composition layer approach directly addresses the concern.

The advantage of our system decomposition is that since we’ve properly separated our infrastructure into distinct composition layers, we naturally gain the capability for credential isolation, regardless of whether we use workspaces or not. Each composition layer can have its own dedicated backend with different IAM roles and access controls.

Network Composition Layer Backend:

# network/backend.tf
terraform {
  backend "s3" {
    bucket       = "mycompany-terraform-network-state"  # Dedicated bucket for network composition layer
    key          = "terraform.tfstate"
    region       = "us-east-1"
    encrypt      = true
    use_lockfile = true                                  # State locking via S3 object locking

    assume_role {
      role_arn = "arn:aws:iam::123456789012:role/NetworkTeamRole"  # Only network team has access
    }
  }
}

Application Composition Layer Backend:

# workload-a/backend.tf  
terraform {
  backend "s3" {
    bucket       = "mycompany-terraform-workload-a-state"  # Dedicated bucket for workload-a composition layer
    key          = "terraform.tfstate"
    region       = "us-east-1"
    encrypt      = true
    use_lockfile = true                                      # State locking via S3 object locking

    assume_role {
      role_arn = "arn:aws:iam::123456789012:role/AppTeamRole"  # Only app team has access
    }
  }
}

Now each team has proper credential isolation with dedicated backends and credentials. The network team can’t access the application team’s state, and vice versa. This is where workspaces become safe and appropriate. They work within each properly isolated composition layer.

Advanced Security: Composition Layer + Environment Isolation

For maximum security (perfect for highly regulated environments), you can use dedicated backends per composition layer AND environment-specific access policies:

Network Composition Layer Bucket Policy (on mycompany-terraform-network-state):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "NetworkDevTeamAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/NetworkDevRole"
      },
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::mycompany-terraform-network-state/*"
      ],
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "terraform.tfstate",
            "env:/network-dev/*",
            "env:/network-feature-*/*"
          ]
        }
      }
    },
    {
      "Sid": "NetworkProdTeamAccess", 
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/NetworkProdRole"
      },
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::mycompany-terraform-network-state/*"
      ],
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "env:/network-prod/*"
          ]
        }
      }
    }
  ]
}

Application Composition Layer Bucket Policy (on mycompany-terraform-workload-a-state):

{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Sid": "AppTeamAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/AppTeamRole"
      },
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::mycompany-terraform-workload-a-state/*"
      ]
    }
  ]
}

This gives you multiple security layers:

Backend-level isolation - Network team can’t even see app team’s backend
Environment-level restrictions - Dev team can’t touch prod state files
Composition layer boundaries - Complete separation between infrastructure composition layers
Workspace safety - Feature branches are isolated within appropriate environments

Note: This example uses the S3 backend with IAM role-based isolation within a single AWS account, which is common for self-managed Terraform. For even stronger isolation, many organizations prefer separate AWS accounts for different environments or teams, providing complete billing, resource, and access boundaries. If you’re using HCP Terraform with the remote backend, workspace configuration works differently. In that case, you would use workspaces.prefix to map CLI workspaces to remote workspaces. For example, prefix = "network-" maps terraform workspace select prod to the network-prod remote workspace.

With secure backend isolation established, we’ve addressed the credential separation concern. Now we can ensure our composition layers don’t become repetitive code maintenance burdens.

Step 3: Reusable Modules

The DRY principle master said: “Write once, use many times. But abstract wrongly, debug infinite times.”

The documentation recommends using “one or more re-usable modules to represent the common elements” as part of the complete solution. This addresses the code duplication concern while working alongside our composition layer architecture.

This approach isn’t replacing workspaces; it’s providing the reusable foundation that makes workspaces safe and effective within each composition layer.

Modules provide reusable infrastructure patterns within our composition layer architecture. They work alongside the foundation we’ve built, not competing with it, but making it more maintainable. Here’s how:

VPC Module Example:

# modules/vpc/main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = var.enable_dns_hostnames
  enable_dns_support   = var.enable_dns_support

  tags = merge(var.tags, {
    Name = "${var.name_prefix}-vpc"
  })
}

variable "name_prefix" {
  description = "Prefix for resource names"
  type        = string
}

This module encapsulates VPC creation with configurable parameters. It’s reusable across different composition layers and environments without duplicating code.

Using the Module:

# network/main.tf
module "vpc" {
  source = "../modules/vpc"

  vpc_cidr             = var.vpc_cidr
  name_prefix          = var.environment
  enable_dns_hostnames = var.enable_dns_hostnames

  tags = var.tags
}

The network composition layer uses this module, passing in environment-specific values. The same module can be used across different composition layers or environments with different configurations.

With reusable modules in place, we’ve eliminated code duplication while maintaining our composition layer boundaries. Now we can address how these separate layers communicate with each other.

Step 4: Composition Layer Communication

The distributed systems sage declared: “Loose coupling with high cohesion: this is the way of maintainable systems.”

The documentation provides specific guidance on how separate composition layers should communicate: “When multiple configurations represent distinct system components rather than multiple deployments, you can pass data from one component to another using paired resources types and data sources.”

This directly addresses our need to connect our distinct composition layers. Here’s how the recommended “paired resources and data sources” pattern works:

Approach 1: Paired Resource Outputs and Remote State Data Sources

Network component exposes data via resource outputs:

# network/outputs.tf
output "vpc_id" {
  value = module.vpc.vpc_id
}

output "private_subnet_ids" {
  value = module.vpc.private_subnet_ids
}

Application component consumes data via terraform_remote_state data source:

# workload-a/main.tf
data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "mycompany-terraform-network-state"
    key    = "terraform.tfstate"
    region = "us-east-1"

    assume_role {
      role_arn = "arn:aws:iam::123456789012:role/NetworkTeamRole"
    }
  }
}

resource "aws_instance" "app" {
  ami               = data.aws_ami.amazon_linux.id
  instance_type     = var.instance_type
  subnet_id         = data.terraform_remote_state.network.outputs.private_subnet_ids[0]
  availability_zone = data.aws_availability_zones.available.names[0]
}

Approach 2: Paired Resource Tags and Named Data Sources

# workload-a/main.tf
# Instead of remote state, use data sources to discover resources
data "aws_vpc" "main" {
  filter {
    name   = "tag:Name"
    values = ["${var.environment}-vpc"]
  }
}

data "aws_subnets" "private" {
  filter {
    name   = "vpc-id"
    values = [data.aws_vpc.main.id]
  }

  filter {
    name   = "tag:Type"
    values = ["private"]
  }
}

resource "aws_instance" "app" {
  ami               = data.aws_ami.amazon_linux.id
  instance_type     = var.instance_type
  subnet_id         = data.aws_subnets.private.ids[0]
  availability_zone = data.aws_availability_zones.available.names[0]
}

Both approaches implement the “paired resources and data sources” pattern the documentation describes:

Approach 1: Explicit pairing through outputs and remote state creates clear dependencies
Approach 2: Implicit pairing through resource tags and named data sources provides looser coupling

Both maintain composition layer boundaries while enabling the necessary communication between distinct system components.

With composition layer communication established, we have the complete foundation in place. Now we can finally show where workspaces fit within this properly architected system.

Step 5: Where Workspaces Finally Fit

A configuration management wizard observed: “The same code in different environments should behave predictably different.”

Now that we have the complete foundation in place, we can finally show workspaces in their proper context. Remember the documentation’s guidance: workspaces are for creating “a parallel, distinct copy of a set of infrastructure in order to test a set of changes before modifying the main production infrastructure.”

Within each properly isolated composition layer, workspaces provide exactly that. They offer a safe way to test variations. To handle environment-specific configuration differences, tfvars files provide the solution. This combination gives you a clean separation between your infrastructure code and environment-specific configuration.

Why tfvars + workspaces work so well together:

Same code, different configs: Workspaces let you deploy identical Terraform code with different configurations
Environment isolation: Each workspace gets its own state, but can use different tfvars for sizing, features, and settings
Configuration outside code: tfvars keep environment-specific details out of your .tf files, making them truly reusable
Safe testing: Feature workspaces can use dev.tfvars for smaller, cheaper resources while prod uses prod.tfvars
Clean workflows: Switch workspace, apply with appropriate tfvars for simple and predictable operations

Here’s how this elegant combination works in practice:

Environment-Specific tfvars:

# workload-a/config/dev.tfvars
environment = "dev"
instance_type = "t3.micro"
min_capacity = 1
max_capacity = 2
enable_monitoring = false

# workload-a/config/prod.tfvars  
environment = "prod"
instance_type = "t3.large"
min_capacity = 3
max_capacity = 10
enable_monitoring = true

Clean Resource Configuration:

# workload-a/main.tf
resource "aws_autoscaling_group" "app" {
  name             = "app-asg-${terraform.workspace}"
  min_size         = var.min_capacity
  max_size         = var.max_capacity
  desired_capacity = var.min_capacity

  # Use network composition layer's outputs
  vpc_zone_identifier = data.terraform_remote_state.network.outputs.private_subnet_ids
}

The Complete Workflow:

cd workload-a/

# 1. Create feature branch environment for development
terraform workspace new workload-a-feature-user-dashboard
terraform apply -var-file=config/dev.tfvars  # Test with smaller, cheaper resources

# 2. Test in shared dev environment
terraform workspace select workload-a-dev
terraform apply -var-file=config/dev.tfvars  # Shared dev environment

# 3. Deploy to production after testing
terraform workspace select workload-a-prod
terraform apply -var-file=config/prod.tfvars  # Full production resources

# 4. Clean up feature environment
terraform workspace select workload-a-feature-user-dashboard
terraform destroy -var-file=config/dev.tfvars
terraform workspace select workload-a-dev  # Switch to any other workspace
terraform workspace delete workload-a-feature-user-dashboard

This demonstrates the workspace documentation’s guidance. It creates “parallel, distinct copies” to test changes safely before affecting production infrastructure. The tfvars and workspace combination provides the perfect interface with the same infrastructure code, different configurations, and isolated state.

Notice how we never modified the Terraform code itself. We just switched workspaces and applied different configurations. This is the elegant simplicity the documentation describes.

This workflow is both scalable and portable. The same commands work whether you’re running them locally on your laptop, in a GitHub Actions pipeline, GitLab CI, Jenkins, or any other CI/CD system. No special orchestration tools or complex deployment scripts required. Just standard Terraform commands that work everywhere.

Why This Works

The Unix philosophy teaches: “Do one thing, do it well, and compose with others.”

This approach addresses every concern the documentation raises because it implements the complete architecture HashiCorp describes:

System Decomposition FIRST: Each composition layer has its own configuration and backend
Separate Backends: Dedicated backends with composition layer-specific credentials
Reusable Modules: VPC module demonstrates DRY infrastructure patterns
Composition Layer Communication: Remote state enables data sharing between composition layers
Team Boundaries: Different teams manage different composition layers with appropriate access controls
Blast Radius Control: Changes are isolated within composition layer boundaries
Simple Deployment Interface: Workspaces + tfvars provide elegant environment management without complex orchestration
Workspaces Within Layers: Safe testing environments within proper boundaries

Workspaces work safely within each properly isolated composition layer for testing variations and managing parallel environments, exactly as the documentation intended.

The beauty of this approach is that workspaces encapsulate all the complexity of environment management within a simple, powerful interface without compromising any of the established architectural foundations. You get the benefits of proper system decomposition, security isolation, and team boundaries, while workspaces provide an elegant way to manage multiple environments within each composition layer.

Key Takeaways

An infrastructure architect reflected: “Tools are not good or bad. They are appropriate or inappropriate. Wisdom lies in knowing the difference.”

Read the documentation completely - The warning is about using workspaces ALONE, not avoiding them entirely
System decomposition first - Break infrastructure into logical composition layers with separate backends
Use reusable modules - DRY your infrastructure patterns
Enable data sharing - Composition layers communicate via terraform_remote_state
Separate credentials - Different teams, different access controls
Workspaces within layers - Use workspaces for multiple environments and feature testing within each composition layer
tfvars for configuration - Keep environment-specific config out of your Terraform code

Looking back at workspace debates I’ve witnessed and participated in, I’ve come to believe the challenge wasn’t the tool itself. It was attempting to use workspaces as the primary solution for complex scenarios instead of as one part of a comprehensive infrastructure strategy.

Interestingly, many teams may already have solid foundations. They have composition layer decomposition, separate backends, reusable modules, and proper credential isolation. They just need the workspaces and tfvars combination to complete the pattern.

The “curious case” of Terraform workspaces isn’t that they’re bad. It’s that many of us interpreted the documentation in a way that led to avoiding workspaces entirely. When used properly as part of the complete pattern HashiCorp actually describes, they’re not just useful, they’re elegant.

Sometimes the simplest solution really is right in front of you. It just requires building the proper foundation first.

Cleaner Terraform: Stop Writing Backwards Conditionals

John Reilly Pospos (JP) — Wed, 12 Nov 2025 00:27:15 +0000

How to write Terraform conditionals that read naturally and make your code easier to maintain.

Introduction

“The master debugger does not ask ‘What is missing?’ but ‘What is present?’”

I was tasked with refactoring an existing Terraform module. Simple enough, right? Wrong. I found myself staring at my monitor for god knows how long, trying to figure out how the logic flows in these ternary conditions. My Terraform game was a bit rusty, and I kept second-guessing myself.

Was I missing something obvious? Why did this feel so backwards?

Turns out the problem wasn’t my rusty skills (or maybe it was, haha). But I realized it was actually the code itself. When you write Terraform logic for things like S3 buckets, RDS databases, security groups, or EC2 instances, backwards conditionals make you think about what’s missing first. But that’s not how we naturally think about defaults:

“If the value exists, use it. Otherwise, do this.”

But I keep seeing Terraform code that works against this natural flow. Let’s fix that and make your code easier to read and maintain.

The Problem: Backwards Conditionals

“Backward your condition flows, hmm. flow backward your mind must, yes.” - Master Yoda, probably

Here’s a common pattern I see when setting defaults. These are backwards conditionals because they test for absence first:

# This reads backwards and is confusing
locals {
  instance_config = {
    instance_type = var.instance_type == null ? "t3.micro" : var.instance_type
    region        = var.region == null ? "us-east-1" : var.region
    environment   = var.environment == null ? "dev" : var.environment
  }
}

This reads like: “If instance_type doesn’t exist, use default, otherwise use the value.” That forces you to think about absence first, which feels backwards when setting defaults.

Better: Forward Conditionals

Here’s the same logic using forward conditionals that test for presence first. This matches how we naturally think about defaults and flows in one direction without mental gymnastics:

# This reads naturally
locals {
  instance_config = {
    instance_type = var.instance_type != null ? var.instance_type : "t3.micro"
    region        = var.region != null ? var.region : "us-east-1"
    environment   = var.environment != null ? var.environment : "dev"
  }
}

Now it reads naturally: “If instance_type exists, use it, otherwise use default.” Much better!

Maybe I’m just not smart enough, but forward conditionals make peer reviews and refactoring existing code so much easier for me.

Cleanest: Skip the Conditionals

“The wise function speaks once what the conditional repeats thrice”

But we can skip the conditional debate entirely with Terraform’s coalesce() function:

# Crystal clear what's happening
locals {
  instance_config = {
    instance_type = coalesce(var.instance_type, "t3.micro")
    region        = coalesce(var.region, "us-east-1")
    environment   = coalesce(var.environment, "dev")
  }
}

The coalesce() function returns the first value that isn’t null. No conditional logic needed, no forward vs backward thinking required - just clean, obvious defaults.

Real Examples That Matter

These aren’t the exact modules I was refactoring, but they exhibit the same backwards conditional patterns that had me staring at my screen for god knows how long.

S3 Bucket Setup

Here’s the pattern I kept seeing - backwards conditionals everywhere:

# Hard to follow backwards conditionals
resource "aws_s3_bucket" "app_buckets" {
  for_each = var.buckets

  bucket = each.key

  tags = merge(
    var.default_tags,
    each.value.tags == null ? {} : each.value.tags,
    {
      Environment = each.value.environment == null ? "dev" : each.value.environment
      Owner = each.value.owner == null ? "platform-team" : each.value.owner
    }
  )
}

# Better with forward conditionals
resource "aws_s3_bucket" "app_buckets" {
  for_each = var.buckets

  bucket = each.key

  tags = merge(
    var.default_tags,
    each.value.tags != null ? each.value.tags : {},
    {
      Environment = each.value.environment != null ? each.value.environment : "dev"
      Owner = each.value.owner != null ? each.value.owner : "platform-team"
    }
  )
}

# Cleanest with coalesce
resource "aws_s3_bucket" "app_buckets" {
  for_each = var.buckets

  bucket = each.key

  tags = merge(
    var.default_tags,
    coalesce(each.value.tags, {}),
    {
      Environment = coalesce(each.value.environment, "dev")
      Owner = coalesce(each.value.owner, "platform-team")
    }
  )
}

Much better! No more mental gymnastics to figure out what’s happening. The clean version took me seconds to understand instead of minutes.

Database Configuration

Another common pattern that shows how backwards conditionals compound. Every line forces you to think about absence first:

# Painful to read and debug
resource "aws_db_instance" "databases" {
  for_each = var.databases

  identifier               = each.key
  engine                   = each.value.engine == null ? "mysql" : each.value.engine
  engine_version           = each.value.engine_version == null ? "8.0" : each.value.engine_version
  instance_class           = each.value.instance_class == null ? "db.t3.micro" : each.value.instance_class
  allocated_storage        = each.value.storage_size == null ? 20 : each.value.storage_size
  backup_retention_period  = each.value.backup_retention == null ? 7 : each.value.backup_retention
  storage_encrypted        = each.value.encrypt_storage == null ? true : each.value.encrypt_storage
}

Forward conditionals make this much more readable:

# Better with forward conditionals
resource "aws_db_instance" "databases" {
  for_each = var.databases

  identifier               = each.key
  engine                   = each.value.engine != null ? each.value.engine : "mysql"
  engine_version           = each.value.engine_version != null ? each.value.engine_version : "8.0"
  instance_class           = each.value.instance_class != null ? each.value.instance_class : "db.t3.micro"
  allocated_storage        = each.value.storage_size != null ? each.value.storage_size : 20
  backup_retention_period  = each.value.backup_retention != null ? each.value.backup_retention : 7
  storage_encrypted        = each.value.encrypt_storage != null ? each.value.encrypt_storage : true
}

But coalesce is even cleaner:

# Cleanest with coalesce
resource "aws_db_instance" "databases" {
  for_each = var.databases

  identifier               = each.key
  engine                   = coalesce(each.value.engine, "mysql")
  engine_version           = coalesce(each.value.engine_version, "8.0")
  instance_class           = coalesce(each.value.instance_class, "db.t3.micro")
  allocated_storage        = coalesce(each.value.storage_size, 20)
  backup_retention_period  = coalesce(each.value.backup_retention, 7)
  storage_encrypted        = coalesce(each.value.encrypt_storage, true)
}

This version is so much easier to scan and understand. I can actually focus on the business logic instead of decoding the conditionals.

Security Group Rules

This pattern shows how backwards conditionals become a nightmare when nested. Each condition requires mental translation:

# Nested backwards conditions everywhere
locals {
  security_rules = flatten([
    for sg_name, sg_config in var.security_groups : [
      for rule in sg_config.rules : {
        sg_name     = sg_name
        type        = rule.type
        from_port   = rule.from_port == null ? rule.port : rule.from_port  
        to_port     = rule.to_port == null ? rule.port : rule.to_port
        protocol    = rule.protocol == null ? "tcp" : rule.protocol
        cidr_blocks = rule.cidr_blocks == null ? ["0.0.0.0/0"] : rule.cidr_blocks
        description = rule.description == null ? "Auto-generated rule" : rule.description
      }
    ]
  ])
}

Forward conditionals help, but are still verbose:

# Better with forward conditionals
locals {
  security_rules = flatten([
    for sg_name, sg_config in var.security_groups : [
      for rule in sg_config.rules : {
        sg_name     = sg_name
        type        = rule.type
        from_port   = rule.from_port != null ? rule.from_port : rule.port
        to_port     = rule.to_port != null ? rule.to_port : rule.port  
        protocol    = rule.protocol != null ? rule.protocol : "tcp"
        cidr_blocks = rule.cidr_blocks != null ? rule.cidr_blocks : ["0.0.0.0/0"]
        description = rule.description != null ? rule.description : "Auto-generated rule"
      }
    ]
  ])
}

Coalesce makes it crystal clear:

# Cleanest with coalesce
locals {
  security_rules = flatten([
    for sg_name, sg_config in var.security_groups : [
      for rule in sg_config.rules : {
        sg_name     = sg_name
        type        = rule.type
        from_port   = coalesce(rule.from_port, rule.port)
        to_port     = coalesce(rule.to_port, rule.port)  
        protocol    = coalesce(rule.protocol, "tcp")
        cidr_blocks = coalesce(rule.cidr_blocks, ["0.0.0.0/0"])
        description = coalesce(rule.description, "Auto-generated rule")
      }
    ]
  ])
}

Now you can actually see what each rule is doing without getting lost in the conditional logic. This is the kind of clarity that makes refactoring so much easier.

When Backwards Conditionals Make Sense

Before we write off backwards conditionals entirely, there are cases where they’re actually the natural way to think about a problem:

# Testing for intentional absence - backwards conditional feels natural here
enable_monitoring = var.disable_monitoring == null ? true : false
auto_backup       = var.skip_backup == null ? true : false
apply_immediately = var.maintenance_window == null ? true : false

In these cases, backwards conditionals match our thinking: “If the disable flag is missing, enable the feature.” But notice how the variable names create confusion too - enable_monitoring based on disable_monitoring forces you to think backwards even with good conditional logic.

The key is matching your conditional pattern to how you naturally think about the problem, but also naming variables clearly.

When to Use What

Use coalesce() when:

You’re setting simple defaults
All values are the same type
You want maximum readability

instance_type = coalesce(var.instance_type, "t3.micro")

Use forward conditionals when:

You need more complex logic than just defaults
You’re working with different data types
You need conditional expressions

# Complex logic that coalesce can't handle
backup_policy = var.environment == "prod" && var.backup_enabled ? "strict" : "standard"

Use backwards conditionals when:

Testing for intentional absence makes semantic sense
The natural thought is “if this disable flag is missing…”
You’re enabling features based on missing configuration

Avoid backwards conditionals for simple defaults because:

They force you to think about absence first
Makes your brain work harder for the common case
More likely to cause bugs when refactoring

Make Your Variables Clear Too

Beyond conditional patterns, your variable definitions should also be clear about how nulls work. This prevents confusion before you even write the conditionals:

# What does null mean here?
variable "users" {
  description = "Map of users to create"
  type = map(object({
    path        = optional(string)
    permissions = optional(string)
    tags        = optional(map(string))
  }))
}

# Clear defaults and what to expect
variable "users" {
  description = "Map of IAM users to create"
  type = map(object({
    path        = optional(string, "/")           # Defaults to root path
    permissions = optional(string, "ReadOnly")    # Defaults to minimal access  
    tags        = optional(map(string), {})       # Defaults to empty tags
  }))
}

With Terraform 1.3+ you can set defaults right in the optional() function. This means you often don’t need null checking at all!

Why This Matters for Your Team

Clear null handling isn’t just about looking nice. It directly helps with:

Code Reviews: Reviewers spend less time figuring out backwards conditionals
Debugging: Errors in conditional logic are easier to spot
New Team Members: They understand the code faster
Maintenance: Refactoring is much less error-prone

Key Takeaways

“Code that reads like thought requires no translation”

Use forward conditionals for defaults: Think “if it exists, use it” rather than “if it’s missing, use default”
Use coalesce(): It’s the cleanest approach for simple defaults
Try optional() defaults: Let Terraform handle nulls for you when possible
Match conditionals to thinking: Choose the pattern that matches how you naturally think about the problem

Looking back at that refactoring task, I realize the problem wasn’t my rusty Terraform skills. It was backwards conditionals that forced me to think unnaturally. Now when I write Terraform, I don’t waste time staring at conditionals trying to figure out which way the logic flows.

Cleaner Terraform code means fewer bugs and happier teammates. Your future self will thank you for writing code that reads the way humans think.

And as I publish this, I can’t help but think about all the backwards conditionals I’ve inflicted on the world over the years. Sorry, future me. Sorry, teammates. The horror is real, but at least now we know better… right?

Human-Readable vs Machine-Optimized: The Coming Split in Code Quality

John Reilly Pospos (JP) — Wed, 12 Nov 2025 00:07:03 +0000

Exploring how AI-assisted development might shift code quality standards from human readability to machine optimization, and what that means for the future of software development.

What does good code look like today?

Ask any senior developer and you’ll hear familiar answers: readable, maintainable, well-documented, follows established patterns, uses meaningful variable names, has clear separation of concerns. We’ve built entire movements around these principles. Clean Code, SOLID, DRY. Every language has evolved its own human-centric standards: Pythonic code, idiomatic Go, Ruby’s principle of least surprise. We conduct code reviews to enforce these standards.

But here’s a question worth exploring: What would good code look like if AI became reliable enough to write, test, debug, and validate most code on its own?

This is purely theoretical. An educated guess based on watching how AI-generated code is evolving. I’m not an expert predicting the future. Just someone exploring what might happen if current trends continue and AI gets good enough.

The Reliability Threshold

The key idea behind this theory: AI reaches a point where it can write code, debug it, find root causes, and fix issues without human help. Not 60% reliable. Not 80% reliable. But reliable enough that humans shift from writing and reading code themselves to validating what the AI produces.

This would be like how senior engineers review junior engineers’ work today. You check the logic and conclusions instead of doing everything from scratch. If AI shows its work (execution traces, state at each step, evidence for its findings), validation becomes more about reviewing the reasoning than reading and understanding implementation details.

We’re not there yet. But if we get there, the implications are worth thinking through.

A Different Set of Priorities

Imagine a future where AI writes the code, reviews it, debugs it, and troubleshoots issues. Humans validate the AI’s work, check that behavior matches expectations, and verify outputs are correct.

In that world, what defines “good” code could change.

The things that might matter most:

Performance
Efficiency
Behavioral correctness
Output validity
Token efficiency

That last point needs explanation. AI systems process code as tokens, and API costs scale with token count. If AI is writing, reviewing, and analyzing code constantly (implementation, security scanning, performance checks, testing, incident response), token costs add up fast. A codebase that’s 30% smaller through shorter variable names and compact syntax could save real money at scale. When AI generates and processes code thousands of times per day but humans review it occasionally, optimizing for the frequent reader and writer makes sense.

Why We Care About Readability Today

We care about code readability, style guides, and clean code principles because we expect humans to write, read, understand, and modify that code.

But if AI writing and reviewing its own code became standard practice, and that AI was reliable enough to trust, would human-centered readability standards still make sense? Code readability has always been a means to an end. It helps human understanding. If humans are neither the primary author nor the primary reader, the optimization target shifts.

This isn’t new. We already make similar tradeoffs:

Nobody reads minified JavaScript. We trust source maps.
Nobody reads compiled binaries. We trust debuggers.
Nobody reads database internals. We trust EXPLAIN plans.
Nobody hand-edits LLVM IR. We trust compilers.

Code could become another intermediate representation. The source of truth becomes business requirements, test suites, and AI reasoning chains. Code itself becomes what binaries are today. Something we trust the toolchain to produce correctly.

Beyond Code Review: What Else Changes?

If AI handles both writing and maintaining code, and human readability becomes less important, the implications go beyond just code style.

We’re already seeing early signs with AI systems like Claude Code, OpenCode, OpenAI Codex, GitHub Copilot CLI, Gemini CLI, and others using Model Context Protocol for tool access. These systems can write code, read logs, trace execution, run tests, and suggest fixes on their own.

In fact, this future might be closer than many realize. Power users of these coding agents are already running armies of autonomous AI systems doing exactly what this article describes: writing code, debugging issues, running tests, and iterating on solutions with minimal human intervention. What seems theoretical to some is already the daily workflow for others.

Picture a production incident at 3am: The code was written by AI. Now AI traces execution paths, connects logs, generates hypotheses, identifies root cause, and implements fixes. Faster than a human team could assemble.

The human role: Validate the evidence. Review the root cause analysis. Confirm the fix doesn’t break business logic. Maintain the AI systems themselves, making sure they stay observable and their reasoning stays transparent.

The Inevitability of AI Dependency

Some might argue this creates dangerous dependency on AI systems. But that framing might miss what’s already happening.

We’re already building AI into our development workflows:

Codebases structured around specific AI tools
Documentation written for AI consumption (.cursorrules, CLAUDE.md files)
Workflows that assume AI availability for testing, refactoring, debugging

In 5-10 years, developing without AI assistance might be like suggesting we go back to punch cards. The dependency isn’t optional. It becomes the baseline. The real questions become: Which AI systems do we depend on? Can we switch between them? Can we verify they’re working correctly?

Regulations Will Evolve Too

It’s easy to assume regulations would prevent this shift. But regulations adapt to technology changes.

Historical precedent:

Aviation moved from “humans must understand every component” to accepting fly-by-wire systems with software doing the work
Medical devices went from purely mechanical to software-controlled with verification frameworks
Financial systems moved from human auditors checking every transaction to automated monitoring with sample checks

Future regulatory frameworks might require:

AI-generated code along with verifiable reasoning chains
Audit logs of AI decision-making processes
Critical path code validated by independent AI systems from different providers
Human verification of AI findings on representative samples with statistical confidence

Not “humans must read all code,” but “humans must verify the verification system works.”

Think about compliance itself. Why would regulatory oversight stay purely human when everything else is AI-assisted? AI could constantly monitor codebases for security holes, privacy violations, and accessibility issues. It could generate compliance reports with evidence and flag potential violations before deployment. Human regulators could review AI-generated summaries and dig deep only on flagged issues.

This might actually increase regulatory coverage. Human regulators can’t review every line of code at every company. AI could, with human oversight on methods and findings.

The Economic Pressure

Here’s where theory meets observable reality: if AI can handle writing code, reviewing it, debugging it, and checking compliance, the money calculation changes fundamentally.

Today, optimizing code for human readability makes sense because humans write and maintain most code. But if AI writes and analyzes code continuously while humans review it occasionally, the economics flip. When AI generates and processes code thousands of times more frequently than humans read it, optimizing for machine efficiency over human comprehension starts to make business sense.

At big enough scale, more compact code means real cost savings. Not just in direct API costs, but in processing speed. Shorter code means faster analysis, which means faster deployment, which means competitive advantage.

The Risks (And How to Manage Them)

The most concerning scenario isn’t the end state. It’s the transition period. Imagine AI that’s 95% reliable. Good enough that teams start depending on it. Not reliable enough to fully trust. You’d end up with code humans can’t easily understand, AI that’s wrong 1 in 20 times, and no one able to catch the errors.

If this transition happens, the real risks are more subtle than simple AI dependency:

Oligopoly control: If 2-3 providers dominate, they control the means of production for all software. Pricing power, feature control, and policy decisions become centralized in ways even cloud providers don’t achieve. This makes multi-provider strategies essential. Organizations will need to maintain relationships with multiple AI providers, similar to multi-cloud strategies today. The ability to switch or run parallel systems becomes a competitive requirement, not a nice-to-have.

Systemic correlation: If everyone uses the same AI models, we get correlated failures. A bug in the model produces bugs across millions of codebases at once. A security flaw in AI reasoning becomes a universal vulnerability. Critical systems will need multi-model verification, requiring validation from AI systems built on different architectures, trained on different data, from different providers. Like how aircraft use redundant systems from different manufacturers. When safety matters, you don’t rely on a single point of failure.

Knowledge concentration: As AI handles more routine work, the broad human ability to deeply understand code could shrink. When AI fails or produces novel bugs, organizations need experts who can debug from first principles. The danger is underinvesting in this specialized expertise because “AI can handle it.” Like GPS navigation. It works great until it doesn’t, and then you’re lost if you never learned to read maps.

But here’s the thing: SMEs (Subject Matter Experts) with deep programming knowledge don’t become less valuable. They become more valuable. Their role shifts from writing all code to validating AI reasoning, handling edge cases, maintaining AI systems, and serving as escalation when AI fails. Organizations that maintain this expertise gain competitive advantage. The skill doesn’t disappear. It concentrates and becomes more strategic.

Verification capability gap: If humans lose the ability to meaningfully verify AI reasoning, trust becomes impossible to check and errors compound undetected. This is where the industry needs to pivot value, effort, and expertise toward verification rather than implementation. The critical skill becomes “can you effectively validate AI reasoning and evidence?” rather than “can you write this code from scratch?”

This is a different skillset but not a lesser one. It requires deep understanding of correctness, edge cases, and system behavior. The developers who master verification in an AI-native world will be as valuable as the architects and senior engineers of today. Organizations that invest in building these verification capabilities during the transition will be better positioned than those that assume “AI can handle it.”

Where This Might Lead

If this theory plays out, we might see a gradual evolution in how we think about code quality:

Short term (now): AI assists most developers with writing and debugging routine code; power users already running autonomous agent workflows. Humans maintain deep understanding and do final reviews.

Medium term (5-10 years): AI writes and debugs most code, humans verify reasoning and outcomes through AI-provided evidence, code readability starts to matter less.

Long term (15+ years): AI-written machine-optimized code becomes standard for many areas, humans verify through abstraction layers (requirements, tests, reasoning chains), regulations adapt to AI-native development.

This could create a split:

Human-readable code for systems where human understanding stays critical: regulated industries with strict oversight, safety-critical systems where failures have serious consequences, long-lived systems needing institutional knowledge.
**
Machine-optimized code** for systems where behavior and performance matter more than readability: internal tools, high-iteration low-stakes systems, performance-critical systems where optimization benefits outweigh readability costs.

The qualities we optimize for wouldn’t disappear. They’d redistribute based on who the primary reader of the code is.

When Might This Become Real?

The shift becomes possible when trusting AI explanation plus cited evidence becomes more reliable than trusting your own ability to read and understand code.

For routine work, we might be approaching that threshold. For high-stakes systems, we’re probably far from it. The path forward likely requires:

AI systems that can reliably explain and justify their reasoning with verifiable evidence
Standards for switching between AI providers
Verification frameworks proving AI reliability at statistical confidence levels
Regulatory changes creating accountability without requiring human understanding of every line
Keeping human baseline knowledge during the transition to catch AI failures

The Bottom Line

Maybe I’m wrong. Maybe human understanding will always stay central. Maybe the verification overhead will exceed efficiency gains. Maybe regulations will require human-readable code regardless of technical ability. Maybe AI reliability will plateau before reaching the threshold this theory requires.

But even if this specific scenario doesn’t happen, the basic question stays worth exploring: When we say “good code,” who are we optimizing for? And if that audience changes, shouldn’t our definition of quality change with it?

The key requirement is reliability. Without AI systems that can consistently and verifiably write, debug, and troubleshoot code on their own, this stays theoretical. But if that threshold is reached, the money pressure and practical advantages might drive this shift faster than we expect.

We’re not there yet. But the direction suggests it’s worth thinking through the implications now, while we still have the knowledge and ability to build the right accountability systems for whatever comes next.

Using Amazon Bedrock with OpenWebUI when working with sensitive data

John Reilly Pospos (JP) — Sun, 18 Aug 2024 09:02:34 +0000

Introduction

I've been using OpenWebUI and local Llama models to help me with heavy lifting tasks like analyzing, classifying, fact-checking, and summarizing against documents, and personal financial records. It's been a valuable tool, allowing me to keep all that confidential data secured on my local machine. But I've run into one major frustration - my laptop just doesn't have the computing power to handle the larger language models I need for this kind of complex analysis. I was stuck using the smaller 7B models, which still took precious seconds to respond.

I was about to subscribe to a cloud-based service, resigning myself to having my sensitive data leave my local environment. But then I had a thought - what if I could leverage the power of a cloud-based service while still keeping my data secure and private? That's when I realized I could use Amazon Bedrock.

I already knew about Amazon Bedrock and had access to an AWS account. It only recently dawned on me that I could combine Bedrock's advanced foundation models with the privacy-focused approach of OpenWebUI. The idea of tapping into Bedrock's powerful LLM (Large Language Model) capabilities, while still maintaining the local data storage and confidentiality of OpenWebUI, was exactly what I needed to overcome the performance limitations of my laptop and keep my information secure.

Now, instead of being stuck with the limited performance of smaller local models, I can seamlessly integrate OpenWebUI with Amazon Bedrock. This allows me to leverage the wider range of high-performing foundation models available through Bedrock, without exposing my sensitive documents, financial records, or other proprietary information to the public cloud.

Although my interactions with Amazon Bedrock happen within my AWS account, all my conversations and data remain locally stored because I'm using a local vector database with OpenWebUI. This ensures my confidential data never leaves my controlled environment.

It's been a game-changer for the way I approach heavy-lifting tasks that require the power of LLMs. That's why I'm excited to share this powerful combination of Amazon Bedrock and OpenWebUI, and how it can benefit you when handling sensitive and proprietary information. Let's dive in.

What are Amazon Bedrock and OpenWebUI?

To dive into the details of how these two tools work together, let's first take a closer look at Amazon Bedrock and OpenWebUI.

Amazon Bedrock is a fully managed service that provides access to a wide range of high-performing foundation models (FMs) from leading AI providers like Anthropic, Cohere, and Stability AI. This allows you to select the best model for your specific use case, whether you're analyzing internal documents, questioning financial records, or processing customer information. Importantly, Amazon Bedrock is designed with a focus on security, privacy, and responsible AI practices, ensuring your sensitive data remains protected.

On the flip side, OpenWebUI is an open-source project that gives you a user-friendly web interface for working with LLMs like LLaMA and GPT. This makes OpenWebUI an ideal companion when handling sensitive information, as it keeps all user data stored locally on your device and prevents any external access or exposure.

By leveraging the capabilities of both Amazon Bedrock and OpenWebUI, you can tap into advanced LLM-powered functionality while prioritizing data security and privacy. Let's explore how these two tools work together in more detail.

What makes them ideal for handling sensitive data?

Now that we've covered what Amazon Bedrock and OpenWebUI are, let's dive into what makes them ideal for handling sensitive data.

OpenWebUI:

Offline-First Design: OpenWebUI’s offline-first approach helps to isolate user data from network-based threats, making it a strong option for handling sensitive information.
Strict Confidentiality: OpenWebUI emphasizes "strict confidentiality and no external requests," ensuring that your data remains secure and private.
Transparent Open-Source: Being open-source, OpenWebUI allows you to audit its codebase, giving you the ability to verify its data handling practices.

Amazon Bedrock:

Compliance with Standards: Bedrock, as part of AWS, complies with stringent security standards such as FedRAMP, SOC, ISO, and HIPAA, making it suitable for industries with high compliance requirements.
Secure Model Deployment: Amazon Bedrock leverages isolated accounts to ensure that model providers do not have access to customer data, enhancing security for sensitive information.
Robust Data Protection: Bedrock is designed to protect customer data with encryption and secure transmission. While data may be transmitted over the public internet, it is safeguarded by AWS’s robust security measures, ensuring data is protected both in transit and at rest.

These security and privacy-focused features of OpenWebUI and Amazon Bedrock make them a powerful combination for handling sensitive data with confidence.

Integrating OpenWebUI with Amazon Bedrock

Now that we've explored the security and privacy features of OpenWebUI and Amazon Bedrock, let's dive into the process of integrating the two tools. To get started, you'll need to set up both OpenWebUI and the Bedrock Access Gateway on your local machine. Once that's done, you can configure OpenWebUI to integrate with Bedrock, allowing you to interact with models like Claude3-Sonnet and use features like Cohere.Embedding - all while keeping your sensitive data secure.

But why integrate OpenWebUI with Amazon Bedrock when you could just use local LLMs like LLaMA and still remain secure? There are a few key reasons:

Access to Larger and More Capable Models: While LLMs like LLaMA are powerful, Amazon Bedrock provides access to an even wider range of leading foundation models, including those from providers like Anthropic, Cohere, and Stability AI. This allows you to leverage more advanced and capable generative AI capabilities.
Faster Responses with Limited Local Resources: Running LLMs can be resource-intensive, especially on local devices with limited CPU, memory, and GPU capabilities. By integrating with Amazon Bedrock, you can offload the heavy computational workload to the cloud, ensuring fast responses even when your local hardware is constrained.
Ongoing Model Updates and Improvements: As a fully managed service, Amazon Bedrock handles the maintenance and updates of the foundation models, ensuring you always have access to the latest versions and improvements. This can be challenging to manage on your own when working with local models.

By combining the benefits of OpenWebUI's offline-first approach with the powerful and scalable capabilities of Amazon Bedrock, you can access advanced generative AI capabilities while keeping your sensitive and proprietary data secure.

Let's get started!

To set up OpenWebUI on your local machine, follow these steps:

1. Download and Install OpenWebUI

Head over to the OpenWebUI GitHub repository, clone their repo and install open-webui by running the commands below;

# This command clones the open-webui repository from GitHub.
git clone https://github.com/open-webui/open-webui.git

# This command changes the current working directory to the cloned repository.
cd open-webui

# This command copies the .env.example file to create a new .env file. The .env file is used to store environment variables for the application.
cp -RPp .env.example .env

# This command installs the required Node.js dependencies for the frontend part of the application.
npm install

# This command builds the frontend code for the application.
npm run build

# This command changes the current working directory to the backend folder.
cd ./backend

# This command activates the Pipenv virtual environment for the backend code.
pipenv shell

# This command installs the required Python dependencies for the backend part of the application.
pip install -r requirements.txt -U

# Start the application
bash start.sh

If everything goes well you should see something similar to the image below.

📝 NOTE
There are other and much easier ways to install `open-webui`, go to their documentation page to see the recommended installation option.

2. Login to your local OpenWebUI installation

Open your browser and navigate to http://0.0.0.0:8080, since this is your first time accessing you will need to sign up.

📝 NOTE
This sign-up is only for your local instance of `open-webui` and totally unrelated to signing-up to `https://openwebui.com/`.

3. Download and Install Bedrock Access Gateway

Head over to the bedrock-access-gateway GitHub repository, clone their repo and install by running the commands below;

# This command clones the bedrock-access-gateway repository from GitHub.
git clone https://github.com/aws-samples/bedrock-access-gateway.git

# This command changes the current working directory to the cloned repository.
cd src

docker build -f Dockerfile_ecs -t bedrock-access-gateway .

docker run -e AWS_ACCESS_KEY_ID="<replace-with-access-key-id>" \
    -e AWS_SECRET_ACCESS_KEY="<replace-with-secret-access-key>" \
    -e AWS_DEFAULT_REGION="<replace-with-region>" \
    -e AWS_REGION="<replace-with-region>" \
    -e DEBUG=true \
    -d -p 8081:80 \
    bedrock-access-gateway

If everything goes well, you should see something similar to the image below.

📝 NOTE
Make sure you have sufficient access to Bedrock and you have requested access to the base models you want to use via the Amazon Bedrock console.

4. Connect the OpenWebUI to Amazon Bedrock

This allows you to chat with Bedrock models. Within OpenWebUI, go to "Settings" > "Admin Settings" > "Connections". Here, Update the "OpenAI API" section's API Base URL to point to your bedrock-access-gateway's URL which is http://localhost:8081/api/v1 and update the API Key to bedrock-access-gateway's default API key which is bedrock.

Then click on the verify connection icon as highlighted on the image below. Upon clicking it, you should see a green popup saying "Server connection verified" Once verified, click the "Save" button.

📝 NOTE
For added security, store the API key you want to use in SSM and reference the SSM parameter name by defining the `API_KEY_PARAM_NAME` environment variable when running the Docker container.

5. Connect the OpenWebUI Embedding Model Engine to Amazon Bedrock

After connecting OpenWebUI to Amazon Bedrock, the next step is to integrate the embedding model engine. This allows you to use Bedrock's embedding models to enhance document processing. Within OpenWebUI, go to "Settings" > "Admin Settings" > "Documents". Here, Update the "Embedding Model Engine" section's API Base URL to point to your bedrock-access-gateway's URL which is http://localhost:8081/api/v1 and update the API Key to bedrock-access-gateway's default API key which is bedrock.

Next, you need to pick which embedding model to use by setting the Embedding Model to either use cohere.embed-english-v3 or cohere.embed-multilingual-v3. Before you save our changes, make sure you re-import all documents by clicking on "Reset Upload Directory" and "Reset Vector Storage", then simply re-upload your existing documents.

Once that is done, click on the "Save" button. With the OpenWebUI-Bedrock embedding integration now set up, you're ready to start leveraging the advanced capabilities of these tools for your document processing needs.

6. Start Interacting with Bedrock Models

With the OpenWebUI-Bedrock integration now set up, you can start tapping into the powerful capabilities of Amazon Bedrock's foundation models. This includes:

Chatting with Bedrock Models: Within the OpenWebUI interface, you can now engage in conversations with advanced language models like Anthropic's Claude3. Simply select the desired Bedrock model from the available options and start chatting, all while keeping your sensitive data securely stored on your local machine.

Start chatting once you've chosen your bedrock model of choice.

Leveraging Bedrock Embedding Models: In addition to language modeling, you can also utilize Bedrock's high-quality embedding models to enhance your document processing workflows. Options like Cohere's Embed-English and Embed-Multilingual are available through the OpenWebUI integration, allowing you to generate rich vector representations of your text data. Whenever you upload new documents to OpenWebUI it should now use Cohere's Embedding model through Amazon Bedrock.

📝 NOTE
You can validate this by checking `bedrock-access-gateway`'s logs as you upload a document.

Once a document is uploaded, you can start questioning it! To do that, you can reference any document by using the # sign on a new chat window.

Here you see a document has been chosen and have started quesitoning it.

And here you see claude3 responding.

By seamlessly connecting OpenWebUI to Amazon Bedrock, you have the best of both worlds - the privacy and security of a local, offline-first tool combined with access to a wide range of advanced generative AI capabilities. This empowers you to handle your sensitive data with confidence while tapping into the cutting-edge functionality provided by Bedrock.

Conclusion

With the OpenWebUI-Bedrock integration set up, you're now ready to start leveraging the powerful capabilities of these two tools to handle your sensitive data with ease. The combination of OpenWebUI's privacy-focused approach and Bedrock's advanced foundation models, along with its robust data protection features, provides a comprehensive solution for tackling your most complex and confidential tasks.

Amazon Bedrock's compliance with stringent security standards like FedRAMP, SOC, ISO, and HIPAA, as well as its secure model deployment and robust data protection mechanisms, ensures that your sensitive data remains safeguarded throughout the process. By seamlessly connecting OpenWebUI to Bedrock, you have the best of both worlds - the privacy and security of a local, offline-first tool combined with access to a wide range of cutting-edge generative AI capabilities.

I'm confident that this integration will be a game-changer for the way you approach sensitive and confidential data tasks. With the powerful combination of OpenWebUI and Amazon Bedrock at your fingertips, you can tackle even your most complex challenges while maintaining the highest standards of security and privacy. As I'll be using this setup as my daily driver, I'll be sure to report back on the cost-effectiveness of running this configuration for a month. Please let me know if you have any other questions as you get started!