diff --git a/website/content/en/docs/building-operators/ansible/development-tips.md b/website/content/en/docs/building-operators/ansible/development-tips.md index 7d377b3f7c..6f1e836386 100644 --- a/website/content/en/docs/building-operators/ansible/development-tips.md +++ b/website/content/en/docs/building-operators/ansible/development-tips.md @@ -454,8 +454,8 @@ its reconciliation procedure. There are only a few main conditions: Please look over the following sections for help debugging an Ansible Operator: -* [View the Ansible logs](../quickstart#view-the-ansible-logs) -* [Additional Ansible debug](../quickstart#additional-ansible-debug) +* [View the Ansible logs](../tutorial#view-the-ansible-logs) +* [Additional Ansible debug](../tutorial#additional-ansible-debug) * [Testing Ansible Operators with Molecule](../testing-guide) ## Extra vars sent to Ansible @@ -505,7 +505,7 @@ operator. The `meta` fields can be accesses via dot notation in Ansible as so: [k8s_ansible_module]:https://docs.ansible.com/ansible/2.6/modules/k8s_module.html [openshift_restclient_python]:https://github.com/openshift/openshift-restclient-python -[ansible_operator_user_guide]:../quickstart +[ansible_operator_user_guide]:../tutorial [manage_status_proposal]:../../proposals/ansible-operator-status.md [time_pkg]:https://golang.org/pkg/time/ [time_parse_duration]:https://golang.org/pkg/time/#ParseDuration diff --git a/website/content/en/docs/building-operators/ansible/quickstart.md b/website/content/en/docs/building-operators/ansible/quickstart.md index 19f0106457..9348677396 100644 --- a/website/content/en/docs/building-operators/ansible/quickstart.md +++ b/website/content/en/docs/building-operators/ansible/quickstart.md @@ -1,381 +1,96 @@ --- -title: Ansible Operator Quickstart -linkTitle: Quickstart +title: Ansible Operator QuickStart +linkTitle: QuickStart weight: 2 --- +## Prerequisites -This guide walks through an example of building a simple memcached-operator powered by Ansible using tools and libraries provided by the Operator SDK. +- [docker][docker_tool] version 17.03+. +- [kubectl][kubectl_tool] version v1.11.3+. +- [operator-sdk][operator_install] v1.0.0+ +- Access to a Kubernetes v1.11.3+ cluster. -## Create a new project - -After [installing the Operator SDK CLI][install-guide] and -[ansible operator prerequisites][ansible-install-guide], use the CLI to create a -new Ansible-based memcached-operator project: +## Creating a Project +Create a directory, and then run the init command inside of it to generate a new project. + ```sh -$ operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached --type=ansible -$ cd memcached-operator -``` - -This creates the memcached-operator project specifically for watching the -Memcached resource with APIVersion `cache.example.com/v1apha1` and Kind -`Memcached`. - -To learn more about the project directory structure, see [project -layout][layout-doc] doc. - -#### Operator scope - -Read the [operator scope][operator-scope] documentation on how to run your operator as namespace-scoped vs cluster-scoped. - -## Customize the operator logic - -For this example the memcached-operator will execute the following -reconciliation logic for each `Memcached` Custom Resource (CR): -- Create a memcached Deployment if it doesn't exist -- Ensure that the Deployment size is the same as specified by the `Memcached` -CR - -## Watch the Memcached CR - -By default, the memcached-operator watches `Memcached` resource events as shown -in `watches.yaml` and executes Ansible Role `Memcached`: - -```yaml ---- -- version: v1alpha1 - group: cache.example.com - kind: Memcached -``` - - -#### Options - -**Role** -Specifying a `role` option in `watches.yaml` will configure the operator to use -this specified path when launching `ansible-runner` with an Ansible Role. By -default, the `new` command will fill in an absolute path to where your role -should go. -```yaml ---- -- version: v1alpha1 - group: cache.example.com - kind: Memcached - role: memcached -``` - -**Playbook** -Specifying a `playbook` option in `watches.yaml` will configure the operator to -use this specified path when launching `ansible-runner` with an Ansible -Playbook -```yaml ---- -- version: v1alpha1 - group: cache.example.com - kind: Memcached - playbook: playbook.yaml +$ mkdir $GOPATH/src/memcached-operator +$ cd $GOPATH/src/memcached-operator +$ operator-sdk init --plugins=ansible ``` -See [watches reference][ansible-watches] for more information. +## Creating an API -## Building the Memcached Ansible Role - -The first thing to do is to modify the generated Ansible role under -`roles/memcached`. This Ansible Role controls the logic that is executed when a -resource is modified. - -### Define the Memcached spec - -Defining the spec for an Ansible Operator can be done entirely in Ansible. The -Ansible Operator will simply pass all key value pairs listed in the Custom -Resource spec field along to Ansible as extra -[variables](https://docs.ansible.com/ansible/2.5/user_guide/playbooks_variables.html#passing-variables-on-the-command-line). -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. - -First, set a default in case the user doesn't set the `spec` field by modifying -`roles/memcached/defaults/main.yml`: -```yaml -size: 1 -``` - -### Defining the Memcached deployment - -Now that we have the spec defined, we can define what Ansible is actually -executed on resource changes. Since this is an Ansible Role, the default -behavior will be to execute the tasks in `roles/memcached/tasks/main.yml`. We -want Ansible to create a deployment if it does not exist which runs the -`memcached:1.4.36-alpine` image. Ansible 2.5+ supports the [k8s Ansible -Module](https://docs.ansible.com/ansible/2.6/modules/k8s_module.html) which we -will leverage to control the deployment definition. - -Modify `roles/memcached/tasks/main.yml` to look like the following: -```yaml ---- -- 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 - -``` - -It is important to note that we used the `size` variable to control how many -replicas of the Memcached deployment we want. We set the default to `1`, but -any user can create a Custom Resource that overwrites the default. - -### Build and run the operator - -Before running the operator, Kubernetes needs to know about the new custom -resource definition the operator will be watching. - -Deploy the CRD: +Let's create a new API with a default role for it: ```sh -$ kubectl create -f deploy/crds/cache.example.com_memcacheds_crd.yaml +$ operator-sdk create api --group cache --version v1 --kind Memcached --generate-role ``` -Once this is done, there are two ways to run the operator: +## Applying the CRDs into the cluster: -- As a pod inside a Kubernetes cluster -- As a go program outside the cluster using `operator-sdk` - -#### 1. Run as a pod inside a Kubernetes cluster - -Running as a pod inside a Kubernetes cluster is preferred for production use. - -Build the memcached-operator image and push it to a registry: -``` -$ operator-sdk build quay.io/example/memcached-operator:v0.0.1 -$ docker push quay.io/example/memcached-operator:v0.0.1 -``` - -Kubernetes deployment manifests are generated in `deploy/operator.yaml`. The -deployment image in this file needs to be modified from the placeholder -`REPLACE_IMAGE` to the previous built image. To do this run: -``` -$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml -``` - -**Note** -If you are performing these steps on OSX, use the following `sed` commands instead: -``` -$ sed -i "" 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml -``` - -Deploy the memcached-operator: +To apply the `Memcached` Kind(CRD): ```sh -$ kubectl create -f deploy/service_account.yaml -$ kubectl create -f deploy/role.yaml -$ kubectl create -f deploy/role_binding.yaml -$ kubectl create -f deploy/operator.yaml +$ make install ``` -Verify that the memcached-operator is up and running: - -```sh -$ kubectl get deployment -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -memcached-operator 1 1 1 1 1m -``` - -#### 2. Run outside the cluster - -This method is preferred during the development cycle to speed up deployment and testing. - -**Note**: Ensure that [Ansible Runner][ansible-runner-tool] and [Ansible Runner -HTTP Plugin][ansible-runner-http-plugin] is installed or else you will see -unexpected errors from Ansible Runner when a Custom Resource is created. - -It is also important that the `role` path referenced in `watches.yaml` exists -on your machine. Since we are normally used to using a container where the Role -is put on disk for us, we need to manually copy our role to the configured -Ansible Roles path (e.g `/etc/ansible/roles`. - -Run the operator locally with the default Kubernetes config file present at -`$HOME/.kube/config`: - -```sh -$ operator-sdk run local -INFO[0000] Go Version: go1.10 -INFO[0000] Go OS/Arch: darwin/amd64 -INFO[0000] operator-sdk Version: 0.0.5+git -``` +## Running it locally -Run the operator locally with a provided Kubernetes config file: +To run the project out of the cluster: ```sh -$ operator-sdk run local --kubeconfig=config -INFO[0000] Go Version: go1.10 -INFO[0000] Go OS/Arch: darwin/amd64 -INFO[0000] operator-sdk Version: 0.0.5+git +$ make run ``` -### 3. Deploy your Operator with the Operator Lifecycle Manager (OLM) +## Building and Pushing the Project Image -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 -[user guide][quickstart-bundle] for more information. - -### Create a Memcached CR - -Modify `deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml` as shown and create a `Memcached` custom resource: +To build and push your image to your repository : ```sh -$ cat deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" -spec: - size: 3 - -$ kubectl apply -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +$ make docker-build docker-push IMG=/:tag ``` -Ensure that the memcached-operator creates the deployment for the CR: +**Note** To allow the cluster pull the image the repository needs to be set as public. -```sh -$ kubectl get deployment -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -memcached-operator 1 1 1 1 2m -example-memcached 3 3 3 3 1m -``` +## Running it on Cluster -Check the pods to confirm 3 replicas were created: +Deploy the project to the cluster: ```sh -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-memcached-6fd7c98d8-7dqdr 1/1 Running 0 1m -example-memcached-6fd7c98d8-g5k7v 1/1 Running 0 1m -example-memcached-6fd7c98d8-m7vn7 1/1 Running 0 1m -memcached-operator-7cc7cfdf86-vvjqk 2/2 Running 0 2m +$ make deploy IMG=/:tag ``` -### View the Ansible logs +## Applying the CR's into the cluster: -In order to see the logs from a particular you can run: +To create instances (CR's) of the `Memcached` Kind (CRD) in the same namespaced of the operator ```sh -kubectl logs deployment/memcached-operator -``` - -The logs contain the information about the Ansible run and will make it much easier to debug issues within your Ansible tasks. -Note that the logs will contain much more detailed information about the Ansible Operator's internals and interface with Kubernetes as well. - -Also, you can use the environment variable `ANSIBLE_DEBUG_LOGS` set as `True` to check the full Ansible result in the logs in order to be able to debug it. - -**Example** - -In the `deploy/operator.yaml`: -```yaml -... -- name: ANSIBLE_DEBUG_LOGS - value: "True" -... +$ kubectl apply -f config/samples/cache_v1alpha1_memcached.yaml -n memcached-operator-system ``` -### Additional Ansible Debug +## Uninstall CRDs -Occasionally while developing additional debug in the Operator logs is nice to have. -Using the memcached operator as an example, we can simply add the -`"ansible.sdk.operatorframework.io/verbosity"` annotation to the Custom -Resource with the desired verbosity. - -```yaml -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" - annotations: - "ansible.sdk.operatorframework.io/verbosity": "4" -spec: - size: 4 -``` - -### Update the size - -Change the `spec.size` field in the memcached CR from 3 to 4 and apply the -change: +To delete your CRDs from the cluster: ```sh -$ cat deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" -spec: - size: 4 - -$ kubectl apply -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +$ make uninstall ``` -Confirm that the operator changes the deployment size: +## Undeploy Project ```sh -$ kubectl get deployment -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -example-memcached 4 4 4 4 5m +$ make undeploy ``` -### Cleanup - -Clean up the resources: - -```sh -$ kubectl delete -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml -$ kubectl delete -f deploy/operator.yaml -$ kubectl delete -f deploy/role_binding.yaml -$ kubectl delete -f deploy/role.yaml -$ kubectl delete -f deploy/service_account.yaml -$ kubectl delete -f deploy/crds/cache.example.com_memcacheds_crd.yaml -``` +## Next Step -**NOTE** Additional CR/CRD's can be added to the project by running, for example, the command :`operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=AppService` -For more information, refer [cli][addcli] doc. +Now, follow up the [Tutorial][tutorial] to better understand how it works by developing a demo project. -[ansible-install-guide]: /docs/building-operators/ansible/installation -[ansible-runner-http-plugin]:https://github.com/ansible/ansible-runner-http -[ansible-runner-tool]: https://ansible-runner.readthedocs.io/en/latest/install.html -[ansible-watches]: /docs/building-operators/ansible/reference/watches -[operator-scope]:https://v0-19-x.sdk.operatorframework.io/docs/legacy-common/operator-scope/ -[layout-doc]:../reference/scaffolding -[homebrew-tool]:https://brew.sh/ -[install-guide]: /docs/installation/install-operator-sdk -[git-tool]:https://git-scm.com/downloads -[go-tool]:https://golang.org/dl/ -[docker-tool]:https://docs.docker.com/install/ -[kubectl-tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ - -[addcli]: https://v0-19-x.sdk.operatorframework.io/docs/cli/operator-sdk_add_api -[quickstart-bundle]:https://v0-19-x.sdk.operatorframework.io/docs/olm-integration/legacy/quickstart-bundle/ +[docker_tool]:https://docs.docker.com/install/ +[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[operator_install]: /docs/installation/install-operator-sdk +[helm-repo-add]: https://helm.sh/docs/helm/helm_repo_add +[helm-chart-memcached]: https://github.com/helm/charts/tree/master/stable/memcached +[tutorial]: /docs/building-operators/ansible/tutorial/ \ No newline at end of file diff --git a/website/content/en/docs/building-operators/ansible/testing-guide.md b/website/content/en/docs/building-operators/ansible/testing-guide.md index daa0510990..357577aabb 100644 --- a/website/content/en/docs/building-operators/ansible/testing-guide.md +++ b/website/content/en/docs/building-operators/ansible/testing-guide.md @@ -1,7 +1,7 @@ --- title: Ansible Based Operator Testing with Molecule linkTitle: Testing with Molecule -weight: 4 +weight: 5 --- ## Getting started diff --git a/website/content/en/docs/building-operators/ansible/tutorial.md b/website/content/en/docs/building-operators/ansible/tutorial.md new file mode 100644 index 0000000000..b4e38ae249 --- /dev/null +++ b/website/content/en/docs/building-operators/ansible/tutorial.md @@ -0,0 +1,381 @@ +--- +title: Ansible Operator Tutorial +linkTitle: Tutorial +weight: 3 +--- + +This guide walks through an example of building a simple memcached-operator powered by Ansible using tools and libraries provided by the Operator SDK. + +## Create a new project + +After [installing the Operator SDK CLI][install-guide] and +[ansible operator prerequisites][ansible-install-guide], use the CLI to create a +new Ansible-based memcached-operator project: + +```sh +$ operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached --type=ansible +$ cd memcached-operator +``` + +This creates the memcached-operator project specifically for watching the +Memcached resource with APIVersion `cache.example.com/v1apha1` and Kind +`Memcached`. + +To learn more about the project directory structure, see [project +layout][layout-doc] doc. + +#### Operator scope + +Read the [operator scope][operator-scope] documentation on how to run your operator as namespace-scoped vs cluster-scoped. + +## Customize the operator logic + +For this example the memcached-operator will execute the following +reconciliation logic for each `Memcached` Custom Resource (CR): +- Create a memcached Deployment if it doesn't exist +- Ensure that the Deployment size is the same as specified by the `Memcached` +CR + +## Watch the Memcached CR + +By default, the memcached-operator watches `Memcached` resource events as shown +in `watches.yaml` and executes Ansible Role `Memcached`: + +```yaml +--- +- version: v1alpha1 + group: cache.example.com + kind: Memcached +``` + + +#### Options + +**Role** +Specifying a `role` option in `watches.yaml` will configure the operator to use +this specified path when launching `ansible-runner` with an Ansible Role. By +default, the `new` command will fill in an absolute path to where your role +should go. +```yaml +--- +- version: v1alpha1 + group: cache.example.com + kind: Memcached + role: memcached +``` + +**Playbook** +Specifying a `playbook` option in `watches.yaml` will configure the operator to +use this specified path when launching `ansible-runner` with an Ansible +Playbook +```yaml +--- +- version: v1alpha1 + group: cache.example.com + kind: Memcached + playbook: playbook.yaml +``` + +See [watches reference][ansible-watches] for more information. + +## Building the Memcached Ansible Role + +The first thing to do is to modify the generated Ansible role under +`roles/memcached`. This Ansible Role controls the logic that is executed when a +resource is modified. + +### Define the Memcached spec + +Defining the spec for an Ansible Operator can be done entirely in Ansible. The +Ansible Operator will simply pass all key value pairs listed in the Custom +Resource spec field along to Ansible as extra +[variables](https://docs.ansible.com/ansible/2.5/user_guide/playbooks_variables.html#passing-variables-on-the-command-line). +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. + +First, set a default in case the user doesn't set the `spec` field by modifying +`roles/memcached/defaults/main.yml`: +```yaml +size: 1 +``` + +### Defining the Memcached deployment + +Now that we have the spec defined, we can define what Ansible is actually +executed on resource changes. Since this is an Ansible Role, the default +behavior will be to execute the tasks in `roles/memcached/tasks/main.yml`. We +want Ansible to create a deployment if it does not exist which runs the +`memcached:1.4.36-alpine` image. Ansible 2.5+ supports the [k8s Ansible +Module](https://docs.ansible.com/ansible/2.6/modules/k8s_module.html) which we +will leverage to control the deployment definition. + +Modify `roles/memcached/tasks/main.yml` to look like the following: +```yaml +--- +- 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 + +``` + +It is important to note that we used the `size` variable to control how many +replicas of the Memcached deployment we want. We set the default to `1`, but +any user can create a Custom Resource that overwrites the default. + +### Build and run the operator + +Before running the operator, Kubernetes needs to know about the new custom +resource definition the operator will be watching. + +Deploy the CRD: + +```sh +$ kubectl create -f deploy/crds/cache.example.com_memcacheds_crd.yaml +``` + +Once this is done, there are two ways to run the operator: + +- As a pod inside a Kubernetes cluster +- As a go program outside the cluster using `operator-sdk` + +#### 1. Run as a pod inside a Kubernetes cluster + +Running as a pod inside a Kubernetes cluster is preferred for production use. + +Build the memcached-operator image and push it to a registry: +``` +$ operator-sdk build quay.io/example/memcached-operator:v0.0.1 +$ docker push quay.io/example/memcached-operator:v0.0.1 +``` + +Kubernetes deployment manifests are generated in `deploy/operator.yaml`. The +deployment image in this file needs to be modified from the placeholder +`REPLACE_IMAGE` to the previous built image. To do this run: +``` +$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml +``` + +**Note** +If you are performing these steps on OSX, use the following `sed` commands instead: +``` +$ sed -i "" 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml +``` + +Deploy the memcached-operator: + +```sh +$ kubectl create -f deploy/service_account.yaml +$ kubectl create -f deploy/role.yaml +$ kubectl create -f deploy/role_binding.yaml +$ kubectl create -f deploy/operator.yaml +``` + +Verify that the memcached-operator is up and running: + +```sh +$ kubectl get deployment +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +memcached-operator 1 1 1 1 1m +``` + +#### 2. Run outside the cluster + +This method is preferred during the development cycle to speed up deployment and testing. + +**Note**: Ensure that [Ansible Runner][ansible-runner-tool] and [Ansible Runner +HTTP Plugin][ansible-runner-http-plugin] is installed or else you will see +unexpected errors from Ansible Runner when a Custom Resource is created. + +It is also important that the `role` path referenced in `watches.yaml` exists +on your machine. Since we are normally used to using a container where the Role +is put on disk for us, we need to manually copy our role to the configured +Ansible Roles path (e.g `/etc/ansible/roles`. + +Run the operator locally with the default Kubernetes config file present at +`$HOME/.kube/config`: + +```sh +$ operator-sdk run local +INFO[0000] Go Version: go1.10 +INFO[0000] Go OS/Arch: darwin/amd64 +INFO[0000] operator-sdk Version: 0.0.5+git +``` + +Run the operator locally with a provided Kubernetes config file: + +```sh +$ operator-sdk run local --kubeconfig=config +INFO[0000] Go Version: go1.10 +INFO[0000] Go OS/Arch: darwin/amd64 +INFO[0000] operator-sdk Version: 0.0.5+git +``` + +### 3. Deploy your Operator with the Operator Lifecycle Manager (OLM) + +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 +[user guide][quickstart-bundle] for more information. + +### Create a Memcached CR + +Modify `deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml` as shown and create a `Memcached` custom resource: + +```sh +$ cat deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +apiVersion: "cache.example.com/v1alpha1" +kind: "Memcached" +metadata: + name: "example-memcached" +spec: + size: 3 + +$ kubectl apply -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +``` + +Ensure that the memcached-operator creates the deployment for the CR: + +```sh +$ kubectl get deployment +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +memcached-operator 1 1 1 1 2m +example-memcached 3 3 3 3 1m +``` + +Check the pods to confirm 3 replicas were created: + +```sh +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +example-memcached-6fd7c98d8-7dqdr 1/1 Running 0 1m +example-memcached-6fd7c98d8-g5k7v 1/1 Running 0 1m +example-memcached-6fd7c98d8-m7vn7 1/1 Running 0 1m +memcached-operator-7cc7cfdf86-vvjqk 2/2 Running 0 2m +``` + +### View the Ansible logs + +In order to see the logs from a particular you can run: + +```sh +kubectl logs deployment/memcached-operator +``` + +The logs contain the information about the Ansible run and will make it much easier to debug issues within your Ansible tasks. +Note that the logs will contain much more detailed information about the Ansible Operator's internals and interface with Kubernetes as well. + +Also, you can use the environment variable `ANSIBLE_DEBUG_LOGS` set as `True` to check the full Ansible result in the logs in order to be able to debug it. + +**Example** + +In the `deploy/operator.yaml`: +```yaml +... +- name: ANSIBLE_DEBUG_LOGS + value: "True" +... +``` + +### Additional Ansible Debug + +Occasionally while developing additional debug in the Operator logs is nice to have. +Using the memcached operator as an example, we can simply add the +`"ansible.sdk.operatorframework.io/verbosity"` annotation to the Custom +Resource with the desired verbosity. + +```yaml +apiVersion: "cache.example.com/v1alpha1" +kind: "Memcached" +metadata: + name: "example-memcached" + annotations: + "ansible.sdk.operatorframework.io/verbosity": "4" +spec: + size: 4 +``` + +### Update the size + +Change the `spec.size` field in the memcached CR from 3 to 4 and apply the +change: + +```sh +$ cat deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +apiVersion: "cache.example.com/v1alpha1" +kind: "Memcached" +metadata: + name: "example-memcached" +spec: + size: 4 + +$ kubectl apply -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +``` + +Confirm that the operator changes the deployment size: + +```sh +$ kubectl get deployment +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +example-memcached 4 4 4 4 5m +``` + +### Cleanup + +Clean up the resources: + +```sh +$ kubectl delete -f deploy/crds/cache.example.com_v1alpha1_memcached_cr.yaml +$ kubectl delete -f deploy/operator.yaml +$ kubectl delete -f deploy/role_binding.yaml +$ kubectl delete -f deploy/role.yaml +$ kubectl delete -f deploy/service_account.yaml +$ kubectl delete -f deploy/crds/cache.example.com_memcacheds_crd.yaml +``` + +**NOTE** Additional CR/CRD's can be added to the project by running, for example, the command :`operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=AppService` +For more information, refer [cli][addcli] doc. + +[ansible-install-guide]: /docs/building-operators/ansible/installation +[ansible-runner-http-plugin]:https://github.com/ansible/ansible-runner-http +[ansible-runner-tool]: https://ansible-runner.readthedocs.io/en/latest/install.html +[ansible-watches]: /docs/building-operators/ansible/reference/watches +[operator-scope]:https://v0-19-x.sdk.operatorframework.io/docs/legacy-common/operator-scope/ +[layout-doc]:../reference/scaffolding +[homebrew-tool]:https://brew.sh/ +[install-guide]: /docs/installation/install-operator-sdk +[git-tool]:https://git-scm.com/downloads +[go-tool]:https://golang.org/dl/ +[docker-tool]:https://docs.docker.com/install/ +[kubectl-tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ + +[addcli]: https://v0-19-x.sdk.operatorframework.io/docs/cli/operator-sdk_add_api +[quickstart-bundle]:https://v0-19-x.sdk.operatorframework.io/docs/olm-integration/legacy/quickstart-bundle/