github.com/GoogleCloudPlatform/terraformer@v0.8.18/README.md (about) 1 # Terraformer 2 3 [](https://github.com/GoogleCloudPlatform/terraformer/actions/workflows/test.yml) 4 [](https://github.com/GoogleCloudPlatform/terraformer/actions/workflows/linter.yml) 5 [](https://goreportcard.com/report/github.com/GoogleCloudPlatform/terraformer) 6 [](https://aur.archlinux.org/packages/terraformer/) 7 [](https://formulae.brew.sh/formula/terraformer) 8 9 A CLI tool that generates `tf`/`json` and `tfstate` files based on existing infrastructure 10 (reverse Terraform). 11 12 * Disclaimer: This is not an official Google product 13 * Created by: Waze SRE 14 15  16 17 # Table of Contents 18 - [Demo GCP](#demo-gcp) 19 - [Capabilities](#capabilities) 20 - [Installation](#installation) 21 - [Supported Providers](/docs) 22 * Major Cloud 23 * [Google Cloud](/docs/gcp.md) 24 * [AWS](/docs/aws.md) 25 * [Azure](/docs/azure.md) 26 * [AliCloud](/docs/alicloud.md) 27 * [IBM Cloud](/docs/ibmcloud.md) 28 * Cloud 29 * [DigitalOcean](/docs/digitalocean.md) 30 * [Equinix Metal](/docs/equinixmetal.md) 31 * [Fastly](/docs/fastly.md) 32 * [Heroku](/docs/heroku.md) 33 * [Linode](/docs/linode.md) 34 * [NS1](/docs/ns1.md) 35 * [OpenStack](/docs/openstack.md) 36 * [TencentCloud](/docs/tencentcloud.md) 37 * [Vultr](/docs/vultr.md) 38 * [Yandex.Cloud](/docs/yandex.md) 39 * Infrastructure Software 40 * [Kubernetes](/docs/kubernetes.md) 41 * [OctopusDeploy](/docs/octopus.md) 42 * [RabbitMQ](/docs/rabbitmq.md) 43 * Network 44 * [Cloudflare](/docs/cloudflare.md) 45 * [PAN-OS](/docs/panos.md) 46 * VCS 47 * [Azure DevOps](/docs/azuredevops.md) 48 * [GitHub](/docs/github.md) 49 * [Gitlab](/docs/gitlab.md) 50 * Monitoring & System Management 51 * [Datadog](/docs/datadog.md) 52 * [New Relic](/docs/relic.md) 53 * [PagerDuty](/docs/pagerduty.md) 54 * Community 55 * [Keycloak](/docs/keycloak.md) 56 * [Logz.io](/docs/logz.md) 57 * [Commercetools](/docs/commercetools.md) 58 * [Mikrotik](/docs/mikrotik.md) 59 * [Xen Orchestra](/docs/xen.md) 60 * [GmailFilter](/docs/gmailfilter.md) 61 * [Grafana](/docs/grafana.md) 62 * [Vault](/docs/vault.md) 63 * Identity 64 * [Okta](/docs/okta.md) 65 - [Contributing](#contributing) 66 - [Developing](#developing) 67 - [Infrastructure](#infrastructure) 68 - [Stargazers over time](#stargazers-over-time) 69 70 ## Demo GCP 71 [](https://asciinema.org/a/243961) 72 73 ## Capabilities 74 75 1. Generate `tf`/`json` + `tfstate` files from existing infrastructure for all 76 supported objects by resource. 77 2. Remote state can be uploaded to a GCS bucket. 78 3. Connect between resources with `terraform_remote_state` (local and bucket). 79 4. Save `tf`/`json` files using a custom folder tree pattern. 80 5. Import by resource name and type. 81 6. Support terraform 0.13 (for terraform 0.11 use v0.7.9). 82 83 Terraformer uses Terraform providers and is designed to easily support newly added resources. 84 To upgrade resources with new fields, all you need to do is upgrade the relevant Terraform providers. 85 ``` 86 Import current state to Terraform configuration from a provider 87 88 Usage: 89 import [provider] [flags] 90 import [provider] [command] 91 92 Available Commands: 93 list List supported resources for a provider 94 95 Flags: 96 -b, --bucket string gs://terraform-state 97 -c, --connect (default true) 98 -ะก, --compact (default false) 99 -x, --excludes strings firewalls,networks 100 -f, --filter strings compute_firewall=id1:id2:id4 101 -h, --help help for google 102 -O, --output string output format hcl or json (default "hcl") 103 -o, --path-output string (default "generated") 104 -p, --path-pattern string {output}/{provider}/ (default "{output}/{provider}/{service}/") 105 --projects strings 106 -z, --regions strings europe-west1, (default [global]) 107 -r, --resources strings firewall,networks or * for all services 108 -s, --state string local or bucket (default "local") 109 -v, --verbose verbose mode 110 -n, --retry-number number of retries to perform if refresh fails 111 -m, --retry-sleep-ms time in ms to sleep between retries 112 113 Use " import [provider] [command] --help" for more information about a command. 114 ``` 115 #### Permissions 116 117 The tool requires read-only permissions to list service resources. 118 119 #### Resources 120 121 You can use `--resources` parameter to tell resources from what service you want to import. 122 123 To import resources from all services, use `--resources="*"` . If you want to exclude certain services, you can combine the parameter with `--excludes` to exclude resources from services you don't want to import e.g. `--resources="*" --excludes="iam"`. 124 125 #### Filtering 126 127 Filters are a way to choose which resources `terraformer` imports. It's possible to filter resources by its identifiers or attributes. Multiple filtering values are separated by `:`. If an identifier contains this symbol, value should be wrapped in `'` e.g. `--filter=resource=id1:'project:dataset_id'`. Identifier based filters will be executed before Terraformer will try to refresh remote state. 128 129 Use `Type` when you need to filter only one of several types of resources. Multiple filters can be combined when importing different resource types. An example would be importing all AWS security groups from a specific AWS VPC: 130 ``` 131 terraformer import aws -r sg,vpc --filter Type=sg;Name=vpc_id;Value=VPC_ID --filter Type=vpc;Name=id;Value=VPC_ID 132 ``` 133 Notice how the `Name` is different for `sg` than it is for `vpc`. 134 135 ##### Resource ID 136 137 Filtering is based on Terraform resource ID patterns. To find valid ID patterns for your resource, check the import part of the [Terraform documentation][terraform-providers]. 138 139 [terraform-providers]: https://www.terraform.io/docs/providers/ 140 141 Example usage: 142 143 ``` 144 terraformer import aws --resources=vpc,subnet --filter=vpc=myvpcid --regions=eu-west-1 145 ``` 146 Will only import the vpc with id `myvpcid`. This form of filters can help when it's necessary to select resources by its identifiers. 147 148 ##### Field name only 149 150 It is possible to filter by specific field name only. It can be used e.g. when you want to retrieve resources only with a specific tag key. 151 152 Example usage: 153 154 ``` 155 terraformer import aws --resources=s3 --filter="Name=tags.Abc" --regions=eu-west-1 156 ``` 157 Will only import the s3 resources that have tag `Abc`. This form of filters can help when the field values are not important from filtering perspective. 158 159 ##### Field with dots 160 161 It is possible to filter by a field that contains a dot. 162 163 Example usage: 164 165 ``` 166 terraformer import aws --resources=s3 --filter="Name=tags.Abc.def" --regions=eu-west-1 167 ``` 168 Will only import the s3 resources that have tag `Abc.def`. 169 170 #### Planning 171 172 The `plan` command generates a planfile that contains all the resources set to be imported. By modifying the planfile before running the `import` command, you can rename or filter the resources you'd like to import. 173 174 The rest of subcommands and parameters are identical to the `import` command. 175 176 ``` 177 $ terraformer plan google --resources=networks,firewall --projects=my-project --regions=europe-west1-d 178 (snip) 179 180 Saving planfile to generated/google/my-project/terraformer/plan.json 181 ``` 182 183 After reviewing/customizing the planfile, begin the import by running `import plan`. 184 185 ``` 186 $ terraformer import plan generated/google/my-project/terraformer/plan.json 187 ``` 188 189 ### Resource structure 190 191 Terraformer by default separates each resource into a file, which is put into a given service directory. 192 193 The default path for resource files is `{output}/{provider}/{service}/{resource}.tf` and can vary for each provider. 194 195 It's possible to adjust the generated structure by: 196 1. Using `--compact` parameter to group resource files within a single service into one `resources.tf` file 197 2. Adjusting the `--path-pattern` parameter and passing e.g. `--path-pattern {output}/{provider}/` to generate resources for all services in one directory 198 199 It's possible to combine `--compact` `--path-pattern` parameters together. 200 201 ### Installation 202 203 From source: 204 1. Run `git clone <terraformer repo> && cd terraformer/` 205 2. Run `go mod download` 206 3. Run `go build -v` for all providers OR build with one provider 207 `go run build/main.go {google,aws,azure,kubernetes,etc}` 208 4. Run ```terraform init``` against a ```versions.tf``` file to install the plugins required for your platform. For example, if you need plugins for the google provider, ```versions.tf``` should contain: 209 210 ``` 211 terraform { 212 required_providers { 213 google = { 214 source = "hashicorp/google" 215 } 216 } 217 required_version = ">= 0.13" 218 } 219 ``` 220 Or alternatively 221 222 * Copy your Terraform provider's plugin(s) to folder 223 `~/.terraform.d/plugins/{darwin,linux}_amd64/`, as appropriate. 224 225 From Releases: 226 227 * Linux 228 229 ``` 230 export PROVIDER={all,google,aws,kubernetes} 231 curl -LO https://github.com/GoogleCloudPlatform/terraformer/releases/download/$(curl -s https://api.github.com/repos/GoogleCloudPlatform/terraformer/releases/latest | grep tag_name | cut -d '"' -f 4)/terraformer-${PROVIDER}-linux-amd64 232 chmod +x terraformer-${PROVIDER}-linux-amd64 233 sudo mv terraformer-${PROVIDER}-linux-amd64 /usr/local/bin/terraformer 234 ``` 235 * MacOS 236 237 ``` 238 export PROVIDER={all,google,aws,kubernetes} 239 curl -LO https://github.com/GoogleCloudPlatform/terraformer/releases/download/$(curl -s https://api.github.com/repos/GoogleCloudPlatform/terraformer/releases/latest | grep tag_name | cut -d '"' -f 4)/terraformer-${PROVIDER}-darwin-amd64 240 chmod +x terraformer-${PROVIDER}-darwin-amd64 241 sudo mv terraformer-${PROVIDER}-darwin-amd64 /usr/local/bin/terraformer 242 ``` 243 244 #### Using a package manager 245 246 If you want to use a package manager: 247 248 - [Homebrew](https://brew.sh/) users can use `brew install terraformer`. 249 - [MacPorts](https://www.macports.org/) users can use `sudo port install terraformer`. 250 - [Chocolatey](https://chocolatey.org/) users can use `choco install terraformer`. 251 252 Links to download Terraform Providers: 253 * Major Cloud 254 * Google Cloud provider >2.11.0 - [here](https://releases.hashicorp.com/terraform-provider-google/) 255 * AWS provider >2.25.0 - [here](https://releases.hashicorp.com/terraform-provider-aws/) 256 * Azure provider >1.35.0 - [here](https://releases.hashicorp.com/terraform-provider-azurerm/) 257 * Alicloud provider >1.57.1 - [here](https://releases.hashicorp.com/terraform-provider-alicloud/) 258 * Cloud 259 * DigitalOcean provider >1.9.1 - [here](https://releases.hashicorp.com/terraform-provider-digitalocean/) 260 * Heroku provider >2.2.1 - [here](https://releases.hashicorp.com/terraform-provider-heroku/) 261 * Linode provider >1.8.0 - [here](https://releases.hashicorp.com/terraform-provider-linode/) 262 * OpenStack provider >1.21.1 - [here](https://releases.hashicorp.com/terraform-provider-openstack/) 263 * TencentCloud provider >1.50.0 - [here](https://releases.hashicorp.com/terraform-provider-tencentcloud/) 264 * Vultr provider >1.0.5 - [here](https://releases.hashicorp.com/terraform-provider-vultr/) 265 * Yandex provider >0.42.0 - [here](https://releases.hashicorp.com/terraform-provider-yandex/) 266 * Infrastructure Software 267 * Kubernetes provider >=1.9.0 - [here](https://releases.hashicorp.com/terraform-provider-kubernetes/) 268 * RabbitMQ provider >=1.1.0 - [here](https://releases.hashicorp.com/terraform-provider-rabbitmq/) 269 * Network 270 * Cloudflare provider >1.16 - [here](https://releases.hashicorp.com/terraform-provider-cloudflare/) 271 * Fastly provider >0.16.1 - [here](https://releases.hashicorp.com/terraform-provider-fastly/) 272 * NS1 provider >1.8.3 - [here](https://releases.hashicorp.com/terraform-provider-ns1/) 273 * PAN-OS provider >= 1.8.3 - [here](https://github.com/PaloAltoNetworks/terraform-provider-panos) 274 * VCS 275 * GitHub provider >=2.2.1 - [here](https://releases.hashicorp.com/terraform-provider-github/) 276 * Monitoring & System Management 277 * Datadog provider >2.1.0 - [here](https://releases.hashicorp.com/terraform-provider-datadog/) 278 * New Relic provider >2.0.0 - [here](https://releases.hashicorp.com/terraform-provider-newrelic/) 279 * Pagerduty >=1.9 - [here](https://releases.hashicorp.com/terraform-provider-pagerduty/) 280 * Community 281 * Keycloak provider >=1.19.0 - [here](https://github.com/mrparkers/terraform-provider-keycloak/) 282 * Logz.io provider >=1.1.1 - [here](https://github.com/jonboydell/logzio_terraform_provider/) 283 * Commercetools provider >= 0.21.0 - [here](https://github.com/labd/terraform-provider-commercetools) 284 * Mikrotik provider >= 0.2.2 - [here](https://github.com/ddelnano/terraform-provider-mikrotik) 285 * Xen Orchestra provider >= 0.18.0 - [here](https://github.com/ddelnano/terraform-provider-xenorchestra) 286 * GmailFilter provider >= 1.0.1 - [here](https://github.com/yamamoto-febc/terraform-provider-gmailfilter) 287 * Vault provider - [here](https://github.com/hashicorp/terraform-provider-vault) 288 289 Information on provider plugins: 290 https://www.terraform.io/docs/configuration/providers.html 291 292 293 294 ## Contributing 295 296 If you have improvements or fixes, we would love to have your contributions. 297 Please read CONTRIBUTING.md for more information on the process we would like 298 contributors to follow. 299 300 ## Developing 301 302 Terraformer was built so you can easily add new providers of any kind. 303 304 Process for generating `tf`/`json` + `tfstate` files: 305 306 1. Call GCP/AWS/other api and get list of resources. 307 2. Iterate over resources and take only the ID (we don't need mapping fields!). 308 3. Call to provider for readonly fields. 309 4. Call to infrastructure and take tf + tfstate. 310 311 ## Infrastructure 312 313 1. Call to provider using the refresh method and get all data. 314 2. Convert refresh data to go struct. 315 3. Generate HCL file - `tf`/`json` files. 316 4. Generate `tfstate` files. 317 318 All mapping of resource is made by providers and Terraform. Upgrades are needed only 319 for providers. 320 321 ##### GCP compute resources 322 323 For GCP compute resources, use generated code from 324 `providers/gcp/gcp_compute_code_generator`. 325 326 To regenerate code: 327 328 ``` 329 go run providers/gcp/gcp_compute_code_generator/*.go 330 ``` 331 332 ### Similar projects 333 334 #### [terraforming](https://github.com/dtan4/terraforming) 335 336 ##### Terraformer Benefits 337 338 * Simpler to add new providers and resources - already supports AWS, GCP, GitHub, Kubernetes, and Openstack. Terraforming supports only AWS. 339 * Better support for HCL + tfstate, including updates for Terraform 0.12. 340 * If a provider adds new attributes to a resource, there is no need change Terraformer code - just update the Terraform provider on your laptop. 341 * Automatically supports connections between resources in HCL files. 342 343 ##### Comparison 344 345 Terraforming gets all attributes from cloud APIs and creates HCL and tfstate files with templating. Each attribute in the API needs to map to attribute in Terraform. Generated files from templating can be broken with illegal syntax. When a provider adds new attributes the terraforming code needs to be updated. 346 347 Terraformer instead uses Terraform provider files for mapping attributes, HCL library from Hashicorp, and Terraform code. 348 349 Look for S3 support in terraforming here and official S3 support 350 Terraforming lacks full coverage for resources - as an example you can see that 70% of S3 options are not supported: 351 352 * terraforming - https://github.com/dtan4/terraforming/blob/master/lib/terraforming/template/tf/s3.erb 353 * official S3 support - https://www.terraform.io/docs/providers/aws/r/s3_bucket.html 354 355 ## Stargazers over time 356 357 [](https://starchart.cc/GoogleCloudPlatform/terraformer)