Oracle Cloud Infrastructure Terraform Modules for Identity and Access Management (oci-iam) v2
This module contains a collection of submodules that simplify the management of Identity and Access Management (IAM) resources such as compartments, users, groups, and dynamic groups for Oracle Cloud Infrastructure. For more information about IAM, see Overview of IAM.
Note: the root folder of this module contains no Terraform code: it groups together the related submodules.
The file and directory layout follows the Terraform Standard Module Structure:
- modules folder contains several standalone, reusable, submodules for creating IAM resources in Oracle Cloud Infrastructure,
- examples folder contains fully-functional examples that you can copy and paste "as is" to have a first look at the submodules capabilities.
Maintainers
This module is maintained by Oracle.
What's new in v2?
iam-compartment
- Add support for nested Compartments,
- Add support for Compartment deletion,
- DEPRECATED:
compartment_create
argument, which creates a data source instead of a resource when set tofalse
. This argument will be removed in the next major release. - DEPRECATED:
tenancy_ocid
. The preferred argument is nowcompartment_id
, as it can be used to create compartments at the tenancy root level and as a nested compartment.
iam-user
- Add for creating a list of users from a single module,
- Add support for defining user email.
iam-group
- DEPRECATED:
group_create
argument, which creates a data source instead of a resource when set tofalse
. This argument will be removed in the next major release.
iam-dynamic-group
- DEPRECATED:
dynamic_group_create
argument, which creates a data source instead of a resource when set tofalse
. This argument will be removed in the next major release.
Requirements
- Terraform 0.12.x
- OCI Terraform Provider 3.27 or greater
This modules and its submodules, in version 2, are optimized for Terraform v0.12:
- They will not run at all, or not as intended with a Terraform version below v0.12.0,
- They are not tested with Terraform versions above v0.12 and may produce unexpected behaviors.
The first OCI Terraform provider version to work with Terraform v0.12 is provider.oci v3.27.
- you must use OCI Terraform Provider v3.27 or above,
- this module and its submodules are not extensively tested with OCI Terraform Provider versions 4 and above,
- It may work and give richer informations for some resources, but also produce unexpected behaviors under certain circumstances.
The diagram below summarizes the required components and their respective versions to use this module.
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:
terraform {
required_version = ">= 0.12, < 0.13"
required_providers {
oci = {
version = ">= 3.27, < 4.0"
}
}
}
See the Oracle Cloud Infrastructure Terraform Provider docs for detailed information about setting up and using the Oracle Cloud Infrastructure Terraform Provider.
How to use the submodules
You should always pin the version of this module in your configuration: add the version
argument of the module block in your root configuration.
- To use v2 of this module for Terraform 0.12:
module "iam" {
source = "oracle-terraform-modules/iam/oci"
version = "2.0.0"
}
- to use v1 of this module for Terraform 0.11 compatibility:
module "iam" {
source = "oracle-terraform-modules/iam/oci"
version = "1.0.3"
}
Note:
- adjust the minor and patch version of the module according to your needs. If version is omitted, the latest available version on the registry will be used.
- When using the oci-iam modules, or more generally when manipulating iam resources, be sure to configure your oci provider to use the tenancy's home region, as IAM resources can only be managed from the home region.
- To combine this template with non-iam resources provisioned in a region different from your home region, you will need to use provider aliases.
The available submodules are listed below with example block codes. For fully-functional examples, please see examples.
Declaring OCI Compartments with iam-compartment
See a basic example below and the iam-compartment readme for details.
- To create a compartment at the root level of the tenancy, insert this block in your root configuration:
module "iam_compartment" {
source = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
tenancy_ocid = var.tenancy_ocid
compartment_id = var.tenancy_ocid # define the parent compartment. Creation at tenancy root if omitted
compartment_name = "tf_example_compartment"
compartment_description = "compartment at root level created - terraformed"
compartment_create = true # if false, a data source with a matching name is created instead
enable_delete = true # if false, on `terraform destroy`, compartment is deleted from the terraform state but not from oci
}
- To create a sub-compartment, with the previously created compartment as parent, insert this block in your root configuration:
module "iam_subcompartment" {
source = "oracle-terraform-modules/iam/oci//modules/iam-compartment"
tenancy_ocid = var.tenancy_ocid
compartment_id = module.iam_compartment.compartment_id # define the parent compartment. Here we make reference to the previous module's output
compartment_name = "tf_example_subcompartment"
compartment_description = "subcompartment created below tf_example_compartment - terraformed"
compartment_create = true # if false, a data source with a matching name is created instead
enable_delete = true # if false, on `terraform destroy`, compartment is deleted from the terraform state but not from oci
}
Declaring a list of OCI Users with iam-user
See a basic example below and the iam-user readme for details.
- To create a list of users, insert this block in your root configuration:
module "iam_users" {
source = "oracle-terraform-modules/iam/oci//modules/iam-user"
version = "2.0.0"
tenancy_ocid = var.tenancy_ocid # required
users = [ # a list of users
{ # user1
name = "tf_example_user1@example.com" # required
description = "user1 - terraformed" # required
email = null # set to null if you don't want to provide an email
},
{ # user2
name = "tf_example_user2@example.com"
description = "user2 - terraformed"
email = "tf_example_user2@example.com"
},
{ # user3
name = "tf_example_user3@example.com"
description = "user3 - terraformed"
email = "tf_example_user3@example.com"
},# add more users below as needed
]
}
Declaring OCI Groups with iam-group
See a basic example below and the iam-group readme for details.
- To create a group, add previously declared users as members and create an IAM policy in the previously declared compartment, insert this block in your root configuration:
module "iam_group" {
source = "oracle-terraform-modules/iam/oci//modules/iam-group"
version = "2.0.0"
tenancy_ocid = var.tenancy_ocid # required
group_name = "tf_example_group" # required
group_description = "an example group - terraformed" # required
user_ids = [element(module.iam_users.user_id,0),element(module.iam_users.user_id,1),element(module.iam_users.user_id,2)] # a list of user ocids
policy_name = "tf-example-policy" # optional
policy_compartment_id = module.iam_compartment.compartment_id # optional
policy_description = "policy created by terraform" # optional
policy_statements = [ # optional
"Allow group ${module.iam_group.group_name} to read instances in compartment tf_example_compartment",
"Allow group ${module.iam_group.group_name} to inspect instances in compartment tf_example_compartment",
]
}
Declaring OCI Dynamic Groups with iam-dynamic-group
See a basic example below and the iam-dynamic-group readme for details.
- To create a dynamic group with a matching rule, and create an IAM policy in the previously declared compartment, insert this block in your root configuration:
module "iam_dynamic_group" {
source = "oracle-terraform-modules/iam/oci//modules/iam-dynamic-group"
tenancy_ocid = var.tenancy_ocid
dynamic_group_name = "tf_example_dynamic_group"
dynamic_group_description = "dynamic group created by terraform"
matching_rule = "instance.compartment.id = '${module.iam_compartment.compartment_id}'"
policy_compartment_id = module.iam_compartment.compartment_id
policy_name = "tf-example-dynamic-policy"
policy_description = "dynamic policy created by terraform"
policy_statements = [
"Allow dynamic-group ${module.iam_dynamic_group.dynamic_group_name} to read instances in compartment tf_example_compartment"
]
}
Contributing
This project is open source. Oracle appreciates any contributions that are made by the open source community.
Learn how to contribute.
License
Copyright (c) 2018, 2021, Oracle and/or its affiliates.
Licensed under the Universal Permissive License 1.0 or Apache License 2.0.
See LICENSE for more details.