docs: Doc edits to readme for tasks and ref section #194

artberger · 2020-09-10T22:22:51Z

Part of a general doc sweep of existing content.

Revised readme for grammar, IBM Style
Updated TOC and back to top
Made more task-oriented
Move around some content into a reference section on the page
Still want to think about presenting some of the info more up top

Signed-off-by: Art Berger [email protected]

codecov · 2020-09-10T22:27:43Z

Codecov Report

Merging #194 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #194   +/-   ##
=======================================
  Coverage   91.11%   91.11%           
=======================================
  Files           6        6           
  Lines         754      754           
=======================================
  Hits          687      687           
  Misses         44       44           
  Partials       23       23

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bbe6ddf...ad83f38. Read the comment docs.

README.md

Signed-off-by: Art Berger <[email protected]>

* Add unit tests for service controller * Add more tests for CF services * Add "make test-fast" for quicker local testing Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

…le (#197) * Validate semver format before running script Signed-off-by: John Starich <[email protected]> * Fix semver install for v0.2 Signed-off-by: John Starich <[email protected]> * Manually fix namespace name Signed-off-by: John Starich <[email protected]> * Fix coverage flapping Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Fixes OLM metadata so it will install properly from Operator Hub for v0.2+. Adds make tasks to assists OLM testing. Bumps the memory limit to mitigate an OOMKilled issue when running in OpenShift 4.4 (i.e. lots of built-in secrets). Opened #199 to look into it further. Also update TokenController to skip processing any secret not using the well-known names. e.g. `secret-ibm-cloud-operator` `<namespace>-secret-ibm-cloud-operator` Signed-off-by: Art Berger <[email protected]>

* Update namespace to use singular form: "ibmcloud-operator" * Breaking change: Update to use the same naming scheme everywhere "ibmcloud-operator-*" Signed-off-by: Art Berger <[email protected]>

…203) * Add new stable channel. New versions will update the stable channel. This isn't perfect right now, but it will be accurate once we release v1.0.0. Signed-off-by: John Starich <[email protected]> * Set default channel to stable Signed-off-by: John Starich <[email protected]> * Order stable channel before alpha Signed-off-by: John Starich <[email protected]> * Fix validation while including old alpha release Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

* Fix Markdown formatting for Operator Hub Signed-off-by: John Starich <[email protected]> * Poke Travis Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Signed-off-by: Art Berger <[email protected]>

…ng deps (#208) Signed-off-by: Art Berger <[email protected]>

* Add more logging * Fix bug: was calling wrong IsNotFound func * Remove confusing IsNotFound func from ibmcloud package Signed-off-by: Art Berger <[email protected]>

* MaxConcurrentReconciles can be set through env var * Combine max reconciles into main Config struct, surface it in deployment.yaml Co-authored-by: qibobo <[email protected]> Signed-off-by: Art Berger <[email protected]>

…create (#211) Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Signed-off-by: Art Berger <[email protected]>

Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Signed-off-by: Art Berger <[email protected]>

…s into adb-doc-review-readme

JohnStarich

This looks great! I'm actually going to go ahead and approve/merge and I can start working on my comments in the next PR.

README.md

JohnStarich · 2020-09-23T17:56:46Z

README.md

+    * [Binding properties](#binding-properties)
+    * [Account context in operator secret and configmap](#account-context-in-operator-secret-and-configmap)
+    * [Versions](#versions)
+*   [Contributing](#contributing)


I don't know if it's just GH being weird, but some of these links didn't render in the preview. Perhaps the headings have changed?

The bottom two should be to the contributing & TS files, so they're formatted wrong.

JohnStarich · 2020-09-23T17:58:07Z

README.md


-## Set up the operator
+5.  Target the appropriate environment (`--cf`) and resource group (`-g`). Note that you must still set the Cloud Foundry `org` and `space` environment, even if you do not create any Cloud Foundry services.


This is actually only required now if you plan to use CF services. The installer will continue if org or space are left blank

JohnStarich · 2020-09-23T18:04:45Z

README.md

+
+    ```bash
+    ibmcloud ks cluster config -c <cluster_name_or_ID>
+    ```


JohnStarich · 2020-09-23T18:09:30Z

README.md


-### Install
+You can use an installation script to set up the IBM Cloud Operator. The installation script stores an API key in a Kubernetes secret in your cluster that can be accessed by the IBM Cloud Operator. Next, the script sets default values that are used to provision IBM Cloud services, like the resource group and region to provision the services in. Later, you can override any default value in the `Service` custom resource. Finally, the script deploys the operator in your cluster in the `ibmcloud-operators` namespace.


I like the new wording 😄
One note: the namespace name has changed to ibmcloud-operator-system and in OpenShift it's openshift-operators

JohnStarich · 2020-09-23T18:15:19Z

README.md

+4.  Set the API key of the service ID as your CLI environment variable. Now, when you run the installation script, the script uses the service ID's API key. The following command is an example for macOS.
+
+    ```bash
+    setenv IBMCLOUD_API_KEY <apikey-ico-value>


I think we need export IBMCLOUD_API_KEY= here instead of setenv IBMCLOUD_API_KEY. It looks like setenv is a thing in some shells, but not in Bash.

JohnStarich · 2020-09-23T18:17:46Z

README.md

-ibmcloud catalog service-marketplace
-```
+### Uninstalling the operator
+Before you begin, complete the [prerequisite steps](#prerequisites) to log in to IBM Cloud and your cluster.


We should add a note here that this will also delete the CRDs and their associated custom resources. It can be pretty destructive if they have a bunch of provisioned services.

JohnStarich · 2020-09-23T18:20:26Z

README.md

-To find the status of your binding, you can run the command:
+To use the IBM Cloud Operator, create a service instance and then bind the service to your cluster. For more information, see the [sample configuration files](config/samples), [user guide](docs/user-guide.md), and [reference documentation](README.md#reference).
+
+**Step 1: Creating a service instance**


Would it be useful to make these headings? ### Step 1: ...

JohnStarich · 2020-09-23T18:23:27Z

README.md

+    kind: ConfigMap
+    metadata:
+      name: ibmcloud-operator-config
+      namespace: ibmcloud-operators # Or update to the namespace where IBM Cloud Operator is running


Same namespace note as above, I like the comment though 👍

JohnStarich · 2020-09-23T18:24:08Z

README.md

+    EOF
+    ```
+
+3.  Copy the existing or create your own `ibmcloud-operator-secret` secrets and `ibmcloud-operator-defaults` configmaps from the other Kubernetes namespace into the `safe` namespace. **Important**: You must rename the secrets and configmaps with the following naming convention. **Tip**: You can create these new secrets and configmaps similarly to `make install`, if you are familiar with that process.


Maybe we should remove the make install tip? I think that may confuse users, since it's more of a development thing.

JohnStarich · 2020-09-23T18:28:01Z

README.md

@@ -44,6 +44,24 @@ With the IBM Cloud Operator, you can provision and bind [IBM public cloud servic
 [Back to top](#ibm-cloud-operator)
 <!-- SHOW operator hub -->

+## Upgrading the operator
+To upgrade, you can reinstall the operator through the OperatorHub or the `curl` [installation command](README.md#setting-up-the-operator).


This one may need to be careful to distinguish the install processes a bit. Since Operator Hub installs in a very different way than the install script does.

…218) Signed-off-by: Art Berger <[email protected]>

artberger added the docs label Sep 10, 2020

artberger self-assigned this Sep 10, 2020

artberger marked this pull request as ready for review September 11, 2020 20:07

artberger commented Sep 11, 2020

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

JohnStarich mentioned this pull request Sep 21, 2020

Merge v1.0.0 release PR into community-operators repo #206

Closed

4 tasks

Art Berger and others added 19 commits September 23, 2020 11:15

docs: Doc edits to readme for tasks and ref section

a6e20ae

Signed-off-by: Art Berger <[email protected]>

docs: Add versions

d94ca9f

Signed-off-by: Art Berger <[email protected]>

docs: add asterisk

256ccb6

Signed-off-by: Art Berger <[email protected]>

docs: add tip about api version

8811224

Signed-off-by: Art Berger <[email protected]>

Doc edits for the contributors guide (#193)

21b43fe

Signed-off-by: Art Berger <[email protected]>

Add service controller unit tests (#195)

309f91f

* Add unit tests for service controller * Add more tests for CF services * Add "make test-fast" for quicker local testing Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Add coverage badge to README (#196)

4b54795

Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

break: Use consistent resource names for v1 (#201)

0a92cb3

* Update namespace to use singular form: "ibmcloud-operator" * Breaking change: Update to use the same naming scheme everywhere "ibmcloud-operator-*" Signed-off-by: Art Berger <[email protected]>

Fix Markdown formatting for Operator Hub (#202)

f681f62

* Fix Markdown formatting for Operator Hub Signed-off-by: John Starich <[email protected]> * Poke Travis Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Upgrade custom resource types to v1 (#204)

3ff174d

Signed-off-by: Art Berger <[email protected]>

Set up both tests and main.go in one place + add tests to check missi…

6e798b8

…ng deps (#208) Signed-off-by: Art Berger <[email protected]>

Fix default namespace fallback (#209)

cecd83a

* Add more logging * Fix bug: was calling wrong IsNotFound func * Remove confusing IsNotFound func from ibmcloud package Signed-off-by: Art Berger <[email protected]>

Add back max concurrent reconciles environment variable (#210)

a10f63e

* MaxConcurrentReconciles can be set through env var * Combine max reconciles into main Config struct, surface it in deployment.yaml Co-authored-by: qibobo <[email protected]> Signed-off-by: Art Berger <[email protected]>

Add tests to ensure an alias service will never issue an API call to …

a55a57d

…create (#211) Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

Add kubeval for validation of kube yaml in PRs (#214)

cb6608d

Signed-off-by: Art Berger <[email protected]>

Bump memory limit again for higher # of secrets in OpenShift (#216)

b108fac

Signed-off-by: John Starich <[email protected]> Signed-off-by: Art Berger <[email protected]>

artberger force-pushed the adb-doc-review-readme branch from 8874155 to b108fac Compare September 23, 2020 15:25

Merge branch 'master' into adb-doc-review-readme

6a3bb78

artberger pushed a commit that referenced this pull request Sep 23, 2020

docs: Adding binding secret keys note #25, includes readme from #194

4442653

Signed-off-by: Art Berger <[email protected]>

artberger mentioned this pull request Sep 23, 2020

docs: Adding binding secret keys note #218

Merged

docs: moving upgrade section back up

3a28a48

Signed-off-by: Art Berger <[email protected]>

Merge branch 'adb-doc-review-readme' of github.com:IBM/cloud-operator…

ad83f38

…s into adb-doc-review-readme

JohnStarich reviewed Sep 23, 2020

View reviewed changes

JohnStarich approved these changes Sep 23, 2020

View reviewed changes

JohnStarich merged commit 53e50ae into master Sep 23, 2020

JohnStarich deleted the adb-doc-review-readme branch September 23, 2020 18:28

JohnStarich mentioned this pull request Sep 23, 2020

README revisions for v1.0 #219

Merged

JohnStarich pushed a commit that referenced this pull request Sep 23, 2020

docs: Adding binding secret keys note #25, includes readme from #194 (#…

c69a195

…218) Signed-off-by: Art Berger <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Doc edits to readme for tasks and ref section #194

docs: Doc edits to readme for tasks and ref section #194

artberger commented Sep 10, 2020

codecov bot commented Sep 10, 2020 •

edited

Loading

JohnStarich left a comment

JohnStarich Sep 23, 2020

artberger Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020

JohnStarich Sep 23, 2020


		## Set up the operator
		5. Target the appropriate environment (`--cf`) and resource group (`-g`). Note that you must still set the Cloud Foundry `org` and `space` environment, even if you do not create any Cloud Foundry services.


		### Install
		You can use an installation script to set up the IBM Cloud Operator. The installation script stores an API key in a Kubernetes secret in your cluster that can be accessed by the IBM Cloud Operator. Next, the script sets default values that are used to provision IBM Cloud services, like the resource group and region to provision the services in. Later, you can override any default value in the `Service` custom resource. Finally, the script deploys the operator in your cluster in the `ibmcloud-operators` namespace.

docs: Doc edits to readme for tasks and ref section #194

docs: Doc edits to readme for tasks and ref section #194

Conversation

artberger commented Sep 10, 2020

codecov bot commented Sep 10, 2020 • edited Loading

Codecov Report

JohnStarich 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Sep 10, 2020 •

edited

Loading