Module Actions

What It Does

Module actions operate on infrastructure that already exists rather than provisioning it: scale a deployment, restart pods, snapshot a database, pull a kubeconfig. They ship with the module and run from the resource's Actions tab or the raptor CLI.

Praxis writes them into the module as Terraform. They deploy with the module during a release, then appear on every instance of that resource in every environment where it is deployed, with no per-environment setup. A module author gets them offered automatically at the end of every build. An operator gets a button instead of a kubectl incantation.

What Praxis Suggests

Praxis proposes actions tailored to the module type it just built, not a generic list. The rule it follows is explicit: no filler. Every proposed action has to be a workflow you will actually run repeatedly.

For developers, that typically means restarting a service after a config change, checking pod status and recent logs, testing connectivity to a database or an API, downloading a kubeconfig for local debugging, or scaling a service up for testing and back down after. For platform and DevOps teams it leans toward scaling a database up for peak and down on weekends, taking a backup before a major change, rotating credentials or certificates, running health checks, flushing a cache after a deployment, and downloading artifacts or configuration.

Reference patterns

Praxis draws on eight complete patterns, each written out as full Terraform in the module-actions skill.

These names are the skill's own. name is free text and is what renders on the action's card, so teams pick their own convention; hyphenated lowercase such as rollout-restart-deployment is common in practice.

How Praxis Offers Them

Offering actions is a mandatory gate, not an optional extra. It fires on every module build, even when you never say the word "action". The trigger is reaching the publish step, not a keyword in the conversation.

1. Praxis designs and implements the module as usual.
2. The gate fires. Before uploading or publishing, Praxis proposes a table of candidate actions for this module type, with a column each for Action, Description, Type, and Rationale.
3. You pick the ones you want, ask for others, or decline entirely. Declining is supported and the module publishes without actions. Praxis never writes actions silently.
4. Praxis writes the approved actions into a dedicated actions.tf, kept separate from main.tf. One file makes them easy to find, review, and disable by commenting out.
5. Praxis re-runs raptor module validate, so a malformed action fails here rather than at deploy time.
6. Only then does the module upload or publish.

Praxis does not generate actions for modules that target only Azure or GCP, because the provider has no cloud action type for them. Such a module can still carry a hand-written Kubernetes action if it manages Kubernetes resources.

Two timing notes. Actions ride along with whichever module version is deployed, so a PREVIEW module's actions are available only in test projects until you publish it. And when your organization has a modules repo linked, actions.tf is committed on a feature branch and goes live through a PR rather than through raptor publish iac-module.

Running an Action

From the Resource Center

Open the resource, go to its Actions tab, and select Run on the action you want. If it declares parameters you supply those values first, then the run's logs and status stream back into the UI. History on the same card shows past runs.

Actions are deployed by a release, so an action becomes runnable only once that resource exists in that environment, and a newly added action appears after the next release rather than immediately.

A deployment resource, for example, commonly carries scale-up-deployment, scale-down-deployment, and rollout-restart-deployment.

From the raptor CLI

The same operations are scriptable. List the actions available on a resource:

raptor get actions service/agent -p PROJECT -e ENV

Trigger one, optionally passing parameters and blocking until it reaches a terminal status:

raptor trigger action service/agent -p PROJECT -e ENV -a rollout-restart-deployment [--param KEY=VALUE] [-w]

List run history for the resource, or filter it to a single action:

raptor get action-runs service/agent -p PROJECT -e ENV [-a ACTION]

Fetch the logs of a specific run, adding -f to follow them live:

raptor get action-run-logs service/agent RUN_NAME -p PROJECT -e ENV -a ACTION [-f]

And download whatever artifact the run uploaded during execution:

raptor get action-run-download service/api RUN_NAME -p PROJECT -e ENV -a ACTION [--save-to ./out/]

An action can be referenced either by its generated hash name or by its display name, for example rollout-restart-deployment. Run raptor get actions --help for exact syntax.

Anatomy of an Action

Two action types exist, and only two: facets_tekton_action_kubernetes and facets_tekton_action_aws, both from the facets Terraform provider. There is no Azure or GCP equivalent.

Required. name (the display name on the card), facets_resource_name, facets_environment, facets_resource, and steps. Each step needs a name, a container image, and a script, and optionally takes environment variables plus CPU and memory requests and limits.

Optional. description (also shown on the card, and what makes an action understandable to whoever runs it), namespace (defaults to the Tekton pipelines namespace), labels (Kubernetes actions only), and params (name and type pairs that become inputs at trigger time). Terraform computes id, a hash-based task_name capped at 63 characters, and step_action_name.

Always use module variables, never hardcoded values

This rule decides whether an action works in more than the one environment it was written against.

• var.instance_name for facets_resource_name
• var.environment for facets_environment and for script references. It carries unique_name, name, namespace, and cloud_tags.
• var.instance for facets_resource. It carries kind, flavor, version, spec, and metadata.

Getting output back

Tekton steps run in ephemeral pods, so output has to go somewhere durable. For text output such as a kubeconfig or a status report, print to stdout between explicit BEGIN and END markers so it can be copied out of the run log. For binary or large output such as a database dump, upload it to S3 from an AWS action and emit a time-limited pre-signed download URL into the log.

A run can also carry an artifact the step uploaded during execution, which you retrieve afterwards with the CLI:

raptor get action-run-download service/api RUN_NAME -p PROJECT -e ENV -a ACTION [--save-to ./out/]

How It Works

An action is one Tekton Task with one or more sequential steps, scoped to one specific resource in one specific environment.

actions.tf deploys via a release, which creates the Tekton Task in the cluster. Selecting Run creates a TaskRun carrying auto-injected credentials, your supplied parameters, and your identity as FACETS_USER_EMAIL. The provider prepends a credential setup step, your steps then execute sequentially in isolated pods, and logs and status return to the UI. The labels linking an action to its resource are auto-generated.

Credentials and permissions

Action execution inherits the triggering user's permissions rather than running with elevated platform rights.

Kubernetes. The UI populates FACETS_USER_KUBECONFIG with your base64-encoded, RBAC-scoped kubeconfig, and a setup-credentials step decodes it and sets KUBECONFIG. Every step runs with kubectl access scoped to your own permissions, so an action cannot do anything in the cluster you could not do yourself.

AWS. The TaskRun runs under a workflows ServiceAccount using IRSA, and a setup-aws-credentials step assumes the target IAM role from the provider config, so the action's reach is bounded by that role's policy. Four things must be configured in advance, and each is a real failure mode: the provider block declares an assume-role configuration, the ServiceAccount carries an IRSA annotation, the IRSA role holds sts:AssumeRole on the target role, and the target role trusts the IRSA role.

Because FACETS_USER_EMAIL is injected into every run, runs are attributable. On the authoring side, the raptor CLI requires you to be authenticated to a control plane (raptor login, confirmed with raptor whoami), and module operations respect your Facets RBAC.

Rules and Limits

• Actions must not modify infrastructure state. Creating resources or changing configuration is what Terraform and releases are for. Actions operate on infrastructure that already exists, and an action duplicating what a release already does is redundant.
• Never embed secrets in action scripts. Credentials come from environment variables, parameters, or the auto-injected credential setup step. Secrets are never typed into chat either: module building uses the vault-backed encrypted-credential flow, where the value goes into a secure modal the model never sees, or a silent shell prompt on the CLI.
• Pin container image tags. An unpinned latest makes runs non-reproducible.
• Use set -e and print informative output. The run log is the only thing the operator sees, so a failing command must abort the step rather than continue silently.
• Validate parameters before anything destructive. The scaling reference pattern rejects an empty replica count before it touches the deployment.
• Declare resource requests and limits on heavy steps, so a long-running action cannot starve the cluster.
• Give every action a description, and keep it single-purpose. A "do everything" action and a filler action nobody runs twice are both wasted.

Troubleshooting

For failures in the broader module flow, such as validation errors, a missing output type, or a deployment failing after upload, see the Troubleshooting section on Module Builder.

Related

• Module Builder - Builds the module your actions ship with; the actions offer is the last step of that flow before publish.
• K8s Inspector - Conversational Kubernetes troubleshooting; where an action gives you a fixed button for a known operation, K8s Inspector answers open-ended questions about cluster state.
• Release Debugger - Diagnoses the release that deploys your actions, when that release fails.