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'sregionis used (defaultde1). - Project: every taggable resource takes
project(a slug, see Projects). Left out, it goes into the provider'sproject(orDCLOUD_PROJECT), else Default. Changing it moves the resource and its parts; it is never replaced. List data sources show the provider's project.ews_projectis 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 -upgrademoves 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 mirrorcopies 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):
- Change
required_providerstodcloud = { source = "<console host>/dcloud/dcloud" }and theprovider "ews"block toprovider "dcloud". - Rename every
ews_type todcloud_, in resources, data sources and references. - Add one
movedblock per resource, thenterraform init -upgradeandterraform 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_recordand verify in the console.
Troubleshooting
HTTP 403on 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: setdeletion_protection = false, apply, then destroy. - A bucket will not delete (
409): it still holds objects or object versions. Empty it first.