Skip to content
This repository has been archived by the owner on Jul 1, 2024. It is now read-only.

Commit

Permalink
Fix missing Go reference, other issues in the project docs (#3876)
Browse files Browse the repository at this point in the history
  • Loading branch information
@cnunciato
cnunciato authored Jan 25, 2024
1 parent 39b55c8 commit 06ef7c3
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 108 deletions.
140 changes: 36 additions & 104 deletions themes/default/content/docs/concepts/projects/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,69 +16,71 @@ aliases:
- /docs/intro/concepts/project/
---

A Pulumi project is any folder which contains a `Pulumi.yaml` file. When in a subfolder, the closest enclosing folder with a `Pulumi.yaml` file determines the current project. A new project can be created with `pulumi new`. A project specifies which runtime to use and determines where to look for the program that should be executed during deployments. Supported runtimes are `nodejs`, `python`, `dotnet`, `go`, `java`, and `yaml`.
A Pulumi project is any folder that contains a `Pulumi.yaml` project file. At runtime, the nearest parent folder containing a `Pulumi.yaml` file determines the current project. Projects are created with the [`pulumi new`](/docs/cli/commands/pulumi_new/) command.

## Project file {#pulumi-yaml}
## The project file (Pulumi.yaml) {#pulumi-yaml}

The `Pulumi.yaml` project file specifies metadata about your project. The project file must begin with a capitalized `P`, although either `.yml` or `.yaml` extension will work.
The project file specifies which runtime to use and determines where to look for the program that should be executed during deployments. Supported runtimes are `nodejs`, `python`, `dotnet`, `go`, `java`, and `yaml`.

Project files also contain metadata about your project. The project file must begin with a capital `P`, although either `.yml` or `.yaml` extension will work.

A typical `Pulumi.yaml` file looks like the following:

```yaml
name: webserver
runtime: nodejs
description: Basic example of an AWS web server accessible over HTTP.
description: A minimal JavaScript Pulumi program.
```
In addition, when using JavaScript, the working directory for the project should contain a `package.json` that points to a file such as `index.js`. In Python, there should either be a `__main__.py` file or a `setup.py` file that defines the entry point.
In addition, when using JavaScript or TypeScript, the working directory for the project should contain a `package.json` file that points to an entrypoint such as `index.js`. In Python, the presence of a `__main__.py` or `setup.py` file defines the entrypoint.

The following are other examples of `Pulumi.yaml` files that define project configurations for other use cases:

* A `Pulumi.yaml` file for a `nodejs` program that uses JavaScript rather than TypeScript.
* A `Pulumi.yaml` file for a Node.js program that uses JavaScript rather than TypeScript:

```yaml
name: my-project
description: A minimal JavaScript Pulumi program.
runtime:
name: nodejs
options:
typescript: false
name: nodejs
options:
typescript: false
```

* A `Pulumi.yaml` file for a `go` program that will only use a pre-built executable by the name `mybinary`.
* A `Pulumi.yaml` file for a Go program that uses a pre-built executable named `mybinary`:

```yaml
name: my-project
description: A precompiled Go Pulumi program.
runtime:
name: go
options:
binary: mybinary
description: A minimal Go Pulumi program
name: go
options:
binary: mybinary
```

* A `Pulumi.yaml` file for a `dotnet` program that will use a pre-built assembly `MyInfra.dll` under the `bin` directory.
* A `Pulumi.yaml` file for a .NET program that uses a pre-built assembly named `MyInfra.dll` in the `bin` directory:

```yaml
name: my-project
description: A precompiled .NET Pulumi program.
runtime:
name: dotnet
options:
binary: bin/MyInfra.dll
description: A precompiled .NET Pulumi program
name: dotnet
options:
binary: bin/MyInfra.dll
```

* A `Pulumi.yaml` file for a `java` program that will use a pre-built JAR `target/my-project-1.0-SNAPSHOT-jar-with-dependencies.jar`.
* A `Pulumi.yaml` file for a Java program that uses a pre-built JAR file:

```yaml
name: my-project
description: A precompiled Java Pulumi program.
runtime:
name: java
options:
binary: target/my-project-1.0-SNAPSHOT-jar-with-dependencies.jar
description: A precompiled Java Pulumi program
```

* A `Pulumi.yaml` file for a `YAML` program that includes its resources inline.
* A `Pulumi.yaml` file for a `YAML` program that includes its resources inline:

```yaml
name: my-project
Expand All @@ -88,83 +90,15 @@ The following are other examples of `Pulumi.yaml` files that define project conf
type: aws:s3:Bucket
```

For more information on valid Pulumi project metadata, see [Pulumi Configuration Reference](/docs/reference/pulumi-yaml/).

## Paths
For more information on valid Pulumi project metadata, see the [Pulumi.yaml reference](/docs/reference/pulumi-yaml/).

When your Pulumi program references resources in the local filesystem, they are always relative to the working directory. The following example code references a subfolder `app` of the working directory, which would contain a `Dockerfile` and application code:
## Project-relative paths

{{< chooser language "javascript,typescript,python,csharp,java,yaml" >}}
When your Pulumi program refers to resources in the local filesystem, paths are always relative to the working directory. In the following example, the `aws.ecr.Image` resource refers to a subfolder of the working directory named `app` that contains a `Dockerfile`:

{{% choosable language javascript %}}

```javascript
const myTask = new cloud.Task("myTask", {
build: "./app", // subfolder of working directory
...
});
```
{{< example-program path="awsx-ecr-image" >}}

{{% /choosable %}}
{{% choosable language typescript %}}

```typescript
const myTask = new cloud.Task("myTask", {
build: "./app", // subfolder of working directory
...
});
```

{{% /choosable %}}
{{% choosable language python %}}

```python
myTask = Task('myTask',
spec={
'build': './app' # subfolder of working directory
...
}
)
```

{{% /choosable %}}
{{% choosable language csharp %}}

```csharp
var myTask = new Task("myTask", new TaskArgs
{
Build = "./app", // subfolder of working directory
...
});
```

{{% /choosable %}}
{{% choosable language java %}}

```java
var myTask = new Task("myTask",
TaskArgs.builder()
.build("./app") // subfolder of working directory.
.build()); // Java overloading handles ambiguity since the arguments are different
```

{{% /choosable %}}
{{% choosable language yaml %}}

```yaml
resources:
myTask:
type: cloud:Task
properties:
build: ./app # subfolder of working directory
...
```

{{% /choosable %}}

{{< /chooser >}}

## Getting the Current Project Programmatically
## Getting the current project programmatically

The {{< pulumi-getproject >}} function returns the name of the currently deploying project. This can be useful for naming or tagging resources.

Expand All @@ -173,14 +107,14 @@ The {{< pulumi-getproject >}} function returns the name of the currently deployi
{{% choosable language javascript %}}

```javascript
let project = pulumi.getProject();
const project = pulumi.getProject();
```

{{% /choosable %}}
{{% choosable language typescript %}}

```typescript
let project = pulumi.getProject();
const project = pulumi.getProject();
```

{{% /choosable %}}
Expand Down Expand Up @@ -216,19 +150,17 @@ var project = ctx.projectName();

```yaml
variables:
project: ${pulumi.project}
project: ${pulumi.project}
```

{{% /choosable %}}

{{< /chooser >}}

## Stack Settings Files {#stack-settings-file}
## Stack settings files {#stack-settings-file}

Each stack that is created in a project will have a file named `Pulumi.<stackname>.yaml` that contains the configuration specific to this stack. This file typically resides in the root of the project directory.

For stacks that are actively developed by multiple members of a team, the recommended practice is to check them into source control as a means of collaboration. Since secret values are encrypted, it is safe to check in these stack settings.

When using ephemeral stacks, the stack settings are typically not checked into source control.
For stacks that are actively developed by multiple members of a team, the recommended practice is to check them into source control as a means of collaboration. Since secret values are encrypted, it is safe to check in these stack settings. When using ephemeral stacks, the stack settings are typically not checked into source control.

For more information about configuration and how this file is managed using the CLI and programming model, refer to [Configuration](/docs/concepts/config/).
For more information about configuration and how to manage these files on the command line and programmatically, refer to the [Configuration](/docs/concepts/config/) and [Secrets](/docs/concepts/secrets/) documentation.
4 changes: 2 additions & 2 deletions themes/default/content/docs/concepts/projects/project-file.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
title_tag: Project File Reference
meta_desc: Documentation of the settings that are valid for the Pulumi project file.
title: Project file
h1: Pulumi project file
title: Project file reference
h1: Pulumi project file reference
meta_image: /images/docs/meta-images/docs-meta.png
menu:
concepts:
Expand Down
10 changes: 8 additions & 2 deletions themes/default/layouts/shortcodes/pulumi-getproject.html
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<pulumi-chooser type="language" options="javascript,typescript,python,go,csharp" option-style="none" class="inline">
<pulumi-chooser type="language" options="javascript,typescript,python,go,csharp,java,yaml" option-style="none" class="inline">
<pulumi-choosable class="highlight" type="language" value="javascript">
<code class="language-javascript"><a href="/docs/reference/pkg/nodejs/pulumi/pulumi#getProject">getProject</a></code>
</pulumi-choosable>
Expand All @@ -12,6 +12,12 @@
<code class="language-go"><a href="https://godoc.org/github.com/pulumi/pulumi/sdk/v3/go/pulumi#Context.Project">context.Project</a></code>
</pulumi-choosable>
<pulumi-choosable class="highlight" type="language" value="csharp">
<code class="language-csharp">Deployment.ProjectName</code>
<code class="language-csharp"><a href="/docs/reference/pkg/dotnet/Pulumi/Pulumi.DeploymentInstance.html#Pulumi_DeploymentInstance_ProjectName">Deployment.Instance.ProjectName</a></code>
</pulumi-choosable>
<pulumi-choosable class="highlight" type="language" value="java">
<code class="language-java">context.projectName()</code>
</pulumi-choosable>
<pulumi-choosable class="highlight" type="language" value="yaml">
<code class="language-yaml"><a href="/docs/languages-sdks/yaml/yaml-language-reference/#built-in-variables">pulumi.project</a></code>
</pulumi-choosable>
</pulumi-chooser>

0 comments on commit 06ef7c3

Please sign in to comment.