Defining Module Resource Actions

Overview

Platform or DevOps engineers can define custom Actions for any module in Facets.cloud. Actions ride along with the module version they are defined in, so they appear on a resource once a release carrying that version has landed in the environment.

Custom Actions are implemented using containerised workflows managed by Facets. You define the logic, environment, and parameters, Facets handles authentication, execution, and UI integration.

Defining an Action (Terraform Resource)

Actions are defined using one of two Terraform resources: facets_tekton_action_kubernetes for kubectl and Helm operations, and facets_tekton_action_aws for AWS API calls. These are the only two action types that exist. There is no equivalent resource for Azure or GCP, so a module targeting those clouds can only ship Kubernetes actions.

Kubernetes Example

resource "facets_tekton_action_kubernetes" "restart_app" {
  name                  = "Restart Application"
  description           = "Performs a rollout restart of the app deployment"
  facets_resource_name  = var.instance_name
  facets_environment    = var.environment
  facets_resource       = var.instance

  steps = [
    {
      name   = "rollout-restart"
      image  = "bitnami/kubectl:latest"
      script = <<-EOT
        kubectl rollout restart deployment/${var.instance.metadata.name} -n ${var.environment.namespace}
      EOT
    }
  ]
}

AWS Example

An AWS action takes broadly the same arguments, but runs its steps with an assumed IAM role instead of a kubeconfig:

resource "facets_tekton_action_aws" "create_snapshot" {
  name                  = "Create DB Snapshot"
  description           = "Creates a manual snapshot of the RDS instance"
  facets_resource_name  = var.instance_name
  facets_environment    = var.environment
  facets_resource       = var.instance

  steps = [
    {
      name   = "create-snapshot"
      image  = "amazon/aws-cli:2.15"
      script = <<-EOT
        aws rds create-db-snapshot \
          --db-instance-identifier "${var.instance.metadata.name}" \
          --db-snapshot-identifier "${var.instance.metadata.name}-$(date +%Y%m%d-%H%M)"
      EOT
    }
  ]
}

AWS actions have one prerequisite. The facets provider must carry an aws block naming the region and the role to assume, because Facets prepends a credential step that assumes that role before your steps run:

provider "facets" {
  aws = {
    region = "us-east-1"
    assume_role = {
      role_arn     = "arn:aws:iam::123456789012:role/TargetRole"
      session_name = "my-workflow"        # Optional
      external_id  = "unique-external-id" # Optional
    }
  }
}

Key Arguments

Runtime Environment

Each Action runs in an isolated Pod with:

• Auto-injected credentials for scoped Kubernetes access (FACETS_USER_KUBECONFIG)
• Injected environment variables:
  • FACETS_USER_EMAIL: email of the user who triggered the action
  • KUBECONFIG: preconfigured path (/workspace/.kube/config)

This ensures all steps execute with proper RBAC-based permissions of the triggering user.

Labeling and Discovery

Facets automatically tags all Action resources with standardized labels for tracking and discovery:

These labels allow the Facets backend to dynamically surface the right Actions for each resource type in the UI.

Tips and Best Practices

• Keep scripts lightweight: each step runs inside a short-lived container.
• Use official container images whenever possible (e.g., bitnami/kubectl, alpine, python).
• Validate parameters before executing destructive operations.
• Name actions clearly for better discoverability in the UI.