TFE Components

Operational Modes

Operational Mode Decision

Design Attributes

The SDG evaluates decisions against four non-functional attributes. Each recommendation in the guide explicitly notes its impact:

Personnel Roles

Access Requirements

The installation team requires direct (including administrator) access to the following before starting:

Network Egress Requirements

TFE should not be exposed to the public internet for ingress. Users must be on the company network. TFE does need outbound access to:

• registry.terraform.io — public module registry (official providers index here; restrict via Sentinel/OPA for community content)
• releases.hashicorp.com — Terraform binary releases (stay within two minor releases of latest)
• reporting.hashicorp.services — license usage aggregation (strongly recommend allow-listing)
• Algolia — used by the Terraform Registry for indexing
• VCS/SAML endpoints, public cloud cost estimation APIs as applicable

Resource Sizing

CPU Sizing Rules (All Providers)

• Avoid burstable CPU instances (AWS T-type, Azure B-type, GCP e2-/f1-/g1-series)
• Choose latest generation general-purpose x86-64 instances
• Use CPU/RAM ratio of 1:4 or higher
• Do not use memory-optimized instances

Concurrency & RAM Calculations

The TFE_CAPACITY_CONCURRENCY variable controls concurrent workspace runs. Default RAM per agent is 2048 MiB. Formula:

Default machine (8 vCPU, 30 GB): maximum concurrency of 11. Scaled machine (16 vCPU, 61 GB): maximum concurrency of 26.

HVD Module Deployment Process (High-Level)

1. Import TFE modules into your VCS repository
2. Configure remote state storage (S3/Blob/GCS or HCP Terraform free tier)
3. Select a machine with Terraform CLI available and cloud credentials instantiated
4. Read the module GitHub README in its entirety before starting
5. Prepare TLS certificate and private key (SAN must match FQDN; no self-signed certificates)
6. Run terraform init, plan, apply
7. Tail installation logs post-deployment; watch for errors
8. Retrieve the Initial Admin Creation Token (IACT) within 60 minutes of deployment

General Guidance

• Separate TFE pods and HCP Terraform agent worker pods — agent workload is inconsistent under load
• Use HCP Terraform Operator instead of the internal Kubernetes driver run pipeline for customers going beyond default concurrency per TFE pod
• Three TFE pods is sufficient for HA — HCP Terraform agent cluster capacity has the greatest impact on run success at scale
• TFE supports x86-64 on all versions; ARM requires v1.0.0 or later
• Do not use burstable instance types (AWS T-type, Azure B-type, GCP e2-/f1-/g1-series)

K8s Resource Sizing

Approximate minimum cluster sizing for HCP Terraform agents with 3 TFE pods at system defaults:

• 3-node cluster: 96 GB total memory, 64 GB (n-1)
• 5-node cluster: 80 GB total memory, 64 GB (n-1)

Agent Count Formula

Internal Run Pipeline vs. HCP Terraform Operator

Network Considerations

• Specify a version tag for HCP Terraform agent image (e.g., tfc-agent:<tag>) — using :latest pulls the image on every run, adding unnecessary network load
• HVD Modules deploy layer 4 load balancers (highest throughput available)
• Load HCP Terraform agent Docker image from a region-local source (ECR) rather than public internet when possible
• Do not use instances with burstable network characteristics

Common Troubleshooting

Private Cloud Component Considerations

Compute Sizing (Private Cloud)

Recommended operating systems: Red Hat Enterprise Linux or Ubuntu LTS.

Monitoring PostgreSQL and Redis

Monitor CPU, memory, available disk space, and disk IO using organizational telemetry. Create alerts at 50% and 70% utilization thresholds. If any parameter consistently exceeds 70%, increase the resource.

Network Requirements

TFE has specific ingress and egress requirements — refer to the TFE network requirements page for the latest. If a corporate proxy is filtering outbound traffic, add required destinations to the allow-list. Use a layer 4 load balancer. Air-gapped mode is available if external access is not possible.

Operating System

• Use OS configurations compliant with the CIS benchmark for the chosen operating system
• Limit CLI access to machines to a shortlist of well-known staff
• Ensure the organization's SIEM/audit log reflects all access

Application

• Use single sign-on (SSO) with multi-factor authentication (MFA) for all users
• TCP port restrictions for ingress/egress are configured by the deployment. Do not alter unless advised by HashiCorp support, a solutions engineer, or certified partner.
• Enable the Strict-Transport-Security response header
• For manual installs: set restrict_worker_metadata_access as a Docker environment variable to prevent Terraform operations from accessing the cloud instance metadata service
• HVD Module automated deployments restrict access to the AWS metadata service — do not re-enable this
• After deployment, do not create the initial administrator immediately — coordinate a handoff to the operations team

Primary Planning Considerations

Component-Specific Guidance

The Platform Team

The platform team serves as the central hub, orchestrating functions and ensuring streamlined operations across teams. It may consist of one or more teams with separate areas of responsibility.

Security Team Collaboration

The security team collaborates with the platform team to establish governance policies and deploy monitoring tools. Key cloud security functions include:

• Subscribing to security updates and vulnerability alerts; collaborating with SRE on patches
• Managing TLS certificate validity and renewal for TFE
• Scanning TFE instances for vulnerabilities; integrating SIEM tools for audit logging
• Providing governance inputs to CCoE (PaC guardrails, CIS benchmarks)

Producers and Consumers

Golden IaC Workflows

A golden workflow is a standardized, repeatable process for completing a specific task. The platform team shifts these workflows left using pre-approved Terraform configurations and curated modules, empowering teams to independently provision infrastructure while maintaining centralized management.

Hierarchy Overview

Access Management

HCP Terraform access is built on three components: User accounts, Teams, and Permissions. Implement SAML/SSO for user management combined with RBAC.

Cloud Provisioning Key Steps

1. Plan the project: installation/config of TFE, self-service capability design. Consider onboarding early adopters before general availability — use stepwise refinement.
2. Consider platform team size and bandwidth — if any onboarding step is not automated, it compounds with scale.
3. Plan a landing zone provisioning workflow.
4. Ensure the platform team is fully trained on IaC with Terraform and the cloud providers in use. All contributors must adhere to the HashiCorp Terraform language style guide.
5. Set up a TFE Stack or workspace with cloud credentials.
6. Store Terraform code in your strategic VCS.
7. Provision cloud resources from the VCS-backed Stack or workspace.
8. Consider configuration required to enable end-to-end deployment within org security and compliance requirements. Identify manual steps and what would be needed to automate each.

Landing Zones

A cloud landing zone is a foundational, standardized environment for secure, scalable cloud operations. The platform team deploys a control workspace during onboarding of each internal customer.

Workflow Personas

VCS-Driven Workflow

API-Driven Workflow

For customers with strategic CI/CD pipeline orchestrators, HCP Terraform and TFE form the infrastructure management component of those pipelines. In this model, the CI/CD tool drives the Terraform run via the TFE API rather than through VCS webhooks. This supports more complex orchestration patterns where infrastructure changes are part of a larger pipeline.

What to Import vs. What Not to Import

Team Responsibilities

Phased Approach

Feature Availability by Product

Observability Feature Definitions

• Operational logs: Track performance and behavior — error messages, warnings, events. Used by SRE to monitor and maintain service.
• Audit trail: Security-focused — login attempts, access control changes, suspicious activities. Used by security analysts and incident response teams.
• Metrics: Application component performance and usage data — detect service quality issues or inform capacity planning.

TFE Monitoring Focus Areas

• Each team member should have an account created through the HashiCorp support portal
• Configure each team member permitted to open support tickets as an Authorized Technical Contact. Provide the list to your assigned HashiCorp Solutions Engineer for configuration.
• Familiarize the team with documentation on how to open a support ticket and generate/upload a support bundle when applicable
• Be aware of your support plan level to manage response time expectations
• Understand the severity level definitions when opening a ticket — see the Customer Success Enterprise Support page

Health Assessment Components

Drift Resolution Workflow

Once drift is detected, the workspace notifies the application team. They decide the best resolution:

Refresh State vs. Update Configuration

Registry Roles

Module Requirements

Additional Benefits of Custom Modules

Beyond reusability, custom modules enable organizations to encode:

• Naming conventions
• Security controls
• FinOps standards (tagging, cost allocation)

Key Benefits of Sentinel

Policy Enforcement Workflow

1. Define governance/compliance policies and translate them into Sentinel policy requirements
2. Code policies using the Sentinel language; arrange in policy sets
3. Scope policy sets to the entire organization, or to one or more projects/workspaces
4. Policy enforcement levels: advisory (warns but doesn't block), soft-mandatory (can be overridden by authorized users), hard-mandatory (cannot be overridden)

People and Responsibilities

• Sentinel policies owned by the Security team with input from regulatory compliance areas
• CCoE/Platform Team understands Sentinel code and how to employ it in production pipelines
• CCoE/Platform Team partners with Security Team to manage ownership and RBAC over policy code

Repository Organization Best Practices

How Run Tasks Work

Run tasks send an API payload to an external service at a specific run stage. The service processes the data, evaluates whether the run passes or fails, and sends a response back to HCP Terraform. Based on the enforcement level, HCP Terraform determines if the run can proceed.

Run Stages

Common Use Cases

Implementation Flow

1. Select the desired run task from the public Terraform Registry; review requirements and documentation
2. Establish and verify two-way connectivity between HCP Terraform platform and the run task endpoint (network/security modifications may be required)
3. Create the run task in the Terraform Organization (connect endpoints, test communication path)
4. Associate the run task with a workspace; configure the stage and enforcement level (Advisory or Mandatory)
5. Run task executes as part of normal run cycles; review results in run completion output

When to Use Self-hosted Agents

TFE Scaling Strategies (Priority Order)

1. Migrate to active-active operational mode and increase TFE node count
2. Add more resources to VMs hosting TFE nodes; increase capacity config params (TFE_CAPACITY_CONCURRENCY, TFE_CAPACITY_CPU, TFE_CAPACITY_MEMORY)
3. Deploy HCP Terraform agents — the next logical step once the above limits are reached

Agent Pool Design

Custom Resources Introduced

Use Case 1: Auto-scaling Agent Pools

The Operator manages agent pool lifecycle and deployment via the AgentPool CRD. It can monitor workspace queues to trigger autoscaling based on defined min and max replicas.

• Increase agents up to autoscaling.maxReplicas or licensed limit (whichever is reached first)
• Reduce agents to autoscaling.minReplicas within autoscaling.cooldownPeriodSeconds when no pending runs exist

Sizing AgentPool Autoscaling

• maxReplicas: Determined by peak-run concurrency demand and HCP Terraform tier constraints. Scale-test your cluster to ensure peak load is handled.
• minReplicas: Consider baseline run concurrency from health checks (drift detection, continuous validation).
• Set memory limits and resource requests on agents — helps efficient node placement; critical if using cluster scaling technologies like Karpenter.

Use Case 2: Self-Service Infrastructure via Kubernetes Native Consumption

The Operator lets application developers define infrastructure configuration using Kubernetes configuration files. It delegates the reconciliation phase to HCP Terraform. This frees developers from needing to learn HCL for infrastructure management tasks — useful when your application teams are Kubernetes-native and prefer K8s manifest-based workflows.

Security Considerations

Agent tokens stored in the Kubernetes cluster must be secured using your organization's K8s secrets management approach. Review the Operator documentation for specific security guidance. Egress requirements for the HCP Terraform agent apply when agents are deployed via the Operator — includes provider endpoint connectivity, Terraform registry access, and Terraform releases access.

Why Continuous Validation?

Failed infrastructure changes can introduce project delays and expose the organization to operational or security risks. Continuous validation gives advance notice of issues preventing successful changes, so they can be addressed before a Terraform apply fails in production.

Best Practice Recommendation

• When a new workspace is created, enable continuous validation (explicitly at workspace level or implicitly at org level)
• Include necessary logic in Terraform configuration to validate important components whose health may change over time
• If infrastructure changes fail in the future due to an unchecked condition, update the Terraform configuration to incorporate the new validation — and apply this pattern to existing infrastructure code

Rule of Thumb — Which Resources to Validate

• Check the status of any critical resource that can fail (e.g., VMs)
• Check validity of resources with user-defined time frames whose failure impacts the application stack (e.g., TLS certificates)
• Not necessary for inherently durable resources (e.g., S3 buckets — native to cloud provider)

Implementation Requirements

Permissions required: Organization health settings require Owners team membership. Individual workspace settings require Workspace Admin access.

Notification Event Categories

Implementation Guidance

Configure notifications via WebUI, the API (tfe_notification_configuration), or using the Terraform TFE provider. HashiCorp recommends using the TFE provider to configure notifications as part of the project/workspace creation process.

Notification Strategy

• Choose appropriate destination: Slack is popular, but use whatever fits team workflow (email, Teams, etc.)
• Granular notifications: Avoid broad notifications that cause alert fatigue — focus on critical events
• Integration with incident management: Integrate with incident management tools so alerts lead to actionable items

Maintenance

• Periodically review notification settings and adjust based on changing infrastructure needs and team feedback
• Test when making changes — trigger events manually to verify notifications are received
• Continuously monitor and solicit feedback to reduce noise and improve relevance

No-code provisioning is deployed into new TFE workspaces. This is a consideration for platform teams managing license consumption — each no-code deployment creates a new workspace.

Roles and Responsibilities

Permissions

• Marking a module as no-code enabled requires the Manage Private Registry permission or Owners team membership
• Deploying a no-code module requires Project Admin permission or higher
• HCP Terraform/TFE uses the module's configured variable set or workspace variables for cloud credentials

Configuring at Scale

• Use the TFE provider or API to automate no-code module configuration when setting up new projects
• Define variable sets at the project level to provide the necessary cloud credentials — these are inherited by no-code workspaces
• Document the no-code provisioning process for consumers so they understand what is available and how to use it

Use Cases

• Spin up and tear down feature-branch infrastructure automatically
• CI/CD environments that need fresh infrastructure per pipeline run
• Time-boxed customer or internal demos and proof-of-concept deployments
• Any scenario where infrastructure should not persist beyond a defined lifecycle

Roles and Responsibilities

Permissions

• Creating ephemeral workspaces and configuring auto-destroy requires Workspace Admin permission or higher at the project level

Configuring at Scale

• Use the TFE provider or API to automate ephemeral workspace creation as part of CI/CD pipelines
• Set auto-destroy notifications (12h and 24h reminders are available) so teams are aware of impending destruction
• Define standard auto-destroy schedules in project-level documentation — prevents unintended persistence of temporary resources
• Integrate auto-destroy results notifications with your incident management or team communication channels