Ansible Operator Tutorial

This guide walks through an example of building a simple memcached-operator powered by Ansible using tools and libraries provided by the Operator SDK.

  • Install operator-sdk and the
  • Access to a Kubernetes v1.16.0+ cluster.
  • User authorized with permissions.

In this section we will:

  • extend the Kubernetes API with a Custom Resource Definition that allows users to create Memcached resources.
  • create a manager that updates the state of the cluster to the desired state defined by Memcached resources.

Scaffold a New Project

Begin by generating a new project from a new directory.

Among the files generated by this command is a Kubebuilder PROJECT file. Subsequent operator-sdk commands (and help text) run from the project root read this file and are aware that the project type is Ansible.

  1. # Since this is an Ansible-based project, this help text is Ansible specific.
  2. $ operator-sdk create api -h

Next, we will create a Memcached API.

  1. $ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --generate-role

The scaffolded operator has the following structure:

  • Memcached Custom Resource Definition, and a sample Memcached resource.
  • A “Manager” that reconciles the state of the cluster to the desired state
    • A reconciler, which is an Ansible Role or Playbook.

See scaffolded files reference and for more detailed information

Modify the Manager

Now we need to provide the reconcile logic, in the form of an Ansible Role, which will run every time a Memcached resource is created, updated, or delete.

Update roles/memcached/tasks/main.yml:

  1. ---
  2. - name: start memcached
  3.   community.kubernetes.k8s:
  4.     definition:
  5.       kind: Deployment
  6.       apiVersion: apps/v1
  7.       metadata:
  9.         namespace: '{{ ansible_operator_meta.namespace }}'
  10.       spec:
  11.         replicas: "{{size}}"
  12.         selector:
  13.           matchLabels:
  14.             app: memcached
  15.         template:
  16.           metadata:
  17.             labels:
  18.               app: memcached
  19.           spec:
  20.             containers:
  21.             - name: memcached
  22.               command:
  23.               - -m=64
  24.               - -o
  25.               - modern
  26.               - -v
  27.               image: "docker.io/memcached:1.4.36-alpine"
  28.               ports:
  29.                 - containerPort: 11211
  • Ensure a memcached Deployment exists
  • Set the Deployment size

It is good practice to set default values for variables used in Ansible Roles, so edit :

Finally, update the Memcached sample, config/samples/cache_v1alpha1_memcached.yaml:

  1. apiVersion: cache.example.com/v1alpha1
  2. kind: Memcached
  3. metadata:
  4.   name: memcached-sample
  5. spec:
  6.   size: 3

The key-value pairs in the Custom Resource spec are passed to Ansible as extra variables.

Note: The names of all variables in the spec field are converted to snake_case by the operator before running ansible. For example, serviceAccount in the spec becomes service_account in ansible. You can disable this case conversion by setting the snakeCaseParameters option to false in your watches.yaml. It is recommended that you perform some type validation in Ansible on the variables to ensure that your application is receiving expected input.

Finishing up

All that remains is building and pushing the operator container to your favorite registry.

  1. $  make docker-build docker-push IMG=<some-registry>/<project-name>:tag

NOTE: To allow the cluster pull the image the repository needs to be set as public or you must configure an image pull secret

This section walks through the steps that operator users will perform to deploy the operator and managed resources.

Install the CRD

To apply the Memcached Kind (CRD):

  1. $ make install

Deploy the Operator:

We are using the memcached-operator-system Namespace, so let’s set that context.

  1. $ kubectl config set-context --current --namespace=memcached-operator-system
  1. $ kubectl get deployment 
  3. NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  4. memcached-operator       1         1         1            1           1m

Create Memcached Resource

Create the resource, the operator will do the rest.

    Verify that Memcached pods are created

    Cleanup

    Clean up the resources:

    1. $ make undeploy

    We recommend reading through the our Ansible development section for tips and tricks, including how to run the operator locally.

    In this tutorial, the scaffolded could be used as-is, but has additional optional features. See .

    For brevity, some of the scaffolded files were left out of this guide. See Scaffolding Reference

    This example built a namespaced scope operator, but Ansible operators can also be used with cluster-wide scope. See the documentation.

    OLM will manage creation of most if not all resources required to run your operator, using a bit of setup from other operator-sdk commands. Check out the OLM integration guide.