Merge pull request #4 from oracle-quickstart/release-0.1.3

Release 0.1.3

README.md

@@ -5,6 +5,7 @@
 This repository contains Terraform OCI (Oracle Cloud Infrastructure) modules for security services that help customers align their OCI implementations with the CIS (Center for Internet Security) OCI Foundations Benchmark recommendations.
 
 The following modules are available:
+- [Bastion Service](./bastion/)
 - [Cloud Guard](./cloud-guard/)
 - [Security Zones](./security-zones/)
 - [Vaults](./vaults/) (a.k.a KMS)

RELEASE-NOTES.md

@@ -1,4 +1,13 @@
-# # January 08, 2024 Release Notes - 0.1.2
+# March 20, 2024 Release Notes - 0.1.3
+
+## New
+1. [Bastion module](./bastion/), with support for managed SSH and port forwarding sessions.
+
+## Updates
+1. Examples code in all modules updated with remote source references.
+2. Examples documentation in all modules updated with remote link references.
+
+# January 08, 2024 Release Notes - 0.1.2
 
 ## Updates
 ### All Modules

bastion/README.md

@@ -0,0 +1,151 @@
+# Oracle Cloud Infrastructure (OCI) Terraform Bastion Module
+
+![Landing Zone logo](../landing_zone_300.png)
+
+This module manages bastions and bastion sessions in Oracle Cloud Infrastructure (OCI). OCI Bastion service provides restricted and time-limited access to target resources that do not have public endpoints. Bastions let authorized users connect from specific IP addresses to target resources using Secure Shell (SSH) sessions. When connected, users can interact with the target resource by using any software or protocol supported by SSH.
+
+The module outputs the SSH command to run for any managed sessions.
+
+Check [module specification](./SPEC.md) for a full description of module requirements, supported variables, managed resources and outputs.
+
+Check the [examples](./examples/) folder for actual module usage.
+
+- [Requirements](#requirements)
+- [Module Functioning](#functioning)
+  - [Bastions](#bastions)
+  - [Sessions](#sessions)
+  - [External Dependencies](#ext-dep)
+- [Related Documentation](#related)
+- [Known Issues](#issues)
+
+## <a name="requirements">Requirements</a>
+### IAM Permissions
+
+This module requires the following IAM permissions:
+```
+Allow group <GROUP-NAME> to manage bastion-family in compartment <BASTION-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to inspect work-requests in compartment <BASTION-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to read virtual-network-family in compartment <NETWORK-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to use subnets in compartment <NETWORK-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to use vnics in compartment <NETWORK-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to manage bastion-session in compartment <TARGET-INSTANCE-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to read instance-family in compartment <TARGET-INSTANCE-COMPARTMENT-NAME>
+Allow group <GROUP-NAME> to read instance-agent-plugins in compartment <TARGET-INSTANCE-COMPARTMENT-NAME>
+```
+
+**Note:** the permissions account for a topology with multiple compartments, with distinct compartments for the bastion (\<BASTION-COMPARTMENT-NAME\>), the network (\<NETWORK-COMPARTMENT-NAME\>) and the bastion target instance (\<TARGET-INSTANCE-COMPARTMENT-NAME\>). In a simpler topology, those three compartments can be the same compartment.
+
+For more information about Bastion policies [click here](https://docs.oracle.com/en-us/iaas/Content/Bastion/Tasks/managingbastions.htm).
+
+### Terraform Version >= 1.3.0
+This module relies on [Terraform Optional Object Type Attributes feature](https://developer.hashicorp.com/terraform/language/expressions/type-constraints#optional-object-type-attributes), which has been promoted and no longer experimental in versions greater than or equal to 1.3.0. The feature shortens the amount of input values in complex object types, by having Terraform automatically inserting a default value for any missing optional attributes.
+
+## <a name="functioning">Module Functioning</a>
+The module defines two top level attributes used to manage bastions and sessions: 
+- **bastions_configuration**: for managing bastions.
+- **sessions_configuration**: for managing bastion sessions.
+
+### <a name="bastions">Bastions</a>
+Bastions are managed using the **bastions_configuration** object. It contains a set of attributes starting with the prefix *default_* and one attribute named *bastions*. The *default_* attribute values are applied to all bastions within **bastions**, unless overridden at the bastion level.
+
+The *default_* attributes are the following:
+- **default_compartment_id**: Default compartment for all bastions. It can be overridden by *compartment_id* attribute in each bastion. This attribute is overloaded. It can be assigned either a literal OCID or a reference (a key) to an OCID in *compartments_dependency* variable. See [External Dependencies](#ext-dep) for details.
+- **default_defined_tags**: (Optional) Default defined tags for all bastions. It can be overridden by *defined_tags* attribute in each bastion.
+- **default_freeform_tags**: (Optional) Default freeform tags for all bastions. It can be overridden by *freeform_tags* attribute in each bastion.
+- **default_subnet_id**: (Optional) Default subnet for all bastions. It can be overridden by *subnet_id* attribute in each bastion. This attribute is overloaded. It can be assigned either a literal OCID or a reference (a key) to an OCID in *network_dependency* variable. See [External Dependencies](#ext-dep) for details.
+- **default_cidr_block_allow_list**: (Optional) Default CIDR blocks allowed to connect to bastions. It an be overridden by *cidr_block_allow_list* in each bastion.
+- **enable_cidr_check**: (Optional) Whether provided CIDR blocks should be checked for "0.0.0.0\0". Default is true. When true, "0.0.0.0\0" is not allowed in *default_cidr_block_allow_list* and *cidr_block_allow_list*.
+
+The bastions themselves are defined within the **bastions** attribute. In Terraform terms, it is a map of objects, where each object is referred by an identifying key. The supported attributes are listed below:
+- **bastion_type**: (Optional) The bastion type. The only supported value is "STANDARD", which is the default value.
+- **compartment_id**: (Optional) The bastion compartment. *default_compartment_id* is used if undefined. This attribute is overloaded. It can be assigned either a literal OCID or a reference (a key) to an OCID in *compartments_dependency* variable. See [External Dependencies](#ext-dep) for details.
+- **subnet_id**: (Optional) The subnet ID where the bastion is created. This attribute is overloaded. It can be assigned either a literal OCID or a reference (a key) to an OCID in *network_dependency* variable. See [External Dependencies](#ext-dep) for details.
+- **defined_tags**: (Optional) Bastion defined_tags. *default_defined_tags* is used if undefined.
+- **freeform_tags**: (Optional) Bastion freeform_tags. *default_freeform_tags* is used if undefined.
+- **cidr_block_allow_list**: (Optional) The list of CIDR blocks allowed to connect to bastion.
+- **enable_dns_proxy**: (Optional) Whether bastion support is enabled for FQDN and SOCKS5 proxy.
+- **max_session_ttl_in_seconds**: (Optional) The maximum allowed time to live for bastion sessions.
+- **name**: the bastion display name.
+
+### <a name="sessions">Sessions</a>
+Sessions are managed using the **sessions_configuration** object. It contains a set of attributes starting with the prefix *default_* and an attribute named *sessions* .The *default_* attribute values are applied to all sessions, unless overridden at the session object level.
+
+The defined **default_** attributes are the following:
+- **default_ssh_public_key**: (Optional) Default SSH public key path for all sessions. It can be overridden by the *ssh_public_key* attribute in each session.
+- **default_session_type**: (Optional) Default session type for all sessions. Supported values are "MANAGED_SSH" and "PORT_FORWARDING". It can be overridden by *session_type* attribute in each session.
+
+Sessions are defined using the  **sessions** attribute. In Terraform terms, it is a map of objects, where each object is referred by an identifying key. The following attributes are supported:
+- **bastion_id**: The bastion where the session is created. This attribute is overloaded. It can be assigned either a literal OCID or a reference (a key) to an OCID in the *bastions* map of objects.
+- **ssh_public_key**: (Optional) The SSH public key path to connect to target. *default_ssh_public_key* is used if undefined.
+- **session_type**: (Optional) The session type. Supported values are "MANAGED_SSH" and "PORT_FORWARDING". *default_session_type* if undefined.
+- **target_resource**: Either the FQDN, OCID or IP of the target resource.
+- **target_user**: (Optional) The SSH user name in the target resource. Required for "MANAGED_SSH" session type. 
+- **target_port**: The SSH port number.
+- **session_ttl_in_seconds**: (Optional) The session time to live.
+- **session_name**: The session display name.
+
+### <a name="ext-dep">External Dependencies</a>
+An optional feature, external dependencies are resources managed elsewhere that resources managed by this module may depend on. The following dependencies are supported:
+- **compartments_dependency**: A map of objects containing the externally managed compartments this module may depend on. All map objects must have the same type and must contain at least an *id* attribute with the compartment OCID.
+
+Example:
+```
+{
+	"APP-CMP": {
+		"id": "ocid1.compartment.oc1..aaaaaaaa...7xq"
+	}
+}
+```
+- **network_dependency**: A map of objects containing the externally managed network resources (including subnets and network security groups) this module may depend on. All map objects must have the same type and should contain the following attributes:
+  - An *id* attribute with the subnet OCID.
+  - An *id* attribute with the network security group OCID.
+
+Example:
+```
+{
+  "subnets" : {
+    "APP-SUBNET" : {
+      "id" : "ocid1.subnet.oc1.iad.aaaaaaaax...e7a"
+    }
+  },
+  "network_security_groups" : { 
+    "APP-NSG" : {
+      "id" : "ocid1.networksecuritygroup.oc1.iad.aaaaaaaa...xlq"
+    }
+  } 
+}
+```
+
+- **instances_dependency**: A map of objects containing the externally managed compute resources this module may depend on. All map objects must have the same type and should contain the following attributes:
+  - An *id* attribute with the instance OCID.
+
+Example:
+```
+{
+  "INSTANCE-1" : {
+    "id" : "ocid1.instance.oc1.iad.aaaaaaaax...e7a"
+  }, 
+} 
+```
+
+- **endpoints_dependency**: A map of objects containing the externally managed endpoint resources this module may depend on. All map objects must have the same type and should contain the following attributes:
+  - A *private_endpoint* attribute with endpoint IP.
+
+Example:
+```
+{
+  "OKE1" : {
+    "endpoints" : {
+        "private_endpoint" : "10.0.1.23"
+    }
+  }, 
+} 
+```
+## <a name="related">Related Documentation</a>
+- [Bastions](https://docs.oracle.com/en-us/iaas/Content/Bastion/Concepts/bastionoverview.htm)
+- [Bastions in Terraform OCI Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/bastion_bastion)
+- [Sessions](https://docs.oracle.com/en-us/iaas/Content/Bastion/Tasks/managingsessions.htm)
+- [Bastion Sessions in Terraform OCI Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/bastion_session)
+
+## <a name="issues">Known Issues</a>
+None

bastion/SPEC.MD

@@ -0,0 +1,40 @@
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_oci"></a> [oci](#provider\_oci) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [oci_bastion_bastion.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/bastion_bastion) | resource |
+| [oci_bastion_session.these](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/bastion_session) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_bastions_configuration"></a> [bastions\_configuration](#input\_bastions\_configuration) | Bastion configuration attributes. | <pre>object({<br>    default_compartment_id        = optional(string)       # the default compartment where all resources are defined. It's overriden by the compartment_ocid attribute within each object.<br>    default_defined_tags          = optional(map(string))  # the default defined tags. It's overriden by the defined_tags attribute within each object.<br>    default_freeform_tags         = optional(map(string))  # the default freeform tags. It's overriden by the freeform_tags attribute within each object.<br>    default_subnet_id             = optional(string)       # the default subnet_id. It`s overriden by the subnet_id attribute in each object.<br>    default_cidr_block_allow_list = optional(list(string)) # the default cidr block allow list. It`s overriden by the cidr_block_allow_list attribute in each object.<br>    enable_cidr_check             = optional(bool,true)    # whether provided CIDR blocks should be checked for "0.0.0.0\0".<br>    bastions = map(object({ <br>      bastion_type               = optional(string,"standard") # type of bastion. Allowed value is "STANDARD".<br>      compartment_id             = optional(string)            # the compartment where the bastion is created. default_compartment_ocid is used if this is not defined.<br>      subnet_id                  = optional(string)            # the subnet id where the bastion will be created. default_subnet_id is used if this is not defined.<br>      defined_tags               = optional(map(string))       # bastions defined_tags. default_defined_tags is used if this is not defined.<br>      freeform_tags              = optional(map(string))       # bastions freeform_tags. default_freeform_tags is used if this is not defined.<br>      cidr_block_allow_list      = optional(list(string))      # list of cidr blocks that will be able to connect to bastion. default_cidr_block_allow_list is used if this is not defined.<br>      enable_dns_proxy           = optional(bool,true)         # bool to enable dns_proxy on the bastion.<br>      max_session_ttl_in_seconds = optional(number)            # maximum allowd time to live for a session on the bastion.<br>      name                       = string                      # bastion name<br>    }))<br>  })</pre> | `null` | no |
+| <a name="input_compartments_dependency"></a> [compartments\_dependency](#input\_compartments\_dependency) | A map of objects containing the externally managed compartments this module may depend on. All map objects must have the same type and must contain at least an 'id' attribute (representing the compartment OCID) of string type. | `map(any)` | `null` | no |
+| <a name="input_enable_output"></a> [enable\_output](#input\_enable\_output) | Whether Terraform should enable the module output. | `bool` | `true` | no |
+| <a name="input_endpoints_dependency"></a> [endpoints\_dependency](#input\_endpoints\_dependency) | A map of objects containing the externally managed endpoints this module may depend on. | `map(any)` | `null` | no |
+| <a name="input_instances_dependency"></a> [instances\_dependency](#input\_instances\_dependency) | A map of objects containing the externally managed Compute instances this module may depend on. All map objects must have the same type and must contain at least an 'id' attribute (representing the instance OCID) of string type. | `map(any)` | `null` | no |
+| <a name="input_module_name"></a> [module\_name](#input\_module\_name) | The module name. | `string` | `"bastion"` | no |
+| <a name="input_network_dependency"></a> [network\_dependency](#input\_network\_dependency) | A map of objects containing the externally managed network resources this module may depend on. All map objects must have the same type and must contain at least an 'id' attribute (representing the network resource OCID) of string type. | `map(any)` | `null` | no |
+| <a name="input_sessions_configuration"></a> [sessions\_configuration](#input\_sessions\_configuration) | Sessions configuration attributes. | <pre>object({<br>    default_ssh_public_key   = optional(string)        # the default ssh_public_key path. It's overriden by the ssh_public_key attribute within each object.<br>    default_session_type     = optional(string)        # the default session_type. It's overriden by the session_type attribute within each object.<br>    sessions = map(object({ <br>      bastion_id             = string                  # the ocid or the key of Bastion where the session will be created.<br>      ssh_public_key         = optional(string)        # the ssh_public_key path used by the session to connect to target. The default_ssh_public_key is used if this is not defined.<br>      session_type           = optional(string)        # session type of the session. Supported values are MANAGED_SSH and PORT_FORWARDING. The default_session_type is used if this is not defined.<br>      target_resource        = string                  # Either the FQDN, OCID or IP of the target resource to connect the session to.<br>      target_user            = optional(string)        # User of the target that will be used by session. It is required only with MANAGED_SSH. <br>      target_port            = number                  # Port number that will be used by the session.<br>      session_ttl_in_seconds = optional(number,10800)  # Session time to live<br>      session_name           = string                  # Session name<br>    }))<br>  })</pre> | `null` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_bastions"></a> [bastions](#output\_bastions) | The bastions service details. |
+| <a name="output_sessions"></a> [sessions](#output\_sessions) | The bastion sessions connection string. |