Skip to content

Commit 7d931cf

Browse files
author
ccushing
committed
Migrate oci docs to guides
1 parent ec6a169 commit 7d931cf

File tree

5 files changed

+292
-5
lines changed

5 files changed

+292
-5
lines changed

‎GNUmakefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ GOFMT_FILES?=$$(find . -name '*.go' |grep -v vendor)
33
PKG_NAME=oci
44
WEBSITE_REPO=github.com/hashicorp/terraform-website
55

6-
prefix := $(if $(debug),TF_LOG=DEBUG DEBUG=true OCI_GO_SDK_DEBUG=1, )
6+
prefix := $(if $(debug),TF_LOG=DEBUG OCI_GO_SDK_DEBUG=1, )
77
timeout := $(if $(timeout), $(timeout), 120m)
88
run_regex := $(if $(run), -run $(run), )
99
skip_goimports_check_flag := $(if $(skip_goimports_check), -s, )

‎README.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,20 @@ $ make build
4040
```
4141

4242

43-
Using the provider
43+
Using the Provider
4444
----------------------
45-
If you're building the provider, follow the instructions to [install it as a plugin.](https://www.terraform.io/docs/plugins/basics.html#installing-a-plugin) After placing it into your plugins directory, run `terraform init` to initialize it.
45+
If you're building the provider, follow the instructions to [install it as a plugin.](https://www.terraform.io/docs/plugins/basics.html#installing-a-plugin)
46+
After placing it into your plugins directory, run `terraform init` to initialize it and begin using Terraform with the Oracle Cloud Infrastructure provider.
47+
48+
49+
Troubleshooting the Provider
50+
----------------------
51+
To get verbose console output when the provider is running, precede your Terraform command with the `TF_LOG` and `OCI_GO_SDK_DEBUG` flags:
52+
```sh
53+
TF_LOG=DEBUG OCI_GO_SDK_DEBUG=1 terraform plan
54+
```
55+
56+
The [tf_log](https://www.terraform.io/docs/internals/debugging.html) level and `OCI_GO_SDK_DEBUG` flags can also be set as environment variables.
4657

4758

4859
Developing the Provider

‎website/docs/guides/best_practices.html.markdown‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
layout: "oci"
3+
page_title: "Provider: Oracle Cloud Infrastructure"
4+
sidebar_current: "docs-oci-guide-best_practices"
5+
description: |-
6+
The Oracle Cloud Infrastructure provider. Best Practices
7+
---
8+
9+
## Terraform Provider Best Practices
10+
11+
Following are recommended best practices for writing configurations for the Oracle Cloud Infrastructure Terraform provider.
12+
13+
### Referencing Images
14+
15+
When launching Compute instances, your Terraform configuration should use the same image every time you execute a Terraform Apply command.
16+
17+
To ensure this, specify the image OCID directly, rather than locating it using the `oci_core_image` data source.
18+
This is because the `oci_core_image` data source calls into the ListImages API, whose return values can change over
19+
time as new images are periodically added and older ones deleted. For a list of Oracle-Provided images and their OCIDs,
20+
see [Oracle-Provided Images](https://docs.cloud.oracle.com/iaas/Content/Compute/References/images.htm).
21+
For more information, see the write up in this issue: [Results of oci_core_images will change over time for Oracle-provided images](https://github.com/oracle/terraform-provider-oci/issues/352).
22+
23+
We recommend the following pattern for specifying an image for a given region:
24+
25+
```hcl
26+
variable "image_id" {
27+
type = "map"
28+
default = {
29+
// See https://docs.cloud.oracle.com/iaas/images/
30+
// Oracle-provided image "Oracle-Linux-7.4-2018.02.21-1"
31+
us-phoenix-1 = "ocid1.image.oc1.phx.aaaaaaaaupbfz5f5hdvejulmalhyb6goieolullgkpumorbvxlwkaowglslq"
32+
us-ashburn-1 = "ocid1.image.oc1.iad.aaaaaaaajlw3xfie2t5t52uegyhiq2npx7bqyu4uvi2zyu3w3mqayc2bxmaa"
33+
eu-frankfurt-1 = "ocid1.image.oc1.eu-frankfurt-1.aaaaaaaa7d3fsb6272srnftyi4dphdgfjf6gurxqhmv6ileds7ba3m2gltxq"
34+
uk-london-1 = "ocid1.image.oc1.uk-london-1.aaaaaaaaa6h6gj6v4n56mqrbgnosskq63blyv2752g36zerymy63cfkojiiq"
35+
}
36+
}
37+
```
38+
39+
A Compute instance can use this in the following way:
40+
41+
```hcl
42+
resource "oci_core_instance" "TFInstance" {
43+
image = "${var.image_id[var.region]}"
44+
...
45+
}
46+
```
47+
48+
49+
### Availability Domains
50+
51+
With respect to Availability Domains, we caution against the common pattern of iterating over the results of the `oci_identity_availability_domains` data source, as shown here:
52+
53+
```hcl
54+
// Get all availability domains for the region
55+
data "oci_identity_availability_domains" "ads" {
56+
compartment_id = "${var.tenancy_ocid}"
57+
}
58+
59+
// Then either use it to get a single AD name based on the index:
60+
resource "oci_core_instance" "nat" {
61+
availability_domain = "${lookup(data.oci_identity_availability_domains.ads.availability_domains[var.nat_instance_ad],"name")}"
62+
...
63+
}
64+
65+
// Or iterate through all the ADs:
66+
resource "oci_core_subnet" "nat" {
67+
count = "${length(data.oci_identity_availability_domains.ads.availability_domains)}"
68+
availability_domain = "${lookup(data.oci_identity_availability_domains.ad.availability_domains[count.index], "name")}"
69+
...
70+
}
71+
```
72+
73+
The recommendation is to explicitly list the Availability Domain names for the regions in your configuration. To do so, use a variable that you have defined as follows:
74+
75+
```hcl
76+
variable "ad_list" {
77+
type = "list"
78+
}
79+
```
80+
81+
You can then use the variable as shown here:
82+
83+
```hcl
84+
// Index:
85+
resource "oci_core_instance" "nat" {
86+
availability_domain = "${var.ad_list[var.nat_instance_ad_index]}"
87+
...
88+
}
89+
90+
// Or iterate through all the ADs:
91+
resource "oci_core_subnet" "nat" {
92+
count = "${length(var.ad_list)}"
93+
availability_domain = "${var.ad_list[count.index]}"
94+
...
95+
}
96+
```
97+
98+
You can then set the ad_list variable directly by using the availability domain names for your tenant and region, as shown here:
99+
100+
```hcl
101+
variable "ad_list" {
102+
type = "list"
103+
default = ["kIdk:PHX-AD-1","kIdk:PHX-AD-2","kIdk:PHX-AD-3"]
104+
}
105+
```
106+
107+
The advantage of using this method is that it gives you control over your availability domain usage and prevents unexpected changes over time.
108+
However, this approach is problematic when configurations are shared between tenancies and regions, since availability domain names are tenancy and region-specific.
109+
110+
A convenient alternative is to instead set the ad_list value by using the oci_identity_availability_domains data source.
111+
You should do this in the configuration, then pass them into the resources or modules. This effectively centralizes the list of ADs,
112+
making it is easy to switch to an explicit list later, should that become necessary.
113+
114+
```hcl
115+
data "oci_identity_availability_domains" "ad" {
116+
compartment_id = "${var.tenancy_ocid}"
117+
}
118+
119+
data "template_file" "ad_names" {
120+
count = "${length(data.oci_identity_availability_domains.ad.availability_domains)}"
121+
template = "${lookup(data.oci_identity_availability_domains.ad.availability_domains[count.index], "name")}"
122+
}
123+
124+
module "ssm_network" {
125+
ad_list = "${data.template_file.ad_names.*.rendered}"
126+
...
127+
}
128+
```

‎website/docs/guides/object_store_backend.html.markdown‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
layout: "oci"
3+
page_title: "Provider: Oracle Cloud Infrastructure"
4+
sidebar_current: "docs-oci-guide-object_store_backend"
5+
description: |-
6+
The Oracle Cloud Infrastructure provider. Object Store Backend
7+
---
8+
9+
## Using the Object Store for Terraform State Files
10+
You can store [Terraform state files](https://www.terraform.io/docs/state/index.html) in the
11+
Oracle Cloud Infrastructure Object Storage. Doing so requires that you configure a backend using one of the Terraform backend types.
12+
13+
Terraform supports various backend types to allow flexibility in how state files are loaded into Terraform. (For more
14+
information, see [Terraform Backend Types](https://www.terraform.io/docs/backends/types/index.html).) For our purposes, we address two of these approaches:
15+
16+
- Using an HTTP remote state backend
17+
- Using an S3-compatible remote state backend
18+
19+
### Using an HTTP Backend
20+
21+
Using the [HTTP backend type](https://www.terraform.io/docs/backends/types/http.html) allows you to store state using a simple REST client. With the HTTP backend type, you can
22+
easily fetch, update, and purge state using the HTTP GET, POST, and DELETE methods.
23+
24+
To configure the HTTP backend to store your Oracle Cloud Infrastructure Terraform state files, do the following:
25+
26+
27+
#### Create a Pre-Authenticated Request
28+
29+
Creating a pre-authenticated request in Oracle Object Storage enables accessing a bucket or object in the Oracle Cloud
30+
Infrastructure without needing to provide credentials. To do so, you must create a pre-authenticated request that has
31+
read/write permissions to the object store where you intend to save the Terraform state file. You can do so in any of
32+
three ways: by using the Console UI, by using the command line interface (CLI), or by using the REST APIs.
33+
34+
> **Note**
35+
A state file must exist in the bucket before you create the pre-authenticated request. This file can be an existing state file, or an empty file for the initial state.
36+
37+
For guidance, see [Using Pre-Authenticated Requests](https://docs.cloud.oracle.com/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm).
38+
39+
40+
#### Upload Existing State
41+
42+
If you have an existing state file, you can upload it using Curl to make an HTTP Put request to the object store URL, as shown here:
43+
44+
```sh
45+
curl -X PUT -H "Content-Type: text/plain" --data-binary "@path/to/local/tfstate" http://<prefix>/<my-access-uri>
46+
```
47+
48+
49+
#### Configure HTTP as a Terraform Backend
50+
51+
The [HTTP backend type](https://www.terraform.io/docs/backends/types/http.html) stores state using a simple REST client
52+
and allows you to easily fetch, update, and purge state using the HTTP GET, POST, and DELETE methods.
53+
54+
The access URI for addressing Oracle Cloud Infrastructure Terraform configurations must be of the form:
55+
https://objectstorage.us-phoenix-1.oraclecloud.com/my-access-uri (where region and access URI are specific to you).
56+
57+
For more example configuration and state files that reference code, and a summary of configuration variables,
58+
see [Standard Backends: HTTP](https://www.terraform.io/docs/backends/types/http.html).
59+
60+
Following is an example Terraform configuration. The region in the URL can be something other than the Phoenix region.
61+
62+
```hcl-terraform
63+
terraform {
64+
backend "http" {
65+
address = "https://objectstorage.us-phoenix-1.oraclecloud.com/<my-access-uri>" update_method = "PUT" }
66+
}
67+
```
68+
69+
70+
#### Reinitialize Terraform
71+
72+
Finally, you must reinitialize Terraform and then run the apply command, as shown following.
73+
74+
```sh
75+
terraform init
76+
terraform apply
77+
```
78+
79+
After completing these steps, you are able to use Oracle Cloud Infrastructure as the backend for storing Terraform state files.
80+
81+
82+
### Using an S3-Compatible Backend
83+
84+
Configuring the S3-compatible backend requires that the account be enabled with S3 authentication keys, which are set on a per-user basis.
85+
86+
1. In the Console, open the navigation menu, then, under Governance and Administration, navigate to Identity, then Users.
87+
Under User Details, click Amazon S3 Compatibility API Keys. For more guidance,
88+
see [Working with Amazon S3 Compatibility API Keys](https://docs.cloud.oracle.com/Content/Identity/Tasks/managingcredentials.htm#s3).
89+
90+
2. Set the location for the credentials file. The default location is `~/.aws/credentials`. You can set an alternate location by using the S3 backend `shared_credentials_file` option.
91+
92+
> **Warning**
93+
Never set the access_key and the secret_key attributes in the same Terraform backend configuration, since this creates a security risk.
94+
95+
3. Configure the `[default]` entry in the credentials file with the appropriate object storage credentials.
96+
The file can contain any number of credential profiles. If you provide a different profile name, you must also
97+
update the backend `profile` option in your Terraform configuration file.
98+
99+
Following is an example of Object Storage credentials:
100+
101+
```
102+
[default]
103+
aws_access_key_id=ocid1.credential.oc1..aaaaaaaasbmhehdmefolvqwtbdjgwfsxjsgxgipdbph7odn2brgurgsyztca
104+
aws_secret_access_key=mSTdaWhlbWj3ty4JZXlm0NUZV52xlImWjayJLJ6OH9A=
105+
```
106+
107+
Where `aws_access_key_id and aws_secret_access_key` are user-specific values provided from the Console.
108+
The key values provided in the example are not valid and provided as examples only.
109+
110+
4. Set the object storage endpoint value in the following format: `https://{tenancy}.compat.objectstorage.{region}.oraclecloud.com`
111+
112+
Following is a full example of an Object Storage backend configuration:
113+
114+
```hcl-terraform
115+
terraform {
116+
backend "s3" {
117+
bucket = "terraform-state"
118+
key = "terraform.tfstate"
119+
region = "us-phoenix-1"
120+
endpoint = "https://acme.compat.objectstorage.us-phoenix-1.oraclecloud.com"
121+
122+
skip_region_validation = true
123+
skip_credentials_validation = true
124+
skip_requesting_account_id = true
125+
skip_get_ec2_platforms = true
126+
skip_metadata_api_check = true
127+
force_path_style = true
128+
}
129+
}
130+
```
131+
132+
The S3 backend configuration can also be used for the terraform_remote_state data source to enable sharing state across Terraform projects.
133+
134+
Once you have configured the backend, you must run `terraform init` to finish the setup.
135+
If you already have an existing `terraform.tfstate` file, then Terraform prompts you to confirm that the current state file is the one to upload to the remote state.
136+
137+
138+
### For More Information
139+
140+
- [Using Pre-Authenticated Requests](https://docs.cloud.oracle.com/iaas/Content/Object/Tasks/usingpreauthenticatedrequests.htm)
141+
- [State Files](https://www.terraform.io/docs/state/index.html)
142+
- [Terraform Backend Types](https://www.terraform.io/docs/backends/types/index.html)

‎website/oci.erb‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,21 @@
1111
<li<%= sidebar_current("docs-oci-guide") %>>
1212
<a href="#">Guides</a>
1313
<ul class="nav nav-visible">
14-
<li<%= sidebar_current("docs-oci-guide-filters") %>>
15-
<a href="/docs/providers/oci/guides/filters.html">Filters</a>
14+
<li<%= sidebar_current("docs-oci-guide-best_practices") %>>
15+
<a href="/docs/providers/oci/guides/best_practices.html">Best Practices</a>
1616
</li>
1717
<li<%= sidebar_current("docs-oci-guide-faq") %>>
1818
<a href="/docs/providers/oci/guides/faq.html">Frequently Asked Questions</a>
1919
</li>
20+
<li<%= sidebar_current("docs-oci-guide-filters") %>>
21+
<a href="/docs/providers/oci/guides/filters.html">Filters</a>
22+
</li>
2023
<li<%= sidebar_current("docs-oci-guide-managing_default_resources") %>>
2124
<a href="/docs/providers/oci/guides/managing_default_resources.html">Managing Default Resources</a>
2225
</li>
26+
<li<%= sidebar_current("docs-oci-guide-object_store_backend") %>>
27+
<a href="/docs/providers/oci/guides/object_store_backend.html">Object Store Backend</a>
28+
</li>
2329
<li<%= sidebar_current("docs-oci-guide-tagging_resources") %>>
2430
<a href="/docs/providers/oci/guides/tagging_resources.html">Tagging Resources</a>
2531
</li>

0 commit comments

Comments
 (0)