Unit 2.4: Storage Provisioning as Code
Introduction
TaskBoard now has compute, a segmented network and a load balancer. It still stores everything on the API server's system disk, and users cannot upload attachments yet. You need a data volume that survives a server rebuild, a bucket for uploaded files, and credentials your application can read from Terraform outputs.
In this unit you provision the storage tier as code. You add a Block Storage data volume with the right performance class and zone, create an IONOS Cloud Object Storage bucket with its own access key, connect the remote-state pattern from Unit 1.2, and see how Network File Storage (NFS) follows the same pattern for shared files. In the Code Lab you deploy TaskBoard's storage tier and verify the bucket with an S3 client.
1. Block Storage with ionoscloud_volume
resource "ionoscloud_volume" "api_data" {
datacenter_id = ionoscloud_datacenter.taskboard.id
server_id = ionoscloud_server.api.id
name = "taskboard-api-data"
size = 100
disk_type = "PERFORMANCE"
availability_zone = "ZONE_1"
licence_type = "UNKNOWN"
bus = "VIRTIO"
}
The data volume is separate from the server's inline system volume, so you can rebuild the server without losing data. licence_type (or image_name) is required; for a secondary data volume the provider documentation asks for UNKNOWN. server_id attaches the volume; leave it unset for an unattached volume.
1.1 Choosing the Performance Class
disk_type takes ESSENTIAL, BALANCED or PERFORMANCE for the Block Storage performance classes, and it is immutable. Essential is a cost-efficient class for data such as backups and archives, Balanced is a general-purpose class for web servers and development environments, and Performance is a high-throughput class for data that requires low latency, such as databases. The following table shows the limits per class:
| Storage Volume | Essential | Balanced | Performance |
|---|---|---|---|
| Minimum size per volume | 1 GB | 1 GB | 1 GB |
| Maximum size per volume | 4 TB | 4 TB | 4 TB |
| Maximum Read/write speed, sequential | 200 MB/s (static per instance) | 300 MB/s per volume at 1 MB block size | 600 MB/s per volume at 1 MB block size |
| Maximum Read speed, full random | 1,100 (static per instance) | 24,000 IOPS at 4 KB block size and minimum 2 Cores, 2 GB RAM per volume | 45,000 IOPS at 4 KB block size and minimum 4 Cores, 4 GB RAM per volume |
| Maximum Write speed, full random | 1,100 (static per instance) | 18,000 IOPS at 4 KB block size and minimum 2 Cores, 2 GB RAM per volume | 30,000 IOPS at 4 KB block size and minimum 4 Cores, 4 GB RAM per volume |
As shown above, Essential performance is static, while Balanced and Performance scale with the volume size: Performance delivers 75 IOPS per GB for full random reads at 4 KB block size. IONOS CLOUD recommends at least 100 GB to get the full benefit of the SSD classes, and volumes larger than 600 GB reach the maximum values. TaskBoard's API server has 4 cores and 8 GB RAM, so a 100 GB Performance volume fits its database-like workload.
1.2 The Availability Zone Constraint
resource "ionoscloud_server" "api" {
# ...
availability_zone = "ZONE_1" # servers: AUTO, ZONE_1, ZONE_2
}
resource "ionoscloud_volume" "api_data" {
# ...
availability_zone = "ZONE_1" # volumes: AUTO, ZONE_1, ZONE_2, ZONE_3
}
Block Storage offers Zone 1, Zone 2, Zone 3 and Auto. Compute offers Zone 1, Zone 2 and Auto only, so a variable shared by servers and volumes must not allow ZONE_3:
variable "server_zone" {
type = string
default = "ZONE_1"
validation {
condition = contains(["AUTO", "ZONE_1", "ZONE_2"], var.server_zone)
error_message = "Servers support AUTO, ZONE_1 or ZONE_2 only."
}
}
The volume's zone is immutable. To move a volume to another zone, create a snapshot (Unit 2.1) and provision a new volume from it.
1.3 Resizing
You can increase size in code after provisioning, even while the server is running if the operating system supports it. Reducing the size is impossible. After an increase, extend the partition and file system inside the guest.
2. IONOS Cloud Object Storage as Code
IONOS Cloud Object Storage is compatible with the S3 protocol and authenticates with a pair of keys: an Access Key and a Secret Key. It does not use the bearer token of the Cloud API. Object Storage is not enabled by default; a contract owner or administrator enables it.
2.1 Provider Credentials and the Bucket
The provider manages buckets with an existing key pair, which you pass through the environment (Unit 1.2):
export IONOS_S3_ACCESS_KEY="<access key>"
export IONOS_S3_SECRET_KEY="<secret key>"
export IONOS_S3_REGION="eu-central-3"
resource "ionoscloud_s3_bucket" "uploads" {
name = "taskboard-uploads-dev-7f3a"
region = "eu-central-3"
force_destroy = false
tags = {
app = "taskboard"
env = "dev"
}
}
The bucket name must be unique across all IONOS accounts in all Object Storage regions and has 3 to 63 characters, so add a random or environment suffix. The region must match the global region (IONOS_S3_REGION or the s3_region provider attribute) or the global region must be unset. Contract-owned buckets are available in eu-central-3, eu-central-4 and us-central-1; their endpoint follows the pattern s3.<region>.ionoscloud.com.
With force_destroy = false, Terraform refuses to delete a bucket that still contains objects. Set it to true only for ephemeral environments, because it irreversibly deletes all contents.
2.2 Application Credentials
TaskBoard should not use your personal key. Create a dedicated key in Terraform and expose it as sensitive outputs:
resource "ionoscloud_object_storage_accesskey" "taskboard" {
description = "taskboard-api uploads"
}
output "uploads_access_key" {
value = ionoscloud_object_storage_accesskey.taskboard.accesskey
sensitive = true
}
output "uploads_secret_key" {
value = ionoscloud_object_storage_accesskey.taskboard.secretkey
sensitive = true
}
The accesskey attribute is a string of 92 characters. A user can have up to 5 access keys, so clean up keys of destroyed environments. To create a key for a separate IONOS CLOUD user instead, use ionoscloud_s3_key with that user's user_id; its computed secret_key attribute also belongs in a sensitive output.
sensitive = true hides the values in plan and apply output, but they are still stored in plain text in the state. That is one more reason for the access-controlled remote state below.
2.3 The Bucket as Terraform Backend
Unit 1.2 configured the s3 backend against an IONOS Cloud Object Storage endpoint. Create the state bucket once, outside the configuration it stores, for example in a small bootstrap project:
resource "ionoscloud_s3_bucket" "tfstate" {
name = "taskboard-tfstate-7f3a"
region = "eu-central-3"
}
resource "ionoscloud_s3_bucket_versioning" "tfstate" {
bucket = ionoscloud_s3_bucket.tfstate.name
versioning_configuration {
status = "Enabled"
}
}
Versioning lets you recover an earlier state file after a bad apply. The backend block itself stays as shown in Unit 1.2 and authenticates with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
3. Network File Storage
NFS is a same-pattern reference for TaskBoard: you use it only if several servers must share files. It is a managed shared storage service that VMs reach over a private LAN using NFSv4.2.
resource "ionoscloud_nfs_cluster" "shared" {
name = "taskboard-shared"
location = "de/txl"
size = 2048
size_unit = "GiB"
nfs {
min_version = "4.2"
}
connections {
datacenter_id = ionoscloud_datacenter.taskboard.id
lan = ionoscloud_lan.app.id
ip_address = "10.10.1.8/24"
}
}
resource "ionoscloud_nfs_share" "attachments" {
location = "de/txl"
cluster_id = ionoscloud_nfs_cluster.shared.id
name = "attachments"
quota = 102400
uid = 1000
gid = 1000
client_groups {
description = "app tier"
ip_networks = ["10.10.1.0/24"]
hosts = ["10.10.1.11"]
nfs {
squash = "root-anonymous"
}
}
}
Key differences from Block Storage:
- Size: the cluster ranges from 2 TiB to 42 TiB in 1 TiB increments, and can only be increased, not decreased.
- Shares: each share has an optional
quotain MiB;0disables it. - Squash:
none,root-anonymousorall-anonymousmaps client users to the anonymous ID. - Connection: the cluster gets an address in your private LAN; use one from the managed-services range (Unit 2.2).
- Mounting: clients mount with
mount -t nfs <cluster-ip>:<share-uuid> <local-mount-path>.
The NFS API is regional (https://nfs.{region}.ionos.com), and NFS is not available in gb/bhx.
4. Choosing Storage in Code
| Access pattern | Service | Terraform resource |
|---|---|---|
| One server reads and writes blocks (database files, application data) | Block Storage | ionoscloud_volume |
| Many clients read and write objects over HTTP (uploads, static assets, backups, Terraform state) | IONOS Cloud Object Storage | ionoscloud_s3_bucket |
| Several servers share a POSIX file system in a private LAN | Network File Storage | ionoscloud_nfs_cluster, ionoscloud_nfs_share |
As the table shows, the deciding question is who accesses the data and over which protocol. TaskBoard uses Block Storage for the API server's data volume and Object Storage for user uploads. In Unit 2.5 the transactional data moves to a managed PostgreSQL cluster, so the data volume then holds only local working files.
import boto3
s3 = boto3.client(
"s3",
endpoint_url="https://s3.eu-central-3.ionoscloud.com",
aws_access_key_id=ACCESS_KEY,
aws_secret_access_key=SECRET_KEY,
region_name="eu-central-3",
)
s3.upload_file("report.pdf", "taskboard-uploads-dev-7f3a", "tasks/42/report.pdf")
The application side needs only the endpoint and the key pair from the outputs in Section 2.2. Module 4 covers the integration in depth.
API Reference Quick Card
Key API endpoints behind this unit's resources:
| Method | Endpoint | Description |
|---|---|---|
POST |
/datacenters/{datacenterId}/volumes |
Created by ionoscloud_volume (Cloud API) |
POST |
/datacenters/{datacenterId}/servers/{serverId}/volumes |
Attaches a volume to a server (Cloud API) |
PUT |
/{bucket} |
Creates a bucket (S3 API, https://s3.<region>.ionoscloud.com) |
POST |
/clusters |
Created by ionoscloud_nfs_cluster (NFS API, https://nfs.{region}.ionos.com) |
POST |
/clusters/{clusterId}/shares |
Created by ionoscloud_nfs_share (NFS API) |
Base URL: https://api.ionos.com/cloudapi/v6 (Object Storage and NFS use their own endpoints, shown above)
Authentication: Authorization: Bearer <token> (Object Storage: Access Key and Secret Key)
Code Lab
Objective: Deploy TaskBoard's storage tier with Terraform: a Block Storage data volume attached to the API server and an Object Storage bucket with its own access key, with the credentials as sensitive outputs.
Prerequisites:
- The project from Units 2.1 to 2.3 with
IONOS_TOKENset - An existing Object Storage key pair in
IONOS_S3_ACCESS_KEYandIONOS_S3_SECRET_KEY, andIONOS_S3_REGION=eu-central-3 - The AWS CLI installed locally
Step 1: Add the data volume
Add ionoscloud_volume.api_data from Section 1. Set its availability_zone to AUTO, or to the zone you set on the server, then plan:
terraform plan | grep "will be created"
Expected output:
# ionoscloud_volume.api_data will be created
Step 2: Add the bucket and the access key
Add ionoscloud_s3_bucket.uploads (with your own unique suffix), ionoscloud_object_storage_accesskey.taskboard and both outputs from Section 2.2. Then apply:
terraform apply -auto-approve | tail -n 5
Expected output:
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
Outputs:
uploads_access_key = <sensitive>
uploads_secret_key = <sensitive>
Step 3: Mount the volume on the API server
ssh root@"$(terraform output -raw api_public_ip)" 'lsblk -o NAME,SIZE,TYPE,MOUNTPOINT'
Expected output:
NAME SIZE TYPE MOUNTPOINT
vda 20G disk
└─vda1 20G part /
vdb 100G disk
Format and mount vdb (for example with mkfs.ext4 and an /etc/fstab entry), or add those steps to the cloud-config of a rebuilt server.
Step 4: Configure the AWS CLI with the new key
export AWS_ACCESS_KEY_ID="$(terraform output -raw uploads_access_key)"
export AWS_SECRET_ACCESS_KEY="$(terraform output -raw uploads_secret_key)"
aws s3 ls --endpoint-url https://s3.eu-central-3.ionoscloud.com --region eu-central-3
Expected output:
... taskboard-uploads-dev-7f3a
Step 5: Upload and read back an object
echo "hello taskboard" > hello.txt
aws s3 cp hello.txt s3://taskboard-uploads-dev-7f3a/tests/hello.txt \
--endpoint-url https://s3.eu-central-3.ionoscloud.com --region eu-central-3
aws s3 ls s3://taskboard-uploads-dev-7f3a/tests/ \
--endpoint-url https://s3.eu-central-3.ionoscloud.com --region eu-central-3
Expected output:
upload: ./hello.txt to s3://taskboard-uploads-dev-7f3a/tests/hello.txt
... 16 hello.txt
Validation Checklist:
- [ ] The data volume is attached to the API server and visible as a second disk
- [ ] The bucket exists in
eu-central-3 - [ ] The new access key can list the bucket and upload an object
- [ ]
terraform outputshows both credentials as<sensitive>
Cleanup:
aws s3 rm s3://taskboard-uploads-dev-7f3a --recursive \
--endpoint-url https://s3.eu-central-3.ionoscloud.com --region eu-central-3
terraform destroy -auto-approve
Common Pitfalls
Developer mistakes to avoid with this unit's topic:
-
Using ZONE_3 for a server
- Problem: A shared
zonevariable works for volumes but the server plan or apply fails withZONE_3. - Why it happens: Block Storage has Zone 3, but Compute supports only Zone 1, Zone 2 and Auto.
- Fix: Keep separate variables for server and volume zones, and validate the server zone (Section 1.2).
- Problem: A shared
-
Sending a bearer token to Object Storage
- Problem: Bucket operations fail with an authentication error although
IONOS_TOKENis set. - Why it happens: Object Storage authenticates with an Access Key and a Secret Key, not with Cloud API tokens.
- Fix: Set
IONOS_S3_ACCESS_KEYandIONOS_S3_SECRET_KEYfor the provider, andAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYfor S3 clients.
- Problem: Bucket operations fail with an authentication error although
-
Bucket name already taken
- Problem:
terraform applyfails onionoscloud_s3_bucketin a new environment. - Why it happens: Bucket names must be unique across all IONOS accounts and all Object Storage regions.
- Fix: Add a suffix, for example from
random_id, and keep the name in a variable per environment.
- Problem:
Summary
You can now provision TaskBoard's storage tier as code. Block Storage volumes use ESSENTIAL, BALANCED or PERFORMANCE, attach with server_id, grow but never shrink, and live in zones that compute does not fully share. IONOS Cloud Object Storage buckets authenticate with Access Key and Secret Key pairs that Terraform can create and hand to your application as sensitive outputs, and a versioned bucket holds your remote state. NFS adds shared POSIX storage in a private LAN with the same resource pattern.
Key Points:
disk_typeand the volume'savailability_zoneare immutable; volumes can useZONE_3, servers cannot- Balanced and Performance scale with size; book at least 100 GB for full SSD performance
- The Object Storage S3 API uses Access Key plus Secret Key, not bearer tokens (only the Object Storage Management API for keys takes a bearer token); bucket names are globally unique
- Mark credential outputs
sensitive, and protect the state that still contains them - NFS clusters range from 2 TiB to 42 TiB, grow in 1 TiB steps and attach to a private LAN
Important Terminology:
- Performance class: The Block Storage type set in
disk_type: Essential, Balanced or Performance - Contract-owned bucket: A bucket owned by the contract owner, available in
eu-central-3,eu-central-4andus-central-1 - Access Key and Secret Key: The key pair that S3 clients and the provider use for Object Storage
- Sensitive output: A Terraform output hidden from CLI output but still stored in state
- Share: An exported directory of an NFS cluster, with its own quota and client groups
Next Steps
Continue Learning: Unit 2.5: Database and Streaming Service Provisioning
Related Topics: