Hi all, super noob question here. I can't find any documentation that describes how the Pulumi file structure should be used with the project it is deploying. Assume I have an existing NodeJS project that implements an API endpoint using a Lambda container and function URL. This project is under Git control and has /.gitignore /README.md /.eslintrc.json /other-typical-root-level-config-files /src /src/lambda.dockerfile /src/handler.js /src/some-other-non-relevant-files /package.json Should I create a pulumi folder and put my pulumi files in there? Since I already have a package.json, is there any issue adding Pulumi's deps to the existing package.json devDependencies object? And if I can do that, can I leave the other Pulumi files in the root, and if so, can I rename Pulumi's index.js to pulumi.js to differentiate from the actual app being deployed?

Hi Troy — thanks for this feedback! We just published some new docs that I think touch on this — lemme see if I can find a link.

Cool thanks. And thanks for a near-instantaneous response. I wasn't expecting that level of service 🙂

We touch on this here, although this isn’t necessarily specific to what you’re describing, but does use this same concept: https://www.pulumi.com/docs/guides/organizing-projects-stacks/#monorepo-with-base-infrastructure-project

Question: is

infra

any sort of convention? I prefer to adopt existing conventions than create my own taxonomy

infra

and

infrastructure

are common choices for these, i’d say, yeah

infra it is then (less to type than infrastructure too)

🍻

I'm looking forward to diving deeper this weekend. I'm quite excited by what I have seen in the docs so far

I have an update in the works for the page @miniature-musician-31262 linked which has more details too - and I'll try to include answers to some of these specifics!

@miniature-musician-31262, https://www.pulumi.com/docs/guides/organizing-projects-stacks/ mentions projects, and stacks… but not “programs”. Can I say (see https://pulumi-community.slack.com/archives/C84L4E3N1/p1649918660769559 for my confusion) that each project can only have 1 “program”?

That is fundamentally correct, in that the Pulumi.yaml is the “project” configuration, which is what is used/run when you do

pulumi up

Now…you can have more than one project per repo - there is nothing explicitly tying project to repo… Think about it this way. The “project” is everything ar the same level as Pulumi.yaml, which includes the program. The program is the entry point (main.go, index.ts, etc) I think I said all this right. But @miniature-musician-31262 can and will correct me :)

If it helps, here is one observation from someone engaging with the service and docs for the very first time (me). The term project is overloaded. That is to say that we often refer to the repo that we are working on as a project. And that is where I got hung up as we have a Pulumi project inside our project. And the confusion was further enhanced in my NodeJS case because the Pulumi project was presented with a package.json and an index.js file. Both of which are already present in "my" project. That's when I started to add the Pulumu dependencies to "my" package.json and put the Pulumu yaml files in "my" root. @miniature-musician-31262 cleared this up for me very quickly and succinctly and now I understand the project in project-in-project structure. Perhaps we can make some minor changes to the getting started docs? I followed the AWS/JavaScript getting started https://www.pulumi.com/docs/get-started/aws/create-project/. If the heading "Create a New Project" was changed to "Create a New Pulumi Project Inside Your Existing NodeJS Project" it would set the tone very early in the noob onboarding process.

Totally get that - we can probably make that clearer in the getting started, but it's not always “project in project” (pulumi projects aren't always in the same repo/filesystem as application code) and the QuickStart is intended to be the lowest common demoninator approach (to see how Pulumi code, etc works). But I we should consider how this isn't clear!

💡 Ah! As in a DevOps team that might be charged with managing infrastructure independent of their organisations Development team projects?

Sometimes :) There are a few different patterns we see. I wrote some blogs about them - let me find them!