Managing Stacks and Jobs

This topic describes how to create, edit, and delete stacks as well as work with jobs, including generating and applying execution plans. Drift detection is also covered in this topic.

Required IAM Policy

To manage stacks and jobs, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

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.

If you're new to policies, see Getting Started with Policies and Common Policies.

Administrators: For common policies that give groups access to Resource Manager resources, see Manage Stacks and Jobs (Securing Resource Manager).

Tagging Resources

You can apply tags to your resources to help you organize them according to your business needs. You can apply tags at the time you create a resource, or you can update the resource later with the wanted tags. For general information about applying tags, see Resource Tags.

Moving Resources to a Different Compartment

You can move stacks from one compartment to another. When you move a stack to a new compartment, its associated jobs move with it. After you move the stack to the new compartment, inherent policies apply immediately and affect access to the stack and associated jobs through the Console. For more information, see Managing Compartments.

Using the Console

Managing Stacks (Console)

To create a stack

This section describes how to start from the Create stack page when creating stacks. For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click Create stack.

  4. In the Create stack page, under Choose the origin of the Terraform configuration, select the option you want.

    • My configuration: Local folder, Object Storage bucket, or local .zip file.

      Under Stack configuration, select the option corresponding to the location of your Terraform configuration:

      • Folder: Drag and drop a folder onto the dialog's control or click Browse and navigate to the location of the folder you want.
      • Object Storage bucket: Select a bucket from the list.

        The list shows buckets in the indicated compartment. To choose another compartment, click Change Compartment.

      • .Zip file: Drag and drop a .zip file onto the dialog's control or click Browse and navigate to the location of the .zip file you want.

      The dialog box is populated with information contained in the local Terraform configuration.

    • Template: Pre-built Terraform configuration (service, architecture, or private template).

      Under Stack configuration, click Select template and then select the template you want. Private templates are under the Private tab.

      The dialog box is populated with information contained in the Terraform configuration for the selected template.

    • Source code control system: Remote location using a configuration source provider.
      Steps
      1. Under Stack configuration, select a Configuration source provider.

        If you need to create one, see To create a configuration source provider.

      2. Select a Repository.

        Example: https://gitlab.com/example

      3. Select a Branch.

        The list returned is limited to 100 branches.

      4. (Optional) Specify a Working directory for running Terraform.

        This field is visible when you select a branch with directories.

        Example (one level): Directory

        Example (two levels): Directory/Subdirectory

        If not specified, the root directory is used.

      The dialog box is populated with information contained in the remote Terraform configuration.

    • Existing compartment: Generate a Terraform configuration using resource discovery.

      Steps
      • Select the Compartment for resource discovery (the compartment containing the resources that you want to capture).

        A compartment from the list scope is set by default.

      • Select the Region for resource discovery (the region containing the resources that you want to capture).

      • To filter for specific services supported for resource discovery, select Selected and then select the services you want.

        Note

        This setting cannot be changed when editing the stack later.

      The dialog box is populated with information about the specified compartment.

  5. To use custom providers, do the following.
    1. Select Use custom providers.
    2. Select the bucket that contains the custom providers.
  6. Enter a Name for the new stack (or accept the default name provided). Avoid entering confidential information.
  7. Optionally enter a Description.
  8. For Create in compartment, select the compartment where you want to create the stack.

    A compartment from the list scope is set by default.

  9. For Terraform version, select the version you want for the Terraform configuration.

    This field is not available when Existing compartment is selected.

  10. Optionally apply tags to the stack.

    If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

  11. Click Next.

    The Configure variables panel displays variables from the Terraform configuration.

    No variables are listed for the Existing compartment stack origin because no Terraform configuration exists yet.

  12. Review the variables and change as needed.

    Important

    Do not add your private key or other confidential information to configuration variables.
  13. Click Next.

  14. In the Review panel, verify your stack configuration.

  15. To automatically provision resources when the stack is created, select Run apply.

    This field is not available when Existing compartment is selected.

    Note

    Run apply is selected by default for stacks created from the Deploy to Oracle Cloud button or from Marketplace.
  16. Click Create to create your stack.

    The stack detail page for the new stack appears.

    If Run apply was selected, then Resource Manager runs the apply action on the new stack.

Existing compartment stack origin: A work request runs on your stack. When the work request finishes, a job runs to generate a Terraform configuration file for the stack. When the job finishes, the resources in the selected compartment are captured in the generated configuration. You can recreate these resources in another compartment.

To deploy the defined resources, run an apply job on your new stack.

To begin stack creation from the Create Compute Instance page

You can create a stack using the configuration you specify in the Create Compute Instance page available in the Console. Use the new stack to install, configure, and manage your compute instance  through the "infrastructure-as-code" model.

Note

Before you start, view requirements for creating Compute instances. See Required IAM Policy and the prerequisites for Creating a Linux Instance or Creating a Windows Instance.
  1. Open the Create Compute Instance page:
    1. Open the navigation menu and click Compute. Under Compute, click Instances.
    2. Click Create instance.
  2. Populate configuration fields to specify stack details. For example, select the image you want to use in your stack.
  3. Click Save as stack.

    The Create stack page appears. The "Compute Instance" stack origin is indicated at the top of the dialog window, along with any provided instance name.

  4. In the Create stack page, do the following.
    1. Enter a Name for the new stack. Avoid entering confidential information.

      Example: My Compute Instance

    2. Optionally enter a Description.
    3. From the Create in compartment drop-down, select the compartment where you want to create the stack.

      A compartment from the list scope is set by default.

    4. Select a Terraform version.

      Note

      Terraform versions are not backward compatible.
    5. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
    6. Click Next.

      The Configure variables panel displays variables from the selected Terraform configuration file.

    7. Review the variables and make changes as necessary.

      Important

      Do not add your private key or other confidential information to configuration variables.
    8. Click Next.
    9. In the Review panel, verify your stack configuration.
    10. To automatically provision resources when the stack is created, select Run apply.

    11. Click Create to create your stack.

    The stack detail page for the new stack appears.

    If Run apply was selected, then Resource Manager runs the apply action on the new stack.

    If Run apply was not selected, then you can manually run the apply action on the stack.

To see how Terraform represents your resources

Learn how Terraform uses HashiCorp Configuration Language (HCL) syntax to represent Oracle Cloud Infrastructure resources.

  1. Capture existing infrastructure by creating a stack from that compartment.

    Key steps in the Create stack page:

    1. Under Choose the origin of the Terraform configuration, select Existing compartment.

    2. Select the Compartment for resource discovery (the compartment containing the resources that you want to capture).

      A compartment from the list scope is set by default.

    3. Select the Region for resource discovery (the region containing the resources that you want to capture).
    4. To filter for specific services supported for resource discovery, select Selected and then select the services you want.

      Note

      This setting cannot be changed when editing the stack later.
    5. Click Next twice, and then click Create to create your stack.

    The stack detail page for the new stack appears. A work request runs on your stack. When the work request finishes, a job runs to generate a Terraform configuration file for the stack. When the job finishes, the resources in the selected compartment are captured in the generated configuration.

  2. Download the generated Terraform configuration file: In the Stack information tab of the stack detail page, click Download.
    Note

    Alternatively, you can view the generated Terraform configuration file in Code Editor. For more information, see Editing Configurations Using Code Editor.
To recreate (clone) existing infrastructure in another compartment
  1. Capture existing infrastructure by creating a stack from that compartment.

    The stack detail page for the new stack appears. A work request runs on your stack. When the work request finishes, a job runs to generate a Terraform configuration for the stack. When the job finishes, the resources in the selected compartment are captured in the generated configuration.

  2. Download the generated Terraform configuration file: In the Stack Information tab of the stack detail page, click Download.
  3. Edit the vars.tf file (variables in the downloaded Terraform configuration file) to specify the destination compartment_ocid and region.

    Example:

    variable "compartment_ocid" {
      default = "ocid1.compartment.oc1..uniqueid"
    }
    variable "region" {
      default = "us-phoenix-1"
    }
  4. If the destination region has more or fewer availability domains than the source region, then edit the vars.tf file to specify the correct number of availability domains.

    For example, if you cloned from a region that has 3 availability domains and you want to recreate the infrastructure in a region that has only 1 availability domain, then remove the references to the second and third availability domains.

    Example showing 3 availability domains:

    data oci_identity_availability_domain export_NzDH-EU-FRANKFURT-1-AD-1 {
      compartment_id = var.compartment_ocid
      ad_number      = "1"
    }
    data oci_identity_availability_domain export_NzDH-EU-FRANKFURT-1-AD-2 {
      compartment_id = var.compartment_ocid
      ad_number      = "2"
    }
    data oci_identity_availability_domain export_NzDH-EU-FRANKFURT-1-AD-3 {
      compartment_id = var.compartment_ocid
      ad_number      = "3"
    }

    Example showing 1 availability domain:

    data oci_identity_availability_domain export_NzDH-EU-FRANKFURT-1-AD-1 {
      compartment_id = var.compartment_ocid
      ad_number      = "1"
    }
  5. Create a second stack using the edited configuration file.

    1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
    2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

    3. Click Create stack.
    4. In the Create stack dialog, click My configuration.
    5. Add the downloaded Terraform configuration (.zip) file.

      You can leave other fields as is for now. For reference, see To create a stack.

    6. For Terraform version, select a version supported by resource discovery.
    7. Click Next to display the Configure variables panel.
    8. Update the compartment_ocid variable to specify the destination compartment for the cloned resources.
    9. If you want to clone the resources to a different region, update the region variable.
    10. Click Next to display the Review panel.
    11. To automatically provision resources when the stack is created, select Run apply.

    12. Click Create to create your stack.

      The stack detail page for the second stack appears.

      If Run apply was selected, then Resource Manager runs the apply action on the new stack.

      The resources are cloned in the specified compartment and region.

  6. If you didn't select Run apply for the new stack, then run Apply now (after optionally running Plan):
    1. (Optional) To confirm that the stack will create resources as expected, run a plan job.
    2. Clone resources: Run an apply job on the new stack.

      The resources are cloned in the specified compartment and region.

To view stacks

You can view stack names, descriptions, states, and time created. The detail page for a stack lists its drift status and allows you to view the latest drift detection report.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. To display the detail page for a stack, click the stack's name.
To check the OCI Terraform provider version

Follow these instructions to verify the version of OCI Terraform provider used by Resource Manager in the current region.

Note

You can also check this version using a Terraform command. For instructions, see Checking the Terraform and OCI Terraform Provider Versions.

The OCI Terraform provider documentation reflects the latest version. You can view documentation for earlier provider versions by visiting the HashiCorp reference and selecting a specific version.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Ensure that the region you want to use is selected.

    For example, select a dedicated commercial region.

  4. Click the name of a stack.

    The Stack details page is displayed.

  5. Click Plan.

    The plan job automatically includes the version of OCI Terraform provider in its log.

    You can alternatively run an apply job, which also includes this version information in its log.

  6. (Optional) In the Plan panel, review the plan job Name and update it if needed.

  7. In the Plan panel, click Plan.

    The new plan job is listed under Jobs. When the job is complete, the Job details page appears, with the log listed.

  8. In the Job details page, view the provider version listed in the job log.

    To access the job log from this page, click Logs under Resources.

    Example provider version:

    *provider.oci: version = "~> 4.23"
To download the stack's Terraform configuration file

The Terraform configuration file listed on the stack detail page is the same as the Terraform configuration file listed on the job detail page for the most recent successful job.

Note

For stacks created using source code control systems, configuration files are not available for download until a job is successfully run on the stack.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack to display its detail page.
  4. In the Stack information tab, to the right of Terraform configuration, click Download.
    Note

    Alternatively, you can view the generated Terraform configuration file in Code Editor. For more information, see Editing Configurations Using Code Editor.
To detect drift for a stack or selected resources

You can detect drift for new stacks created from compartments or for stacks where the last job run was Apply or Import state. When detecting drift, you can specify all resources or selected resources.

Drift is the 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 is deleted.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack to display its detail page.

  4. Go to More actions and select Run drift detection.

    Alternatively, in the Stack information tab, click Run drift detection now.

  5. In the Run drift detection panel, select the option you want.

    • All resources: Detects drift for all resources in the stack.

    • Selected resources: Detects drift for the specified resources in the stack.

      You can select an address from the list or enter the address. 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] (resource type of oci_core_instance, a period as delimiter, resource name of test_instance, and index of 3 in brackets). For more details and examples of resource addresses, see the Terraform documentation at https://www.terraform.io/docs/internals/resource-addressing.html#examples.

  6. (Optional) Configure advanced options:

    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Optionally tag the job.
  7. Click Run drift detection.

    A work request is started. When the work request is complete, the drift status appears in the Stack information tab. See To view the latest drift detection report.

To add unmanaged resources to a stack
Note

Some steps in this procedure use the Terraform CLI.
  1. Gather information about the unmanaged resources that you want to add: Note their OCIDs.

    Unmanaged resources are created outside Resource Manager.

    Tip

    You can generate a Terraform configuration that lists all resources in a compartment. For instructions, see To see how Terraform represents your resources.
  2. Gather stack information
    1. In the Console, access the detail page for the stack that you want to add the resources to.

      1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
      2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

      3. Click the name of the stack to display its detail page.

    2. Confirm that currently managed resources are up to date: Generate a drift detection report.

      1. Go to More actions and select Run drift detection.

      2. In the Run drift detection panel, select All resources.

      3. Click Run drift detection.

        A work request is started. When the work request is complete, the drift status appears in the Stack information tab.

      4. Go to More actions and select View drift detection report.

        A panel lists the drift status of the specified resources defined by the stack. Resources are identified by resource names.

      5. To view details of drift status for a resource, click the down arrow.

        Actual and expected properties are listed.

      6. If differences between actual and expected properties are reported, make your resources match the properties of your Terraform configuration: run an apply job. In the Stack Details page, click Apply.

        You can alternatively address these differences when manually editing the Terraform configuration later.

    3. Download the stack's Terraform configuration file: In the Stack information tab, to the right of Terraform configuration, click Download.

    4. Download the stack's state file:

      1. Go to the detail page for the most recent apply job: Click the job link under Jobs.
      2. On the job detail page, click Download Terraform state.
  3. Update the state file using Terraform CLI
    1. Set up Terraform CLI on your local machine.

      For instructions, see Terraform CLI.

    2. On your local machine, go to Terraform CLI and navigate to the directory containing the downloaded Terraform configuration and state file.

    3. For each unmanaged resource previously identified, import the state file by running the terraform import command:

      terraform import -state=<path_to_tfstate_file> -var-file="<path_to_credentials_file>" -var-file="<path_to_env_file>" <resource_name> <resource_ocid>

      Example:

      terraform import -state=example.tfstate -var-file="credentials.tfvars" -var-file="environments.tfvars" module.operations.oci_identity_compartment.move_compartment ocid1.compartment.oc1..exampleid

      For more information about this command, see Terraform Import CLI Command.

    4. Refresh the state file by running the terraform refresh command:

      Note

      To refresh for a specific resource, use the refresh target -target=<resource>.

      For more information about this command, see Terraform Refresh CLI Command.

  4. Manually update the downloaded Terraform configuration to include the unmanaged resource previously identified.

    If any unresolved drift remains in the drift detection report, address those differences in your manual update.

  5. Update the stack
    1. Access the stack's detail page again.

      1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
      2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

      3. Click the name of the stack to display its detail page.

    2. Import the refreshed state file to the stack.

      1. Go to More actions and select Import state.

      2. In the Import state dialog, add your Terraform state file, either by dragging and dropping it onto the dialog's control, or by clicking Browse and navigating to the file location.

      3. Click Import.

    3. Upload the manually edited Terraform configuration to the stack.

      1. In the Stack information tab, next to Terraform configuration, click Upload.

      2. In the Edit stack dialog, under Stack configuration, click .Zip file and add your revised Terraform configuration.

        You can either drag and drop your Terraform configuration .zip file onto the control or click Browse and navigate to the location of the .zip file.

      3. Click Next as needed and then click Save changes.

  6. Confirm that infrastructure is up to date
    1. Click Plan.

    2. In the Plan dialog, review the plan job Name and update it if needed.

    3. Click Plan.

      The new plan job is listed under Jobs, with an initial state of Accepted. Soon the status changes to In progress. When the job is complete, view the job log to confirm no changes.

      Example of a job log reporting no changes:

      No changes. Infrastructure is up-to-date.
      This means that Terraform did not detect any differences between your
      configuration and real physical resources that exist. As a result, no
      actions need to be performed. 

    Congratulations! You have successfully added previously unmanaged resources to the stack. The added resources are now managed by Resource Manager.

To view the latest drift detection report
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack to display its detail page.
  4. Go to More actions and select Run drift detection.

    Alternatively, in the Stack information tab, click View drift detection report.

    A panel lists the drift status of the specified resources defined by the stack. Resources are identified by resource names.

  5. To view details of drift status for a resource, click the down arrow.

    Actual and expected properties are listed.

  6. (Optional) To make your resources match the properties of your Terraform configuration, run an apply job: In the Stack details page, click Apply.

To view an old drift detection report
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack to display its detail page.
  4. Click Work requests.
  5. Click the work request for the drift detection report you want.
  6. In the Work requests information tab, click View drift detection report.

    A panel lists the drift status of the specified resources defined by the stack at the time the drift detection was detected. Resources are identified by resource names.

  7. To view details of drift status for a resource, click the down arrow.

    Actual and expected properties are listed.

To view the latest drift detection report, see To view the latest drift detection report. To detect drift again, see To detect drift for a stack or selected resources.

To edit a stack

You can edit stacks. When editing a stack, you can upload a different configuration and change the stack's name, description, and variables.

Note

As an alternative to these steps, edit the generated Terraform configuration file in Code Editor. For more information, see Editing Configurations Using Code Editor.

If your configuration is stored in a source code control system, such as GitLab, then commit your changes there. The most recent commit is used when you run jobs on the stack.

If your configuration is stored in a bucket, you cannot change the bucket in your existing stack, but you can change the contents of the bucket. The most recent contents of the bucket are used when you run jobs on the stack.

No configuration file is available for download until a job is successfully run on the stack.

For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the Actions menu, and then select Edit.

    You can also edit a stack from its detail page. Click the name of the stack to display its detail page and then click Edit.

  4. In the Edit stack dialog box, change the properties you want. For origin-specific configuration, see the origin step in To create a stack.

    Note

    For a stack that specifies an Object Storage bucket, the bucket and compartment cannot be changed.
    • To edit the values assigned to variables in a stack, click Configure variables.

      You can also edit variables from a stack's detail page. Click the name of the stack to display the Stack details page, click Variables (under Resources) and then click Edit variables.

      Important

      Do not add your private key or other confidential information to configuration variables.

      If you want to add, reconfigure, or delete variables in a stack, update the Terraform configuration.

    • To automatically provision resources when the stack is updated, select Run apply.

      The Run apply option is displayed on the Review page. Click Review on the left to see it.

  5. Click Save changes.

    The stack detail page for the edited stack appears.

    If Run apply was selected, then Resource Manager runs the apply action on the updated stack.

To use Terraform Registry with an older stack

Update older stacks to fetch providers from Terraform Registry.

Caution

  • To prevent incompatible provider versions, update the configuration to specify version constraints, listing versions that exist in the configured provider source (Terraform Provider or custom providers).
  • To prevent job failures from unavailable provider versions, ensure that versions listed in the version constraints of the configuration exist in the configured provider source (Terraform Provider or custom providers), or remove version constraints entirely (results in retrieval of the latest versions).

To determine the source of providers for your stack, review the logs for a recent job.

The following phrase indicates that the stack is fetching providers from Terraform Registry:

Getting providers from hashicorp registry and/or custom terraform providers
Stacks that were created before Terraform Registry sourcing was available continue to fetch providers from Resource Manager until updated. When updated, stacks fetch providers from Terraform Registry and custom providers are available.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
  3. Click the stack that you want.
  4. In the detail page for the stack, click More actions and then select Use Terraform registry.
To use custom providers with a stack

Learn how to update an existing stack to use custom providers.

Older stacks: If the stack was created before custom providers were available, then first update the stack to use Terraform Registry. This update allows the stack to use custom providers.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.
  3. Locate the stack that you want, click the Actions menu, and then select Edit.
  4. In the Edit stack dialog box, select Use custom providers.
  5. Select the bucket that contains the custom providers.
  6. Click Save changes.
To view the state of a stack

Download the state file corresponding to the most recently run job for the stack.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack to display its detail page.
  4. Go to More actions and select Download Terraform state.
To manage tags for a stack

Tags are key/value pairs that you can attach to resources to help you organize and track your resources across compartments. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack you want.

    The Stack details page lists the details about the selected job.

  4. Click Tags to view or edit existing tags, or click Add tags to add new ones.
To move a stack to a different compartment
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack.
  4. On the Stack details page, go to More actions and then select Move resource.
  5. In the Move resource dialog box, select the compartment that you want to move the stack to.
  6. Click Move resource.
To delete a stack
Note

Associated resources persist after stack deletion. When you delete a stack, its associated state file is also deleted; therefore, you lose track of the state of its associated resources. Cleaning up resources associated with a deleted stack can be difficult without the state file, especially when those resources are spread across multiple compartments. To avoid difficult cleanup later, we recommend that you release associated resources first by running a destroy job.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the Actions menu, select Delete, and confirm the operation when prompted.

    Note

    You cannot undo the delete stack operation.

    You can also delete a stack from its detail page. Click the name of the stack to display the Stack details page, go to More actions, and then select Delete stack.

Managing Jobs (Console)

To view jobs and job details

You can view name, type, status, and other key information about jobs for a given compartment or stack. You can view name, type, status, and other key information about a given job. You can also access the job's execution plan (represented by the job log), Terraform configuration, and Terraform state, as well as view the variables used in the job.

For configurations stored in a source code control system, such as GitHub or GitLab, job details include the relevant commit identifier.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

    You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. To view job details, click the name of the job you want.

    The Job details page lists the details about the selected job.

  4. To view variables used in the job, click Variables under Resources.
To manage tags for a job

Tags are key/value pairs that you can attach to resources to help you organize and track your resources across compartments. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

    You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the job you want.

    The Job details page lists the details about the selected job.

  4. Click Tags to view or edit existing tags, or click Add tags to add new ones.
To retrieve latest versions of providers

Within the version constraints of your Terraform configuration, retrieve the latest versions available from the configured source of Terraform providers.

Prerequisites:

Upgrade provider versions is available for the following jobs: Plan, Apply, Destroy, Import state, and Run drift detection.

When retrieving latest versions of providers for a job, Resource Manager automatically manages dependency lock files for your stack.

For more information about advanced job options, see To configure advanced job options.

  1. Open the panel for running a job on the stack.
  2. Under Show advanced options, select Upgrade provider versions.
  3. Run the job.
To configure advanced job options
  1. Display the job panel for the type of job that you want to run (Plan, Apply, or Destroy):
    1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
    2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

    3. Click the name of the stack that you want to use.

      The Stack details page is displayed.

    4. Click the option for the job type that you want:

      • Plan
      • Apply
      • Destroy
      • Import state (from More actions)
      • Run drift detection (from More actions)

      The job panel for the selected job type is displayed.

  2. In the job panel, click Show advanced options.
  3. Configure the options that you want.
    Note

    Upgrade provider versions is available for the following jobs: Plan, Apply, Destroy, Import state, and Run drift detection. Advanced job options for debugging, parallel operations, and refreshing resources are available for the following jobs: Plan, Apply, and Destroy.
    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Detailed log level: Verbosity to use for Terraform detailed log content for this job. Default: None (no detailed log content is generated).

      For more information, see Debugging Terraform.

    • Maximum number of parallel operations: Concurrent operations as Terraform walks the graph. Default: 10.

      Use this option to speed up the job.

      Note

      A high value might cause resources to be throttled. For example, consider a Terraform configuration that defines hundreds of compute instances. An Apply job attempts to create as many instances as possible at the same time. In this example, a value of 100 might cause throttling by the Compute service.

    • Refresh resource states before checking for differences: Fetch the latest state of stack infrastructure before running the job. Default: Enabled.

      Use this option to refresh the state first. For example, consider using this option with an Apply job to be run on existing infrastructure that was manually updated.

      Note

      Refreshing the state can affect performance. Consider disabling if the configuration includes several resources.

    • Optionally tag the job.
  4. Follow the rest of the workflow for the job type that you selected.

    The job runs using your configured options.

To cancel a job

You can cancel a job that is running.

  1. If you need to display the detail page for the job you want to cancel, then do the following:
    1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

      You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

    2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

    3. Click the name of the job that you want to cancel.

      The detail page for the job is displayed.

  2. On the detail page, click Cancel job.

    The Cancel job dialog box is displayed.

  3. If the job is for Import state, Apply, or Destroy, then select the option you want:

    • Cancel job

      Resource Manager attempts to cancel the job gracefully. Internally, the running Terraform process signals the child processes to terminate. The job might execute partially depending on the responses of the child processes, even though the ultimate job status is Canceled.

    • Force the job to cancel now

      Note

      Forcing a job to cancel might cause a mismatch between the state file and the actual resource states.
  4. Click Yes, cancel job.

To generate an execution plan (run a plan job)

Running a plan job parses your Terraform configuration and converts it into an execution plan listing resources and actions that will result when an apply job is run. For configurations stored in a source code control system, such as GitHub or GitLab, the job uses the most recent commit. We recommend generating an execution plan before running an apply job.

Note

A job might fail because of a downstream service issue. For example, an Apply job that is intended to create 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.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack that you want to use.

    The Stack details page is displayed.

  4. Click Plan.

  5. (Optional) In the Plan panel, review the plan job Name and update it if needed.

  6. (Optional) Configure advanced options
    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Detailed log level: Verbosity to use for Terraform detailed log content for this job. Default: None (no detailed log content is generated).

      For more information, see Debugging Terraform.

    • Maximum number of parallel operations: Concurrent operations as Terraform walks the graph. Default: 10.

      Use this option to speed up the job.

      Note

      A high value might cause resources to be throttled. For example, consider a Terraform configuration that defines hundreds of compute instances. An Apply job attempts to create as many instances as possible at the same time. In this example, a value of 100 might cause throttling by the Compute service.

    • Refresh resource states before checking for differences: Fetch the latest state of stack infrastructure before running the job. Default: Enabled.

      Use this option to refresh the state first. For example, consider using this option with an Apply job to be run on existing infrastructure that was manually updated.

      Note

      Refreshing the state can affect performance. Consider disabling if the configuration includes several resources.

    • Optionally tag the job.
  7. In the Plan panel, click Plan.

    The new plan job is listed under Jobs, with an initial state of Accepted. Soon the status changes to In progress. When the job is complete, you can review the execution plan or download the job information.

To view the job log
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

    You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the plan job that you ran.

  4. On the Job details page, under Resources, click Logs.

    For plan jobs, the log file is the execution plan. View the log file for the plan job and note the "message" fields in the sequence of log entries of the log file. These values represent the sequence of operations specified in your configuration.

    You can also download the job information.

To update the configuration for a stack
Important

Ensure that your Terraform configuration file is valid. See Authoring Configurations and Terraform Configurations for Resource Manager.
Note

As an alternative to these steps, edit the generated Terraform configuration file in Code Editor. For more information, see Editing Configurations Using Code Editor.

If your configuration is stored in a source code control system, such as GitHub or GitLab, then commit your changes there. The most recent commit is used when you run jobs on the stack.

If your configuration is stored in a bucket, you cannot change the bucket in your existing stack, but you can change the contents of the bucket. The most recent contents of the bucket are used when you run jobs on the stack.

For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

  1. If you are only changing settings for a configuration source provider, or Object Storage bucket originally set up for this stack, then skip this step.

    Otherwise, ensure you have your revised Terraform configuration (.zip file or folder) ready for upload.

    To edit a Terraform configuration that was generated from a template or existing compartment using resource discovery, first download the configuration. Then use the edited configuration .zip file for the update.

  2. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  3. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  4. Click the name of the stack that you want to update.

    The Stack details page is displayed.

  5. In the Stack information tab, next to Terraform configuration, click Upload.

  6. In the Edit stack dialog, under Stack configuration, do one of the following:

    The dialog box is populated with information contained in the Terraform configuration.

  7. Click Next as needed.

  8. To automatically provision resources when the stack is updated, select Run apply.

    The Run apply option is displayed on the Review page. Click Review on the left to see it.

  9. Click Save changes.

    The stack detail page for the edited stack appears.

    If Run apply was selected, then Resource Manager runs the apply action on the updated stack.

    Otherwise, consider running the Plan action on the updated stack, using your revised configuration.

To download job information

You can download files associated with jobs: Terraform configurations, Terraform states, and logs, including detailed Terraform log files.

  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

    You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the job you want.

    The Job details page appears.

    You can view the log by clicking Logs under Resources.

    You can view the state of your resources (for relevant jobs) by clicking View state under Resources. Optionally select Show changes in this version.

  4. Download the job information you want:

    To download this job-associated file Click
    Terraform configuration (.zip file)

    Download Terraform configuration

    Note: As an alternative to these steps, edit the generated Terraform configuration file in Code Editor. For more information, see Editing Configurations Using Code Editor.

    Terraform state (.json file) Download Terraform state
    Logs (.txt file) Download logs (Logs section under Resources)
    Detailed log file (.log file)* Download detailed log file (in the Job information tab, to the right of Detailed log level)
    Plan output (binary or .json file) Download Terraform plan and then select the file format option you want

    *No detailed log file is generated for the job unless a detailed log file level is selected. For instructions, see To configure advanced job options

To run an apply job

When you run an apply job for a stack, Terraform creates the resources and executes the actions defined in your Terraform configuration. For configurations stored in a source code control system, such as GitHub or GitLab, the job uses the most recent commit. The time required to complete an apply job depends on the number and type of cloud resources to be created.

Note

A job might fail because of a downstream service issue. For example, an Apply job that is intended to create 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.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack that you want to use.

    The Stack details page is displayed.

  4. Click Apply.

  5. (Optional) In the Apply panel, review the apply job Name and other settings and update if needed.

  6. (Optional) For Apply job plan resolution, select the name of the latest generated plan job.

    Only the latest generated plan job is available. If no plan job has been generated for this stack, then only the default value is available (Automatically approve). For more information about Automatically approve, see Auto-Approve Option for Terraform Apply Command.

  7. (Optional) Configure advanced options
    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Detailed log level: Verbosity to use for Terraform detailed log content for this job. Default: None (no detailed log content is generated).

      For more information, see Debugging Terraform.

    • Maximum number of parallel operations: Concurrent operations as Terraform walks the graph. Default: 10.

      Use this option to speed up the job.

      Note

      A high value might cause resources to be throttled. For example, consider a Terraform configuration that defines hundreds of compute instances. An Apply job attempts to create as many instances as possible at the same time. In this example, a value of 100 might cause throttling by the Compute service.

    • Refresh resource states before checking for differences: Fetch the latest state of stack infrastructure before running the job. Default: Enabled.

      Use this option to refresh the state first. For example, consider using this option with an Apply job to be run on existing infrastructure that was manually updated.

      Note

      Refreshing the state can affect performance. Consider disabling if the configuration includes several resources.

    • Optionally tag the job.
  8. In the Apply panel, click Apply.

    The new apply job is listed under Jobs. Monitor its status: Succeeded indicates that the job has completed. While the job runs, or after it completes, you can download its log file.

  9. To view the Terraform state file (shows the state of your resources after running the job), click the name of the apply job and then click View state under Resources.

To view the state of a job
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Jobs.

    You can also access jobs from a stack detail page. Click Stacks and then click the name of the stack you want.

  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the job you want.

  4. On the Job details page, click View state under Resources.

    Optionally select Show changes in this version.

To import an existing Terraform state file (run an import job)

You can import state files for existing resources already managed by Terraform.

Note

A job might fail because of a downstream service issue. For example, an Apply job that is intended to create 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.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack that you want to use.

    The Stack details page appears.

  4. Go to More actions and select Import state.

  5. (Optional) In the Import panel, review the job Name and update it if needed. Avoid entering confidential information.

  6. In the Import panel, add your Terraform state file, either by dragging and dropping it onto the dialog's control, or by clicking Browse and navigating to the file location.

  7. (Optional) Configure advanced options:

    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Optionally tag the job.
  8. Click Import.

To release a stack's resources (run a destroy job)

Run a destroy job to tear down the resources and clean up the tenancy.

Note

  • We recommend running a destroy job before deleting a stack to release associated resources first. When you delete a stack, its associated state file is also deleted; therefore, you lose track of the state of its associated resources. Cleaning up resources associated with a deleted stack can be difficult without the state file, especially when those resources are spread across multiple compartments. To avoid difficult cleanup later, we recommend that you release associated resources first by running a destroy job.

    Data cannot be recovered from destroyed resources.

  • A job might fail because of a downstream service issue. For example, an Apply job that is intended to create 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.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.
  2. Choose a compartment that you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the stack that you want to use.

    The Stack details page is displayed.

  4. Click Destroy.

  5. (Optional) In the Destroy panel, review the job Name and update it if needed. Avoid entering confidential information.

  6. (Optional) Configure advanced options
    • Upgrade provider versions (stack must be Terraform 0.14 and later; older stacks must be upgraded to use Terraform Registry): Retrieves the latest versions available from the configured source of Terraform providers.

      Required if provider versions in the Terraform configuration changed since the last time a job was run on the stack. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration.

    • Detailed log level: Verbosity to use for Terraform detailed log content for this job. Default: None (no detailed log content is generated).

      For more information, see Debugging Terraform.

    • Maximum number of parallel operations: Concurrent operations as Terraform walks the graph. Default: 10.

      Use this option to speed up the job.

      Note

      A high value might cause resources to be throttled. For example, consider a Terraform configuration that defines hundreds of compute instances. An Apply job attempts to create as many instances as possible at the same time. In this example, a value of 100 might cause throttling by the Compute service.

    • Refresh resource states before checking for differences: Fetch the latest state of stack infrastructure before running the job. Default: Enabled.

      Use this option to refresh the state first. For example, consider using this option with an Apply job to be run on existing infrastructure that was manually updated.

      Note

      Refreshing the state can affect performance. Consider disabling if the configuration includes several resources.

    • Optionally tag the job.
  7. In the Destroy panel, click Destroy again to confirm your action.

    You can monitor the status and review the results of a destroy job by viewing the state or the logs.

  8. To view the Terraform state file (shows the state of your resources after running the job), click the name of the job to display the Job details page, then click View state under Resources.

    Optionally select Show changes in this version.

  9. To view the logs for the job, click the name of the job to display the Job details page, then click Logs under Resources.

Note

You can recreate destroyed resources by running an apply job. Recreated resources have different OCIDs and other metadata.
To recreate a stack's destroyed resources

Use this procedure to recreate a stack's resources after the resources are destroyed. The new resources differ from previously destroyed resources by their unique OCIDs.

Note

Data cannot be recovered from destroyed resources.

Using the CLI

This section provides basic sample CLI commands for managing stacks and jobs. For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.

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.

Managing Stacks (CLI)

To create a stack from a file (CLI)

Use the command related to your file location. For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

Important

Ensure your Terraform configuration file is valid. See Authoring Configurations and Terraform Configurations for Resource Manager.
To create a stack from a file hosted on a source code control system

Open a command prompt and run oci resource-manager stack create-from-git-provider to create a stack from a file tracked with a configuration source provider: 

oci resource-manager stack create-from-git-provider --compartment-id <compartment_OCID> --config-source-configuration-source-provider-id <configuration_source_provider_OCID> --config-source-repository-url <repository_url> --config-source-branch-name <branch_name> --display-name "<friendly_name>" --description "<description>" --terraform-version "<version>" --variables <var_file_path> --working-directory "<directory>"
Note

You can return later to update stack settings or add variables after you have created the stack.

For example: 

oci resource-manager stack create-from-git-provider --compartment-id ocid1.tenancy.oc1..uniqueid --config-source-configuration-source-provider-id ocid.ormconfigsourceprovider.oc1..uniqueid --config-source-repository-url https://github.com/user/repo.git --config-source-branch-name mybranch --display-name "My Stack from Git" --description "My Test" --variables file://variables.json --working-directory ""
To create a stack from an uploaded file

This section describes how to create a stack from an uploaded configuration file (.zip).

Note

You can also create stacksfrom configuration files stored in source code control systems, such as Git, and from templates.

On Windows, be sure the .zip file and variables.json files are in the same directory from which you're running the CLI. The CLI currently has a limitation on Windows that prevents correct handling of the files if either one is in a subdirectory.

Open a command prompt and run oci resource-manager stack create to create a stack: 

oci resource-manager stack create --compartment-id <compartment_OCID> --config-source <config_file_name> --variables <var_file_path> --display-name "<friendly_name>" --description "<description>" --working-directory ""
Note

You can return later to update stack settings or add variables after you have created the stack.

For example: 

oci resource-manager stack create --compartment-id ocid1.tenancy.oc1..uniqueid --config-source vcn.zip --variables file://variables.json --display-name "My Example Stack" --description "My Tutorial to Create a VCN" --working-directory ""
Example response
{
  "data": {
    config-source": 
    {
      "working-directory": null,
      "config-source-type": "ZIP_UPLOAD"
    },
    "defined-tags": {},
    "description": "My Tutorial to Create a VCN",
    "display-name": "My Example Stack",
    "freeform-tags": {},
    "id": "ocid1.ormstack.oc1..uniqueid",
    "lifecycle-state": "ACTIVE",
    "time-created": "2019-04-03T18:26:56.299000+00:00",
    "variables": 
    {
      "compartment_ocid": "ocid1.compartment.oc1..uniqueid", 
      "region": "us-phoenix-1"
    }
  }
}
To create a stack from a Terraform configuration in an Object Storage bucket

Open a command prompt and run oci resource-manager stack create-from-object-storage to create a stack from a Terraform configuration stored in an Object Storage bucket:

oci resource-manager stack create-from-object-storage --compartment-id <compartment_OCID> --config-source-namespace <bucket_namespace> --config-source-bucket-name <bucket_name> --config-source-region <bucket_region> --display-name "<friendly_name>"  --description "<description>" --variables <var_file_path>
Note

You can return later to update stack settings or add variables after you have created the stack.

For example:

oci resource-manager stack create-from-object-storage 
--compartment-id ocid1.tenancy.oc1..uniqueid 
--config-source-namespace MyNamespace
--config-source-bucket-name MyBucket
--config-source-region PHX
--display-name "My Stack from Object Storage" 
--description "My Test" 
--variables file://variables.json
To copy a stack

Open a command prompt and run oci resource-manager stack copy to copy a stack to another compartment:

oci resource-manager stack copy --stack-id <stack_OCID> --destination-compartment-id <compartment_OCID> --destination-region <region> --display-name "<friendly_name>" --description "<description>" --variables <var_file_path> --access-token <token> --freeform-tags <freeform-tags> --defined-tags <defined-tags>

Use options to specify the following fields of the copied stack:

  • destination compartment
  • destination region
    Note

    Any configuration source provider used by the stack is copied to the specified destination region and the source compartment.
  • display name (default when not specified: copy-from-<source_region>-<originalStackDisplayName>)
  • description
  • variables (existing variable values are retained unless explicitly overwritten)
  • tags, free-form and defined (existing tag values are retained unless explicitly overwritten)
  • access token for the stack's configuration source provider (required when copying to a different region)

For a complete list of flags and options available for CLI commands, see CLI Help.

Examples
Create a copy of a stack in the current compartment and region
oci resource-manager stack copy --stack-id <stack_OCID>
Copy a stack to a different compartment
oci resource-manager stack copy --stack-id <stack_OCID> --destination-compartment-id <compartment_OCID>
Copy a stack that uses CI/CD to a different region

In this example, the stack uses a configuration source provider specifying GitHub, which helps achieve continuous integration and continuous delivery (CI/CD). The GitHub access token is required when copying a stack to another region.

oci resource-manager stack copy --stack-id <stack_OCID> --destination-region <region> --access-token <token>
To discover resources (create a stack from a compartment)

Open a command prompt and run oci resource-manager stack create-from-compartment to create a stack from the specified compartment and region:

oci resource-manager stack create-from-compartment --config-source-compartment-id <source_compartment_OCID> --config-source-region <source_region> --config-source-services-to-discover [<services>] –-compartment-id <compartment_OCID> --terraform-version <version --display-name "<friendly_name>" --description "<description>" 

For example (discovers supported resources from the core and database services; the source compartment is not a root compartment):

oci resource-manager stack create-from-compartment --config-source-compartment-id ocid1.tenancy.oc1..uniqueid1 --config-source-region PHX --config-source-services-to-discover [core,database] –-compartment-id ocid1.tenancy.oc1..uniqueid2 --terraform-version 0.13.X --display-name "Stack From Compartment ABC" --description "List of Resources to Duplicate"
Example response
{
  "data": {
    "config-source": {
      "config-source-type": "COMPARTMENT_CONFIG_SOURCE"
    },
    "defined-tags": {},
    "display-name": "Stack from Compartment ABC",
    "freeform-tags": {},
    "id": "ocid1.ormstack.oc1..uniqueid",
    "lifecycle-state": "CREATING",
    "time-created": "2019-04-03T18:26:56.299000+00:00",
    "variables": {
      "compartment_ocid": "ocid1.compartment.oc1..uniqueid1", 
      "region": "us-phoenix-1"
    }
  }
}
{
  "data": {
    "compartment-id": "ocid1.compartment.oc1..uniqueid2",
    "config-source": {
      "compartment-id": "ocid1.compartment.oc1..uniqueid1",
      "config-source-type": "COMPARTMENT_CONFIG_SOURCE",
      "region": "PHX",
      "working-directory": null
    },
    "defined-tags": {},
    "description": "List of Resources to Duplicate",
    "display-name": "Stack From Compartment ABC",
    "freeform-tags": {},
    "id": "ocid1.ormstack.oc1.phx.uniqueid",
    "lifecycle-state": "CREATING",
    "stack-drift-status": "NOT_CHECKED",
    "terraform-version": "0.12.x",
    "time-created": "2020-06-01T18:25:56.102000+00:00",
    "time-drift-last-checked": null,
    "variables": {}
  },
  "etag": "009010cb57f5162655c6a34f5ef8834f204a734df81e4baa696a7d830488ea25",
  "opc-work-request-id": "ocid1.ormworkrequest.oc1.phx.uniqueid"
}
To list resources for discovery

This section describes how to determine which services are supported for resource discovery from a given compartment OCID.

When you create a stack from a compartment, the stack represents all supported resources in the entire compartment, at the appropriate scope. If you select the root compartment for your tenancy, then the scope is the tenancy level, such as users and groups. If you select a non-root compartment, then the scope is compartment level, such as Compute instances.

Open a command prompt and run oci resource-manager stack list-resource-discovery-services to retrieve a list of services supported for resource discovery (the compartment OCID is used for authorization only):

oci resource-manager stack list-resource-discovery-services --compartment-id <compartment_OCID>
To list stacks in a compartment

Open a command prompt and run oci resource-manager stack list to list the stacks in a compartment: 

oci resource-manager stack list –-compartment-id <compartment_OCID>
To list full details of a stack

Open a command prompt and run oci resource-manager stack get to list the details for the specified stack: 

oci resource-manager stack get –-stack-id <stack_OCID>
To detect drift for a stack

Open a command prompt and run oci resource-manager stack get to detect drift for the specified stack: 

oci resource-manager stack detect-drift --stack-id <stack_OCID>
To list resource details in the stack's last drift detection report

Open a command prompt and run oci resource-manager stack get to list the resource details for the last drift detection report of a specified stack: 

oci resource-manager stack list-resource-drift-details --stack-id <stack_OCID>
To delete a stack
Note

Associated resources persist after stack deletion. When you delete a stack, its associated state file is also deleted; therefore, you lose track of the state of its associated resources. Cleaning up resources associated with a deleted stack can be difficult without the state file, especially when those resources are spread across multiple compartments. To avoid difficult cleanup later, we recommend that you release associated resources first by running a destroy job.

Open a command prompt and run oci resource-manager stack delete to delete the specified stack: 

oci resource-manager stack delete –-stack-id <stack_OCID>

Managing Jobs (CLI)

To generate an execution plan (run a plan job)

Open a command prompt and run oci resource-manager job create-plan-job to run a plan job on the specified stack (--display-name is optional): 

oci resource-manager job create-plan-job –-stack-id <stack_OCID> --display-name "<friendly_name>"

Depending on the complexity of the configuration, the plan job can take several minutes to complete. When the job is complete, make sure you review the generated execution plan before running an apply job.

To check the current state of the plan job

Open a command prompt and run oci resource-manager job get to retrieve information about the job: 

oci resource-manager job get –-job-id <plan_job_OCID>
Lifecycle states
Possible values for lifecycle-state:
  • ACCEPTED: The job is queued for execution.
  • IN_PROGRESS: The job is running.
  • FAILED: The job has failed and stopped running.
  • SUCCEEDED: The job has completed successfully.
  • CANCELING: The job has been notified to cancel, but has not yet stopped running.
  • CANCELED: The job was canceled and has stopped running.
Example response

This example shows ACCEPTED for lifecycle-state.

{
  "data": 
  {
    "compartment-id": " ocid1.compartment.oc1..uniqueid",
    "defined-tags": null,
    "display-name": "Example Plan Job",
    "freeform-tags": {},
    "id": "ocid1.ormjob.oc1..uniqueid",
    "lifecycle-state": "ACCEPTED",
    "operation": "PLAN",
    "jobOperationDetails": 
    {
      "operation": "PLAN"
    },
    "stack-id": " ocid1.ormstack.oc1..uniqueid",
    "time-created": "2019-03-09T20:52:13.922000+00:00",
    "time-finished": null,
    "variables": 
    {
      "compartment_ocid": "ocid1.compartment.oc1..uniqueid",
      "region": "us-phoenix-1"
    }
  }
}
To review an execution plan (view the log for a plan job)

Review the execution plan to ensure that it accurately reflects your intentions. View the log file and note the "message" fields in the sequence of log entries of the log file. These values represent the sequence of operations specified in your configuration.

Open a command prompt and run oci resource-manager job get-job-logs to view the log file for the specified job: 

oci resource-manager job get-job-logs --job-id <plan_job_OCID>

If you see problems or errors and wish to make changes, then update the appropriate configuration file (.tf file), update the stack to use the revised configuration, generate a new execution plan, and then review the new execution plan.

Example response

The command returns JSON objects that describe log entries. Each object has a message member with a property that displays one line of the execution plan. In the example shown below, the plan creates a single virtual cloud network (VCN); the remaining members show details about the VCN.

...
                {
                "level": "INFO",
                "message": "Terraform will perform the following actions:",
                "timestamp": "2018-05-24T00:57:14.170000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "",
                "timestamp": "2018-05-24T00:57:14.170000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "+ oci_core_virtual_network.vcn1",
                "timestamp": "2018-05-24T00:57:14.170000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "id: <computed>",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "cidr_block:  \"10.0.0.0/16\",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "compartment_id:  \"ocid1.tenancy.oc1..exampleaqnpcpfqfmrf6dw5gcew7yqpirvarueirj2mv4jzn5goejsxma\",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "default_dhcp_options_id:  <computed_value>",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "      default_route_table_id: <computed_value>",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                {
                "level": "INFO",
                "message": "      default_security_list_id: <computed_value>",
                "timestamp": "2018-05-24T00:57:14.172000+00:00",
                "type": "TERRAFORM_CONSOLE"
                },
                ...
              
To update an execution plan (update an uploaded configuration for a stack)
Note

These instructions don't apply to configurations stored in source code control systems. For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

To edit a Terraform configuration that was generated from a template or existing compartment using resource discovery, first download the configuration. Then use the edited configuration .zip file for the update.

Open a command prompt and run oci resource-manager stack update with the option --config-source to update the Terraform configuration for the specified stack: 

oci resource-manager stack update --stack-id <stack_OCID> --config-source <config_file_name>

After updating the stack, regenerate and review an execution plan (run a new plan job and then view the log file).

To run an apply job

To check the current state of the apply job

Open a command prompt and run oci resource-manager job create-apply-job with the relevant value for --execution-plan-strategy (examples use --display-name, which is optional): 

  • To specify a plan job ("apply" an execution plan), use FROM_PLAN_JOB_ID:

    oci resource-manager job create-apply-job --stack-id <stack_OCID> --execution-plan-strategy FROM_PLAN_JOB_ID --execution-plan-job-id <plan_job_OCID> --display-name "Example Apply Job"

    Use this option to "apply" your confirmed execution plan to the stack, execute the instructions, and provision the stack with the specified resources.

  • To automatically approve the apply job (no plan job specified), use AUTO_APPROVED:

    oci resource-manager job create-apply-job --stack-id <stack_OCID> --execution-plan-strategy AUTO_APPROVED --display-name "Example Apply Job"

Depending on the complexity of your execution plan, the operation can take some time. Periodically check the lifecycle state of your apply job to see when it switches from IN_PROGRESS to SUCCEEDED.

To check the current state of the apply job

Open a command prompt and run oci resource-manager job get to retrieve information about the job: 

oci resource-manager job get –-job-id <apply_job_OCID>
Lifecycle states
Possible values for lifecycle-state:
  • ACCEPTED: The job is queued for execution.
  • IN_PROGRESS: The job is running.
  • FAILED: The job has failed and stopped running.
  • SUCCEEDED: The job has completed successfully.
  • CANCELING: The job has been notified to cancel, but has not yet stopped running.
  • CANCELED: The job was canceled and has stopped running.

To confirm existence of newly provisioned resources, inspect resources in the compartment.

To download or view job information

You can download Terraform configurations and Terraform states associated with jobs. You can also view logs associated with jobs.

For configurations stored in a source code control system, such as GitLab, job details include the relevant commit identifier.

To download the configuration for a job

Open a command prompt and run oci resource-manager job get-job-tf-config to download the Terraform configuration of the specified job to the specified file:

oci resource-manager job get-job-tf-config –job-id <job_OCID> --file <output_file_name>
To download the state file for a job

Open a command prompt and run oci resource-manager job get-job-tf-state to download the Terraform state of the specified job to the specified file: 

oci resource-manager job get-job-tf-state --job-id <job_OCID> --file <output_file_name>
Example response for an apply job
{
  "data": 
  {
    "lineage": "57ef4f0c-c8cd-8a32-d45f-d2c40be7b915",
    "modules": 
    [
      {
        "depends_on": [],
        "outputs": {},
        "path": 
        [
          "root"
        ],
        "resources": 
        {
          "oci_core_virtual_network.vcn1": {
          "depends_on": [],
          "deposed": [],
          "primary": 
          {
            "attributes": {
            "cidr_block": "10.0.0.0/16",
            "compartment_id": "ocid1.tenancy.oc1..uniqueid",
            "default_dhcp_options_id": "ocid1.dhcpoptions.oc1.phx.uniqueid",
            "default_route_table_id": "ocid1.routetable.oc1.phx.uniqueid",
            "default_security_list_id": "ocid1.securitylist.oc1.phx.uniqueid",
            "display_name": "My VCN display name",
            "dns_label": "myvcntest",
            "id": "ocid1.vcn.oc1.phx.uniqueid",
            "state": "AVAILABLE",
            "time_created": "2018-05-24 01:13:05.855 +0000 UTC",
            "vcn_domain_name": "myvcntest.oraclevcn.com"
          },
          "id": "ocid1.vcn.oc1.phx.uniqueid",
          "meta": 
          {
            "e2bfb730-ecaa-11e6-8f88-34363bc7c4c0": {
            "create": 300000000000,
            "delete": 300000000000,
            "update": 300000000000
          }
        },
        "tainted": false
      },
      "provider": "provider.oci",
      "type": "oci_core_virtual_network"
          }
        }
      }
    ],
  "serial": 4,
  "terraform_version": "0.11.7",
  "version": 3
}
                }
To download the output of a plan job

Open a command prompt and run oci resource-manager job get-job-tf-plan to download the output of a plan job: 

oci resource-manager job get-job-tf-plan --job-id <job_OCID> --file <output_file_name> --tf-plan-format <binary_or_json>

For example, the following command downloads the output of a plan job in JSON format:

oci resource-manager job get-job-tf-plan --job-id ocid1.ormjob.oc1.phx.<uniqueid> --file tfplan.json --tf-plan-format JSON
To view the log for a job

View the log file and note the "message" fields in the sequence of log entries of the log file. You can view the log file for the specified job as either a paged list of entries or in its raw form.

To view the log as a paged list of entries, open a command prompt and run oci resource-manager job get-job-logs:

oci resource-manager job get-job-logs --job-id <job_OCID>

To view the log in raw form, open a command prompt and run oci resource-manager job get-job-logs-content:

oci resource-manager job get-job-logs-content --job-id <job_OCID>
To import an existing Terraform state file (run an import job)

Open a command prompt and run oci resource-manager x to import an existing state file for resources already managed by Terraform: 

oci resource-manager job create-import-tf-state-job --stack-id stack_id --tf-state-file state_file
To inspect resources in a compartment

Inspecting resources in a compartment allows you to confirm existence of a resource that you provisioned (by running an apply job) or absence of a resource that you released (by running a destroy job).

Open a command prompt and run the CLI command corresponding to the resources you want to inspect.

For example, run oci network vcn list to inspect VCN resources in the specified compartment:

oci network vcn list --compartment-id <compartment_OCID>
To release a stack’s resources (run a destroy job)
Note

We recommend running a destroy job before deleting a stack to release associated resources first. When you delete a stack, its associated state file is also deleted; therefore, you lose track of the state of its associated resources. Cleaning up resources associated with a deleted stack can be difficult without the state file, especially when those resources are spread across multiple compartments. To avoid difficult cleanup later, we recommend that you release associated resources first by running a destroy job.

Open a command prompt and run oci resource-manager job create-destroy-job to tear down and clean up the resources provisioned by the specified stack: 

oci resource-manager job create-destroy-job --stack-id <stack_OCID> --execution-plan-strategy=AUTO_APPROVED

To confirm deletion of the resources, inspect resources in the compartment.

Using the API