terraform-provider-oci: driving Oracle Cloud Infrastructure from Terraform

A registry-published provider with a large example set

The provider is the Terraform provider for Oracle Cloud Infrastructure, and the first line of the README states that the OCI Terraform Provider is now available for automatic download through the Terraform Provider Registry. That line matters more than it sounds, because it describes the distribution model. A provider downloaded automatically is one the Terraform CLI fetches, verifies and caches on its own, so a team does not maintain a plugin directory or a mirror. The provider documentation, a setup guide for the version 3 upgrade, an examples tree, the OCI customer forums and the GitHub issue tracker are all linked from the top of the README. The examples directory in the repository is organised by service, with separate folders for things like aiAnomalyDetection, aiDocument, aiLanguage, aiVision, api_gateway, apiaccesscontrol, apm, audit, autoscaling, bastion, batch, certificatesManagement and more, and the list runs to dozens of entries.

Two plugin SDKs in the dependency tree

The module file shows the technical shape of the provider, and the most interesting entry is that both Terraform plugin generations are present. The newer terraform-plugin-framework at 1.16.1 comes with its validators package and terraform-plugin-go for the protocol layer, while the older terraform-plugin-sdk/v2 is still there at 2.38.1, and terraform-plugin-mux at 0.21.0 sits alongside. Mux is the piece that makes sense of it, because it lets a single provider binary serve resources implemented under either framework, which is how a provider of this size migrates incrementally rather than in one release. Alongside those are the standard HashiCorp support libraries: go-cty for value conversion, go-version for version comparison, hcl2 for configuration parsing, and terraform-exec and terraform-json for driving Terraform and reading its output during testing. The Oracle SDK itself, oci-go-sdk/v65, is pinned at v65.127.0, so the provider tracks the API surface of the OCI client library closely.

The build is a make target and a GOPATH checkout

Building the provider from source follows the older Go layout that the instructions describe. You clone the repository into a directory under your GOPATH, under a github.com/terraform-providers path, then change into the provider directory and run the build target.

$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
$ git clone [email protected]:terraform-providers/terraform-provider-oci

$ cd $GOPATH/src/terraform-provider-oci
$ make build

The README notes that the provider binary outputs to your $GOPATH/bin directory and that this has to be on your $PATH, which is the classic pre-modules Go workflow and is still how the build instructions are written. The build file itself is named GNUmakefile rather than Makefile, which is a detail that matters on systems where another Makefile is present. There is also a .goreleaser.yml, a .go-version file, a .travis.yml alongside wercker.yml for continuous integration, and a terraform-registry-manifest.json, which is the file the registry uses to publish the provider.

Acceptance tests hit live Oracle Cloud APIs

The test target is make testacc, and the note attached to it is the one to read before running it.

$ make testacc

The tests run against live OCI service APIs, so you need to configure environment variables with valid credentials as the documentation describes. That is the honest description of how a provider of this size is tested: the unit tests can check the schema and the plan logic, but the create, read, update and delete cycle for a real OCI resource is the only way to know that the provider matches the API, and there is no mock for that. The practical consequence for a contributor or an integrator is that running the acceptance suite creates real resources in a real tenancy and costs real money, and the credentials have to be scoped carefully. The repository also carries an httpreplay directory, a coverage directory and a codecov.yml, which suggests some part of the suite is recorded and replayed rather than executed live.

The examples directory is the real documentation

The examples tree is the most useful thing in the repository for anyone configuring the provider, and its structure is telling. Each service gets a folder rather than one giant directory, which means you can read the configuration for the service you are about to use without wading through the rest. The set of folders listed in the repository shows the breadth of what the provider covers: the AI services, the API platform, analytics, announcements, API gateway, access control, application management, audit, autoscaling, bastion, batch, big data services, blockchain, budget, capacity management and certificate management are all present, alongside the always_free example. That last one tells you something about the intended audience, since a provider that ships an example for the free tier is a provider aiming at people evaluating the platform. There is an examples/README.md at the top and a website directory for the documentation.

Requirements and the version 3 upgrade

The stated requirements are Terraform v0.12.31 or greater and Go 1.26.6, which is described as recommended rather than required. The Terraform floor is the old SDK-style requirement rather than a modern one, but the dependency on terraform-plugin-framework at 1.16.1 means the provider is built for the current plugin protocol as well, so the practical requirement is looser than the README's floor suggests. The setup guide the README links is explicitly the version 3 upgrade guide, which tells you that the provider has been through a major rewrite and that upgrading configurations from an older provider is not free. The troubleshooting guide has a section on verbose logging for the OCI provider, which is where to look when a plan looks correct and the apply does something else, since the provider's own logs carry the API calls.

Where the OCI provider is the wrong choice

Four limits apply. It is enormous, and an enormous provider has an enormous surface: every OCI service you can reach is a potential source of behaviour you have to understand, and the version numbering moves fast, with v9.10.0, v9.9.0 and v9.8.0 published in the space of a fortnight, so an unpinned provider in CI is a moving target. It depends on the Oracle Cloud API being reachable from wherever Terraform runs, which in a locked-down network means the provider needs egress to Oracle's endpoints and a credentials path that works from a CI runner. The acceptance testing model means the provider's own quality assurance costs money in someone's account, which shapes how quickly a new service gets supported. And it is tied to OCI, so anything that would need to span two clouds means running two providers with two sets of credentials, two sets of state and two different retry and timeout behaviours.

Editorial conclusion

Use terraform-provider-oci when you want Oracle Cloud resources managed declaratively alongside the rest of your infrastructure, since the provider covers the service catalogue broadly and ships with a setup guide for the version 3 upgrade path and per-service examples. Do not expect a small provider, since it is a large surface with both the legacy plugin SDK and the newer plugin framework in the dependency tree, and the version numbering moves fast at a nine to ten minor release cadence. Verify first that your OCI tenancy and its API keys are configured as the provider expects, that the acceptance tests you are asked to run against live services will not create real billable resources, and that the provider version you pin matches the Terraform version your team uses, since the plugin SDK dependency is still on the v2 line.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. oracle/terraform-provider-oci on GitHub
3. Project website
4. README
5. Releases