Merge pull request #55 from ibm-hyper-protect/create-contract-dynamic-registry

Add create-contract-dynamic-registry example

Author: Timo-1

terraform-hpvs/create-contract-dynamic-registry/README.md

@@ -0,0 +1,68 @@
+## Contract generation example with support for dynamic container registry definition
+
+This sample creates an encrypted and signed contract and stores it locally in a file. You can later use the contract to provision a HPVS for VPC instance.
+The contract will define the container registry and the credentials for pulling your workload container image.
+
+### Prerequisite
+
+Prepare your environment according to [these steps](../README.md)
+
+### Define your settings
+
+Define your settings:
+- logdna_ingestion_hostname: The ingestion host name of your Log instance which you provisioned previously
+- logdna_ingestion_key: The ingestion key of your Log instance
+- registry: The container registry to pull your workload container image from
+- pull_username: The container registry username for pulling your workload container image
+- pull_password: The container registry password for pulling your workload container image
+
+The settings are defined in form of Terraform variables.
+
+Use one of the following options to define the variables:
+
+#### Define the variables in a template file
+
+1. `cp my-settings.auto.tfvars-template my-settings.auto.tfvars`
+2. Fill the values in `my-settings.auto.tfvars`
+
+#### Define environment variables
+
+Set the following environment variables:
+
+```text
+TF_VAR_logdna_ingestion_key=
+TF_VAR_logdna_ingestion_hostname=
+TF_VAR_registry=
+TF_VAR_pull_username=
+TF_VAR_pull_password=
+```
+
+### Define your workload
+
+Create the file `compose\docker-compose.yml` for your workload. Specify at least the container image digest and use the `${REGISTRY}` variable to reference the container registry defined in your settings, e.g.:
+
+```
+services:
+  helloworld:
+    image: ${REGISTRY}/hpse-docker-hello-world-s390x@sha256:43c500c5f85fc450060b804851992314778e35cadff03cb63042f593687b7347
+```
+
+### Run the Example
+
+Initialize terraform:
+
+```bash
+terraform init
+```
+
+Deploy the example:
+
+```bash
+terraform apply
+```
+
+### Further steps
+
+The contract will be written to the file `build/contract.yml` and can now be used for e.g. provisining a HPVS for VPC instance.
+
+Note that you will need to create a public gateway in your VPC before creating the HPVS for VPC instance. This is necessary to allow the HPVS for VPC instance to reach your Log instance through the public gateway. 

terraform-hpvs/create-contract-dynamic-registry/compose/docker-compose.yml

@@ -0,0 +1,3 @@
+services:
+  helloworld:
+    image: ${REGISTRY}/hpse-docker-hello-world-s390x@sha256:43c500c5f85fc450060b804851992314778e35cadff03cb63042f593687b7347

terraform-hpvs/create-contract-dynamic-registry/my-settings.auto.tfvars-template

@@ -0,0 +1,6 @@
+logdna_ingestion_key="Your LogDNA ingestion key".
+logdna_ingestion_hostname="rsyslog endpoint of IBM Log Analysis instance"   # Example: "syslog-a.<log_region>.logging.cloud.ibm.com".
+registry="Prefix for the dynamic registry" # e.g. docker.io/library or us.icr.io
+pull_username="Username for registry" # Username with read access to the container registry
+pull_password="Password for registry" # Password with read access to the container registry
+

terraform-hpvs/create-contract-dynamic-registry/terraform.tf

@@ -0,0 +1,56 @@
+terraform {
+  required_providers {
+    hpcr = {
+      source  = "ibm-hyper-protect/hpcr"
+      version = ">= 0.1.1"
+    }
+  }
+}
+
+# archive of the folder containing docker-compose file. This folder could create additional resources such as files 
+# to be mounted into containers, environment files etc. This is why all of these files get bundled in a tgz file (base64 encoded)
+resource "hpcr_tgz" "contract" {
+  folder = "compose"
+}
+
+locals {
+  # contract in clear text
+ contract = yamlencode({
+    "env" : {
+      "type" : "env",
+      "logging" : {
+        "logDNA" : {
+          "ingestionKey" : var.logdna_ingestion_key,
+          "hostname" : var.logdna_ingestion_hostname,
+        }
+      },
+      "auths" : {
+        (var.registry) : {
+          "username" : var.pull_username,
+          "password" : var.pull_password
+        }
+      },
+      "env" : {
+        "REGISTRY" : var.registry
+      }
+    },
+    "workload" : {
+      "type" : "workload",
+      "compose" : {
+        "archive" : hpcr_tgz.contract.rendered
+      }
+    }
+  })
+}
+
+# In this step we encrypt the fields of the contract and sign the env and workload field. The certificate to execute the 
+# encryption it built into the provider and matches the latest HPCR image. If required it can be overridden. 
+# We use a temporary, random keypair to execute the signature. This could also be overriden. 
+resource "hpcr_contract_encrypted" "contract" {
+  contract = local.contract
+}
+
+resource "local_file" "contract" {
+  content  = hpcr_contract_encrypted.contract.rendered
+  filename = "${path.module}/build/contract.yml"
+}

terraform-hpvs/create-contract-dynamic-registry/variables.tf

@@ -0,0 +1,40 @@
+variable "logdna_ingestion_key" {
+  type        = string
+  sensitive   = true
+  description = <<-DESC
+                  Ingestion key for IBM Log Analysis instance. This can be 
+                  obtained from "Linux/Ubuntu" section of "Logging resource" 
+                  tab of IBM Log Analysis instance
+                DESC
+}
+
+variable "logdna_ingestion_hostname" {
+  type        = string
+  description = <<-DESC
+                  rsyslog endpoint of IBM Log Analysis instance. 
+                  Don't include the port. Example: 
+                  syslog-a.<log_region>.logging.cloud.ibm.com
+                  log_region is the region where IBM Log Analysis is deployed
+                DESC
+}
+
+variable "registry" {
+  type        = string
+  description = <<-DESC
+                  Prefix of the container registry used to pull the image
+                DESC
+}
+
+variable "pull_username" {
+  type        = string
+  description = <<-DESC
+                  Username to pull from the above registry
+                DESC
+}
+
+variable "pull_password" {
+  type        = string
+  description = <<-DESC
+                  Password to pull from the above registry
+                DESC
+}