making resources that use an SDK polymorphic object use a consistent pattern

Author: rcohenma

docs/core/boot_volumes.md

@@ -17,8 +17,8 @@ The following attributes are exported:
 * `size_in_gbs` - The size of the boot volume in GBs.
 * `size_in_mbs` - The size of the volume in MBs. The value must be a multiple of 1024. This field is deprecated. Please use `size_in_gbs`. 
 * `source_details` - The boot volume source, either an existing boot volume in the same Availability Domain or a boot volume backup. If null, this means that the boot volume was created from an image. 
-	* `type` - The type of the boot volume source. Supported values are `bootVolumeBackup` and `bootVolume`
 	* `id` - The OCID of the boot volume backup or the boot volume
+	* `type` - The type of the boot volume source. Supported values are `bootVolumeBackup` and `bootVolume`
 * `state` - The current state of a boot volume.
 * `time_created` - The date and time the boot volume was created. Format defined by RFC3339.
 * `volume_group_id` - The OCID of the source volume group.
@@ -41,8 +41,8 @@ The following arguments are supported:
 * `display_name` - (Optional) A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information. 
 * `freeform_tags` - (Optional) Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).  Example: `{"Department": "Finance"}` 
 * `source_details` - (Required) Specifies the boot volume source details for a new boot volume. The volume source is either another boot volume in the same Availability Domain or a boot volume backup. This is a mandatory field for a boot volume. 
-	* `type` - (Required) The type of the boot volume source. Supported values are `bootVolumeBackup` and `bootVolume`
 	* `id` - (Required) The OCID of the boot volume backup or the boot volume
+	* `type` - (Required) The type of the boot volume source. Supported values are `bootVolumeBackup` and `bootVolume`
 
 
 ### Update Operation
@@ -66,6 +66,7 @@ resource "oci_core_boot_volume" "test_boot_volume" {
 	compartment_id = "${var.compartment_id}"
 	source_details {
 		#Required
+		id = "${var.boot_volume_source_details_id}"
 		type = "${var.boot_volume_source_details_type}"
 	}
 

docs/core/dhcp_options.md

@@ -61,12 +61,12 @@ The following arguments are supported:
 * `display_name` - (Optional) A user-friendly name for the image. It does not have to be unique, and it's changeable. Avoid entering confidential information.  You cannot use an Oracle-provided image name as a custom image name.  Example: `My Oracle Linux image` 
 * `freeform_tags` - (Optional) Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).  Example: `{"Department": "Finance"}` 
 * `image_source_details` - (Optional) Details for creating an image through import
+	* `bucket_name` - (Required when source_type=objectStorageTuple) The Object Storage bucket for the image.
+	* `namespace_name` - (Required when source_type=objectStorageTuple) The Object Storage namespace for the image.
+	* `object_name` - (Required when source_type=objectStorageTuple) The Object Storage name for the image.
     * `source_image_type` - (Optional) The format of the image to be imported. Exported Oracle images are QCOW2. Only monolithic images are supported. Allowed values are: - `QCOW2` - `VMDK`
-    * `source_type` - (Required) The source type for the image. Use objectStorageTuple when specifying the namespace, bucket name, and object name. Use `objectStorageUri` when specifying the Object Storage URL. Allowed values are: - `objectStorageTuple` - `objectStorageUri` 
-    * `source_uri` - (Required for objectStorageUri source_type) The Object Storage URL for the image.
-    * `bucket_name` - (Required for objectStorageTuple source_type) The Object Storage bucket for the image.
-    * `namespace_name` - (Required for objectStorageTuple source_type) The Object Storage namespace for the image.
-    * `object_name` - (Required for objectStorageTuple source_type) The Object Storage name for the image.
+	* `source_type` - (Required) The source type for the image. Use `objectStorageTuple` when specifying the namespace, bucket name, and object name. Use `objectStorageUri` when specifying the Object Storage URL. 
+	* `source_uri` - (Required when source_type=objectStorageUri) The Object Storage URL for the image.
 * `instance_id` - (Optional -- required when not specifying `image_source_details`) The OCID of the instance you want to use as the basis for the image.
 * `launch_mode` - (Optional) Specifies the configuration mode for launching virtual machine (VM) instances. The configuration modes are: 
     * `NATIVE` - VM instances launch with iSCSI boot and VFIO devices. The default value for Oracle-provided images. 

docs/core/images.md

@@ -26,6 +26,7 @@ The following attributes are exported:
 	    * `SCSI` - Emulated SCSI disk. 
 	    * `IDE` - Emulated IDE disk. 
 	    * `VFIO` - Direct attached Virtual Function storage.  This is the default option for Local data volumes on Oracle provided images. 
+		* `PARAVIRTUALIZED` - Paravirtualized disk. 
 	* `firmware` - Firmware used to boot VM.  Select the option that matches your operating system. 
 	    * `BIOS` - Boot VM using BIOS style firmware.  This is compatible with both 32 bit and 64 bit operating systems that boot using MBR style bootloaders. 
 	    * `UEFI_64` - Boot VM using UEFI style firmware compatible with 64 bit operating systems.  This is the default for Oracle provided images. 
@@ -37,6 +38,7 @@ The following attributes are exported:
 	    * `SCSI` - Emulated SCSI disk. 
 	    * `IDE` - Emulated IDE disk. 
 	    * `VFIO` - Direct attached Virtual Function storage.  This is the default option for Local data volumes on Oracle provided images. 
+		* `PARAVIRTUALIZED` - Paravirtualized disk. 
 * `metadata` - Custom metadata that you provide.
 * `preserve_boot_volume` - Specifies whether to delete or preserve the boot volume when terminating an instance. The default value is false. Note: This value only applies to destroy operations initiated by Terraform.
 * `private_ip` - The private IP address of instance VNIC. To set the private IP address, use the `private_ip` argument in create_vnic_details.
@@ -110,7 +112,7 @@ The following arguments are supported:
 * `preserve_boot_volume` - (Optional) Specifies whether to delete or preserve the boot volume when terminating an instance. The default value is false. Note: This value only applies to destroy operations initiated by Terraform. 
 * `shape` - (Required) The shape of an instance. The shape determines the number of CPUs, amount of memory, and other resources allocated to the instance.  You can enumerate all available shapes by calling [ListShapes](https://docs.us-phoenix-1.oraclecloud.com/api/#/en/iaas/20160918/Shape/ListShapes). 
 * `source_details` - (Optional) Details for creating an instance. Use this parameter to specify whether a boot volume or an image should be used to launch a new instance. 
-    * `boot_volume_size_in_gbs` - (Optional) The size of the boot volume in GBs. Minimum value is 50 GB and maximum value is 16384 GB (16TB). This should only be specified when `source_type` is `image`.
+	* `boot_volume_size_in_gbs` - (Applicable when source_type=image) The size of the boot volume in GBs. Minimum value is 50 GB and maximum value is 16384 GB (16TB).
     * `source_id` - (Required) The OCID of an image or a boot volume to use, depending on the value of `source_type`. 
 	* `source_type` - (Required) The source type for the instance. Use `image` when specifying the image OCID. Use `bootVolume` when specifying the boot volume OCID. 
 * `subnet_id` - (Optional) Deprecated. Instead use `subnetId` in [CreateVnicDetails](https://docs.us-phoenix-1.oraclecloud.com/api/#/en/iaas/20160918/CreateVnicDetails/). At least one of them is required; if you provide both, the values must match. 
@@ -173,8 +175,8 @@ resource "oci_core_instance" "test_instance" {
 	}
 	source_details {
 	    #Required
-	    source_type = "image"
 	    source_id = "${oci_core_image.test_image.id}"
+	    source_type = "image"
 
 	    #Optional
 	    boot_volume_size_in_gbs = "60"

docs/core/instances.md

@@ -35,7 +35,7 @@ The following arguments are supported:
 * `display_name` - (Optional) A user-friendly name. Does not have to be unique, and it cannot be changed. Avoid entering confidential information. 
 * `instance_id` - (Required) The OCID of the instance.
 * `is_read_only` - (Optional) Whether the attachment was created in read-only mode.
-* `use_chap` - (Optional) Whether to use CHAP authentication for the volume attachment. This only applies if the attachment type is "iscsi".
+* `use_chap` - (Applicable when attachment_type=iscsi) Whether to use CHAP authentication for the volume attachment. Defaults to false.
 * `volume_id` - (Required) The OCID of the volume.
 
 
@@ -53,13 +53,14 @@ Any change to a property that does not support update will force the destruction
 ```hcl
 resource "oci_core_volume_attachment" "test_volume_attachment" {
 	#Required
+	attachment_type = "${var.volume_attachment_attachment_type}"
 	instance_id = "${oci_core_instance.test_instance.id}"
-	attachment_type = "iscsi"
 	volume_id = "${oci_core_volume.test_volume.id}"
 
 	#Optional
 	display_name = "${var.volume_attachment_display_name}"
 	is_read_only = "${var.volume_attachment_is_read_only}"
+	use_chap = "${var.volume_attachment_use_chap}"
 }
 ```
 

docs/core/volume_attachments.md

@@ -16,9 +16,9 @@ The following attributes are exported:
 * `size_in_mbs` - The aggregate size of the volume group in MBs.
 * `source_details` - The volume group source. The source is either another a list of volume IDs in the same availability domain, another volume group, or a volume group backup. 
 	* `type` - The type of the volume group source. It should be set to either `volumeIds`, `volumeGroup`, or `volumeBackup`
-	* `volume_ids` - OCIDs for the volumes in this volume group, if the type is `volumeIds`
-	* `volume_group_id` - The OCID of the volume group to clone from, if the type is `volumeGroup`
-	* `volume_group_backup_id` - The OCID of the volume group backup to restore from, if the type is `volumeGroupBackup` 
+	* `volume_group_backup_id` - The OCID of the volume group backup to restore from.
+	* `volume_group_id` - The OCID of the volume group to clone from.
+	* `volume_ids` - OCIDs for the volumes in this volume group.
 * `state` - The current state of a volume group.
 * `time_created` - The date and time the volume group was created. Format defined by RFC3339.
 * `volume_ids` - OCIDs for the volumes in this volume group.
@@ -44,9 +44,9 @@ The following arguments are supported:
 * `freeform_tags` - (Optional) Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm).  Example: `{"Department": "Finance"}` 
 * `source_details` - (Required) Specifies the volume group source details for a new volume group. The volume source is either another a list of volume ids in the same Availability Domain, another volume group or a volume group backup. 
 	* `type` - (Required) The type of the volume group source. It should be set to either `volumeIds`, `volumeGroup`, or `volumeBackup`
-	* `volume_ids` (Optional) - OCIDs for the volumes in this volume group, if the type is `volumeIds`
-	* `volume_group_id` (Optional) - The OCID of the volume group to clone from, if the type is `volumeGroup`
-	* `volume_group_backup_id` (Optional) - The OCID of the volume group backup to restore from, if the type is `volumeGroupBackup` 
+	* `volume_group_backup_id` - (Required when type=volumeGroupBackupId) The OCID of the volume group backup to restore from.
+	* `volume_group_id` - (Required when type=volumeGroupId) The OCID of the volume group to clone from.
+	* `volume_ids` - (Required when type=volumeIds) OCIDs for the volumes in this volume group.
 
 
 ### Update Operation

docs/core/volume_groups.md

@@ -16,8 +16,8 @@ The following attributes are exported:
 * `size_in_gbs` - The size of the volume in GBs.
 * `size_in_mbs` - The size of the volume in MBs. This field is deprecated. Use `size_in_gbs` instead.
 * `source_details` - The volume source, either an existing volume in the same Availability Domain or a volume backup. If null, an empty volume is created. 
-	* `type` - The type of volume source. It should be set to either `volumeBackup` or `volume`.
 	* `id` - The OCID of the volume or volume backup.
+	* `type` - The type of volume source. It should be set to either `volumeBackup` or `volume`.
 * `state` - The current state of a volume.
 * `time_created` - The date and time the volume was created. Format defined by RFC3339.
 * `volume_group_id` - The OCID of the source volume group.
@@ -51,8 +51,8 @@ The following arguments are supported:
 * `size_in_gbs` - (Optional) The size of the volume in GBs.
 * `size_in_mbs` - (Optional) The size of the volume in MBs. The value must be a multiple of 1024. This field is deprecated. Use sizeInGBs instead. 
 * `source_details` - (Optional) Specifies the volume source details for a new Block volume. The volume source is either another Block volume in the same Availability Domain or a Block volume backup. This is an optional field. If not specified or set to null, the new Block volume will be empty. When specified, the new Block volume will contain data from the source volume or backup. 
-	* `type` - (Required) The type of volume source. It should be set to either `volumeBackup` or `volume`.
 	* `id` - (Required) The OCID of the volume or volume backup.
+	* `type` - (Required) The type of volume source. It should be set to either `volumeBackup` or `volume`.
 * `volume_backup_id` - (Optional) The OCID of the volume backup from which the data should be restored on the newly created volume. This field is deprecated. Use the `source_details` field instead to specify the backup for the volume. 
 
 
@@ -86,8 +86,8 @@ resource "oci_core_volume" "test_volume" {
 	size_in_mbs = "${var.volume_size_in_mbs}"
 	source_details {
 		#Required
-		type = "${var.volume_source_details_type}"
 		id = "${var.volume_source_details_id}"
+		type = "${var.volume_source_details_type}"
 	}
 }
 ```