Update oracle-oci.html.md

Updated documentation

website/source/docs/builders/oracle-oci.html.md

@@ -33,6 +33,9 @@ authentication see the documentation on [Required Keys and
 OCIDs](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm)
 ([Oracle Cloud
 IDs](https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/identifiers.htm)).
+Alternatively you can use [Instance
+Principals](https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm)
+in which case you don't need the above user authorization.
 
 ## Configuration Reference
 
@@ -65,11 +68,6 @@ builder.
 -   `compartment_ocid` (string) - The OCID of the
     [compartment](https://docs.us-phoenix-1.oraclecloud.com/Content/GSG/Tasks/choosingcompartments.htm)
 
--   `fingerprint` (string) - Fingerprint for the OCI API signing key. Overrides
-    value provided by the [OCI config
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
-
 -   `shape` (string) - The template that determines the number of CPUs, amount
     of memory, and other resources allocated to a newly created instance.
 
@@ -90,41 +88,51 @@ builder.
 
 ### Optional
 
+-   `use_instance_principals` (boolean) - Whether to use [Instance
+    Principals](https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm)
+    instead of User Principals. If this key is set to true, setting any one of the `access_cfg_file`,
+    `access_cfg_file_account`, `region`, `tenancy_ocid`, `user_ocid`, `key_file`, `fingerprint`, 
+    `pass_phrase` will result in configuration validation errors.
+    Defaults to `false`.
+
 -   `access_cfg_file` (string) - The path to the [OCI config
     file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm).
+    This cannot be used along with the `use_instance_principals` key.
     Defaults to `$HOME/.oci/config`.
 
--   `access_cfg_file_account` (string) - The specific account in the [OCI
+-   `access_cfg_file_account` (string) - The specific account in the [OCI config
-    config
+    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm) to use.
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
+    This cannot be used along with the `use_instance_principals` key.
-    to use. Defaults to `DEFAULT`.
+    Defaults to `DEFAULT`.
+
+-   `region` (string) - An Oracle Cloud Infrastructure region. Overrides value provided by the
+    [OCI config file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
+    if present. This cannot be used along with the `use_instance_principals` key.
+
+-   `tenancy_ocid` (string) - The OCID of your tenancy. Overrides value provided by the [OCI config
+    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm) if present.
+    This cannot be used along with the `use_instance_principals` key.
+
+-   `user_ocid` (string) - The OCID of the user calling the OCI API. Overrides value provided by the
+    [OCI config file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
+    if present. This cannot be used along with the `use_instance_principals` key.
+
+-   `key_file` (string) - Full path and filename of the OCI API signing key. Overrides value provided
+    by the [OCI config file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
+    if present. This cannot be used along with the `use_instance_principals` key.
+
+-   `fingerprint` (string) - Fingerprint for the OCI API signing key. Overrides value provided by the
+    [OCI config file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm) if
+    present. This cannot be used along with the `use_instance_principals` key.
+
+-   `pass_phrase` (string) - Pass phrase used to decrypt the OCI API signing key. Overrides value provided
+    by the [OCI config file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
+    if present. This cannot be used along with the `use_instance_principals` key.
 
 -   `image_name` (string) - The name to assign to the resulting custom image.
 
--   `key_file` (string) - Full path and filename of the OCI API signing key.
+-   `instance_name` (string) - The name to assign to the instance used for the image creation process.
-    Overrides value provided by the [OCI config
+    If not set a name of the form `instanceYYYYMMDDhhmmss` will be used.
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
-
--   `pass_phrase` (string) - Pass phrase used to decrypt the OCI API signing
-    key. Overrides value provided by the [OCI config
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
-
--   `region` (string) - An Oracle Cloud Infrastructure region. Overrides value
-    provided by the [OCI config
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
-
--   `tenancy_ocid` (string) - The OCID of your tenancy. Overrides value
-    provided by the [OCI config
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
-
--   `user_ocid` (string) - The OCID of the user calling the OCI API. Overrides
-    value provided by the [OCI config
-    file](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm)
-    if present.
 
 -   `use_private_ip` (boolean) - Use private ip addresses to connect to the
     instance via ssh.
@@ -191,3 +199,46 @@ substituted with the letter `a` and OCIDS have been shortened for brevity.
     "type": "oracle-oci"
 }
 ```
+
+## Using Instance Principals
+
+Here is a basic example. Note that account specific configuration has been
+substituted with the letter `a` and OCIDS have been shortened for brevity.
+
+```json
+{
+    "use_instance_principals": "true",
+    "availability_domain": "aaaa:PHX-AD-1",
+    "base_image_ocid": "ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa",
+    "compartment_ocid": "ocid1.compartment.oc1..aaa",
+    "image_name": "ExampleImage",
+    "shape": "VM.Standard2.1",
+    "ssh_username": "opc",
+    "subnet_ocid": "ocid1.subnet.oc1..aaa",
+    "type": "oracle-oci"
+}
+```
+
+```
+[opc@packerhost ~]$ packer build packer.json
+oracle-oci: output will be in this color.
+
+==> oracle-oci: Creating temporary ssh key for instance...
+==> oracle-oci: Creating instance...
+==> oracle-oci: Created instance (ocid1.instance.oc1.phx.aaa).
+==> oracle-oci: Waiting for instance to enter 'RUNNING' state...
+==> oracle-oci: Instance 'RUNNING'.
+==> oracle-oci: Instance has IP: 10.10.10.10.
+==> oracle-oci: Using ssh communicator to connect: 10.10.10.10
+==> oracle-oci: Waiting for SSH to become available...
+==> oracle-oci: Connected to SSH!
+==> oracle-oci: Creating image from instance...
+==> oracle-oci: Image created.
+==> oracle-oci: Terminating instance (ocid1.instance.oc1.phx.aaa)...
+==> oracle-oci: Terminated instance.
+Build 'oracle-oci' finished.
+
+==> Builds finished. The artifacts of successful builds are:
+--> oracle-oci: An image was created: 'ExampleImage' (OCID: ocid1.image.oc1.phx.aaa) in region 'us-phoenix-1'
+[opc@packerhost ~]$
+```