DRAFT_Ansible_kb_docs.md

Quickstart

This section will demonstrate how to use the operator-sdk to quickly scaffold a simple Ansible-based operator that extends the Kubernetes API, allowing users to deploy Memcached by creating a custom Kubernetes resource.

Installation

See osdk install and then install the additional Ansible-operator prerequisites.

Initialize a new Project

The operator-sdk can initialize an Ansible-based operator project and create a new Kubernetes API in a single command::

mkdir memcached-operator
cd memcached-operator
operator-sdk init --plugins=ansible.operator-sdk.io/v1 \
  --group=cache --domain=example.com --version=v1alpha1 --kind=Memcached \ 
  --generate-role

For an explanation of the files see the [Scaffolded files][TODO] section.

For more on the CLI, see the [Commands][TODO], or type operator-sdk -h.

Modify the manager

Ansible-based operators control the state of the cluster by running Ansible Roles or Playbooks in response to changes in a watched Kubernetes resouces. In this case, any time a Memcached resource is created, updated, or deleted, the memcached Ansible Role is executed.

Update the memcached Ansible Role

Edit the role to deploy a Memcached container.

memcached-operator/roles/memcached/tasks/main.yml:

---
- name: start memcached
  community.kubernetes.k8s:
    definition:
      kind: Deployment
      apiVersion: apps/v1
      metadata:
        name: '{{ meta.name }}-memcached'
        namespace: '{{ meta.namespace }}'
      spec:
        replicas: "{{size}}"
        selector:
          matchLabels:
            app: memcached
        template:
          metadata:
            labels:
              app: memcached
          spec:
            containers:
            - name: memcached
              command:
              - memcached
              - -m=64
              - -o
              - modern
              - -v
              image: "docker.io/memcached:1.4.36-alpine"
              ports:
                - containerPort: 11211

The value of {{ size }} comes from the Memcached resource. See [Custom Resource][TODO].

It's good practice to set default values for variables used in Ansible roles, so go ahead and edit roles/defaults.main.yml:

---
# defaults file for Memcached
size: 1

Finishing up

That's all there is to creating a simple operator! All that's left is building and pushing the operator container to your favorite registry.

export IMG=quay.io/someuser/image:v1.0.0 make docker-build && make docker-push

If you would prefer to skip this step for now, the following steps use a container we've built from the [operator-sdk-samples][TODO/ansible-memcached] repository:

quay.io/operator-sd/ansible-memcached-operator-tutorial:v0.0.0

Operator User: Update the Memcached resource

Update the sample Memcached manifest to set the desired size:

memcached-operator/config/samples/cache_v1alpha1_memcached.yaml

apiVersion: cache.example.com/v1alpha1
kind: Memcached
metadata:
  name: memcached-sample
spec:
  size: 3

Operator User: Deploy the Operator

Install the Custom Resource Definitions and deploy the operator:

make deploy IMG=quay.io/operator-sdk/ansible-memcached-quickstart:v0.0.0

Operator User: Create a Memcached resource

Create a Memcached resource, and let the operator do the rest.

kubectl apply -f config/samples/cache_v1alpha1_memcached.yaml

Watch it happen with the Ansible logs:

kubectl logs <pod> -c manager --namespace=kb-system

See that the Memcached pods are deployed.