Document the manageStatus flag

Author: djzager

doc/ansible/dev/developer_guide.md

@@ -147,79 +147,6 @@ trigger this Ansible logic when a custom resource changes. In the above
 example, we want to map a role to a specific Kubernetes resource that the
 operator will watch. This mapping is done in a file called `watches.yaml`.
 
-### Watches file
-
-The Operator expects a mapping file, which lists each GVK to watch and the
-corresponding path to an Ansible role or playbook, to be copied into the
-container at a predefined location: /opt/ansible/watches.yaml
-
-Dockerfile example:
-```Dockerfile
-COPY watches.yaml /opt/ansible/watches.yaml
-```
-
-The Watches file format is yaml and is an array of objects. The object has
-mandatory fields:
-
-**version**:  The version of the Custom Resource that you will be watching.
-
-**group**:  The group of the Custom Resource that you will be watching.
-
-**kind**:  The kind of the Custom Resource that you will be watching.
-
-**playbook**:  This is the path to the playbook that you have added to the
-container. This playbook is expected to be simply a way to call roles. This
-field is mutually exclusive with the "role" field.
-
-**role**:  This is the path to the role that you have added to the container.
-For example if your roles directory is at `/opt/ansible/roles/` and your role
-is named `busybox`, this value will be `/opt/ansible/roles/busybox`. This field
-is mutually exclusive with the "playbook" field.
-
-Example specifying a role:
-
-```yaml
----
-- version: v1alpha1
-  group: foo.example.com
-  kind: Foo
-  role: /opt/ansible/roles/Foo
-```
-
-#### Using playbooks in watches.yaml
-
-By default, `operator-sdk new --type ansible` sets `watches.yaml` to execute a
-role directly on a resource event. This works well for new projects, but with a
-lot of Ansible code this can be hard to scale if we are putting everything
-inside of one role. Using a playbook allows the developer to have more
-flexibility in consuming other roles and enabling more customized deployments
-of their application. To do this, modify `watches.yaml` to use a playbook
-instead of the role:
-```yaml
----
-- version: v1alpha1
-  group: foo.example.com
-  kind: Foo
-  playbook: /opt/ansible/playbook.yml
-```
-
-Modify `tmp/build/Dockerfile` to put `playbook.yml` in `/opt/ansible` in the
-container in addition to the role (`/opt/ansible` is the `HOME` environment
-variable inside of the Ansible Operator base image):
-```Dockerfile
-FROM quay.io/water-hole/ansible-operator
-
-COPY roles/ ${HOME}/roles
-COPY playbook.yaml ${HOME}/playbook.yaml
-COPY watches.yaml ${HOME}/watches.yaml
-```
-
-Alternatively, to generate a skeleton project with the above changes, a
-developer can also do:
-```bash
-$ operator-sdk new --type ansible --kind Foo --api-version foo.example.com/v1alpha1 foo-operator --generate-playbook
-```
-
 ### Custom Resource file
 
 The Custom Resource file format is Kubernetes resource file. The object has

doc/ansible/user-guide.md

@@ -62,6 +62,55 @@ If you'd like to create your memcached-operator project to be cluster-scoped use
 $ operator-sdk new memcached-operator --cluster-scoped --api-version=cache.example.com/v1alpha1 --kind=Memcached --type=ansible
 ```
 
+### Watches file
+
+The Watches file contains a list of mappings from custom resources, identified
+by it's Group, Version, and Kind, to an Ansible Role or Playbook. The Operator
+expects this mapping file in a predefined location: `/opt/ansible/watches.yaml`
+
+* **group**:  The group of the Custom Resource that you will be watching.
+* **version**:  The version of the Custom Resource that you will be watching.
+* **kind**:  The kind of the Custom Resource that you will be watching.
+* **role** (default):  This is the path to the role that you have added to the
+  container.  For example if your roles directory is at `/opt/ansible/roles/`
+  and your role is named `busybox`, this value will be
+  `/opt/ansible/roles/busybox`. This field is mutually exclusive with the
+  "playbook" field.
+* **playbook**:  This is the path to the playbook that you have added to the
+  container. This playbook is expected to be simply a way to call roles. This
+  field is mutually exclusive with the "role" field.
+* **reconcilePeriod** (optional): The reconciliation interval, how often the
+  role/playbook is run, for a given CR.
+* **manageStatus** (optional): Specifies who is managing the status for the CR.
+  Set to `false` when you want the role/playbook to be solely responsible for
+  the CR's status.
+
+An example Watches file:
+
+```yaml
+---
+# Simple example mapping Foo to the Foo role
+- version: v1alpha1
+  group: foo.example.com
+  kind: Foo
+  role: /opt/ansible/roles/Foo
+
+# Simple example mapping Bar to a playbook
+- version: v1alpha1
+  group: bar.example.com
+  kind: Bar
+  playbook: /opt/ansible/playbook.yaml
+
+# More complex example for our Baz kind
+# Here we will disable requeuing and be managing the CR status in the playbook
+- version: v1alpha1
+  group: baz.example.com
+  kind: Baz
+  playbook: /opt/ansible/baz.yaml
+  reconcilePeriod: 0
+  manageStatus: false
+```
+
 ## Customize the operator logic
 
 For this example the memcached-operator will execute the following