This document describes the YAML format for ACL Policy definition files.
Multiple aclpolicy files can be stored in the same directory, helping the management of each set of rules. This reduces the complexity of each file. The default path is
Policy files are parsed using YAML and while the structure is rigid, additional information can be added and safely ignored. So creating arbitrary elements for documentation or organizational purposes is gracefully parsed.
The resulting file must be a valid yaml file.
For more information about the exact resources and actions you need to authorize for the Rundeck application, see the Administration Guide - Authorization.
The YAML format has changed since version 1.2 to address several issues:
The Rundeck server no longer uses role-mapping and instead defers to the aclpolicy for all authorizations.
Note: The XML format from Rundeck 1.3 and earlier is no longer supported. As well, the YAML format from 1.2 is now only partially supported.
If you are upgrading from Rundeck 1.3 or earlier, you will have to modify your *.aclpolicy files.
If you have XML formatted files, you will need to remove and replace them with a YAML document in the format described below. A full, admin-level ACL is described at the end of this document.
If you have YAML formatted files, you will also need to upgrade them slightly.
An example policy document.
description: Yaml Policy 1 context: # declares the context of the ACL project: '.*' # applies to projects matching a regex. for: resource: - equals: kind: job allow: '*' job: - allow: '*' - match: group: 'group1/.*' deny: '*' # note, the 1.2 format "rules" section can still be used if no # "for: job: " section is used rules: ^$: actions: 'foobar' /listAction/.*: actions: [action_list_1,action_list_2] by: username: 'yml_usr_1' group: ['yml_group_1','group2']
An .aclpolicy supports multiple policy definitions in the form of YAML documents usign the
--- separator. There are four elements that make a policy definition:
It's recommended that this description be short and descriptive as it appears in the log output.
context section declares the scope of the ensuing policy description.
context can contain one of two things:
project: declares the name of the project(s) for which the policy applies. Its value is a String, and can be a regular expression, for which the project name must match to apply.
If you declare an
application section, its only supported value is
rundeck, as: context: application: 'rundeck'
This declares that the policy document describes access control at the application level, rather than for at a project level. You can then declare access control on actions such as creating Projects.
Note that to provide a full "admin" level access control for a user or group, then two policies must be defined, for application level as well as for project level.
NOTE if you are upgrading a yaml 1.2 format document, you will need to add a
for section declares a set of resource types, each containing a sequence of matching rules which allow or deny certain actions.
Resource types declare the type of a specific resource for the match, and the generic "resource" is used to declare rules for all resources of a certain type.
for is an entry for any of these resource types:
job- a Rundeck Job
node- a Node resource
adhoc- an Ad-hoc execution
project- a Project
resource- indicates rules for all resources of a certain kind
Within each type section is a sequence of rules. Recall that in YAML, a sequence is defined using multiple
- indicators, or within
] and separated by commas.
- a - b
[ a, b ]
Type rules are in the form:
matching*: property: value allow: actions deny: actions
Each rule has one or more of these Action entries:
allow- (List or String) - the actions allowed
deny- (List or String) - the actions denied
It also has one or more of these "Matching" entries:
match- (List or String) - regular expression matches
equals- (String) - equality matches
contains- (List or String) - set membership matches
Each Matching entry is composed of
property: value, which declare what property of the resource to test, and what value or values to apply the matching rule to.
For example, to declare a rule for a resource with a "name" property of "bob" exactly, use
equals: name: bob allow: [action1, action2] deny: action3
For regular expression matching, use
match: name: 'bob|sam'
For set membership matches, such as matching a Node that must have three different tags, you can use
contains: tags: [a,b,c]
contains allow a list of property values, and all of them must match the resource's property for the rule to match. This allows the basic boolean AND logic. For OR logic, you can simply declare another rule in the sequence since all rules are checked (except in the case of an explicit deny).
group entries that declare who the policy applies to.
Each entry can contain a single string, or a sequence of strings to define multiple entries.
A single match will result in further evaluation of the policy.
username elements are evaluated first as they are typically more restrictive.
group elements are evaluated second. Ordering is not important within this element.
by: username: 'bob' by: group: [test,qa,prod] by: username: - simon - frank
YAML aclpolicy files created before 1.4 would have the
rules sections. These were only designed to match Jobs, and so for backwards compatibilty these rules sections can still be used for matching only jobs.
The changes for the newer version affect the old
rules section in these ways:
See Administration Guide - Authorization for more information.
rules element contains a map of resource paths to
actions. The key in each rule, for example:
/path: actions: 'an_action'
/path is evaluated against the resource being evaluated. See below for a complete list of paths that can have ACLs applied. The path is evaluated as a java regex expression. If a match is successful, then a final check against
actions element is performed.
The actions element can be either a single value, or a list of values. A single value takes the form:
And a list takes the form:
Note that the single tick marks are optional according to the yaml specification.
Possible values are limitless so it requires an understanding of the job definition you're trying to run. The best way to understand what the actions are is to look at the rundeck-audit.log. This will show all the options as they're being evaluated.
This document grants full permissions to an 'admin' role:
description: Admin project level access control. Applies to resources within a specific project. context: project: '.*' # all projects for: resource: - equals: kind: job allow: [create] # allow create jobs - equals: kind: node allow: [read,create,update,refresh] # allow refresh node sources - equals: kind: event allow: [read,create] # allow read/create events adhoc: - allow: [read,run,runAs,kill,killAs] # allow running/killing adhoc jobs job: - allow: [create,read,update,delete,run,runAs,kill,killAs] # allow create/read/write/delete/run/kill of all jobs node: - allow: [read,run] # allow read/run for nodes by: group: admin --- description: Admin Application level access control, applies to creating/deleting projects, admin of user profiles, viewing projects and reading system information. context: application: 'rundeck' for: resource: - equals: kind: project allow: [create] # allow create of projects - equals: kind: system allow: [read] # allow read of system info - equals: kind: user allow: [admin] # allow modify user profiles project: - match: name: '.*' allow: [read,admin] # allow view/admin of all projects by: group: admin
The Rundeck source code and all documentation may be downloaded from