Deploying to a Private EKS Cluster Using Terraform Cloud (TFC)

By default, Terraform Cloud (TFC) workspaces require network-level access to the EKS API endpoint to deploy workloads or manage clusters. When the EKS API endpoint is private, it becomes unreachable from the public internet, including TFC. Here are your options for deploying applications to a private EKS cluster from TFC:

1. Use a Network Bridge: AWS VPC Endpoint + PrivateLink

• PrivateLink lets you expose the EKS API as a private service inside your AWS VPC. TFC cannot use this directly, but you can provision a bastion (jumpbox) EC2 instance or a client node inside the VPC with access to the private endpoint.
• Use an AWS Session Manager (SSM) tunnel or a self-hosted runner/agent (see #2 below) running on this bastion to perform EKS operations. TFC connects to the runner, and the runner has private-path-only access to EKS.

2. Deploy a Self-Hosted (Agent) Runner in Your AWS VPC

• Terraform Cloud supports self-hosted agents that can run inside your AWS environment.
• Spin up a small EC2 instance (or Fargate task) in a private subnet with permissions scoped for your deployment.
• Register this instance as a TFC agent, then run TFC jobs through it. These jobs have network access to your private EKS cluster.
• This is the most seamless and secure method as no public access or proxies are exposed.

3. Temporary Public Access Only During Deployment

• Make the EKS API endpoint public only for the duration of Terraform apply, then revert to private.
• This is logistically complex, somewhat insecure, and not recommended for automation but can be used as a short-term workaround.

4. VPN or Direct Peering

• Connect your organization’s internal network and the AWS VPC via VPN or VPC Peering so TFC jobs can route to the private API endpoint from a trusted on-premises location (rare, but technically possible).

5. Use a Bastion + SSM Bridge

• Set up a bastion host (jumphost) with SSM enabled inside the VPC.
• Use [AWS SSM Session Manager] to tunnel traffic from your corporate/TFC runner to the EKS endpoint.
• This pattern is documented by AWS as a secure approach for accessing private EKS clusters for CI/CD and automation tasks.

Summary Table

Option	Additional Infra Needed	Security Level	Maint. Overhead	Typical Use Case
TFC Agent (self-hosted runner)	EC2 in VPC	High	Moderate	Enterprise, robust CI/CD
PrivateLink & Bastion (jump host)	EC2, PrivateLink	High	High	Strictly isolated clusters
Public endpoint (on/off as needed)	None	Low	Low	Short-term workaround
VPN/Peering	VPN Gateway/Peering	Varies	High	On-premises CI/CD bridge
Bastion+SSM tunnel	EC2 + AWS SSM	High	Moderate	Secure admin/CI access

Recommended Solution

Deploy a Self-Hosted TFC Agent (Runner) in your AWS VPC:

• This aligns with best practices, giving you private network access to EKS and all AWS resources.
• Keeps your EKS endpoint private and your CI/CD pipeline secure.
• See [HashiCorp’s documentation] for steps to register self-hosted agents.

Alternatively, for advanced isolation, use AWS PrivateLink with a jump/bastion or an SSM bridge as described by AWS.

Comparing AWS PrivateLink (VPC Endpoint) vs. Self-Hosted Agent Runner for Private EKS Deployment

When deciding between using AWS PrivateLink (VPC Endpoint) and deploying a self-hosted agent runner in your AWS VPC for private EKS deployment (e.g., with Terraform Cloud), each approach differs in setup complexity, ongoing management, and cost. Here’s a practical, side-by-side breakdown:

1. AWS PrivateLink (VPC Endpoint) + Network Bridge

Description

• Exposes your EKS API or application endpoints privately within your VPC, accessible only to resources that reside within the same (or peered) VPCs.
• Requires a bridging mechanism: typically a bastion host, jumpbox, or session manager must be set up inside the VPC to bridge external systems (like TFC) to the private EKS API.

Pros

• Secure: Keeps traffic fully within AWS, never exposed to the public internet.
• Reduced data transfer cost: Eliminates the need for more expensive NAT Gateways in some setups, offering significant network cost savings per GB transferred.
• Simplifies network topology: Direct VPC-to-VPC or VPC-to-service communication; easy to scale by adding more endpoints for different services.

Cons

• Setup Complexity: You must configure PrivateLink endpoints and configure bastion hosts or equivalent network bridges, then securely manage bastion access.
• Maintenance Overhead: Bastions require hardening, patching, and ongoing management.
• Not a direct solution for TFC cloud: TFC (unless running an agent inside your VPC) cannot reach PrivateLink endpoints from the public internet. You’ll either need a bastion or to move to a self-hosted agent pattern anyway.

Cost Summary (Per Month Example)

Item	Rate	Example (5,000hr + 10TB)
Endpoint Hourly	$0.01/hr	$50
Data Processing	$0.01/GB	$100
Data Transfer (AWS)	Often free/intra-region	$0
Total		$150

In similar NAT Gateway scenarios, total network cost could be over $1,500/month versus $150/month with PrivateLink, showing 90%+ savings when substituting NAT Gateway for PrivateLink.

2. Self-Hosted (Agent) Runner in Your VPC

Description

• You deploy a self-hosted agent (an EC2 instance or Fargate task) within your VPC.
• This agent executes all Terraform Cloud jobs: it can reach your private EKS API endpoint directly (no bastion, no extra bridge).

Pros

• Easy integration with private resources: Agent, being inside the VPC, talks directly to private EKS, RDS, etc..
• Simpler architecture: No need for extra jumpboxes or manual session tunneling.
• Secure: Keeps your infrastructure and API access within your secured VPC.
• Recommended by Terraform Cloud for private infra: Official guidance from HashiCorp is to use self-hosted agents for deploying to private networks.

Cons

• EC2 instance cost: Running a dedicated agent incurs compute and (minor) storage cost.
• Agent maintenance: Occasional need for patching, scaling, and log management, but infrastructure is much simpler than managing bastions with PrivateLink.
• Still inside your AWS bill: Cost is very controllable—typically a single t3.medium/t3.large EC2 covers most needs.

Cost Summary (Typical, per agent)

Item	Ballpark Rate/Month	Example
EC2 (t3.medium)	$32	$32
EBS Storage	$1-2	$1-2
Data Transfer	VPC-internal/free	$0
Total		$33-34

Head-to-Head: Setup, Management, and Cost

Factor	PrivateLink + Bridge	Self-Hosted Agent Runner
Ease of Setup	Moderate to complex	Easier: just launch agent
Ongoing Management	Must maintain bastion(s), IAM, patching	Just agent maintenance
Cost	$150/mo (with data)	~$33/mo (agent typical)
Recommended by TFC?	Not direct, requires extra bridging	Yes: official preferred
Direct Integration with TFC	No	Yes

Recommendation

For most teams deploying to private EKS with Terraform Cloud:

• Deploying a Self-Hosted Agent Runner in your AWS VPC is the most recommended, easiest-to-manage, and most cost-effective solution.
  • No need for NAT Gateway or complex network bridges.
  • Lower running cost for typical CI/CD workloads.
  • Direct compatibility with Terraform Cloud’s automation tools.

Only use PrivateLink + Network Bridge if:

• You need to share your application across VPCs/account boundaries (e.g., SaaS with private endpoints), or you have other integration requirements that specifically need L4/L7 networking via PrivateLink.

Bottom line:
For seamless TFC-to-EKS automation that is easy to set up, maintain, and cost-optimal, choose a self-hosted agent runner in your AWS VPC.

Deploying to a Private EKS Cluster: PrivateLink with Bastion Host

When you want to keep your Amazon EKS cluster’s API endpoint private—but still require Terraform Cloud (TFC) or other automation to deploy to it—a proven solution is to combine AWS PrivateLink with a bastion host (jumpbox) inside your VPC. Here’s how this works, the architecture options, and key considerations.

How PrivateLink Secures EKS API Access

• AWS PrivateLink allows you to expose the EKS API as a private endpoint within your VPC.
• This means only resources inside the VPC (or those accessing via trusted connectivity such as VPC peering) can reach the EKS API. Public internet access is prevented.
• The PrivateLink interface endpoint creates elastic network interfaces (ENIs) in your VPC, serving as secure entry points for EKS API traffic.

Why Terraform Cloud Can’t Reach the Private API Directly

• TFC runs jobs from its managed, internet-based infrastructure.
• It cannot access resources reachable only on your private VPC network or via PrivateLink endpoints.
• To bridge this gap, you use a bastion host in your AWS network.

Bastion Host Pattern: How It Works

1. Bastion Host or Client Node Setup

• Launch an EC2 instance (the “bastion”) in a public subnet of your VPC.
• Install the necessary tools: kubectl, AWS CLI, and (if desired) Terraform itself.
• This instance should have an IAM role or credentials that permit access to the EKS cluster, with security group rules allowing it to reach the EKS API endpoint.

2. Restricting Access to the Bastion

• Best practice: Do not assign a public IP. Instead, access the instance via AWS Systems Manager Session Manager (SSM) for shell access, removing the need for SSH keys and public access.
• Only allow port 443 from the bastion’s security group to the EKS API endpoint private IP.

3. Running Terraform or Deployment Tools

• You may run Terraform (and the Kubernetes provider) directly on the bastion, or use it as a jump host for your automation.
• The workflow is:
  • TFC or your operator connects (often via SSM or SSH) to the bastion.
  • All kubectl, helm, or Terraform apply commands that interact with EKS run within the bastion environment.
  • The bastion uses the VPC PrivateLink endpoint to talk to the EKS API securely.

4. Securing and Automating

• Limit who can access the bastion using IAM policies and SSM session permissions.
• Use automation scripts or CI/CD pipelines that trigger Terraform runs or deployment scripts from inside the bastion.

Architectural Overview

Component	Purpose
EKS with PrivateLink	API accessible only inside VPC
Bastion host (jumpbox)	Bridge for deployment tools, limited to VPC network
TFC/CI/CD	Triggers deployment actions remotely
SSM/VPN (optional)	Secure connectivity to bastion (no public SSH)

Implementation Tips

• Place the bastion host in the same VPC (and preferably subnet) with access to the EKS PrivateLink endpoint.
• Grant the bastion IAM permissions for EKS and, if needed, for Terraform state management (S3, DynamoDB).
• Restrict security group and network ACLs so only trusted systems can reach the bastion, and only the bastion can reach EKS.
• Clean up or terminate the bastion when not needed, or use on-demand ephemeral instances for extra security.
• For production, consider:
  • Using SSM Session Manager for access (rather than public IP or SSH).
  • Enforcing audit logging and access controls on the bastion.
  • Regularly updating bastion software and patching.

Reference Use Cases and Guides

• AWS Official Docs: Explains creating PrivateLink endpoints for EKS and securing access.
• Community Guides: Cover setup with Terraform and detail how automation must be executed from inside the VPC (typically on the bastion).
• CI/CD Automation: TFC can trigger agents (scripts or self-hosted runners) set up inside the VPC, ideally using the bastion for both access and deployment orchestration.

Conclusion:
By combining AWS PrivateLink with a bastion host inside your VPC, you ensure EKS API endpoints are fully private—meeting strong security standards—while still enabling deployments from Terraform Cloud or any CI/CD system. All sensitive operations and credentials stay inside your protected network, dramatically reducing external exposure.