I am a few months into working with the official Terraform provider for OCI and my opinion is that Oracle still has a lot of work ahead of them. I honestly don’t understand how some things are as bad as they are. That might sound a bit scathing but let’s remember that Oracle has no native IaC language for OCI… Rather, they claim Terraform as their first-party, fully supported, IaC language of choice. Hence, the following complaint is particularly egregious… simply put, the documentation is terrible. While the bulk of my experience has been with Microsoft’s Azure provider, I have seen and used 3rd party providers from single developers that significantly better documentation than what Oracle has thrown together. I had no idea how good I had it (with Microsoft) until I started having to reference the OCI documentation. I will go ahead and spend time discussing one obvious positive… it exists (congrats). Okay, moving on. Let’s dive in and do a bit of detailed damning…
The most glaring fault in the OCI provider documentation is the low quality of resource examples…
When referencing any given resource in a provider’s documentation, a developer should be able to straight-up copy and paste examples and run them (plan/apply) successfully with minimal know-how or manipulation beyond provider and backend configuration. I get that this might be a high bar to set for the primary documentation of a multi-billion dollar flagship platform’s sole IaC language.. also – YES – I realize that including all of the supporting resources in an example is like top-notch, and not exactly easy to pull off. (thank you Microsoft for doing this for many of your examples.. and don’t you folks also have to document ARM and BICEP as well… and yet -somehow- you find the time…)
However, barring the above standard, resource examples should at a bare minimum be opinionated… i.e. example configuration arguments should be static values. In either a display of ignorance, laziness or, more likely, a high degree of pressure to get something out the door combined with a lack of corporate willingness to provide appropriate resourcing, Oracle has instead just put in variables for all configuration value examples, with zero context or explanation.
To make it painfully clear what I am talking about, here is a decent example from the AWS provider documentation:
GOOD
ami = data.aws_ami.ubuntu.id
instance_type = "t3.micro"
tags = {
Name = "HelloWorld"
}
}
Notice how all configuration values inside of the brackets have statically defined values – this is a blessing for someone who is reading and using the documentation because they have a very clear example of what is expected to go there.
Compare that with a (truncated) example from the OCI documentation:
BAD
#Required
availability_domain = var.instance_availability_domain
compartment_id = var.compartment_id
shape = var.instance_shape
#Optional
#...
}
Notice in the above how every single configuration value is “var.whatever” – this might be how you would have it in an actual deployment but for the purposes of an example it means absolutely nothing. Nowhere does Oracle indicate what any of those variables actually are. This is consistent across every single resource example I have had to reference – to the point where I feel like someone, somewhere, made a conscientious decision to, putting it frankly, ‘do it the wrong way.’ (I actually am second-guessing myself as I am writing this wondering if I have somehow missed the “correct” documentation…)
It gets worse though…
The actual written documentation on the configuration items is extremely hit-or-miss.
Take for example the resource “oci_cloud_guard_cloud_guard_configuration” – this has a required configuration item called “status”. Drop down to look at the description for what goes here and you get “Status of Cloud Guard Tenant.” That’s fun… does it take specific values or is it free-form? Is it a bool or a list or, heaven forbid, some obscure map? You can often intuit and guess quite a bit… but again, this is documentation – I shouldn’t have to guess anything.
In the specific case above, it takes one of two very specific strings… which, furthermore, must be in ALL CAPS. How did I figure this out? By referencing their API documentation (which was nearly as vague) and trying several different things until Terraform gave me a detailed error message that told me what values were suitable. I will emphasize what I said earlier that this is, mercifully, at least hit-or-miss. Sometimes you may find a link to additional documentation or, surprisingly, an actual robust explanation right there in the documentation. I will clarify, I am not asking to be taught in-depth OCI cloud concepts or even fundamentals (links, in either case, would at least be nice though) – only to be informed in detail if there are constraints on the inputs in your provider resources and what those constraints are.
How can one who is a new user of the OCI TF provider successfully stumble forward and make progress? Thankfully, on github, there is a really good “Landing Zone” quick-start terraform deployment with lots of modules. Inside of that deployment is a treasure trove of sub-modules and examples, that, with enough patience and tracing of variables, a new OCI IaC developer (Hi!) can painstakingly piece together to sort out information that isn’t readily available in the documentation. While not precisely on point, to quote a friend “there is always the source code.”
And those are just documentation headaches… I have also ran into bugs and some rather glaring oddities which I didn’t want to spend time writing about today. Enough said for now; I get that OCI is a new, evolving, and vastly immature cloud compared to AWS, Azure, and GCP. But the ops person in me looks at sloppiness like this and wonders what else on the OCI platform has been given such minimal and/or misguided attention and then released as production ready.
Please Oracle, fix this, for all our sakes. I get documentation isn’t easy or glamorous but that really shouldn’t matter because it’s fundamental.