This module manages arbitrary Identity and Access Management (IAM) compartment topologies in Oracle Cloud Infrastructure (OCI) based on a map of objects that can be nested up to six levels. Appropriate compartments usage is a key consideration for OCI tenancy design and it is a recommendation of CIS (Center for Internet Security) OCI Foundations Benchmark.
Check module specification for a full description of module requirements, supported variables, managed resources and outputs.
A fundamental principle in using a map of objects is the ability to quickly visualize the actual compartment structure by simply looking at the variable definition. The input variable is an object named compartments_configuration, with the following attributes:
- default_parent_id – (Optional) determines the parent compartment for all your top (first level) compartments defined by the compartments attribute. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. For referring to the tenancy_ocid, leave it unassigned or use the reserved key "TENANCY-ROOT".
- enable_delete – (Optional) determines whether or not OCI should physically delete compartments when destroyed by Terraform. Default is false.
- default_defined_tags – (Optional) defined tags to apply to all compartments, unless overridden by defined_tags attribute within each compartment object.
- default_freeform_tags – (Optional) freeform tags to apply to all compartments, unless overridden by freeform_tags attribute within each compartment object. Freeform tags are limited to 10 tags per OCI resource.
- compartments – (Optional) the map of objects that define compartments hierarchies. Each top (first level) compartment has a parent_id attribute to identify the compartment's parent (in other words, where the particular tree descends from). It overrides default_parent_id. Each compartment object has a children attribute that defines its sub-compartments. The compartments map supports up to six levels of nesting, which is the maximum supported by OCI.
- name – The compartment name.
- description – The compartment description.
- parent_id – (Optional) The compartment's parent compartment. Only available for first-level compartments. This attribute is overloaded: it can be either a compartment OCID or a reference (a key) to the compartment OCID. default_parent_id is used if undefined. For referring to the tenancy_ocid, use the reserved key "TENANCY-ROOT".
- defined_tags – (Optional) The compartment defined_tags. default_defined_tags is used if undefined.
- freeform_tags – (Optional) The compartment freeform_tags. default_freeform_tags is used if undefined.
- tag_defaults – (Optional) A map of tag defaults to apply to the compartment. Every resource created in the compartment is tagged per this setting.
- tag_id – The tag default tag id. This attribute is overloaded: it can be either a tag OCID or a reference (a key) to the tag OCID.
- default_value – The default value to assign to the tag.
- is_user_required – (Optional) Whether the user must provide a tag value for resources created in the compartment.
- children: – (Optional) The map of sub-compartments. It has the same structure of the compartments map, except for the parent_id attribute.
Note it is possible to apply tag defaults to compartments. Tag defaults are tag values that are automatically applied or required from users on any resources eventually created in the compartments and in their sub-compartments. Use tag defaults to enforce organization wide governance practices in your cloud infrastructure, like automatically applying the cost center identifier to specific compartments. Before using a tag default, a defined tag must be defined in OCI. For configuring tags, you can use the Tags module in OCI Landing Zones Governance repository.
Tag defaults are defined using tag_defaults attribute within each compartment in compartments attribute. You can have multiple tag defaults in a single compartment. Each tag default requires an immutable key (use an uppercase string as a convention), a tag id (tag_id), the default value (default_value) and whether or not the value is required from users when creating resources (is_user_required). If is_user_required is not provided or set to false, the default value is automatically applied upon resource creation.
Each compartment is identified by Terraform with an artificial key provided in the input variable. For example, in the snippet below, DATABASE (rows 4-13) identifies the database-cmp compartment, while PROD (rows 8-11) identifies its child database-production-cmp compartment.
1 compartments_configuration = {
2 default_parent_id = "<COMPARTMENT-OCID>"
3 compartments = {
4 DATABASE = {
5 name = "database-cmp"
6 description = "Database compartment"
7 children = {
8 PROD = {
9 name = "database-production-cmp"
10 description = "Database production compartment"
11 }
12 }
13 }
14 }
15 }
These identifying keys are used in Terraform state file as resource addresses. By default, the keys are written "as-is" to the state file. As such, they must be unique across all compartment definitions. However, when defining complex hierarchies where distinct compartment subtrees has similar characteristics, it is desirable to use the same identifying key across the subtrees, as in when both DATABASE and APPLICATION compartments have PROD compartments. In use cases like this, set the variable derive_keys_from_hierarchy to true and the PROD compartments will be identified as DATABASE-PROD and APPLICATION-PROD. It works at all levels in the hierarchy, i.e., if DATABASE's PROD had a child defined as HR in the variable declaration, the HR compartment would be identified as DATABASE-PROD-HR in Terraform state file.
derive_keys_from_hierarchy: whether identifying keys should be derived from the provided compartments hierarchy. It allows for using the same identifying key in different compartment subtrees, thus removing the requirement of unique keys. Default is false.
Check the examples folder for module usage with actual input data.
An optional feature, external dependencies are resources managed elsewhere that resources managed by this module depends on. The following dependencies are supported:
- compartments_dependency – (Optional) 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. This mechanism allows for the usage of referring keys (instead of OCIDs) in default_parent_id and parent_id attributes. The module replaces the keys by the OCIDs provided within compartments_dependency map. Contents of compartments_dependency is typically the output of a client of this module.
Example:
{
"NETWORK-CMP": {
"id": "ocid1.compartment.oc1..aaaaaaaa...7xq"
}
}
- tags_dependency – (Optional) A map of objects containing the externally managed tags this module may depend on. All map objects must have the same type and must contain at least an id attribute with the tag OCID. This mechanism allows for the usage of referring keys (instead of OCIDs) in tag_id attribute. The module replaces the keys by the OCIDs provided within tags_dependency map. Contents of tags_dependency is typically the output of a client of the Tags module.
Example:
{
"COST-CENTER-TAG": {
"id": "ocid1.tag.oc1..aaaaaaaa...8yr"
}
}
This module requires Terraform binary version 1.3.0 or greater, as it relies on Optional Object Type Attributes feature. 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.
This module requires the following OCI IAM permission in compartments referred by default_parent_ocid and/or parent_ocid:
Allow group <group> to manage compartments in compartment <parent_compartment_name>
If parent is the root compartment, the permission becomes:
Allow group <group> to manage compartments in tenancy
In case you are applying tag defaults to compartments, the following permissions are required:
Allow group <group> to manage tag-defaults in compartment <tag_default_compartment_name>
Allow group <group> to use tag-namespaces in compartment <tag_namespace_compartment_name>
Allow group <group> to inspect tag-namespaces in tenancy
- <tag_default_compartment_name> is the compartment where the tag default is applied.
- <tag_namespace_compartment_name> is the compartment where the tag namespace is available.
Terraform modules can be invoked locally or remotely.
For invoking the module locally, just set the module source attribute to the module file path (relative path works). The following example assumes the module is two folders up in the file system.
module "compartments" {
source = "../.."
compartments_configuration = var.compartments_configuration
}
For invoking the module remotely, set the module source attribute to the compartments module folder in this repository, as shown:
module "compartments" {
source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-iam/compartments"
compartments_configuration = var.compartments_configuration
}
For referring to a specific module version, append ref=<version> to the source attribute value, as in:
source = "github.com/oracle-quickstart/terraform-oci-cis-landing-zone-iam//compartments?ref=v0.1.0"
- Account and Access Concepts
- Managing Compartments
- Compartments in Terraform OCI Provider
- Managing Tag Defaults
- Tag Defaults in Terraform OCI Provider
Open an issue in this repository.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2023,2024 Oracle and/or its affiliates.
Replace this statement if your project is not licensed under the UPL
Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.
None.