Terraform on OCI Getting Started

Terraform is the most common way to define an Oracle Cloud Infrastructure estate as code, and for good reason: it lets you describe the infrastructure you want in plain definitions, and it makes reality match the description. But Terraform is easy to start and easy to use badly, and an estate that adopts it without the right habits can end up with tangled state, drifting environments, and changes nobody can predict. This guide is a practical introduction that covers how Terraform works on OCI and the habits that keep it safe as the estate grows.

It is part of our DevOps and automation on OCI cluster, and it pairs with our guides on the OCI Resource Manager, which runs Terraform as a managed service, and infrastructure as code patterns on OCI, which covers how to structure larger estates.

How Terraform works

Terraform works on a simple and powerful idea: you write definitions describing the resources you want, the networks, the compute, the databases, the policies, and Terraform compares that desired state with what actually exists and works out the changes needed to make them match. You do not tell Terraform how to create each thing step by step; you tell it what you want, and it figures out the steps. This declarative model is what makes Terraform reproducible, because the same definitions always produce the same estate.

The cycle has three core actions. You write or change the definitions, you run a plan to see exactly what Terraform intends to do, and you apply to make it happen. The plan step is the safety mechanism that matters most, because it shows you the consequences of a change before anything is altered, and reading the plan carefully before applying is the single most important habit in using Terraform well.

The OCI provider

Terraform talks to OCI through the OCI provider, a component that translates Terraform's instructions into actions against the OCI API. The provider supports the full range of OCI resources, which means almost everything in the estate can be defined and managed in Terraform, from the foundational networking through compute, databases, storage, and identity policies. Getting the provider configured with the right credentials and the right permissions is the first practical step, and it should use credentials scoped to what the automation needs rather than broad administrative access.

Because the provider covers so much of OCI, it is possible to define an entire estate in Terraform, which is the goal for a DevOps operating model. Starting smaller is sensible, defining one part of the estate and growing the coverage as confidence builds, but the destination is an estate where the Terraform definitions are the source of truth and the running infrastructure simply reflects them.

State is the thing to get right

Terraform keeps track of what it manages in a state file, a record of the resources it has created and their current configuration. State is how Terraform knows the difference between what exists and what you want, and getting state management right is the difference between Terraform that scales and Terraform that becomes a source of pain. The two cardinal rules are that state must be stored somewhere shared and safe, not on one person's laptop, and that state must be locked during changes so two people cannot apply at once.

On OCI, state is commonly held in object storage with locking, or managed entirely by the Resource Manager, which handles state and locking for you. For any estate worked on by more than one person, shared and locked state is not optional, and the most common Terraform disasters trace back to state that was local, unshared, or unlocked. Our Resource Manager guide covers the managed option that removes much of this burden.

Structure for change, not just creation

It is easy to write Terraform that creates an estate and far harder to write Terraform that an estate can live with for years, and the difference is structure. Definitions should be organized so that related resources sit together, so that environments share common definitions rather than duplicating them, and so that a change to one part does not require touching everything. Reusable modules, which package a piece of infrastructure into something that can be used repeatedly with different inputs, are the main tool for this, and they keep a growing estate manageable rather than sprawling.

The temptation early on is to put everything in one place because it works, but that approach does not survive growth, and an estate defined as one giant undifferentiated set of definitions becomes slow to plan, risky to change, and hard to reason about. Structuring for change from the start, even when the estate is small, pays off as it grows. We cover this in depth in our infrastructure as code patterns on OCI guide.

Guard against drift

Drift is what happens when the real estate stops matching the Terraform definitions, usually because someone made a change by hand in the console. Drift undermines the whole value of infrastructure as code, because once the definitions and reality disagree, the definitions can no longer be trusted as the source of truth and applying them might undo a manual change that mattered. The defence against drift is discipline: changes go through Terraform, not the console, and the console is for looking, not for changing.

This discipline is cultural as much as technical, and it is the habit that most distinguishes an estate that gets value from Terraform from one that fights it. Where manual changes are sometimes unavoidable, they should be brought back into the definitions promptly so the source of truth stays true. An estate that holds this discipline keeps its definitions trustworthy, and trustworthy definitions are the entire point of the exercise.

Put Terraform in a pipeline

Running Terraform from a person's laptop works for learning but not for an estate, because it concentrates the ability to change production in individuals and skips the review and testing that make change safe. The mature pattern is to run Terraform through a pipeline, so that a change is committed, reviewed, planned automatically, and applied only after approval, with the state managed centrally. This brings Terraform into the same disciplined path as every other change, which is the heart of the DevOps model.

OCI's Resource Manager and DevOps service both support this, and external CI and CD tools integrate with OCI as well, so there are several good ways to put Terraform in a pipeline. The choice matters less than the principle, which is that production infrastructure changes should flow through an automated, reviewed path rather than from individual command lines. Our OCI DevOps service pipelines guide covers how to build that path, and our DevOps and IaC solution is where we help teams establish these foundations properly. Terraform learned well and used with discipline is the bedrock of a fast, reliable OCI estate, and the habits in this guide are what keep it that way as the estate grows.