> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pulumi Guide

> Use a Pulumi AWS provider through Cloud Adapter with explicit endpoint and lifecycle verification.

Pulumi uses cloud provider plugins that call cloud APIs. With an AWS-origin Cloud Adapter, use an explicit AWS provider instance and attach it to every resource in the test. This keeps endpoint selection visible and prevents resources from falling back to the default AWS provider.

## Prerequisites

* Pulumi CLI 3.x and `@pulumi/aws` `6.83.0` for the exact configuration below;
* an installed AWS-origin adapter endpoint;
* an existing test bucket and isolated object prefix;
* an origin-side AWS identity;
* a disposable Pulumi stack.

The example uses S3. Confirm the selected target in [S3 service coverage](/cloud-adapter/service-catalog/aws/databases-storage/s3).

## Create an explicit provider

```ts theme={null}
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const config = new pulumi.Config();
const endpoint = config.require("adapterEndpoint");
const bucket = config.require("testBucket");

const adapter = new aws.Provider("cloud-adapter", {
  region: "us-east-1",
  endpoints: [{ s3: endpoint }],
  s3UsePathStyle: true,
  skipCredentialsValidation: true,
  skipMetadataApiCheck: true,
  skipRegionValidation: true,
  skipRequestingAccountId: true,
});

const object = new aws.s3.BucketObjectv2("smoke", {
  bucket,
  key: "pulumi/cloud-adapter-smoke.txt",
  content: "hello through Cloud Adapter\n",
  contentType: "text/plain",
}, { provider: adapter });

export const etag = object.etag;
```

Pin the package in `package.json` as `"@pulumi/aws": "6.83.0"`. The four startup switches keep this bounded S3 fixture from calling EC2 metadata, region validation, or AWS STS outside the configured adapter route. They do not weaken Cloud Adapter authentication. Reassess the provider call graph before changing versions or adding resource types.

## Preview and apply

```bash theme={null}
pulumi stack init cloud-adapter-smoke
pulumi config set adapterEndpoint https://adapter.example.test
pulumi config set testBucket adapter-smoke-test
export AWS_PROFILE="adapter-test"
export AWS_REQUEST_CHECKSUM_CALCULATION="WHEN_REQUIRED"
pulumi preview --diff
pulumi up --yes
```

After `pulumi up`, read the object through the origin API and inspect it in the native target service. Confirm bytes, content type, translated name, and request identifiers.

## Refresh deliberately

```bash theme={null}
pulumi refresh --preview-only --diff
pulumi refresh --yes
pulumi preview --diff
```

Refresh proves that the provider can read the object and reconcile provider-visible defaults. A create that succeeds followed by a refresh diff usually points to fidelity, normalization, or identifier translation rather than a Pulumi state-backend problem.

## Clean up

```bash theme={null}
pulumi destroy --yes
pulumi stack rm --yes
```

Verify deletion through both the origin API and target service. The Pulumi stack state, Pulumi secrets provider, Cloud Adapter configuration, and target object data are separate stores with separate retention policies.

## Important boundaries

* `pulumi preview` and `refresh` execute read calls; they are not offline operations.
* Provider initialization may call discovery APIs beyond the resource's service.
* Attaching the explicit provider to one resource does not automatically attach it to every child component.
* State is not a data migration engine.
* A successful object test does not certify bucket policies, lifecycle rules, notifications, retention, or signed URLs.

When a provider operation fails, reproduce its AWS call with the [AWS CLI guide](/cloud-adapter/guides/aws-cli), preserve response metadata, and compare the operation with the service profile.