Terraform is an open-source infrastructure as code software tool created by HashiCorp. Users define and provide data center infrastructure using a declarative configuration language known as HashiCorp Configuration Language, or optionally JSON. Terraform then takes this configuration and interacts with cloud providers or on-premises infrastructure to create, modify, or delete resources to match the defined configuration. This approach makes it easy to version and manage infrastructure, collaborate with team members, and ensure consistency across different environments.
The Rundeck Terraform Provider enables infrastructure automation teams to manage Rundeck resources using HashiCorp Terraform. The provider allows Terraform to create and configure Projects, Jobs and Keys in Rundeck. A provider is a plugin that serves as an interface between Terraform and a specific infrastructure or service provider. Providers are essential components in Terraform because they enable the tool to interact with various cloud, virtualization, and other infrastructure platforms. Each provider is responsible for translating the resource configurations defined in Terraform's HashiCorp Configuration Language into API calls and actions that are specific to a particular provider's platform.
This provider is community-supported. While Rundeck/PagerDuty staff review and approve pull requests, new feature development is driven by community contributions. We welcome and encourage community involvement at the open source repository.
Core Concepts
Rundeck Projects, Jobs, and Keys can be created and configured via Terraform using the Rundeck Terraform service. Terraform can handle Rundeck projects thanks to the project resource.
In Rundeck a project is the container object for a set of jobs and the configuration for which servers those jobs can be run on.
Terraform is an open-source Infrastructure as Code IaC tool used in IT and DevOps to automate and manage the provisioning and configuration of infrastructure resources. It allows users to define their infrastructure in a declarative manner, specifying the desired state of resources, such as virtual machines, networks, and databases, in a configuration file.
Though these instructions are written for the open source Rundeck application, they are also applicable for PagerDuty Runbook Automation.
Prerequisites and Environment Setup
The exercise is based on the Welcome Projects. Please ensure you have completed the tutorial and have that environment running.
Terraform 1.0 or later must be installed on your local machine. Confirm with
terraform -version
A local Rundeck instance version 5.0.0 or later is required. Basic knowledge about Linux terminal usage is assumed.
The Rundeck Instance must be configured for access. To accomplish this, the objective is to create an API access token. In this example, the Rundeck instance is a local war based installation that runs in the /opt/ directory.
Launch the Rundeck instance and login as admin user.
To confirm click the Rundeck logo in the upper left of the interface to load the project list.
Provider Configuration
The Rundeck provider configuration establishes connectivity between Terraform and the Rundeck API.
terraform {
required_providers {
rundeck = {
source = "rundeck/rundeck"
version = "~> 1.1"
}
}
}
provider "rundeck" {
url = "http://localhost:4440/"
auth_token = "your-auth-token"
}
The requiredproviders block pins the provider source to rundeck/rundeck with version ~> 1.1. The provider block requires a url and an authtoken for API authentication.
A table of the core provider settings is shown below.
| Setting | Example Value | Purpose |
|---|---|---|
| source | rundeck/rundeck | Provider namespace |
| version | ~> 1.1 | Version constraint |
| url | http://localhost:4440/ | Rundeck instance endpoint |
| auth_token | your-auth-token | API access token |
Resource Types Managed by Terraform
The Rundeck Terraform Provider supports creation and configuration of Rundeck Projects, Jobs, Keys, and ACL policies.
- rundeck_project
- rundeck_job
- rundeckpublickey
- rundeckprivatekey
- rundeckaclpolicy
Project Resource
The project resource allows Rundeck projects to be managed by Terraform.
Example project definition:
resource "rundeck_project" "terraform" {
name = "terraform"
description = "Sample Application Created by Terraform Plan"
ssh_key_storage_path = "${rundeck_private_key.terraform.path}"
resource_model_source {
type = "file"
config = {
format = "resourcexml"
file = "/home/rundeck/resources.xml"
writable = "true"
generateFileAutomatically = "true"
}
}
extra_config = {
"project.label" = "Terraform Example"
}
}
The resourcemodelsource block configures the resource model source type as file with format resourcexml. The file path is interpreted on the Rundeck server. Extra config allows arbitrary project properties such as project.label.
Job Resource
Rundeck Jobs can be created and configured via Terraform using the Terraform Rundeck Provider.
Example job definition:
resource "rundeck_job" "bounceweb" {
name = "Bounce All Web Servers"
project_name = "${rundeck_project.terraform.name}"
node_filter_query = "tags: web"
description = "Restart the service daemons on all the web servers"
command {
shell_command = "sudo service anvils restart"
}
}
The job is bound to the terraform project and filtered to nodes with tags: web. The command block defines the shell_command to execute.
Key Storage Resources
Keys can be managed in Rundeck Key Storage via Terraform.
resource "rundeck_public_key" "terraform" {
path = "terraform/id_rsa.pub"
key_material = "ssh-rsa yada-yada-yada"
}
resource "rundeck_private_key" "terraform" {
path = "terraform/id_rsa"
key_material = "$${file(\"id_rsa\")}"
}
The public key resource stores the public key material at the specified path. The private key resource references local file content via interpolation.
ACL Policy Resource
Access control can be defined declaratively.
data "local_file" "acl" {
filename = "${path.cwd}/acl.yaml"
}
resource "rundeck_acl_policy" "example" {
name = "ExampleAcl.aclpolicy"
policy = "${data.local_file.acl.content}"
}
by:
group: terraform
description: Allow terraform Key Storage
The ACL policy name is ExampleAcl.aclpolicy and the policy content is loaded from a local acl.yaml file.
Workflow Operations
Terraform apply creates the Rundeck resources.
Type yes and press the Enter key. The Rundeck project, including the sample task, has been built. You may use the terraform show command to check the current status of this implementation. In your web browser, navigate to the Rundeck instance. The project, job, key, and ACL are all present.
Destruction is handled with terraform destroy.
In the working directory created in the first section, type
terraform destroy
to undo all changes made to the Instance. Type yes and press the Enter key to confirm.
Sample destroy output includes:
rundeck_acl_policy.example: Destroying... [id=ExampleAcl.aclpolicy]
rundeck_password.terraform: Destroying... [id=keys/passwd]
rundeck_job.bounceweb: Destroying... [id=acb1685c-6940-4818-bf60-ec6c027552cd]
rundeck_password.terraform: Destruction complete after 0s
rundeck_acl_policy.example: Destruction complete after 0s
rundeck_job.bounceweb: Destruction complete after 0s
rundeck_project.terraform: Destroying...
[id=terraform]
rundeck_project.terraform: Destruction complete after 0s
Only 'yes' will be accepted to approve.
Extended Capabilities
Once you're comfortable with the basics, explore additional capabilities:
- Job Scheduling - Add cron schedules to your jobs for automated execution
- Notifications - Configure email, webhook, or plugin notifications for job events
- Job Options - Create parameterized jobs with dropdown choices and validation
- Webhooks - Configure external systems to trigger your Rundeck jobs
- Import Existing Resources - Bring existing Rundeck resources under Terraform management
These capabilities expand the provider from basic project and job creation to full lifecycle automation of Runbook workflows.
Comparison of Managed Resources
| Resource | Terraform Type | Managed Object | Key Attributes |
|---|---|---|---|
| Project | rundeck_project | Rundeck project container | name, description, sshkeystorage_path |
| Job | rundeck_job | Executable Runbook job | name, projectname, nodefilter_query |
| Public Key | rundeckpublickey | Key Storage public key | path, key_material |
| Private Key | rundeckprivatekey | Key Storage private key | path, key_material |
| ACL Policy | rundeckaclpolicy | Access control policy | name, policy |
Community and Maintenance Model
The Rundeck Terraform Provider is maintained by the community in the spirit of open source collaboration, with oversight from Rundeck/PagerDuty staff who review and approve contributions.
This provider is community-supported. While Rundeck/PagerDuty staff review and approve pull requests, new feature development is driven by community contributions.
The open source repository is the central location for issue tracking, feature requests, and contributions.
Conclusion
The Rundeck Terraform Provider bridges declarative infrastructure as code with Rundeck Runbook automation, allowing Projects, Jobs, Keys, and ACL policies to be versioned, peer reviewed, and reproduced across environments. By defining the desired state in HashiCorp Configuration Language, teams can apply consistent Rundeck configurations, destroy them predictably, and integrate Rundeck lifecycle management into existing Terraform pipelines. The community-supported nature of the provider means that feature evolution reflects real operational use, with Rundeck/PagerDuty staff providing oversight while community contributions drive capability growth. Effective use requires a properly authenticated Rundeck instance, Terraform 1.0 or later, and understanding of Rundeck project and job semantics. With those in place, Terraform becomes a control plane for Rundeck automation, reducing manual UI changes and enabling safe, repeatable changes to critical operational workflows.