docs: update module block in main README (#82)

* docs: update module block in main README

move iSCSI Block Volumes related information to a dedicated documentation page

* fix: iscsiadm link targets the relevant line of code

Author: kral2

README.md

@@ -54,6 +54,8 @@ module "instance" {
   ssh_public_keys            = var.ssh_public_keys
   block_storage_sizes_in_gbs = [50]
   shape                      = var.shape
+  instance_state             = var.instance_state # RUNNING or STOPPED
+  boot_volume_backup_policy  = var.boot_volume_backup_policy # disabled, gold, silver or bronze
 }
 ```
 
@@ -63,13 +65,7 @@ The current focus is to close the gap between this module and the provider's cap
 
 We will continue to push in that direction with the goal of [feature parity with the provider's capabilities](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/projects/4), as well as adding more features and integration points with other OCI services: Block Volume Backups, Secondary VNICs and IPs, etc ...
 
-Given the dependency to Network and Storage for Compute Instances,it is a perfect place to illustrate [module composition principles](https://www.terraform.io/docs/language/modules/develop/composition.html) and how to reuse the other official Terraform OCI modules.
-
-## Configuring iSCSI volume attachments
-
-- For guidance configuring iSCSI on a Windows platform, see [Adding a Block Volume to a Windows Instance](https://docs.cloud.oracle.com/iaas/Content/GSG/Tasks/addingstorageForWindows.htm).
-
-- For guidance configuring iSCSI on a Linux platform, see [iSCSI Commands and Information](https://docs.cloud.oracle.com/iaas/Content/Block/Concepts/iscsiinformation.htm). See also this example of inline iSCSI commands execution using `iscsiadm` CLI called from terraform file: [instance.tf](https://github.com/terraform-providers/terraform-provider-oci/blob/master/examples/compute/instance/instance.tf).
+Given the dependency to Network and Storage for Compute Instances, it is a perfect place to illustrate [module composition principles](https://www.terraform.io/docs/language/modules/develop/composition.html) and how to reuse the other official Terraform OCI modules.
 
 ## Contributing
 

docs/iscsi_volume_attachements.adoc

@@ -0,0 +1,44 @@
+= Configuring iSCSI volume attachments
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+:idprefix:
+:idseparator: -
+:sectlinks:
+:toc:
+
+:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-vcn
+:uri-rel-file-base: link:{uri-repo}/blob/main
+:uri-rel-tree-base: link:{uri-repo}/tree/main
+:uri-docs: {uri-rel-file-base}/docs
+:uri-oci-security-credentials: https://docs.oracle.com/en-us/iaas/Content/General/Concepts/credentials.htm#Instance
+:uri-oci-core-instance: https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_instance#metadata
+:uri-tf-heredoc: https://www.terraform.io/docs/language/expressions/strings.html#heredoc-strings
+:uri-tf-file-function: https://www.terraform.io/docs/language/functions/file.html
+:uri-adding-bv-linux: https://docs.cloud.oracle.com/iaas/Content/Block/Concepts/iscsiinformation.htm
+:uri-adding-bv-windows: https://docs.cloud.oracle.com/iaas/Content/GSG/Tasks/addingstorageForWindows.htm
+:uri-inline-iscsi-cmd: https://github.com/terraform-providers/terraform-provider-oci/blob/afe6f577b70e24c31c8bcddf6a3750d6b0f9e74c/examples/compute/instance/instance.tf#L204
+:uri-tf-remote-exec: https://www.terraform.io/docs/language/resources/provisioners/remote-exec.html
+:uri-oci-ocid-daemon: https://docs.oracle.com/en-us/iaas/Content/Compute/References/ocid.htm
+
+If you attach additional Block Volumes to your compute instance with an attachement type `iSCSI`, the operating system needs to be aware of this new device before it can be used.
+
+There is two methods for that:
+
+- configuring the device manually with the operating system tools,
+- automatically configure the device using an OCI helper: `ocid` daemon.
+
+== Configuring additional devices manually
+
+- For guidance on configuring iSCSI on a Windows platform, see {uri-adding-bv-windows}[Adding a Block Volume to a Windows Instance].
+- For guidance on configuring iSCSI on a Linux platform, see {uri-adding-bv-linux}[iSCSI Commands and Information]. See also this example on the oci provider documentation of {uri-inline-iscsi-cmd}[inline iSCSI commands execution using iscsiadm CLI] using a {uri-tf-remote-exec}[Terraform remote-exec].
+
+== Configuration additional devices automatically
+
+The `ocid` daemon is the service component of the `oci-utils`. It monitors for changes in the VNIC and iSCSI configuration of the instance and attempts to automatically attach or detach devices as they appear or disappear - for example, when they are created or deleted using the Oracle Cloud Infrastructure Console, CLI, or the API.
+
+See {uri-oci-ocid-daemon}[the ocid daemon documentation] for more details.