Ansible support in Operator SDK

Ansible support in Operator SDK

Custom resource files

Operators use the Kubernetes extension mechanism, custom resource definitions (CRDs), so your custom resource (CR) looks and acts just like the built-in, native Kubernetes objects.

The CR file format is a Kubernetes resource file. The object has mandatory and optional fields:

Table 1. Custom resource fields
Field	Description
`apiVersion`	Version of the CR to be created.
`kind`	Kind of the CR to be created.
`metadata`	Kubernetes-specific metadata to be created.
`spec` (optional)	Key-value list of variables which are passed to Ansible. This field is empty by default.
`status`	Summarizes the current state of the object. For Ansible-based Operators, the status subresource is enabled for CRDs and managed by the `operator_sdk.util.k8s_status` Ansible module by default, which includes `condition` information to the CR `status`.
`annotations`	Kubernetes-specific annotations to be appended to the CR.

The following list of CR annotations modify the behavior of the Operator:

Table 2. Ansible-based Operator annotations
Annotation	Description
`ansible.operator-sdk/reconcile-period`	Specifies the reconciliation interval for the CR. This value is parsed using the standard Golang package time. Specifically, ParseDuration is used which applies the default suffix of `s`, giving the value in seconds.

Example Ansible-based Operator annotation

apiVersion: "test1.example.com/v1alpha1"
kind: "Test1"
metadata:
  name: "example"
annotations:
  ansible.operator-sdk/reconcile-period: "30s"

watches.yaml file

A group/version/kind (GVK) is a unique identifier for a Kubernetes API. The watches.yaml file contains a list of mappings from custom resources (CRs), identified by its GVK, to an Ansible role or playbook. The Operator expects this mapping file in a predefined location at /opt/ansible/watches.yaml.

Table 3. `watches.yaml` file mappings
Field	Description
`group`	Group of CR to watch.
`version`	Version of CR to watch.
`kind`	Kind of CR to watch
`role` (default)	Path to the Ansible role added to the container. For example, if your `roles` directory is at `/opt/ansible/roles/` and your role is named `busybox`, this value would be `/opt/ansible/roles/busybox`. This field is mutually exclusive with the `playbook` field.
`playbook`	Path to the Ansible playbook added to the container. This playbook is expected to be a way to call roles. This field is mutually exclusive with the `role` field.
`reconcilePeriod` (optional)	The reconciliation interval, how often the role or playbook is run, for a given CR.
`manageStatus` (optional)	When set to `true` (default), the Operator manages the status of the CR generically. When set to `false`, the status of the CR is managed elsewhere, by the specified role or playbook or in a separate controller.

Example watches.yaml file

- version: v1alpha1 (1)
  group: test1.example.com
  kind: Test1
  role: /opt/ansible/roles/Test1
- version: v1alpha1 (2)
  group: test2.example.com
  kind: Test2
  playbook: /opt/ansible/playbook.yml
- version: v1alpha1 (3)
  group: test3.example.com
  kind: Test3
  playbook: /opt/ansible/test3.yml
  reconcilePeriod: 0
  manageStatus: false

1	Simple example mapping `Test1` to the `test1` role.
2	Simple example mapping `Test2` to a playbook.
3	More complex example for the `Test3` kind. Disables re-queuing and managing the CR status in the playbook.

Advanced options

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

Some features can be overridden per resource using an annotation on that CR. The options that can be overridden have the annotation specified below.

Table 4. Advanced watches.yaml file options
Feature	YAML key	Description	Annotation for override	Default value
Reconcile period	`reconcilePeriod`	Time between reconcile runs for a particular CR.	`ansible.operator-sdk/reconcile-period`	`1m`
Manage status	`manageStatus`	Allows the Operator to manage the `conditions` section of each CR `status` section.		`true`
Watch dependent resources	`watchDependentResources`	Allows the Operator to dynamically watch resources that are created by Ansible.		`true`
Watch cluster-scoped resources	`watchClusterScopedResources`	Allows the Operator to watch cluster-scoped resources that are created by Ansible.		`false`
Max runner artifacts	`maxRunnerArtifacts`	Manages the number of artifact directories that Ansible Runner keeps in the Operator container for each individual resource.	`ansible.operator-sdk/max-runner-artifacts`	`20`

Example watches.yml file with advanced options

- version: v1alpha1
  group: app.example.com
  kind: AppService
  playbook: /opt/ansible/playbook.yml
  maxRunnerArtifacts: 30
  reconcilePeriod: 5s
  manageStatus: False
  watchDependentResources: False

Extra variables sent to Ansible

Extra variables can be sent to Ansible, which are then managed by the Operator. The spec section of the custom resource (CR) passes along the key-value pairs as extra variables. This is equivalent to extra variables passed in to the ansible-playbook command.

The Operator also passes along additional variables under the meta field for the name of the CR and the namespace of the CR.

For the following CR example:

apiVersion: "app.example.com/v1alpha1"
kind: "Database"
metadata:
  name: "example"
spec:
  message: "Hello world 2"
  newParameter: "newParam"

The structure passed to Ansible as extra variables is:

{ "meta": {
        "name": "<cr_name>",
        "namespace": "<cr_namespace>",
  },
  "message": "Hello world 2",
  "new_parameter": "newParam",
  "_app_example_com_database": {
     <full_crd>
   },
}

The message and newParameter fields are set in the top level as extra variables, and meta provides the relevant metadata for the CR as defined in the Operator. The meta fields can be accessed using dot notation in Ansible, for example:

---
- debug:
    msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"

Ansible Runner directory

Ansible Runner keeps information about Ansible runs in the container. This is located at /tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name>.

Additional resources

To learn more about the runner directory, see the Ansible Runner documentation.