Skip to content

ADR 0002: Use Terraform for OpenShift and Infrastructure Provisioning

Status: Accepted
Date: 2026-04-24
Authors: BRAC POC Team

Context

The POC requires provisioning a 3-node OpenShift cluster plus supporting infrastructure (Kafka, Redis, GitLab, Jenkins) in an aggressive 6-day timeline. Manual provisioning would: - Exceed timeline - Introduce inconsistencies - Make validation/reproduction difficult - Limit scalability demonstration

BRAC requires evidence of automation capability as a key qualifying factor.

Decision

Use Terraform as the primary Infrastructure-as-Code (IaC) tool for: 1. OpenShift cluster provisioning (3 nodes on VMs) 2. Kafka KRaft cluster setup 3. Redis Sentinel HA deployment 4. CI/CD infrastructure (GitLab HA, Jenkins) 5. Nexus artifact repository

Key commitments: - Use public Terraform modules from Registry where available (RedHat, CNCF, HashiCorp) - Organize code by component in separate modules - Implement state management (local or Terraform Cloud) - Store all .tf files in Git; exclude state files - Generate comprehensive documentation from code

Consequences

Positive

  • Repeatability: Cluster can be destroyed and rebuilt identically
  • Compliance: State tracked in code, audit trail built-in
  • Scalability: Easy to spin up multiple environments (dev, test, prod)
  • Team enablement: Developers see IaC best practices applied
  • BRAC requirement: Demonstrates infrastructure automation maturity
  • Documentation: Code becomes self-documenting when well-written
  • Version control: All changes tracked, easy rollback

Negative

  • Learning curve: Team needs Terraform expertise
  • Debugging complexity: State drift issues can be cryptic
  • Provider dependencies: Changes in cloud provider APIs may break code
  • Maintenance overhead: Modules need updates as provider versions change
  • Setup time: Initial module creation takes effort (offset by reuse)

Neutral

  • Terraform state management requires careful handling (never commit state files)
  • Module versioning adds complexity but improves reusability

Alternatives Considered

Alternative 1: CloudFormation (AWS-only)

  • Pros: Native AWS tool, well-integrated
  • Cons: AWS-specific, doesn't support OpenShift on other clouds, less portable
  • Why rejected: POC needs flexibility across cloud/on-premise environments

Alternative 2: Ansible

  • Pros: Agentless, good for configuration management
  • Cons: Not ideal for infrastructure provisioning, more imperative than declarative
  • Why rejected: Better suited for post-provisioning configuration, not cluster creation

Alternative 3: Pulumi

  • Pros: Infrastructure as code using Python/Go, modern approach
  • Cons: Smaller ecosystem, less mature, learning curve, longer POC timeline
  • Why rejected: Terraform has broader team familiarity and larger module ecosystem

Alternative 4: Helm Only (No Infrastructure Layer)

  • Pros: Simpler, focuses on Kubernetes deployment
  • Cons: Assumes cluster already exists, doesn't address BRAC's infrastructure automation requirement
  • Why rejected: POC explicitly requires cluster provisioning automation

Implementation Notes

Directory Structure

terraform/ ├── modules/ │ ├── openshift/ (3-node cluster) │ ├── kafka/ (KRaft cluster) │ ├── redis/ (Sentinel mode) │ ├── cicd/ (GitLab + Jenkins) │ └── nexus/ (Artifact repository) ├── environments/ │ ├── dev/ │ │ ├── main.tf │ │ ├── variables.tf │ │ └── terraform.tfvars │ └── prod/ ├── outputs.tf (consolidated cluster info) ├── variables.tf (global vars) └── versions.tf (provider constraints)

Module Design

  • Self-contained per component
  • Parameterized for flexibility
  • Clear input variables and outputs
  • Includes default values where appropriate

State Management

  • Store state in Terraform Cloud or S3 backend
  • Enable state locking to prevent concurrent modifications
  • .gitignore includes *.tfstate files
  • Document state backend setup in DEPLOYMENT.md

Validation & Testing

  • Run terraform validate in CI/CD
  • Use terraform fmt for consistency
  • Generate plan files for review before apply
  • Document plan in PR for audit trail

References

Approval

  • Approved by: BRAC POC Technical Lead
  • Date: 2026-04-24

History

Date Status Notes
2026-04-24 Accepted Initial decision, Phase 1 implementation starting