Missing details about Component Resource supported options (and their inheritance)

[aureq]

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

Currently, our document does cover resource option but there's no mention about supported options for a Component Resource. While all are accepted, a few of them generate a warning and for others it may seem unclear of said options are working as intended.

Affected area/feature

• docs

[aureq]

Currently, I have found the following information in our code.

Unsupported resource options

According to this test, the resource options aren't supported.

• additionalSecretOutputs
• customTimeouts
• ignoreChanges
• retainOnDelete
• replaceOnChanges

I also think the one below isn't supported for a Component Resource due to the nature of a Component Resource.

• import
• provider (according to @ringods )

Other resource options

The list below and the associated comment is based on tribal knowledge / conversations but it's unclear.

• aliases
• deleteBeforeReplace
• dependsOn I've been told this doesn't work.
• parent Not inherited onto sub-resources
• protect Seems passed down to sub-resources
• providers This should work according to our doc. It should be passed onto sub-resources as well.
• transformations Not tested
• version Probably not supported but it's unclear

[MitchellGerdisch]

FWIW, regarding the note about dependsOn above, it does appear to work with a component resource as expected. For example, this code:

const storageAccount1 = new storage.StorageAccount("sa1", {
    resourceGroupName: resourceGroup.name,
    sku: {
        name: storage.SkuName.Standard_LRS,
    },
    kind: storage.Kind.StorageV2,
});

const storageInfra = new StorageInfra("si1", {
    resourceGroupName: resourceGroup.name
}, {dependsOn: [storageAccount1]})

did not start building the storageinfra resource or its children until storageAccount1 was created..

[aureq]

@pierskarsenbarg for visibility

[EronWright]

Some docs were added along these lines: https://github.com/pulumi/docs/commit/9da1943043145b75e547da56e9e1016b8bef7885

[jkodroff]

We need to do an audit of what is and what is not answered in the above questions.

@claude, could you look into this and comment on the issue with what you find?

[claude[bot]]

Claude finished @jkodroff's task —— View job

---

Component Resource Options Documentation Audit

I've completed a comprehensive audit of our current Component Resource documentation against the questions raised in this issue. Here are my findings:

Todo List:

• [x] Read repository setup instructions and understand codebase structure
• [x] Find and analyze current Component Resource documentation
• [x] Cross-reference documentation against the specific resource options questions from the issue
• [x] Identify gaps between what's documented vs. what users need to know
• [x] Document findings and recommendations

---

Current Documentation Status

✅ Well Documented - Resource Options That DON'T Work with Component Resources

The following resource options clearly state they don't work with component resources:

1. additionalSecretOutputs - content/docs/iac/concepts/options/additionalsecretoutputs.md:92

   • ⚠️ Warning: "The additionalSecretOutputs resource option does not apply to component resources, and will not have the intended effect."

2. customTimeouts - content/docs/iac/concepts/options/customtimeouts.md:97

   • ⚠️ Warning: "The customTimeouts resource option does not apply to component resources, and will not have the intended effect."

3. ignoreChanges - content/docs/iac/concepts/options/ignorechanges.md:103

   • ℹ️ Info: "The ignoreChanges resource option does not apply to inputs to component resources. If ignoreChanges is passed to a component resource, it is up to that component's implementation to decide what if anything it will do."

4. replaceOnChanges - content/docs/iac/concepts/options/replaceonchanges.md:137

   • ⚠️ Warning: "The replaceOnChanges resource option does not apply to component resources, and will not have the intended effect."

5. retainOnDelete - content/docs/iac/concepts/options/retainondelete.md:93

   • ⚠️ Warning: "The retainOnDelete resource option does not apply to component resources, and will not have the intended effect."

✅ Well Documented - Resource Options That DO Work with Component Resources

1. aliases - content/docs/iac/concepts/options/aliases.md:18

   • ✅ Explicitly mentions: "provides a list of aliases for a resource or component resource"
   • ✅ Shows inheritance behavior for parent/child relationships

2. parent - content/docs/iac/concepts/options/parent.md:17,108-119

   • ✅ Explicitly mentions component resources as good parents
   • ✅ Documents inheritance of provider, aliases, protect, transformations, and transforms

3. providers - Both main component docs and providers option docs

   • ✅ Components documentation (content/docs/iac/concepts/components/_index.md:449-526) has a full section on "Inheriting Resource Providers"
   • ✅ Shows how providers option works with component resources
   • ✅ Documents inheritance from parent to child

4. transformations and transforms - Well documented as working with components

   • ✅ Documentation shows these are specifically designed for use with component resources
   • ✅ Examples show applying transforms to component resources to affect their children

---

⚠️ Documentation Gaps Identified

Missing Documentation for These Resource Options:

1. dependsOn

   • ❌ No mention in component docs about whether it works
   • ❌ The issue comment says "I've been told this doesn't work" but @MitchellGerdisch provided evidence it DOES work
   • 📝 Gap: Need to clarify and document the actual behavior

2. protect

   • ✅ Parent docs mention it's inherited (content/docs/iac/concepts/options/parent.md:114)
   • ❌ But there's no explicit documentation about using protect directly on component resources
   • 📝 Gap: Need to clarify direct usage vs inheritance

3. import

   • ❌ No documentation about whether components can be imported
   • ❌ Issue suggests this doesn't work "due to the nature of Component Resources"
   • 📝 Gap: Need to document this limitation

4. provider (singular)

   • ❌ Issue suggests this doesn't work for components, but documentation is unclear
   • ❌ We document providers (plural) but not the singular provider option
   • 📝 Gap: Need to clarify difference and document limitations

5. version

   • ❌ No documentation about whether this works with components
   • ❌ Issue says "Probably not supported but it's unclear"
   • 📝 Gap: Need to clarify and document

6. deleteBeforeReplace

   • ❌ Not mentioned in component context anywhere
   • 📝 Gap: Need to clarify behavior

Missing from Main Component Resource Documentation

The main component resource documentation (content/docs/iac/concepts/components/_index.md) has no dedicated section about resource options support. It only mentions:

• providers option (well documented)
• parent option in examples
• No comprehensive section explaining which options work vs don't work

---

📋 Recommendations

1. Add a dedicated section to the main Component Resources page explaining:

   • Which resource options work with component resources
   • Which don't work (with brief explanations why)
   • How inheritance works for supported options

2. Clarify the unclear cases through testing/code review:

   • dependsOn - Document actual behavior since there's conflicting information
   • protect - Clarify direct usage vs inheritance
   • provider vs providers - Document the differences
   • version, import, deleteBeforeReplace - Test and document actual behavior

3. Cross-reference consistency: Ensure all resource option pages consistently mention their component resource compatibility status

This audit shows that while some aspects are well documented, there's a significant gap in having a centralized, comprehensive explanation of resource options support for component resources - which is exactly what this issue is requesting.

---

Job Run | Branch: claude/issue-11663-20250926-0325