Merge pull request #72 from rundeck/docs-updates

Example Updates / Project Extra Config Clarification

website/docs/index.html.markdown

@@ -3,16 +3,15 @@ layout: "rundeck"
 page_title: "Provider: Rundeck"
 sidebar_current: "docs-rundeck-index"
 description: |-
-  The Rundeck provider configures projects, jobs and keys in Rundeck.
+  The Rundeck provider configures projects, jobs, ACLs and keys in Rundeck.
 ---
 
 # Rundeck Provider
 
 The Rundeck provider allows Terraform to create and configure Projects,
-Jobs and Keys in [Rundeck](http://rundeck.org/). Rundeck is a tool
-for runbook automation and execution of arbitrary management tasks,
-allowing operators to avoid logging in to individual machines directly
-via SSH.
+Jobs, ACLs and Keys in [Rundeck](http://www.rundeck.com/). Rundeck is a tool
+for Runbook Automation and execution of arbitrary management tasks,
+allowing operators to avoid logging in to individual machines directly.
 
 The provider configuration block accepts the following arguments:
 
@@ -21,7 +20,7 @@ The provider configuration block accepts the following arguments:
 
 * ``api_version`` - (Optional) The API version of the server. Defaults to `14`, the
   minium supported version. May alternatively be set via the ``RUNDECK_API_VERSION``
-  environment variable. 
+  environment variable.
 
 * ``auth_token`` - (Required) The API auth token to use when making requests. May alternatively
   be set via the ``RUNDECK_AUTH_TOKEN`` environment variable.
@@ -30,34 +29,48 @@ Use the navigation to the left to read about the available resources.
 
 ## Example Usage
 
+A full Example Exercise is included on the [Rundeck Learning site](https://docs.rundeck.com/docs/learning/howto/use-terraform-provider.html).
+
+For those familiar with Terraform and Rundeck use the contents below.
+
 ```hcl
+terraform {
+  required_providers {
+    rundeck = {
+      source  = "rundeck/rundeck"
+      version = "0.4.2"
+    }
+  }
+}
+
 provider "rundeck" {
-  url         = "http://rundeck.example.com/"
-  api_version = "26"
+  url         = "http://rundeck.example.com:4440/"
+  api_version = "38"
   auth_token  = "abcd1234"
 }
 
-resource "rundeck_project" "anvils" {
-  name        = "anvils"
-  description = "Application for managing Anvils"
-
-  ssh_key_storage_path = "${rundeck_private_key.anvils.path}"
-
+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"
-
       # This path is interpreted on the Rundeck server.
-      file = "/var/rundeck/projects/anvils/resources.xml"
+      file = "/home/rundeck/resources.xml"
+      writable = "true"
+      generateFileAutomatically = "true"
     }
   }
+  extra_config = {
+    "project.label" = "Terraform Example"
+  }
 }
 
 resource "rundeck_job" "bounceweb" {
-  name              = "Bounce Web Servers"
-  project_name      = "${rundeck_project.anvils.name}"
+  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"
 
@@ -66,18 +79,18 @@ resource "rundeck_job" "bounceweb" {
   }
 }
 
-resource "rundeck_public_key" "anvils" {
-  path         = "anvils/id_rsa.pub"
+resource "rundeck_public_key" "terraform" {
+  path         = "terraform/id_rsa.pub"
   key_material = "ssh-rsa yada-yada-yada"
 }
 
-resource "rundeck_private_key" "anvils" {
-  path         = "anvils/id_rsa"
-  key_material = "${file(\"id_rsa.pub\")}"
+resource "rundeck_private_key" "terraform" {
+  path         = "terraform/id_rsa"
+  key_material = "$${file(\"id_rsa.pub\")}"
 }
 
 data "local_file" "acl" {
-  filename = "${path.module}/acl.yaml"
+  filename = "${path.cwd}/acl.yaml"
 }
 
 resource "rundeck_acl_policy" "example" {
@@ -86,3 +99,39 @@ resource "rundeck_acl_policy" "example" {
   policy = "${data.local_file.acl.content}"
 }
 ```
+
+> Note: This example uses an ACL Policy file stored at the current working directory named `acl.yaml`.  Valid contents for that file are shown below.
+
+```
+by:
+  group: terraform
+description: Allow terraform Key Storage Access
+for:
+  storage:
+  - allow:
+    - read
+context:
+  application: rundeck
+---
+by:
+  group: terraform
+description: Allow Terraform Group [read] for all projects
+for:
+  project:
+  - allow:
+    - read
+context:
+  application: rundeck
+---
+by:
+  group: terraform
+description: Terraform Project Full Admin
+for:
+  project:
+  - allow:
+    - admin
+    match:
+      name: terraform
+context:
+  application: rundeck
+```

website/docs/r/acl_policy.md

@@ -36,3 +36,39 @@ The following arguments are supported:
 * `name` - (Required) The name of the policy. Must end with `.aclpolicy`.
 
 * `policy` - (Required) The name of the job, used to describe the job in the Rundeck UI.
+
+> Note: This example uses an ACL Policy file stored at the current working directory named `acl.yaml`.  Valid contents for that file are shown below.
+
+```
+by:
+  group: terraform
+description: Allow terraform Key Storage Access
+for:
+  storage:
+  - allow:
+    - read
+context:
+  application: rundeck
+---
+by:
+  group: terraform
+description: Allow Terraform Group [read] for all projects
+for:
+  project:
+  - allow:
+    - read
+context:
+  application: rundeck
+---
+by:
+  group: terraform
+description: Terraform Project Full Admin
+for:
+  project:
+  - allow:
+    - admin
+    match:
+      name: terraform
+context:
+  application: rundeck
+```

website/docs/r/job.html.md

@@ -17,11 +17,11 @@ Each job belongs to a project. A project can be created with the `rundeck_projec
 ## Example Usage
 
 ```hcl
-resource "rundeck_job" "bounceweb" {
-    name = "Bounce Web Servers"
-    project_name = "anvils"
+  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"
+    description       = "Restart the service daemons on all the web servers"
 
     command {
         shell_command = "sudo service anvils restart"

website/docs/r/private_key.html.md

@@ -15,9 +15,9 @@ it runs commands.
 ## Example Usage
 
 ```hcl
-resource "rundeck_private_key" "anvils" {
-    path = "anvils/id_rsa"
-    key_material = "${file("/id_rsa")}"
+resource "rundeck_private_key" "terraform" {
+  path         = "terraform/id_rsa"
+  key_material = "$${file(\"id_rsa.pub\")}"
 }
 ```
 

website/docs/r/project.html.md

@@ -15,20 +15,23 @@ can be run on.
 ## Example Usage
 
 ```hcl
-resource "rundeck_project" "anvils" {
-    name = "anvils"
-    description = "Application for managing Anvils"
-
-    ssh_key_storage_path = "anvils/id_rsa"
-
-    resource_model_source {
-        type = "file"
-        config = {
-            format = "resourcexml"
-            # This path is interpreted on the Rundeck server.
-            file = "/var/rundeck/projects/anvils/resources.xml"
-        }
+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"
+      # This path is interpreted on the Rundeck server.
+      file = "/home/rundeck/resources.xml"
+      writable = "true"
+      generateFileAutomatically = "true"
     }
+  }
+  extra_config = {
+    "project.label" = "Terraform Example"
+  }
 }
 ```
 
@@ -71,7 +74,7 @@ The following arguments are supported:
 * `extra_config` - (Optional) Behind the scenes a Rundeck project is really an arbitrary set of
   key/value pairs. This map argument allows setting any configuration properties that aren't
   explicitly supported by the other arguments described above, but due to limitations of Terraform
-  the key names must be written with slashes in place of dots. Do not use this argument to set
+  the key names must be written wrapped in double quotes. Do not use this argument to set
   properties that the above arguments set, or undefined behavior will result.
 
 `resource_model_source` blocks have the following nested arguments:
@@ -87,4 +90,3 @@ The following attributes are exported:
 
 * `name` - The unique name that identifies the project, as set in the arguments.
 * `ui_url` - The URL of the index page for this project in the Rundeck UI.
-

website/docs/r/public_key.html.md

@@ -18,17 +18,17 @@ may be used in the configuration of other resources such as ``aws_key_pair``.
 ## Example Usage
 
 ```hcl
-resource "rundeck_public_key" "anvils" {
-    path = "anvils/id_rsa.pub"
-    key_material = "ssh-rsa yada-yada-yada"
+resource "rundeck_public_key" "terraform" {
+  path         = "terraform/id_rsa.pub"
+  key_material = "ssh-rsa yada-yada-yada"
 }
 ```
 
 ## Argument Reference
 
 The following arguments are supported:
 
-* `delete` - (Computed) True if the key should be deleted when the resource is deleted. 
+* `delete` - (Computed) True if the key should be deleted when the resource is deleted.
   Defaults to true if key_material is provided in the configuration.
 
 * `path` - (Required) The path within the key store where the key will be stored. By convention