Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Consider replacing terraform with pulumi globally #2251

Open
guineveresaenger opened this issue Jul 25, 2024 · 2 comments
Open

docs: Consider replacing terraform with pulumi globally #2251

guineveresaenger opened this issue Jul 25, 2024 · 2 comments
Labels
area/docsgen Issues with docs capture or example rendering, historically part of pkg/tfgen kind/enhancement Improvements or new features

Comments

@guineveresaenger
Copy link
Contributor

guineveresaenger commented Jul 25, 2024

The current status quo for registry docs "sections" (not including actual code snippets; see #2248 for that) is as follows:

  1. The bridge detects the mention of "Terraform"
  2. The bridge elides the entire section from the schema
  3. We miss out on a lot of examples and top-level content

Previously, the reason we elide sections that include the word "Terraform" was that we assumed such a section would very specifically talk about Terraform concepts. In practice, this is often untrue, and we lose quite a lot of content with this strategy.

We should consider a default edit rule that is a bit wider or even global in scope.

Note We need to consider that the detection logic for transforming pulumi import currently relies on seeing terraform import in the passed-in docs section. That would need to change.

@guineveresaenger guineveresaenger added kind/bug Some behavior is incorrect or out of spec kind/enhancement Improvements or new features labels Jul 25, 2024
@pulumi-bot pulumi-bot added the needs-triage Needs attention from the triage team label Jul 25, 2024
@guineveresaenger guineveresaenger removed the needs-triage Needs attention from the triage team label Jul 26, 2024
@guineveresaenger guineveresaenger changed the title docs: Consider replacing terraform with `pulumi globally docs: Consider replacing terraform with pulumi globally Jul 26, 2024
@iwahbe iwahbe added area/docs Improvements or additions to docs for this repo area/docsgen Issues with docs capture or example rendering, historically part of pkg/tfgen and removed kind/bug Some behavior is incorrect or out of spec area/docs Improvements or additions to docs for this repo labels Sep 12, 2024
@flostadler
Copy link
Contributor

There is an instance of this biting AWS users pretty hard: pulumi/pulumi-aws#4872
This is a rather dangerous resource, that has multiple warnings in Terraform and we dropped them because they included the word Terraform.

Having a global rule would've been better here. Even mentioning Terraform instead of Pulumi would've been better in this case

flostadler added a commit to pulumi/pulumi-aws that referenced this issue Dec 4, 2024
…cs (#4882)

The `iam.PolicyAttachment` resource assumes exclusive management of IAM
policies. Across the entire AWS account, all of the users/roles/groups
to which a single policy is attached must be declared by a single
`iam.PolicyAttachment` resource. This means that even any
users/roles/groups that have the attached policy via any other mechanism
(including other Pulumi resources) will have that attached policy
revoked by this resource when it's deleted.

This is quite surprising to users, especially because there's no mention
of it in the [Pulumi
docs](https://www.pulumi.com/registry/packages/aws/api-docs/iam/policyattachment).

The [warnings from the upstream
provider](https://registry.terraform.io/providers/hashicorp/aws/5.78.0/docs/resources/iam_policy_attachment)
were not carried into Pulumi docs because they included `Terraform` and
were elided. This fixes it.

Fixes #4872
Relates to pulumi/pulumi-terraform-bridge#2251
@guineveresaenger
Copy link
Contributor Author

Another example of missing documentation: pulumi/pulumi-gcp#2739; in this case the affected section is a field description, not a top-level doc, but the same thoughts apply.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/docsgen Issues with docs capture or example rendering, historically part of pkg/tfgen kind/enhancement Improvements or new features
Projects
None yet
Development

No branches or pull requests

4 participants