Building the Operator

The SDK’s new command creates the skeleton project files for a new Operator. These files include all of the code necessary for a Kubernetes controller that invokes the appropriate Helm chart to field requests for CRs. We’ll discuss these files in greater detail later in this section.

$ OPERATOR_NAME=visitors-helm-operator
$ operator-sdk new $OPERATOR_NAME --api-version=example.com/v1 
  --kind=VisitorsApp --type=helm
INFO[0000] Creating new Helm operator 'visitors-helm-operator'.
INFO[0000] Created helm-charts/visitorsapp
INFO[0000] Generating RBAC rules
WARN[0000] The RBAC rules generated in deploy/role.yaml are based on
the chart's default manifest. Some rules may be missing for resources
that are only enabled with custom values, and some existing rules may
be overly broad. Double check the rules generated in deploy/role.yaml
to ensure they meet the operator's permission requirements.
INFO[0000] Created build/Dockerfile
INFO[0000] Created watches.yaml
INFO[0000] Created deploy/service_account.yaml
INFO[0000] Created deploy/role.yaml
INFO[0000] Created deploy/role_binding.yaml
INFO[0000] Created deploy/operator.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_crd.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_cr.yaml
INFO[0000] Project creation complete.

$ OPERATOR_NAME=visitors-helm-operator
$ wget https://github.com/kubernetes-operators-book/
  chapters/releases/download/1.0.0/visitors-helm.tgz  
$ operator-sdk new $OPERATOR_NAME --api-version=example.com/v1 
  --kind=VisitorsApp --type=helm --helm-chart=./visitors-helm.tgz
INFO[0000] Creating new Helm operator 'visitors-helm-operator'.
INFO[0000] Created helm-charts/visitors-helm
INFO[0000] Generating RBAC rules
WARN[0000] The RBAC rules generated in deploy/role.yaml are based on
the chart's default manifest. Some rules may be missing for resources
that are only enabled with custom values, and some existing rules may
be overly broad. Double check the rules generated in deploy/role.yaml
to ensure they meet the operator's permission requirements.
INFO[0000] Created build/Dockerfile
INFO[0000] Created watches.yaml
INFO[0000] Created deploy/service_account.yaml
INFO[0000] Created deploy/role.yaml
INFO[0000] Created deploy/role_binding.yaml
INFO[0000] Created deploy/operator.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_crd.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_cr.yaml
INFO[0000] Project creation complete.

$ ls -l $OPERATOR_NAME/helm-charts/visitors-helm/templates
_helpers.tpl
auth.yaml
backend-deployment.yaml
backend-service.yaml
frontend-deployment.yaml
frontend-service.yaml
mysql-deployment.yaml
mysql-service.yaml
tests

$ cat $OPERATOR_NAME/helm-charts/visitors-helm/values.yaml
backend:
  size: 1

frontend:
  title: Helm Installed Visitors Site

$ cat $OPERATOR_NAME/deploy/crds/example_v1_visitorsapp_cr.yaml
apiVersion: example.com/v1
kind: VisitorsApp
metadata:
  name: example-visitorsapp
spec:
  # Default values copied from <proj_dir>/helm-charts/visitors-helm/values.yaml

  backend:
    size: 1

  frontend:
    title: Helm Installed Visitors Site

Fleshing Out the CRD

The generated CRD does not include specific details of the value input and state values of the CR type. Appendix B describes the steps you should take to finish defining the CR.

Reviewing Operator Permissions

The generated deployment files include the role the Operator will use to connect to the Kubernetes API. By default, this role is extremely permissive. Appendix C talks about how to fine-tune the role definition to limit the Operator’s permissions.

Running the Helm Operator

An Operator is delivered as a normal container image. However, during the development and testing cycle, it is often easier to skip the image creation process and simply run the Operator outside of the cluster. In this section we describe those steps (see Appendix A for information about running the Operator as a deployment inside the cluster). Run all the commands here from within the Operator project root directory:

1. Create a local watches file. The generated watches.yaml file refers to a specific path where the Helm chart is found. This path makes sense in the deployed Operator scenario; the image creation process takes care of copying the chart to the necessary location. This watches.yaml file is still required when running the Operator outside of the cluster, so you need to manually make sure your chart can be found at that location.

   The simplest approach is to copy the existing watches.yaml file, which is located in the root of the Operator project:

   $ cp watches.yaml local-watches.yaml
   

   In the local-watches.yaml file, edit the chart field to contain the full path of the chart on your machine. Remember the name of the local watches file; you will need it later when you start the Operator process.

2. Create the CRDs in the cluster using the kubectl command:

   $ kubectl apply -f deploy/crds/*_crd.yaml
   

3. Once you have finished creating the CRDs, start the Operator using the following SDK command:

   $ operator-sdk up local --watches-file ./local-watches.yaml
   INFO[0000] Running the operator locally.
   INFO[0000] Using namespace default.  
   

   

   The Operator log messages will appear in this running process as it starts up and fields CR requests.

   This command starts a running process that behaves in the same way the Operator would if you had deployed it as a pod inside the cluster. (We’ll cover testing in more detail in “Testing an Operator”.)

Building the Operator

As with its Helm support, the Operator SDK generates a project skeleton. When run with the --type=ansible argument, the project skeleton contains the structure for a blank Ansible role. The name of the role is derived from the specified CR type name.

The following example demonstrates creating an Ansible Operator that defines a CR for the Visitors Site application:

$ OPERATOR_NAME=visitors-ansible-operator
$ operator-sdk new $OPERATOR_NAME --api-version=example.com/v1 
  --kind=VisitorsApp --type=ansible
INFO[0000] Creating new Ansible operator 'visitors-ansible-operator'.
INFO[0000] Created deploy/service_account.yaml
INFO[0000] Created deploy/role.yaml
INFO[0000] Created deploy/role_binding.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_crd.yaml
INFO[0000] Created deploy/crds/example_v1_visitorsapp_cr.yaml
INFO[0000] Created build/Dockerfile
INFO[0000] Created roles/visitorsapp/README.md
INFO[0000] Created roles/visitorsapp/meta/main.yml
INFO[0000] Created roles/visitorsapp/files/.placeholder
INFO[0000] Created roles/visitorsapp/templates/.placeholder
INFO[0000] Created roles/visitorsapp/vars/main.yml
INFO[0000] Created molecule/test-local/playbook.yml
INFO[0000] Created roles/visitorsapp/defaults/main.yml
INFO[0000] Created roles/visitorsapp/tasks/main.yml
INFO[0000] Created molecule/default/molecule.yml
INFO[0000] Created build/test-framework/Dockerfile
INFO[0000] Created molecule/test-cluster/molecule.yml
INFO[0000] Created molecule/default/prepare.yml
INFO[0000] Created molecule/default/playbook.yml
INFO[0000] Created build/test-framework/ansible-test.sh
INFO[0000] Created molecule/default/asserts.yml
INFO[0000] Created molecule/test-cluster/playbook.yml
INFO[0000] Created roles/visitorsapp/handlers/main.yml
INFO[0000] Created watches.yaml
INFO[0000] Created deploy/operator.yaml
INFO[0000] Created .travis.yml
INFO[0000] Created molecule/test-local/molecule.yml
INFO[0000] Created molecule/test-local/prepare.yml
INFO[0000] Project creation complete.

This command produces a similar directory structure to the Helm Operator example. The SDK creates a deploy directory that contains the same set of files, including the CRD and deployment template.

There are a few notable differences from the Helm Operator:

watches.yaml

• The purpose of this is the same as for the Helm Operator: it maps a CR type to the location of a file that is executed during its resolution. The Ansible Operator, however, supports two different types of files (these fields are mutually exclusive):

  • If the role field is included, it must point to the directory of an Ansible role that is executed during resource reconciliation.

  • If the playbook field is included, it must point to a playbook file that is run.

• The SDK defaults this file to point to the role it created during generation.

roles/

• This directory contains all of the Ansible roles that may be run by the Operator. The SDK generates the base files for a new role when the project is created.

• If the Operator manages multiple CR types, multiple roles are added to this directory. Additionally, an entry for each type, and its associated role, is added to the watches file.

Next, you’ll implement the Ansible role for the CR. The details of what the role does will vary depending on the application: some common tasks include the creation of deployments and services to run the application’s containers. For more on writing Ansible roles, see the Ansible documentation.

You can find the Ansible role for deploying the Visitors Site in the book’s GitHub repository. For simplicity while following along with the example application, the role files are available as a release there. Similar to the previous Operator creation command, you can add the Visitors Site role with the following:

$ cd $OPERATOR_NAME/roles/visitorsapp
$ wget https://github.com/kubernetes-operators-book/
  chapters/releases/download/1.0.0/visitors-ansible.tgz
$ tar -zxvf visitors-ansible.tgz 
$ rm visitors-ansible.tgz

This command overwrites the default generated role files with the files necessary to run the Visitors Site role.

We don’t cover writing Ansible roles in this book, but it’s important for you to understand how user-entered configuration values are propagated into an Ansible role.

As with the Helm Operator, configuration values come from the CR’s spec section. However, within the playbooks and roles, Ansible’s standard {{ variable_name }} syntax is used. Field names in Kubernetes typically use camel case (e.g., camelCase), so the Ansible Operator will convert the name of each field to snake case (e.g., snake_case) before passing the parameter to the Ansible role. That is, the field name serviceAccount would be converted to service_account. This allows the reuse of existing roles using the standard Ansible convention while also honoring the Kubernetes resource conventions. You can find the source for an Ansible role that deploys the Visitors Site in the book’s GitHub repository.

Fleshing Out the CRD

As with the Helm Operator, you’ll need to expand on the generated CRD to include the specifics of your CR. Consult Appendix B for more information.

Reviewing Operator Permissions

The Ansible Operator also includes a generated role the Operator uses to connect to the Kubernetes API. Check Appendix C for more on refining the default permissions.

Running the Ansible Operator

As with the Helm Operator, the easiest way to test and debug an Ansible Operator is to run it outside a cluster, avoiding the steps of building and pushing an image.

Before you can do this, however, there are a few extra steps you need to take:

1. First, install Ansible on the machine running the Operator. Consult the Ansible documentation for specifics on how to install Ansible on your local OS.

2. Additional Ansible-related packages must be installed as well, including the following (consult the documentation for details on installation):

   • Ansible Runner

   • Ansible Runner HTTP Event Emitter

3. As with the Helm Operator, the watches.yaml file generated by the SDK refers to a specific directory for the Ansible role. So you’ll copy the watches file and modify it as necessary. Again, run these commands from within the Operator project root directory:

   $ cp watches.yaml local-watches.yaml
   

   In the local-watches.yaml file, change the role field to reflect the directory structure on your machine.

4. Create the CRDs in the cluster using the kubectl command:

   $ kubectl apply -f deploy/crds/*_crd.yaml
   

5. Once the CRDs are deployed in the cluster, run the Operator using the SDK:

   $ operator-sdk up local --watches-file ./local-watches.yaml
   INFO[0000] Running the operator locally.
   INFO[0000] Using namespace default.  
   

   

   The Operator log messages will appear in this running process as it starts up and fields CR requests.

   This command starts a running process that behaves as the Operator would if it was deployed as a pod inside the cluster.

Now let’s walk through the steps of how to test an Operator.