---
title: Executor
---

**Executors** are specialized components designed to run infrastructure modules that perform specific, non-reusable tasks. Unlike Resources which are instances of reusable Templates, Executors are purpose-built for one-time operations, utility tasks, and custom workflows that don't fit the template model.

Executors are the utility tools in your infrastructure kitchen - they handle specialized tasks like database migrations, data imports, cleanup operations, and custom scripts that you need to run but don't want to turn into reusable templates.

An executor combines:

- **Code Repository** (what to run)
- **Runtime** (how to execute it - OpenTofu/Terraform)
- **Command Arguments** (specific instructions for execution)
- **Integrations** (credentials for cloud access)
- **Secrets** (sensitive data needed for execution)
- **Storage** (for state management)

Once executed, executors perform their designated task and maintain their state for tracking and audit purposes.

## Executor Lifecycle

Executors move through these stages: **Create → Provision → Destroy → Delete**.

**States:** `provision` → `provisioned` → `destroy` → `destroyed`

**Statuses:** `ready`, `queued`, `in_progress`, `done`, `error`, `pending`, `unknown`

Unlike resources, executors are typically task-oriented and may be destroyed after completing their purpose.

## Executor Properties

Each executor in InfraKitchen contains the following core properties:

| Property                 | Description                                    | Notes                                    |
| :----------------------- | :--------------------------------------------- | :--------------------------------------- |
| **Name**                 | Unique identifier for the executor             | Must be unique                           |
| **Description**          | Detailed information about the executor's task | Markdown supported                       |
| **Runtime**              | Execution environment                          | Currently supports `opentofu`            |
| **Command Arguments**              | Arguments to main script                           | E.g., `-var-file=environments/dev/eu-west-1.tfvars` |
| **Code Repository**      | Git repository containing the module           | Required                                 |
| **Template Version**     | Specific tag/release to use                    | Either version or branch required        |
| **Branch**               | Specific branch to use                         | Either version or branch required        |
| **Folder**               | Path to module within repository               | Defaults to root                         |
| **State**                | Lifecycle state                                | `provision`, `provisioned`, `destroy`    |
| **Status**               | Current operation status                       | `queued`, `in_progress`, `done`, `error` |
| **Cloud Integrations**   | Cloud provider credentials                     | Optional, as needed for task             |
| **Secrets**              | Sensitive data for execution                   | Database passwords, API keys, etc.       |
| **Storage**              | Backend for Terraform/OpenTofu state           | S3, Azure Blob, GCS, etc.                |
| **Storage Path**         | Path to state file in storage                  | Auto-generated or custom                 |
| **Labels**               | Tags for organizing and filtering              | E.g., `migration`, `cleanup`, `one-time` |
| **Revision Number**      | Version tracking for executor changes          | Auto-incremented on updates              |
| **Creator**              | User who created the executor                  | Used for permissions and audit           |

## Creating Executors

Executors are created to perform specific infrastructure tasks that don't require the reusability of templates.

### Creation Steps

1. **Navigate to Executors**

    Go to **Executors** in the sidebar and click <kbd>Create</kbd>.

2. **Configure basic properties**

    - Enter unique name
    - Add description explaining the task
    - Select runtime (`opentofu`)
    - Specify command arguments

3. **Configure code**

    - Select code repository
    - Choose version (tag) or branch
    - Specify folder path within repository

4. **Configure execution context**

    - Select cloud integration(s) if needed
    - Select secrets if needed for sensitive data
    - Select storage backend for state management
    - Specify storage path
    - Add labels for organization

5. **Save**

    Click <kbd>Save</kbd>.

:::tip[When to Use Executors]
Use executors for:

- **Database migrations** - One-time schema updates
- **Data imports/exports** - Bulk data operations
- **Cleanup tasks** - Resource decommissioning
- **Custom scripts** - Specialized automation
- **Utility operations** - Tasks that don't fit templates

Use Resources/Templates for:

- Reusable infrastructure patterns
- Long-lived infrastructure
- Hierarchical resource management
:::

## Managing Executors

Executors support various lifecycle actions based on their current state.

| Action        | When Available             | Description                                 |
| :------------ | :------------------------- | :------------------------------------------ |
| **Provision** | State: `provision`         | Execute the infrastructure task             |
| **Dry Run**   | Before provisioning        | Preview changes without applying            |
| **Update**    | State: `provisioned`       | Modify executor configuration               |
| **Destroy**   | State: `provisioned`       | Clean up infrastructure created by executor |
| **Delete**    | State: `destroyed`         | Permanently remove executor                 |

:::warning[State Management]
Even for one-time tasks, executors maintain Terraform/OpenTofu state. This ensures proper cleanup and tracking of any infrastructure modifications made during execution.
:::

## Executor Integrations

Executors can be associated with multiple integrations to access various cloud providers and services.

### Integration Types

- **Cloud Providers**: AWS, Azure, GCP, MongoDB Atlas, Datadog
- **Required for**: Accessing cloud resources during execution
- **Multiple integrations**: Can use several at once if task spans multiple clouds

**Example:**

```yaml
Executor: database-migration-prod
Integrations:
  - AWS Production Account (for RDS access)
  - MongoDB Atlas Production (for data migration)
```

Learn more about [Cloud Providers](../integrations/cloud).

## Executor Secrets

Secrets provide secure access to sensitive data needed during execution.

### Secret Usage

- **Database credentials** - Connection strings, passwords
- **API keys** - Third-party service authentication
- **Certificates** - SSL/TLS certificates
- **Tokens** - Access tokens, refresh tokens

**Example:**

```yaml
Executor: data-export-task
Secrets:
  - database-master-password
  - api-service-key
  - s3-upload-credentials
```

Secrets are securely injected into the execution environment as environment variables.

Learn more about [Secrets Management](../../secrets/overview).

## Executor Storage

Executors require storage backends to persist Terraform/OpenTofu state.

### Supported Storage Backends

- **AWS S3** - With DynamoDB for state locking
- **Azure Blob Storage** - With blob leases for locking
- **Google Cloud Storage** - With native locking

### Storage Path

Each executor uses a unique storage path to isolate its state from other executors and resources:

```
<storage-bucket>/executors/<executor-name>/terraform.tfstate
```

This ensures executors can be safely executed in parallel without state conflicts.

## Executors vs Resources

Executors run specific modules for one-time tasks; Resources are instances of reusable templates:

- ✅ Use an **Executor**: "I need to run a database migration once in production"
- ✅ Use a **Resource**: "I need to provision a VPC that follows our standard template"

For the full comparison of Executors, Templates, and Blueprints, see the [comparison table](./blueprint#blueprints-vs-templates-vs-executors) on the Blueprint page.

## Executor Outputs

After successful execution, executors may produce outputs that can be:

- Viewed in the UI in logs tab
- Used for verification and audit

## Executor Permissions

Executor actions are controlled by role-based access control:

| Action               | Permission Required          |
| :------------------- | :--------------------------- |
| **View**             | Read access                  |
| **Create**           | Write access                 |
| **Edit**             | Admin access                 |
| **Execute**          | Write access                 |
| **Destroy**          | Admin access                 |
| **Delete**           | Admin access                 |

## Integration with Other Features

### Executors and Code Repositories

Executors reference Git repositories containing infrastructure code:

- Must specify either a version (tag) or branch
- Can use any folder within the repository
- Support mono-repos with multiple modules
- Track code changes via revision numbers

### Executors and Storage

State management is critical for executors:

- Enables proper cleanup even for one-time tasks
- Tracks what infrastructure was modified
- Prevents conflicts with parallel executions
- Supports state rollback if needed

### Executors and Workspaces

Unlike resources, executors typically don't use workspace Git sync:

- Executor code comes directly from the registered code repository
- No automatic Git commits of generated Terraform
- State is stored in configured backend only

## Best Practices

### Naming Conventions

Use descriptive names that indicate purpose and context (e.g. `prod-db-migration-v2-0-0`, `staging-cleanup-unused-volumes` — avoid generic names like `executor-1` or `test-task`).

### Version Management

- Use **tags** for stable, tested code; use **branches** only for development/testing
- Tag executor code releases just like application releases
- Document what each version does in Git commit messages

### Security

- Use secrets for all sensitive data — never hardcode credentials in executor source code
- Limit integrations to the minimum required
- Audit executor executions regularly

### Lifecycle Management

- Destroy executors after task completion (if one-time); keep them for recurring tasks
- Use labels to track executor status
- Document executor purpose in the description