Add docs for ansible (#708)

docs/getting_started/0_scripts_quickstart/9_ansible_quickstart/index.mdx

@@ -0,0 +1,231 @@
+---
+title: 'Ansible Quickstart'
+slug: '/getting_started/scripts_quickstart/ansible'
+---
+
+import DocCard from '@site/src/components/DocCard';
+
+# Ansible Quickstart
+
+## Windmill Scripts
+
+In this quickstart guide, we will write our first script/playbook with ansible.
+
+<video
+	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
+	autoPlay
+	controls
+	id="main-video"
+	src="/videos/ansible_quickstart.mp4"
+/>
+
+<br />
+
+This tutorial covers how to create a simple ansible script through Windmill web IDE. See the dedicated page to [Develop Scripts Locally](../../../advanced/4_local_development/index.mdx).
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Local Development"
+		description="Develop from various environments such as your terminal, VS Code, and JetBrains IDEs."
+		href="/docs/advanced/local_development"
+	/>
+</div>
+
+Scripts are the basic building blocks in Windmill. They can be [run and scheduled](../../8_trigger_scripts/index.mdx) as standalone, chained together to create [Flows](../../../flows/1_flow_editor.mdx) or displayed with a personalized User Interface as [Apps](../../7_apps_quickstart/index.mdx).
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Script Editor"
+		description="All the details on scripts."
+		href="/docs/script_editor"
+	/>
+	<DocCard
+		title="Triggering Scripts"
+		description="Trigger flows on-demand, by schedule or on external events."
+		href="/docs/getting_started/trigger_scripts"
+	/>
+</div>
+
+Scripts consist of 2 parts:
+
+- [Code](#code): For ansible this is a playbook file written in yaml.
+- [Settings](#settings): settings & metadata about the Script such as its path, summary, description, [jsonschema](../../../core_concepts/13_json_schema_and_parsing/index.mdx) of its inputs (inferred from its signature).
+
+When stored in a code repository, these 2 parts are stored separately at `<path>.playbook.yml` and `<path>.script.yaml`
+
+#### Create an Ansible playbook script
+
+![Ansible in Windmill](./create_ansible_script.png)
+
+## Code (Playbook)
+
+In order to make Ansible playbooks compatible with the windmill environment and script model, there is some extra information preceding the start of the playbook that can be entered. Because of this, an Ansible playbook in Windmill will typically look like this:
+
+![Ansible in Windmill](./ansible_script_ide.png)
+
+```yml
+---
+inventory:
+  - resource_type: ansible_inventory
+    # You can pin an inventory to this script:
+    # resource: u/user/your_resource
+
+# File resources will be written in the relative \`target\` location before
+# running the playbook
+file_resources:
+  - resource: u/user/fabulous_jinja_template
+    target:  ./config_template.j2
+
+# Define the arguments of the windmill script
+extra_vars:
+  world_qualifier:
+    type: string
+
+dependencies:
+  galaxy:
+    collections:
+      - name: community.general
+      - name: community.vmware
+  python:
+    - jmespath
+---
+- name: Echo
+  hosts: 127.0.0.1
+  connection: local
+  vars:
+    my_result:
+      a: 2
+      b: true
+      c: "Hello"
+
+  tasks:
+  - name: Print debug message
+    debug:
+      msg: "Hello, {{world_qualifier}} world!"
+  - name: Write variable my_result to result.json
+    delegate_to: localhost
+    copy:
+      content: "{{ my_result | to_json }}"
+      dest: result.json
+```
+
+There are two YAML documents in series, the second being the Ansible Playbook. The first one is only used by windmill, and will not be visible to Ansible when executing the playbook. It contains different sections that declare some metadata about the script.
+
+We will now go thorugh each of these sections.
+
+### Arguments (extra-args)
+
+Windmill scripts can take arguments, and in order to define the names and types of the arguments you can use this section. These definitions will be parsed allowing the frontend to interactively display dynamic inputs for the script.
+
+
+```yaml
+extra_vars:
+  world_qualifier:
+    type: string
+  nested_object:
+    type: object
+    properties:
+      a:
+        type: string
+      b:
+        type: number
+  some_arr:
+    type: array
+    objects:
+      type: string
+```
+
+![Parsing Yaml and generating UI](./extra_vars_ui.png)
+
+The type definition is inspired and tries to follow the [OpenAPI Data Types standard](https://swagger.io/docs/specification/data-models/data-types/). Note that not all features / types are supported, the best way to know what is supported is to test it out in the Web IDE.
+
+To use windmill resources as types you can use the following type definition:
+
+```yaml
+extra_vars:
+  my_resource:
+    type: windmill_resource
+    resource_type: postgresql
+```
+
+![Postgres Resource UI](./postgres_ui.png)
+
+Under the hood, Windmill will pass these variables using the `--extra-args` flag to Ansible, so you can expect the according behavior.
+
+### Return Values
+
+In windmill scripts usually have a return value, which allows scripts to be chained in flows and run conditionally on the result of a previous operation. For Ansible playbooks you can achieve the same result by having one of the tasks (preferably the last one for coherence of results/errors) write a file named `result.json` with the JSON object you want to return:
+
+```yaml
+---
+tasks:
+
+  [...]
+
+  - name: Write variable my_result to result.json
+    delegate_to: localhost
+    copy:
+      content: "{{ my_result | to_json }}"
+      dest: result.json
+
+```
+
+Note that valid json must be written to the file or else the job will fail. Also, this should be done by the control node i.e. your worker, so it's important to use the `delegate_to: localhost` directive.
+
+
+### Inventories
+
+When using ansbile playbooks, you would usually run a command such as `ansible-playbook playbook.yml -i inventory.ini`. The ways to pass inventories to Ansible in Windmill is by filling the following section:
+
+```yaml
+inventory:
+  - resource_type: ansible_inventory
+```
+
+After adding this in the Web IDE, you will see a new `inventory.ini` argument pop up. You can then select or create a new ansible_inventory resource.
+
+![inventory ui](./inventory_ui.png)
+
+If you don't want one of the inputs of the script be the inventory, you can pin a specific resource to the script by specifying its path. In this case you don't need to specify the resource_type anymore:
+
+```yaml
+inventory:
+  - resource: u/user/my_ansible_inventory
+```
+
+Then the UI will not prompt you for the inventory but will use this resource at every run of the script. If otherwise you wish to not specify any inventory, you can remove the section altogether
+
+### Other non-inventory file resources
+
+It sometimes happens that your Ansible playbook depends on some text file existing at a relative path to the playbook. This can be a configuration file, a template, some other file that you can't inline or otherwise is simpler to keep as a separate file. In this case, Windmill offers a feature to create these files at the specified path before running the playbook. The syntax will be the following:
+
+```yaml
+file_resources:
+  - resource: u/user/fabulous_jinja_template
+    target:  ./config_template.j2
+```
+
+In the example above, the resource `u/user/faboulous_jinja_template` is a special plain text file resource. The target `./config_template.j2` is the path relative to the playbook where the file will be created and where the playbook can access it.
+
+Now you can write your notebook assuming that this file will exist at the time of execution.
+
+### Dependencies
+
+Ansible playbooks often depend on python packages or Ansible Galaxy Collections. In windmill you can specify these dependencies in the `dependencies` section and Windmill will take care of satisfying them before running the playbook.
+
+```yaml
+dependencies:
+  galaxy:
+    collections:
+      - name: community.general
+      - name: community.vmware
+  python:
+    - jmespath
+```
+
+The syntax is similar to `ansible-builder` and Execution Environments, however all is installed locally using the same technology as for managing [Python Dependencies](../../../advanced/15_dependencies_in_python/index.mdx) in python scripts, meaning no extra container is created.
+
+:::info Ansible vs Ansible-core
+Currently the Windmill image supporting ansible runs the full `ansible` and not `ansible-core`. You can expect the respective collections to be preinstalled.
+:::
+

docs/getting_started/0_scripts_quickstart/index.mdx

@@ -7,7 +7,8 @@ import {
 	SiPostgresql,
 	SiGraphql,
 	SiDocker,
-	SiPhp
+	SiPhp,
+	SiAnsible
 } from 'react-icons/si';
 
 # Scripts Quickstart
@@ -63,4 +64,10 @@ Windmill supports scripts in Python, TypeScript, Go, PHP, Bash, PHP and Sql.
 		href="/docs/getting_started/scripts_quickstart/rest_graphql"
 		Icon={SiGraphql}
 	/>
+	<DocCard
+		title="Ansible"
+		description="Write your first Windmill script in Ansible"
+		href="/docs/getting_started/scripts_quickstart/ansible"
+		Icon={SiAnsible}
+	/>
 </div>

sidebars.js

@@ -64,6 +64,11 @@ const sidebars = {
 									type: 'doc',
 									id: 'getting_started/scripts_quickstart/rest_grapqhql_quickstart/index',
 									label: 'Rest / GraphQL'
+								},
+								{
+									type: 'doc',
+									id: 'getting_started/scripts_quickstart/ansible_quickstart/index',
+									label: 'Ansible'
 								}
 							]
 						},