Doc and examples updated (#2)

* doc updated

Signed-off-by: Karthic Ravindran <[email protected]>

* updated README

Signed-off-by: Karthic Ravindran <[email protected]>

* updated README in alarm module

Signed-off-by: Karthic Ravindran <[email protected]>

* updated alarm module

Signed-off-by: Karthic Ravindran <[email protected]>

* updated alarm README

Signed-off-by: Karthic Ravindran <[email protected]>

---------

Signed-off-by: Karthic Ravindran <[email protected]>

README.md

@@ -1,22 +1,17 @@
 # Oracle Cloud Infrastructure Terraform Module for Observability
 
-*This module is for creating resources related to Observability in Oracle Cloud Infrastructure*
+*This module is for creating resources related to [Observability](https://www.oracle.com/in/manageability/) in Oracle Cloud Infrastructure*
 
-## Installation
-
-*Provide detailed step-by-step installation instructions*
+## Pre-requisites:
 
+- git is installed. 
+- Terraform 1.3.0 or higher version is installed.
+- [Required keys](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are availabe for authentication
 ## Documentation
-
-*Developer-oriented documentation can be published on GitHub, but all product documentation must be published on <https://docs.oracle.com>*
-
-## Examples
-
-*Describe any included examples or provide a link to a demo/tutorial*
-
-## Help
-
-*Inform users on where to get help or how to receive official support from Oracle (if applicable)*
+Please refer to the [examples](https://github.com/oracle-terraform-modules/terraform-oci-oandm/tree/main/examples) on how to use each submodule.       
+Below are some reference document to understand the service related to the modules  
+[Alarm](https://docs.oracle.com/en-us/iaas/Content/Monitoring/Tasks/managingalarms.htm)  
+[ServiceConnector](https://docs.oracle.com/en-us/iaas/Content/service-connector-hub/overview.htm)  
 
 ## Contributing
 

examples/alarm/README.md

@@ -0,0 +1,14 @@
+## Simple Alarm creation
+
+This example is to create a simple alarm with notification topic.   
+Rename the provider.tf.example to provider.tf  and provide the required values   
+
+Local values are defined to test it quickly.   
+If you like to create multiple alarms with a topic then rename the terraform.tfvars.example to terraform.tfvars.   
+
+Run the terraform commands to execute 
+```console
+terraform init
+terraform plan
+terraform apply
+```

examples/alarm/main.tf

@@ -1,5 +1,8 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
 module "alarm" {
-  source           = "./modules/alarm"
+  source           = "../../modules/alarm"
   alarm_def        = local.alarm_def
   compartment_ocid = local.compartment_ocid
   notification     = local.notification
@@ -22,10 +25,11 @@ locals {
     }
   }
   alarm_def = {
-    "testdelete" = {
-      destination = "demotopic"
-      namespace   = "oci_computeagent"
-      query       = "CpuUtilization[1m].mean() > 70"
+    demoalarm = {
+      destination  = "demotopic"
+      display_name = "demoalarm"
+      namespace    = "oci_computeagent"
+      query        = "CpuUtilization[1m].mean() > 70"
     }
   }
 }

examples/alarm/provider.tf.example

@@ -1,3 +1,6 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
 provider "oci" {
   region           = "<region where alarm,notification to be created>"
   fingerprint      = ""

examples/alarm/terraform.tfvars.example

@@ -0,0 +1,35 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+
+compartment_ocid = "<compartment where topic and alarm to be created>"
+alarm_def = {
+     alarm1 = {
+      display_name = "alarm1"
+      destination  = "demotopic"
+      namespace    = "oci_computeagent"
+      query        = "CpuUtilization[1m].mean() > 70"
+    }
+     alarm2 = {
+      display_name = "alarm2"
+      destination  = "demotopic"
+      namespace    = "oci_computeagent"
+      query        = "CpuUtilization[1m].mean() > 70"
+      severity     = "WARNING"
+      body         = "CPU is greater than 70 please follow the runbook"
+    }
+}
+notification = {
+    demotopic = {
+      subscription = {
+        sub1 = {
+          protocol = "EMAIL"
+          endpoint = "<email address>"
+        }
+        sub2 = {
+            protocol = "SMS"
+            endpoint = "<phonenumber>"
+        }
+      }
+    }
+}

examples/alarm/variables.tf

@@ -0,0 +1,49 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+variable "compartment_ocid" {
+  description = "Compartment OCID"
+  type        = string
+}
+
+
+variable "alarm_def" {
+  description = "OCI Alarm definition"
+  type = map(object({
+    destination                  = string
+    display_name                 = string
+    severity                     = optional(string, "CRITICAL")
+    query                        = string
+    is_enabled                   = optional(bool, true)
+    namespace                    = string
+    metric_compartment_id        = optional(string)
+    repeat_notification_duration = optional(string, "PT5M")
+    trigger                      = optional(string, "PT5M")
+    suppression_from_time        = optional(string)
+    suppression_till_time        = optional(string)
+    message_format               = optional(string, "RAW")
+    body                         = optional(string, null)
+    freeform_tags                = optional(map(string))
+    defined_tags                 = optional(map(string))
+  }))
+}
+
+variable "notification" {
+  description = "Notification Topic and Subscription"
+  type = map(object({
+    description   = optional(string)
+    create_topic  = optional(bool, true)
+    defined_tags  = optional(map(string))
+    freeform_tags = optional(map(string))
+    subscription = optional(map(object({
+      endpoint = string
+      protocol = string
+    })))
+  }))
+}
+
+variable "label_prefix" {
+  default     = "none"
+  description = "Prefix to be added to the resources"
+  type        = string
+}

examples/multiplealarm/README.md

@@ -0,0 +1,15 @@
+## Multiple Alarm creation
+
+This example is to create multiple alarm with notification topic based on csv file.   
+Rename the provider.tf.example to provider.tf  and provide the required values   
+
+This example does not create any subscription for the topic.
+
+In the csv for the column named create_topic specify *true* if the topic has to be created and *false* if you want to use existing topic.
+
+Run the terraform commands to execute 
+```console
+terraform init
+terraform plan
+terraform apply
+```

examples/multiplealarm/alarm.csv

@@ -0,0 +1,4 @@
+display_name,namespace,query,destination,create_topic,severity
+alarm1,oci_computeagent,CpuUtilization[1m].mean() > 80,demo1,true,
+alarm2,oci_computeagent,CpuUtilization[1m].mean() > 50,demotopic,false,WARNING
+alarm3,oci_computeagent,MemoryUtilization[1m].mean() > 80,demo1,true,

examples/multiplealarm/main.tf

@@ -0,0 +1,18 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+module "multiplealarm" {
+  source           = "../../modules/alarm"
+  alarm_def        = local.alarm_def_map
+  compartment_ocid = local.compartment_ocid
+  notification     = local.notification
+
+}
+
+locals {
+  compartment_ocid = "<compartment_id>"
+  alarm_def        = csvdecode(file("./alarm.csv"))
+  alarm_def_map    = { for alarm in local.alarm_def : alarm.display_name => alarm }
+  topicmergelist   = distinct([for alarm in local.alarm_def_map : { create_topic = alarm.create_topic, destination = alarm.destination }])
+  notification     = { for topic in local.topicmergelist : topic.destination => { create_topic = topic.create_topic } }
+}

examples/multiplealarm/provider.tf.example

@@ -0,0 +1,22 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+provider "oci" {
+  region           = "<region where alarm,notification to be created>"
+  fingerprint      = ""
+  private_key_path = ""
+
+  tenancy_ocid = ""
+  user_ocid    = ""
+
+}
+
+terraform {
+  required_providers {
+    oci = {
+      source  = "oracle/oci"
+      version = ">= 4.67.3"
+    }
+  }
+  required_version = ">= 1.3.0"
+}

examples/multiplealarm/variables.tf

@@ -0,0 +1,49 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+variable "compartment_ocid" {
+  description = "Compartment OCID"
+  type        = string
+}
+
+
+variable "alarm_def" {
+  description = "OCI Alarm definition"
+  type = map(object({
+    destination                  = string
+    display_name                 = string
+    severity                     = optional(string, "CRITICAL")
+    query                        = string
+    is_enabled                   = optional(bool, true)
+    namespace                    = string
+    metric_compartment_id        = optional(string)
+    repeat_notification_duration = optional(string, "PT5M")
+    trigger                      = optional(string, "PT5M")
+    suppression_from_time        = optional(string)
+    suppression_till_time        = optional(string)
+    message_format               = optional(string, "RAW")
+    body                         = optional(string, null)
+    freeform_tags                = optional(map(string))
+    defined_tags                 = optional(map(string))
+  }))
+}
+
+variable "notification" {
+  description = "Notification Topic and Subscription"
+  type = map(object({
+    description   = optional(string)
+    create_topic  = optional(bool, true)
+    defined_tags  = optional(map(string))
+    freeform_tags = optional(map(string))
+    subscription = optional(map(object({
+      endpoint = string
+      protocol = string
+    })))
+  }))
+}
+
+variable "label_prefix" {
+  default     = "none"
+  description = "Prefix to be added to the resources"
+  type        = string
+}

examples/serviceconnector/README.md

@@ -0,0 +1,28 @@
+## Service Connector creation
+
+This example is to create a service connector with source as streaming and target as object storage.    
+Rename the provider.tf.example to provider.tf and provide the required values   
+
+Local values are defined to test it quickly.   
+If you like to create multiple service connectors then rename the terraform.tfvars.example to terraform.tfvars and provide the required values   
+
+Supported values for sch_source in variable service_connector_def is     
+- streaming     
+- logging      
+- monitoring    
+
+Supported values for sch_target in variable service_connector_def is     
+- loggingAnalytics      
+- objectstorage
+- functions
+- streaming
+- notifications
+
+If the dynamic group is created manually then the variable *dynamic_group* can be empty map `{}` which is the default value 
+
+Run the terraform commands to execute 
+```console
+terraform init
+terraform plan
+terraform apply
+```

examples/serviceconnector/main.tf

@@ -1,5 +1,8 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
 module "svc" {
-  source                = "./modules/serviceconnector"
+  source                = "../../modules/serviceconnector"
   service_connector_def = local.service_connector_def
   policy_compartment_id = local.policy_compartment_id
   dynamic_group         = local.dynamic_group

examples/serviceconnector/provider.tf.example

@@ -1,3 +1,6 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
 provider "oci" {
   region           = "<region where service connector to be created>"
   fingerprint      = ""

examples/serviceconnector/terraform.tfvars.example

@@ -0,0 +1,48 @@
+#Copyright (c) 2023 Oracle Corporation and/or its affiliates.
+#Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+tenancy_ocid = "<tenancy_ocid>"
+dynamic_group = {
+    sch_dg = { compartment_id = "<service connector compartment id>" }
+  }
+policy_compartment_id = "<policy compartment>" #if not set policy will be created default in root compartment
+service_connector_def = { sch_stream_storage = {
+    compartment_id = "<service connector compartment id>"
+    #If policy needs to be created set the below two values. By default its set to false to not create policy
+    #Set create_policy to true 
+    #set dynamic group name with respect to service connector compartment
+    create_policy      = true
+    dynamic_group_name = sch_dg
+
+    sch_source   = "streaming"
+    sch_target   = "objectstorage"
+    display_name = "sch_stream_storage"
+
+    stream_id = "<existing stream ocid>"
+    target = {
+      bucket = "<bucket name>"
+    }
+    }
+  sch_logging_LA = {
+    compartment_id = "<service connector compartment id>"
+    #If policy needs to be created set the below two values. By default its set to false to not create policy
+    #set dynamicgroup name with respect to service connector compartment
+    create_policy      = true
+    dynamic_group_name = sch_dg
+
+    sch_source   = "logging"
+    sch_target   = "loggingAnalytics"
+    display_name = "sch_logging_LA"
+
+    log_source = [{
+        #specify compartment_id if its different from service connector compartment
+        compartment_id = "<compartment_id>"
+        log_group_id = "<ocilogging_loggroup_id>"
+
+      }]
+
+    target = {
+      log_group_id = "<loggingAnalytics_loggroup_id>" 
+    }
+    }
+  }