Autonaming configuration

content/blog/autonaming-configuration/index.md

@@ -0,0 +1,95 @@
+---
+title: "Introducing Auto-naming Configuration in Pulumi"
+date: 2025-01-16T08:00:00-07:00
+meta_desc: "Learn how to configure Pulumi's resource naming to match your organization's naming conventions and requirements across all cloud providers."
+meta_image: meta.png
+authors:
+    - mikhail-shilkov
+tags:
+    - features
+---
+
+I'm thrilled to announce the release of our auto-naming configuration feature. This highly anticipated capability addresses one of our most requested features [pulumi/pulumi#1518](https://github.com/pulumi/pulumi/issues/1518) and gives you complete control over how Pulumi names your cloud resources.
+
+<!--more-->
+
+## The Journey to Better Resource Naming
+
+Since Pulumi's early days, auto-naming has been a core feature that ensures unique names for cloud resources by generating names or name suffixes. While this approach solved many challenges around zero-downtime deployments and stack replication, we heard consistently from our community that you needed more control over how your resources are named.
+
+The original [feature request](https://github.com/pulumi/pulumi/issues/1518) I opened in June 2018 has generated extensive discussion, with users sharing various use cases and requirements. Today, I'm happy to finally close that issue with a solution that addresses the community's needs while maintaining Pulumi's robust resource management capabilities.
+
+## Introducing Auto-naming Configuration
+
+With the new auto-naming configuration feature, you now have full control over how Pulumi generates resource names. Here are some common scenarios you can achieve:
+
+### Disable Auto-naming
+
+If you want complete control over your resource names, you can disable auto-naming entirely:
+
+```yaml
+pulumi:autonaming:
+  mode: disabled
+```
+
+### Use Logical Names As-Is
+
+For scenarios where you want Pulumi to use exactly the names you specify:
+
+```yaml
+pulumi:autonaming:
+  mode: verbatim
+```
+
+### Custom Naming Patterns
+
+Create your own naming patterns that combine static text, resource information, and random elements:
+
+```yaml
+pulumi:autonaming:
+  pattern: ${project}-${stack}-${name}${alphanum(6)}
+```
+
+### Configuration Syntax
+
+The configuration syntax differs slightly depending on where you define it:
+
+In your project file (Pulumi.yaml):
+```yaml
+config:
+  pulumi:autonaming:
+    value:
+      mode: verbatim
+```
+
+In your stack configuration file (Pulumi.<stack-name>.yaml):
+```yaml
+config:
+  pulumi:autonaming:
+    mode: verbatim
+```
+
+The same applies to other configuration patterns shown above - use the `value:` key in project-level configuration, but omit it in stack-level configuration.
+
+## Getting Started
+
+To use the auto-naming configuration feature, you'll need:
+
+1. Pulumi CLI 3.143.0 or later
+2. The following minimum provider versions:
+   - AWS provider 6.66.0 or later
+   - Azure Native provider 2.78.0 or later
+   - Azure Classic provider 6.14.0 or later
+   - Google Cloud Platform provider 8.11.0 or later
+
+Once you have the required versions installed, simply add your desired auto-naming configuration to your Pulumi configuration file
+
+For complete documentation and advanced usage scenarios, visit our [auto-naming configuration documentation](https://www.pulumi.com/docs/intro/concepts/resources/names/#auto-naming-configuration).
+
+## General Availability
+
+We're excited to announce that the auto-naming configuration feature is now generally available across our major cloud providers. This release marks an important milestone in Pulumi's evolution, delivering a robust and flexible solution for resource naming that our community has been asking for.
+
+Thank you to everyone who participated in the preview period and provided valuable feedback. Your input has been invaluable in creating a solution that works for diverse use cases while maintaining Pulumi's core strengths.
+
+If you have any questions or feedback about the auto-naming configuration feature, please don't hesitate to reach out to us on GitHub or in the Pulumi Community Slack.

content/blog/infrastructure-as-code-resource-naming/index.md

@@ -9,6 +9,10 @@ tags:
     - features
 ---
 
+{{% notes %}}
+We've introduced a new way to customize or disable auto-naming with a configuration option. See [Auto-naming Configuration](/blog/autonaming-configuration/) for more information about all the ways you can customize auto-naming.
+{{% /notes %}}
+
 "What's in a name? That which we call a rose by any other name would smell as sweet."  William Shakespeare's oft repeated quote was used to help Juliet explain that a "Montague" is worthy of love.  Juliet may have underestimated the importance of a name, however, since things didn't work out so well for everyone in Verona!  Many customers have questions about "names" in Pulumi -- and in an effort to make sure that things work out better for them than they did for Romeo, here's a quick note on naming!
 
 <!--more-->
@@ -27,6 +31,10 @@ Second, physical names are used in important ways when we update our resources.
 
 ## Controlled Naming
 
+{{% notes %}}
+We've introduced a new way to customize or disable auto-naming with a configuration option. See [Auto-naming Configuration](/blog/autonaming-configuration/) for more information about all the ways you can customize auto-naming.
+{{% /notes %}}
+
 There are times, however, where precise naming is important.  You might need to match an existing environment, or want to explicitly control other behavior.  If you know for certain that you want to control the naming yourself, you can indeed override auto-naming.  Simply specify the physical name on your resource during creation. Most resources expose a `name` property that may be specified in the argument object to the constructor:
 
 ```typescript

content/blog/pulumi-recommended-patterns-the-basics/index.md

@@ -89,6 +89,7 @@ Along with this recommendation, using a unique prefix in the name of your resour
 Here are a few links to understand physical names and auto-naming a bit better:
 
 * [Resources and auto-naming](/docs/concepts/resources#autonaming)
+* [Auto-naming Configuration](/docs/concepts/resources#autonaming-configuration)
 * [Infrastructure as Code Resource Naming](/blog/infrastructure-as-code-resource-naming/)
 * [Why do resource names have random hex character suffixes?](/docs/support/faq#why-do-resource-names-have-random-hex-character-suffixes)
 

content/docs/iac/concepts/how-pulumi-works.md

@@ -461,7 +461,7 @@ This time, the engine will not need to make any changes to `media-bucket` since
 
 Pulumi executes resource operations in parallel whenever possible, but understands that some resources may have dependencies on other resources. If an [output](/docs/concepts/inputs-outputs/) of one resource is provided as an input to another, the engine records the dependency between these two resources as part of the state and uses these when scheduling operations. This list can also be augmented by using the [dependsOn](/docs/concepts/resources#dependson) resource option.
 
-By default, if a resource must be replaced, Pulumi will attempt to create a new copy of the resource before destroying the old one. This is helpful because it allows updates to infrastructure to happen without downtime. This behavior can be controlled by the [deleteBeforeReplace](/docs/concepts/resources#deletebeforereplace) option. If you have disabled [auto-naming](/docs/concepts/resources#autonaming) by providing a specific name for a resource, it will be treated as if it was marked as `deleteBeforeReplace` automatically (otherwise the create operation for the new version would fail since the name is in use).
+By default, if a resource must be replaced, Pulumi will attempt to create a new copy of the resource before destroying the old one. This is helpful because it allows updates to infrastructure to happen without downtime. This behavior can be controlled by the [deleteBeforeReplace](/docs/concepts/resources#deletebeforereplace) option. If you have disabled [auto-naming](/docs/concepts/resources#autonaming) using configuration or by providing a specific name for a resource, it will be treated as if it was marked as `deleteBeforeReplace` automatically (otherwise the create operation for the new version would fail since the name is in use).
 
 ## Declarative and imperative approach
 

content/docs/iac/concepts/options/import.md

@@ -213,6 +213,6 @@ For this to work, your Pulumi stack must be configured correctly. In this exampl
 
 If the resource’s arguments differ from the imported state, the import will fail. You will receive this message: `warning: inputs to import do not match the existing resource; importing this resource will fail`. Select “details” in the `pulumi up` preview to learn what the differences are. If you try to proceed without correcting the inconsistencies, you will see this message: `error: inputs to import do not match the existing resource`. To fix these errors, make sure that your program computes a state that completely matches the resource to be imported.
 
-Because of auto-naming, it is common to run into this error when you import a resource’s name property. Unless you explicitly specify a name, Pulumi will auto-generate one, which is guaranteed not to match, because it will have a random hex suffix. To fix this problem, explicitly specify the resource’s name [as described here](/docs/iac/concepts/resources/names/#autonaming). Note that, in the example for the EC2 security group, the name was specified by passing `web-sg-62a569b` as the resource’s name property.
+Because of auto-naming, it is common to run into this error when you import a resource’s name property. Unless you explicitly specify a name, Pulumi will auto-generate one, which is guaranteed not to match, because it will have a random hex suffix. To fix this problem, explicitly specify the resource’s name or disable auto-naming [as described here](/docs/iac/concepts/resources/names/#autonaming-configuration). Note that, in the example for the EC2 security group, the name was specified by passing `web-sg-62a569b` as the resource’s name property.
 
 Once a resource is successfully imported, remove the `import` option because Pulumi is now managing the resource.

content/docs/iac/concepts/resources/names.md

@@ -19,7 +19,7 @@ aliases:
 
 Each resource in Pulumi has a [logical name](#logicalname) and a [physical name](#autonaming).  The logical name is how the resource is known inside Pulumi, and establishes a notion of identity within Pulumi even when the physical resource might need to change (for example, during a replacement).  The physical name is the name used for the resource in the cloud provider that a Pulumi program is deploying to.
 
-Pulumi [auto-names](#autonaming) most resources by default, using the logical name and a random suffix to construct a unique physical name for a resource.  Users can provide explicit names to override this default.
+Pulumi [auto-names](#autonaming) most resources by default, using the logical name and a random suffix to construct a unique physical name for a resource.  Users can provide explicit names to override this default.  Users can also [customize or disable auto-naming](#autonaming-configuration) globally, per provider, or per resource type.
 
 Each resource also has a [Uniform Resource Name (URN)](#urns) which is a unique name derived from both the logical name of the resource and the type of the resource and, in the case of components, its parents.
 
@@ -279,6 +279,124 @@ resources:
 
 {{< /chooser >}}
 
+## Configuring Auto-Naming {#autonaming-configuration}
+
+You can customize how Pulumi generates resource names through the `pulumi:autonaming` configuration setting. This can be set at the stack, project, or organization level.
+
+{{% notes %}}
+When configuring auto-naming in your project configuration (`Pulumi.yaml`), you need to wrap the configuration in a `value` key:
+
+```yaml
+config:
+  pulumi:autonaming:
+    value:
+      mode: verbatim
+```
+
+However, when configuring it in a stack configuration file (`Pulumi.<stack-name>.yaml`), you can specify the configuration directly:
+
+```yaml
+config:
+  pulumi:autonaming:
+    mode: verbatim
+```
+{{% /notes %}}
+
+Here are the key ways to configure auto-naming:
+
+### Default Auto-Naming
+
+The default behavior adds a random suffix to resource names:
+
+```yaml
+config:
+  pulumi:autonaming:
+    mode: default
+```
+
+This is equivalent to having no configuration at all.
+
+### Verbatim Names
+
+To use the logical name exactly as specified, without any modifications:
+
+```yaml
+config:
+  pulumi:autonaming:
+    mode: verbatim
+```
+
+### Disable Auto-Naming
+
+To require explicit names for all resources:
+
+```yaml
+config:
+  pulumi:autonaming:
+    mode: disabled
+```
+
+### Custom Naming Pattern
+
+You can specify a template pattern for generating names:
+
+```yaml
+config:
+  pulumi:autonaming:
+    pattern: ${name}-${hex(8)}
+```
+
+The following expressions are supported in patterns:
+
+| Expression | Description | Example |
+| :---- | :---- | :---- |
+| name | Logical resource name | ${name} |
+| hex(n) | Hexadecimal random string of length n | ${name}-${hex(5)} |
+| alphanum(n) | Alphanumeric random string of length n | ${name}${alphanum(4)} |
+| string(n) | Random string of letters of length n | ${name}${string(6)} |
+| num(n) | Random string of digits of length n | ${name}${num(4)} |
+| uuid | UUID | ${uuid} |
+| organization | Organization name | ${organization}_${name} |
+| project | Project name | ${project}_${name} |
+| stack | Stack name | ${stack}_${name} |
+| config.key | Config value of key | ${config.region}_${name} |
+
+### Provider-Specific Configuration
+
+You can configure auto-naming differently for specific providers or resource types:
+
+```yaml
+config:
+  pulumi:autonaming:
+    mode: default
+    providers:
+      aws:
+        pattern: ${name}_${hex(4)}  # AWS resources use underscore and shorter suffix
+      azure-native:
+        mode: verbatim  # Azure resources use exact names
+        resources:
+          "azure-native:storage:Account": ${name}${string(6)}  # Storage accounts need unique names
+```
+
+### Strict Name Pattern Enforcement
+
+By default, providers may modify the generated names to comply with resource-specific requirements. To prevent this and enforce your exact pattern:
+
+```yaml
+config:
+  pulumi:autonaming:
+    pattern: ${name}-${hex(8)}
+    enforce: true
+```
+
+{{% notes type="warning" %}}
+When using verbatim names or patterns without random components, resources that need to be replaced will require delete-before-replace behavior, which can lead to downtime. Consider including random components in your naming pattern for resources that may need replacement.
+{{% /notes %}}
+
+### Migration
+
+Changing the autonaming setting on an existing stack doesn't cause any immediate changes. It will only affect any newly created resources on this stack, including resources being replaced for unrelated reasons. To re-create resources with new names, e.g. on a dev stack, you would need to destroy the stack and update it again.
+
 ## Resource Types {#types}
 
 Each resource is an instance of a specific Pulumi resource type.  This type is specified by a type token in the format `<package>:<module>:<typename>`.  Concrete examples of this format are:

content/docs/iac/support/faq.md

@@ -39,6 +39,8 @@ To ensure that as many logical Pulumi resources and stacks can be stood up side-
 
 You can disable this [auto-naming](/docs/concepts/resources#autonaming) on a per-resource basis if this isn't right for you. Doing so lets you have precise physical names without random suffixes, but also means you lose the two benefits named above.
 
+You can also use project or stack configuration to customize or disable auto-naming globally, per provider, or per resource type. See [Auto-naming Configuration](/docs/concepts/resources#autonaming-configuration) for more information.
+
 ## Secrets
 
 ### Are my secrets ever visible?