HUBS-1695 | Add example documentation for database specific VDB provi…

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)

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"
+    }
+  }
+}