Skip to content

Latest commit

 

History

History
235 lines (189 loc) · 9.7 KB

terraform.md

File metadata and controls

235 lines (189 loc) · 9.7 KB

Terraform / OpenTofu

CloudEmu speaks the real cloud wire protocols, so Terraform and OpenTofu run against it as they are (init, apply, plan, destroy), with no extra plugins or shims. Point the provider's endpoints at a running CloudEmu and apply your resources unchanged. The HCL is the same for Terraform and OpenTofu.

CI checks this on every run: contrib/terraform drives a real tofu binary through apply → plan → destroy against CloudEmu and asserts that the plan after apply is empty (no perpetual diff). See What's verified.

Fastest path: the cloudemu-tf wrapper

contrib/terraform/cloudemu-tf is a wrapper similar to LocalStack's tflocal. It writes a provider override that points at CloudEmu, supplies dummy credentials, and then runs the real tofu/terraform:

# 1. start CloudEmu (AWS on :4566)
cloudemu serve &

# 2. put the wrapper on your PATH
ln -s "$PWD/contrib/terraform/cloudemu-tf" /usr/local/bin/cloudemu-tf

# 3. run terraform as usual, from a dir with your .tf files
cloudemu-tf init
cloudemu-tf apply

Your config only needs an empty provider block, with no endpoints, credentials or skip flags:

provider "aws" {}

Configure the wrapper with env vars:

Variable Default Meaning
CLOUDEMU_ENDPOINT http://localhost:4566 CloudEmu AWS endpoint
AWS_REGION us-east-1 region to report
CLOUDEMU_TF_BIN tofu, then terraform binary to run

The wrapper leaves a cloudemu_providers_override.tf next to your config. It is regenerated on each run, so you can delete it or add it to .gitignore.

Manual provider config (AWS)

Without the wrapper, add the endpoints yourself. It is the same block you would use for LocalStack or floci:

provider "aws" {
  access_key = "test"
  secret_key = "test"
  region     = "us-east-1"

  # CloudEmu is path-style and needs no real-AWS preflight.
  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    ec2      = "http://localhost:4566"
    iam      = "http://localhost:4566"
    sts      = "http://localhost:4566"
    # ...one line per additional service you use
  }
}

Azure and GCP

CloudEmu serves Azure on :4568 (HTTPS) and GCP on :4569. The HTTPS ports use a self-signed cert, so point your client at the CloudEmu CA or disable verification for local use.

GCP: the google provider accepts a per-service *_custom_endpoint, so point each service you use at the GCP port:

provider "google" {
  project = "cloudemu" # run serve with --project-id cloudemu
  # e.g. storage_custom_endpoint = "http://localhost:4569/storage/v1/"
}

GCP resources are scoped to the project in the request path, so two provider aliases with different project values keep same-named resources apart. Pub/Sub, Secret Manager and IAM custom roles are scoped this way today. Resources created through the Go API, --init-dir seeds, and project-less state restored from an older snapshot belong to --project-id (default cloudemu-local). Set --project-id to the project your provider or SDK uses.

Shared REST paths and the API alias

Some GCP services serve identical REST paths on different hosts. GKE and Managed Kafka both serve /v1/projects/{p}/locations/{l}/clusters, and Filestore, Memorystore for Redis, Data Fusion and Secure Source Manager all serve .../locations/{l}/instances. On a single port CloudEmu tells them apart by the body, the path shape and which service owns the id. A collection list in a location where two of them own resources cannot be told apart that way.

To name the API explicitly, put its googleapis host as the first path segment of the endpoint. CloudEmu strips that segment before routing. Always end the endpoint with the version segment the provider expects (/v1/), as with any custom endpoint:

provider "google" {
  container_custom_endpoint     = "http://localhost:4569/container.googleapis.com/v1/"
  managed_kafka_custom_endpoint = "http://localhost:4569/managedkafka.googleapis.com/v1/"
  filestore_custom_endpoint     = "http://localhost:4569/file.googleapis.com/v1/"
  redis_custom_endpoint         = "http://localhost:4569/redis.googleapis.com/v1/"
}

Go clients take the same form without the version, which they append: option.WithEndpoint("http://localhost:4569/managedkafka.googleapis.com"). A Host: <api>.googleapis.com header (from a proxy, /etc/hosts or curl -H) works the same way.

Alias host Shared path it disambiguates
container.googleapis.com, alloydb.googleapis.com, managedkafka.googleapis.com locations/{l}/clusters
file.googleapis.com, redis.googleapis.com, datafusion.googleapis.com, securesourcemanager.googleapis.com locations/{l}/instances
securesourcemanager.googleapis.com, artifactregistry.googleapis.com, dataform.googleapis.com locations/{l}/repositories
ids.googleapis.com, us-central1-aiplatform.googleapis.com (region named literally) locations/{l}/endpoints
gkebackup.googleapis.com, backupdr.googleapis.com locations/{l}/backupPlans
spanner.googleapis.com, sqladmin.googleapis.com /v1/projects/{p}/instances

Without a hint, these pairs are told apart by body, path shape and ownership: a Cloud IDS create carries severity/network and no displayName; a Filestore create carries a Filestore tier, and zonal locations are Filestore's; a Backup and DR plan carries backupVault/backupRules/resourceType; a Dataform repository carries Dataform fields and no format; and a v1 instance list is Spanner's only when it pages with pageSize or Spanner owns an instance in the project. In a project that has both Spanner and Cloud SQL instances, list Cloud SQL through /sqladmin.googleapis.com/v1/.

Any other *.googleapis.com first segment is stripped and otherwise ignored, so http://localhost:4569/storage.googleapis.com/storage/v1/ is the same as http://localhost:4569/storage/v1/.

AlloyDB creates, reads, updates and deletes work without the alias, so a plain alloydb_custom_endpoint = "http://localhost:4569/v1/" serves Terraform. An AlloyDB list (a data source, gcloud, or an SDK ListClusters) needs the alias, since unhinted cluster lists are GKE's. GKE and AlloyDB clusters cannot share a name, in any location; the second create gets 409 ALREADY_EXISTS. Managed Kafka and AlloyDB may reuse a cluster id; unhinted item calls then reach Managed Kafka. Use the alias to address the AlloyDB cluster.

Without the alias, a list in a location where two services own resources goes to the first registered owner (GKE for clusters). URLs CloudEmu returns in responses, such as an operation selfLink, do not carry the alias; clients poll operations by name, so this does not affect them.

Azure: the azurerm provider has no per-service endpoint override. It reads every endpoint from an Azure metadata document and gets a bearer token from an AAD OAuth2 endpoint. CloudEmu serves both. Set ARM_METADATA_HOSTNAME to the Azure port and the unmodified azurerm provider starts up against the emulator. The metadata document CloudEmu returns points back at itself, so Resource Manager and token requests also go to the emulator.

The azurerm provider is a Go binary that always verifies TLS (there is no skip-verify flag), so it has to trust CloudEmu's cert. Run the Azure port with a cert you generate, then give the same cert to Terraform through SSL_CERT_FILE. Go's TLS stack honors that on Linux; on macOS, run Terraform in a Linux container or add the cert to the system keychain:

# 1. a cert whose SANs cover the host Terraform dials
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 2 \
  -subj "/CN=cloudemu" \
  -addext "subjectAltName=IP:127.0.0.1,DNS:localhost" \
  -addext "basicConstraints=critical,CA:TRUE"

# 2. serve Azure with that cert
cloudemu serve -providers=azure -azure-port 4568 \
  -tls-cert cert.pem -tls-key key.pem \
  -azure-subscription 00000000-0000-0000-0000-0000000000ab
# 3. Terraform env: any credentials work (CloudEmu doesn't verify them by default)
export ARM_METADATA_HOSTNAME=127.0.0.1:4568
export ARM_SUBSCRIPTION_ID=00000000-0000-0000-0000-0000000000ab
export ARM_TENANT_ID=11111111-1111-1111-1111-111111111111
export ARM_CLIENT_ID=00000000-0000-0000-0000-000000000001
export ARM_CLIENT_SECRET=any
export ARM_RESOURCE_PROVIDER_REGISTRATIONS=none
export SSL_CERT_FILE=$PWD/cert.pem

The config needs only an empty provider block:

provider "azurerm" {
  features {}
}

init → apply → plan(no-diff) → destroy then runs unchanged. This was checked with azurerm v4 against azurerm_resource_group and azurerm_storage_account.

AWS is the most tested provider today and the only one with an automated idempotency suite. The GCP block above works, and the Azure recipe was tested by hand, but neither is covered by the suite yet. Fixtures for either are welcome.

What's verified

The contrib/terraform suite checks apply → plan(no-diff) → destroy against a real Terraform binary. It currently covers:

  • S3: aws_s3_bucket
  • DynamoDB: aws_dynamodb_table (PAY_PER_REQUEST and PROVISIONED)
  • IAM: aws_iam_role
  • Networking: aws_vpc, aws_subnet, aws_security_group, aws_route_table, aws_route_table_association
  • The wrapper: the same flow through cloudemu-tf with only an empty provider block

contrib/terraform/README.md lists the known limits (for example, which sub-resources are not persisted yet). To run the suite locally:

cd contrib/terraform
go test ./...   # needs a tofu or terraform binary on PATH