Terraform & OpenTofu

Manage Deutsche Cloud resources as code with the ews provider.

The dcloud provider manages Deutsche Cloud resources from Terraform or OpenTofu: networks, instances, volumes, managed Postgres and Valkey, buckets, DNS, deploy apps, IAM and Secrets. It signs in with an access key and can do exactly what that key's IAM user is allowed to do.

Concepts

  • Access key: EWS1…:secret, created under IAM → Access keys. The provider sends it the same way the CLI does.
  • Region: resources that live in a region take region_id; when you leave it out, the provider's region is used (default de1).
  • Project: every taggable resource takes project (a slug, see Projects). Left out, it goes into the provider's project (or DCLOUD_PROJECT), else Default. Changing it moves the resource and its parts; it is never replaced. List data sources show the provider's project. ews_project is a saved view (a tag query), not a project.
  • In place or replaced: an argument that the API can change on a live resource is updated in place. Every other argument replaces the resource when it changes, and the plan says so.
  • Secrets stay in Secrets: database master passwords, login passwords and cache passwords are generated by Deutsche Cloud and filed in Secrets. The provider exposes the secret's id, never the password.

Install the provider

Every Deutsche Cloud console is also a provider registry, for Terraform and OpenTofu alike. The provider's source address is the console's host name followed by dcloud/dcloud; terraform init (or tofu init) downloads it from there, checks the SHA-256 sums and their OpenPGP signature, and records the version and hashes in .terraform.lock.hcl as it does for any provider. No .terraformrc and no account are needed.

terraform {
  required_providers {
    dcloud = {
      source  = "console.example.com/dcloud/dcloud" # your console's host
      version = "~> 0.1"
    }
  }
}
  • Versions: the console serves every version it has ever served, so a lock file keeps working after the console is upgraded. terraform init -upgrade moves to the newest.
  • Platforms: Linux, macOS and Windows, each on amd64 and arm64.
  • Signing: each console signs with its own key, generated the first time it publishes a version. The key comes with the download, over the console's TLS connection; the lock file then pins the exact hashes.
  • Air-gapped: terraform providers mirror copies the provider out of a console like out of any registry.

To work on the provider itself, build it and use a development override instead:

cd ews/terraform && go build -o ~/.terraform.d/dcloud/terraform-provider-dcloud .
# ~/.terraformrc (Terraform) or ~/.tofurc (OpenTofu)
provider_installation {
  dev_overrides { "console.example.com/dcloud/dcloud" = "/home/you/.terraform.d/dcloud" }
  direct {}
}

Configure it

terraform {
  required_providers {
    dcloud = { source = "console.example.com/dcloud/dcloud" }
  }
}

provider "dcloud" {
  endpoint = "https://console.example.com" # or DCLOUD_ENDPOINT
  region   = "de1"                         # or DCLOUD_REGION
  project  = "shop"                        # optional, or DCLOUD_PROJECT
  # access_key from DCLOUD_ACCESS_KEY
}

Coming from the ews provider

The provider was called ews (source = "<console host>/ews/ews", types ews_*). That name keeps working, unchanged, until at least 31 December 2027: the console serves every new version under both names, and old versions stay where they were, so existing lock files keep matching. Runs under the old name show one warning.

To switch a configuration (Terraform 1.8 or newer; nothing is replaced):

  1. Change required_providers to dcloud = { source = "<console host>/dcloud/dcloud" } and the provider "ews" block to provider "dcloud".
  2. Rename every ews_ type to dcloud_, in resources, data sources and references.
  3. Add one moved block per resource, then terraform init -upgrade and terraform plan. The plan shows only moves.
moved {
  from = ews_vpc.main
  to   = dcloud_vpc.main
}

EWS_ENDPOINT, EWS_ACCESS_KEY and EWS_REGION are still read when the DCLOUD_ names are not set. Data sources need no moved block. Once the plan is clean, the moved blocks can be deleted (after every workspace that uses the configuration has applied them).

Create a network, a machine and a database

data "dcloud_images" "x86" { architecture = "x86_64" }

resource "dcloud_vpc" "main" {
  name       = "main"
  cidr_block = "10.10.0.0/16"
}

resource "dcloud_security_group" "web" { name = "web" }

resource "dcloud_security_group_rule" "https" {
  security_group_id = dcloud_security_group.web.id
  direction         = "inbound"
  protocol          = "tcp"
  from_port         = 443
  to_port           = 443
}

resource "dcloud_key_pair" "me" {
  name       = "me"
  public_key = file("~/.ssh/id_ed25519.pub")
}

resource "dcloud_instance" "web" {
  name               = "web-1"
  server_type        = "performance-2"
  image_id           = [for i in data.dcloud_images.x86.items : i.id if i.name == "debian-13"][0]
  vpc_id             = dcloud_vpc.main.id
  ssh_key_pair_id    = dcloud_key_pair.me.id
  security_group_ids = [dcloud_security_group.web.id]
}

resource "dcloud_db_instance" "main" {
  identifier          = "main"
  instance_class      = "performance-4"
  vpc_id              = dcloud_vpc.main.id
  deletion_protection = true
}

resource "dcloud_db_login" "app" {
  db_instance_id = dcloud_db_instance.main.id
  name           = "app"
  access         = "readwrite"
}

terraform apply waits until the instance is running and the database is available. terraform destroy waits until they are gone.

Import what already exists

terraform import dcloud_db_instance.main ewdb-0123456789ab
terraform import dcloud_db_login.app <database-id>/<login-id>

Child resources are imported as <parent-id>/<id>: security group rules, database logins, DNS records, app domains, volume attachments and policy attachments.

Reference

Resource What it manages Changes in place
dcloud_vpc A private network tags
dcloud_security_group A firewall tags
dcloud_security_group_rule One rule of a security group —
dcloud_instance A virtual machine name, security_group_ids, server_type (stop, resize, start), tags
dcloud_volume A block storage volume tags
dcloud_volume_attachment A volume attached to an instance —
dcloud_key_pair An SSH public key tags
dcloud_db_instance Managed PostgreSQL instance class, storage, backups, deletion protection, TLS requirement, tags
dcloud_db_login A Postgres login valid_until
dcloud_cache_cluster Managed Valkey eviction_policy, tags
dcloud_bucket An S3 bucket —
dcloud_dns_zone, dcloud_dns_record A hosted zone and its record sets record ttl, values, app_id
dcloud_app A deploy app everything the console's app settings change
dcloud_app_env An app's whole environment all of it
dcloud_app_domain A custom domain on an app —
dcloud_iam_user An IAM user or service account —
dcloud_iam_role An IAM role trust_policy
dcloud_iam_policy A custom IAM policy name, description, document
dcloud_iam_oidc_provider An OpenID Connect identity provider audiences
dcloud_iam_*_policy_attachment A policy attached to a user or role —
dcloud_audit_destination Audit log export or alarm name, enabled, filter_actions, filter_outcome; config is jsonencoded
dcloud_secret A secret value (a rotation: a new version), tags
dcloud_schedule A schedule (cron/rate/at) everything but name; target is jsonencoded, the API's shape
dcloud_event_bus A custom event bus — (the default bus needs no resource)
dcloud_event_rule A rule on an event bus everything but event_bus, name; event_pattern, targets are jsonencoded
dcloud_event_archive An archive of an event bus description, event_pattern (jsonencoded), retention_days

More resources, by area (each imports by its id, or <parent-id>/<id> for a child):

Area Resources
Network dcloud_subnet, dcloud_eip, dcloud_eip_association, dcloud_nat_gateway, dcloud_lb, dcloud_lb_service, dcloud_lb_target, dcloud_vpn_endpoint, dcloud_vpn_peer
Compute dcloud_machine_image, dcloud_snapshot_policy, dcloud_volume_snapshot, dcloud_launch_template, dcloud_autoscaling_group, dcloud_autoscaling_policy, dcloud_autoscaling_schedule, dcloud_ssh_key_pair_generated
Kubernetes dcloud_eks_cluster, dcloud_eks_nodegroup, dcloud_eks_pod_identity_association, dcloud_eks_access_entry, dcloud_eks_access_policy_association
Databases and caches dcloud_db_read_replica, dcloud_db_extension, dcloud_db_parameters, dcloud_app_database_binding, dcloud_app_cache_binding
Storage dcloud_bucket_versioning, dcloud_bucket_policy, dcloud_bucket_public_access_block, dcloud_bucket_website, dcloud_bucket_domain, dcloud_bucket_lifecycle, dcloud_bucket_replication, dcloud_s3_access_key, dcloud_file_system, dcloud_queue
Keys, DNS, registries dcloud_kms_key, dcloud_dns_zone_dnssec, dcloud_dns_query_log, dcloud_ecr_repository, dcloud_ecr_lifecycle_policy
IAM and organization dcloud_iam_group, dcloud_iam_group_membership, dcloud_iam_group_policy_attachment, dcloud_iam_user_role_assignment, dcloud_iam_access_key, dcloud_iam_user_login_profile, dcloud_iam_password_policy, dcloud_iam_grant, dcloud_iam_sso_connection, dcloud_iam_sso_domain, dcloud_project, dcloud_tag_policy, dcloud_budget, dcloud_ai_settings
Secrets dcloud_secrets_environment, dcloud_secrets_source, dcloud_secret_grant
Apps and code dcloud_app_job, dcloud_app_registry_credentials, dcloud_function, dcloud_git_repository, dcloud_git_branch_protection, dcloud_git_tag_protection, dcloud_git_deploy_key, dcloud_git_webhook, dcloud_git_ssh_key
Monitoring and email dcloud_uptime_check, dcloud_monitoring_alarm, dcloud_status_page, dcloud_status_page_subscriber, dcloud_email_identity, dcloud_email_suppression

Secrets the API hands over only once (dcloud_iam_access_key, dcloud_s3_access_key, dcloud_ssh_key_pair_generated) are kept in the state, marked sensitive: protect the state accordingly.

Data sources: dcloud_regions, dcloud_availability_zones, dcloud_server_types, dcloud_images, dcloud_db_instance_classes, dcloud_cache_node_types, dcloud_kms_keys, dcloud_subnets, dcloud_eks_versions, dcloud_iam_users, dcloud_iam_roles, dcloud_iam_policies, dcloud_monitoring_check_locations. Each returns items, a list of objects.

Every argument, its type, default and range is listed on the provider's per-resource pages in terraform/docs/ of the Deutsche Cloud repository.

Tags. Once a configuration sets tags, only the keys it names are compared. Tags Deutsche Cloud adds by itself (inherited from an owner, or filled in by a tag policy) never show as a change.

Never read back. dcloud_instance.user_data, dcloud_instance.enable_public_ipv4, dcloud_secret.value, dcloud_app_env.redeploy and dcloud_schedule.failure_alarm are sent to the API and not returned by it. They are empty after an import.

What is not supported

  • The public Terraform and OpenTofu registries (registry.terraform.io, registry.opentofu.org): install from your console (see above).
  • Changing an IAM user, a security group's name or description, or a bucket after creation: each is replaced.
  • Things that are not infrastructure: invitations, payment methods, npm and CI runner tokens, git personal access tokens. One-off cache and file system snapshots, CI runs and deployments are actions, not resources; use the CLI or the API.
  • Verifying an SSO domain (it needs a DNS TXT record the provider cannot prove); add the record with dcloud_dns_record and verify in the console.

Troubleshooting

  • HTTP 403 on apply: the access key's IAM user lacks the action named in the error. Attach a policy that allows it.
  • Destroying a database fails with deletion protection: set deletion_protection = false, apply, then destroy.
  • A bucket will not delete (409): it still holds objects or object versions. Empty it first.
Did this page help you?