foreman_deployments 0.0.1

data/doc/design/tasks.md

@@ -0,0 +1,74 @@
+## Tasks
+
+
+#### RunPuppetTask
+Triggers a puppetrun on a host or group of them.
+
+* inputs:
+  * host_id(s)
+
+#### EnablePuppetTask
+Enable/disable periodic puppet runs on a host or group of them.
+
+* inputs:
+  * host_id(s)
+  * enable (flag saying whether to enable or disable puppet)
+
+#### ProvisionHostTask
+Starts provisioning of a host or group of them.
+
+* inputs:
+  * host_id(s)
+
+#### ParameterUpdateTask
+Updates a parameter on a hostgroup, host or group of them.
+
+* inputs:
+  * parameter
+  * host_id(s)
+  * hostgroup_id(s)
+
+#### RemoteExecutionTask
+Execute custom code on a host or group of them.
+
+* inputs:
+  * execution provider
+  * host_id(s)
+
+#### SelectResourceTask
+Select an existing resource from the Foreman.
+
+* limited only to resources that have scoped search defined on them
+* allows for defining query that limits the selection
+* inputs:
+  * preselected resource id (can be used as default)
+* output:
+  * the resource's id
+
+#### CreateResourceTask
+Creates a Foreman resource. Eventually it should be possible to create any resource inside Foreman.
+
+We're currently evaluating the posibilities of re-using the existing UI partials for this task's configuration.
+
+It will be possible to specify a range of how many resources of such type should be created. This is useful mainly for hosts
+where one sometimes wants to create multiple hosts with the same configuration. In such case, the host name will be configured
+to a template "#{name}-#{index}" by default.
+
+* inputs:
+  * attributes for the resource
+  * range for the number of resources (mainly for hosts)
+* output:
+  * the resource's id
+
+Alternatively we can create a dedicated task for each resource type.
+
+#### SelectOrCreateResourceTask
+Shows configuration UI of the select task but allows for switching into creation mode
+and adding new resource.
+
+* encapsulates `SelectResourceTask` and `CreateResourceTask` into one
+* inputs:
+  * select task (and it's configuration)
+  * create task (and it's configuration)
+* output:
+  * the resource's id

data/doc/design/user_interfaces.md

@@ -0,0 +1,189 @@
+# User interfaces
+
+
+## 3 Ways of creating a deployment:
+- by deploying a stack
+  - every stack is deployable
+  - the UI path: `stack list` → select stack & click `[Deploy]` → `deployment creation form` → click `[Configure]` → `deployment config form` → click `[Deploy]` → `deployment info`
+- by deploying a configuraion
+  - an existing configuration is cloned and used for the new deployment (not all values are clonable, e.g. bare metal hosts)
+  - the path: `stack's config list` → select config & click `[Deploy]` → `deployment creation form` → click `[Configure]` → `deployment config form` with cloned values, fields that are not clonable are blank → click `[Deploy]` → `deployment info`
+- by cloning an existing deployment
+  - technically the same as deploying a configuration, different only from the user's perspective
+  - the path: `deployment list` → select config & click `[Clone]` → `deployment creation form` → `[Configure]` → `deployment config form` with cloned values, fields that are not clonable are blank → `[Deploy]` → `deployment info`
+
+
+## UI pages
+
+### List of stacks
+- shows all stacks imported into foreman
+- the list contains
+  - stack name
+  - number of existing deployments (link to list of the deployments filtered by search)
+  - row action buttons:
+    - `deploy` - leads to the deployment creation form
+    - `configure` - leads to config form, result is saved as a separate config for future cloning
+    - `configurations` - leads to the list of existing configurations
+    - `export`
+    - `delete` - disabled if it's already deployed
+- top buttons:
+  - `import stack`
+
+### Stack info
+- shows info about used tasks, required puppet classes, subnets etc.
+- top buttons:
+  - `deploy` - leads to the deployment creation form
+  - `configure` - leads to config form, result is saved as a separate config for future cloning
+  - `export`
+  - `delete` - disabled if it's already deployed
+
+
+### List of stack configurations
+- shows all stack configurations
+- the list contains
+  - name of the configuration
+  - what stack is that for
+  - what deployment was that for (only if it's not a saved config template)
+  - row action buttons:
+    - `deploy` - leads to the deployment creation form
+    - `delete` - only for configurations that have no deployment assigned
+    - `details` - list of all configuration values
+- top buttons:
+  - NONE
+
+
+### List of existing deployments
+- shows all created deplyments
+- the list contains
+  - name of the deployment
+  - phase of the deployment (created/configured/deploying/deployed)
+  - number of hosts in the stack (link to list of the hosts filtered by search)
+  - row action buttons:
+    - `configure` - leads to the deployment creation form, shown only if the configuration is not finished yet
+    - `delete`
+- top buttons:
+  - NONE
+
+
+### Import stack form
+- select file field
+- below buttons:
+  - `cancel`
+  - `import` - successful import leads to the list of stacks
+
+
+### Deployment creation form
+- name for the deployment
+- list of select boxes for abstract substacks (name, description from the ChildStackTask should be shown here to explain)
+- select box for existing configuration (probably dependent on the combination of concrete substacks)
+- below buttons:
+  - `cancel`
+  - `create` - leads to config form
+
+
+### Deployment configuration form
+- displays field for configuration name (is prefilled with some meaningful value or hidden in case of deploying without preset config)
+- shows configuration partials for tasks that need some users inputs
+- parials are shown in the order from the stack definition
+
+- below buttons:
+  - `save`
+  - `deploy`
+  - `cancel`
+
+
+### Deployment info
+- progressbar is shown, waits until all hosts are provisioned and configured.
+- can show progress of the single actions
+- link to dynflow console
+- below buttons:
+  - `cancel`/`back`
+
+
+## CLI interactions
+Mimics the UI interactions.
+
+List available stacks
+```bash
+hammer stack list
+```
+
+Import a new stack from a file
+```bash
+hammer stack import --name "Web Server Stack" --file "web_server.json"
+```
+
+Json export of existing stacks
+```bash
+hammer stack export --name "Web Server Stack"
+```
+
+Get details about a stack
+```bash
+hammer stack info --name "Web Server Stack"
+```
+
+List all deployments of a stack
+```bash
+hammer stack deployments --name "Web Server Stack"
+```
+
+List saved configurations and deployments' configurations
+```bash
+hammer stack configurations --name "Web Server Stack"
+```
+
+List all existing deployments, filterable by stacks
+```bash
+hammer deployment list [--stack "Web Server Stack"]
+```
+
+Create a deployment of a stack. Users can optionally pass a saved config
+```bash
+hammer deployment create --stack "Web Server Stack" --name "Web Server Instance" [--configuration "My saved config"]
+```
+Assignment of concrete stacks will be available in future
+```bash
+hammer deployment create --stack "Web Server Stack" --name "Web Server Instance" [--configuration "My saved config"] --stacks="db=mysql,gallery=phoca"
+```
+
+Get details about a deployment. It shows state of the deployment and configuration values too
+```bash
+hammer deployment info --name "Web Server Instance"
+```
+
+Configure the deployment parameters. Values can be saved either all at once or one by one. There are multiple ways of implementing this
+
+**TODO**: *solve how to send structured values like nics*
+
+1) Mapping config to key-value pairs
+```bash
+hammer deployment configure --name "Web Server Instance" --values "db_passwd=xxx,db_user=webapp"
+```
+2) Always specify the task one configures as a full dot separated path
+```bash
+hammer deployment configure --name "Web Server Instance" --task "db" --values "count=1,compute_resource=libvirt"
+```
+```bash
+hammer deployment configure --name "Web Server Instance" --task "db.nics" --values "count=1"
+```
+3) Always send a json
+```bash
+hammer deployment configure --name "Web Server Instance" --values "{'db': {'count': 1, 'nics': [ ... ]}}"
+```
+
+Start the deployment process
+```bash
+hammer deployment deploy --name "Web Server Instance"
+```
+
+Clone a deployment. Creates a deployment with the cloned configuration. Should notify user whether there are some blank values that need additional attention.
+```bash
+hammer deployment clone --name "Web Server Instance" --new-name "Second Web Server Instance"
+```
+
+Deploy the cloned deployment.
+```bash
+hammer deployment deploy --name "Second Web Server Instance"
+```
+

data/doc/introduction.md

@@ -0,0 +1,84 @@
+# Foreman deployments
+
+Foreman deployments plugin allows for defining multi-host provisioning, configuration and orchestration.
+There are three main entities accross the whole plugin: **stacks**, **tasks** and **deployments**.
+
+
+## Stack
+
+*Stack* is an abstract representation of the multi-host infrastructure to be built. They are composed of multiple *tasks* dependent on each other and define
+relationships between them. See the "Tasks" section below for the detailed definition of the term.
+
+Same as majority of entities in the Foreman, stacks can be available to multiple organizations and locations.
+
+
+## Tasks
+
+Tasks are the units a stack is composed of. Each task has defined input parameters and results that it produces. Result of one task can be used as an input
+of another one, which enables for setting dependencies.
+
+The stack definition gives a unique name for each of the task instances.
+
+See the list of all [available tasks](writing_stacks.md) and their parameters.
+
+
+## Stack definition
+
+The stack defines tasks to be used, their inputs and relationships. Task's input can be:
+* hardcoded value
+* input required form a user in the configuration phase, see list of [available inputs](writing_stacks.md#available-inputs)
+* reference to a value from another task
+* ignored (default value is used)
+
+Stacks are defined in yaml files.
+
+```yaml
+# Following is an example stack definition that creates a new host within a hostgroup
+
+# name of the task
+#  |                  task type
+#  |                    |
+#  ˇ                    ˇ
+test_hostgroup: !task:FindResource
+  class: test_hostgroup        # <-- task parameters
+  search_term: 'name = Test'
+
+test_host: !task:CreateResource
+  class: Host
+  params:
+    hostgroup_id: !reference   # <-- reference to another task's output
+      object: test_hostgroup
+      field: result.ids.first
+    compute_resource_id: 1
+    compute_profile_id: 1
+    compute_attributes:
+      start: '1'
+    name: !input:Value         # <-- input entry point
+      default: deployment-test
+      description: Name for the test host
+```
+
+#### Stack's lifecycle
+
+1. Stacks are created as yaml descriptions of the infrastructure. Such yaml file is imported into the Foreman either via API.
+1. Modification of imported stacks are allowed up to the point where a first deployment of the stack is created.
+1. Stacks can't be deleted in the current release but this feature will be comming soon.
+
+
+## Deployment
+
+A *deployment* is a result of performing the instructions in a *stack*. It is an instance of a *stack*.
+
+Similar to hosts, deployments belong to a single organization and location.
+
+#### Deployment's lifecycle
+
+1. A deployment is created as a named instance of a stack.
+2. Before the deployment can be deployed, it can be configured. Users fill missing parameters in this step.
+3. A configured deployment can be deployed onto the Foreman's infrastructure. This step is handled by dynflow.
+
+
+## Example
+
+A more detailed example is covered in [How to create and deploy a stack](deployment_process.md) section
+of our documentation.

data/doc/writing_stacks.md

@@ -0,0 +1,102 @@
+# How to write a stack
+
+Stacks are defined in [yaml](http://yaml.org) format. Foreman deployments provide set of custom
+yaml tags for specifying tasks, references between them and inputs.
+
+Stack definition can contain only `task name` -> `task definition` pairs.
+Inner structure of the task definition varies according to the task type.
+
+```yaml
+uniqe_task_name: !task:TaskType
+  parameters:
+    some: values
+```
+
+## Available tasks
+
+### CreateResource
+Creates a resource in the Foreman including hosts.
+
+```yaml
+example: !task:CreateResource
+  class: Host # The foreman resource to create
+  params:     # Hash of parameters for the resource
+    # ...
+```
+**Output:**
+```yaml
+object:
+  # hash of the host's parameters including facts
+  # ...
+```
+
+### FindResource
+Find resources by the scoped search filter.
+
+```yaml
+example: !task:FindResource
+  class: Hostgroup           # The foreman resource to search for
+  search_term: 'name = Test' # Scoped search filter, same syntax as in the UI Search field
+```
+**Output:**
+```yaml
+results:
+    # array of the found resources
+    # ...
+result:
+    ids:     # array of resources' ids
+        - 1
+        - 2
+```
+
+### WaitUntilBuilt
+Waits until a host is provisioned and reports successfully.
+
+```yaml
+example: !task:WaitUntilBuilt
+  timout: 3600           # In seconds, default is 3 hours
+  host_id: !reference    # Id fo a host to wait for,
+    object: host_x       # usually passed as a reference to a host creation task
+    field: object.id
+
+```
+**Output:**
+```yaml
+task:
+  build: true/false # has the host been built yet?
+object:
+  # hash of the host's parameters including facts
+  # ...
+```
+
+## Available inputs
+
+Currently there's only one input type.
+More input types including some validation capabilities will be implemented in future.
+
+### Value
+Marks the parameter as an input entry point for users. It allows to
+provide a description and a default value.
+
+```yaml
+example: !task:SomeTask
+  name: !input:Value
+    default: test-deployment-foreman
+    description: Name for the foreman host
+```
+
+## Ordering actions without direct dependency
+
+Even though dynflow engine calculates the task dependencies automatically,
+there might be cases when a stack writer needs to put hard order between two
+tasks that don't directly depend on each other. In such situations a reserved
+field `after` can be used:
+
+```yaml
+FirstTask: !task:SomeTask
+
+SecondTask: !task:SomeTask
+  after: !reference
+    object: 'FirstTask'
+    field: 'result'
+```