Merge pull request #29156 from adellape/osdk_47_ansible

Author: adellape

_topic_map.yml

@@ -1139,18 +1139,44 @@ Topics:
     File: osdk-about
   - Name: Installing the CLI
     File: osdk-installing-cli
-  - Name: Creating Go-based Operators
+  - Name: Go-based Operators
     Dir: golang
     Topics:
     - Name: Quickstart
       File: osdk-golang-quickstart
     - Name: Tutorial
       File: osdk-golang-tutorial
-  - Name: Creating Ansible-based Operators
-    File: osdk-ansible
-  - Name: Creating Helm-based Operators
-    File: osdk-helm
-  - Name: Generating a cluster service version (CSV)
+    - Name: Project layout
+      File: osdk-golang-project-layout
+  - Name: Ansible-based Operators
+    Dir: ansible
+    Topics:
+    - Name: Quickstart
+      File: osdk-ansible-quickstart
+    - Name: Tutorial
+      File: osdk-ansible-tutorial
+    - Name: Project layout
+      File: osdk-ansible-project-layout
+    - Name: Ansible support
+      File: osdk-ansible-support
+    - Name: Kubernetes Collection for Ansible
+      File: osdk-ansible-k8s-collection
+    - Name: Using Ansible inside an Operator
+      File: osdk-ansible-inside-operator
+    - Name: Custom resource status management
+      File: osdk-ansible-cr-status
+  - Name: Helm-based Operators
+    Dir: helm
+    Topics:
+    - Name: Quickstart
+      File: osdk-helm-quickstart
+    - Name: Tutorial
+      File: osdk-helm-tutorial
+    - Name: Project layout
+      File: osdk-helm-project-layout
+    - Name: Helm support
+      File: osdk-helm-support
+  - Name: Defining cluster service versions (CSVs)
     File: osdk-generating-csvs
   - Name: Working with bundle images
     File: osdk-working-bundle-images
@@ -1165,8 +1191,6 @@ Topics:
   - Name: Migrating to Operator SDK v0.1.0
     File: osdk-migrating-to-v0-1-0
     Distros: openshift-origin
-  - Name: Appendices
-    File: osdk-appendices
 - Name: Red Hat Operators reference
   File: operator-reference
 ---

modules/osdk-about-openapi-validation.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * operators/operator_sdk/osdk-golang-tutorial.adoc
+// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc
 
 [id="osdk-about-openapi-validation_{context}"]
 = About OpenAPI validation

…les/osdk-ansible-managing-cr-status.adoc modules/osdk-ansible-cr-status-about.adocmodules/osdk-ansible-managing-cr-status.adoc renamed to modules/osdk-ansible-cr-status-about.adoc modules/osdk-ansible-managing-cr-status.adoc renamed to modules/osdk-ansible-cr-status-about.adoc

@@ -1,17 +1,17 @@
 // Module included in the following assemblies:
 //
-// * operators/operator_sdk/osdk-ansible.adoc
+// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc
 
-[id="osdk-ansible-managing-cr-status_{context}"]
-= Managing custom resource status using the `operator_sdk.util` Ansible collection
+[id="osdk-ansible-cr-status-about_{context}"]
+= About custom resource status in Ansible-based Operators
 
 Ansible-based Operators automatically update custom resource (CR) link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource[`status` subresources] with generic information about the previous Ansible run. This includes the number of successful and failed tasks and relevant error messages as shown:
 
 [source,yaml]
 ----
 status:
   conditions:
-    - ansibleResult:
+  - ansibleResult:
       changed: 3
       completion: 2018-12-03T13:45:57.13329
       failures: 1
@@ -33,51 +33,3 @@ status:
 Ansible-based Operators also allow Operator authors to supply custom status values with the `k8s_status` Ansible module, which is included in the link:https://galaxy.ansible.com/operator_sdk/util[`operator_sdk.util` collection]. This allows the author to update the `status` from within Ansible with any key-value pair as desired.
 
 By default, Ansible-based Operators always include the generic Ansible run output as shown above. If you would prefer your application did _not_ update the status with Ansible output, you can track the status manually from your application.
-
-.Procedure
-
-. To track CR status manually from your application, update the `watches.yaml` file with a `manageStatus` field set to `false`:
-+
-[source,yaml]
-----
-- version: v1
-  group: api.example.com
-  kind: Test1
-  role: Test1
-  manageStatus: false
-----
-
-. Use the `operator_sdk.util.k8s_status` Ansible module to update the subresource. For example, to update with key `test1` and value `test2`, `operator_sdk.util` can be used as shown:
-+
-[source,yaml]
-----
-- operator_sdk.util.k8s_status:
-    api_version: app.example.com/v1
-    kind: Test1
-    name: "{{ meta.name }}"
-    namespace: "{{ meta.namespace }}"
-    status:
-      test1: test2
-----
-+
-Collections can also be declared in the `meta/main.yml` for the role, which is included for new scaffolded Ansible Operators:
-+
-[source,yaml]
-----
-collections:
-  - operator_sdk.util
-----
-+
-Declaring collections in the role meta allows you to invoke the `k8s_status` module directly:
-+
-[source,yaml]
-----
-k8s_status:
-  <snip>
-  status:
-    test1: test2
-----
-
-.Additional resources
-
-- For more details about user-driven status management from Ansible-based Operators, see the link:https://github.com/operator-framework/operator-sdk/blob/master/proposals/ansible-operator-status.md[Ansible-based Operator Status Proposal for Operator SDK].

modules/osdk-ansible-cr-status-manual.adoc

@@ -0,0 +1,56 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc
+
+[id="osdk-ansible-cr-status-manual_{context}"]
+= Tracking custom resource status manually
+
+You can use the `operator_sdk.util` collection to modify your Ansible-based Operator to track custom resource (CR) status manually from your application.
+
+.Prerequisites
+
+* Ansible-based Operator project created by using the Operator SDK
+
+.Procedure
+
+. Update the `watches.yaml` file with a `manageStatus` field set to `false`:
++
+[source,yaml]
+----
+- version: v1
+  group: api.example.com
+  kind: <kind>
+  role: <role>
+  manageStatus: false
+----
+
+. Use the `operator_sdk.util.k8s_status` Ansible module to update the subresource. For example, to update with key `test` and value `data`, `operator_sdk.util` can be used as shown:
++
+[source,yaml]
+----
+- operator_sdk.util.k8s_status:
+    api_version: app.example.com/v1
+    kind: <kind>
+    name: "{{ ansible_operator_meta.name }}"
+    namespace: "{{ ansible_operator_meta.namespace }}"
+    status:
+      test: data
+----
+
+. You can declare collections in the `meta/main.yml` file for the role, which is included for scaffolded Ansible-based Operators:
++
+[source,yaml]
+----
+collections:
+  - operator_sdk.util
+----
+
+. After declaring collections in the role meta, you can invoke the `k8s_status` module directly:
++
+[source,yaml]
+----
+k8s_status:
+  ...
+  status:
+    key1: value1
+----

modules/osdk-ansible-create-api.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc
+
+[id="osdk-ansible-create-api-controller_{context}"]
+= Creating an API
+
+Use the Operator SDK CLI to create a Memcached API.
+
+.Procedure
+
+* Run the following command to create an API with group `cache`, version, `v1`, and kind `Memcached`:
++
+[source,terminal]
+----
+$ operator-sdk create api \
+    --group cache \
+    --version v1 \
+    --kind Memcached \
+    --generate-role <1>
+----
+<1> Generates an Ansible role for the API.
+
+After creating the API, your Operator project updates with the following structure:
+
+Memcached CRD:: Includes a sample `Memcached` resource
+
+Manager:: Program that reconciles the state of the cluster to the desired state by using:
++
+--
+* A reconciler, either an Ansible role or playbook
+* A `watches.yaml` file, which connects the `Memcached` resource to the `memcached` Ansible role
+--

modules/osdk-ansible-custom-resource-files.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * operators/operator_sdk/osdk-ansible.adoc
+// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
 
 [id="osdk-ansible-custom-resource-files_{context}"]
 = Custom resource files

modules/osdk-ansible-extra-variables.adoc

@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * operators/operator_sdk/osdk-ansible.adoc
+// * operators/operator_sdk/ansible/osdk-ansible-support.adoc
 
 [id="osdk-ansible-extra-variables_{context}"]
 = Extra variables sent to Ansible
@@ -42,6 +42,7 @@ The `message` and `newParameter` fields are set in the top level as extra variab
 
 [source,yaml]
 ----
+---
 - debug:
-    msg: "name: {{ meta.name }}, {{ meta.namespace }}"
+    msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"
 ----

modules/osdk-ansible-inside-operator-local.adoc

@@ -0,0 +1,123 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc
+
+[id="osdk-ansible-inside-operator-local_{context}"]
+= Testing an Ansible-based Operator locally
+
+You can test the logic inside of an Ansible-based Operator running locally by using the `make run` command from the top-level directory of your Operator project. The `make run` Makefile target runs the `ansible-operator` binary locally, which reads from the `watches.yaml` file and uses your `~/.kube/config` file to communicate with a Kubernetes cluster just as the `k8s` modules do.
+
+[NOTE]
+====
+You can customize the roles path by setting the environment variable `ANSIBLE_ROLES_PATH` or by using the `ansible-roles-path` flag. If the role is not found in the `ANSIBLE_ROLES_PATH` value, the Operator looks for it in `{{current directory}}/roles`.
+====
+
+.Prerequisites
+
+- link:https://ansible-runner.readthedocs.io/en/latest/install.html[Ansible Runner] version v1.1.0+
+- link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plug-in] version v1.0.0+
+- Performed the previous steps for testing the Kubernetes Collection locally
+
+.Procedure
+
+. Install your custom resource definition (CRD) and proper role-based access control (RBAC) definitions for your custom resource (CR):
++
+[source,terminal]
+----
+$ make install
+----
++
+.Example output
+[source,terminal]
+----
+/usr/bin/kustomize build config/crd | kubectl apply -f -
+customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created
+----
+
+. Run the `make run` command:
++
+[source,terminal]
+----
+$ make run
+----
++
+.Example output
+[source,terminal]
+----
+/home/user/memcached-operator/bin/ansible-operator run
+{"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.3.0","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
+...
+{"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"}
+{"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
+{"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
+{"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
+{"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
+{"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
+{"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
+{"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
+{"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}
+----
++
+With the Operator now watching your CR for events, the creation of a CR will trigger your Ansible role to run.
++
+[NOTE]
+====
+Consider an example `config/samples/<gvk>.yaml` CR manifest:
+
+[source,yaml]
+----
+apiVersion: <group>.example.com/v1alpha1
+kind: <kind>
+metadata:
+  name: "<kind>-sample"
+----
+
+Because the `spec` field is not set, Ansible is invoked with no extra variables. Passing extra variables from a CR to Ansible is covered in another section. It is important to set reasonable defaults for the Operator.
+====
+
+. Create an instance of your CR with the default variable `state` set to `present`:
++
+[source,terminal]
+----
+$ oc apply -f config/samples/<gvk>.yaml
+----
+
+. Check that the `example-config` config map was created:
++
+[source,terminal]
+----
+$ oc get configmaps
+----
++
+.Example output
+[source,terminal]
+----
+NAME                    STATUS    AGE
+example-config          Active    3s
+----
+
+. Modify your `config/samples/<gvk>.yaml` file to set the `state` field to `absent`. For example:
++
+[source,yaml]
+----
+apiVersion: cache.example.com/v1
+kind: Memcached
+metadata:
+  name: memcached-sample
+spec:
+  state: absent
+----
+
+. Apply the changes:
++
+[source,terminal]
+----
+$ oc apply -f config/samples/<gvk>.yaml
+----
+
+. Confirm that the config map is deleted:
++
+[source,terminal]
+----
+$ oc get configmap
+----