Add documentation for importing existing resources

[zopz]

Is your feature request related to a problem? Please describe. I discovered this after doing some manual configuration of my devices, as such I already had some of the basic resources created. It was not a huge deal for me, as I had not gotten very far, but I had to do some testing/guessing to figure out the generated IDs for my existing resources. It would be nice to have this documented like other Terraform providers offer. Random example

Describe the solution you'd like I can see importer attributes on most/all of the resource schemas, so I am fairly certain this is just documentation lacking. Please add documentation regarding retrieving IDs for importing the various resources this provider handles. I would be happy to help track these down and add to the repo, but quite honestly I've never written a provider, so I'm not where that would need to be added. If you can point me in the right direction I'd be happy to send a PR.

Additional context Was able to successfully import a routeros_ip_address with:

terraform import routeros_ip_address.router *1

[durandguru]

@GNewbury1 I have for the majority of the commands the import command. Can I just edit the md's in docs and submit an pull request?

[vaerh]

@durandguru Of course! I was grateful for the help. But there are 2 points:

• you need to edit not md files, but templates;
• import parameters can be filled in automatically (make docs), but you need to follow the correct format for placing files.

Docs generator - https://github.com/hashicorp/terraform-plugin-docs

changes for routeros_ip_address:

• the template "templates/resources/ip_address.md.tmpl" can be changed to the following form or removed altogether (the default resource template will be used)

  
  ---
  # generated by https://github.com/hashicorp/terraform-plugin-docs
  page_title: "routeros_ip_address Resource - terraform-provider-routeros"
  subcategory: "IP"
  description: |-

---

routeros_ip_address (Resource)

{{ if .HasExample -}}

Example Usage

{{ tffile .ExampleFile }} {{- end }}

Schema

Required

• address (String)
• interface (String)
• network (String)

Optional

• comment (String)
• disabled (Boolean)

Read-Only

• actual_interface (String)
• id (String) The ID of this resource.
• invalid (Boolean)

{{ if .HasImport -}}

Import

Import is supported using the following syntax: {{ codefile "shell" .ImportFile }} {{- end }}

* the example "examples/resources/ip_addrss.tf" should be moved to this path: "examples/resource/routeros_ip_address/resource.tf"
* the import code should be places to this file: "examples/resource/routeros_ip_address/import.sh"

terraform import routeros_ip_address.router *1

* and the last step is documentation generation ``` make docs ```

[vaerh]

@zopz This is not as difficult as it seems at first glance. Walk and ye shall reach )))

[javierbertoli]

@durandguru mind you share a couple of examples on how to import resources? From your example above, I assumed that all it was required was to import them using the internal id (.id). And although that worked to import some resources, it fails when trying to import those resources where the id has letters:

terraform import 'routeros_dns_record.ros["bla"]' "*1A"

fails with

│ Error: Cannot import non-existent remote object
│ 
│ While attempting to import an existing object to "routeros_dns_record.ros[\"bla\"]", the provider detected that no object exists with the given id. Only pre-existing objects
│ can be imported; check that the id is correct and that it is associated with the provider's configured region or endpoint, or use "terraform apply" to create a new remote object
│ for this resource.
╵

but when I query the API directly, I see the ID for the resource is correct:

curl -X POST \
  -u "user:password" \
  -H "content-type: application/json" \
  "https://mymikrotik/rest/ip/dns/static/getall" | jq .

I get

...
{
    ".id": "*1A",
    "address": "10.10.10.8",
    "disabled": "false",
    "dynamic": "false",
    "name": "bla.my.domain",
    "ttl": "1d"
  },
...

Can you give me a hint of what am I doing wrong?

[vaerh]

This recipe only works for importing dns resources that have an Name defined (won't work for regular expressions):

main.tf

resource "routeros_dns_record" "import_record" {
}

terraform import routeros_dns_record.import_record bla.my.domain

[javierbertoli]

Ah, excellent! Thanks, @vaerh! That did the trick. I was just checking the code to see if I could get the proper way to import things (I'm totally new at go, so I was struggling a little :smile: ) but I get, from your answer and the code, that the import parameter is the one in MetaId: PropId(whatever) right?

[vaerh]

MetaId defines the type of the key field for a specific Mikrotik resource. In some cases it must be a id number - PropId(Id) (1, 2A, ...), in others it must be a resource name - PropId(Name). In this case, the wrong key field type (Name) was initially specified, with this configuration it is impossible to import fields without FQDN.

[durandguru]

@javierbertoli , had no time yet. @vaerh mentioned you can use the name in the import if it is known with an name. If it is known with an id you have to use the id, "*1A", the letter needs to be in capital. Easy way in winbox/terminal is like this /interface/bridge/port> :put [find where interface="ether1"] if you want to filter or an complete list of all id -> /interface/bridge/port> :put [print show-ids ]

[durandguru]

MetaId defines the type of the key field for a specific Mikrotik resource. In some cases it must be a id number - PropId(Id) (1, 2A, ...), in others it must be a resource name - PropId(Name). In this case, the wrong key field type (Name) was initially specified, with this configuration it is impossible to import fields without FQDN.

Ah this probably solves the bug I have not reported yet. When a hostname has an IPv4 and IPv6 address, an apply will remove the IPv6 one.

[vaerh]

Ah this probably solves the bug I have not reported yet. When a hostname has an IPv4 and IPv6 address, an apply will remove the IPv6 one.

Traditional: I need a resource block from a TF. I'll try to watch it in a few days until there's enough time for a full immersion.

Removed duplicate comment.

[vaerh]

@javierbertoli, @durandguru Can you check the bug fix? #140

[vaerh]

@durandguru I've updated the documentation, if you still want to post import examples for resources, that would be a great help!

[javierbertoli]

@vaerh I can confirm #140 allows importing DNS entries using the .id and solves the issue where the same FQDN has two or more IPs associated to it.

[vaerh]

@javierbertoli Good news! Thanks for the feedback.

[durandguru]

I created pull request #148 . Quite new in this. Hope it is good.

[vaerh]

I looked at the request and it's good! If possible, exclude the docs directory from commit and refresh PR, because the generation script did not fully work and did not remove the meta fields:

I'll fix #149 and regenerate the documentation.

[vaerh]

@durandguru 👍 I've merged the branches, thanks a lot for the help! Documentation will be published in the next release.