Merge pull request #59 from delphix-integrations/develop

HUBS-1564 | Develop -> Main | Release version 2.0.0

.goreleaser.yml

@@ -1,7 +1,7 @@
 # Visit https://goreleaser.com for documentation on how to customize this
 # behavior.
 env:
-  - PROVIDER_VERSION=1.0.1
+  - PROVIDER_VERSION=2.0.0
 before:
   hooks:
     # this is just an example and not a requirement for provider building/publishing

GNUmakefile

@@ -3,7 +3,7 @@ HOSTNAME=delphix.com
 NAMESPACE=dct
 NAME=delphix
 BINARY=terraform-provider-${NAME}
-VERSION=1.0.1
+VERSION=2.0.0
 OS_ARCH=darwin_amd64
 
 default: install

docs/guides/provider_guide.md

@@ -0,0 +1,6 @@
+# Guide: <guide name> Delphix Provider Guide
+
+## Delphix Provider Guide
+[We have provided a handful of examples in our GitHub repository to help you get a jump start with our Delphix Provider.](https://github.com/delphix-integrations/terraform-provider-delphix/tree/main/examples) These examples range from Terraform resource templates, quick Terraform examples, and full Jenkins pipelines. We update this repository based on our implementation experience, so be sure to check back for updates!
+
+If you have a suggested template, request, or modification, please submit it in our [GitHub Issues section.](https://github.com/delphix-integrations/terraform-provider-delphix)

docs/resources/vdb.md

@@ -223,6 +223,42 @@ Environment variable to be set when the engine creates a VDB. See the Engine doc
   * `key` - (Required) Key of the tag
   * `value` - (Required) Value of the tag
 
+* `make_current_account_owner` - (Optional) Whether the account provisioning this VDB must be configured as owner of the VDB. 
+
+* `config_params` - (Optional) Database configuration parameter overrides
+
+* `appdata_source_params` - The JSON payload conforming to the DraftV4 schema based on the type of application data being manipulated.
+
+* `appdata_config_params` - (Optional) The list of parameters specified by the source config schema in the toolkit
+
+* `additional_mount_points` - (Optional) Specifies additional locations on which to mount a subdirectory of an AppData container
+  * `shared_path` - (Required) Relative path within the container of the directory that should be mounted.
+  * `mount_path` - (Required) Absolute path on the target environment were the filesystem should be mounted
+  * `environment_id` - (Required) The entity ID of the environment on which the file system will be mounted.
+
+* `vcdb_tde_key_identifier` - (Optional) ID of the key created by Delphix. (Oracle Multitenant Only)
+
+* `cdb_tde_keystore_password` - (Optional) The password for the Transparent Data Encryption keystore associated with the CDB. (Oracle Multitenant Only)
+
+* `target_vcdb_tde_keystore_path` - (Optional) Path to the keystore of the target vCDB. (Oracle Multitenant Only)
+
+* `tde_key_identifier` - (Optional) ID of the key created by Delphix. (Oracle Multitenant Only)
+
+* `tde_exported_key_file_secret` - (Optional) Secret to be used while exporting and importing vPDB encryption keys if Transparent Data Encryption is enabled on the vPDB. (Oracle Multitenant Only)
+
+* `parent_tde_keystore_password` - (Optional) The password of the keystore specified in parentTdeKeystorePath. (Oracle Multitenant Only)
+
+* `parent_tde_keystore_path` - (Optional) Path to a copy of the parent's Oracle transparent data encryption keystore on the target host. Required to provision from snapshots containing encrypted database files. (Oracle Multitenant Only)
+
+* `oracle_rac_custom_env_vars` - (Optional) Environment variable to be set when the engine creates an Oracle RAC VDB. See the Engine documentation for the list of allowed/denied environment variables and rules about substitution.
+  * `node_id` - (Required) The node id of the cluster.
+  * `name` - (Required) Name of the environment variable
+  * `value` - (Required) Value of the environment variable.
+
+* `oracle_rac_custom_env_files` - (Optional) Environment files to be sourced when the Engine creates an Oracle RAC VDB. This path can be followed by parameters. Paths and parameters are separated by spaces.
+  * `node_id` - (Required) The node id of the cluster.
+  * `path_parameters` - (Required) This references a file from which certain parameters will be loaded.
+
 
 ## Attribute Reference
 

examples/jenkins-integration/Readme.md

@@ -0,0 +1,21 @@
+### Summary
+The Jenkinsfile presents a simple CI/CD scenario where it provisions a VDB, runs an automated test (like Selenium or JUnit) against that application & dataset, and then destroys the VDB. On testing failure, which will happen every time, a bookmark is created. This Jenksinfile leverages the DCT Terrafrom Provider and an API Curl command to show the full breadth of possibilites. All other steps are mocked out.
+
+### Simple Getting Stated 
+1) Create a Jenkinsfile Pipeline Job
+2) Insert or reference the associated `Jenkinsfile` file.
+    - Note: This Jenkinsfile also references the Terraform files in the `../simple-provision` folder. Feel free to fork, update, and modify those.
+3) Update the following values:
+    - DCT_HOSTNAME - Example: `123.0.0.0`
+    - DCT_API_KEY - Example: `2.abc...`
+        - [Manage this value through the Jenkins' Credentials plugin](https://docs.cloudbees.com/docs/cloudbees-ci/latest/cloud-secure-guide/injecting-secrets)
+        - In a pinch, update it directly.
+    - SOURCE_VDB - Example: `Oracle_QA`
+4) Run Jenkins Job
+
+Note: I suggest you reduce the sleep timers in early testing scenarios .
+
+
+### Known Issues
+On VDB destroy, the underlying Bookmark's snapshot will be deleted and the Bookmark will become "dangling".
+Instead, I recommend using an "Enable/Disable" command instead of "Provision/Destroy" or skip the destroy VDB on failure.

examples/jenkins-integration/jenkinsfile

@@ -0,0 +1,175 @@
+pipeline {
+    agent any
+
+    environment {
+        def provision_successful = false
+        def vdb_id = ""
+        def vdb_name = ""
+        def DCT_HOSTNAME = "<INSERT>"
+        def SOURCE_VDB = "<INSERT>"
+        test_error = 'false'
+    }
+
+    stages {
+
+        stage ('Build Application') {
+            steps {
+                echo ('Building...')
+                sleep (50)
+            }
+        }
+
+        stage ('Stand Up Full Application') {
+            parallel {
+                stage ('Apply Application Install') {
+                    steps{
+                        echo ('Provisioning Test App...')
+                        sleep (30)
+                    }
+                }
+                stage ('Create Database w/ Terraform') {
+                    steps {
+                        script {
+                            echo ('Provisioning  VDB...')
+                            git branch: 'main', changelog: false, poll: false, url: 'https://github.com/delphix-integrations/terraform-provider-delphix.git'
+                            // sh ('ls -R')
+                            sh ('terraform -chdir=examples/simple-provision init')
+                            withCredentials([string(credentialsId: 'DCT_API_KEY', variable: 'KEY')]) {
+                                sh ('terraform -chdir=examples/simple-provision apply -var="source_data_id_1=$SOURCE_VDB" -var="dct_hostname=$DCT_HOSTNAME" -var="dct_api_key=$KEY" -auto-approve')
+                            }
+                            vdb_id = sh(script: 'terraform -chdir=examples/simple-provision output vdb_id_1', returnStdout: true)
+                            vdb_id = vdb_id.replaceAll('\\"', "").trim()
+                            vdb_name = sh(script: 'terraform -chdir=examples/simple-provision output vdb_name_1', returnStdout: true)
+                            echo ("vdb_id:" + vdb_id)
+                            echo ("vdb_name:" + vdb_name)
+                            provision_successful = true
+                        }
+                    }
+                }
+            }
+        }
+
+        stage ('Combine') {
+            steps {
+                echo ('Combining...')
+                sleep (10)
+            }
+        }
+
+        stage ('Run Tests') {
+            parallel {
+                stage ('UI') {
+                    stages {
+                        stage ('Run UI Tests') {
+                            steps{
+                                echo ('UI Tests...')
+                                sleep (150)
+                            }
+                        }
+                        stage ('Send UI Test Results') {
+                            steps{
+                                echo ('Send UI Test Results...')
+                                sleep (5)
+                            }
+                        }
+                    }
+                }
+                stage ('Unit') {
+                    stages {
+                        stage ('Run Unit Tests') {
+                            steps {
+                                script {
+                                    echo ('Unit Tests...')
+                                    sleep (70)
+                                    catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
+                                       echo ('Identified 7 failing Unit Tests!')
+                                        test_error = 'true';
+                                        sh "exit 1"
+                                    }
+                                }
+                            }
+                        }
+                        stage ('Send Unit Test Results') {
+                            steps{
+                                echo ('Send Unit Test Results...')
+                                sleep (6)
+                            }
+                        }
+                    }
+                }
+                stage ('Integ.') {
+                    stages {
+                        stage ('Run Integration Tests') {
+                            steps{
+                                echo ('UI Tests...')
+                                sleep (130)
+                            }
+                        }
+                        stage ('Send Integration Test Results') {
+                            steps{
+                                echo ('Send Integration Test Results...')
+                                sleep (4)
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+         stage ('Bookmark Database') {
+            when {
+                equals expected: 'true', actual: test_error
+            }
+            steps{
+                script {
+                    echo ('Bookmark VDB... ')
+                    withCredentials([string(credentialsId: 'DCT_API_KEY', variable: 'KEY')]) {
+                        sh """
+                            curl -X 'POST' -k \
+                                'https://$DCT_HOSTNAME/v3/bookmarks' \
+                                -H 'accept: application/json' \
+                                -H 'Authorization: apk ${KEY}' \
+                                -H 'Content-Type: application/json' \
+                                -d '{
+                                    "name": "JKNS-BOOKMARK-$BUILD_NUMBER",
+                                    "vdb_ids": [
+                                        "${vdb_id}"
+                                    ],
+                                    "retain_forever": true,
+                                    "make_current_account_owner": true
+                                }'
+                        """
+                    }
+                }
+            }
+        }
+
+        stage ('Destroy Full Application') {
+            parallel {
+                stage ('Destroy Application') {
+                    steps {
+                        script {
+                            echo ('Destroying Application...')
+                            sleep (30)
+                        }
+                    }
+                }
+                stage ('Destroy Database w/ Terraform') {
+                    steps {
+                        script {
+                            if (provision_successful) {
+                                    sleep (60)
+                                    echo ('Destroying Test App and VDB...')
+                                    withCredentials([string(credentialsId: 'DCT_API_KEY', variable: 'KEY')]) {
+                                        sh ('terraform -chdir=examples/simple-provision destroy -var="source_data_id_1=$SOURCE_VDB" -var="dct_hostname=$DCT_HOSTNAME" -var="dct_api_key=$KEY" -auto-approve')
+                                    }
+                            } else {
+                                echo ('No App or VDB to destroy...')
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

examples/simple-provision/README.md

@@ -0,0 +1,28 @@
+
+### Simple Getting Stated 
+
+1) Update the dct_hostname and dct_api_key variables in the `variables.tf` or in Terrafrom Cloud with the DCT Server and API Key. 
+For example:
+- DCT: uv123abcfei59h6qajyy.vm.cld.sr
+- API Key: 2.ZAAgpjHxljW7A7g...
+
+2) Update `Oracle_QA` with an applicable VDB name and run the following commands. 
+```
+# Create all resources
+terraform apply -var="source_data_id_1=Oracle_QA"
+
+# Destroy resources
+terraform destroy"
+```
+
+
+### Troubleshoot: Invalid Resource State
+
+If you find that you've lost the sync between DCT and Terraform, use the `terraform state rm` command to help reconfigure without starting over.
+```
+terraform state rm delphix_vdb.provision_vdb_1
+
+terraform state rm delphix_vdb_group.create_vdb_group
+```
+
+[Documentation](https://developer.hashicorp.com/terraform/cli/commands/state/rm)

examples/simple-provision/main.tf

@@ -0,0 +1,21 @@
+# Configure the connection to Data Control Tower
+provider "delphix" {
+  host = var.dct_hostname
+  key = var.dct_api_key
+  tls_insecure_skip = true
+}
+
+# Provision a VDB 1
+resource "delphix_vdb" "provision_vdb_1" {
+  name                   = "tfmtest1"
+  source_data_id         = var.source_data_id_1
+  auto_select_repository = true
+}
+
+# Create a VDB Group with VDB 1
+resource "delphix_vdb_group" "create_vdb_group" {
+  name  = "Terraform Demo Group"
+  vdb_ids = [
+    delphix_vdb.provision_vdb_1.id
+  ]
+}

examples/simple-provision/outputs.tf

@@ -0,0 +1,33 @@
+###
+# VDB Group Information
+###
+output "vdb_group_id" {
+  value = delphix_vdb_group.create_vdb_group.id
+}
+
+output "vdb_group_name" {
+  value = delphix_vdb_group.create_vdb_group.name
+}
+
+###
+# VDB 1 Information
+###
+output "vdb_id_1" {
+  value = delphix_vdb.provision_vdb_1.id
+}
+
+output "vdb_name_1" {
+  value = delphix_vdb.provision_vdb_1.name
+}
+
+output "vdb_ip_address_1" {
+  value = delphix_vdb.provision_vdb_1.ip_address
+}
+
+output "vdb_database_type_1" {
+  value = delphix_vdb.provision_vdb_1.database_type
+}
+
+output "vdb_database_version_1" {
+  value = delphix_vdb.provision_vdb_1.database_version
+}

examples/simple-provision/variables.tf

@@ -0,0 +1,13 @@
+variable "dct_hostname" {
+  type  = string
+  description = "dct hostname config file [default: workspace variable set]"  
+}
+
+variable "dct_api_key" {
+  type  = string
+  description = "dct api key config file [default: workspace variable set]"
+}
+
+variable "source_data_id_1" {
+  description = "Name or ID of the VDB or Data Source to provision from. [User Defined]"
+}

examples/simple-provision/versions.tf

@@ -0,0 +1,8 @@
+terraform {
+  required_providers {
+    delphix = {
+      source = "delphix-integrations/delphix"
+      version = "1.0.0"
+    }
+  }
+}