Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update customer managed agents config docs #12254

Merged
merged 1 commit into from
Jul 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update customer managed agents config docs
  • Loading branch information
seanyeh committed Jul 11, 2024
commit bd89a964785b8e0d00d1740439037496a34b95b1
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Customer-Managed Agents allow you to self-host deployment agents bringing the sa
Customer-Managed Agents support all the [deployment triggers](/docs/pulumi-cloud/deployments/#deployment-triggers) currently offered by Pulumi Deployments such as click to deploy, the Pulumi Deployments REST API, git push to deploy, Review Stacks, and remote Automation API.

{{% notes "info" %}}
Customer-Managed Agents is available on the Business Critical edition of Pulumi Cloud. [Contact sales](/contact/?form=sales) if you are interested and want to enable Customer-Managed Agents. If you are a self-hosted Pulumi Cloud customer, please [get in touch](https://share.hsforms.com/1YajiJ73sSuGn5RoTkyvKxg2mxud) to be notified when it is available.
Customer-Managed Agents is available on the Business Critical edition of Pulumi Cloud. [Contact sales](/contact/?form=sales) if you are interested and want to enable Customer-Managed Agents.
{{% /notes %}}

## Using Customer-Managed Agents
Expand All @@ -32,7 +32,7 @@ Before you begin, ensure you have installed the [Pulumi Github App](/docs/using-
2. Create a new pool. Ensure to copy and save the token
3. Install the agents as per the instructions on the page
4. Verify the agent status by refreshing the page
5. Configure a stack to use the agent by going to the Deploy tab within Stack Settings, and selecting the pool you created under the **Deployment Runner** pool drop-down
5. Configure a stack to use the agent by going to the Deploy tab within Stack Settings, and selecting the pool you created under the **Deployment Runner** pool drop-down
6. **(Optional)** Add more agents to the pool to increase concurrency by using the same token
7. Verify setup by doing a 'pulumi refresh' through the **Actions** drop-down in your stack page

Expand Down Expand Up @@ -68,7 +68,7 @@ There are two methods to provide cloud provider credentials to the agents:
VARIABLE=value customer-managed-deployment-agent run
```

You also need to update the `pulumi-deployment-agent.yaml` configuration file by setting `env_forward_allowlist`. The configuration file can be found in the directory where the agent is extracted. `env_forward_allowlist` expects an array of strings. Example:
You also need to update the `pulumi-deployment-agent.yaml` [configuration file](#configuration-reference) by setting `env_forward_allowlist`. `env_forward_allowlist` expects an array of strings. Example:

```yaml
token: pul-d2d2….
Expand All @@ -78,3 +78,59 @@ There are two methods to provide cloud provider credentials to the agents:
- key_two
- key_three
```

## Configuration Reference

All configuration for customer managed agents are done through the `pulumi-deployment-agent.yaml` file. This can be created manually or with the `customer-managed-deployment-agent configure` command.

The customer managed agent will look for `pulumi-deployment-agent.yaml` in the following directories:

- Current directory
- Home directory
- `/etc`
- Location of the `customer-managed-deployment-agent` binary

\
Below are available configuration parameters and their default values. In most cases, only `token` is required.

```yaml
# pulumi-deployment-agent.yaml

## Required settings

# Pulumi token provided when creating a new deployment runner pool
token: pul-xxx

## Optional settings

# Location of temp directory
# Uses the OS's preferred temporary file location (usually /tmp) by default
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if we should get into detail around dind

shared_volume_directory: ""

# The base path from which to load the runners
# This defaults to the location of the customer-managed-deployment-agent binary
# (usually ~/.pulumi/bin/customer-managed-deployment-agent)
working_directory: "<location of customer-managed-deployment-agent binary>"

# If using Self-Hosted Pulumi, set this to API domain of instance
service_url: "https://api.pulumi.com"

# If true, exit immediately after completing a single job
single_run: false

# If true, always pull the Pulumi image from the Docker registry
# If false, use a local image
pull_image: true

# If true, write errors to syslog instead of stderr
syslog: false

# Values for configuring OpenID Authentication
organization_name: ""
runner_pool_id: ""
token_expiration: ""
oidc_token_file: ""

# List of environment variables to pass to the deployment agent
env_forward_allowlist: []
```
2 changes: 1 addition & 1 deletion content/docs/pulumi-cloud/self-hosted/components/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -441,7 +441,7 @@ scrape_configs:
In order to enable [Pulumi Deployments](/docs/pulumi-cloud/deployments), the following must be configured:

* `PULUMI_SERVICE_METADATA_BLOB_STORAGE_ENDPOINT` or `PULUMI_LOCAL_OBJECTS` [object storage](#object-storage)
* [Customer-Managed Agents](/docs/pulumi-cloud/deployments/customer-managed-agents/) - You also need to update the `pulumi-deployment-agent.yaml` configuration file by setting `service_url` to `<PULUMI_API_DOMAIN>`. The configuration file can be found in the directory where the agent is extracted. Example:
* [Customer-Managed Agents](/docs/pulumi-cloud/deployments/customer-managed-agents/) - You also need to update the `pulumi-deployment-agent.yaml` [configuration file](/docs/pulumi-cloud/deployments/customer-managed-agents/#configuration-reference) by setting `service_url` to `<PULUMI_API_DOMAIN>`. Example:

```yaml
token: pul-d2d2….
Expand Down
Loading