Skip to content

Commit c7aca9b

Browse files
ccushingkohashim
ccushing
authored and
kohashim
committed
Readme updates for new version requirements
* better setup instructions * update links
1 parent 514dfe5 commit c7aca9b

File tree

2 files changed

+79
-63
lines changed

2 files changed

+79
-63
lines changed

‎README.md‎

Lines changed: 52 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,37 @@
11
## NOTICE
2-
**The terraform provider has been renamed, see [this wiki](https://github.com/oracle/terraform-provider-oci/wiki/Oracle-Terraform-Provider-Name-Change) for information on migration steps.**
3-
4-
*Legacy provider documentation (for v1.0.18 and earlier) can be found [here](https://github.com/oracle/terraform-provider-oci/tree/v1.0.18/docs)*
5-
2+
**OCI Terraform Provider v2.2.0 and above is not compatible with Terraform binaries below v0.10.1. To use the latest OCI
3+
Provider, upgrade your version of Terraform to v0.10.1 or higher.**
64

75
# ___ ____ _ ____ _ _____
86
# / _ \| _ \ / \ / ___| | | ____|
97
# | | | | |_) | / _ \| | | | | _|
108
# | |_| | _ < / ___ | |___| |___| |___
119
# \___/|_| \_/_/ \_\____|_____|_____|
1210
***
13-
# Terraform provider for Oracle Cloud Infrastructure
11+
# Terraform Provider for Oracle Cloud Infrastructure
1412

1513
[![wercker status](https://app.wercker.com/status/666d2ee10f45dde41189bb03248aadf9/s/master "wercker status")](https://app.wercker.com/project/byKey/666d2ee10f45dde41189bb03248aadf9)
1614

17-
Oracle customers now have access to an enterprise class, developer friendly orchestration tool they can use to manage [Oracle Cloud Infrastructure](https://cloud.oracle.com/cloud-infrastructure).
18-
19-
This Terraform provider is OSS, available to all OCI customers at no charge.
15+
OCI Terraform Provider gives Oracle customers access to an enterprise class, developer friendly orchestration tool they
16+
can use to manage [Oracle Cloud Infrastructure](https://cloud.oracle.com/cloud-infrastructure). This Terraform provider
17+
is open-source software, available to all OCI customers at no charge.
2018

2119
## Compatibility
22-
The provider is compatible with Terraform v0.10.x.
20+
The OCI Terraform Provider is compatible with Terraform v0.10.1 or greater.
2321

2422
### Coverage
25-
The Terraform provider provides coverage for the entire OCI API, with some minor exceptions.
23+
The OCI Terraform Provider supports the entire OCI API, with a few minor exceptions.
2624

2725
## Getting started
28-
Be sure to read the FAQ and Writing Terraform configurations for OCI in [/docs](https://github.com/oracle/terraform-provider-oci/tree/master/docs).
26+
27+
To see supported OCI resources and view documentation go to the OCI resource and datasource documentation
28+
[Table of Contents](https://github.com/oracle/terraform-provider-oci/tree/master/docs/Table%20of%20Contents.md).
29+
30+
Be sure to read the [FAQ](https://github.com/oracle/terraform-provider-oci/tree/master/docs/FAQ.md)
31+
and [Writing Terraform configurations for OCI](https://github.com/oracle/terraform-provider-oci/tree/master/docs/Writing%20Terraform%20configurations%20for%20OCI.md) document
32+
in the [docs](https://github.com/oracle/terraform-provider-oci/tree/master/docs) section.
2933

3034
## Installation
31-
**NOTE** Terraform v0.10.x introduces a change to plugin management where
32-
previous v0.9.x configuration no longer applies. See note below.
3335

3436
### On Oracle Linux 7.x
3537
```
@@ -38,7 +40,7 @@ $ sudo yum install -y terraform terraform-provider-oci
3840

3941
### Other platforms
4042
#### Download Terraform
41-
Download the appropriate **v0.10.x binary** for your platform.
43+
Download the appropriate **v0.11.x binary** for your platform.
4244
https://www.terraform.io/downloads.html
4345

4446
#### Install Terraform
@@ -47,24 +49,13 @@ https://www.terraform.io/intro/getting-started/install.html
4749
#### Get the Oracle Cloud Infrastructure Terraform provider
4850
https://github.com/oracle/terraform-provider-oci/releases
4951

50-
Unpack the provider. Terraform v0.10.x introduces a change to plugin
51-
management where v0.9.x configuration no longer applies. To be compatible
52-
with both terraform v0.9.x and v0.10.x, do the following depending on your
53-
platform.
52+
Unpack the provider.
5453

55-
##### On \*nix other than Oracle Linux 7.x
54+
##### On Mac or other Linux flavors
5655
Copy the provider to the following location:
5756
```
5857
~/.terraform.d/plugins/
5958
```
60-
###### For terraform v0.9.x only
61-
Create the `~/.terraformrc` file that specifies the path to the
62-
`oci` provider.
63-
```
64-
providers {
65-
oci = "~/.terraform.d/plugins/terraform-provider-oci"
66-
}
67-
```
6859

6960
##### On Windows
7061
Copy the provider to the following location:
@@ -73,34 +64,37 @@ Copy the provider to the following location:
7364
```
7465
Note: `%APPDATA%` is a system path specific to your Windows version.
7566

76-
###### For terraform v0.9.x only
77-
Create `%APPDATA%/terraform.rc` that specifies the path to the
78-
`oci` provider.
79-
```
80-
providers {
81-
oci = "%appdata%/terraform.d/plugins/terraform-provider-oci"
82-
}
83-
```
8467

85-
### Export credentials
86-
Required Keys and OCIDs - https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
68+
### Setup credentials for using OCI
69+
Every call to OCI infrastructure requires a minimum of four credentials.
70+
These are `tenancy_ocid`, `user_ocid`, `fingerprint` and `private_key_path`. It is common to export these values as
71+
environment variables, or source them in different bash profiles when executing Terraform commands. See the next
72+
section for OS specific instructions on configuring these environment values.
8773

88-
If you primarily work in a single compartment consider exporting that compartment's OCID as well. Remember that the tenancy OCID is also the OCID of the root compartment.
74+
Here is breakdown of required as well as commonly set configuration values:
75+
- `tenancy_ocid` - The global identifier for your account, always shown on the bottom of the web console.
76+
- `user_ocid` - The identifier of the user account you will be using Terraform with.
77+
- `private_key_path` - The path to the private key stored on your computer. The public key portion must be added to the
78+
user account above in the _API Keys_ section of the web console.
79+
- `fingerprint` - The fingerprint of the public key added in the above user's _API Keys_ section of the web console.
80+
81+
For details on how to create and configure keys see [Required Keys and OCIDs](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
82+
83+
If you primarily work in a single compartment consider defining a `compartment_ocid` as well. The tenancy OCID is also
84+
the OCID of the root compartment, so that can be used where resources expect a `compartment_id` or `compartment_ocid`.
8985

9086
#### \*nix
91-
If your TF configurations are limited to a single compartment/user then
92-
using this `bash_profile` option will work well. For more complex
93-
environments you may want to maintain multiple sets of environment
94-
variables.
87+
If your Terraform configurations are limited to a single compartment or user then using this `bash_profile` option
88+
will work well. For more complex environments you may want to maintain multiple sets of environment variables.
9589
See the [compute single instance example](https://github.com/oracle/terraform-provider-oci/tree/master/docs/examples/compute/instance) for more info.
9690

9791
In your `~/.bash_profile` set these variables
9892
```
99-
export TF_VAR_tenancy_ocid=
100-
export TF_VAR_user_ocid=
101-
export TF_VAR_compartment_ocid=<The tenancy OCID can be used as the compartment OCID of your root compartment>
102-
export TF_VAR_fingerprint=
103-
export TF_VAR_private_key_path=<fully qualified path>
93+
export TF_VAR_tenancy_ocid=<value>
94+
export TF_VAR_compartment_ocid=<value>
95+
export TF_VAR_user_ocid=<value>
96+
export TF_VAR_fingerprint=<value>
97+
export TF_VAR_private_key_path=<value>
10498
```
10599

106100
Once you've set these values open a new terminal or source your profile changes
@@ -111,8 +105,8 @@ $ source ~/.bash_profile
111105
#### Windows
112106
```
113107
setx TF_VAR_tenancy_ocid <value>
114-
setx TF_VAR_user_ocid <value>
115108
setx TF_VAR_compartment_ocid <value>
109+
setx TF_VAR_user_ocid <value>
116110
setx TF_VAR_fingerprint <value>
117111
setx TF_VAR_private_key_path <value>
118112
```
@@ -121,34 +115,29 @@ The variables won't be set for the current session, exit the terminal and reopen
121115
## Deploy an example configuration
122116
Download the [virtual cloud network example](https://github.com/oracle/terraform-provider-oci/tree/master/docs/examples/networking/vcn).
123117

124-
You should always plan, then apply a configuration -
125118
```
126-
# From the vcn directory
119+
# Change to the directory of an example like:
120+
$ cd doc/examples/networking/vcn
127121
128122
# Initialize the plugin for this template directory
129123
$ terraform init
130124
131-
# Run the plan command to see what will happen.
125+
# Run the plan command to see what will happen
132126
$ terraform plan
133127
134-
# If the plan looks right, apply it.
128+
# If the plan looks right, apply it
135129
$ terraform apply
136130
137131
# If you are done with this infrastructure, take it down
138132
$ terraform destroy
139133
```
140134

141-
## OCI resource and datasource details
142-
https://github.com/oracle/terraform-provider-oci/tree/master/docs
143-
144135
## Getting help
145-
You can file an issue against the project
146-
https://github.com/oracle/terraform-provider-oci/issues
147-
148-
or meet us in the OCI forums
149-
https://community.oracle.com/community/cloud_computing/bare-metal
150-
151-
## Known issues
136+
If you are having trouble getting the OCI Provider working, check the
137+
[troubleshooting doc](https://github.com/oracle/terraform-provider-oci/tree/master/docs/Troubleshooting.md)
152138

153-
[Github issues](https://github.com/oracle/terraform-provider-oci/issues)
139+
To see known issues or report unexpected behavior go to the
140+
[Github issues](https://github.com/oracle/terraform-provider-oci/issues) page.
154141

142+
For questions or information visit the
143+
[OCI forums](https://cloudcustomerconnect.oracle.com/resources/9c8fa8f96f/summary).

‎docs/Troubleshooting.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
### Not Authenticated Error when configuring Terraform
2+
3+
_If the Terraform CLI gives an error message like:_
4+
5+
`* oci_core_vcn.resource1: Service error:NotAuthenticated. The required information to complete authentication was not provided or was incorrect.. http status code: 401`
6+
7+
* Verify you have properly set `user_ocid`, `tenancy_ocid`, `fingerprint` and `private_key_path`
8+
* Verify your `private_key_path` is pointing to your private key and not the corresponding public key
9+
* Verify you have added the corresponding public key to the user account you have specified with `user_ocid`
10+
* Verify the public/private key pairs you are using are of the correct format
11+
* see: [Required Keys](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/apisigningkey.htm) for details on the correct format and how to generate keys
12+
* Verify the user account is part of a group with the appropriate permissions to perform the actions in the plan you are executing
13+
* Verify your Tenancy has been subscribed to the Region you are targeting in your plan
14+
15+
16+
### Error message after upgrading OCI Terraform Provider
17+
18+
_If the Terraform CLI gives an error message like:_
19+
20+
```
21+
Error asking for user input: 1 error(s) occurred:
22+
23+
* provider.oci: dial unix /var/folders/6r/8fk5dmbj4_z3sl0mc_y_fhjw0000gn/T/plugin811254328|netrpc: connect: no such file or directory
24+
```
25+
26+
You are likely using a version of the OCI Terraform Provider that is not compatible with the Terraform binary you have
27+
installed. For OCI Provider versions v3.x.x and above, a minimum Terraform version of v.0.10.1 is required.

0 commit comments

Comments
 (0)