Ansible Operator Watches

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 These resources, as well as child resources (determined by owner references) will be monitored for updates and cached.

  • 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): Specifies a role to be executed. This field is mutually exclusive with the “playbook” field. This field can be:
    • an absolute path to a role directory.
    • a relative path within one of the directories specified by ANSIBLE_ROLES_PATH environment variable or ansible-roles-path flag.
    • a relative path within the current working directory, which defaults to /opt/ansible/roles.
    • a fully qualified collection name of an installed Ansible collection. Ansible collections are installed to ~/.ansible/collections or /usr/share/ansible/collections by default. If they are installed elsewhere, use the ANSIBLE_COLLECTIONS_PATH environment variable or the ansible-collections-path flag
  • playbook: This is the playbook name 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. When running locally, the playbook is expected to be in the current project directory.
  • vars: This is an arbitrary map of key-value pairs. The contents will be passed as extra_vars to the playbook or role specified for this watch.
  • reconcilePeriod (optional): The maximum interval in seconds that the operator will wait before beginning another reconcile, even if no watched events are received. When an operator watches many resources, each reconcile can become expensive, and a low value here can actually reduce performance. Typically, this option should only be used in advanced use cases where watchDependentResources is set to False and when is not possible to use the watch feature. E.g To managing external resources that don’t raise Kubernetes events.
  • manageStatus (optional): When true (default), the operator will manage the status of the CR generically. Set to false, the status of the CR is managed elsewhere, by the specified role/playbook or in a separate controller.
  • blacklist: A list of child resources (by GVK) that will not be watched or cached.

An example Watches file:

  1. ---
  2. # Simple example mapping Foo to the Foo role
  3. - version: v1alpha1
  4. group: foo.example.com
  5. kind: Foo
  6. role: Foo
  7. # Simple example mapping Bar to a playbook
  8. - version: v1alpha1
  9. group: bar.example.com
  10. kind: Bar
  11. playbook: playbook.yml
  12. # More complex example for our Baz kind
  13. # Here we will disable requeuing and be managing the CR status in the playbook,
  14. # and specify additional variables.
  15. - version: v1alpha1
  16. group: baz.example.com
  17. kind: Baz
  18. playbook: baz.yml
  19. reconcilePeriod: 0
  20. manageStatus: False
  21. vars:
  22. foo: bar
  23. # ConfigMaps owned by a Memcached CR will not be watched or cached.
  24. - version: v1alpha1
  25. group: cache.example.com
  26. kind: Memcached
  27. role: /opt/ansible/roles/memcached
  28. blacklist:
  29. - group: ""
  30. version: v1
  31. kind: ConfigMap
  32. # Example usage with a role from an installed Ansible collection
  33. - version: v1alpha1
  34. group: bar.example.com
  35. kind: Bar
  36. role: myNamespace.myCollection.myRole
  37. # Example filtering of resources with specific labels
  38. - version: v1alpha1
  39. group: bar.example.com
  40. kind: Bar
  41. playbook: playbook.yml
  42. selector:
  43. matchLabels:
  44. foo: bar
  45. matchExpressions:
  46. - {key: foo, operator: In, values: [bar]}
  47. - {key: baz, operator: Exists, values: []}

The advanced features can be enabled by adding them to your watches file per GVK. They can go below the group, version, kind and playbook or role.

Some features can be overridden per resource via an annotation on that CR. The options that are overridable will have the annotation specified below.

FeatureYaml KeyDescriptionAnnotation for overridedefaultDocumentation
Reconcile PeriodreconcilePeriodtime between reconcile runs for a particular CRansible.sdk.operatorframework.io/reconcile-period1m
Manage StatusmanageStatusAllows the ansible operator to manage the conditions section of each resource’s status section.true
Watching Dependent ResourceswatchDependentResourcesAllows the ansible operator to dynamically watch resources that are created by ansibletruedependent watches
Watching Cluster-Scoped ResourceswatchClusterScopedResourcesAllows the ansible operator to watch cluster-scoped resources that are created by ansiblefalse
Max Runner ArtifactsmaxRunnerArtifactsManages the number of artifact directories that ansible runner will keep in the operator container for each individual resource.ansible.sdk.operatorframework.io/max-runner-artifacts20
FinalizerfinalizerSets a finalizer on the CR and maps a deletion event to a playbook or rolefinalizers
SelectorselectorIdentifies a set of objects based on their labelsNone AppliedLabels and Selectors
Automatic Case ConversionsnakeCaseParametersDetermines whether to convert the CR spec from camelCase to snake_case before passing the contents to Ansible as extra_varstrue

Example

  1. ---
  2. - version: v1alpha1
  3. group: app.example.com
  4. kind: AppService
  5. playbook: playbook.yml
  6. maxRunnerArtifacts: 30
  7. reconcilePeriod: 5s
  8. manageStatus: False
  9. watchDependentResources: False
  10. snakeCaseParameters: False
  11. finalizer:
  12. name: finalizer.app.example.com
  13. vars:
  14. state: absent

Note: By using the command operator-sdk add api you are able to add additional CRDs to the project API, which can aid in designing your solution using concepts such as encapsulation, single responsibility principle, and cohesion, which could make the project easier to read, debug, and maintain. With this approach, you are able to customize and optimize the configurations more specifically per GKV via the watches.yaml file.

Example:

  1. ---
  2. - version: v1alpha1
  3. group: app.example.com
  4. kind: AppService
  5. playbook: playbook.yml
  6. maxRunnerArtifacts: 30
  7. reconcilePeriod: 5s
  8. manageStatus: False
  9. watchDependentResources: False
  10. finalizer:
  11. name: finalizer.app.example.com
  12. vars:
  13. state: absent
  14. - version: v1alpha1
  15. group: app.example.com
  16. kind: Database
  17. playbook: playbook.yml
  18. watchDependentResources: True
  19. manageStatus: True

Last modified July 24, 2020: *: consistently use *.sdk.operatorframework.io wherever we use domains (#3527) (faa4a563)