[Terraform/Advanced Topics] improve documentation in import-cloudflare-resources.mdx
#20977
Conversation
Simplify the documentation about using cf-terraforming to generate and import some resources. With this changes, I hope to make the documentation easier to follow, more compact and to bring a bit more knowledge to the reader - simple use case for a bit of shell scripting to automate things.
|
Howdy and thanks for contributing to our repo. The Cloudflare team reviews new, external PRs within two (2) weeks. If it's been two weeks or longer without any movement, please tag the PR Assignees in a comment. We review internal PRs within 1 week. If it's something urgent or has been sitting without a comment, start a thread in the Developer Docs space internally. PR Change SummaryImproved the documentation for using cf-terraforming to streamline the process of importing resources into Terraform state.
Modified Files
How can I customize these reviews?Check out the Hyperlint AI Reviewer docs for more information on how to customize the review. If you just want to ignore it on this PR, you can add the Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add What is Hyperlint?Hyperlint is an AI agent that helps you write, edit, and maintain your documentation. Learn more about the Hyperlint AI reviewer and the checks that we can run on your documentation. |
| One way to ease the process of executing all the `terraform import`, is saving the result from `cf-terraforming import ...` into a shell script file. | ||
|
|
||
| > **NOTE** | ||
| > You can also just let cf-terraforming output directly to stdout (standard output, your terminal) and copy and run each of the command lines that `cf-terraforming import ...` generates for you |
There was a problem hiding this comment.
there is an alternative here with --modern-import-block with will output the idempotent import blocks instead which can then live alongside your side. they look like:
import {
to = "cloudflare_record.terraform_managed_resource_3c0b456bc2aa443089c5f40f45f51b31"
id = "1109d899a5ff5fd74bc01e581693685b/3c0b456bc2aa443089c5f40f45f51b31"
}full docs: https://developer.hashicorp.com/terraform/language/import
There was a problem hiding this comment.
@jacobbednarz yeah, it is an alternative. But depending on what people want to do, it might be less clean.
For the purpose of having a backup of the cloudflare settings for example.
Can I add as an alternative? And not replace entirely?
| One way to ease the process of executing all the `terraform import`, is saving the result from `cf-terraforming import ...` into a shell script file. | ||
|
|
||
| > **NOTE** | ||
| > You can also just let cf-terraforming output directly to stdout (standard output, your terminal) and copy and run each of the command lines that `cf-terraforming import ...` generates for you |
There was a problem hiding this comment.
we should avoid words like "just" and shortened words where we can be more explicit.
| > You can also just let cf-terraforming output directly to stdout (standard output, your terminal) and copy and run each of the command lines that `cf-terraforming import ...` generates for you | |
| > You can also let cf-terraforming output directly to standard output in your terminal and copy and run each of the command lines that `cf-terraforming import ...` generates for you |
There was a problem hiding this comment.
@jacobbednarz
My intention with stdout is because it's also a word that is widely used in tools, compilers, code and Linux.
What if I flip that into "standard output (stdout)"?
| ``` | ||
| 2. Copy each `terraform import ...` command included in the output and run it. Terraform will import each resource individually into Terraform state. | ||
| This new file - `to-import.sh` - will have valid the necessary commands `terraform import ...` to import into the TF. state all the previously generated resources. |
There was a problem hiding this comment.
this sentence doesn't really read well for me. couple of stand outs:
- don't shorten to "TF", let's use the correct names
- we should clean up the usages of
-and the period in the middle of the sentence.
|
|
||
| When you run `cf-terraforming import ...`, you will obtain a list of `terraform import ...` commands that you must run manually afterward to import those resources into Terraform state. This is currently a manual process, but it may be automated in the future. | ||
|
|
||
| One way to ease the process of executing all the `terraform import`, is saving the result from `cf-terraforming import ...` into a shell script file. |
There was a problem hiding this comment.
we're getting ready to revamp this entire tutorial with the goal of less bash. i don't think we really want to be adding more right now. cc @jhutchings1
There was a problem hiding this comment.
@jacobbednarz From my recent use of cf-terraforming, I haven't found a way to not script the use of it. There is currently no way to generate all the resources with the tool in just one command. There was before an all argument that you could give to it but there is not now.
So I believe that scripting with shell script is a well known and widely accepted way of scripting simple small things vs using something like Python or other scripting languages.
Also, I think that we should have a reference to the Terraform tool's -generate-config-out argument since that also has a somewhat similar result to cf-terraforming. What do you think?
Related to this: Ruleset can't be fully generated as of yet as per this issue. The fix a person found was to import the ruleset before generating the rest of it (with the rules). So both ways, with the modern import block or the command way can be acceptable for different use cases.
There was a problem hiding this comment.
@gui-baeta Thanks for all your work here! We've been working on a bunch of changes around cf-terraforming recently, so this is timely. My broader question on this is whether we think there's a good reason not to default our guidance to focus on the --modern-import-block options? Asking folks to run so many bash commands seems like it adds a bit of complexity. I know I struggled with this step in my own testing.
There was a problem hiding this comment.
@jhutchings1 Yeah, it can get really convoluted and confusing really quickly.
I agree.
I have been testing more throughout the day and I guess that the problem I and others detected on that cf-terraforming issue I reference, should be fixed in cf-terraforming and/or the terraform provider.
The use of shell commands, even if they are only to interact with terraform with its basic commands (in this case the import via commandline), depending on the context it can be a dirty fix to the end goal which is to be able to use cf-terraforming directly and arrive at a just works tool solution.
So, for this PR, documenting the use of --modern-import-block would be the best approach? I can do that, if that sounds good to you guys.
There was a problem hiding this comment.
I think documenting --modern-import-block is the most sensible approach, yes. Thank you for leaning in like you have. Really appreciate the effort you've put in here! cc: @dcpena
|
Will be closing this due to inactivity. If this work still needs to be done, I'd recommend opening a new PR to be better in sync with production. |
5 participants
Summary
Simplify the documentation about using cf-terraforming to generate and import some resources.
Why
With this changes, I hope to make the documentation easier to follow, more compact and to bring a bit more knowledge to the reader - simple use case for a bit of shell scripting to automate things.
How/What was done
This PR changes the explanation of importing resources to the TF state:
terraform import ...commands to saving the newline-separated output ofcf-terraforming importinto a file.