Oracle Cloud Infrastructure Documentation

Overview of Resource Manager

Automate deployment and operations for Oracle Cloud Infrastructure resources using Resource Manager. With supported Infrastructure as Code (IaC) tools, DevOps engineers can develop and deploy their infrastructure anywhere.

A Terraform configuration codifies your infrastructure in declarative configuration files. Resource Manager allows you to share and manage infrastructure configurations and state files across multiple teams and platforms. This infrastructure management can't be done with local Terraform installations and Oracle Terraform modules alone. For more information about the Oracle Cloud Infrastructure Terraform provider, see Terraform Provider. For a general introduction to Terraform and the "infrastructure-as-code" model, see Terraform Community.

Resource Manager is compliant with Federal Information Processing Standard (FIPS). For more information about OCI in US government regions, see Oracle Cloud Infrastructure US Government Cloud.

Tip

Watch a video introduction to the service.

Key Concepts

Following are brief descriptions of key concepts and the main components of Resource Manager.

configuration
Information to codify your infrastructure. Use your configuration to specify the Oracle Cloud Infrastructure resources in a given stack. For example, specify resource metadata, data source definitions, and variable declarations. Each Terraform configuration file is either HashiCorp Configuration Language (HCL) format or JSON format. HCL-formatted files use the file extension .tf . JSON-formatted files use the file extension .tf.json.
For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.
For example configurations, see Terraform Oracle Cloud Infrastructure Provider Examples and Oracle-Provided Templates. For more information, see Terraform Configurations for Resource Manager and Authoring Configurations; see also Terraform Language Documentation.
configuration source provider
Connection information to a source code control system where your Terraform configuration files are stored. Use a configuration source provider to create a stack from a remote, versioned Terraform configuration file.
A configuration source provider has the following types: 

A configuration source provider can be one of the following types:

  • Bitbucket
  • GitHub
  • GitLab

Following are the supported products for each type of configuration source provider.

A configuration source provider has the following lifecycle states:
  • Active: The configuration source provider is available for use.
For more information, see Managing Configuration Source Providers and Creating a Stack.

For a walk-through using CLI for cloud provisioning in a CI/CD pipeline, see IaC in the Cloud: Integrating Terraform and Resource Manager into your CI/CD Pipeline - Building With the OCI CLI.

drift
Difference between the actual, real-world state of your infrastructure, and the stack's last executed configuration. For example, drift occurs when a team member adds a production tag to your resources, or when a resource fails. You can run drift detection reports to determine if provisioned resources have different states than those resources defined in the stack's last executed configuration. You can also view detailed drift status for each resource.
job
Instructions to perform the actions defined in your configuration. Only one job at a time can run on a given stack; further, you can have only one set of Oracle Cloud Infrastructure resources on a given stack. To provision a different set of resources, you must create a separate stack and use a different configuration.
Jobs store history about their associated stack. For example, plan jobs store generated execution plans and apply jobs store configurations (snapshots) and state files. Jobs reside in the same compartment as the stack they are associated with. An OCID  is assigned to each job.
For information about Resource Manager job types, see Creating a Job.
A job has the following lifecycle states:
  • Accepted (ACCEPTED): The job was accepted for processing.
  • In progress (IN_PROGRESS): The job is running (executing).
  • Failed (FAILED): The job did not complete execution.
  • Succeeded (SUCCEEDED): The job has completed successfully.
  • Canceling (CANCELING): The job is being canceled; a notification has been sent, but the job has not yet stopped running.
  • Canceled (CANCELED): The job was canceled and has stopped running.
Default retry policy: A job might fail because of a downstream service issue. For example, an apply job for creating a compute instance might fail because of a temporary connectivity issue in the Compute service. When a job fails because of downstream service issue, the job retries according to the Go SDK default retry policy. See Go SDK for Oracle Cloud Infrastructure.
module
A group of related resources. Use modules to create lightweight and reusable abstractions, so that you can describe your infrastructure in terms of its architecture. For more information, see Creating Modules.
package
Typically a .zip file to a Terraform configuration that is stored in a supported provider, such as GitHub. For more information, see Using the Deploy to Oracle Cloud Button.
private endpoint
Network information for connecting to a nonpublic resource. For more information, see Managing Private Endpoints.
resource discovery
A feature to capture deployed Oracle Cloud Infrastructure resources as Terraform configuration and state files. For more information, see Resource Discovery.
stack
The collection of Oracle Cloud Infrastructure resources corresponding to a given Terraform configuration. Each stack resides in the compartment you specify, in a single region; however, resources on a given stack can be deployed across multiple regions. An OCID  is assigned to each stack.
For steps on creating stacks, see Creating a Stack. For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.
A stack has the following lifecycle states:
  • Creating: The stack is being created.
  • Active: The stack is available for use.
  • Deleting: The stack is being deleted.
  • Deleted: The stack was deleted.
  • Failed: The stack could not be created.
state
The state of your resource configuration, stored in JSON format in a state file (.tfstate). For more information, see State Management.
template
A prebuilt Terraform configuration that provisions a set of resources used in a common scenario. The template can be provided by either Oracle or someone in your tenancy, as a private template. To create stacks from templates, see Creating a Stack from a Template. For reference, see Oracle-Provided Templates.

To create private templates, see Managing Private Templates.

Features

Templates

A template is a Terraform configuration that you can use to manage infrastructure. Templates can help customers who are new to infrastructure as code and who are updating production workflow configurations. Use templates to try out Resource Manager and to apply proven best practices to your production workflow configuration. For information about Oracle-provided templates, see Oracle-Provided Templates.

Create your own private templates to share with others in the tenancy.

Start with a Resource Creation Page

Save your configuration from a resource configuration page to a stack. Use the stack to install, configure, and manage the resource through the "infrastructure-as-code" model. For more information, see Creating a Stack from a Resource Creation Page.

CI/CD with Resource Manager

Remotely store your Terraform configurations using integrated source code control systems, such as Bitbucket Cloud, Bitbucket Server, DevOps, GitHub, and GitLab. This integration helps you achieve continuous integration and continuous delivery (CI/CD).

For more information, see:

For a walk-through using CLI for cloud provisioning in a CI/CD pipeline, see IaC in the Cloud: Integrating Terraform and Resource Manager into your CI/CD Pipeline - Building With the OCI CLI.

In addition, we also allow storing Terraform configurations in Object Storage buckets. For more information, see Creating a Stack from a Bucket.

Resource Discovery

A feature to capture deployed resources as Terraform configuration and state files. With this feature, you can:

  • Move from manually managed infrastructure to Resource Manager-controlled infrastructure.
  • Learn how Terraform uses HashiCorp Configuration Language (HCL) syntax to represent Oracle Cloud Infrastructure resources.
  • Duplicate or rebuild existing infrastructure in another compartment.
For more information, see Resource Discovery and the following instructions:
State Management

Resource Manager stores Terraform state files for stacks so you don't have to. Multiple people can work on a stack concurrently because Resource Manager locks the stack state, allowing only one job at a time to run on a given stack. Resource Manager automatically generates and updates the stack's state file (.tfstate, in JSON format). This file maps your stack's resources to your configuration and maintains essential configuration metadata, such as resource dependencies.

For related instructions, see:

For more information about Terraform state files, see State.

Drift Detection

Find out if provisioned resources have different states than those resources defined in the stack's last run configuration and view detailed drift status for each resource.

You can optionally limit the drift detection to specified resources. Each resource is identified by a resource address, which is a string derived from the resource type and name specified in the stack's Terraform configuration plus an optional index. For example, the resource address for the fourth Compute instance with the name "test_instance" is oci_core_instance.test_instance[3]. The resource type is oci_core_instance, a period acts as delimiter, the resource name is test_instance, and the index is 3 in bracket. For more details and examples of resource addresses, see the Terraform documentation at Examples.

For more information about drift detection, see drift and the following instructions:
Deploy to Oracle Cloud Button

The Deploy to Oracle Cloud button allows you to launch your remote Terraform configuration using the Create Stack workflow available in Resource Manager.

This image shows the Deploy to Oracle Cloud button.

For more information, see Using the Deploy to Oracle Cloud Button.

Private Endpoints

With private endpoints, you can access nonpublic cloud resources in your tenancy from Resource Manager. For example, use Remote Exec with a private instance or access a Terraform configuration in a private GitHub server.

For more information, including common scenarios, see Managing Private Endpoints.

Custom Providers

You can supply custom Terraform providers using Object Storage. To add custom providers to buckets, see Putting Data into Object Storage. To fetch custom providers from buckets, see Using Custom Providers with a Stack.

Dependency Lock Files

Dependency lock files are automatically managed for new and updated stacks. You decide when to retrieve the latest versions available from the configured source of Terraform providers. Providers are updated within the version constraints of the Terraform configuration. For instructions, see Retrieving the Latest Providers.

Roll Back Jobs

Roll back a stack to a previous known state. Rolling back is a good alternative to spending time troubleshooting a stack's unknown state.

To roll back, first identify the successful apply job that you want. This "target job" uses a different Terraform configuration. Create a plan rollback job for this target job, and then create an apply rollback job using the generated execution plan.

Availability

The Resource Manager service is available in all Oracle Cloud Infrastructure commercial regions. See About Regions and Availability Domains for the list of available regions, along with associated locations, region identifiers, region keys, and availability domains.

Generalized Workflow

The following image represents a generalized view of the Resource Manager workflow.

This image shows the workflow for provisioning infrastructure using Resource Manager.

  1. Create a Terraform configuration.

    Note

    For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.
  2. Create a stack.
  3. Run a plan job, which produces an execution plan.
  4. Review the execution plan (job logs).
  5. If changes are needed in the execution plan, update the configuration and run a plan job again.
  6. Run an apply job to provision resources.
  7. Review state files and log files, as needed.
  8. You can optionally reapply your configuration, with or without making changes, by running an apply job again.
  9. Optionally, to release the resources running on a stack, run a destroy job.

For a detailed walkthrough of the Resource Manager workflow, see Getting Started.

Ways to Access Resource Manager

You can access the Resource Manager service using the Console or the Resource Manager REST API. Instructions for using the Console, API, and CLI are included in topics throughout this documentation. For a list of available SDKs, see Software Development Kits and Command Line Interface.

Console: To access Resource Manager using the Console, you must use a supported browser. To go to the Console sign-in page, open the navigation menu at the top of this page and click Infrastructure Console. You are prompted to enter your cloud tenant, your user name, and your password. Open the navigation menu and click Developer Services. Under Resource Manager, click Overview.

API: To access Resource Manager through APIs, use Resource Manager API.

CLI: See Command Line Reference for Resource Manager.

Default Provider

By default, Resource Manager supports terraform-provider-oci, the Terraform provider for Oracle Cloud Infrastructure.

For supported third-party Terraform providers, see Supported Terraform Providers.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, and so on. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you're a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

Important

Policies for managing Oracle Cloud Infrastructure resources are also required for Resource Manager operations that access resources. For example, running an apply job on a stack that includes Compute instances and subnets requires policies that grant you permissions for those resource types, in the compartments where you want to provision the resources. To see examples of policies for managing Oracle Cloud Infrastructure resources, see Common Policies.

Administrators: For common policies that give groups access to Resource Manager resources, see IAM Policies (Securing Resource Manager).

Security

In addition to creating IAM policies, follow these security best practices for Resource Manager.

  • Limit the use of sensitive information in configuration and output files
  • Perform a security audit
  • Use private endpoints to securely access resources without exposing network traffic to the public

See Securing Resource Manager.