feat: add reserved public ip (#71)

- var.public_ip and var.public_ip_display_name are added to control this new feature
- var.public_ip accept a string with value NONE, RESERVED or EPHEMERAL. each keyword does what it says.

- var.assign_public_ip becomes deprecated

- rename terraform resources from <this> to more meaningful name

fix #55

Author: kral2

CHANGELOG.adoc

@@ -19,12 +19,16 @@ Given a version number MAJOR.MINOR.PATCH:
 === Deprecated
 
 * `var.ssh_authorized_keys` is deprecated. Use `var.ssh_public_keys`.
+* `var.assign_public_ip` is deprecated. Use `var.public_ip` with the predefined keywords instead.
 
 === New features
 
 * Add support for freeform and defined tags for instances, vnics and block volumes (Fix #10, #11, #12, #13, #18, #20)
 * Add "module watermark" freeform tags: module defined and user defined freeform tags are merged on the final resource
 * Add support to provide the `ssh_authorized_keys` argument as a string or as a file (Fix #67 #70)
+* Add support for reserved Public IP on instance first VNIC (fix #55)
+* [ ] Define a backup policy for boot volume and additional block volumes (fix #64)
+* Add new outputs for each provisioned resources: "all_attributes" outputs have full provider coverage and are auto-updating.
 
 === Documentation
 
@@ -47,7 +51,6 @@ Given a version number MAJOR.MINOR.PATCH:
 * Outputs produces unnecessarily multidimensional objects (Issue #31)
 * Repo maintenance:
 ** add .gitattributes for consistent line ending and tab
-** add pre-commit configuration file
 
 == 2.0.4 - 2021-02-13
 

README.md

@@ -1,6 +1,6 @@
 # Oracle Cloud Infrastructure Terraform Module for Compute Instance
 
-This Module provides an easy way to launch compute instances with advanced settings and good practices embedded.
+This module provides an easy way to launch compute instances with advanced settings and good practices embedded.
 
 On top of the compute instance capabilities, this module can also provision and attach additional Block Volumes to the instances.
 
@@ -10,24 +10,20 @@ On top of the compute instance capabilities, this module can also provision and
 >
 > Oracle recommends that you do not use custom images without these rules unless you understand the security risks. See [Compute Best Practices](https://docs.cloud.oracle.com/iaas/Content/Compute/References/bestpracticescompute.htm#two) for recommendations on how to manage instances.
 
-## Maintainers
-
-This module is maintained by Oracle.
-
 ## Requirements
 
 The diagram below summarizes the required components and their respective versions to use this module.
 
 ![versions](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/blob/main/docs/diagrams/versions.svg?raw=true&sanitize=true)
 
-To enforce versions compatibility of both Terraform and the OCI provider, your root configuration should ideally include this block in `main.tf` for version pinning:
+To enforce versions compatibility of both Terraform and the OCI provider, your root configuration should ideally include this block for version pinning:
 
 ```HCL
 terraform {
-  required_version = ">= 0.12"
+  required_version = ">= 0.12.6"
   required_providers {
     oci = {
-      version = ">= 3.27"
+      version = ">= 4.0.0"
     }
   }
 }
@@ -59,11 +55,11 @@ module "instance" {
 
 ## What's coming next for this module?
 
-The current focus is to get back in close the gap between this module and the provider's capabilities. We started with a complete code base update for [HCL2 syntax compatibility](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/releases/tag/v2.0.2), then adding support for [Regional Subnets](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/releases/tag/v2.0.4) and now [Flexible Shapes](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/pull/49).
+The current focus is to close the gap between this module and the provider's capabilities. We started with a complete codebase update for [HCL2 syntax compatibility](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/releases/tag/v2.0.2), then adding support for [Regional Subnets](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/releases/tag/v2.0.4) and lastly [Flexible Shapes](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/pull/49).
 
 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 ...
 
-Compute Instances are also a perfect place to illustrate [module composition principles](https://www.terraform.io/docs/language/modules/develop/composition.html) reusing the other existing official Terraform OCI Modules
+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
 
@@ -73,7 +69,8 @@ Compute Instances are also a perfect place to illustrate [module composition pri
 
 ## Contributing
 
-This project is open source. Oracle appreciates any contributions that are made by the open source community: raising issues, improving documentation, fixing bugs, or adding new features.
+This project is open source and maintained by Oracle.  
+Oracle appreciates any contributions that are made by the open source community: raising issues, improving documentation, fixing bugs, or adding new features.
 
 Learn how to [contribute](https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/blob/main/CONTRIBUTING.adoc).
 

docs/terraformoptions.adoc

@@ -24,12 +24,15 @@ No modules.
 [cols="a,a",options="header,autowidth"]
 |===
 |Name |Type
-|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_instance[oci_core_instance.this] |resource
-|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_volume[oci_core_volume.this] |resource
-|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_volume_attachment[oci_core_volume_attachment.this] |resource
-|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_instance_credentials[oci_core_instance_credentials.this] |data source
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_instance[oci_core_instance.instance] |resource
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_public_ip[oci_core_public_ip.public_ip] |resource
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_volume[oci_core_volume.volume] |resource
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/core_volume_attachment[oci_core_volume_attachment.volume_attachment] |resource
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_instance_credentials[oci_core_instance_credentials.credential] |data source
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_private_ips[oci_core_private_ips.private_ips] |data source
 |https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_shapes[oci_core_shapes.ad1] |data source
-|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_subnet[oci_core_subnet.this] |data source
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_subnet[oci_core_subnet.instance_subnet] |data source
+|https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/core_vnic_attachments[oci_core_vnic_attachments.vnic_attachment] |data source
 |https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/identity_availability_domains[oci_identity_availability_domains.ad] |data source
 |===
 
@@ -45,7 +48,7 @@ No modules.
 |no
 
 |[[input_assign_public_ip]] <<input_assign_public_ip,assign_public_ip>>
-|Whether the VNIC should be assigned a public IP address.
+|Deprecated: use `var.public_ip` instead. Whether the VNIC should be assigned a public IP address (Always EPHEMERAL).
 |`bool`
 |`false`
 |no
@@ -146,6 +149,18 @@ No modules.
 |`[]`
 |no
 
+|[[input_public_ip]] <<input_public_ip,public_ip>>
+|Whether to create a Public IP to attach to primary vnic and which lifetime. Valid values are NONE, RESERVED or EPHEMERAL.
+|`string`
+|`"NONE"`
+|no
+
+|[[input_public_ip_display_name]] <<input_public_ip_display_name,public_ip_display_name>>
+|(Updatable) A user-friendly name. Does not have to be unique, and it's changeable.
+|`string`
+|`null`
+|no
+
 |[[input_resource_platform]] <<input_resource_platform,resource_platform>>
 |Platform to create resources in.
 |`string`
@@ -219,10 +234,16 @@ No modules.
 [cols="a,a",options="header,autowidth"]
 |===
 |Name |Description
+|[[output_instance_all_attributes]] <<output_instance_all_attributes,instance_all_attributes>> |all attributes of created instance
 |[[output_instance_id]] <<output_instance_id,instance_id>> |ocid of created instances.
 |[[output_instance_password]] <<output_instance_password,instance_password>> |Passwords to login to Windows instance.
 |[[output_instance_username]] <<output_instance_username,instance_username>> |Usernames to login to Windows instance.
 |[[output_instances_summary]] <<output_instances_summary,instances_summary>> |Private and Public IPs for each instance.
 |[[output_private_ip]] <<output_private_ip,private_ip>> |Private IPs of created instances.
+|[[output_private_ips_all_attributes]] <<output_private_ips_all_attributes,private_ips_all_attributes>> |all attributes of created private ips
 |[[output_public_ip]] <<output_public_ip,public_ip>> |Public IPs of created instances.
+|[[output_public_ip_all_attributes]] <<output_public_ip_all_attributes,public_ip_all_attributes>> |all attributes of created public ip
+|[[output_vnic_attachment_all_attributes]] <<output_vnic_attachment_all_attributes,vnic_attachment_all_attributes>> |all attributes of created vnic attachments
+|[[output_volume_all_attributes]] <<output_volume_all_attributes,volume_all_attributes>> |all attributes of created volumes
+|[[output_volume_attachment_all_attributes]] <<output_volume_attachment_all_attributes,volume_attachment_all_attributes>> |all attributes of created volumes attachments
 |===

examples/instances_fixed_shape/README.md

@@ -13,7 +13,8 @@ You will need to collect the following information before you start:
 
 1. your OCI provider authentication values
 2. a compartment OCID in which the instances will be created
-3. a subnet OCID to which the instance's primary VNICs will be attached
+3. a source OCID to deploy the instance, usually an image ocid from [OCI Platform Images list]
+4. a subnet OCID to which the instance's primary VNICs will be attached
 
 For detailed instructions, see [docs/prerequisites.adoc]
 
@@ -33,3 +34,5 @@ Then apply the example using the following commands:
 
 [Terraform Variable Definition file]:https://www.terraform.io/docs/language/values/variables.html#variable-definitions-tfvars-files
 [docs/prerequisites.adoc]:https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/blob/main/docs/prerequisites.adoc
+[Provisioning Infrastructure with Terraform]:https://www.terraform.io/docs/cli/run/index.html
+[OCI Platform Images list]:https://docs.oracle.com/en-us/iaas/images/

examples/instances_fixed_shape/main.tf

@@ -1,10 +1,10 @@
 // Copyright (c) 2018, 2021 Oracle and/or its affiliates.
 
 terraform {
-  required_version = ">= 0.12" // terraform version below 0.12 is not tested/supported with this module
+  required_version = ">= 0.13" // terraform version below 0.12 is not tested/supported with this module
   required_providers {
     oci = {
-      version = ">= 3.27" // force downloading oci-provider compatible with terraform v0.12
+      version = ">= 4.0.0" // force downloading oci-provider compatible with terraform v0.12
     }
   }
 }
@@ -34,8 +34,8 @@ module "instance_nonflex" {
   # operating system parameters
   ssh_public_keys = var.ssh_public_keys
   # networking parameters
-  assign_public_ip = var.assign_public_ip
-  subnet_ocids     = var.subnet_ocids
+  public_ip    = var.public_ip # NONE, RESERVED or EPHEMERAL
+  subnet_ocids = var.subnet_ocids
   # storage parameters
   block_storage_sizes_in_gbs = var.block_storage_sizes_in_gbs
 }
@@ -65,8 +65,8 @@ module "instance_nonflex_custom" {
   # operating system parameters
   ssh_public_keys = var.ssh_public_keys
   # networking parameters
-  assign_public_ip = var.assign_public_ip
-  subnet_ocids     = var.subnet_ocids
+  public_ip    = var.public_ip # NONE, RESERVED or EPHEMERAL
+  subnet_ocids = var.subnet_ocids
   # storage parameters
   block_storage_sizes_in_gbs = [] # no block volume will be created
 }

examples/instances_fixed_shape/variables.tf

@@ -118,6 +118,12 @@ variable "assign_public_ip" {
   default     = false
 }
 
+variable "public_ip" {
+  description = "Whether to create a Public IP to attach to primary vnic and which lifetime. Valid values are NONE, RESERVED or EPHEMERAL."
+  type        = string
+  default     = "NONE"
+}
+
 variable "subnet_ocids" {
   description = "The unique identifiers (OCIDs) of the subnets in which the instance primary VNICs are created."
   type        = list(string)

examples/instances_flex_shape/README.md

@@ -13,7 +13,8 @@ You will need to collect the following information before you start:
 
 1. your OCI provider authentication values
 2. a compartment OCID in which the instances will be created
-3. a subnet OCID to which the instance's primary VNICs will be attached
+3. a source OCID to deploy the instance, usually an image ocid from [OCI Platform Images list]
+4. a subnet OCID to which the instance's primary VNICs will be attached
 
 For detailed instructions, see [docs/prerequisites.adoc]
 
@@ -33,3 +34,5 @@ Then apply the example using the following commands:
 
 [Terraform Variable Definition file]:https://www.terraform.io/docs/language/values/variables.html#variable-definitions-tfvars-files
 [docs/prerequisites.adoc]:https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/blob/main/docs/prerequisites.adoc
+[Provisioning Infrastructure with Terraform]:https://www.terraform.io/docs/cli/run/index.html
+[OCI Platform Images list]:https://docs.oracle.com/en-us/iaas/images/

examples/instances_flex_shape/main.tf

@@ -1,10 +1,10 @@
 // Copyright (c) 2018, 2021 Oracle and/or its affiliates.
 
 terraform {
-  required_version = ">= 0.12" // terraform version below 0.12 is not tested/supported with this module
+  required_version = ">= 0.13" // terraform version below 0.12 is not tested/supported with this module
   required_providers {
     oci = {
-      version = ">= 3.27" // force downloading oci-provider compatible with terraform v0.12
+      version = ">= 4.0.0" // force downloading oci-provider compatible with terraform v0.12
     }
   }
 }
@@ -37,8 +37,8 @@ module "instance_flex" {
   # operating system parameters
   ssh_public_keys = var.ssh_public_keys
   # networking parameters
-  assign_public_ip = var.assign_public_ip
-  subnet_ocids     = var.subnet_ocids
+  public_ip    = var.public_ip # NONE, RESERVED or EPHEMERAL
+  subnet_ocids = var.subnet_ocids
   # storage parameters
   block_storage_sizes_in_gbs = var.block_storage_sizes_in_gbs
 }
@@ -67,7 +67,7 @@ output "instance_flex" {
 #   # operating system parameters
 #   ssh_public_key = var.ssh_public_key
 #   # networking parameters
-#   assign_public_ip = var.assign_public_ip
+#   public_ip    = var.public_ip # NONE, RESERVED or EPHEMERAL
 #   subnet_ocids     = var.subnet_ocids
 #   # storage parameters
 #   block_storage_sizes_in_gbs = [] # no block volume will be created

examples/instances_flex_shape/variables.tf

@@ -119,10 +119,10 @@ variable "ssh_public_keys" {
 
 # networking parameters
 
-variable "assign_public_ip" {
-  description = "Whether the VNIC should be assigned a public IP address."
-  type        = bool
-  default     = false
+variable "public_ip" {
+  description = "Whether to create a Public IP to attach to primary vnic and which lifetime. Valid values are NONE, RESERVED or EPHEMERAL."
+  type        = string
+  default     = "NONE"
 }
 
 variable "subnet_ocids" {

examples/instances_reserved_public_ip/README.md

@@ -0,0 +1,39 @@
+# Creating Compute Instances using Flex shape
+
+This example illustrates how to use this module to creates compute instances with a reserved public IP.
+
+One modules will be configured:
+
+- 1 instance (1 OCPU, 1GB RAM) with a reserved public IP associated with the Primary IP of the primary VNIC.
+
+## Prerequisites
+
+You will need to collect the following information before you start:
+
+1. your OCI provider authentication values
+2. a compartment OCID in which the instances will be created
+3. a source OCID to deploy the instance, usually an image ocid from [OCI Platform Images list]
+4. a subnet OCID to which the instance's primary VNICs will be attached
+
+For detailed instructions, see [docs/prerequisites.adoc]
+
+## Using this example with Terraform cli
+
+Prepare one [Terraform Variable Definition file] named `terraform.tfvars` with the required authentication information.
+
+*TIP: You can rename and configure `terraform.tfvars.example` from this example's folder.*
+
+Then apply the example using the following commands:
+
+```shell
+> terraform init
+> terraform plan
+> terraform apply
+```
+
+See [Provisioning Infrastructure with Terraform] for more details about Terraform CLI and the available subcommands.
+
+[Terraform Variable Definition file]:https://www.terraform.io/docs/language/values/variables.html#variable-definitions-tfvars-files
+[docs/prerequisites.adoc]:https://github.com/oracle-terraform-modules/terraform-oci-compute-instance/blob/main/docs/prerequisites.adoc
+[Provisioning Infrastructure with Terraform]:https://www.terraform.io/docs/cli/run/index.html
+[OCI Platform Images list]:https://docs.oracle.com/en-us/iaas/images/

examples/instances_reserved_public_ip/main.tf

@@ -0,0 +1,49 @@
+// Copyright (c) 2018, 2021 Oracle and/or its affiliates.
+
+terraform {
+  required_version = ">= 0.13" // terraform version below 0.12 is not tested/supported with this module
+  required_providers {
+    oci = {
+      version = ">= 4.0.0" // force downloading oci-provider compatible with terraform v0.12
+    }
+  }
+}
+
+provider "oci" {
+  tenancy_ocid     = var.tenancy_ocid
+  user_ocid        = var.user_ocid
+  fingerprint      = var.fingerprint
+  private_key_path = var.private_key_path
+  region           = var.region
+}
+
+# # * This module will create 1 Flex Compute Instances, with a reserved public IP
+module "instance_reserved_ip" {
+  source = "oracle-terraform-modules/compute-instance/oci"
+  # general oci parameters
+  compartment_ocid = var.compartment_ocid
+  freeform_tags    = var.freeform_tags
+  defined_tags     = var.defined_tags
+  # compute instance parameters
+  ad_number                   = null
+  instance_count              = 1
+  instance_display_name       = "instance_reserved_ip"
+  shape                       = var.shape
+  source_ocid                 = var.source_ocid
+  source_type                 = var.source_type
+  instance_flex_memory_in_gbs = 1 # only used if shape is Flex type
+  instance_flex_ocpus         = 1 # only used if shape is Flex type
+  # operating system parameters
+  ssh_authorized_keys = var.ssh_authorized_keys
+  # networking parameters
+  public_ip    = var.public_ip # NONE, RESERVED or EPHEMERAL
+  subnet_ocids = var.subnet_ocids
+  # storage parameters
+  block_storage_sizes_in_gbs = [] # no block volume will be created
+  preserve_boot_volume       = false
+}
+
+output "instance_reserved_ip" {
+  description = "IP information of the instances provisioned by this module."
+  value       = module.instance_reserved_ip.instances_summary
+}