docs: Add a user guide for using an Ansible Operator #559

dymurray · 2018-10-02T16:55:09Z

Sdk-cli-reference updates
Ansible Operator User Guide
Ansible Operator Project Layout
Include link to Ansible Operator user guide from top level user guide

openshift-ci-robot · 2018-10-02T16:55:23Z

Hi @dymurray. Thanks for your PR.

I'm waiting for a operator-framework member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

doc/ansible/user-guide.md

leifmadsen

General comment: please wrap text to 80 chars

leifmadsen · 2018-10-02T17:47:54Z

doc/ansible/user-guide.md

+
+## Customize the operator logic
+
+For this example the memcached-operator will execute the following reconciliation logic for each `Memcached` CR:


Could you call out CR fully? (custom resource?)

leifmadsen · 2018-10-02T17:48:17Z

doc/ansible/user-guide.md

+
+For this example the memcached-operator will execute the following reconciliation logic for each `Memcached` CR:
+- Create a memcached Deployment if it doesn't exist
+- Ensure that the Deployment size is the same as specified by the `Memcached` CR spec


s/CR spec/CRD?

This actually refers to the spec field on the Custom Resource. I will remove spec for simplicity.

doc/ansible/user-guide.md

leifmadsen · 2018-10-02T17:52:08Z

doc/ansible/user-guide.md

+
+Once this is done, there are two ways to run the operator:
+
+- As pod inside Kubernetes cluster


As a pod inside a Kubernetes cluster

leifmadsen · 2018-10-02T17:52:46Z

doc/ansible/user-guide.md

+Once this is done, there are two ways to run the operator:
+
+- As pod inside Kubernetes cluster
+- As go program outside cluster using `operator-sdk`


As a Go program outside the cluster...

leifmadsen · 2018-10-02T17:52:59Z

doc/ansible/user-guide.md

+- As pod inside Kubernetes cluster
+- As go program outside cluster using `operator-sdk`
+
+#### 1. Run as pod inside a Kubernetes cluster


Run as a pod...

leifmadsen · 2018-10-02T17:53:10Z

doc/ansible/user-guide.md

+
+#### 1. Run as pod inside a Kubernetes cluster
+
+Run as pod inside a Kubernetes cluster is preferred for production use.


Running as a pod ...

leifmadsen · 2018-10-02T17:54:18Z

doc/ansible/user-guide.md

+
+#### 2. Run outside the cluster
+
+This method is preferred during development cycle to deploy and test faster.


This method is preferred during the development cycle to speed up deployment and testing.

leifmadsen · 2018-10-02T17:55:24Z

doc/ansible/user-guide.md

+spec:
+  size: 4
+
+$ kubectl apply -f deploy/cr.yaml


You could just use the kubectl patch command here to make things simpler I think?

In the user-guide that is at the top-level they seem to suggest using apply. Any idea what the advantages using kubectl patch provides?

leifmadsen · 2018-10-02T17:59:01Z

Depends on #486

dymurray · 2018-10-03T15:47:22Z

Also depends on: #565

johnkim76 · 2018-10-04T07:25:14Z

doc/ansible/user-guide.md

+Build the memcached-operator image and push it to a registry:
+```
+$ operator-sdk build quay.io/example/memcached-operator:v0.0.1
+$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml


NIT @dymurray I was thinking it may be better if this step was done just before doing the kubectl create -f deploy/operator.yam below, with a short description of what and why it's being done.

dymurray · 2018-10-04T19:48:26Z

I have no idea why Travis is failing... it can't be related to my documentation changes so must be transient. I'm unsure how to kick off a rebuild.

AlexNPavel · 2018-10-04T19:51:28Z

Due to the way that travis and github handle merging for tests, there's currently an issue where if your branch is behind the master, that could cause the tests to fail (depending on what has changed). I merged a change to the test framework yesterday, so that's out of sync now. To fix this, rebase your branch to the latest master, or merge the latest master into your branch.

hasbro17 · 2018-10-04T21:15:11Z

@dymurray It's not related to your changes. Currently the e2e tests have to vendor the SDK from the contributor's PR branch so that any transitive dependencies from changing the core SDK pkgs are resolved by dep as well. This is a workaround for dep's inability to source from local repos.
#522 (comment)
#525

Since it's just doc changes we can technically disregard the CI but I think you should be able to rebase from the master as well.

mhrivnak

I made some minor suggestions, but this looks great!

One other suggestion, that I think someone else already made: It's maybe a matter of preference, but I find it much easier to edit markdown that has a reasonably-limited line length. 80 characters is fine, especially since it's a default for vim. Speaking of, here's how I do the wrapping super-quickly:

highlight several lines by hitting V followed by appropriate up or down keys
hit gq to auto-wrap. Vim does a nice job of it, and it even handles inline code comments well.

mhrivnak · 2018-10-05T02:40:49Z

doc/ansible/user-guide.md

+
+#### 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. This is the default.


re: "This is the default", I think it would help to be more specific and say something like "By default, the new command will fill in an absolute path to where your role should go." That helps clarify that "default" does not imply that there is a default value in case role is left empty in this file.

mhrivnak · 2018-10-05T02:48:10Z

doc/ansible/user-guide.md

+
+```
+
+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 which overwrites the default.


Add a comma before "but" since there are two independent clauses.

Also s/which/that/ since the ending clause is important to the meaning of the sentence.

mhrivnak · 2018-10-05T02:48:57Z

doc/ansible/user-guide.md

+Once this is done, there are two ways to run the operator:
+
+- As a pod inside a Kubernetes cluster
+- As a go program outside cluster using `operator-sdk`


s/cluster/the cluster/

mhrivnak · 2018-10-05T03:01:00Z

doc/user-guide.md

@@ -2,6 +2,8 @@

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

+This guide covers the workflow of creating and deploying an operator written in Go. To read about the Ansible Operator, see the [Ansible Operator User Guide][ansible_user_guide]. 


I would put the word "Ansible" as close as possible to the beginning of the paragraph for people who are visually scanning the document for this section and link. Also as we discussed earlier today, it might be better to avoid calling it the "Ansible Operator". Maybe:

"To learn how to use Ansible to create a memcached operator, see [Ansible Operator User Guide][ansible_user_guide]. The rest of this document will show how to program an operator in Go."

dymurray · 2018-10-05T13:05:57Z

Thanks a lot for that information about Travis @hasbro17 and @AlexNPavel. And thank you for reviewing @mhrivnak that was great feedback. I had no idea about that autowrap feature in vim that is awesome!

mhrivnak · 2018-10-05T14:48:27Z

doc/ansible/user-guide.md

+              - -o
+              - modern
+              - -v
+              image: "memcached:1.4.36-alpine"


Sorry, one more thing. This should be fully qualified so it will work with non-docker runtimes. I think just prefixing it with docker.io/ will work.

openshift-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 2, 2018

dymurray changed the title ~~Add a user guide for using an Ansible Operator~~ [WIP] Add a user guide for using an Ansible Operator Oct 2, 2018

openshift-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 2, 2018

leifmadsen reviewed Oct 2, 2018

View reviewed changes

doc/ansible/user-guide.md Show resolved Hide resolved

leifmadsen reviewed Oct 2, 2018

View reviewed changes

shawn-hurley added the language/ansible Issue is related to an Ansible operator project label Oct 2, 2018

dymurray changed the title ~~[WIP] Add a user guide for using an Ansible Operator~~ Add a user guide for using an Ansible Operator Oct 3, 2018

openshift-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 3, 2018

dymurray changed the title ~~Add a user guide for using an Ansible Operator~~ docs: Add a user guide for using an Ansible Operator Oct 3, 2018

johnkim76 reviewed Oct 4, 2018

View reviewed changes

mhrivnak suggested changes Oct 5, 2018

View reviewed changes

dymurray added 12 commits October 5, 2018 08:55

Add Ansible Operator documentation

2c1f288

Add deployment information

8e0de94

Project layout page

236ca56

Update project layout

1fa2ec5

Some small updates

9ee9cf4

Add link to Ansible guide from main user guide

f1e33d2

Update link

c92390e

Add CLI reference commands

6ce99eb

Fix ansible typo

b7d900f

Mention modifying rbac.yaml

419ecde

Include ansible-runner information

a1c1e37

Add some changes for up local

3893001

Enforce 80 char limit and grammar updates

04c6410

dymurray force-pushed the userguide branch from ae3e52b to 04c6410 Compare October 5, 2018 13:04

mhrivnak approved these changes Oct 5, 2018

View reviewed changes

mhrivnak suggested changes Oct 5, 2018

View reviewed changes

Fully qualify image name

9dc7206

mhrivnak approved these changes Oct 5, 2018

View reviewed changes

shawn-hurley approved these changes Oct 8, 2018

View reviewed changes

shawn-hurley merged commit b5dbae5 into operator-framework:master Oct 8, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add a user guide for using an Ansible Operator #559

docs: Add a user guide for using an Ansible Operator #559

dymurray commented Oct 2, 2018 •

edited

Loading

openshift-ci-robot commented Oct 2, 2018

leifmadsen left a comment

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

dymurray Oct 2, 2018

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

leifmadsen Oct 2, 2018

dymurray Oct 2, 2018 •

edited

Loading

leifmadsen commented Oct 2, 2018

dymurray commented Oct 3, 2018

johnkim76 Oct 4, 2018

dymurray commented Oct 4, 2018

AlexNPavel commented Oct 4, 2018

hasbro17 commented Oct 4, 2018

mhrivnak left a comment

mhrivnak Oct 5, 2018

mhrivnak Oct 5, 2018

mhrivnak Oct 5, 2018

mhrivnak Oct 5, 2018

dymurray commented Oct 5, 2018

mhrivnak Oct 5, 2018

dymurray Oct 5, 2018


		## Customize the operator logic

		For this example the memcached-operator will execute the following reconciliation logic for each `Memcached` CR:


		Once this is done, there are two ways to run the operator:

		- As pod inside Kubernetes cluster


		#### 1. Run as pod inside a Kubernetes cluster

		Run as pod inside a Kubernetes cluster is preferred for production use.


		#### 2. Run outside the cluster

		This method is preferred during development cycle to deploy and test faster.


		```

		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 which overwrites the default.

		@@ -2,6 +2,8 @@

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

		This guide covers the workflow of creating and deploying an operator written in Go. To read about the Ansible Operator, see the [Ansible Operator User Guide][ansible_user_guide].

docs: Add a user guide for using an Ansible Operator #559

docs: Add a user guide for using an Ansible Operator #559

Conversation

dymurray commented Oct 2, 2018 • edited Loading

openshift-ci-robot commented Oct 2, 2018

leifmadsen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dymurray Oct 2, 2018 • edited Loading

Choose a reason for hiding this comment

leifmadsen commented Oct 2, 2018

dymurray commented Oct 3, 2018

Choose a reason for hiding this comment

dymurray commented Oct 4, 2018

AlexNPavel commented Oct 4, 2018

hasbro17 commented Oct 4, 2018

mhrivnak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dymurray commented Oct 5, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dymurray commented Oct 2, 2018 •

edited

Loading

dymurray Oct 2, 2018 •

edited

Loading