Merge pull request #937 from ovh/dev/aamstutz/backport-baremetal-1.8.0

Dev/aamstutz/backport baremetal 1.8.0

Author: amstuta

docs/guides/dedicated_server_migration.md

@@ -0,0 +1,105 @@
+---
+page_title: "Migrating dedicated servers from previous versions to v2.2.0"
+---
+
+Version v2.0.0 of OVHcloud Terraform provider introduced a breaking change on the resources related to dedicated servers, mainly:
+- Deletion of resource `ovh_dedicated_server_install_task` that has been replaced by a new resource `ovh_dedicated_server_reinstall_task`
+- The parameters of resource `ovh_dedicated_server` have been updated to reflect the changes on parameters needed to reinstall a dedicated server
+
+The complete changelog can be found [here](https://github.com/ovh/terraform-provider-ovh/releases/tag/v2.0.0).
+
+This guide explains how to migrate your existing configuration relying on resource `ovh_dedicated_server_install_task` to a new configuration compatible with version v2.2.0 of the provider without triggering a reinstallation of your dedicated servers.
+
+!> This documentation presents a direct migration path between v1.6.0 and v2.2.0. To make this transition easier, we released a version v1.8.0 of the provider that includes both deprecated resources and the new ones. The migration steps are the same, but this version allows a more gradual shift towards v2.2.0.
+
+## First step: import your dedicated servers in the state
+
+From version v2.0.0 and later, the preferred way to manage dedicated servers installation details is through usage of resource `ovh_dedicated_server`. As a result, if you don't already have your dedicated servers declared in your Terraform configuration, you must import them.
+
+You can use an `import` block like the following:
+
+```terraform
+import {
+  id = "nsxxxxxxx.ip-xx-xx-xx.eu"
+  to = ovh_dedicated_server.srv
+}
+
+resource "ovh_dedicated_server" "srv" {}
+```
+
+-> If you are doing a first migration to v1.8.0, you should add the following parameter `prevent_install_on_import = true` to the dedicated server resource. This guarantees you that the server won't be reinstalled after import, even if you have a diff on the reinstall-related parameters.
+
+To finish importing the resource into your Terraform state, you should run:
+
+```sh
+terraform apply
+```
+
+## Second step: backport your previous task details into the imported resource
+
+This step is manual and requires you to convert the previous installation details from resource `ovh_dedicated_server_install_task` to the new fields of resource `ovh_dedicated_server`: `os`, `customizations`, `properties` and `storage`.
+
+Let's take an example: if you previously used the following configuration:
+
+```terraform
+resource "ovh_dedicated_server_install_task" "server_install" {
+  service_name      = "nsxxxxxxx.ip-xx-xx-xx.eu"
+  template_name     = "debian12_64"
+  details {
+      custom_hostname = "mytest"
+  }
+  user_metadata {
+    key = "sshKey"
+    value = "ssh-ed25519 AAAAC3..."
+  }
+  user_metadata {
+    key = "postInstallationScript"
+    value = <<-EOF
+        #!/bin/bash
+          echo "coucou postInstallationScript" > /opt/coucou
+          cat /etc/machine-id  >> /opt/coucou
+          date "+%Y-%m-%d %H:%M:%S" --utc >> /opt/coucou
+        EOF
+  }
+}
+```
+
+You can replace it by the following one:
+
+```terraform
+resource "ovh_dedicated_server" "srv" {
+  customizations = {
+    hostname                 = "mytest"
+    post_installation_script = "IyEvYmluL2Jhc2gKZWNobyAiY291Y291IHBvc3RJbnN0YWxsYXRpb25TY3JpcHQiID4gL29wdC9jb3Vjb3UKY2F0IC9ldGMvbWFjaGluZS1pZCAgPj4gL29wdC9jb3Vjb3UKZGF0ZSAiKyVZLSVtLSVkICVIOiVNOiVTIiAtLXV0YyA+PiAvb3B0L2NvdWNvdQo="
+    ssh_key                  = "ssh-ed25519 AAAAC3..."
+  }
+  os         = "debian12_64"
+  properties = null
+  storage    = null
+}
+```
+
+You can check the documentation of resource `ovh_dedicated_server` to see what inputs are available for the reinstallation-related fields.
+The documentation of resource `ovh_dedicated_server_reinstall_task` also includes several examples of configuration.
+
+## Third step: make sure your server is not reinstalled unintentionally
+
+You should add the following piece of configuration in the declaration of your dedicated server resource in order to avoid a reinstallation on the next `terraform apply`:
+
+```terraform
+resource "ovh_dedicated_server" "srv" {
+  #
+  # ... resource fields
+  #
+
+  lifecycle {
+    ignore_changes = [os, customizations, properties, storage]
+  }
+}
+```
+
+This is needed because there is no API endpoint that returns the previous installation parameters of a dedicated server. The goal here is to migrate your old configuration to the new format without triggering a reinstallation.
+
+## Fourth step: remove the lifecycle block
+
+After a while, whenever you need to trigger a reinstallation of your dedicated server, you can just remove the `lifecycle` field from your configuration and run `terraform apply`.

docs/resources/dedicated_server.md

@@ -90,6 +90,7 @@ resource "ovh_dedicated_server" "server" {
   * `configuration` - Representation of a configuration item to personalize product
     * `label` - (Required) Identifier of the resource
     * `value` - (Required) Path to the resource in API.OVH.COM
+* `service_name` - (Optional) The service_name of your dedicated server. This field can be used to avoid ordering a dedicated server at creation and just create the resource using an already existing service
 
 ### Editable fields of a dedicated server
 
@@ -103,40 +104,47 @@ resource "ovh_dedicated_server" "server" {
 * `state` - All states a Dedicated can in (error, hacked, hackedBlocked, ok)
 
 ### Arguments used to reinstall a dedicated server
+
 * `os` - Operating System to install
 * `customizations` - Customization of the OS configuration
-  * `configDriveUserData` -Config Drive UserData
-  * `efiBootloaderPath` - Path of the EFI bootloader from the OS installed on the server
+  * `config_drive_user_data` - Config Drive UserData
+  * `efi_bootloader_path` - Path of the EFI bootloader from the OS installed on the server
   * `hostname` - Custom hostname
-  * `httpHeaders` - Image HTTP Headers
-  * `imageCheckSum` - Image checksum
-  * `imageCheckSumType` - Checksum type
-  * `imageType` - Image Type
-  * `imageURL` - Image URL
+  * `http_headers` - Image HTTP Headers
+  * `image_check_sum` - Image checksum
+  * `image_check_sum_type` - Checksum type
+  * `image_type` - Image Type
+  * `image_url` - Image URL
   * `language` - Display Language
-  * `postInstallationScript` - Post-Installation Script
-  * `postInstallationScriptExtension` - Post-Installation Script File Extension
-  * `sshKey` - SSH Public Key
+  * `post_installation_script` - Post-Installation Script
+  * `post_installation_script_extension` - Post-Installation Script File Extension
+  * `ssh_key` - SSH Public Key
 * `storage` - Storage customization
-  * `diskGroupId` - Disk group id
-  * `hardwareRaid` - Hardware Raid configurations
+  * `disk_group_id` - Disk group id
+  * `hardware_raid` - Hardware Raid configurations
     * `arrays` - Number of arrays
     * `disks` - Total number of disks in the disk group involved in the hardware raid configuration
-    * `raidLevel` - Hardware raid type
+    * `raid_level` - Hardware raid type
     * `spares` - Number of disks in the disk group involved in the spare
   * `partitioning` - Partitioning configuration
     * `disks` - Total number of disks in the disk group involved in the partitioning configuration
     * `layout` - Custom partitioning layout
       * `extras` - Partition extras parameters
         * `lv` - LVM-specific parameters
         * `zp` - ZFS-specific parameters
-      * `fileSystem` - File system type
-      * `mountPoint` - Mount point
-      * `raidLevel` - Software raid type
+      * `file_system` - File system type
+      * `mount_point` - Mount point
+      * `raid_level` - Software raid type
       * `size` - Partition size in MiB
-    * `schemeName` - Partitioning scheme (if applicable with selected operating system)
+    * `scheme_name` - Partitioning scheme (if applicable with selected operating system)
 * `properties` - Arbitrary properties to pass to cloud-init's config drive datasource
 
+### Arguments used to control the lifecycle of a dedicated server
+
+* `keep_service_after_destroy` - Avoid termination of the service when deleting the resource (when using this parameter, make sure to apply your configuration before running the destroy so that the value is set in the state)
+* `prevent_install_on_create` - Prevent server installation after it has been delivered
+* `prevent_install_on_import` - Defines whether a reinstallation of the server is allowed after importing it if there is a modification on the installation parameters
+
 ## Attributes Reference
 
 * `service_name` - The service_name of your dedicated server

docs/resources/dedicated_server_reinstall_task.md

@@ -282,11 +282,3 @@ The following attributes are exported:
 * `function` - Function name (should be `hardInstall`).
 * `start_date` - Task creation date in RFC3339 format.
 * `status` - Task status (should be `done`)
-
-## Import
-
-Installation task can be imported using the `service_name` (`nsXXXX.ip...`) of the baremetal server, the `operating_system` used and ths `task_id`, separated by "/" E.g.,
-
-```bash
-terraform import ovh_dedicated_server_reinstall_task nsXXXX.ipXXXX/operating_system/12345
-```