{{toc}}

h1. Rundeck Integration

In case you want to know what Rundeck is: http://rundeck.org/docs/RunDeck-Guide.html#what-is-rundeck

Foreman supports Rundeck integration through the foreman_host_rundeck plugin - https://github.com/theforeman/foreman_host_rundeck. 

It allows you to export a list of nodes (resources) as yaml to populate your Rundeck project.

h2. Basic setup

On your Rundeck server you might want to change your default resources file from XML to YAML:

Edit _/etc/rundeck/project.properties_

<pre>

# The resources registration file

project.resources.file = /var/rundeck/projects/${project.name}/etc/resources.yaml

</pre>

Setup your project (here called _"examples"_) properties:

Edit _/var/rundeck/projects/examples/etc/project.properties_

<pre>

# The resources registration file

project.resources.file = /var/rundeck/projects/examples/etc/resources.yaml

http://<foremanuser>:<foremanpasswd>@foreman.mydomain.local/hosts?rundeck=true&format=yaml

</pre>

Now, in Rundeck, when you press _"Update Nodes for project examples"_ it should import the information of all Foreman registered hosts and classes as tags.

h2. Advanced setup

Foreman supports some customization of what is supposed to be exported.

h3. 1- Export a subset of hosts (*Default = All hosts*)

You might only want to export a subset of your hosts (leveraged by Foreman's search engine).

Example - Export only machines that belong to the production environment:

on your _/var/rundeck/projects/examples/etc/project.properties_ change the URL to:

<pre>

# The resources registration file

project.resources.file = /var/rundeck/projects/examples/etc/resources.yaml

http://<foremanuser>:<foremanpasswd>@foreman.mydomain.local/hosts?search=+environment+%3D++production&rundeck=true&format=yaml

</pre>

h3. 2- Export specific facts as tags (*Default = classes only*)

Next to the classes, you might want configure a parameter in Foreman to export specific facts as Rundeck tags. This can be done for a single or multiple hosts.

Example - Export: environment and domain information

In Foreman, add a parameter *"rundeckfacts = domain,environment"*

h3. 3- Customize Rundeck user (*Default = root*)

You can customize the user Rundeck should use for logging in. This can be done for a single or multiple hosts.

Example - On my host _"myserver1.mydomain.local"_ I want to use a _"mycustomuser"_ instead of root

In Foreman, add a parameter *"rundeckuser = mycustomuser"*

h2. Troubleshooting

Be querying the server with curl you should see something like:

<pre>

$ curl -k -u admin:changeme "https://foreman/hosts/myserver1.mydomain.local?rundeck=true&format=yaml"

</pre>

<pre>

--- 

  myserver1.mydomain.local: 

    osFamily: Redhat 

    osVersion: "5.6" 

    tags: 

      - domain=mydomain.local 

      - environment=production 

      - class=ntp::main 

      - class=puppet::client 

    username: mycustomuser 

    osName: CentOS 

    osArch: x86_64 

    nodename: myserver1.mydomain.local 

    description: My description specified in the HOST edit screen

    hostname: myserver1.mydomain.local

</pre>