Pulumi Self-Hosted Installers: What the Repository Actually Ships

What problem the self-hosted Pulumi Service installers solve

Pulumi's managed service runs the state backend, the secrets store, the policy engine and the web console for you. Some organizations cannot use it: regulated workloads, air-gapped networks, or teams whose security review treats a third-party control plane as out of scope. The Self-Hosted Pulumi Service exists for that case, and this repository exists because deploying it is not a single binary. The README describes the repository as containing "installation guides for deploying the Self-Hosted Pulumi Service into a variety of different target environments." Each guide covers two things: the supporting cloud infrastructure the service runs on, and the container images that make up the service itself.

The audience is narrow and specific. You need someone who can provision a Kubernetes cluster or an ECS cluster, someone who can manage container image pull credentials, and someone who understands that the Pulumi Service is a stateful system with a database behind it. If your team has no infrastructure engineer, this repository will not compensate for that. It assumes you already know how to run a cluster.

The guides currently listed are Quickstart (Docker Compose), AWS (EKS or ECS), Azure (AKS), Docker Engine, and Google Cloud (GKE). VMware is listed as coming soon, which is a useful signal about coverage: the repository follows the major cloud providers first and leaves on-premises virtualization for later.

How the repository is organized, and why the layout matters

The top-level tree is the clearest description of the project. There are directories for each deployment target: aks-hosted/, ecs-hosted/, eks-hosted/, gke-hosted/, local-docker/, quickstart-docker-compose/, plus byo-infra/ and components-microstacks/. There is also eks-hosted-deprecated/, which is worth noticing. When a platform directory gets a deprecated sibling, it means the repository has already retired one approach in favor of another, and that the guides are versioned by directory rather than by a stable interface.

The TypeScript in the repository is tooling, not the deployment logic. package.json describes the package as "Development tools for Pulumi Self-Hosted Installers" and it is marked private. Its scripts lint markdown and validate Mermaid diagrams: lint:markdown runs markdownlint, and validate:standalone finds every .mmd file and renders it with mmdc. generate:diagrams does the same but writes SVGs back next to the sources. That tells you the diagrams in the guides are checked in as source files and rendered as part of the documentation pipeline, so a broken diagram fails a build rather than silently shipping.

The go.mod file shows the repository also contains Go code that depends on github.com/pulumi/pulumi/sdk/v3 at v3.243.0. The README does not describe what that Go code deploys in each directory, so treat the per-platform directories as the place to look for the actual program definitions.

One more structural detail: the README points reviewers at AGENTS.md files, with a root file for repository-wide concerns and per-platform files under eks-hosted/, ecs-hosted/, aks-hosted/, gke-hosted/ and components-microstacks/. That is a documentation convention for AI reviewers and coding agents, and it also tells a human contributor where the review checklist for a given platform lives.

Installing from the quickstart Docker Compose guide

There is no package to install. The README's own list of guides is the entry point, and the fastest path to a running service is the Quickstart guide in quickstart-docker-compose. The repository does not document a single clone command in the README, but the guide directory is the thing you check out, so start by cloning the repository and moving into that directory.

git clone https://github.com/pulumi/pulumi-self-hosted-installers.git
cd pulumi-self-hosted-installers/quickstart-docker-compose

Inside that directory the guide walks through deploying the supporting infrastructure and then the container images. The README does not reproduce those steps, so treat the guide's own files as the source of truth for the exact commands and configuration keys. What the README does establish is the split: infrastructure first, service containers second.

If you are working on the repository itself rather than deploying from it, the tooling has its own prerequisites. package.json declares an engines field of node >=16.0.0 and pins @mermaid-js/mermaid-cli at 11.12.0 and markdownlint-cli at 0.48.0 as dev dependencies.

npm install
npm run lint

The lint script runs the markdown check and then the Mermaid check, so a first run tells you whether your edits to a guide kept the diagrams valid. The validate:standalone script renders each .mmd file to an SVG in /tmp, which is the check that fails when a diagram references something that no longer exists.

Where the guides stop being enough

These are guides, and the repository says so. The README describes them as installation guides and points to the Self-Hosted Pulumi Service documentation for "the components of the Pulumi Service and general guidance on deploying and operating the service." That sentence is doing a lot of work: operating the service is explicitly out of scope here. Backup, restore, upgrades of a running deployment, database migrations and disaster recovery are not documented in the README, and the README does not claim they are.

The maintenance signal is the part to weigh carefully. The last push to the repository was on 2025-04-29, which is more than six months before today. The most recent release is v3.1, dated the same day. There is no statement in the README about a support window or a compatibility matrix between installer versions and Pulumi Service image versions, so you cannot tell from the repository alone how long a given tag stays usable.

A second limitation is coverage. VMware is listed as coming soon, which means on-premises virtualization is not covered today. If your target is bare metal or a hypervisor, the closest thing in the tree is local-docker, and that is a different environment with different assumptions about networking, storage and availability. The byo-infra/ directory suggests some support for bringing your own infrastructure, but the README does not describe it, so you would be reading the directory rather than following a guide.

Finally, there is the deprecated directory. eks-hosted-deprecated/ sitting next to eks-hosted/ is a reminder that the recommended approach for a platform can change, and that the old guide stays in the tree rather than disappearing. If you find two directories for your platform, check which one the README lists.

How this compares with running Pulumi Cloud or Terraform

The obvious alternative is not self-hosting at all. Pulumi Cloud is the managed service the self-hosted deployment mirrors, and choosing it removes the cluster, the database and the image pipeline from your responsibilities. The trade is that your state and secrets live in Pulumi's control plane rather than yours. This repository only makes sense when that trade is unacceptable, and the guides are the mechanism for taking the other side of it.

The comparison people actually search for is Terraform. The difference in approach is architectural, not cosmetic. Terraform's default state backend is a file or a remote object store that you configure, and the open-source workflow runs entirely on your machine or in your CI. Pulumi's model puts a service in the middle: state, secrets, policy and the console are served by a running application, which is exactly why self-hosting Pulumi requires deploying a set of containers and their supporting infrastructure rather than pointing at an S3 bucket. That is the reason this repository has guides for EKS, ECS, AKS and GKE at all.

Within the self-hosting space, the choice is between the Docker Compose quickstart and a managed Kubernetes or ECS deployment. The quickstart is the smallest surface and the right first step for evaluating the service. The cloud guides exist because a Compose file on one host is not what most organizations will run in production, and moving from one to the other means re-doing the infrastructure layer.

Licence, upgrades and what maintenance actually costs

The repository is licensed under Apache-2.0, and the LICENSE file sits at the top level. That covers the guides and the tooling in this repository. It does not tell you anything about the licence terms of the Pulumi Service container images themselves, which are pulled from elsewhere and are governed separately. Anyone evaluating this for a regulated environment should read the terms attached to the service images, not just the repository licence. This is not legal advice, and the repository does not attempt to answer the question.

Upgrade cost is where the guide model shows its edges. Releases are tagged, with v3.1 on 2025-04-29, v3.0 on 2024-12-10 and v2.1 on 2024-12-05. The README does not document an upgrade procedure, a rollback procedure, or how a running deployment moves from one tag to the next. In practice that means the upgrade path is whatever the Self-Hosted Pulumi Service documentation describes, and the repository is the infrastructure layer beneath it. Budget for the fact that a major version bump in the installer may require re-applying infrastructure changes rather than editing a version string.

The day-to-day maintenance cost of the repository itself is low, and the tooling reflects that. Two dev dependencies, a markdown linter and a Mermaid renderer, plus a Go module that tracks the Pulumi SDK. Renovate is configured via renovate.json5, which suggests dependency updates arrive as pull requests rather than being hunted manually. If you fork this to adapt a guide, you inherit that pipeline, which is a small but real benefit.

Editorial conclusion

Adopt this repository if you already operate Kubernetes or ECS and need a documented path to running the Pulumi Service inside your own account, and you accept that the guides are reference material you will adapt rather than a supported product with a version number. Do not adopt it if you want Pulumi Cloud without operating its infrastructure, or if you expect a single install command. Verify first that your target platform has a guide in the repository tree, that you can pull the Pulumi Service container images, and that the v3.1 tag from 2025-04-29 is current enough for the service version you intend to run.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes