LogoLogo
HomeBlogGitHubGet Started FreeLogin
Earthly 0.8
Earthly 0.8
  • 👋Introduction
  • 💻Install Earthly
  • 🎓Learn the basics
    • Part 1: A simple Earthfile
    • Part 2: Outputs
    • Part 3: Adding dependencies With Caching
    • Part 4: Args
    • Part 5: Importing
    • Part 6: Using Docker In Earthly
    • Part 7: Using remote runners
    • Part 8a: Using Earthly in your current CI
    • Final words
  • ⭐Featured guides
    • Rust
  • 📖Docs
    • Guides
      • Importing
      • Build arguments and variables
      • Secrets
      • Functions
      • Using Docker in Earthly
      • Multi-platform builds
      • Authenticating Git and image registries
      • Integration Testing
      • Debugging techniques
      • Podman
      • Configuring registries
        • AWS ECR
        • GCP Artifact Registry
        • Azure ACR
        • Self-signed certificates
      • Using the Earthly Docker Images
        • earthly/earthly
        • earthly/buildkitd
      • ✅Best practices
    • Caching
      • Caching in Earthfiles
      • Managing cache
      • Caching via remote runners
    • Remote runners
    • Earthfile reference
      • Builtin args
      • Excluding patterns
      • Version-specific features
    • The earthly command
    • Earthly lib
    • Configuration reference
    • Examples
    • Misc
      • Alternative installation
      • Data collection
      • Definitions
      • Public key authentication
  • 🔧CI Integration
    • Overview
    • Use the Earthly CI Image
    • Build your own Earthly CI Image
    • Pull-Through Cache
    • Remote BuildKit
    • Vendor-Specific Guides
      • GitHub Actions
      • Circle CI
      • GitLab CI/CD
      • Jenkins
      • AWS CodeBuild
      • Google Cloud Build
      • Bitbucket Pipelines
      • Woodpecker CI
      • Kubernetes
  • ☁️Earthly Cloud
    • Overview
    • Managing permissions
    • Cloud secrets
    • Earthly Satellites
      • Managing Satellites
      • Using Satellites
      • Self-Hosted Satellites
      • GitHub runners
      • Best Practices
      • Bring Your Own Cloud (BYOC)
        • AWS
          • Requirements
          • CloudFormation
          • Terraform
          • Manual
        • VPN
          • Tailscale
Powered by GitBook
On this page
  • Requirements
  • Installation
  • Quickstart
  • Colocating With Other Terraform Code
  • Module Parameters
  • Module Inputs
  • Module Outputs

Was this helpful?

Edit on GitHub
  1. Earthly Cloud
  2. Earthly Satellites
  3. Bring Your Own Cloud (BYOC)
  4. AWS

Terraform

PreviousCloudFormationNextManual

Last updated 10 months ago

Was this helpful?

This page documents the requirements and steps required to install in AWS using Earthly's Terraform module.

Requirements

Before you begin to provision your BYOC configuration, ensure that you meet the for installation within AWS.

There are also a few additional requirements you will need to make sure you meet:

  • Terraform is installed, and on your $PATH.

  • An AWS account or role that can create all the resources specified in the module.

  • You have permission to list Terraform outputs.

Installation

You can find our module in the . If you're curious about what we're provisioning, you can look at our .

Quickstart

Place the following code into a file named byoc.tf, in an empty directory:

module "byoc" {
  source  = "earthly/byoc/aws"
  version = "0.0.10"

  cloud_name = "my-cloud"
  subnet = "subnet-0123456789abcde01"
}

output "my-cloud" {
  value = module.byoc.automatic_installation
}

Open your terminal, and navigate to the directory with byoc.tf in it. Run terraform init && terraform apply, and inspect the resources it wants to create. If they appear ok, type yes to create them.

After Terraform finishes running, you can link this freshly provisioned infrastructure to an Earthly cloud by running:

earthly cloud install --via terraform --name my-cloud

Assuming the installation reports the status as Green, you should be good to go!

Colocating With Other Terraform Code

  1. The installation command is run in the same directory as the module containing your BYOC block.

  2. The automatic_installation output is exported. The name of the output is the value used for the --name parameter.

We recommend that the name of the output matches the name in the cloud_name of the module, to ensure that naming is consistent between AWS, your tooling, and Earthly.

Module Parameters

Module Inputs

Name
Description

cloud_name

The name to use to identify the cloud installation. Used by Earthly during automatic installation, and to mark related resources in AWS.

subnet

The subnet Earthly will deploy satellites into.

ssh_public_key

(Optional) The SSH key to include in provisioned satellites. If left unspecified, a new key is generated, and the private key is available as an output.

Module Outputs

Name
Description

installation_name

The name to use to identify the cloud installation. Used by Earthly during automatic installation, and to mark related resources in AWS.

security_group_id

The ID of the security group for new satellites.

ssh_key_name

The name of the SSH key in AWS that is included in new satellites.

ssh_private_key

(Sensitive) The private key, if ssh_public_key is unspecified.

instance_profile_arn

The ARN of the instance profile satellite instances will use for logging.

compute_role_arn

The ARN of the role Earthly will assume to orchestrate satellites on your behalf.

automatic_installation

All items needed to perform an automatic installation, bundled into one output.

You can use the module as explained in . However, if you would like to also enable automatic installation, some additional conditions apply:

☁️
BYOC Satellites
base requirements
public Terraform Registry
source code
Quickstart