Terrafy a single resource

README.md

@@ -44,9 +44,27 @@ Although `aztfy` depends on `terraform`, it is not required to have `terraform`
 
 Follow the [authentication guide](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure) from the Terraform AzureRM provider to authenticate to Azure.
 
-Then you can go ahead and run `aztfy [option] <resource group name>`. The tool can run in two modes: interactive mode and batch mode, depending on whether `--batch`/`-b` is specified.
+Then you can go ahead and run `aztfy resource [option] <resource id>` or `aztfy resource-group [option] <resource group name>` to import either a single resource, or a resource group and its including resources.
 
-### Interactive Mode
+### Terrafy a Single Resource
+
+`aztfy resource [option] <resource id>` terrafies a single resource by its Azure control plane ID.
+
+E.g.
+
+```shell
+aztfy resource /subscriptions/0000/resourceGroups/rg1/providers/Microsoft.Compute/virtualMachines/vm1
+```
+
+The command will automatically identify the Terraform resource type (e.g. correctly identifies above resource as `azurerm_linux_virtual_machine`), and import it into state file and generate the Terraform configuration.
+
+> ❗Currently, data plane only resources are not supported.
+
+### Terrafy a Resource Group
+
+`aztfy resource-group [option] <resource group name>` terrafies a resource group and its including resources by its name. Depending on whether `--batch` is used, it can work in either interactive mode or batch mode.
+
+#### Interactive Mode
 
 In interactive mode, `aztfy` list all the resources resides in the specified resource group. For each resource, user is expected to input the Terraform resource address in form of `<resource type>.<resource name>` (e.g. `azurerm_linux_virtual_machine.test`). Users can press `r` to see the possible resource type(s) for the selected import item (though this is not guaranteed to be 100% accurate). In case there is exactly one resource type match for the import item, that resource type will be automatically filled in the text input for the users, with a 💡 line prefix as an indication.
 
@@ -56,11 +74,9 @@ In some cases, there are Azure resources that have no corresponding Terraform re
 
 After going through all the resources to be imported, users press `w` to instruct `aztfy` to proceed importing resources into Terraform state and generating the Terraform configuration.
 
-> 💡 `aztfy` will run `terraform import` under the hood to import each resource. Then it will run [`tfadd`](https://github.com/magodo/tfadd) to generate the Terraform template for each imported resource. Whereas there are kinds of [quirks](https://github.com/apparentlymart/terrafy/blob/main/docs/quirks.md) causing the output of `tfadd` to be an invalid Terraform template in most cases. `aztfy` will leverage extra knowledge from the provider (which is generated from the provider codebase) to further manipulate the template, to make it pass the Terraform validations against the provider.
-> 
-> As the last step, `aztfy` will leverage the ARM template to inject dependencies between each resource. This makes the generated Terraform template to be useful.
+As the last step, `aztfy` will leverage the ARM template to inject dependencies between each resource. This makes the generated Terraform template to be useful.
 
-### Batch Mode
+#### Batch Mode
 
 In batch mode, instead of interactively specifying the mapping from Azurem resource id to the Terraform resource address, users are expected to provide that mapping via the resource mapping file, with the following format:
 
@@ -108,6 +124,10 @@ One limitation of doing so is users can't import resources to existing state fil
 
 This means if the output directory has an active Terraform workspace, i.e. there exists a state file, any resource imported by the `aztfy` will be imported into that state file. Especially, the file generated by `aztfy` in this case will be named differently than normal, where each file will has `.aztfy` suffix before the extension (e.g. `main.aztfy.tf`), to avoid potential file name conflicts. If you run `aztfy --append` multiple times, the generated config in `main.aztfy.tf` will be appended in each run.
 
+## How it Works
+
+`aztfy` leverage [`aztft`](https://github.com/magodo/aztft) to identify the Terraform resource type on its Azure resource ID. Then it runs `terraform import` under the hood to import each resource. Afterwards, it runs [`tfadd`](https://github.com/magodo/tfadd) to generate the Terraform template for each imported resource.
+
 ## Demo
 
 [![asciicast](https://asciinema.org/a/475516.svg)](https://asciinema.org/a/475516)
@@ -138,3 +158,5 @@ Another reason is that an Azure resource can be a property of its parent resourc
 
 - [The aztfy Github Page](https://azure.github.io/aztfy): Everything about aztfy, including comparisons with other existing import solutions.
 - [Kyle Ruddy's Blog about aztfy](https://www.kmruddy.com/2022/terrafy-existing-azure-resources/): A live use of `aztfy`, explaining the pros and cons.
+- [aztft](https://github.com/magodo/aztft): A Go program and library for identifying the correct Terraform AzureRM provider resource type on the Azure resource id.
+- [tfadd](https://github.com/magodo/tfadd): A Go program and library for generating Terraform configuration from Terraform state.