terraform-provider-hpcr

Terraform Provider HPCR

Terraform provider to automate generating workloads for IBM Hyper Protect confidential computing platforms.

Table of Contents

• Overview
• Who Is This For?
• Features
• Installation
• Quick Start
• Documentation
• Supported Platforms
• Examples
• Related Projects
• Contributing
• License
• Support

Overview

This Terraform provider is built on top of the contract-go library, which provides the core functionality for IBM Hyper Protect contract operations.

The contract-go library automates IBM Hyper Protect confidential computing workloads across IBM Confidential Computing Container Runtime, IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions, and IBM Confidential Computing Containers for Red Hat OpenShift Container Platform, providing capabilities for:

• Contract Generation: Create signed and encrypted contracts for the platforms

• Certificate Operations: Download and manage HPVS encryption certificates from IBM Cloud

• Image Selection: Retrieve and validate HPCR images with semantic versioning

• Archive Management: Generate Base64 tar archives from docker-compose and podman play configurations

• Attestation: Decrypt attestation records from HPCR, HPVS and HPCC

• IBM Confidential Computing Container Runtime (formerly known as Hyper Protect Virtual Servers (HPVS)) — Deploy confidential computing workloads on IBM Z and LinuxONE using IBM Secure Execution for Linux

• IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions (formerly known as Hyper Protect Container Runtime for Red Hat Virtualization Solutions (HPCR4RHVS)) — Purpose-built for hosting critical, centralized services within tightly controlled virtualized environments on IBM Z

• IBM Confidential Computing Containers for Red Hat OpenShift Container Platform (formerly known as IBM Hyper Protect Confidential Container for Red Hat OpenShift Container Platform (HPCC)) — Deploy isolated workloads using IBM Secure Execution for Linux, integrated with Red Hat OpenShift Container Platform

What are Hyper Protect Services?

IBM Hyper Protect services provide confidential computing capabilities that protect data in use by leveraging the Secure Execution feature of IBM Z and LinuxONE.

Learn more:

• Confidential computing with LinuxONE
• IBM Confidential Computing Container Runtime
• IBM Confidential Computing Container Runtime for Red Hat Virtualization Solutions
• IBM Confidential Computing Containers for Red Hat OpenShift

Who Is This For?

This Terraform provider is designed for:

• DevOps Engineers automating confidential computing deployments via Terraform or CI/CD pipelines
• Solution Providers building applications that run in IBM Hyper Protect secure enclaves
• Platform Teams managing contract lifecycle across multiple environments
• Security Architects implementing zero-trust confidential computing architectures

Not sure if this is right for you?

When to use this provider:

• You manage infrastructure with Terraform
• You need state management for contracts
• You want to integrate with other Terraform providers (IBM Cloud, libvirt)
• You prefer declarative configuration over imperative scripts

When to use alternatives:

• contract-cli: Manual contract generation, one-off deployments, testing
• contract-go library: Custom Go applications, advanced contract manipulation
• k8s-operator-hpcr: Kubernetes-native deployments on OpenShift

Features

The Terraform Provider HPCR provides comprehensive support for deploying and managing IBM Hyper Protect confidential computing workloads through Infrastructure-as-Code. Key capabilities include:

Archive Management

• Create Base64-encoded tgz archives from folders containing docker-compose and podman play configurations
• Automatic compression and encoding for contract workload sections

Encryption Operations

• Encrypt contract sections (workload, env) using HPVS, HPCR4RHVS and HPCC encryption certificates
• Automatic retrieval of encryption certificates from IBM Cloud
• Support for latest or specific encryption certificate versions
• Secure handling of sensitive configuration data
• Support for password-protected private keys
• Platform version targeting for version-specific encryption

Image Selection & Validation

• Select appropriate HPCR stock images from IBM Cloud VPC
• Semantic versioning support with flexible version constraints (e.g., >=1.1.0, ~>1.0)
• Automatic validation of image availability
• Support for public IBM Cloud Hyper Protect images

Contract Generation

• Streamlined workflow for generating encrypted HPCR contracts
• Integration with contract-go library for contract operations
• Support for signed and encrypted contracts
• Support for password-protected signing keys
• Platform version targeting
• YAML-based contract composition

Installation

This provider is published on the Terraform Registry and can be installed automatically by Terraform.

Add the provider configuration to your Terraform files:

terraform {
  required_providers {
    hpcr = {
      source  = "ibm-hyper-protect/hpcr"
      version = "~> 1.2.0"
    }
  }
}

provider "hpcr" {}

Then run:

terraform init

Requirements

• Terraform 0.13 or later
• OpenSSL binary (not LibreSSL)
  • Linux: apt-get install openssl
  • macOS: brew install openssl
  • Windows: Download from Win32OpenSSL

Optional: Custom OpenSSL Path

If OpenSSL is not in your system PATH, set the OPENSSL_BIN environment variable:

# Linux/macOS
export OPENSSL_BIN=/usr/bin/openssl

# Windows (PowerShell)
$env:OPENSSL_BIN="C:\Program Files\OpenSSL-Win64\bin\openssl.exe"

Quick Start

Create TGZ Archive

Use the hpcr_tgz resource to create a tgz archive from your docker-compose or podman play folder:

resource "hpcr_tgz" "compose" {
  folder = var.FOLDER
}

You can access the Base64-encoded content via the rendered property.

Encrypt Contract Sections

Use the hpcr_text_encrypted resource to encrypt contract sections. By default, it uses the encryption key of the latest HPCR image:

resource "hpcr_text_encrypted" "workload" {
  text = yamlencode({
    "compose" : {
      "archive" : resource.hpcr_tgz.compose.rendered
    }
  })
  # Optionally target a specific platform version
  # version = "1.0.16"
}

The typical use case is to encrypt the workload and env sections separately and pass the YAML-encoded contract as input.

Select HPCR Image

Use the hpcr_image data source to select the appropriate HPCR stock image from IBM Cloud VPC with optional version constraints:

data "ibm_is_images" "hyper_protect_images" {
  visibility = "public"
  status     = "available"
}

data "hpcr_image" "selected_image" {
  images = jsonencode(data.ibm_is_images.hyper_protect_images.images)
  spec   = ">=1.1.0"  # optional version constraint
}

Documentation

Provider Documentation

• Terraform Registry Documentation
• Confidential computing with LinuxONE

Contract-Go Documentation

• User Documentation
• Go Package Docs
• Sample Configurations

Additional Resources

• IBM Confidential Computing Container Runtime
• IBM Confidential Computing Containers for Red Hat OpenShift
• Terraform Provider Development Guide

Supported Platforms

Examples

Complete examples for all resources and data sources are available in the examples/ directory:

Resources

• hpcr_tgz - Create Base64-encoded tar.gz archives from docker-compose or podman folders
• hpcr_tgz_encrypted - Create encrypted archives with platform and certificate options
• hpcr_text - Encode text as Base64 for contract inclusion
• hpcr_text_encrypted - Encrypt text content for secure contracts
• hpcr_json - Encode JSON data as Base64
• hpcr_json_encrypted - Encrypt JSON configuration data
• hpcr_contract_encrypted - Generate encrypted and signed HPCR contracts
• hpcr_contract_encrypted_contract_expiry - Generate contracts with automatic expiry using CSR

Data Sources

• hpcr_image - Select HPCR images from IBM Cloud VPC with semantic versioning
• hpcr_attestation - Decrypt and parse attestation records
• hpcr_encryption_certs - Download encryption certificates from IBM Cloud
• hpcr_encryption_cert - Select specific certificate versions

Quick Start Example

Here's a complete workflow for creating and deploying an HPCR contract:

terraform {
  required_providers {
    hpcr = {
      source  = "ibm-hyper-protect/hpcr"
      version = "~> 1.2.0"
    }
    ibm = {
      source  = "IBM-Cloud/ibm"
      version = ">= 1.37.1"
    }
  }
}

# Create TGZ archive from docker-compose folder
resource "hpcr_tgz" "workload" {
  folder = "./docker-compose"
}

# Define contract
locals {
  contract = yamlencode({
    "env" : {
      "type" : "env",
      "logging" : {
        "logRouter" : {
          "hostname" : "logs.example.cloud.ibm.com",
          "iamApiKey" : xxxxxxxxxxxxxxxx
        }
      }
    },
    "workload" : {
      "type" : "workload",
      "compose" : {
        "archive" : resource.hpcr_tgz.workload.rendered
      }
    }
  })
}

# Generate encrypted contract
resource "hpcr_contract_encrypted" "contract" {
  contract = local.contract
  # Optionally target a specific platform version
  # version = "1.0.16"
  # Optionally use a password-protected signing key
  # privkey  = file("./cert/private_encrypted.pem")
  # password = var.signing_key_password
}

# Select HPCR image
data "ibm_is_images" "hyper_protect_images" {
  visibility = "public"
  status     = "available"
}

data "hpcr_image" "selected_image" {
  images = jsonencode(data.ibm_is_images.hyper_protect_images.images)
  spec   = ">=1.1.0"
}

# Deploy to IBM Cloud VPC
resource "ibm_is_instance" "hpcr_instance" {
  name    = "my-hpcr-workload"
  image   = data.hpcr_image.selected_image.image
  profile = var.profile
  keys    = [var.key_id]
  vpc     = var.vpc_id
  zone    = var.zone

  primary_network_interface {
    name            = "eth0"
    subnet          = var.subnet_id
    security_groups = [var.security_group_id]
  }

  user_data = resource.hpcr_contract_encrypted.contract.rendered
}

output "instance_id" {
  value = ibm_is_instance.hpcr_instance.id
}

output "contract_sha256" {
  value = resource.hpcr_contract_encrypted.contract.sha256_out
}

For more detailed examples and specific use cases, explore the examples/ directory.

Related Projects

This provider is part of the IBM Hyper Protect ecosystem:

• contract-go - Go library for contract automation (underlying library for this provider)
• contract-cli - Command-line contract generation tool
• k8s-operator-hpcr - Kubernetes operator for HPCR workloads
• linuxone-vsi-automation-samples - Infrastructure-as-code examples and automation samples

Contributing

Contributions are welcome! This repository uses semantic-release for automated versioning and releases.

Please follow the Conventional Commits specification when authoring commit messages:

• feat: - New features (triggers minor version bump)
• fix: - Bug fixes (triggers patch version bump)
• docs: - Documentation changes only
• chore: - Maintenance tasks, refactoring, or dependency updates
• BREAKING CHANGE: - Include in commit footer for breaking changes (triggers major version bump)

See CONTRIBUTING.md for detailed contribution guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

• Issues: Report bugs or request features via GitHub Issues
• Security: Report vulnerabilities via GitHub Security Advisories (never public issues)
• Discussions: Community discussions available on the repository discussions page

Contributors