Skip to content

Commit

Permalink
updated the readme based on my testing
Browse files Browse the repository at this point in the history
  • Loading branch information
Simone Bennett committed Oct 20, 2021
1 parent e6ca9a0 commit 4b6692e
Showing 1 changed file with 29 additions and 6 deletions.
35 changes: 29 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,31 @@

A tool to bring your existing Azure resources under the management of Terraform.


## Goal

Import all the AzureRM provider supported resources inside the resource group that the user specifies into to Terraform state, and generate a valid Terraform configuration. After running this tool, the Terraform state and configuration should be consistent with the resources' remote state, i.e. `terraform plan` shows no diff. The user then is able to use Terraform to manage these resources.
* Import all the AzureRM provider supported resources inside the resource group that the user specifies into to Terraform state
* Generate a valid Terraform configuration
* After running this tool, the Terraform state and configuration should be consistent with the resources' remote state, i.e., `terraform plan` shows no diff. The user then can use Terraform to manage these resources.


## Prerequisites
For Windows Devices:
* 7zip to open the installer
* Install the Azure CLI
* [Install Terraform and set the path]( https://docs.microsoft.com/en-us/azure/developer/terraform/get-started-windows-powershell?tabs=azure-powershell)
* Create a service principal


## Install
* Precompiled binaries for Windows, OS X, Linux are available at [Releases](https://github.com/magodo/aztfy/releases).
* Windows: Download the latest binary, extract the files using 7zip

* Linux:
```bash
go install github.com/magodo/aztfy@latest
```

### How to get a precompiled binary
Precompiled binaries for Windows, OS X, Linux are available at [Releases](https://github.com/magodo/aztfy/releases).

## Usage

Expand All @@ -22,22 +35,30 @@ Follow the [authentication guide](https://registry.terraform.io/providers/hashic
Then you can go ahead and run:

```shell
$ az group list --output table
$ aztfy <resource_group_name>
```

The tool will then list all the resources resides in the specified resource group. For each of them, it will ask the user to input the Terraform resource type and name for each Azure resource in the form of `<resource type>.<resource name>` (e.g. `azurerm_linux_virtual_machine.example`).
The tool will then list all the resources resides in the specified resource group. For each resource, aztfy will ask the user to input the Terraform resource type and name for each Azure resource in the form of `<resource type>.<resource name>` (e.g. `azurerm_linux_virtual_machine.example`).

Especially, in some cases there are resources that have no corresponding terraform resource (e.g. due to lacks of Terraform support), or some resource might be created as a side effect of provisioning another resource (e.g. the Disk resource is created automatically when provisioning a VM). In these cases, you can directly press enter without typing anything to skip that resource.
Press `enter` on each line to edit or skip the resource.

After getting the input from user, `aztfy` will run `terraform import` to import each resource. Then it will run `terraform add -from-state` to generate the Terraform template for each imported resource. Where as there are kinds of [limitations](https://github.com/apparentlymart/terrafy/blob/main/docs/quirks.md) causing the output of `terraform add` 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.
NB: In some cases, there are resources that have no corresponding terraform resource (e.g. due to lacks of Terraform support), or some resource might be created as a side effect of provisioning another resource (e.g. the Disk resource is created automatically when provisioning a VM). In these cases, you can directly press enter without typing anything to skip that resource.

After getting the input from user, `aztfy` will run `terraform import` to import each resource. Then it will run `terraform add -from-state` to generate the Terraform template for each imported resource. Whereas there are kinds of [limitations](https://github.com/apparentlymart/terrafy/blob/main/docs/quirks.md) causing the output of `terraform add` 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 a last step, `aztfy` will leverage the ARM template to inject dependencies between each resource. This makes the generated Terraform template to be useful.

## To Test
To test run terraform plan on the main.tf file that has been created by aztfy
The file is created in %AppData%\Local\aztfy\<resource group name>

## Demo

[![asciicast](https://asciinema.org/a/iPTGS6E2CSxpYPtbPQhWmxLdu.svg)](https://asciinema.org/a/iPTGS6E2CSxpYPtbPQhWmxLdu)

## Limitation
When resources have a long name, they are cut off in the aztfy UI and will need to be skipped and manually added in later.[issue17]( https://github.com/magodo/aztfy/issues/17)

Some Azure resources are modeled differently in AzureRM provider, which means there might be N:M mapping between the Azure resources and the Terraform resources.

Expand All @@ -46,3 +67,5 @@ For example, the `azurerm_lb_backend_address_pool_address` is actually a propert
Another popular case is that in the AzureRM provider, there are a bunch of "association" resources, e.g. the `azurerm_network_interface_security_group_association`. These "association" resources represent the association relationship between two Terraform resources (in this case they are `azurerm_network_interface` and `azurerm_network_security_group`). They also have some synthetic resource ID, e.g. `/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mygroup1/providers/microsoft.network/networkInterfaces/example|/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/group1/providers/Microsoft.Network/networkSecurityGroups/group1`.

Currently, this tool only works on the assumption that there is 1:1 mapping between Azure resources and the Terraform resources.


0 comments on commit 4b6692e

Please sign in to comment.