Merge pull request #4 from oracle-quickstart/release-0.1.3

Release 0.1.3

.gitignore

@@ -8,4 +8,6 @@
 **/terraform_*.tfvars*
 **/terraform.tfvars
 **/input.auto.tfvars
-**/*.pptx
+**/*.pptx
+**/private
+**/creds

README.md

@@ -7,6 +7,7 @@ This repository contains Terraform OCI (Oracle Cloud Infrastructure) modules for
 The following modules are available:
 - [Events](./events/)
 - [Alarms](./alarms/)
+- [Logging](./logging/)
 - [Notifications](./notifications/)
 - [Streams](./streams/)
 - [Service Connectors](./service-connectors/)
@@ -25,6 +26,7 @@ This repository is part of a broader collection of repositories containing modul
 - [Governance](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-governance)
 - [Security](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-security)
 - [Observability & Monitoring](https://github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability) - current repository
+- [Secure Workloads](https://github.com/oracle-quickstart/terraform-oci-secure-workloads)
 
 The modules in this collection are designed for flexibility, are straightforward to use, and enforce CIS OCI Foundations Benchmark recommendations when possible.
 

RELEASE-NOTES.md

@@ -1,3 +1,8 @@
+# January 10, 2024 Release Notes - 0.1.3
+
+## Added
+1. Logging module, supporting service logs and custom logs, with the additional ability for bulk provisioning bucket logs and flow logs.
+
 # September 28, 2023 Release Notes - 0.1.2
 
 ## Updates

alarms/README.md

@@ -71,13 +71,13 @@ module "alarms" {
 For invoking the module remotely, set the module *source* attribute to the alarms module folder in this repository, as shown:
 ```
 module "alarms" {
-  source = "git@github.com:oracle-quickstart/terraform-oci-cis-landing-zone-observability.git//alarms"
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability/alarms"
   alarms_configuration = var.alarms_configuration
 }
 ```
 For referring to a specific module version, append *ref=\<version\>* to the *source* attribute value, as in:
 ```
-  source = "git@github.com:oracle-quickstart/terraform-oci-cis-landing-zone-observability.git//alarms?ref=v0.1.0"
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability//alarms?ref=v0.1.0"
 ```
 ## <a name="functioning">Module Functioning</a>
 

events/README.md

@@ -75,13 +75,13 @@ module "events" {
 For invoking the module remotely, set the module *source* attribute to the events module folder in this repository, as shown:
 ```
 module "events" {
-  source = "git@github.com:oracle-quickstart/terraform-oci-cis-landing-zone-observability.git//events"
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability/events"
   events_configuration = var.events_configuration
 }
 ```
 For referring to a specific module version, append *ref=\<version\>* to the *source* attribute value, as in:
 ```
-  source = "git@github.com:oracle-quickstart/terraform-oci-cis-landing-zone-observability.git//events?ref=v0.1.0"
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability//events?ref=v0.1.0"
 ```
 ## <a name="functioning">Module Functioning</a>
 

logging/README.md

@@ -0,0 +1,208 @@
+# CIS OCI Landing Zone Logging Module
+
+![Landing Zone logo](../landing_zone_300.png)
+
+This module manages log groups and logs in Oracle Cloud Infrastructure (OCI) based on a single configuration object. Logging provides access to logs from Oracle Cloud Infrastructure resources. These logs include critical diagnostic information that describes how resources are performing and being accessed. 
+
+Check [module specification](./SPEC.md) for a full description of module requirements, supported variables, managed resources and outputs.
+
+Check the [examples](./examples/) folder for actual module usage.
+
+- [Requirements](#requirements)
+- [How to Invoke the Module](#invoke)
+- [Module Functioning](#functioning)
+- [Related Documentation](#related)
+- [Known Issues](#issues)
+
+## <a name="requirements">Requirements</a>
+### IAM Permissions
+
+This module requires the following OCI IAM permissions in compartments where log groups and logs are managed. Additionally, extra permissions are needed depending on the resource that logging is being enabled for.
+
+For deploying log groups and logs in general:
+```
+Allow group <group> to manage logging-family in compartment <log-group-compartment-name>
+```
+
+For deploying flow logs (using the *service_logs* attribute. See [Module Functioning](#functioning)):
+```
+Allow group <group> to manage subnets in compartment <subnet-compartment-name> where request.permission = 'SUBNET_UPDATE'
+```
+
+For deploying flow logs (using the *flow_logs* attribute. See [Module Functioning](#functioning)):
+```
+Allow group <group> to inspect compartments in tenancy
+Allow group <group> to manage subnets in compartment <subnet-compartment-name> where request.permission = 'SUBNET_UPDATE'
+```
+
+For deploying bucket logs (using the *service_logs* attribute. See [Module Functioning](#functioning)):
+```
+Allow group <group> to use buckets in compartment <bucket-compartment-name>
+```
+
+For deploying bucket logs (using the *bucket_logs* attribute. See [Module Functioning](#functioning)):
+```
+Allow group <group> to inspect compartments in tenancy
+Allow group <group> to read objectstorage-namespaces in tenancy
+Allow group <group> to use buckets in compartment <bucket-compartment-name>
+```
+
+### Terraform Version < 1.3.x and Optional Object Type Attributes
+This module relies on [Terraform Optional Object Type Attributes feature](https://developer.hashicorp.com/terraform/language/expressions/type-constraints#optional-object-type-attributes), which is experimental from Terraform 0.14.x to 1.2.x. It shortens the amount of input values in complex object types, by having Terraform automatically inserting a default value for any missing optional attributes. The feature has been promoted and it is no longer experimental in Terraform 1.3.x.
+
+**As is, this module can only be used with Terraform versions up to 1.2.x**, because it can be consumed by other modules via [OCI Resource Manager service](https://docs.oracle.com/en-us/iaas/Content/ResourceManager/home.htm), that still does not support Terraform 1.3.x.
+
+Upon running *terraform plan* with Terraform versions prior to 1.3.x, Terraform displays the following warning:
+```
+Warning: Experimental feature "module_variable_optional_attrs" is active
+```
+
+Note the warning is harmless. The code has been tested with Terraform 1.3.x and the implementation is fully compatible.
+
+If you really want to use Terraform 1.3.x, in [providers.tf](./providers.tf):
+1. Change the terraform version requirement to:
+```
+required_version = ">= 1.3.0"
+```
+2. Remove the line:
+```
+experiments = [module_variable_optional_attrs]
+```
+## <a name="invoke">How to Invoke the Module</a>
+
+Terraform modules can be invoked locally or remotely. 
+
+For invoking the module locally, just set the module *source* attribute to the module file path (relative path works). The following example assumes the module is two folders up in the file system.
+```
+module "logging" {
+  source = "../.."
+  tenancy_ocid = var.tenancy_ocid # for deploying bucket logs using bucket_logs attribute.
+  logging_configuration = var.logging_configuration
+}
+```
+
+For invoking the module remotely, set the module *source* attribute to the logging module folder in this repository, as shown:
+```
+module "logging" {
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability/logging"
+  tenancy_ocid = var.tenancy_ocid # for deploying bucket logs using bucket_logs attribute.
+  logging_configuration = var.logging_configuration
+}
+```
+For referring to a specific module version, append *ref=\<version\>* to the *source* attribute value, as in:
+```
+  source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-observability//logging?ref=v0.1.0"
+```
+## <a name="functioning">Module Functioning</a>
+
+In this module, log groups and logs are defined using the top-level *logging_configuration* variable. It contains a set of attributes starting with the prefix *default_* and a set of attributes to define any number of log groups and logs. The *default_* attribute values are applied to all log groups and logs, unless overriden at the object level. **The module supports defining service and custom logs for single resources or for a set of resources within specified compartments**. For defining logs to single resources, use either *service_logs* or *custom_logs* attributes. For defining service logs to a set of resources within specified compartments, use *flow_logs* or *bucket_logs* attributes.
+
+**Note**: *log_groups*, *service_logs*, *flow_logs*, *bucket_logs* and *custom_logs* are maps of objects. Each object is defined as a key/value pair. The key must be unique and not be changed once defined. See the [examples](./examples/) folder for sample declarations.
+
+The *default_* attributes are the following:
+
+- **default_compartment_id**: (Optional) The default compartment for all resources managed by this module. It can be overriden by *compartment_id* attribute in each resource. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. See [External Dependencies](#extdep) section.
+- **default_defined_tags**: (Optional) The default defined tags that are applied to all resources managed by this module. It can be overriden by *defined_tags* attribute in each resource.
+- **default_freeform_tags**: (Optional) The default freeform tags that are applied to all resources managed by this module. It can be overriden by *freeform_tags* attribute in each resource.
+
+### Defining Log Groups
+- **log_groups**: A map of log groups. In OCI, every log must be belong to a log group.
+  - **compartment_id**: (Optional) The compartment where the log group is created. *default_compartment_id* is used if undefined. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. See [External Dependencies](#extdep) section.
+  - **name**: The log group name.             
+  - **description**: (Optional) The log group description. It defaults to log group name if undefined.      
+  - **defined_tags**: (Optional) The log group defined tags. *default_defined_tags* is used if undefined.
+  - **freeform_tags**: (Optional) The log group freeform tags. *default_freeform_tags* is used if undefined.
+
+### Defining Service Logs  
+- **service_logs**: (Optional) A map of service logs. **Use this when defining service logs for single resources**. Logs are created in the same compartment as the enclosing log group.
+  - **name**: The log name.
+  - **log_group_id**: The log group. The value should be one of the reference keys defined in *log_groups*.
+  - **service**: The resource service name for which the log is being created. Sample valid values: "flowlogs", "objectstorage". Supported services may change over time. See [Services Integrated with the Logging Services and their Categories](#services).
+  - **category**: The category name within each service. This is service specific and valid values may change over time. See [Services Integrated with the Logging Services and their Categories](#services).
+  - **resource_id**: The resource id to create the log for.
+  - **is_enabled**: (Optional) Whether the log is enabled. Default is true.
+  - **retention_duration**: (Optional) The log retention duration in 30-day increments. Valida values are 30, 60, 90, 120, 150, 180. Default is 30. 
+  - **defined_tags**: (Optional) The log defined tags. *default_defined_tags* is used if undefined.
+  - **freeform_tags**: (Optional) The log freeform tags. *default_freeform_tags* is used if undefined.
+
+### Defining Flow Logs
+- **flow_logs**: A map of flow logs. **Use this when defining flow logs in bulk within specified compartments**. Logs are created in the same compartment as the enclosing flow log group.
+  - **name_prefix**: (Optional) a prefix to flow log names.
+  - **log_group_id** The flow log group. The value should be one of the reference keys defined in *log_groups*.
+  - **target_resource_type** The target resource type for flow logs. Valid values: "vcn", "subnet", "vnic".
+  - **target_compartment_ids** The list of compartments containing the resources of type defined in target_resource_type to create flow logs for. The module searches for all resources of target_resource_type in these compartments. For "vnic" target_resource_type, NLB (Network Load Balancer) private IP VNICs are also included.
+  - **is_enabled**: (Optional) Whether the flow logs are enabled. Default is true.
+  - **retention_duration**: (Optional) The flow log retention duration in 30-day increments. Valida values are 30, 60, 90, 120, 150, 180. Default is 30. 
+  - **defined_tags**: (Optional) The flow log defined tags. *default_defined_tags* is used if undefined.
+  - **freeform_tags**: (Optional) The flow log freeform tags. *default_freeform_tags* is used if undefined.
+
+### Defining Bucket Logs  
+- **bucket_logs**: A map of bucket logs. **Use this when defining bucket logs in bulk within specified compartments**. Logs are created in the same compartment as the enclosing bucket log group.
+  - **name_prefix**: (Optional) a prefix to bucket log names.
+  - **log_group_id**: The bucket log group. The value should be one of the reference keys defined in *log_groups*.
+  - **target_compartment_ids**: The list of compartments containing the buckets to create logs for. The module seaeches for all buckets in these compartments.
+  - **category**: The category of operations to enable the bucket logs for. Valid values: "read" or "write".
+  - **is_enabled**: (Optional) Whether the bucket logs are enabled. Default is true.
+  - **retention_duration**: (Optional) The bucket log retention duration in 30-day increments. Valida values are 30, 60, 90, 120, 150, 180. Default is 30. 
+  - **defined_tags**: (Optional) The bucket log defined tags. *default_defined_tags* is used if undefined.
+  - **freeform_tags**: (Optional) The bucket log freeform tags. *default_freeform_tags* is used if undefined.
+
+### Defining Custom Logs  
+- **custom_logs**: A map of custom logs. **Use this when defining custom logs for single resources**. Logs are created in the same compartment as the enclosing log group.
+  - **compartment_id**: (Optional) The compartment where log is created. *default_compartment_id* is used if undefined. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID.
+  - **name**: The log name.
+  - **log_group_id**: The log group. The value should be one of the reference keys defined in *log_groups*.
+  - **dynamic_groups**: The list of dynamic groups associated with this configuration
+  - **parser_type**: (Optional) The type of fluent parser. Valid values: "NONE", "SYSLOG", "CSV", "TSV", "REGEXP", "MULTILINE", "APACHE_ERROR", "APACHE2", "AUDITD", "JSON", "CRI". Default is "NONE".
+  - **path**: Absolute paths for log source files. Wildcards can be used.
+  - **is_enabled**: (Optional) Whether the log is enabled. Default is true.
+  - **retention_duration**: (Optional) The log retention duration in 30-day increments. Valida values are 30, 60, 90, 120, 150, 180. Default is 30. 
+  - **defined_tags**: (Optional) The log defined tags. *default_defined_tags* is used if undefined.
+  - **freeform_tags**: (Optional) The log freeform tags. *default_freeform_tags* is used if undefined.
+
+### <a name="services">Services Integrated with the Logging Services and their Categories</a>
+
+As of Oct/2023, these are the OCI services that are integrated with the Logging service. Use this as reference to fill in *service* and *category* attributes when creating logs using the *service_log* attribute.
+For any updates, use OCI CLI to execute ```oci logging service list```.
+
+Service | Service Name | Categories 
+--------------|-------------|-------------
+Analytics Cloud |"oacnativeproduction" | "audit", "diagnostic"
+API Gateway | "apigateway" | "access", "execution"
+Application Dependency Management | "adm" | "remediationrecipelogs"
+Application Performance Monitoring | "apm" | "dropped-data"
+Connector Hub | "och" | "runlog"
+Container Engine for Kubernetes | "oke-k8s-cp-prod" | "kube-apiserver", "all-service-logs", "cloud-controller-manager", "kube-controller-manager", "kube-scheduler"
+Content Delivery Network | "contentdeliverynetwork" | "access", "error"
+Data Flow | "dataflow" | "diagnostic"
+Data Integration Service | "dataintegration" | "disworkspacelogs"
+Data Science | "datascience" | "pipelinerunlog"
+DevOps | "devops" | "all"
+Email Delivery | "emaildelivery" | "outboundaccepted", "outboundrelayed"
+Events Service | "cloudevents" | "ruleexecutionlog"
+File Storage | "filestorage" | "nfslogs"
+Functions | "functions" | "invoke"
+GoldenGate | "goldengate" | "process_logs", "error_logs"
+Integration | "integration" | "activitystream"
+Load Balancers | "loadbalancer" | "access", "error"
+Media Flow | "mediaflow" | "execution"
+Network Firewall | "ocinetworkfirewall" | "threatlog", "trafficlog"
+Object Storage | "objectstorage" | "read", "write"
+Operator Access Control Service | "operatoraccessprod" | "access"
+Site-To-Site VPN | "oci_c3_vpn" | "read"
+Virtual Cloud Network - Flowlogs | "flowlogs" | "vcn", "subnet", "vnic", "all" (valid for subnets only)
+WAA Service | "waa" | "all"
+WAF Service | "waf" | "all"
+
+### <a name="extdep">External Dependencies</a>
+
+An optional feature, external dependencies are resources managed elsewhere that resources managed by this module may depend on. The following dependencies are supported:
+
+- **compartments_dependency**: A map of objects containing the externally managed compartments this module may depend on. All map objects must have the same type and must contain at least an *id* attribute with the compartment OCID. This mechanism allows for the usage of referring keys (instead of OCIDs) in *default_compartment_id* and *compartment_id* attributes. The module replaces the keys by the OCIDs provided within *compartments_dependency* map. Contents of *compartments_dependency* is typically the output of a [Compartments module](../compartments/) client.
+
+## <a name="related">Related Documentation</a>
+- [OCI Logging](https://docs.oracle.com/en-us/iaas/Content/Logging/home.htm)
+- [Logging in Terraform OCI Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/logging_log)
+
+## <a name="issues">Known Issues</a>
+None.