Target

A target defines where resources live: the cloud account, region, or environment formae creates and manages them in, and where it discovers existing ones. Every forma needs at least one target.

One agent per target. A target should only ever be managed by a single formae agent. Running multiple agents against the same target produces conflicting state and unpredictable behaviour. See Architecture.

One target or many

If a forma defines exactly one target, every resource in it belongs to that target automatically. You don’t set a target on each resource:

forma {
  new formae.Target {
    label = "aws-uw2"
    config = new aws.Config { region = "us-west-2" }
  }

  // No target set: this bucket uses the only target in the forma.
  new bucket.Bucket {
    label = "assets"
    bucketName = "my-assets"
  }
}

If a forma defines more than one target, the assignment is no longer implied. Each resource must declare which target it belongs to:

forma {
  local uw2 = new formae.Target {
    label = "aws-uw2"
    config = new aws.Config { region = "us-west-2" }
  }
  uw2

  local ue1 = new formae.Target {
    label = "aws-ue1"
    config = new aws.Config { region = "us-east-1" }
  }
  ue1

  new bucket.Bucket {
    label = "assets"
    bucketName = "my-assets"
    target = uw2.res
  }

  new bucket.Bucket {
    label = "certs"
    bucketName = "my-certs"
    target = ue1.res
  }
}

Dynamic target config

Like a resource, a target’s config fields don’t have to be hardcoded. They can be driven by a property, for example a region you set on the command line:

new formae.Target {
  label = "aws"
  config = new aws.Config {
    region = properties.region   // set with --region on the CLI
  }
}

…or by a resolvable, which reads a value from another resource at apply time:

new formae.Target {
  label = "grafana"
  config = new grafana.Config {
    url = lgtmStack.res.endpoints.at("lgtm:3000")   // resolved from a Compose stack
  }
}

See Resolvables in targets for the full cross-plugin pattern.

Discovery

Discovery scans your targets for resources formae doesn’t manage yet. The discoverable field controls whether a target is scanned; targets are discoverable by default. Set discoverable = false on any target you want excluded:

new formae.Target {
  label = "staging-uw2"
  discoverable = false
  config = new aws.Config { region = "us-west-2" }
}

For the workflow of registering a target and pulling in what already runs on it, see Bring resources under management.

Applying a target-only forma (just targets, no resources) with --mode reconcile is safe. Reconcile only affects managed resources within a stack, and a target-only forma has no stack, so there is nothing to remove.

Unreachable targets

If the agent cannot reach a target for a sustained period, formae eventually cleans up that target’s discovered (unmanaged) resources from inventory so they don’t linger as stale entries. This is an inventory cleanup only: formae never deletes anything in the cloud, never touches resources under formae management, and never acts on a target with intermittent connectivity. Re-applying the target brings its inventory back. By default a target is cleaned up after it has been continuously unreachable for 24 hours. Set the reap field to change that window:

new formae.Target {
  label = "batch-eu"
  config = new aws.Config { region = "eu-west-1" }
  reap = new formae.ReapAfter { maxUnreachable = 72.h }
}

To keep a target no matter how long it stays unreachable, never cleaning it up:

  reap = new formae.NeverReap {}

Replacing a target

Most target config changes update the target in place. Some config is immutable, though: changing it (switching region, changing a connection endpoint) triggers a target replace. formae deletes the target and every managed resource on it, then recreates them against the new config. Whether a resource survives that automatically depends on the resource:

Portable resources can be recreated on the new target.
Non-portable resources cannot. An EC2 instance, for example, may use a region-bound AMI that doesn’t exist in the new region.

If a target replace would hit non-portable managed resources, formae rejects the operation rather than break them:

Cannot replace target 'aws-uw2'

The following resources are bound to the current target configuration and
cannot be automatically moved to the new target:

  - my-stack/AWS::EC2::Instance/web

To proceed, manually remove these resources first with 'formae destroy',
then reapply to recreate them with the new target configuration.

Run formae apply --simulate first: it shows which config fields changed and whether each change updates in place or forces a replace.

Which config fields update in place versus force a replace is decided by the plugin, not by you. As a user, it’s enough to know that some target config updates in place and some forces a replace, and that --simulate tells you which. Plugin authors: see Plugin development.

Deleting a target

Destroy a target-only forma (just targets, no resources) to remove the declared targets:

formae destroy target.pkl

Deleting a target also cascade-deletes every managed resource on it from the cloud. Because that blast radius can be large, the CLI guards it: with --yes, a destroy that would cascade is aborted unless you also pass --on-dependents=cascade. Run interactively (without --yes) and formae shows what will be cascaded and asks you to confirm.

Deleting a target removes its unmanaged resources from formae’s inventory, but never from your cloud. formae only destroys resources it manages, so discovered resources you never brought under management stay exactly where they are; formae simply stops tracking them once their target is gone.

Targets during a full destroy

When you destroy a forma that has both targets and resources, formae keeps plain targets (a cloud region target, say), because they exist independently of the resources. Only a target whose config depends on a resource being destroyed, through a resolvable reference, is deleted automatically. To remove a plain target, destroy it separately with its own target-only forma. Keep shared targets in one file and import them wherever you need them, so target config stays consistent across your formae. This is how our own infrastructure is organised:

// vars.pkl
awsProd: formae.Target = new formae.Target {
  label = "aws-prod-uw2"
  config = new aws.Config { region = "us-west-2" }
}

import "./vars.pkl"

forma {
  vars.awsProd
  // resources on the shared target
}

Get started

Guides

Concepts

Reference

One target or many

Dynamic target config

Discovery

Unreachable targets

Replacing a target

Deleting a target

Targets during a full destroy

See also

​One target or many

​Dynamic target config

​Discovery

​Unreachable targets

​Replacing a target

​Deleting a target

​Targets during a full destroy

​Sharing targets

​See also

One target or many

Dynamic target config

Discovery

Unreachable targets

Replacing a target

Deleting a target

Targets during a full destroy

Sharing targets

See also