fix(public_ssh_keys): support single and multiple keys, as string or …

…file

This change simplify how ssh_authorized_keys is handled and support more scenarios.
The module input variable now expect a string. It gives more flexibility to the module user
to construct the string as needed: heredoc, file function ...

Fix oracle-terraform-modules#70

.github/ISSUE_TEMPLATE/bug_report.md

@@ -28,7 +28,7 @@ If you are running into one of these scenarios, we recommend opening an issue in
 
 ### Terraform Version and Provider Version
 
-<!--- Please run `terraform -v` to show the Terraform core version and provider version(s). 
+<!--- Please run `terraform -v` to show the Terraform core version and provider version(s).
 If you are using a local copy of the Terraform Oracle Cloud Infrastructure Provider, run the plugin directly to get the version: `<path-to-plugin>/terraform-provider-oci`
 If you are not running the latest version of Terraform or the provider, please upgrade because your issue may have already been fixed. [Terraform documentation on provider versioning](https://www.terraform.io/docs/configuration/providers.html#provider-versions). --->
 
@@ -43,8 +43,8 @@ If you are not running the latest version of Terraform or the provider, please u
 
 ```hcl
 # Copy-paste your Terraform configurations here - for large Terraform configs,
-# please use a service like Dropbox and share a link to the ZIP file. 
-# Please remove any sensitive information from configuration files before sharing them. 
+# please use a service like Dropbox and share a link to the ZIP file.
+# Please remove any sensitive information from configuration files before sharing them.
 ```
 
 ### Debug Output
@@ -59,8 +59,8 @@ Github Gist: https://gist.github.com/
 
 ### Panic Output
 
-<!--- 
-If Terraform produced a panic, please provide a link to a GitHub Gist containing the output of the `crash.log`. 
+<!---
+If Terraform produced a panic, please provide a link to a GitHub Gist containing the output of the `crash.log`.
 
 Github Gist: https://gist.github.com/
 --->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -28,7 +28,7 @@ labels: enhancement
 <!--- Information about code formatting: https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code --->
 
 ```hcl
-# Copy-paste any Terraform configurations for how the requested feature may be used. 
+# Copy-paste any Terraform configurations for how the requested feature may be used.
 ```
 
 ### References

CHANGELOG.adoc

@@ -18,13 +18,17 @@ Given a version number MAJOR.MINOR.PATCH:
 
 === Deprecated
 
-* `var.ssh_authorized_keys` is deprecated. Use `var.ssh_public_key` add a single public key or `var.ssh_public_key_path` for a file containing mutiple public keys.
+* `var.ssh_authorized_keys` is deprecated. Use `var.ssh_public_keys`.
 
 === 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)
+* Add support to provide the `ssh_authorized_keys` argument as a string or as a file (Fix #67 #70)
+
+=== Documentation
+
+* Add add instructions on how to provide one or more public ssh keys using string, variable or file.
 
 == 2.1.0 - 2021-03-02
 

README.md

@@ -71,25 +71,6 @@ Compute Instances are also a perfect place to illustrate [module composition pri
 
 - 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).
 
-## Windows remote scripts execution
-
-Terraform supports using Windows Remote Management (WinRM) for connecting to Windows instances. Ensure that your Windows image has WinRM properly configured to allow remote access. Following is a sample WinRM configuration:
-
-```HCL
-winrm quickconfig -q
-winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="300"}’'
-winrm set winrm/config ‘@{MaxTimeoutms=”1800000″}’
-winrm set winrm/config/service '@{AllowUnencrypted="true"}'
-winrm set winrm/config/service/auth '@{Basic="true"}'
-
-netsh advfirewall firewall add rule name="WinRM 5985" protocol=TCP dir=in localport=5985 action=allow
-netsh advfirewall firewall add rule name="WinRM 5986" protocol=TCP dir=in localport=5986 action=allow
-
-net stop winrm
-sc.exe config winrm start=auto
-net start winrm
-```
-
 ## 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.

docs/instance_ssh_keys.adoc

@@ -0,0 +1,94 @@
+= Instance SSH Keys
+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
+
+This document explains how to provide one or more Instance public SSH keys for Linux instances using this module. See {uri-oci-security-credentials}[Instance SSH key] on OCI documentation for more details.
+
+Linux public keys are controlled by the `ssh_authorized_keys` argument in the `metadata` block of the {uri-oci-core-instance}[oci_core_instance] resource at the provider level.
+
+The corresponding feature on this module uses the module Input Variable `var.ssh_public_keys`.
+
+== Providing one public key
+
+Providing one public ssh key is as simple as directly pasting it as a string in your module block.
+
+[source,hcl]
+----
+module "instance" {
+  source = "oracle-terraform-modules/compute-instance/oci"
+  ...
+  ssh_public_keys = "<your public ssh key>"
+}
+----
+
+Alternatively, you can also declare a variable in your configuration and feed the module with it.
+
+[source,hcl]
+----
+module "instance" {
+  source = "oracle-terraform-modules/compute-instance/oci"
+  ...
+  ssh_public_keys = var.my_public_ssh_key
+}
+
+variable "my_public_ssh_key" {
+  type    = string
+  default = "<ssh public key>" 
+}
+----
+
+== Providing multiple public keys
+
+To inject multiple public SSH keys when launching an instance, you must provide one public key per line. Terraform allows multi-line strings using {uri-tf-heredoc}[Heredoc strings] and this is maybe the most straight-forward solution.
+
+[source,hcl]
+----
+module "instance" {
+  source = "oracle-terraform-modules/compute-instance/oci"
+  ...
+  ssh_public_keys = var.my_public_ssh_key
+}
+
+variable "my_public_ssh_key" {
+  type    = string
+  default = <<EOT
+  <ssh public key 1>
+  <ssh public key 2>
+  ...
+  <ssh public key n>
+  EOT
+}
+----
+
+Alternatively, you can also source your public ssh keys from a file, using the {uri-tf-file-function}[Terraform File function].
+
+[source,hcl]
+----
+module "instance" {
+  source = "oracle-terraform-modules/compute-instance/oci"
+  ...
+  ssh_public_keys = file("/path/to/your/file")
+}
+----
+
+== Examples
+
+For example configuration using this feature, see link:../examples/instances_flex_shape/README.md[examples/instances_flex_shape]

docs/terraformoptions.adoc

@@ -12,7 +12,7 @@
 [cols="a,a",options="header,autowidth"]
 |===
 |Name |Version
-|[[provider_oci]] <<provider_oci,oci>> |>= 3.27
+|[[provider_oci]] <<provider_oci,oci>> |4.17.0
 |===
 
 == Modules
@@ -177,19 +177,13 @@ No modules.
 |no
 
 |[[input_ssh_authorized_keys]] <<input_ssh_authorized_keys,ssh_authorized_keys>>
-|DEPRECATED: use ssh_public_key or ssh_public_key_path instead. Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance.
+|DEPRECATED: use ssh_public_keys instead. Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance.
 |`string`
 |`null`
 |no
 
-|[[input_ssh_public_key]] <<input_ssh_public_key,ssh_public_key>>
-|The content of the ssh public key used to access the compute instance. Set this, or ssh_public_key_path to add multiple keys at once.
-|`string`
-|`null`
-|no
-
-|[[input_ssh_public_key_path]] <<input_ssh_public_key_path,ssh_public_key_path>>
-|Path to file containing one or more ssh public keys used to access the compute instance. One key per line. Set this or the ssh_public_key.
+|[[input_ssh_public_keys]] <<input_ssh_public_keys,ssh_public_keys>>
+|Public SSH keys to be included in the ~/.ssh/authorized_keys file for the default user on the instance. To provide multiple keys, see docs/instance_ssh_keys.adoc.
 |`string`
 |`null`
 |no

examples/instances_fixed_shape/main.tf

@@ -32,7 +32,7 @@ module "instance_nonflex" {
   source_ocid           = var.source_ocid
   source_type           = var.source_type
   # operating system parameters
-  ssh_authorized_keys = var.ssh_authorized_keys
+  ssh_public_keys = var.ssh_public_keys
   # networking parameters
   assign_public_ip = var.assign_public_ip
   subnet_ocids     = var.subnet_ocids
@@ -63,7 +63,7 @@ module "instance_nonflex_custom" {
   instance_flex_memory_in_gbs = 8 # 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
+  ssh_public_keys = var.ssh_public_keys
   # networking parameters
   assign_public_ip = var.assign_public_ip
   subnet_ocids     = var.subnet_ocids

examples/instances_fixed_shape/terraform.tfvars.example

@@ -1,4 +1,4 @@
-# Copyright (c) 2019, 2020 Oracle Corporation and/or affiliates.  All rights reserved.
+# Copyright (c) 2019, 2021 Oracle Corporation and/or affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
 
 /*----------------------------------------------------------------------------
@@ -27,7 +27,11 @@ source_ocid  = "<The OCID of an image or a boot volume>"
 
 # operating system parameters
 
-ssh_authorized_keys = "<path to the instance's public key>"
+ssh_public_keys = <<EOT
+<ssh_public_key_1>
+<ssh_public_key_2>
+<ssh_public_key_3>
+EOT
 
 # networking parameters
 

examples/instances_fixed_shape/variables.tf

@@ -104,9 +104,10 @@ variable "source_type" {
 
 # operating system parameters
 
-variable "ssh_authorized_keys" {
-  description = "Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance."
+variable "ssh_public_keys" {
+  description = "Public SSH keys to be included in the ~/.ssh/authorized_keys file for the default user on the instance. To provide multiple keys, see docs/instance_ssh_keys.adoc."
   type        = string
+  default     = null
 }
 
 # networking parameters
@@ -129,12 +130,3 @@ variable "block_storage_sizes_in_gbs" {
   type        = list(string)
   default     = [50]
 }
-
-
-
-
-
-
-
-
-

examples/instances_flex_shape/main.tf

@@ -26,14 +26,16 @@ module "instance_flex" {
   freeform_tags    = var.freeform_tags
   defined_tags     = var.defined_tags
   # compute instance parameters
-  ad_number             = var.instance_ad_number
-  instance_count        = var.instance_count
-  instance_display_name = var.instance_display_name
-  shape                 = var.shape
-  source_ocid           = var.source_ocid
-  source_type           = var.source_type
+  ad_number                   = var.instance_ad_number
+  instance_count              = var.instance_count
+  instance_display_name       = var.instance_display_name
+  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_public_key = var.ssh_public_key
+  ssh_public_keys = var.ssh_public_keys
   # networking parameters
   assign_public_ip = var.assign_public_ip
   subnet_ocids     = var.subnet_ocids

examples/instances_flex_shape/terraform.tfvars.example

@@ -1,4 +1,4 @@
-# Copyright (c) 2019, 2020 Oracle Corporation and/or affiliates.  All rights reserved.
+# Copyright (c) 2019, 2021 Oracle Corporation and/or affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
 
 /*----------------------------------------------------------------------------
@@ -27,7 +27,11 @@ source_ocid  = "<The OCID of an image or a boot volume>"
 
 # operating system parameters
 
-ssh_authorized_keys = "<path to the instance's public key>"
+ssh_public_keys = <<EOT
+<ssh_public_key_1>
+<ssh_public_key_2>
+<ssh_public_key_3>
+EOT
 
 # networking parameters
 

examples/instances_flex_shape/variables.tf

@@ -105,18 +105,14 @@ variable "source_type" {
 # operating system parameters
 
 variable "ssh_authorized_keys" {
-  description = "Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance."
+  #! Deprecation notice: Please use `ssh_public_keys` instead
+  description = "DEPRECATED: use ssh_public_keys instead. Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance."
   type        = string
   default     = null
 }
 
-variable "ssh_public_key" {
-  description = "The content of the ssh public key used to access the compute instance. Set this, or ssh_public_key_path to add multiple keys at once."
-  type        = string
-  default     = null
-}
-variable "ssh_public_key_path" {
-  description = "Path to file containing one or more ssh public keys used to access the compute instance. One key per line. Set this or the ssh_public_key."
+variable "ssh_public_keys" {
+  description = "Public SSH keys to be included in the ~/.ssh/authorized_keys file for the default user on the instance. To provide multiple keys, see docs/instance_ssh_keys.adoc."
   type        = string
   default     = null
 }

main.tf

@@ -90,10 +90,8 @@ resource "oci_core_instance" "this" {
   }
 
   metadata = {
-    ssh_authorized_keys = (var.ssh_public_key != "" ? var.ssh_public_key :
-      (var.ssh_public_key_path != "" ? file(var.ssh_public_key_path) :
-    (var.ssh_authorized_keys != "" ? file(var.ssh_authorized_keys) : "")))
-    user_data = var.user_data
+    ssh_authorized_keys = var.ssh_public_keys != null ? var.ssh_public_keys : file(var.ssh_authorized_keys)
+    user_data           = var.user_data
   }
 
   source_details {

variables.tf

@@ -105,19 +105,14 @@ variable "resource_platform" {
 }
 
 variable "ssh_authorized_keys" {
-  #! Deprecation notice: Please use `ssh_public_key` or `ssh_public_key_path` instead
-  description = "DEPRECATED: use ssh_public_key or ssh_public_key_path instead. Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance."
+  #! Deprecation notice: Please use `ssh_public_keys` instead
+  description = "DEPRECATED: use ssh_public_keys instead. Public SSH keys path to be included in the ~/.ssh/authorized_keys file for the default user on the instance."
   type        = string
   default     = null
 }
 
-variable "ssh_public_key" {
-  description = "The content of the ssh public key used to access the compute instance. Set this, or ssh_public_key_path to add multiple keys at once."
-  type        = string
-  default     = null
-}
-variable "ssh_public_key_path" {
-  description = "Path to file containing one or more ssh public keys used to access the compute instance. One key per line. Set this or the ssh_public_key."
+variable "ssh_public_keys" {
+  description = "Public SSH keys to be included in the ~/.ssh/authorized_keys file for the default user on the instance. To provide multiple keys, see docs/instance_ssh_keys.adoc."
   type        = string
   default     = null
 }