Pulumi Heroku Resource Provider

The Pulumi Heroku provider serves as the primary mechanism for automating the lifecycle of resources within the Heroku ecosystem. By leveraging the Heroku Platform API, this provider allows developers to transition from manual dashboard interactions or command-line interface (CLI) executions to a formalized Infrastructure as Code (IaC) paradigm. Published on April 8, 2025, by Marcel Arns under the pulumiverse organization, the provider enables the definition of cloud resources using general-purpose programming languages. This approach eliminates the fragility of manual configurations and allows for the versioning of infrastructure alongside application code.

Heroku itself is designed as a fully-managed platform intended to provide the most streamlined path for delivering applications. When integrated with Pulumi, the platform's simplicity is augmented by the rigor of software engineering practices. Developers can define their application environments, add-ons, and configurations in a declarative manner, ensuring that every environment—from development to staging and production—is a precise replica of the others. This integration bridges the gap between application deployment and infrastructure management, allowing for a unified deployment pipeline where the infrastructure is treated as a first-class citizen in the software development lifecycle.

Language Support and Installation

The Heroku provider is engineered for broad accessibility, offering packages across all primary Pulumi-supported languages. This ensures that teams can utilize their existing expertise without needing to learn a proprietary domain-specific language for their infrastructure.

The following table outlines the installation requirements and package names for each supported language:

The availability of these packages allows for seamless integration into various CI/CD pipelines. For instance, a Node.js project can integrate the provider via npm, while a Python-based data science application can utilize pip. The Go implementation leverages the standard go get mechanism to pull the latest SDK version, and .NET developers can integrate it via the dotnet package manager. This multi-language support means that the Heroku provider can be used in heterogeneous environments where different services are written in different languages but all share a common infrastructure management tool.

Authentication Mechanisms

Authentication is a critical component of the Heroku provider, as it requires valid credentials to interact with the Heroku Platform API. The provider implements a flexible authentication hierarchy, allowing users to choose the method that best suits their security posture and environment.

Token Generation

Before authentication can be established, a valid API token must be generated. The Heroku API no longer supports direct username-password authentication. Tokens must be acquired through one of the following approved methods:

• Heroku Dashboard: Tokens can be generated by navigating to Account Settings, then Applications, and finally Authorizations.
• Heroku CLI: The heroku auth command can be used to manage and generate authentication tokens.
• Heroku Platform APIs: OAuth flows can be implemented for programmatic token acquisition.

Authentication Precedence

The provider evaluates credentials in a specific order of precedence. If a higher-priority method is found, the provider will use those credentials and ignore subsequent methods.

• Static credentials: These are provided directly within the provider configuration block. This method has the highest priority.
• Environment variables: If static credentials are absent, the provider searches for the HEROKU_API_KEY environment variable.
• Netrc: As a final fallback, the provider looks for credentials within the .netrc file located in the user's home directory.

Implementation of Authentication Methods

The following sections detail the technical implementation of each authentication strategy.

Static Credentials

Static credentials are defined within the Pulumi code itself. This is often used in conjunction with Pulumi's secrets management to ensure that the API key is not stored in plain text in version control.

```hcl
variable "herokuapikey" {
type = string
sensitive = true
}

provider "heroku" {
apikey = var.herokuapi_key
}
```

Environment Variables

Environment variables provide a clean separation between code and configuration. When the api_key property is omitted from the provider block, the provider automatically attempts to source the token from the shell environment.

hcl provider "heroku" { }

The corresponding terminal command to set this variable is:

bash export HEROKU_API_KEY="<heroku_auth_token>" pulumi preview

Netrc

The .netrc file is a standard for storing credentials for various network services. The provider can read this file to authenticate requests.

hcl provider "heroku" { }

The .netrc file in the home directory should be formatted as follows:

text machine api.heroku.com login <ignored, can be any value> password <heroku_auth_token>

If the .netrc file is located in a non-standard directory, the NETRC environment variable can be used to override the default path.

Provider Configuration Reference

The Heroku provider configuration includes several inputs and blocks that allow users to fine-tune how the provider interacts with the Heroku API and how it manages the state of resources.

General Configuration Inputs

The following inputs can be configured within the provider block:

• apiKey: The primary authentication token required for API access. This is a mandatory requirement, though it can be sourced via the methods described previously.
• email: This field is currently ignored. It was originally used for username-password authentication, which has since been deprecated.
• headers: An optional field that allows the user to send additional HTTP headers to Heroku. These must be provided as a string-encoded JSON object.

An example of the headers implementation:

json {"X-Custom-Header":"yes","X-Custom-Header-Too":"no"}

If the headers property is not explicitly provided in the code, the provider will check for the HEROKU_HEADERS environment variable.

Customizations Block

The customizations block is used to alter the behavior of specific resources. Only one customizations block is permitted per provider configuration.

• setAppAllConfigVarsInState: This boolean property controls the behavior of the heroku_app.all_config_vars attribute. By default, it is set to true, meaning a snapshot of all configuration variables—including those created via the Heroku CLI, web dashboard, or add-ons (such as the DATABASE_URL from Postgres)—is stored in the Pulumi state file. Setting this to false ensures that only configuration variables managed directly by Pulumi are tracked in the state.
• setAddonConfigVarsInState: This property governs the heroku_addon.config_var_values attribute. When set to true (the default), sensitive add-on configuration variables are captured and stored in the Pulumi state. To prevent the capture of these sensitive values, the property should be set to false.

Delays Block

Heroku employs an eventually consistent data model, which can occasionally lead to race conditions where a resource is requested before the system has fully processed its creation. The delays block allows users to introduce artificial pauses to mitigate these issues.

• postAppCreateDelay: The duration in seconds the provider waits after an application is created. The default value is 5 seconds.
• postSpaceCreateDelay: The duration in seconds the provider waits after a private space is created. The default value is 5 seconds.
• postDomainCreateDelay: The duration in seconds the provider waits after a domain is created. The default value is 5 seconds.

Timeouts Block

Timeouts define the maximum duration the provider will wait for a resource to be successfully modified before failing the operation.

• addonCreateTimeout: The maximum number of minutes the provider will wait for an add-on to be provisioned. The default is 20 minutes, and the absolute minimum allowed value is 10 minutes.

Resource Management and Usage

The core utility of the Heroku provider is the creation and management of resources. This is achieved by defining resources in the Pulumi program, which the provider then synchronizes with the Heroku Platform API.

Creating an Application

The basic unit of deployment in Heroku is the application. Using the provider, an application can be instantiated as follows:

hcl resource "heroku_app" "default" { # Application configuration details }

The use of the heroku_app resource ensures that the application is created with a consistent set of parameters. Because this is managed via Pulumi, any change to the application's definition in the code will be reflected in the actual Heroku environment upon the next pulumi up execution.

Infrastructure as Code (IaC) Capabilities

Integrating Heroku with Pulumi unlocks several high-level IaC features that are not available when using the Heroku Dashboard:

• Real Language Implementation: Unlike YAML or JSON, Pulumi allows the use of TypeScript, Python, Go, and .NET. This enables the use of loops, conditionals, and functions to define infrastructure.
• State Management: Pulumi maintains a state file that acts as the source of truth for the deployed infrastructure. This prevents the "configuration drift" common in manual environments.
• Secrets Management: Sensitive data, such as the HEROKU_API_KEY, can be encrypted using Pulumi's built-in secrets management, ensuring that credentials are never leaked in plain text.
• Policy as Code: Users can define policies to ensure that Heroku resources adhere to corporate or security standards (e.g., ensuring certain add-ons are always used).
• Automation API: The infrastructure can be wrapped in a programmatic interface, allowing for the dynamic creation of ephemeral environments for testing or preview branches.

Technical Analysis of Provider Versioning and Maintenance

The current version of the Heroku provider is v1.0.4, as of the April 2025 release. This version signifies a stable release of the resource provider, providing a foundation for managing cloud resources. The maintenance of the provider is handled by the pulumiverse community, specifically Marcel Arns, ensuring that the provider evolves in tandem with updates to the Heroku Platform API.

The transition from traditional deployment methods to the Pulumi Heroku provider represents a shift toward operational maturity. By treating infrastructure as code, organizations can implement a "GitOps" workflow where every change to the Heroku environment is peer-reviewed via pull requests. The ability to define delays and timeouts specifically addresses the inherent challenges of Heroku's eventual consistency, providing a layer of resilience that is missing from simple API scripts.

Furthermore, the strict prohibition of username-password authentication in the provider aligns with modern security standards. By forcing the use of API tokens and supporting .netrc and environment variables, the provider encourages the use of non-interactive authentication, which is a prerequisite for secure, automated CI/CD pipelines.

Conclusion

The Pulumi Heroku provider is a comprehensive tool for developers seeking to move away from the manual overhead of the Heroku Dashboard and the limitations of the Heroku CLI. By providing robust support for multiple programming languages and implementing a flexible, hierarchical authentication system, it lowers the barrier to entry for implementing Infrastructure as Code on the Heroku platform.

The provider's depth is evident in its handling of Heroku's specific architectural quirks. The inclusion of the delays block directly addresses the eventually consistent nature of the Heroku API, while the customizations block provides granular control over how sensitive configuration variables are handled within the Pulumi state. This ensures that developers can balance the need for comprehensive state tracking with the requirement for strict security, particularly regarding sensitive add-on values like database URLs.

From a strategic perspective, the adoption of this provider allows for the creation of reproducible environments. The impact is a significant reduction in "it works on my machine" errors, as the entire infrastructure stack—from the app creation to the add-on provisioning—is codified. For organizations operating at scale, the ability to integrate this with Pulumi's Automation API and Policy as Code features transforms Heroku from a simple hosting platform into a sophisticated, programmable cloud environment.

Sources

1. Pulumi Registry - Heroku
2. GitHub - pulumiverse/pulumi-heroku
3. Pulumi Registry - Heroku API Docs
4. CheckCharm - Setup Heroku with Pulumi