Add new transforms docs

[justinvp]

Adds docs for the new transforms APIs. Ported from pulumi/pulumi-hugo#4044.

[pulumi-bot]

Your site preview for commit dbac5d8 is ready! 🎉

http://www-production-pulumi-docs-origin-pr-11851-dbac5d83.s3-website.us-west-2.amazonaws.com.

[EronWright]

I think it would be great to expand on how to transform the props, like explain that the values are encapsulated as Outputs, that you should expect variations related to secretness (should you?), and that you transform the outputs as explained elsewhere.

Here's an example of how to add a Kubernetes annotation. Would be awesome to show an example like this for each SDK.

const applyPatchForceAnnotation = async (args: pulumi.ResourceTransformArgs) => {
    switch(args.type) {
        case "kubernetes:helm.sh/v4:Chart":
            break;
        default:
            args.props.metadata.annotations = {
                "pulumi.com/patchForce": "true",
                ...args.props.metadata.annotations
            }
    }
    return {
        props: args.props,
        opts: args.opts,
    };
};

// Use Helm to install the Nginx ingress controller
const ingressController = new kubernetes.helm.v4.Chart("ingresscontroller", {
    chart: "nginx-ingress",
    namespace: ingressNs.metadata.name,
    repositoryOpts: {
        repo: "https://helm.nginx.com/stable",
    },
    skipCrds: false,
    values: {
        controller: {
            enableCustomResources: true,
            appprotect: {
                enable: false,
            },
            appprotectdos: {
                enable: false,
            },
            service: {
                extraLabels: appLabels,
            },
        },
    },
    version: "0.14.1",
}, {transforms: [applyPatchForceAnnotation]});

[EronWright]

A similar example in Python:

def apply_patchforce_annotation(args: ResourceTransformArgs):
    if not args.type_ == "kubernetes:helm.sh/v4:Chart":
        if not 'metadata' in args.props:
            args.props['metadata'] = {}
        if not 'annotations' in args.props['metadata']:
            args.props['metadata']['annotations'] = {}
        args.props['metadata']['annotations']['pulumi.com/patchForce'] = 'true'

    return ResourceTransformResult(
        props=args.props,
        opts=args.opts)

ingresscontroller = kubernetes.helm.v4.Chart(
    "ingresscontroller",
    chart="nginx-ingress",
    namespace=ingress_ns.metadata.name,
    repository_opts=kubernetes.helm.v3.RepositoryOptsArgs(
        repo="https://helm.nginx.com/stable",
    ),
    version="0.14.1",
    opts=pulumi.ResourceOptions(transforms=[apply_patchforce_annotation])
)

[justinvp]

I think it would be great to expand on how to transform the props, like explain that the values are encapsulated as Outputs, that you should expect variations related to secretness (should you?), and that you transform the outputs as explained elsewhere.

Agree! It's somewhat shown in some of the examples, but I'd like to expand on this as a fast follow.

Would be awesome to show an example like this for each SDK.

Yes. Haven't had a chance to port to each language, but would love to have more examples to show.

[tgummerer]

A few things I noticed while experimenting with transforms based of these docs.

[pulumi-bot]

Your site preview for commit 23ed418 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-11851-23ed418b.s3-website.us-west-2.amazonaws.com.