tb_pulumi

Standardization library for the usage of Pulumi in Python at Thunderbird. For an overview of how to use this library, read the Getting Started page.

class tb_pulumi.ProjectResourceGroup(pulumi_type: str, name: str, project: ThunderbirdPulumiProject, opts: ResourceOptions = None, tags: dict = {})

Bases: ThunderbirdComponentResource

A collection of all resources in a given project, determined after all resources in the Pulumi stack have been fully resolved (at the end of a pulumi up or pulumi preview, for example). This means that all available context about these resources is available by the time the tb_pulumi.ProjectResourceGroup.ready() function is called.

Parameters:

  • pulumi_type (str) – The “type” string (commonly referred to in docs as just t) of the component as described by Pulumi’s type docs.

  • name (str) – The name of the ProjectResourceGroup resource.

  • project (tb_pulumi.ThunderbirdPulumiProject) – The ThunderbirdPulumiProject to build a resource group out of.

  • opts (pulumi.ResourceOptions, optional) – Additional pulumi.ResourceOptions to apply to this resource. Defaults to None.

  • tags (dict, optional) – Key/value pairs to merge with the default tags which get applied to all resources in this group. Defaults to {}.

all_outputs

All Pulumi Outputs in the project

all_resources

All items in the project which are already-resolved pulumi resources

abstractmethod classmethod ready(outputs: list[Resource])

This function gets called only after all outputs in the project have been resolved into values. This function should be considered a post-apply stage of the __init__ function and a starting point for acting on a project with full context. When this function is called by the ProjectResourceGroup constructor, the class’s all_resources member will contain all resources in the stack with all outputs populated. This function is essentially a hand-off to an implementing class, an indicator that the project has been successfully applied, and all resource context is available for inspection.

This is an abstract method which must be implemented by an inheriting class. That function should inspect the self.all_resources variable for resources to act on.

Parameters:

outputs (list[pulumi.Resource]) – A list of resolved outputs discovered in the project. This is provided primarily for reference, and has limited value.

class tb_pulumi.ThunderbirdComponentResource(pulumi_type: str, name: str, project: ThunderbirdPulumiProject, exclude_from_project: bool = False, opts: ResourceOptions = None, tags: dict = {})

Bases: ComponentResource

A special kind of pulumi.ComponentResource which handles common elements of resources such as naming and tagging. All such resources must belong to a tb_pulumi.ThunderbirdPulumiProject.

Parameters:

  • pulumi_type (str) – The “type” string (commonly referred to in docs as just t) of the component as described by Pulumi’s docs.

  • name (str) – An identifier for this set of resources. Generally, this gets used as part of all resources defined by the ComponentResource.

  • project (tb_pulumi.ThunderbirdPulumiProject) – The project this resource belongs to.

  • exclude_from_project (bool, optional) – When True , this prevents this component resource from being registered directly with the project. This does not prevent the component resource from being discovered by the project’s flatten function, provided that it is nested within some resource that is not excluded from the project. This option largely pertains to the ability to debug resources after they have been applied, and is not something most users need worry themselves with. When developing a ThunderbirdComponentResource that includes other ThunderbirdComponentResources, the child resources should have this set to True. Defaults to False.

  • opts (pulumi.ResourceOptions, optional) – Additional pulumi.ResourceOptions to apply to this resource. Defaults to None.

  • tags (dict, optional) – Key/value pairs to merge with the default tags which get applied to all resources in this group. Defaults to {}.

finish(outputs: dict[str, Any] = {}, resources: dict[str, Flattenable] = {})

Stores the mapping of resources internally as the resources member of this component resource’s ThunderbirdPulumiProject, where they can be acted on collectively. Any implementation of this class should call this function at the end of its __init__ function to ensure its state is properly represented.

Values in resources should be of a type compatible with the Flattenable custom type.

Parameters:

  • outputs (dict[str, Any], optional) – Dict of outputs to register with Pulumi’s register_outputs function. This parameter is deprecated and will be removed in a future version. Defaults to {}.

  • resources (dict[str, Flattenable], optional) – Dict of Pulumi resources this component reosurce contains. Defaults to {}.

name: str

Identifier for this set of resources.

project: ThunderbirdPulumiProject

Project this resource is a member of.

property protect_resources: bool

Determines whether resources should have protection against changes enabled based on the project’s configuration. Unprotected resources are not part of a protected stack, or you have run Pulumi with TBPULUMI_DISABLE_PROTECTION=True set in your environment.

resources: dict

Resources which are members of this ComponentResource.

tags: dict

Tags to apply to all taggable resources

class tb_pulumi.ThunderbirdPulumiProject(protected_stacks: list[str] = ['prod'])

Bases: object

A collection of related Pulumi resources upon which we can take bulk/collective actions. This class enforces some usage conventions that help keep us organized and consistent.

Parameters:

protected_stacks (list[str], optional) – List of stack names which should require explicit instruction to modify. Defaults to tb_pulumi.constants.DEFAULT_PROTECTED_STACKS.

aws_account_id: str

Account number that the currently configured AWS user/role is a member of, in which Pulumi will act.

aws_region: str

Currently configured AWS region

common_tags: dict

Tags to apply to all taggable resources

property config: dict

Provides read-only access to the project configuration, which is expected to be in the root of your Pulumi project directory, and should match the current stack. For example, config.preprod.yaml would be a configuration for an environment called “preprod”.

flatten() → set[Resource]

Returns a flat set of all resources existing within this project.

get_aws_client(service: str, region_name: str = None)

Retrieves an AWS client for the requested service, preferably from a cache. Caches any clients it creates.

Parameters:

  • service (str) – Name of the service as described in boto3 docs

  • region_name (str) – Name of the AWS region to set the client up for, such as “us-east-1”.

get_latest_amazon_linux_ami(region_name: str = None, name_alias: str = 'al2023-ami-minimal-kernel-6.1-x86_64') → str

Returns the AMI ID of the latest Amazon Linux 2023 image for the given region. AWS provides many such AMIs for various purposes. By default, this returns the AMI for the x86-architecture HVM image with GP2 storage. You can specify a different image by providing the appropriate name_alias. This is accomplished by checking an SSM parameter that AWS publishes.

Parameters:

  • region_name (str, optional) – Name of the region to get the localized AMI ID for. Defaults to the project’s region.

  • name_alias (str, optional) –

    AMI name alias describing the image to look up. To see what values are valid for your region, run this AWSCLI command:

    aws ssm describe-parameters \
    --region $your_region_here \
    --filters 'Key=Name,Values=/aws/service/ami-amazon-linux-latest/' \
    --query 'Parameters[*].Name' |
    sed 's/\/aws\/service\/ami-amazon-linux-latest\///g'

    Defaults to al2023-ami-minimal-kernel-6.1-x86_64.

name_prefix: str

Convenience prefix for naming resources consistently

project: str

Name of the Pulumi project

protected_stacks: list[str]

List of stacks to apply resource deletion protection to

pulumi_config: Config

Pulumi configuration data referencing Pulumi.stack.yaml

resources: dict

Pulumi Resource objects managed by this project

stack: str

Name of the Pulumi stack

tb_pulumi.env_var_is_true(name: str) → bool

Determines if the value of the given environment variable represents “True” in some way.

Parameters:

name (str) – The environment variable to check

Returns:

True if the value of the environment variable looks like it is set to an affirmative value, otherwise False.

Return type:

bool

tb_pulumi.env_var_matches(name: str, matches: list[str], default: bool = False) → bool

Determines if the value of the given environment variable is in the given list. This is a case-insensitive check.

Parameters:

  • name (str) – The environment variable to check

  • matches (list[str]) – A list of strings to match against

  • default (bool, optional) – Default value if the variable doesn’t match. Defaults to False.

Returns:

True if the value of the given environment variable is in the given list, the provided default value if it is not, or None if the variable is unset.

Return type:

bool

  • name:

  • matches:

  • default:

tb_pulumi.flatten(item: Flattenable) → set[Resource | Output]

Recursively traverses a nested collection of Pulumi Resource s, converting them into a flat set which can be more easily iterated over.

Parameters:

item (dict | list | ThunderbirdComponentResource) – An item which we intend to flatten. Must be one of the recognized types or collections defined in the Flattenable type alias.

Returns:

A set of Pulumi Resource s contained within the collection.

Return type:

set(pulumi.Resource)