From d855c60d27a9af23b39f8d3d5a5bc5fcde4d087e Mon Sep 17 00:00:00 2001 From: Michele Cereda Date: Thu, 27 Mar 2025 23:26:00 +0100 Subject: [PATCH] chore(pulumi): expand on components --- knowledge base/pulumi.md | 122 +++++++++++++++++++++++++++++++++- snippets/pulumi/commands.fish | 2 + 2 files changed, 122 insertions(+), 2 deletions(-) diff --git a/knowledge base/pulumi.md b/knowledge base/pulumi.md index b9d0233..6a3a600 100644 --- a/knowledge base/pulumi.md +++ b/knowledge base/pulumi.md @@ -851,11 +851,124 @@ backend: ## Compose resources -FIXME +FIXME: should this be under [Program]? Refer [Component resources]. +Logical grouping of resources.
+Usually leveraged to instantiate a set of related resources, aggregate them as children, and create larger abstractions +that encapsulate their implementation details. + +Component resources only package a set of other resources.
+To have full control over resources' lifecycles in a Component, including running code upon updates or deletion, use +_dynamic providers_ instead. + +Refer [Pulumi Crosswalk for AWS] or [Google Cloud Static Website] as examples. +
+ Procedure + +1. Create a subclass of `ComponentResource`. + +
+ + ```ts + class StandardAwsVpc extends pulumi.ComponentResource {}; + ``` + +
+ +1. Inside its constructor, chain to the base constructor and pass it the subclass' name, arguments, and options. + + Upon creation of a new instance of the Component, the call to the base constructor registers the instance with the + Pulumi engine. This records the resource's state and tracks it across deployments, allowing to see differences during + updates just like any regular resource. + + All resources must have a name, so Components' constructors must accept one and pass it up.
+ Components must also register a unique _type name_ with the base constructor. These names are namespaced alongside + non-Component resources such as `aws:lambda:Function`. + +
+ + ```ts + class StandardAwsVpc extends pulumi.ComponentResource { + constructor(name: string, args: pulumi.Inputs, opts?: pulumi.ComponentResourceOptions) { + super("exampleOrg:StandardAwsVpc", name, {}, opts); + }; + }; + ``` + +
+ +1. Inside the subclass' constructor again, create any child resources.
+ Pass them the `parent` resource option to ensure the children are parented correctly. + +
+ + ```ts + class StandardAwsVpc extends pulumi.ComponentResource { + constructor(name: string, args: pulumi.Inputs, opts?: pulumi.ComponentResourceOptions) { + … + + const vpc = new aws.ec2.Vpc( + `${name}`, + { … }, + { parent: this }, + ); + const internetGateway = new aws.ec2.InternetGateway( + `${name}`, + { + vpcId: vpc.id, + … + }, + { parent: vpc }, + ); + }; + }; + ``` + +
+ +1. Inside the subclass' constructor once more, define the Component's own output properties with the `registerOutputs()` + function.
+ Pulumi's engine uses it display the logical outputs of the Component resource, and any changes to those outputs will + be shown during an update. + +
+ + ```ts + class StandardAwsVpc extends pulumi.ComponentResource { + constructor(name: string, args: pulumi.Inputs, opts?: pulumi.ComponentResourceOptions) { + … + + this.registerOutputs({ + vpcId: vpc.id, + }); + }; + }; + ``` + +
+ +1. Create new instances of the Component resource in the code. + +
+ + ```ts + class StandardAwsVpc extends pulumi.ComponentResource { … }; + const currentVpc = new StandardAwsVpc( + "currentVpc", + { cidrBlock: "172.31.0.0/16" }, + { protect: true }, + ); + ``` + +
+ +
+ +
+ Sample code ```ts import * as aws from "@pulumi/aws"; @@ -891,7 +1004,9 @@ export class StandardAwsVpc extends pulumi.ComponentResource { ); … - this.registerOutputs(); + this.registerOutputs({ + vpcId: vpc.id, + }); }; }; @@ -904,6 +1019,7 @@ const currentVpc = new StandardAwsVpc( cidrBlock: "172.31.0.0/16", }, + { protect: true }, ); ``` @@ -1170,12 +1286,14 @@ Solution: follow the suggestion in the warning message: [documentation]: https://www.pulumi.com/docs/ [enable pulumi refresh to solve pending creates]: https://github.com/pulumi/pulumi/pull/10394 [get started with pulumi policy as code]: https://www.pulumi.com/docs/using-pulumi/crossguard/get-started/ +[google cloud static website]: https://www.pulumi.com/registry/packages/google-cloud-static-website/ [iac recommended practices: developer stacks and git branches]: https://www.pulumi.com/blog/iac-recommended-practices-developer-stacks-git-branches/ [ignorechanges]: https://www.pulumi.com/docs/concepts/options/ignorechanges/ [importing resources]: https://www.pulumi.com/docs/iac/adopting-pulumi/import/ [organizing pulumi projects & stacks]: https://www.pulumi.com/docs/using-pulumi/organizing-projects-stacks/ [projects]: https://www.pulumi.com/docs/concepts/projects/ [pulumi config set-all]: https://www.pulumi.com/docs/cli/commands/pulumi_config_set-all/ +[pulumi crosswalk for aws]: https://www.pulumi.com/docs/iac/clouds/aws/guides/ [pulumi import]: https://www.pulumi.com/docs/iac/cli/commands/pulumi_import/ [pulumi new]: https://www.pulumi.com/docs/cli/commands/pulumi_new/ [pulumi preview]: https://www.pulumi.com/docs/iac/cli/commands/pulumi_preview/ diff --git a/snippets/pulumi/commands.fish b/snippets/pulumi/commands.fish index 4a21296..4613052 100644 --- a/snippets/pulumi/commands.fish +++ b/snippets/pulumi/commands.fish @@ -114,3 +114,5 @@ pulumi import 'aws:rds/instance:Instance' 'staging' 'odoo-staging-replica' pulumi import 'aws:route53/record:Record' 'hoppscotch' 'ZGG4442BC3E8M_hoppscotch.example.org_A' pulumi import 'aws:secretsmanager/secret:Secret' 'example' 'arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456' pulumi import 'aws:secretsmanager/secretVersion:SecretVersion' 'example' 'arn:aws:secretsmanager:us-east-1:123456789012:secret:example-123456|ABCDEF01-2345-6789-ABCD-EF0123456789' +pulumi import 'aws:vpc/securityGroupEgressRule:SecurityGroupEgressRule' 'allowAll' 'sgr-02108b27edd666983' +pulumi import 'aws:vpc/securityGroupIngressRule:SecurityGroupIngressRule' 'allowAll' 'sgr-02108b27edd666984'