/terraform-oci-tdf-network

(OCI) Oracle Cloud Infrastructure module to provision Virtual Cloud Network (VCN) and other optional services

Primary LanguageHCLUniversal Permissive License v1.0UPL-1.0

Oracle Cloud Infrastructure Network Module for Terraform

Introduction

This module provides the initial bootstrapping needed to provision a new Virtual Cloud Network (VCN) and other optional services in Oracle Cloud Infrastructure (OCI).

Solution

A VCN is the core foundation of a network in OCI. This module provides the ability to create the following resources:

Resource Created by Default?
VCN No (optional)
Internet Gateway No (optional)
NAT Gateway No (optional)
Service Gateway No (optional)
Dynamic Routing Gateway No (optional)
Bastion No (optional)

By using this module, a basic cloud network will be created, including the basic foundational communication paths (for most use-cases, though not all). For situations where VPN-connect, FastConnect or VCN Peering is needed, these services will need to be built on top of the VCN deployed by this module.

Getting Started

Several fully-functional examples has been provided in the examples directory. Refer to the README.md in each example directory for directions specific to each example.

To get started quickly, for the minimum deployment, you can use the following example:

module "oci_network" {
  source           = "../../"
  #source          = "oracle-terraform-modules/default-vcn/oci"
  
  default_compartment_id = "${var.compartment_id}"
}

This will deploy a VCN using the module defaults. Review this README for a detailed description of these parameters.

Accessing the Solution

This core service module is typically used at deployment, with no further access required; you might need to access a bastion, if it's been requested to be created as a part of the solution.

You may continue to manage the deployed environment using Terraform (best), the OCI CLI, the OCI console (UI), directly via the API, etc.

Resource-specific inputs

VCN

Attribute Data Type Required Default Value Valid Values Description
default_compartment_id string yes none string of the compartment OCID This is the default OCID that will be used when creating objects (unless overridden for any specific object). This needs to be the OCID of a pre-existing compartment (it will not create the compartment).
vcn_options map no see below see below The optional parameters that can be used to customize the VCN.
existing_vcn_id string no null The OCID of any pre-existing VCN If a new VCN is not to be created, then the OCID of an existing VCN should be provided here. All created resources will be a part of this pre-existing VCN (if a VCN is not provided).

Note that as the VCN is created, the default resources (Route Table, Security List and DHCP Options) are left as-is (not modified in any way). Often these resources are not used. See the documentation around Default Resources, Default Components that Come With Your VCN and Default Security Lists for more information.

vcn_options

The vcn_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). It has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
display_name string "vcn" Any name acceptable to the OCI API. Used to define a specific name for your VCN.
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
cidr string "10.0.0.0/16" IPv4 CIDR Specify the IPv4 CIDR to be used for the VCN.
enable_dns bool true true/false Whether or not DNS should be enabled on the VCN.
dns_label string "vcn" Valid DNS name. Specify the DNS label to be used for the VCN. If this value is null, DNS will be disabled for the VCN.

Example

The following example creates VCN with a CIDR of 10.0.0.0/24, display name of Module test, DNS label of testvcn and use the default compartment OCID (not shown in the above example).

module "oci_network" {
  ... /snip - shortened for brevity...

  vcn_options = {
    display_name      = "Module test"
    cidr              = "10.0.0.0/24"
    enable_dns        = true
    dns_label         = "testvcn"
    compartment_id    = null
    defined_tags      = null
    freeform_tags     = null
  }
}

Internet Gateway (IGW)

Attribute Data Type Required Default Value Valid Values Description
create_igw bool no false true/false Whether or not a IGW should be created in the VCN.
igw_options map no see below see below The optional parameters that can be used to customize the IGW.

igw_options

The igw_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). It has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
display_name string "igw" Any name acceptable to the OCI API. Used to define a specific name for your IGW.
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
enabled bool true true/false Whether or not the IGW should be enabled.

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  igw_options = {
    display_name     = "my_igw"
    compartment_id   = null
    defined_tags     = null
    freeform_tags    = null
    enabled          = false
  }
}

The above example will create a IGW (enabled) in the VCN with a display name of my_igw and use the default compartment OCID (not shown in the above example).

NAT Gateway (NATGW)

Attribute Data Type Required Default Value Valid Values Description
create_natgw bool no false true/false Whether or not a NATGW should be created in the VCN.
natgw_options map no see below see below The optional parameters that can be used to customize the NATGW.

natgw_options

The natgw_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). It has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
display_name string "natgw" Any name acceptable to the OCI API. Used to define a specific name for your IGW.
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
block_traffic bool false true/false Whether or not the NATGW should block traffic.

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  natgw_options = {
    display_name     = "my_natgw"
    compartment_id   = null
    defined_tags     = null
    freeform_tags    = null
    block_traffic    = false
  }
}

The above example will create a NATGW in the VCN with a display name of my_natgw, it will not block traffic and will use the default compartment OCID (not shown in the above example).

Service Gateway (SVCGW)

Attribute Data Type Required Default Value Valid Values Description
create_svcgw bool no false true/false Whether or not a SVCGW should be created in the VCN.
svcgw_options map no see below see below The optional parameters that can be used to customize the SVCGW.

svcgw_options

The svcgw_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). It has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
display_name string "svcgw" Any name acceptable to the OCI API. Used to define a specific name for your SVCGW.
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
services list(string) null The OCID(s) of any valid OCI service gateway service(s). Provide the service that should be permitted by the Service Gateway. Use the svcgw_services module output for a list of services in the region (see below for an example of this).

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  svcgw_options = {
    display_name      = "my_svcgw"
    compartment_id    = null
    defined_tags      = null
    freeform_tags     = null
    services          = [
      module.oci_network.svcgw_services.0.id
    ]
  }
}

The above example will create a SVCGW in the VCN with a display name of my_svcgw, use the default compartment OCID (not shown in the above example) and will use the first service in the list of services available in the region.

Dynamic Routing Gateway (DRG)

Attribute Data Type Required Default Value Valid Values Description
create_drg bool no false true/false Whether or not a DRG should be created in the VCN.
drg_options map no see below see below The optional parameters that can be used to customize the DRG.

drg_options

The drg_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). It has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
display_name string "drg" Any name acceptable to the OCI API. Used to define a specific name for your DRG.
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
route_table_id string null The OCID of any valid, pre-existing OCI Route Table. This is optional, but in cases where a Route Table association is desired (with the DRG), it's the place to establish this association.

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  drg_options = {
    display_name     = "my_drg"
    compartment_id   = null
    defined_tags     = null
    freeform_tags    = null
    route_table_id   = null
  }
}

The above example will create a SVCGW in the VCN with a display name of my_drg, use the default compartment OCID (not shown in the above example) and will not associate any Route Table with the DRG.

route_tables

The route_tables attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). The key indicates the display name for the route table, while the value is a map that defines the attributes. The value is a map that has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
defined_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Defined Tags should be set on this resource, do so with this attribute.
freeform_tags map(string) {} Any map of tag names and values that is acceptable to the OCI API. If any Freeform Tags should be set on this resource, do so with this attribute.
route_rules list(object) - see below {} See below This is optional, but is the place where route rules are configured.

route_rules

Key Data Type Default Value Valid Values Description
next_hop_id string none OCID of a next hop resource This is where the next-hop is specified.
dst_type string none CIDR_BLOCK, SERVICE_CIDR_BLOCK Specify what kind of destination is being given in the dst attribute.
dst string none A valid OCI destination (CIDR or Service CIDR). Specify the destination (remote network) that is to be used for this route rule.

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  route_tables = {
    rt1 = {
      display_name     = "my_drg"
      compartment_id   = null
      defined_tags     = null
      freeform_tags    = null
      route_rules      = [
        {
          dst          = "0.0.0.0/0"
          dst_type     = "CIDR_BLOCK"
          next_hop_id  = local.next_hop_ids["igw"]
        }
      ]
    }
  }
}

The above example will create a Route Table in the VCN with a display name of rt1 using the default compartment OCID (not shown in the above example), containing one route rule (pointing a default route to the Internet Gateway).

dhcp_options

The dhcp_options attribute is an optional map attribute. Note that if this attribute is used, all keys/values must be specified (Terraform does not allow for default or optional map keys/values). The key indicates the display name for the route table, while the value is a map that defines the attributes. The value is a map that has the following defined keys (and default values):

Key Data Type Default Value Valid Values Description
compartment_id string null Compartment OCID Pre-existing compartment OCID (if default compartment is not to be used). If this value is null, the default compartment OCID will be used.
server_type string "VcnLocalPlusInternet" VcnLocalPlusInternet, CustomDnsServer One of the values permitted by the OCI API.
search_domain_name string "${oci_core_vcn.this.dns_label}.oraclevcn.com" if local.vcn_with_dns is set, null otherwise Provide a valid DNS name to be used. This will be given as the domain to be searched.
forwarder_1_ip string null Any valid IP address This is used when a custom DNS server is specified.
forwarder_2_ip string null Any valid IP address This is used when a custom DNS server is specified.
forwarder_3_ip string null Any valid IP address This is used when a custom DNS server is specified.

Example

module "oci_network" {
  ... /snip - shortened for brevity...

  dhcp_options            = {
    custom                = {
      compartment_id      = null
      server_type         = local.dhcp_option_types["custom"]
      forwarder_1_ip      = "10.0.0.11"
      forwarder_2_ip      = "10.0.2.11"
      forwarder_3_ip      = null
      search_domain_name  = "test.local"
    }
    vcn                   = {
      compartment_id      = null
      server_type         = local.dhcp_option_types["vcn"]
      forwarder_1_ip      = null
      forwarder_2_ip      = null
      forwarder_3_ip      = null
      search_domain_name  = null
    }
  }
}

The above example will create two DHCP Options, one named custom, which has two IP addresses used and references the custom DHCP Option type. The vcn DHCP Option is pretty basic, just indicating that it should use VCNLocalPlusInternet and the name vcn.

Outputs

Each discrete resource that's created by the module will be exported, allowing for access to all returned attributes for the resource.

Resource Always returned? Description
ads yes The list of available ADs for the region you're working in.
vcn no* The VCN resource that has been created by the module.
igw no* The IGW resource created by the module (if it was requested/created).
natgw no* The NATGW resource created by the module (if it was requested/created).
svcgw no* The SVCGW resource created by the module (if it was requested/created).
svcgw_services yes The services available that can be used.
drg no* The DRG and DRGAttachment resources created by the module (if it was requested/created). Note that the DRG is accessible via drg.drg, and DRGAttachment via drg.drg_attachment.
route_tables no* The Route Table(s) created/managed by the module (if it was requested/created). A map is returned, where the key is the name of the Route Table and the value is a full listing of all of the resource attributes.
dhcp_options no* The DHCP Options(s) created/managed by the module (if it was requested/created). A map is returned, where the key is the name of the DHCP Option and the value is a full listing of all of the resource attributes.

*only returned when the resource has been requested to be created.

Note that you may still reference the outputs (even if they're not returned) without causing an error in Terraform (it must be smart enough to know not to throw an error in these cases).

Notes/Issues

  • Note that if you provide any single element in the different resource maps (vcn_options, igw_options, etc), you must provide all of them. Maps do not have a notion of an optional (or default value) for keys within the map, requiring that all keys/values be passed (if one key is passed, all keys must be passed).
  • If you change certain parameters, TF will try to delete and create, however it doesn't work properly always... when you see errors like the below, use terraform destroy, then terraform apply (instead of relying on terraform apply to handle things correctly):
Error: Cycle: module.oci_network.oci_core_nat_gateway.this[0], module.oci_network.output.natgw, module.oci_network.oci_core_service_gateway.this[0], module.oci_network.output.svcgw, module.oci_network.oci_core_service_gateway.this[0] (destroy), module.oci_network.oci_core_nat_gateway.this[0] (destroy), module.oci_network.oci_core_vcn.this[0] (destroy), module.oci_network.oci_core_drg_attachment.this[0], module.oci_network.oci_core_route_table.this[1] (destroy), module.oci_network.oci_core_drg_attachment.this[0] (destroy), module.oci_network.output.drg, local.next_hop_ids, module.oci_network.var.route_tables, module.oci_network.oci_core_route_table.this (prepare state), module.oci_network.oci_core_route_table.this[0] (destroy), module.oci_network.oci_core_internet_gateway.this[0] (destroy), module.oci_network.oci_core_internet_gateway.this[0], module.oci_network.output.igw

Release Notes

See release notes for release notes information.

URLs

Versions

This module has been developed and tested by running terraform on macOS Mojave Version 10.14.5

user-mac$ terraform --version
Terraform v0.12.3
+ provider.oci v3.31.0

Contributing

This project is open source. Oracle appreciates any contributions that are made by the open source community.

License

Copyright (c) 2020 Oracle and/or its affiliates.

Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.

See LICENSE for more details.