asg

README

asg

github.com/truvity/asg is a Pulumi Go library for running a service as an EC2 Auto Scaling group: a machine, or a few, built from user-data and replaced rather than repaired.

• asg.New registers the group and its launch template, an optional warm pool of stopped instances, a launch lifecycle hook whose default result is ABANDON (an instance that never finished booting is replaced, not put in service half configured), an IAM role and instance profile with the least privilege the user-data needs, and a security group.

• module and modules/ are the extension mechanism: a module returns data (user-data fragments, IAM statements, SSM parameter names, ingress rules, the steps and checks of the on-box lifecycle) and never a resource, so turning one on changes the launch template and the policy, not the set of resources. Shipped: datavolume (format once and mount a persistent EBS volume), watchdog (replace an instance whose local checks keep failing), ssh (opkssh and a fixed host key), selfregister (a DNS record for the in-service instance), tunnel (a Cloudflare tunnel connector that starts only in service) and ssmcert (a TLS certificate, key and CA from SSM into /run, with a nightly rotation that takes the box out of service through Standby while its daemon restarts).

• bootstrap composes the user-data from fragments: systemd units, files, the secrets an instance reads at boot (SSM parameters and S3 objects, by exact name) and the readiness step that completes the lifecycle hook. The IAM policy is derived from it, so the instance can read exactly what its user-data names and nothing else.

• front puts boxes behind an internal network load balancer: a shared NLB per environment (front.NewSharedNLB), a box's target group, TCP listener and port-scoped security group rules on it (front.Attach), or an NLB of its own (front.NewNLB). The port is the service's identity, and only the NLB's security group reaches the targets.

The rules the component enforces, whatever the caller passes:

• IMDSv2 is always required;
• a bare * action is refused;
• no managed policy is attached by default;
• a warm pool without a lifecycle hook is refused;
• the image is pinned at deploy time, so a newer image is a visible diff.

Who it is for

Anyone running a service on EC2 the replace-don't-repair way with Pulumi in Go: a stateless box, or a small fleet, whose whole configuration is its user-data, behind a load balancer, a tunnel or nothing at all.

The model

One call, asg.New, registers an Auto Scaling group and everything it needs as children of one component. The user-data is a bootstrap.Plan: files, units and the secrets the instance reads at boot, by exact name. The IAM policy is derived from the plan, so an instance can read what its user-data names and nothing else. A launch lifecycle hook with a default of ABANDON means an instance that never finished booting is replaced, never put in service half configured.

One instance with a persistent volume

For a box that is started and stopped on demand, Args.Single makes the appliance one plain EC2 instance (no Auto Scaling group, hook or warm pool), and Args.Data gives it an encrypted EBS volume that outlives it:

a.UserData = plan // rendered WITHOUT bootstrap.Options.Lifecycle
a.Instance.Type = "m7g.xlarge"
a.Single = &asg.SingleArgs{
    SubnetID:     subnet.ID(),          // must be in Data.AvailabilityZone
    RoleTagKey:   "role", RoleTagValue: "builder", // how the proxy finds it
}
a.Data = &asg.DataVolumeArgs{AvailabilityZone: "eu-west-1a", SizeGiB: 500, KMSKeyID: keyARN}
// in the plan: datavolume.New(datavolume.Args{MountPoint: "/var/lib/cache", Units: []string{"buildkitd.service"}})

• A new image or user-data replaces the instance (deleted first, so the volume is free); the replacement comes up running. The volume is detached from the old instance after it is stopped, and attached to the new one.
• Pulumi does not manage the run state: stop and start the instance from outside and the next preview shows no diff.
• The volume is protected and retained on delete. Removing it takes a deliberate pulumi state unprotect and a manual delete.
• Refused with Single: Hook, WarmPool, Refresh, Instance.Types, Alarms, every Group field, Instance.PublicIP, module group actions and in-service steps.

See the package documentation for the details.

Stopped on demand: a wake proxy in front of single boxes

A big box that is idle most of the day can be kept stopped. A small always-on proxy (cmd/wake-proxy, ADR 0006) sits in front of it: a client connects to the proxy through the NLB and sends its first byte (a bare connect and close, such as a TCP health probe, wakes nothing and keeps nothing alive; WakeOn: "connect" on a route restores acting on accept for protocols where the server speaks first), the proxy starts the stopped instance, holds the client's TCP connection until the port accepts (up to a wake timeout, default 180 s), pipes the stream through (mutual TLS stays end to end; the proxy never terminates TLS) and stops the instance after 20 minutes without a connection. Pulumi never owns the run state.

Wire it in three parts.

1. The boxes: Args.Single plus Args.Data, as above, each with a tag the proxy selects it by (RoleTagKey/RoleTagValue, one distinct value per box; exactly one instance may match). The box's security group admits the proxy's security group on the service port, not the NLB's:

   builder.Security.Ingress = []asg.Rule{{
       Description:  "service from the wake proxy",
       FromPort:     1234, ToPort: 1234,
       SourceGroups: []pulumi.StringInput{proxySG.ID()},
   }}
   

   Single.TargetGroups stays empty: the box is no longer a target of anything.

2. The proxy: an ordinary appliance in the Auto Scaling mode (desired 1 and one stopped warm-pool spare, a launch hook, a t4g.nano-class type), with the modules/wakeproxy module in its plan. Binary is the pinned release build per architecture: wakeproxy.ReleaseURL("v0.6.0", "arm64") and the digest from the release's checksums.txt.

   proxy := wakeproxy.New(wakeproxy.Args{
       Binary: map[string]bootstrap.Source{"arm64": {URL: wakeproxy.ReleaseURL(version, "arm64"), SHA256: digest}},
       Region: region,
       Routes: []wakeproxy.Route{
           {Name: "arm64", ListenPort: 9001, TargetPort: 1234, Target: wakeproxy.Selector{TagKey: "role", TagValue: "builder-arm64"}},
           {Name: "amd64", ListenPort: 9002, TargetPort: 1234, Target: wakeproxy.Selector{TagKey: "role", TagValue: "builder-amd64"}},
       },
       Account:    account,                 // set it to get the role statements below
       KMSKeyARNs: []string{dataKeyARN},    // only if the builders' volumes use a customer-managed key
   })
   

   With Account set the module adds the statements of wakeproxy.Statements: ec2:DescribeInstances on *; ec2:StartInstances/ec2:StopInstances and ec2:CreateTags (activity tag key only) on instances that carry the builder's tag, by condition; and, for a customer-managed key, kms:CreateGrant (AWS resources only), kms:Decrypt and kms:GenerateDataKeyWithoutPlaintext. Without the key statements, starting a box with an encrypted volume leaves it in pending. Leave Account empty to call Statements yourself.

3. The front: front.Attach one front.Listener per route on the NLB: Port is the builder's registered port (its identity on the NLB), TargetPort the route's ListenPort, HealthCheck is HTTP, path /healthz, on the proxy's HealthPort (default 8080). That check is 200 whenever the proxy runs, whether or not a builder is up. Set IdleTimeoutSeconds above the wake timeout (the NLB's default of 350 is enough for 180) and above the longest quiet period of a build stream. Put Front.TargetIngress() in the proxy's own security group. The NLB's target group moves from the builder to the proxy.

The first connection after an idle period waits for the wake (about 40 to 60 seconds); the client needs a retry loop longer than its own connect timeout.

Install and a worked example

go get github.com/truvity/asg

import (
    "github.com/truvity/asg"
    "github.com/truvity/asg/bootstrap"
)

Build a bootstrap.Plan, render it, and pass the result to asg.New with the group, instance, IAM and network arguments. The package documentation and composed_test.go show a complete box made of a plan and modules. Compat lets an existing group move onto this library without Pulumi replacing anything: it keeps the component type, the logical names and the layout the group was created with.

Consumers

The status page box in truvity/observability (pkg/statusbox/ec2).

Neighbours

truvity/aws-structure shapes the AWS organization this runs in; the code here used to live there as pkg/appliance and pkg/bootstrap.

Documentation

The package documentation, and the decisions under docs/decisions/.

The rule that makes this repository public

Mechanism only. Account ids, regions, names, images and policy statements are the caller's; nothing here defaults to one estate's value, and the tests use Pulumi mocks and never reach an AWS account. hack/leak-canary.sh enforces the mechanical half over tracked files and runs in the gate, with no exception.

Status

v0.x: the API may change in a minor release, and every change is in the CHANGELOG. v0.1.0 is the code that was pkg/appliance and pkg/bootstrap in truvity/aws-structure, moved without a behaviour change; v0.2.0 adds the module package and the first four modules, and changes two defaults (see the CHANGELOG); v0.3.0 adds front; v0.4.0 adds data volumes, several instance types, warm-pool reuse on scale-in, termination policies, module group actions and ssmcert.

Development

devbox shell
just check      # build, test, lint, leak-canary

Releasing

Releases are a v* tag, which the shared release workflow turns into the Go module version and a GitHub Release. Automatic patch releases are not armed; releases are hand-cut tags.

Licence

MIT, see LICENSE.

Documentation

Overview

Package asg provisions an EC2 appliance: a machine, or a few, that is built from user-data, joins an Auto Scaling group and is replaced rather than repaired. It sits next to bootstrap, which composes the user-data; this package gives that user-data a home and the least privilege it needs.

One call, New, registers these children under one component (or, with Compat.Flat, directly under the caller's parent):

• an Auto Scaling group of Min..Max and a launch template;
• a warm pool of stopped instances (optional);
• an EC2_INSTANCE_LAUNCHING lifecycle hook, on the group or as a separate resource, whose DefaultResult is ABANDON: bootstrap-ready.service sends CONTINUE on every boot, so an instance that never finished is replaced instead of put in service half configured;
• an IAM role and instance profile whose policy is built from the user-data: ssm:GetParameter on exactly the plan's parameter names, s3:GetObject on exactly the plan's object keys and the two Auto Scaling actions the lifecycle scripts call, scoped to the group, plus the statements the caller adds;
• a security group, its rules inline or separate;
• the plan's S3 objects, uploaded (this is the only thing bootstrap leaves to the caller), and the CloudWatch alarms the caller asks for.

The image is found by name filter or by SSM parameter at deploy time and pinned in the launch template, so a newer image is a visible diff and a rolling refresh. IMDSv2 is always required; the hop limit is configurable (a container on the instance needs 2).

Migrating without a replace

An appliance that exists today is adopted in two steps, and both are possible with this package.

Step A. The caller passes the old user-data unchanged (bootstrap.Verbatim) and the options of Compat reproduce every logical name, parent, type and physical name; Args.IAM.Policy returns the old policy document. The preview is empty: no launch template version, no refresh.

Step B. The caller switches to a composed plan and drops the overrides. The launch template gets one new version, which an instance refresh rolls out, and the role's policy is tightened in place.

Extension points

A Module contributes bootstrap fragments, IAM statements, SSM parameters, security group rules, and the steps and checks of the on-box lifecycle in one piece. Collect merges modules into a Contribution that Args.Contribution takes and that [Contribution.AddTo] feeds to the plan. The Pulumi-free package module defines the types and modules/ ships five: watchdog, ssh, selfregister, tunnel and datavolume.

One plain instance, with a persistent cache volume

Args.Single replaces the Auto Scaling group by one aws.ec2.Instance created from the same launch template, for a box that something else starts and stops on demand (a proxy). The role, instance profile, security group, image lookup, S3 objects and user-data are as in group mode; there is no group, hook, warm pool, refresh, health check or scaling, so Hook, WarmPool, Refresh, Types, Alarms, the Group fields and module group actions are refused, the role gets no autoscaling permission, and the user-data must be rendered without bootstrap.Options.Lifecycle (nothing would answer a hook).

A new image or new user-data is a new launch template version and replaces the instance, deleting the old one first; the replacement comes up running. The run state is not managed by Pulumi (there is no instance state resource), so a stopped instance shows no diff. The instance carries a caller-chosen role tag (SingleArgs.RoleTagKey and RoleTagValue) that a proxy finds it by, since the instance id changes on replacement; the private address survives a stop and start, not a replacement. It joins a target group only if SingleArgs.TargetGroups says so.

Args.Data adds an encrypted EBS volume in one availability zone, protected and retained on delete, attached by a resource of its own. On a replacement the old attachment is deleted first (the old instance is stopped, so the file system is cleanly detached), and the new instance attaches the same volume, so a cache survives stop and start and an upgrade. The subnet must be in the volume's zone: New fails the update otherwise. modules/datavolume formats a blank volume once and mounts it on every boot, before the services that need it start.

The on-box lifecycle

A step that must run only when the instance goes in service (start a daemon, read a secret) is a Step; a check that must pass before the launch hook is completed is a ReadyCheck. The library writes them as files and runs them from one oneshot unit that does nothing in the warm pool, and bootstrap-ready.service completes the hook only if that unit succeeded.

Index

• Constants
• func AssumeRolePolicy(partition string) string
• func Document(statements []Statement) (string, error)
• func GroupARN(partition, region, account, group string) string
• func ObjectARN(partition, bucket, key string) string
• func ParameterARN(partition, region, account, name string) string
• type Alarm
• type AlarmsArgs
• type Appliance
  • func New(ctx *pulumi.Context, name string, args *Args, opts ...pulumi.ResourceOption) (*Appliance, error)
• type Args
• type Compat
• type Contribution
  • func Collect(mods ...Module) (Contribution, error)
• type DataVolumeArgs
• type GroupArgs
• type HookArgs
• type HookMode
• type IAMArgs
• type ImageArgs
• type InlinePolicy
• type InstanceArgs
• type Kind
• type Logical
• type Module
• type Names
  • func (n Names) Resolve(name string) Resolved
• type ObjectsArgs
• type PolicyContext
• type PolicyInput
• type ReadyCheck
• type RefreshArgs
• type Resolved
  • func (r Resolved) Lifecycle() *bootstrap.Lifecycle
• type RootVolumeArgs
• type Rule
• type RuleStyle
• type SecurityArgs
• type SingleArgs
• type Statement
  • func BootstrapStatements(in PolicyInput) []Statement
• type Step
• type TargetGroupAttachment
• type VolumeArgs
• type WarmPoolArgs
• type WatchCheck

Constants

const (
	// TypeToken is the Pulumi type of the component unless Compat.ComponentType
	// overrides it.
	TypeToken = "truvity:asg:Box"

	DefaultPartition        = "aws"
	DefaultHeartbeatSeconds = 900
	DefaultGracePeriod      = 300
	DefaultHopLimit         = 1
	DefaultRootDevice       = "/dev/xvda"
	DefaultDataDevice       = "/dev/sdf"
	DefaultRootVolumeGiB    = 8
	DefaultVolumeType       = "gp3"
	// MaxDataVolumes bounds InstanceArgs.Volumes: device names /dev/sdf to
	// /dev/sdp.
	MaxDataVolumes     = 11
	DefaultPolicyName  = "appliance"
	DefaultContentType = "text/plain"
)

Defaults.

const (
	SidReadParameters = "ReadParameters"
	SidReadObjects    = "ReadObjects"
	SidOwnGroup       = "OwnGroup"
)

Statement ids of BootstrapStatements.

const PolicyVersion = "2012-10-17"

PolicyVersion is the IAM policy language version of every document.

Functions

func AssumeRolePolicy

func AssumeRolePolicy(partition string) string

AssumeRolePolicy lets EC2 assume the instance role.

func Document

func Document(statements []Statement) (string, error)

Document renders statements as a policy document, indented by two spaces. A statement without an Effect is an Allow.

func GroupARN

func GroupARN(partition, region, account, group string) string

GroupARN is the ARN of an Auto Scaling group.

func ObjectARN

func ObjectARN(partition, bucket, key string) string

ObjectARN is the ARN of an S3 object.

func ParameterARN

func ParameterARN(partition, region, account, name string) string

ParameterARN is the ARN of an SSM parameter named like /estate/token.

Types

type Alarm

type Alarm struct {
	// Suffix names the alarm: "<Base>-<Suffix>", and its logical name.
	Suffix string
	// Name, when set, is the alarm's physical name instead.
	Name        string
	Description string
	Namespace   string
	MetricName  string
	Statistic   string
	// Comparison is GreaterThanThreshold, GreaterThanOrEqualToThreshold,
	// LessThanThreshold or LessThanOrEqualToThreshold.
	Comparison        string
	Threshold         float64
	PeriodSeconds     int
	EvaluationPeriods int
	DatapointsToAlarm int
	// TreatMissingData defaults to missing.
	TreatMissingData string
	Dimensions       map[string]string
}

Alarm is one metric alarm. Dimensions default to the group.

Deprecated: see Args.Alarms.

type AlarmsArgs

type AlarmsArgs struct {
	// ActionARNs are notified when an alarm fires (e.g. an SNS topic).
	// Empty: the alarms notify nobody.
	ActionARNs   []string
	OKActionARNs []string
	Alarms       []Alarm
}

AlarmsArgs are CloudWatch alarms on the appliance.

Deprecated: see Args.Alarms.

type Appliance

type Appliance struct {
	pulumi.ResourceState

	// Names are the physical names after defaults.
	Names Resolved
	// Group is the Auto Scaling group; nil in single-instance mode.
	Group *autoscaling.Group
	// Instance is the plain EC2 instance of single-instance mode
	// (Args.Single); nil with a group.
	Instance *ec2.Instance
	// DataVolume and DataAttachment are the persistent volume of Args.Data
	// and its attachment to Instance; nil without Data.
	DataVolume     *ebs.Volume
	DataAttachment *ec2.VolumeAttachment
	// TargetAttachments register Instance in Single.TargetGroups.
	TargetAttachments []*lb.TargetGroupAttachment
	// LaunchTemplate carries the image, the user-data and IMDSv2.
	LaunchTemplate *ec2.LaunchTemplate
	// Role and InstanceProfile are the instance's identity.
	Role            *iam.Role
	InstanceProfile *iam.InstanceProfile
	// Policy is the role's main inline policy document as exact JSON: the
	// bytes the role carries, so a golden of it is a review artifact.
	Policy pulumi.StringOutput
	// ManagedPolicies are the attachments of Args.IAM.ManagedPolicyARNs.
	ManagedPolicies []*iam.RolePolicyAttachment
	// SecurityGroup is the group the appliance created; nil with
	// Security.ExistingGroups.
	SecurityGroup *ec2.SecurityGroup
	// Rules are the separate rule resources (RulesSeparate, RulesLegacy).
	Rules []pulumi.Resource
	// Hook is the separate lifecycle hook; nil for an inline hook or none.
	Hook *autoscaling.LifecycleHook
	// Objects are the uploaded S3 objects, in the order of UserData.Objects
	// then Objects.Extra.
	Objects []*s3.BucketObjectv2
	// Alarms are the CloudWatch alarms, in the order of Alarms.Alarms.
	Alarms []*cloudwatch.MetricAlarm
}

Appliance is what New creates. With Compat.Flat it is a plain holder and not a registered component.

func New

func New(ctx *pulumi.Context, name string, args *Args, opts ...pulumi.ResourceOption) (*Appliance, error)

New creates the appliance. It refuses an invalid Args, all problems at once, before it registers anything.

The user-data is applied at launch: a change to it is a new launch template version, which Refresh rolls out.

type Args

type Args struct {
	// Names sets the physical names. Default: all derived from the
	// logical name.
	Names Names
	// Partition is the ARN partition. Default "aws".
	Partition string
	// Tags are added to every resource that takes tags.
	Tags map[string]string
	// Provider is the AWS provider the region, account and image lookups
	// go through. The resources take the options New is called with.
	Provider *aws.Provider

	// UserData is the instance's user-data. Required: a composed plan
	// (bootstrap.Plan.Render) or bootstrap.Verbatim. Its objects are
	// uploaded and its SSM parameters and object keys are granted to the
	// role.
	UserData *bootstrap.Rendered
	// Objects says where UserData.Objects are uploaded.
	Objects ObjectsArgs

	Image    ImageArgs
	Instance InstanceArgs
	// Group configures the Auto Scaling group. Single-instance mode
	// (Single set) has no group and refuses every field of it.
	Group GroupArgs
	// Single, when set, makes the appliance one plain EC2 instance
	// created from the launch template, with no Auto Scaling group, hook,
	// warm pool or refresh. See [SingleArgs].
	Single *SingleArgs
	// Data is a persistent EBS volume that outlives the instance. It
	// needs Single. See [DataVolumeArgs].
	Data *DataVolumeArgs
	// Hook is the launch lifecycle hook; nil declares none.
	Hook *HookArgs
	// WarmPool is the warm pool; nil declares none. It needs Hook.
	WarmPool *WarmPoolArgs
	// Refresh is the group's instance refresh; nil declares none.
	Refresh *RefreshArgs

	IAM      IAMArgs
	Security SecurityArgs
	// Alarms are CloudWatch alarms on the group.
	//
	// Deprecated: monitoring is self-hosted. An alarm with no action is
	// read by nobody; export metrics from the box instead. Alarms keep
	// working and are removed no sooner than the next minor release.
	Alarms AlarmsArgs

	// Contribution is what the modules add (see Collect).
	Contribution Contribution

	// Compat keeps the names of an existing program.
	Compat Compat
}

Args is New's whole input.

type Compat

type Compat struct {
	// ComponentType overrides the component's Pulumi type, so a program
	// that already has a component of its own type keeps its URNs.
	ComponentType string
	// Flat registers no component: the children keep the caller's
	// parent, as in a program that never had one.
	Flat bool
	// Names are the logical names of the children.
	Names Logical
	// Aliases are added to the children, by kind.
	Aliases map[Kind][]pulumi.Alias
	// ComponentAliases are added to the component.
	ComponentAliases []pulumi.Alias
	// GroupTagsExcludeCommon leaves Args.Tags off the group's propagated
	// tags (only Name and ManagedBy remain), as programs did before.
	GroupTagsExcludeCommon bool
	// LaunchTemplateTagTypes are the resource types the launch template
	// tags at launch, in this order. Empty: instance and volume. A
	// program that tagged only its instances lists "instance", so its
	// launch template keeps its version and nothing is refreshed.
	LaunchTemplateTagTypes []string
	// AssumeRolePolicy, when set, is the role's trust policy, byte for
	// byte, instead of [AssumeRolePolicy]: for a program whose own
	// document says the same in another layout. It must be a JSON
	// object.
	AssumeRolePolicy string
}

Compat keeps an existing program's resources where they are.

type Contribution

type Contribution = module.Contribution

Contribution is what modules add; see module.Contribution.

func Collect

func Collect(mods ...Module) (Contribution, error)

Collect merges the modules' contributions in the order given.

type DataVolumeArgs

type DataVolumeArgs struct {
	// AvailabilityZone is the zone of the volume and so of the instance.
	// Required.
	AvailabilityZone string
	// DeviceName is /dev/sdf to /dev/sdp. Default /dev/sdf.
	DeviceName string
	// SizeGiB is required, 1..16384.
	SizeGiB int
	// Type defaults to gp3.
	Type string
	// IOPS and ThroughputMiBps, 0 keeps the type's baseline. Throughput
	// is gp3 only.
	IOPS            int
	ThroughputMiBps int
	// KMSKeyID encrypts with that key (a key ARN); empty: the account's
	// default EBS key. The key's policy must let the principal that
	// attaches and EC2 use it.
	KMSKeyID string
}

DataVolumeArgs is a persistent EBS volume for a single instance. It is created next to the instance, is protected and retained on delete, so no destroy of the appliance removes it, and it is attached with a separate attachment that moves to the new instance on a replacement. It lives in one availability zone and is always encrypted.

The user-data mounts it: see modules/datavolume, which formats a blank volume once and mounts it on every boot. The volume id is not known when the user-data is rendered, so the module finds the device by its DeviceName.

type GroupArgs

type GroupArgs struct {
	// Min, Max and Desired default to 1 (Max and Desired to Min).
	Min, Max, Desired int
	// SubnetIDs are required.
	SubnetIDs []pulumi.StringInput
	// HealthCheckType defaults to EC2.
	HealthCheckType string
	// GracePeriodSeconds defaults to 300.
	GracePeriodSeconds int
	// TargetGroupARNs registers the group's instances in these target
	// groups (front.Front.TargetGroupARNs). With HealthCheckType ELB a
	// failing target health check replaces the instance.
	TargetGroupARNs []pulumi.StringInput
	// EnabledMetrics are group metrics sent to CloudWatch (an alarm on
	// GroupInServiceInstances needs it).
	EnabledMetrics []string
	// TerminationPolicies say which instance a scale-in removes, in
	// order (OldestInstance, NewestInstance, OldestLaunchTemplate,
	// ClosestToNextInstanceHour, AllocationStrategy, Default). Empty:
	// the AWS default.
	TerminationPolicies []string
}

GroupArgs configures the Auto Scaling group.

type HookArgs

type HookArgs struct {
	Mode HookMode
	// HeartbeatTimeoutSeconds defaults to 900, bounded 30..7200.
	HeartbeatTimeoutSeconds int
	// DefaultResult is ABANDON (the default) or CONTINUE. CONTINUE needs
	// UnsafeDefaultContinue: an instance whose scripts never answered is
	// then put in service.
	DefaultResult         string
	UnsafeDefaultContinue bool
}

HookArgs is the EC2_INSTANCE_LAUNCHING hook.

type HookMode

type HookMode int

HookMode says where the lifecycle hook is declared.

const (
	// HookInline (the zero value) declares the hook on the group
	// (initial_lifecycle_hook), so it exists before the first instance
	// launches. A separate hook is created after the group and an instance
	// launched in between is not held by it.
	HookInline HookMode = iota
	// HookSeparate creates an aws.autoscaling.LifecycleHook resource.
	HookSeparate
)

type IAMArgs

type IAMArgs struct {
	// PermissionsBoundary is the full ARN of the boundary policy.
	PermissionsBoundary string
	// ManagedPolicyARNs are attached to the role. AmazonSSMManagedInstanceCore
	// lets the role read every parameter of the account; attach it only
	// for Session Manager.
	ManagedPolicyARNs []string
	// PolicyName is the inline policy's name. Default "appliance".
	PolicyName string
	// SSMParameters and ObjectKeys are granted in addition to the
	// user-data's.
	SSMParameters []string
	ObjectKeys    []string
	// Statements are added to the generated policy.
	Statements []Statement
	// StatementsFunc is like Statements for statements that need the
	// region, account or names.
	StatementsFunc func(PolicyContext) []Statement
	// Policy replaces the generated policy (the migration path of step
	// A). It excludes Statements, StatementsFunc, SSMParameters,
	// ObjectKeys, the user-data's grants and the modules'.
	Policy func(PolicyContext) (string, error)
	// ExtraInlinePolicies are further inline policies of the role.
	ExtraInlinePolicies []InlinePolicy
}

IAMArgs is the instance role.

type ImageArgs

type ImageArgs struct {
	// ID is a literal image id (or an output).
	ID pulumi.StringInput
	// NameFilter is an AMI name pattern, such as "al2023-ami-2023.*-kernel-6.1-arm64";
	// the newest available image wins.
	NameFilter string
	// Owners of the NameFilter lookup. Default "amazon".
	Owners []string
	// Architecture narrows the NameFilter lookup (x86_64, arm64).
	Architecture string
	// SSMParameter is a public or own parameter holding the image id.
	SSMParameter string
}

ImageArgs finds the AMI. Exactly one of ID, NameFilter and SSMParameter.

type InlinePolicy

type InlinePolicy struct {
	Name   string
	Policy func(PolicyContext) (string, error)
}

InlinePolicy is a named inline policy document.

type InstanceArgs

type InstanceArgs struct {
	// Type is the instance type. Exactly one of Type and Types.
	Type string
	// Types are several instance types, in priority order: the group
	// gets a mixed instances policy (on-demand, prioritized) whose
	// overrides are these types, and the launch template names none.
	// The types must share the image's architecture. A warm pool cannot
	// be combined with a mixed instances policy (an Auto Scaling
	// limit), so Types with WarmPool is refused.
	Types []string
	// HopLimit is the IMDS response hop limit, 1..64. Default 1. IMDSv2 is
	// always required.
	HopLimit int
	// RootVolume nil leaves the image's root volume alone.
	RootVolume *RootVolumeArgs
	// Volumes are extra EBS volumes in the launch template, encrypted
	// and deleted with the instance. A warm-pool stop and start keeps
	// them; a replacement starts with empty ones. The instance formats
	// and mounts them itself (a fragment of the consumer's).
	Volumes []VolumeArgs
	// PublicIP, when set, declares a network interface that associates
	// (true) or does not associate (false) a public address; nil
	// declares no interface and the group's subnets decide.
	PublicIP *bool
	// ExtraSecurityGroupIDs are attached next to the appliance's own
	// group.
	ExtraSecurityGroupIDs []pulumi.StringInput
}

InstanceArgs configures the launch template.

type Kind

type Kind string

Kind is a kind of child, for Compat.Aliases.

const (
	KindRole            Kind = "role"
	KindInstanceProfile Kind = "instance-profile"
	KindManagedPolicy   Kind = "managed-policy"
	KindSecurityGroup   Kind = "security-group"
	KindSecurityRule    Kind = "security-rule"
	KindLaunchTemplate  Kind = "launch-template"
	KindGroup           Kind = "group"
	KindInstance        Kind = "instance"
	KindDataVolume      Kind = "data-volume"
	KindDataAttachment  Kind = "data-attachment"
	KindTargetAttach    Kind = "target-attachment"
	KindHook            Kind = "hook"
	KindAlarm           Kind = "alarm"
	KindObject          Kind = "object"
)

Kinds.

type Logical

type Logical struct {
	// Role, InstanceProfile, SecurityGroup, LaunchTemplate and Group
	// default to the component's name.
	Role, InstanceProfile, SecurityGroup, LaunchTemplate, Group string
	// Hook defaults to "<name>-hook".
	Hook string
	// Instance (single-instance mode) defaults to the component's name.
	Instance string
	// DataVolume and DataAttachment default to "<name>-data" and
	// "<name>-data-attachment".
	DataVolume, DataAttachment string
	// TargetGroupAttachment defaults to "<name>-target-<index>".
	TargetGroupAttachment func(index int) string
	// ManagedPolicy defaults to "<name>-managed-<index>".
	ManagedPolicy func(index int, arn string) string
	// Ingress and Egress default to "<name>-ingress-<i>[-<j>]" and
	// "<name>-egress-<i>[-<j>]" for separate rules.
	Ingress, Egress func(index, address int) string
	// Alarm defaults to "<name>-alarm-<suffix>".
	Alarm func(suffix string) string
	// Object defaults to "<name>-object-<first 12 of the digest>".
	Object func(bootstrap.Object) string
}

Logical overrides logical names. An empty field or nil func keeps the default, which is documented on each field.

type Module

type Module = module.Module

Module is an optional piece of an appliance; see module.Module.

type Names

type Names struct {
	// Base defaults to the logical name.
	Base string
	// Group defaults to Base.
	Group string
	// LaunchTemplate defaults to Base.
	LaunchTemplate string
	// Role defaults to Base; the instance profile has the same name.
	Role string
	// InstanceProfile defaults to Role.
	InstanceProfile string
	// Hook defaults to Group + "-launch".
	Hook string
	// SecurityGroup, when set, is the group's fixed name. Empty: a
	// generated name with the prefix Group + "-", so a replacement is
	// created before the old group is deleted.
	SecurityGroup string
}

Names are the physical names. An empty field takes its default from Base.

func (Names) Resolve

func (n Names) Resolve(name string) Resolved

Resolve applies the defaults for the logical name. A caller that renders the plan before calling New needs the group and hook names for bootstrap.Options.Lifecycle: use Resolved.Lifecycle.

type ObjectsArgs

type ObjectsArgs struct {
	// Bucket is required when the user-data has objects or Extra is set.
	Bucket string
	// KMSKeyARN encrypts the objects with that key (aws:kms); empty:
	// AES256.
	KMSKeyARN string
	// ContentType defaults to "text/plain".
	ContentType string
	// Extra are objects uploaded in addition to UserData.Objects, and
	// readable by the role. A migration whose old user-data fetches
	// objects the program owns lists them here.
	Extra []bootstrap.Object
	// Tags, when set, replaces the object's tags (default: Name = the
	// resource name, ManagedBy = pulumi, Tags).
	Tags func(bootstrap.Object) map[string]string
}

ObjectsArgs says where the user-data's S3 objects go.

type PolicyContext

type PolicyContext struct {
	Partition string
	Region    string
	Account   string
	Names     Resolved
	// Bucket is Args.Objects.Bucket.
	Bucket string
	// SSMParameters and ObjectKeys are every parameter and object key the
	// appliance reads: the user-data's, Args.IAM's and the modules'.
	SSMParameters []string
	ObjectKeys    []string
}

PolicyContext is what a policy callback may use.

type PolicyInput

type PolicyInput struct {
	Partition string
	Region    string
	Account   string
	// Group is the Auto Scaling group name. Empty: no group statement.
	Group string
	// Bucket holds ObjectKeys.
	Bucket        string
	SSMParameters []string
	ObjectKeys    []string
}

PolicyInput is the input of BootstrapStatements.

type ReadyCheck

type ReadyCheck = module.ReadyCheck

ReadyCheck gates the launch hook; see module.ReadyCheck.

type RefreshArgs

type RefreshArgs struct {
	MinHealthyPercentage int
	// MaxHealthyPercentage lets a refresh launch before it terminates
	// (100 to 200; 0 leaves it unset).
	MaxHealthyPercentage int
	// WarmupSeconds defaults to 300.
	WarmupSeconds int
	// SkipMatching skips instances that already match the launch template.
	SkipMatching bool
	// AutoRollback rolls the refresh back when it fails.
	AutoRollback bool
	// Triggers are extra triggers beyond the launch template. Default
	// none. Naming launch_template is redundant and makes Pulumi warn.
	Triggers []string
}

RefreshArgs is the rolling instance refresh the launch template change starts. The Auto Scaling API starts a refresh on every launch template version change whenever the group has a refresh block, so Triggers stays empty unless the caller wants another trigger.

type Resolved

type Resolved struct {
	Base            string
	Group           string
	LaunchTemplate  string
	Role            string
	InstanceProfile string
	Hook            string
	// SecurityGroup is the fixed name, or empty.
	SecurityGroup string
	// SecurityGroupPrefix is the generated-name prefix when SecurityGroup is
	// empty.
	SecurityGroupPrefix string
}

Resolved are the physical names after defaults.

func (Resolved) Lifecycle

func (r Resolved) Lifecycle() *bootstrap.Lifecycle

Lifecycle is what bootstrap.Options.Lifecycle needs to abandon the right hook of the right group.

type RootVolumeArgs

type RootVolumeArgs struct {
	// DeviceName defaults to /dev/xvda.
	DeviceName string
	// SizeGiB defaults to 8.
	SizeGiB int
	// Type defaults to gp3.
	Type string
	// KMSKeyID, when set, encrypts with that key instead of the default.
	KMSKeyID string
}

RootVolumeArgs is the root EBS volume. It is encrypted.

type Rule

type Rule struct {
	Description string
	// Protocol is tcp (default), udp, icmp, icmpv6 or -1.
	Protocol string
	// FromPort and ToPort; both 0 with -1.
	FromPort, ToPort int
	CIDRs            []string
	IPv6CIDRs        []string
	SourceGroups     []pulumi.StringInput
	// World acknowledges that an ingress rule opens a port to 0.0.0.0/0
	// or ::/0. Without it such a rule is refused.
	World bool
}

Rule is one security group rule.

type RuleStyle

type RuleStyle int

RuleStyle says how security group rules are declared.

const (
	// RulesInline (the zero value) puts the rules in the group's ingress and
	// egress blocks.
	RulesInline RuleStyle = iota
	// RulesSeparate creates one aws.vpc.SecurityGroupIngressRule or
	// SecurityGroupEgressRule per rule and address.
	RulesSeparate
	// RulesLegacy creates one aws.ec2.SecurityGroupRule per rule, the resource
	// older programs use.
	RulesLegacy
)

type SecurityArgs

type SecurityArgs struct {
	// VPCID is required unless ExistingGroups is set.
	VPCID pulumi.StringInput
	// ExistingGroups use these groups instead of creating one; Ingress
	// and Egress are then refused.
	ExistingGroups []pulumi.StringInput
	// Description cannot change in place. Default "<Base> appliance".
	Description string
	Style       RuleStyle
	Ingress     []Rule
	// Egress nil allows all outbound traffic; an empty non-nil slice
	// allows none.
	Egress []Rule
	// DeleteTimeout bounds the provider's retry of DependencyViolation
	// when a replaced group is deleted, e.g. "30m".
	DeleteTimeout string
}

SecurityArgs is the security group.

type SingleArgs

type SingleArgs struct {
	// SubnetID is the subnet of the instance. Required. With Data, the
	// subnet must be in Data.AvailabilityZone; New checks that at deploy
	// time and fails the update if not.
	SubnetID pulumi.StringInput
	// RoleTagKey and RoleTagValue are a tag on the instance (and on the
	// Data volume) that names its role, for whatever finds it later.
	// Both required.
	RoleTagKey, RoleTagValue string
	// TargetGroups register the instance in existing target groups.
	// Default none (a proxy that dials the private address needs none).
	TargetGroups []TargetGroupAttachment
}

SingleArgs turns the appliance into one plain EC2 instance (aws.ec2.Instance) created from the launch template. The launch template, role, instance profile, security group, image lookup, S3 objects and user-data are the same as in group mode. There is no Auto Scaling group, so no launch hook, warm pool, instance refresh, health check or scaling; Hook, WarmPool, Refresh, Types, Alarms, the Group fields and module GroupActions are refused, and the user-data must be rendered without bootstrap.Options.Lifecycle (nothing would complete a hook, and the role gets no autoscaling permission).

A change to the launch template (a newer image, other user-data) is a new template version, and the instance is replaced, deleted before created, so a Data volume is free when the new instance attaches it. The replacement comes up running.

The run state is not managed: no instance state resource exists, so something else (a proxy) may stop and start the instance, and a stopped instance shows no diff. It finds the instance by the role tag, since the instance id changes on replacement; the private address survives a stop and start, not a replacement.

type Statement

type Statement = module.Statement

Statement is one IAM policy statement. The JSON field order is fixed, and Action and Resource are always arrays, so a document is byte-stable. It is defined in module, so a module can contribute statements without Pulumi.

func BootstrapStatements

func BootstrapStatements(in PolicyInput) []Statement

BootstrapStatements are the statements the bootstrap scripts need and no more: ssm:GetParameter on exactly the parameters, s3:GetObject on exactly the object keys and, when Group is set, the two Auto Scaling actions bootstrap-ready.service and the failure path call, on that group. A list that is empty yields no statement; the lists are sorted and de-duplicated.

type Step

type Step = module.Step

Step is an in-service step; see module.Step.

type TargetGroupAttachment

type TargetGroupAttachment struct {
	// ARN is the target group's ARN. Required.
	ARN pulumi.StringInput
	// Port overrides the target group's port; 0 keeps it.
	Port int
}

TargetGroupAttachment registers a single instance in a target group.

type VolumeArgs

type VolumeArgs struct {
	// DeviceName is /dev/sdf to /dev/sdp (on Nitro instances the volume
	// appears as an NVMe device; AL2023's udev rules link this name to
	// it). Required.
	DeviceName string
	// SizeGiB is required, 1..16384.
	SizeGiB int
	// Type defaults to gp3.
	Type string
	// IOPS and ThroughputMiBps, 0 keeps the type's baseline (gp3: 3000
	// IOPS and 125 MiB/s). Throughput is gp3 only.
	IOPS            int
	ThroughputMiBps int
	// KMSKeyID, when set, encrypts with that key instead of the default.
	KMSKeyID string
}

VolumeArgs is one extra EBS volume. It is encrypted and deleted with the instance.

type WarmPoolArgs

type WarmPoolArgs struct {
	// State is Stopped (default), Running or Hibernated.
	State string
	// MinSize defaults to 0.
	MinSize int
	// MaxGroupPreparedCapacity nil: no cap beyond the group's maximum.
	MaxGroupPreparedCapacity *int
	// ReuseOnScaleIn returns an instance that scales in to the pool
	// (stopped, its volumes kept) instead of terminating it, so a box
	// with a local cache keeps it.
	ReuseOnScaleIn bool
}

WarmPoolArgs is a pool of prepared instances.

type WatchCheck

type WatchCheck = module.WatchCheck

WatchCheck is a watchdog check; see module.WatchCheck.