Document Terraform import for every provider resource

[kavalerov]

Problem

Import is implemented but undocumented, so people assume it doesn't work. Every one of the 20 resources in the provider implements ImportState, yet none of the 20 pages in docs/resources/ mentions import at all. The GitHub issue this came from shows the cost: someone tried terraform import 'module.ably-app["stage-us"].ably_app.app' 'stage-us' and hit an error, because nothing told them what identifier format to use.

So the remaining work is documentation, not implementation.

Context

Two identifier shapes exist:

• ably_app uses resource.ImportStatePassthroughID on id (internal/provider/resource_ably_app.go:530-532), so the app id alone.
• Everything else uses the shared ImportResource helper (internal/provider/rules.go:987-1009), which splits the identifier on commas and maps the parts to named attributes in order. ably_key calls it as ImportResource(ctx, req, resp, "app_id", "id"), so <app_id>,<key_id>. The helper errors with the expected format when the part count doesn't match, which is a good message nobody currently sees before making the mistake.

The repository is ably/terraform-provider-ably; this ticket is a Unito mirror of GitHub issue 16 and is also tracked as SDK-3017.

Acceptance criteria

• Each resource page in docs/resources/ has an import section giving the identifier format and a working example command
• The composite format is spelled out, including that the separator is a comma and the order matters
• ably_app's single-value form is distinguished from the composite ones, so the difference is not something to infer
• An import of an app and of a key is actually run against a real app before the docs claim it works
• The provider docs index mentions that resources support import, so the pages are discoverable

Scope

• In scope: documentation for the existing import support, and verifying it behaves as documented
• Out of scope: adding import to anything that lacks it (nothing does), changing identifier formats, and the other provider bugs

Pointers

• internal/provider/rules.go:987 - the shared ImportResource helper and its format
• internal/provider/resource_ably_app.go:530 - the passthrough case
• internal/provider/resource_ably_key.go:380 - a composite example
• docs/resources/ - the 20 pages to update
• GitHub issue 16, and SDK-3017

┆Issue is synchronized with this Jira Task by Unito

[sync-by-unito]

➤ Ivan Kavalerov commented:

All resources we are creating support importing, so closing.

[Israphel]

➤ Ivan Kavalerov commented:

All resources we are creating support importing, so closing.

but what are the commands to import? I don't see it in the current docs

[kavalerov]

Hi @Israphel ! Apologies for a delay in getting back to you.

In order to import a resource, you need to add the resource to your terraform file, and then use import command as described in Terraform docs: https://www.terraform.io/cli/import

For example, if you want to import an Ably app, you need to add something like the following to your terraform file:

resource "ably_app" "app0" {
  name     = "ably-tf-provider-app-0000"
  status   = "enabled"
  tls_only = true
}

and then run terraform import ably_app.app0 ably-tf-provider-app-0000.

This will import the corresponding Ably app into your state file.

It is a great idea to add example of this to the docs - we will add example of importing a resource to the docs with the next release to Terraform Registry!

[Israphel]

So apps are imported via name, understood. Thanks!

[Israphel]

doesn't work. I think you import by ID and not by name

terraform import 'module.ably-app["stage-us"].ably_app.app' 'stage-us'

terraform plan

Terraform v1.0.11
on linux_amd64
module.ably-app["stage-us"].ably_app.app: Modifying... [id=stage-us]
╷
│ Error: Error updating Resource
│ 
│   with module.ably-app["stage-us"].ably_app.app,
│   on .terraform/modules/ably-app/main.tf line 2, in resource "ably_app" "app":
│    2: resource "ably_app" "app" {
│ 
│ Could not update resource, unexpected error: /apps/stage-us: Could not find
│ app with id 'stage-us': code 40400: status code: 404 see:
│ https://help.ably.io/error/40400

Tried again with:

terraform import 'module.ably-app["stage-us"].ably_app.app' '5Y9M9Q'

and it worked.

[kavalerov]

@Israphel apologies for a late response, and thanks for highlighting this. This is actually interesting, I am now kind of surprised that my code worked for me because you are correct. Let me investigate this further - and then update the docs accordingly.

[sync-by-unito]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-3017