Update docs to include resources; remove outputs

thunderbird · Feb 11, 2025 · 827cccf · 827cccf
1 parent 5773a6c
commit 827cccf
Show file tree

Hide file tree

Showing 10 changed files with 232 additions and 96 deletions.
diff --git a/tb_pulumi/__init__.py b/tb_pulumi/__init__.py
@@ -17,8 +17,8 @@
 #: Type alias representing valid types to be found among a ThunderbirdPulumiProject's resources
 type Flattenable = dict | list | ThunderbirdComponentResource | pulumi.Output | pulumi.Resource
 
-FINISH_OUTPUTS_DEPRECATION_MESSAGE = """Calling ThunderbirdComponentResource.finish with the "outputs" parameter is DEPRECATED. This parameter will be
-    removed in a future version."""
+FINISH_OUTPUTS_DEPRECATION_MESSAGE = """Calling ThunderbirdComponentResource.finish with the "outputs" parameter is
+    DEPRECATED. This parameter will be removed in a future version."""
 
 
 class ThunderbirdPulumiProject:

diff --git a/tb_pulumi/ci.py b/tb_pulumi/ci.py
@@ -16,18 +16,23 @@ class AwsAutomationUser(tb_pulumi.ThunderbirdComponentResource):
 
     Produces the following ``resources``:
 
-    - *user* - `aws.iam.User <https://www.pulumi.com/registry/packages/aws/api-docs/iam/user/>`_ to run CI operations.
-    - *access_key* - `aws.iam.AccessKey <https://www.pulumi.com/registry/packages/aws/api-docs/iam/accesskey/>`_ for
-      that user's authentication.
-    - *secret* - :py:class:`tb_pulumi.secrets.SecretsManagerSecret` where the access key data is stored.
-    - *ecr_image_push_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
-      defining permissions required to push container images to an ECR repository.
-    - *s3_upload_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
-      defining permissions required to upload files to S3 buckets.
-    - *s3_full_access_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
-      defining complete, unfettered access to S3 buckets and their contents.
-    - *fargate_deployment_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
-      defining permissions needed to deploy images to a Fargate service.
+        - *user* - `aws.iam.User <https://www.pulumi.com/registry/packages/aws/api-docs/iam/user/>`_ to run CI
+          operations.
+        - *access_key* - `aws.iam.AccessKey <https://www.pulumi.com/registry/packages/aws/api-docs/iam/accesskey/>`_ for
+          that user's authentication.
+        - *secret* - :py:class:`tb_pulumi.secrets.SecretsManagerSecret` where the access key data is stored.
+        - *ecr_image_push_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
+          defining permissions required to push container images to an ECR repository, but only if
+          ``enable_ecr_image_push`` is ``True``.
+        - *s3_upload_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
+          defining permissions required to upload files to S3 buckets, but only if ``enable_s3_bucket_upload`` is
+          ``True``.
+        - *s3_full_access_policy* - `aws.iam.Policy
+          <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_ defining complete, unfettered access to
+          S3 buckets and their contents, but only if ``enable_full_s3_access`` is ``True``.
+        - *fargate_deployment_policy* - `aws.iam.Policy
+          <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_ defining permissions needed to deploy
+          images to a Fargate service, but only if ``enable_fargate_deployments`` is ``True``.
 
 
     :param name: Name of the IAM user to create.

diff --git a/tb_pulumi/cloudfront.py b/tb_pulumi/cloudfront.py
@@ -18,28 +18,29 @@ class CloudFrontS3Service(tb_pulumi.ThunderbirdComponentResource):
 
     Produces the following ``resources``:
 
-    - *service_bucket* - `aws.s3.Bucket <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucket/>`_ in which to
-      store the static content to be served over the CloudFront Distribution.
-    - *logging_bucket* - `aws.s3.Bucket <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucket/>`_ in which to
-      store the access logs for the service bucket.
-    - *logging_bucket_ownership* - `aws.s3.BucketOwnershipControls
-      <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketownershipcontrols/>`_ which allow CloudFront to
-      upload logs into the logging bucket.
-    - *logging_bucket_acl* - `aws.s3.BucketAclV2
-      <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketaclv2/>`_ allowing CloudFront to control the
-      logging bucket via the AWS account's canonical user.
-    - *origin_access_control* - `aws.cloudfront.OriginAccessControl
-      <https://www.pulumi.com/registry/packages/aws/api-docs/cloudfront/originaccesscontrol/>`_ allowing the CloudFront
-      Distribution to service the service bucket's content via CDN.
-    - *cloudfront_distribution* - `aws.cloudfront.Distribution
-      <https://www.pulumi.com/registry/packages/aws/api-docs/cloudfront/distribution/>`_ that serves the service bucket
-      content over a CDN and produces output logs in the logging bucket.
-    - *service_bucket_policy* - `aws.s3.BucketPolicy
-      <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketpolicy/>`_ allowing the CloudFront Distribution
-      read access to the objects in the service bucket.
-    - *invalidation_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
-      that allows an IAM entity to create cache invalidations in the CloudFront Distribution, which must be done when
-      the contents of the service bucket are updated.
+        - *service_bucket* - `aws.s3.Bucket <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucket/>`_ in
+          which to store the static content to be served over the CloudFront Distribution.
+        - *logging_bucket* - `aws.s3.Bucket <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucket/>`_ in
+          which to store the access logs for the service bucket.
+        - *logging_bucket_ownership* - `aws.s3.BucketOwnershipControls
+          <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketownershipcontrols/>`_ which allow CloudFront
+          to upload logs into the logging bucket.
+        - *logging_bucket_acl* - `aws.s3.BucketAclV2
+          <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketaclv2/>`_ allowing CloudFront to control the
+          logging bucket via the AWS account's canonical user.
+        - *origin_access_control* - `aws.cloudfront.OriginAccessControl
+          <https://www.pulumi.com/registry/packages/aws/api-docs/cloudfront/originaccesscontrol/>`_ allowing the
+          CloudFront Distribution to serve the service bucket's content via CDN.
+        - *cloudfront_distribution* - `aws.cloudfront.Distribution
+          <https://www.pulumi.com/registry/packages/aws/api-docs/cloudfront/distribution/>`_ that serves the service
+          bucket content over a CDN and produces output logs in the logging bucket.
+        - *service_bucket_policy* - `aws.s3.BucketPolicy
+          <https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketpolicy/>`_ allowing the CloudFront
+          Distribution read access to the objects in the service bucket.
+        - *invalidation_policy* - `aws.iam.Policy <https://www.pulumi.com/registry/packages/aws/api-docs/iam/policy/>`_
+          that allows an IAM entity to create cache invalidations in the CloudFront Distribution, which must be done
+          when the contents of the service bucket are updated. This is not attached to any entities; it exists for
+          developer use when setting up CI flows.
 
     :param name: A string identifying this set of resources.
     :type name: str

diff --git a/tb_pulumi/cloudwatch.py b/tb_pulumi/cloudwatch.py
@@ -9,8 +9,18 @@
 
 
 class CloudWatchMonitoringGroup(tb_pulumi.monitoring.MonitoringGroup):
-    """A ``MonitoringGroup`` that monitors AWS-based resources using AWS's CloudWatch service. This creates an SNS topic
-    to send its alarms on.
+    """A ``MonitoringGroup`` that monitors AWS-based resources using AWS's CloudWatch service and sends alerts using
+    SNS-to-email.
+
+    Produces the following ``resources``:
+
+        - *sns_topic* - `aws.sns.Topic <https://www.pulumi.com/registry/packages/aws/api-docs/sns/topic/>`_ to notify
+          when an alarm in this monitoring group is triggered.
+        - *sns_subscriptions* - A list of `aws.sns.TopicSubscription
+          <https://www.pulumi.com/registry/packages/aws/api-docs/sns/topicsubscription/>`_s, one for each entry in
+          ``notify_emails``.
+        - *alarms* - A list of alarms contained in this monitoring group. These may be any kind of alarm in the
+          `aws.cloudwatch <https://www.pulumi.com/registry/packages/aws/api-docs/cloudwatch/>`_ library.
 
     :param name: The name of the ``CloudWatchMonitoringGroup`` resource.
     :type name: str
@@ -101,7 +111,6 @@ def monitor(self, outputs):
             )
 
         self.finish(
-            outputs={'sns_topic_arn': sns_topic.arn},
             resources={'sns_topic': sns_topic, 'sns_subscriptions': subscriptions, 'alarms': alarms},
         )
 
@@ -164,15 +173,15 @@ class AlbAlarmGroup(tb_pulumi.monitoring.AlarmGroup):
     """A set of alarms for Application Load Balancers. Contains the following configurable alarms:
 
         - ``alb_5xx``: Alarms on the number of HTTP responses sourced within the load balancer with status codes in the
-            500-599 range, indicating a count of internal server errors. This metric concerns the load balancer itself,
-            and does not contain any response codes generated by the targets. Defaults to alarming on 10 errors in 1
-            minute.
+          500-599 range, indicating a count of internal server errors. This metric concerns the load balancer itself,
+          and does not contain any response codes generated by the targets. Defaults to alarming on 10 errors in 1
+          minute.
         - ``target_5xx``: Alarms on the number of HTTP responses sourced within the load balancer's targets with status
-            codes in the 500-599 range, indicating a count of internal server errors. This metric concerns the
-            applications the load balancer points to, and does not contain any response codes generated by the load
-            balancer itself. Defaults to alarming on 10 errors in 1 minute.
+          codes in the 500-599 range, indicating a count of internal server errors. This metric concerns the
+          applications the load balancer points to, and does not contain any response codes generated by the load
+          balancer itself. Defaults to alarming on 10 errors in 1 minute.
         - ``response_time``: Alarms on the average response time of HTTP requests. Defaults to alarming if the average
-            response time over a minute is longer than 1 second.
+          response time over a minute is longer than 1 second.
 
     Further detail on these metrics and others can be found within `Amazon's ALB metrics documentation
     <https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-cloudwatch-metrics.html>`_.
@@ -306,7 +315,7 @@ class AlbTargetGroupAlarmGroup(tb_pulumi.monitoring.AlarmGroup):
     """A set of alarms for ALB target groups. Contains the following configurable alarms:
 
         - ``unhealthy_hosts``: Alarms on the number of unhealthy hosts in a target group. Defaults to alarm when the
-            average of unhealthy hosts is over 1 in 1 minute.
+          average of unhealthy hosts is over 1 in 1 minute.
 
     Further detail on these metrics and others can be found within `Amazon's Target Group metric documentation
     <https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-cloudwatch-metrics.html#target-metric-table>`_.
@@ -422,8 +431,8 @@ class CloudFrontDistributionAlarmGroup(tb_pulumi.monitoring.AlarmGroup):
     """A set of alarms for CloudFront distributions. Contains the following configurable alarms:
 
         - ``distro_4xx``: Alarms on the rate of HTTP responses with status codes in the 400-499 range, indicating an
-            elevated number of calls to invalid files. This value is reported as a percentage of all responses. Defaults
-            to alarm on at least 10% 4xx codes in 1 minute.
+          elevated number of calls to invalid files. This value is reported as a percentage of all responses. Defaults
+          to alarm on at least 10% 4xx codes in 1 minute.
 
     Further details about these metrics and more can be found in `Amazon's CloudFront distribution documentation
     <https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/programming-cloudwatch-metrics.html#cloudfront-metrics-distribution-values>`_.
@@ -498,9 +507,9 @@ def __init__(
 class CloudFrontFunctionAlarmGroup(tb_pulumi.monitoring.AlarmGroup):
     """A set of alarms for CloudFront functions. Contains the following configurable alarms:
 
-    - ``cpu_utilization``: Alarms when the function's compute utilization is excessive. This value is reported as a
-        percentage of its allotted CPU. Defaults to alarm when the function's CPU usage has been over 80% on average for
-        1 minute.
+        - ``cpu_utilization``: Alarms when the function's compute utilization is excessive. This value is reported as a
+          percentage of its allotted CPU. Defaults to alarm when the function's CPU usage has been over 80% on average
+          for 1 minute.
 
     Further details about these metrics and more can be found in `Amazon's CloudFront Functions documentation
     <https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/programming-cloudwatch-metrics.html#cloudfront-metrics-function-values>`_.
@@ -578,9 +587,9 @@ class EcsServiceAlarmGroup(tb_pulumi.monitoring.AlarmGroup):
     """A set of alarms for ECS services. Contains the following configurable alarms:
 
         - ``cpu_utilization``: Alarms on the overall CPU usage of the entire service, all tasks combined. Threshold is a
-            percentage.
+          percentage.
         - ``memory_utilization``: Alarms on the overall memory usage of the entire service, all tasks combined.
-            Threshold is a percentage.
+          Threshold is a percentage.
 
     Further detail on these metrics and more can be found on `Amazon's documentation
     <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/available-metrics.html>_`.

diff --git a/tb_pulumi/ec2.py b/tb_pulumi/ec2.py
@@ -17,6 +17,20 @@ class NetworkLoadBalancer(tb_pulumi.ThunderbirdComponentResource):
     """Construct a NetworkLoadBalancer to route TCP traffic to a collection of backends. This targets backend services
     by IP address, connecting a frontend listening port to a backend port on the round-robin load balanced targets.
 
+    Produces the following ``resources``:
+
+        - *security_group_with_rules* - :py:class:`tb_pulumi.network.SecurityGroupWithRules` defining ingress and egress
+          rules for the NLB.
+        - *nlb* - `aws.lb.LoadBalancer <https://www.pulumi.com/registry/packages/aws/api-docs/lb/loadbalancer/>`_ with a
+          ``load_balancer_type`` of ``network``.
+        - *target_group* - `aws.lb.TargetGroup <https://www.pulumi.com/registry/packages/aws/api-docs/lb/targetgroup/>`_
+          containing the IPs the NLB is balancing.
+        - *target_group_attachments* - List of `aws.lb.TargetGroupAttachments
+          <https://www.pulumi.com/registry/packages/aws/api-docs/lb/targetgroupattachment/>`_, one for each IP address
+          registered with the NLB.
+        - *listener* - `aws.lb.Listener <https://www.pulumi.com/registry/packages/aws/api-docs/lb/listener/>`_ for the
+          NLB.
+
     :param name: A string identifying this set of resources.
     :type name: str
 
@@ -178,7 +192,6 @@ def __init__(
         )
 
         self.finish(
-            outputs={'dns_name': nlb.dns_name},
             resources={
                 'security_group_with_rules': security_group_with_rules,
                 'nlb': nlb,
@@ -192,6 +205,13 @@ def __init__(
 class SshableInstance(tb_pulumi.ThunderbirdComponentResource):
     """Builds an EC2 instance which can be accessed with SSH from somewhere on the Internet.
 
+    Produces the following ``resources``:
+
+        - *instance* - The `aws.ec2.Instance <https://www.pulumi.com/registry/packages/aws/api-docs/ec2/instance/>`_.
+        - *keypair* - :py:class:`tb_pulumi.ec2.SshKeyPair` used for authenticating to the instance.
+        - *security_group* - :py:class:`tb_pulumi.network.SecurityGroupWithRules` defining network access to the
+          instance.
+
     :param name: A string identifying this set of resources.
     :type name: str
 
@@ -302,10 +322,6 @@ def __init__(
         )
 
         self.finish(
-            outputs={
-                'instance_dns': instance.public_dns,
-                'instance_ip': instance.public_ip,
-            },
             resources={
                 'instance': instance,
                 'keypair': keypair,
@@ -322,6 +338,13 @@ class SshKeyPair(tb_pulumi.ThunderbirdComponentResource):
     ONE TIME. Each ``pulumi up/preview`` command generates a new keypair, which generates new secret versions (and if
     this is attached to an instance downstream, it triggers the recreation of that instance).
 
+    Produces the following ``resources``:
+
+        - *keypair* - `aws.ec2.KeyPair <https://www.pulumi.com/registry/packages/aws/api-docs/ec2/keypair/>`_ containing
+          the keypair content.
+        - *private_key_secret* :py:class:`tb_pulumi.secrets.SecretsManagerSecret` containing the private key data.
+        - *public_key_secret* :py:class:`tb_pulumi.secrets.SecretsManagerSecret` containing the public key data.
+
     :param name: A string identifying this set of resources.
     :type name: str
 
@@ -404,9 +427,7 @@ def __init__(
             )
 
         self.finish(
-            outputs={'keypair': keypair.id},
             resources={
-                'private_key': private_key if not public_key else None,
                 'keypair': keypair,
                 'private_key_secret': private_key_secret if not public_key else None,
                 'public_key_secret': public_key_secret if not public_key else None,