Adds a blog post introducing the new StackReference OutputDetails feature. The feature was added to all supported SDKs in the following PRs: - https://github.com/pulumi/pulumi/pull/12034 - https://github.com/pulumi/pulumi/pull/12071 - https://github.com/pulumi/pulumi-dotnet/pull/103 - https://github.com/pulumi/pulumi/pull/12072 - https://github.com/pulumi/pulumi-java/pull/986
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
---
|
|
title: "Streamline access to stack outputs with OutputDetails"
|
|
date: 2023-03-24
|
|
meta_desc: >-
|
|
You can now read and transform outputs from stack references
|
|
without calling Output.apply.
|
|
meta_image: meta.png
|
|
authors: [abhinav-gupta]
|
|
tags: [features, stack-reference]
|
|
---
|
|
|
|
You can use the new `StackReference.getOutputDetails` method
|
|
to get output values from other stacks directly—without calling `Output.apply`.
|
|
|
|
<!--more-->
|
|
|
|
## What are Stack References?
|
|
|
|
> If you already understand stack references,
|
|
> skip on to [Introducing `OutputDetails`](#introducing-outputdetails).
|
|
|
|
Stack references are a useful feature of Pulumi
|
|
that you can use to access output values from one stack in another.
|
|
|
|
For instance,
|
|
let's say you have a 'network' stack that provisions an AWS VPC,
|
|
and an 'app' stack that deploys your application on an EC2 instance in that VPC.
|
|
The app stack can reference the output of the network stack
|
|
to obtain the VPC ID, which it needs to configure the EC2 instance.
|
|
|
|
```typescript
|
|
const network = new pulumi.StackReference("acmecorp/network/other");
|
|
const vpcId = network.getOutput("vpcId");
|
|
```
|
|
|
|
The `getOutput` method above returns an `Output` value that holds the result.
|
|
You can call `Output.apply` to perform transformations on the output value.
|
|
As an example,
|
|
if you need to extract a subnet ID from a JSON string in the output,
|
|
you can use the following code:
|
|
|
|
```typescript
|
|
const subnetConfig = network.getOutput("subnetConfig");
|
|
const subnetId = subnetConfig.apply(output => JSON.parse(output).subnetId);
|
|
```
|
|
|
|
This approach works but is limited because
|
|
the output value obtained from the `apply` transformation
|
|
is also an `Output` value.
|
|
You cannot access or manipulate this value directly,
|
|
and you must continue to use `apply` repeatedly to consume the value.
|
|
|
|
As an aid in resolving this problem, we have introduced `OutputDetails`.
|
|
These provide direct access to the output of one stack from another stack.
|
|
|
|
## Introducing `OutputDetails`
|
|
|
|
We've added a new method, `StackReference.getOutputDetails`,
|
|
to allow direct access to output values from stack references.
|
|
This method can be used as follows:
|
|
|
|
```typescript
|
|
const vpcIdDetails = await network.getOutputDetails("vpcId");
|
|
const vpcId = vpcIdDetails.value;
|
|
```
|
|
|
|
Unlike the `getOutput` method,
|
|
the resulting value is a plain value, not an `Output` value.
|
|
As a result, there is no need to call `apply` repeatedly
|
|
to transform or consume the value.
|
|
|
|
Revisiting the previous example of extracting a value from a JSON string,
|
|
`getOutputDetails` can be used as shown below:
|
|
|
|
```typescript
|
|
const subnetConfig = (await network.getOutputDetails("subnetConfig")).value;
|
|
const subnetId = JSON.parse(subnetConfig).subnetId;
|
|
console.log(`Using subnet ID ${subnetId}`);
|
|
```
|
|
|
|
### What about secrets?
|
|
|
|
`getOutputDetails` can also be used to access secret outputs
|
|
generated by the referenced stack.
|
|
For example, if the referenced stack sets up a database
|
|
and produces the password as a stack output,
|
|
you can access it as follows:
|
|
|
|
```typescript
|
|
const passwordDetails = await dbStack.getOutputDetails("databasePassword");
|
|
const password = passwordDetails.secretValue;
|
|
```
|
|
|
|
### Can we do this for all `Output` values?
|
|
|
|
Unfortunately, it is not feasible to do this to every `Output` value.
|
|
Stack references are unique in that
|
|
the referenced stack must already have deployed
|
|
for the reference to be resolved.
|
|
Therefore, when the stack reference is created,
|
|
the outputs of the referenced stack are available immediately.
|
|
This is not the case for other `Output` values.
|
|
Their values only become available as `pulumi update` runs,
|
|
so we cannot access them in the same way.
|
|
|
|
## Availability
|
|
|
|
This feature is available in all stable SDKs for Pulumi,
|
|
starting from v3.55.0.
|
|
Give it a spin and share your thoughts with us on [Slack](https://slack.pulumi.com/)!
|