Skip to content

Commit dc3264b

Browse files
rashik-bhasinrashik-bhasin
committed
Documentation links updated
1 parent 40bfa27 commit dc3264b

15 files changed

+18
-1078
lines changed

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

Lines changed: 2 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -6,129 +6,6 @@ description: |-
66
The Oracle Cloud Infrastructure provider. Best Practices
77
---
88

9-
## Terraform Provider Best Practices
9+
## Best Practices
1010

11-
Following are recommended best practices for writing configurations for the Oracle Cloud Infrastructure Terraform provider.
12-
13-
### Sensitive Data May Be Stored In Statefile
14-
15-
> **Warning**: The state contains all resource attributes that are specified as part of configuration files. If you manage any sensitive data with Terraform (like database or user passwords, instance or load balancer private keys, etc), treat the state itself as sensitive data.
16-
Please refer to [Sensitive Data in State](https://www.terraform.io/docs/state/sensitive-data.html) for more details.
17-
18-
19-
### Referencing Images
20-
21-
When launching Compute instances, your Terraform configuration should use the same image every time you execute a Terraform Apply command.
22-
23-
To ensure this, specify the image OCID directly, rather than locating it using the `oci_core_image` data source.
24-
This is because the `oci_core_image` data source calls into the ListImages API, whose return values can change over
25-
time as new images are periodically added and older ones deleted. For a list of Oracle-Provided images and their OCIDs,
26-
see [Oracle-Provided Images](https://docs.cloud.oracle.com/iaas/Content/Compute/References/images.htm).
27-
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).
28-
29-
We recommend the following pattern for specifying an image for a given region:
30-
31-
```hcl
32-
variable "image_id" {
33-
type = "map"
34-
default = {
35-
// See https://docs.cloud.oracle.com/iaas/images/
36-
// Oracle-provided image "Oracle-Linux-7.5-2018.10.16-0"
37-
us-phoenix-1 = "ocid1.image.oc1.phx.aaaaaaaaoqj42sokaoh42l76wsyhn3k2beuntrh5maj3gmgmzeyr55zzrwwa"
38-
us-ashburn-1 = "ocid1.image.oc1.iad.aaaaaaaageeenzyuxgia726xur4ztaoxbxyjlxogdhreu3ngfj2gji3bayda"
39-
eu-frankfurt-1 = "ocid1.image.oc1.eu-frankfurt-1.aaaaaaaaitzn6tdyjer7jl34h2ujz74jwy5nkbukbh55ekp6oyzwrtfa4zma"
40-
uk-london-1 = "ocid1.image.oc1.uk-london-1.aaaaaaaa32voyikkkzfxyo4xbdmadc2dmvorfxxgdhpnk6dw64fa3l4jh7wa"
41-
}
42-
}
43-
```
44-
45-
A Compute instance can use this in the following way:
46-
47-
```hcl
48-
resource "oci_core_instance" "TFInstance" {
49-
image = var.image_id[var.region]
50-
...
51-
}
52-
```
53-
54-
55-
### Availability Domains
56-
57-
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:
58-
59-
```hcl
60-
// Get all availability domains for the region
61-
data "oci_identity_availability_domains" "ads" {
62-
compartment_id = var.tenancy_ocid
63-
}
64-
65-
// Then either use it to get a single AD name based on the index:
66-
resource "oci_core_instance" "nat" {
67-
availability_domain = lookup(data.oci_identity_availability_domains.ads.availability_domains[var.nat_instance_ad],"name")
68-
...
69-
}
70-
71-
// Or iterate through all the ADs:
72-
resource "oci_core_subnet" "nat" {
73-
count = length(data.oci_identity_availability_domains.ads.availability_domains)
74-
availability_domain = lookup(data.oci_identity_availability_domains.ad.availability_domains[count.index], "name")
75-
...
76-
}
77-
```
78-
79-
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:
80-
81-
```hcl
82-
variable "ad_list" {
83-
type = "list"
84-
}
85-
```
86-
87-
You can then use the variable as shown here:
88-
89-
```hcl
90-
// Index:
91-
resource "oci_core_instance" "nat" {
92-
availability_domain = var.ad_list[var.nat_instance_ad_index]
93-
...
94-
}
95-
96-
// Or iterate through all the ADs:
97-
resource "oci_core_subnet" "nat" {
98-
count = length(var.ad_list)
99-
availability_domain = var.ad_list[count.index]
100-
...
101-
}
102-
```
103-
104-
You can then set the ad_list variable directly by using the availability domain names for your tenant and region, as shown here:
105-
106-
```hcl
107-
variable "ad_list" {
108-
type = "list"
109-
default = ["kIdk:PHX-AD-1","kIdk:PHX-AD-2","kIdk:PHX-AD-3"]
110-
}
111-
```
112-
113-
The advantage of using this method is that it gives you control over your availability domain usage and prevents unexpected changes over time.
114-
However, this approach is problematic when configurations are shared between tenancies and regions, since availability domain names are tenancy and region-specific.
115-
116-
A convenient alternative is to instead set the ad_list value by using the oci_identity_availability_domains data source.
117-
You should do this in the configuration, then pass them into the resources or modules. This effectively centralizes the list of ADs,
118-
making it is easy to switch to an explicit list later, should that become necessary.
119-
120-
```hcl
121-
data "oci_identity_availability_domains" "ad" {
122-
compartment_id = var.tenancy_ocid
123-
}
124-
125-
data "template_file" "ad_names" {
126-
count = length(data.oci_identity_availability_domains.ad.availability_domains)
127-
template = lookup(data.oci_identity_availability_domains.ad.availability_domains[count.index], "name")
128-
}
129-
130-
module "ssm_network" {
131-
ad_list = data.template_file.ad_names.*.rendered
132-
...
133-
}
134-
```
11+
This content is now available at [Best Practices](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/terraformbestpractices.htm).

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

Lines changed: 1 addition & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -8,91 +8,5 @@ description: |-
88

99

1010
## OCI Terraform Provider Boot volume reuse and troubleshooting
11-
This guide details the following scenarios:<br/>
12-
1. Preserving boot volume when performing instance scaling<br/>
13-
2. Boot volume troubleshooting and repair
14-
15-
To read more about boot volumes, see [Boot Volumes](https://docs.cloud.oracle.com/iaas/Content/Block/Concepts/bootvolumes.htm)
16-
17-
18-
### Preserve boot volume with instance scaling
19-
20-
You may want to upscale / downscale instances (change instance shape) while using the same boot volume. When you terminate
21-
your instance, you can keep the associated boot volume and use it to launch a new instance using a different instance type
22-
or shape. This approach is useful for scenarios where instance shape cannot be changed as per [this](https://docs.cloud.oracle.com/en-us/iaas/Content/Compute/Tasks/resizinginstances.htm) while resizing instances.
23-
24-
To achieve this, you need to detach the boot volume from the running instance. This can be performed by either
25-
terminating the instance while preserving the boot volume or by stopping the instance and detaching the boot volume,
26-
27-
All terraform resources of type `oci_core_instance` have the parameter `preserve_boot_volume` set as true by default.
28-
This parameter ensures that upon termination of the instance, the attached boot volume is not terminated.
29-
30-
```
31-
resource "oci_core_instance" "TFInstance" {
32-
...
33-
state = "STOPPED" // set this state to stop the instance
34-
preserve_boot_volume = true
35-
}
36-
37-
output "bootVolumeFromInstance" {
38-
value = [oci_core_instance.TFInstance.boot_volume_id]
39-
}
40-
```
41-
42-
Once the boot volume is detached, the OCID of the boot volume can be referred as the source of the new instance, as
43-
illustrated below
44-
45-
```
46-
resource "oci_core_instance" "TFScaleInstance" {
47-
...
48-
source_details {
49-
source_type = "bootVolume"
50-
51-
// reference the original boot volume id here
52-
source_id = "ocid1.bootvolume.oc1.phx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
53-
}
54-
}
55-
```
56-
57-
58-
<br/>
59-
### OCI Terraform Provider boot volume troubleshooting and repair
60-
61-
If you think a boot volume issue is causing a compute instance problem, you can stop the instance and detach the boot volume.
62-
Then you can attach it to another instance as a data volume to troubleshoot it. After resolving the issue, you can then
63-
reattach it to the original instance or use it to launch a new instance.
64-
65-
Once the boot volume has been detached, the OCID of the boot volume can be referred as the block volume parameter for
66-
another instance.
67-
68-
```
69-
resource "oci_core_volume_attachment" "TFBlockAttach" {
70-
...
71-
attachment_type = "iscsi"
72-
compartment_id = "ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
73-
74-
// new instance
75-
instance_id = "ocid1.instance.oc1.phx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
76-
77-
// attach the boot volume as a block volume
78-
volume_id = "ocid1.bootvolume.oc1.phx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
79-
}
80-
```
81-
82-
Once you have resolved the issue, detach this volume from the second instance and attach it as a boot volume to the
83-
original instance.
84-
85-
```
86-
resource "oci_core_instance" "TFScaleInstance" {
87-
...
88-
89-
source_details {
90-
source_type = "bootVolume"
91-
92-
// attach back as boot volume
93-
// reference the volume id here
94-
source_id = "ocid1.bootvolume.oc1.phx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
95-
}
96-
}
97-
```
9811

12+
This content is now available at [Managing Boot Volumes](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/terraformbootvolumes.htm).

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

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,4 @@ description: |-
88

99
## Timeout errors when waiting for a state change
1010

11-
_If the Terraform CLI gives an error message like:_
12-
13-
```
14-
* oci_database_backup.mydb: timeout while waiting for state to become 'ACTIVE' (last state: 'CREATING', timeout: 15m0s)
15-
```
16-
17-
Then the OCI service is indicating that the resource has not yet reached the expected state after polling for some time.
18-
19-
You may need to increase the operation timeout for your resource to continue polling for longer. See [Operation Timeouts](https://www.terraform.io/docs/configuration/resources.html#operation-timeouts) for details on how to do this.
11+
This content is now available at [Troubleshooting](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/terraformtroubleshooting.htm).

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

Lines changed: 1 addition & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -8,131 +8,4 @@ description: |-
88

99
## Database DB System Migration
1010

11-
The X8M generation of Exadata hardware introduces a new resource model that replaces the Exadata DB system. The new resource model uses new APIs to provision and manage its resources. The existing DB system APIs for Exadata will be deprecated by Oracle Cloud Infrastructure for all users following written notification and a transition period allowing you to switch to the new API and Console interfaces.
12-
13-
If you have existing Exadata DB systems in Oracle Cloud Infrastructure, you can use Terraform to switch them to the new resource model and APIs.
14-
15-
### Warning
16-
Switching an Exadata DB system to the new resource model and APIs cannot be reversed. If you have automation for your system that utilizes the DB system APIs, you may need to update your applications prior to switching.
17-
18-
## Switching to the new resource model:
19-
* Does not impact the DB system's existing Exadata databases or client connections.
20-
* Does not change the underlying hardware or shape family of your Exadata Cloud Service instance.
21-
* Will not affect bare metal and virtual DB systems
22-
23-
After converting your DB system, you will have two new resources in place of the DB system resource: a cloud Exadata infrastructure resource, and a cloud VM cluster resource.
24-
25-
## What to Expect After Switching
26-
27-
* Your new cloud Exadata infrastructure resource and cloud VM cluster are created in the same compartment as the DB system they replace
28-
* Your new cloud Exadata infrastructure resource and cloud VM cluster use the same networking configuration as the DB system they replace
29-
* After the switch, you cannot perform operations on the old Exadata DB system resource
30-
* Switching is permanent, and the change cannot be undone
31-
* X6, X7, X8 and Exadata base systems retain their fixed shapes after the switch, and cannot be expanded
32-
33-
## To switch an Exadata DB system to the new Exadata resource model
34-
35-
These migration steps use the following example, which shows an existing Exadata Cloud Service instance using the old DB system resource model:
36-
37-
```hcl
38-
resource "oci_database_db_system" "test_db_system" {
39-
availability_domain = data.oci_identity_availability_domain.ad.name
40-
compartment_id = var.compartment_ocid
41-
cpu_core_count = var.cpu_core_count
42-
database_edition = var.db_edition
43-
time_zone = var.time_zone
44-
45-
db_home {
46-
database {
47-
admin_password = var.db_admin_password
48-
db_name = "TFdb1Exa"
49-
character_set = var.character_set
50-
ncharacter_set = var.n_character_set
51-
db_workload = var.db_workload
52-
pdb_name = var.pdb_name
53-
54-
db_backup_config {
55-
auto_backup_enabled = false
56-
}
57-
}
58-
59-
db_version = var.db_version
60-
display_name = "MyTFDBHome1Exa"
61-
}
62-
63-
maintenance_window_details {
64-
preference = "CUSTOM_PREFERENCE"
65-
66-
days_of_week {
67-
name = "MONDAY"
68-
}
69-
70-
hours_of_day = ["4"]
71-
lead_time_in_weeks = 2
72-
73-
months {
74-
name = "APRIL"
75-
}
76-
77-
weeks_of_month = ["2"]
78-
}
79-
80-
disk_redundancy = var.db_disk_redundancy
81-
shape = var.db_system_shape
82-
subnet_id = oci_core_subnet.subnet.id
83-
backup_subnet_id = oci_core_subnet.subnet_backup.id
84-
ssh_public_keys = [var.ssh_public_key]
85-
display_name = var.db_system_display_name
86-
sparse_diskgroup = var.sparse_diskgroup
87-
88-
hostname = var.hostname
89-
data_storage_percentage = var.data_storage_percentage
90-
91-
#data_storage_size_in_gb = var.data_storage_size_in_gb
92-
license_model = var.license_model
93-
node_count = data.oci_database_db_system_shapes.test_db_system_shapes.db_system_shapes[0]["minimum_node_count"]
94-
backup_network_nsg_ids = [oci_core_network_security_group.test_network_security_group.id]
95-
nsg_ids = [oci_core_network_security_group.test_network_security_group_backup.id, oci_core_network_security_group.test_network_security_group.id]
96-
}
97-
```
98-
99-
To migrate the system to the new resource model, first create the `oci_database_migration` resource:
100-
101-
```hcl
102-
// This is 1 time action to migrate test_db_system into db ExaCS
103-
// and the test_db_system will become `Migrated`
104-
resource "oci_database_migration" "test_migration" {
105-
#Required
106-
db_system_id = "${oci_database_db_system.test_db_system.id}"
107-
}
108-
```
109-
110-
Provisioning the `oci_database_migration` resource creates two new resources: `oci_database_cloud_exadata_infrastructure` and `oci_database_cloud_vm_cluster`.
111-
112-
You can get OCIDs of these two resources from the `oci_database_migration` resource:
113-
```hcl
114-
output "cloud_exadata_infrastructure_id" {
115-
value = oci_database_migration.test_migration.cloud_exadata_infrastructure_id
116-
}
117-
118-
output "cloud_vm_cluster_id" {
119-
value = oci_database_migration.test_migration.cloud_vm_cluster_id
120-
}
121-
```
122-
For the two new resources, you need to create Terraform config:
123-
```hcl
124-
resource "oci_database_cloud_exadata_infrastructure" "test_cloud_exadata_infrastructure"{}
125-
126-
resource "oci_database_cloud_vm_cluster" "test_cloud_vm_cluster" {}
127-
```
128-
Then run the Terraform import command:
129-
```text
130-
terraform import oci_database_cloud_exadata_infrastructure.test_cloud_exadata_infrastructure <cloud_exadata_infrastructure_id>
131-
terraform import oci_database_cloud_vm_cluster.test_cloud_vm_cluster <cloud_vm_cluster_id>
132-
```
133-
134-
After switching to the new Exadata resource model, remove the old `oci_database_db_system` config.
135-
Terraform now manages the two new resources.
136-
137-
### Tip
138-
After the migration, you can use [Resource Discovery](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/guides/resource_discovery) to create a full configuration and state file for importing these two new resources.
11+
This content is now available at [Database DB System Migration](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/terraformservicesreference_migrateanexadatadb.htm).

0 commit comments

Comments
 (0)