Pulumi Programming Model
Internal
Overview
In Pulumi, infrastructure resources are described programmatically in a program, that gets executed when the pulumi preview and pulumi up are run. At the end of the program execution, the desired state of the infrastructure is built in memory and it is compared with the actual state, pulled from the Pulumi backend, specifically from the state file associated with the active stack the program is being executed in the context of.
Before any interaction with the infrastructure platform could takes place, Pulumi needs to build a context to maintain a model of the infrastructure resources, as they exist in the infrastructure platform backend - the actual state. That is the stack. A stack contains metadata and a state file, which has the actual state of the resources in the stack, as known at the moment. This is how an empty stack is created. Note that the state file maintained by a stack is a cache of the actual state of the infrastructure platform backend, and it can be synchronized with pulumi refresh. Depending on delta between the desired state and the actual state, the Pulumi client takes various actions: infrastructure resources are created, updated or deleted. It is the Pulumi client that interacts with the infrastructure platform, so proper access credentials must exist in the environment that runs the Pulumi client.
While the rest of this article uses Python as example, Pulumi offers SDKs for Python, TypeScript and Go.
Creating an Empty Stack
A project may contain several stacks out of which one is active.
To list all stacks in the project:
pulumi stack ls
More details on listing stacks:
To create an empty stack in the project:
pulumi stack init <org-name>/<stack-name>
More details on creating empty stacks:
The stack metadata in a raw format can be displayed with:
pulumi stack export
More details about exporting stacks:
Creating an Infrastructure Resource in Code
Starting with an empty stack, the simplest way to provision an infrastructure resource is to write the code that creates an instance of that resource, using the API exposed by the dedicated resource provider.
This is an example of a Python program, saved in a __main__.py in a Pulumi project:
import pulumi_datadog
dashboard_json = """
{
"title": "Blue",
"layout_type": "ordered",
"reflow_type": "fixed",
"widgets": [
{
"definition": {
"color": "#4d4d4d",
"font_size": "auto",
"text": "This is some sample text.",
"text_align": "left",
"type": "free_text"
},
"layout": {
"height": 1,
"width": 2,
"x": 0,
"y": 0
}
}
]
}
"""
pulumi_datadog.DashboardJson("Dashboard-01", dashboard=dashboard_json)
Upon the execution of the pulumi up command, the Pulumi runtime builds the desired state in memory and asks for the permission to perform the update:
pulumi up
Previewing update (aiml-dp/ovidiu-experimental-datadog-dashboard-from-json/main)
Type Name Plan
+ pulumi:pulumi:Stack ovidiu-experimental-datadog-dashboard-from-json-main create
+ └─ datadog:index:DashboardJson Dashboard-01 create
Resources:
+ 2 to create
Do you want to perform this update? [Use arrows to move, enter to select, type to filter]
yes
> no
details
If the permission is granted, Pulumi reconciles the desired state (one resource) and actual state (no resource) and crates the resource in the infrastructure platform backend. At the same time, the stack state is updated.
Updating an Infrastructure Resource in Code
Upon the initial infrastructure resource creation, it state exists in three places: in the infrastructure platform itself, in the stack state file and in the program. To update the infrastructure resource from the program, update the code, and run pulumi up again. We change the JSON representation and update the color to dark blue:
import pulumi_datadog
dashboard_json = """
{
"title": "Blue",
...
"widgets": [
{
"definition": {
"color": "#00008B",
...
},
...
]
}
"""
pulumi_datadog.DashboardJson("Dashboard-01", dashboard=dashboard_json)
pulumi up will build the desired state (which includes the dark blue color) in memory, will compare it with the stored actual state, and will detect differences:
pulumi up
Previewing update (aiml-dp/ovidiu-experimental-datadog-dashboard-from-json/main)
Type Name Plan Info
pulumi:pulumi:Stack ovidiu-experimental-datadog-dashboard-from-json-main
~ └─ datadog:index:DashboardJson Dashboard-01 update [diff: ~dashboard]
Resources:
~ 1 to update
1 unchanged
Do you want to perform this update? [Use arrows to move, enter to select, type to filter]
yes
> no
details
If allowed, pulumi up will initiate infrastructure resource update. At the end of the process, all three states stored in code, stack and infrastructure platform will be reconciled.
Importing (Adopting) an Infrastructure Resource
An existing infrastructure resource can be imported (adopted) into an existing stack. This action allows it to be managed by Pulumi via the usual Pulumi workflows.
Assuming an empty stack and a "Green" dashboard that displays some green text in a widget, the import process consists of running the pulumi import and **reconciling the state of the program with the infrastructure resource state**.
Deleting an Infrastructure Resource in Code
I think there is a misunderstanding here. Apologies if the below info is redundant, but I think we can clear this up.
Pulumi uses a statefile to capture a “current” state of resources contained in the current stack, from a physical cloud provider perspective and a pulumi metadata perspective. The statefile is just that, a file or dumb storage that is the result of a pulumi up.
When you execute a pulumi up against a Pulumi program, Pulumi is taking the existing statefile (if one exists) and comparing it to the desired state, which is declared by the code in your Pulumi program.
So what is happening here is, you’ve imported the resource into your Pulumi state and you’ve not included the resource definition (in code) in your Pulumi program. So when you run a pulumi up Pulumi looks at the statefile, sees the datadog dashboard and compares it with your code, which does not contain the resource definition and correctly determines it needs to delete the resource
The Pulumi programming model defines the core concepts in use when creating infrastructure as code programs.
Start with Programming Model https://kb.novaordis.com/index.php/Pulumi_Concepts#Programming_Model as a central place to specify that while the “program” runs, the program builds a model of the infrastructure that is then synchronized with the infrastructure platform.
Remove “Code Example” https://kb.novaordis.com/index.php/Pulumi_Concepts#Code_Examples section work out https://kb.novaordis.com/index.php/Python_Pulumi_Code_Examples page into the “Programming Model”
Move the content of “Python Pulumi Code Examples” in-line into the “Programming Model” section and resolve the links pointing to the “Python Pulumi Code Examples”
Link to https://kb.novaordis.com/index.php/Pulumi_Datadog_DashboardJson#Internal Programming Model.
Describe in detail these two models (the second if we don’t want to change anything)
Understand the difference between stack configuration and stack output.