Add Tasks section to docs #2587

jberkhahn · 2019-03-28T22:28:04Z

how to install a broker
how to sync a broker
refactor concepts section

This PR is a

Feature Implementation
Bug Fix
Documentation

Fixes #1795

jberkhahn · 2019-03-28T22:28:24Z

/cc @MHBauer @jboyd01

jboyd01

I agree with adding the Task section, good addition.

jboyd01 · 2019-03-29T16:02:59Z

docs/tasks/index.md

+## [Install a Broker](./install_broker.md)
+
+How to add a broker to your catalog. This will make the services that broker
+available to users on your cluster. Adding it as a Cluster Service Broker


grammar... "This will make the services that broker available to users..."
"that a broker offers" ?

jboyd01 · 2019-03-29T16:03:06Z

docs/tasks/index.md

+
+How to add a broker to your catalog. This will make the services that broker
+available to users on your cluster. Adding it as a Cluster Service Broker
+(CSB) will make it available cluster-wide. Adding it as a Service Broker,


you are making up new abbreviates here - - CSB and NSB. Not certain we want to do that. ??

You might try something like "A Service Broker can be registered with Service Catalog as either a Cluster Service Broker which makes its resources available cluster wide, to all users in all namespaces, or as a Service Broker which only exposes the resources within the specified namespace."

ACTUALLY.... how about just saying this task covers how to add a service broker. Leave the details about CSB & NSB to the actual task page?

jboyd01 · 2019-03-29T16:42:06Z

docs/tasks/index.md

+
+## [Install a Broker](./install_broker.md)
+
+How to add a broker to your catalog. This will make the services that broker


I think that first sentence should be a complete sentence that is grammatically correct. Maybe "You must install a broker into the service catalog to make the services it offers available."

jboyd01 · 2019-03-29T16:45:37Z

docs/tasks/index.md

+
+## [Sync a Broker](./sync_broker.md)
+
+How to re-sync a broker that is already added to your catalog. When a broker's


Again I'd make the first sentence grammatically correct. "This task shows how to ..." or something. And I'd avoid the sync abbreviation vs spelling it out.

my issue with spelling it out vs just saying 'sync' is we've already used sync in places - the command is called sync, the help in svcat calls it sync, etc.

jboyd01 · 2019-03-29T16:47:01Z

docs/tasks/index.md

+## [Sync a Broker](./sync_broker.md)
+
+How to re-sync a broker that is already added to your catalog. When a broker's
+catalog changes, it may need to be resynced with Service Catalog.


resynchronized

jboyd01 · 2019-03-29T16:59:16Z

docs/tasks/index.md

+also called a Namespaced Service Broker (NSB) will make it available
+only in a single namespace.
+
+## [Sync a Broker](./sync_broker.md)


Instead of Sync can we spell out Synchronize?

jboyd01 · 2019-03-29T17:02:01Z

docs/tasks/install_broker.md

+done by creating either a ClusterServiceBroker or ServiceBroker object, and
+then allowing Service Catalog to sync with the broker. This is typically
+referred to as "registering" the broker.
+


I think this is the right place to elaborate on the differences between Cluster Vs NS. "A Service Broker can be registered with Service Catalog as either a Cluster Service Broker which makes its resources available cluster wide, to all users in all namespaces, or as a Service Broker which only exposes the resources within the specified namespace."

jboyd01 · 2019-03-29T17:06:31Z

docs/tasks/sync_broker.md

+layout: docwithnav
+---
+
+A broker's catalog may occasionaly change the services it offers. A broker


nits about the wording here: a broker doesn't resync - - svcat resyncs.

like everywhere else, spell out sync. Good details though Jonathan.

jberkhahn · 2019-04-01T23:07:06Z

docs/tasks/sync_broker.md

+A broker's catalog may occasionaly change the services it offers. A broker
+may resync automatically or may need to be resynced manually. By default,
+brokers are resynced automatically based on an interval that is globally
+set in Service Catalog. If a broker must be resynced immeadiately or


immediately

jberkhahn · 2019-04-01T23:07:43Z

docs/tasks/sync_broker.md

+layout: docwithnav
+---
+
+A broker's catalog may occasionaly change the services it offers. A broker


occasionally

Therefore, Service Catalog must resync with the broker to get the updated services

add the name of the global flag in the helm chart

jberkhahn · 2019-04-01T23:09:59Z

docs/tasks/sync_broker.md

+`spec.relistBehavior` has been set to manual, then it can be resynced
+manually by incrementing `spec.relistRequests`. This can be done using svcat:
+```console
+$ svcat sync broker foobar --scope cluster


add command line example of updated catalog: 2 -> 3 classes

jberkhahn · 2019-04-01T23:11:16Z

docs/tasks/install_broker.md

+$ svcat register foobarbroker --url http://foobarbroker.com --scope cluster
+```
+
+Most actual brokers will require authenticaiton of some kind. To add this, use the


authentication

jberkhahn · 2019-04-01T23:16:00Z

docs/tasks/sync_broker.md

+may resync automatically or may need to be resynced manually. By default,
+brokers are resynced automatically based on an interval that is globally
+set in Service Catalog. If a broker must be resynced immeadiately or
+`spec.relistBehavior` has been set to manual, then it can be resynced


use .spec... of the broker

MHBauer · 2019-04-01T23:35:41Z

Looked at these with jonathan, his comments are my comments.

- how to install a broker - how to sync a broker - refactor concepts section

jberkhahn · 2019-04-01T23:57:06Z

@jboyd01 @MHBauer rejiggered stuff according to your comments, please take another look when you get a chance

jberkhahn · 2019-04-02T00:24:56Z

/retest

jberkhahn · 2019-04-08T22:21:57Z

@MHBauer could you take a look at this?

MHBauer

browsed, the spelling seems good now.
/lgtm

jboyd01 · 2019-04-09T15:03:59Z

Nice additions @jberkhahn
/approve

k8s-ci-robot · 2019-04-09T15:04:20Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jboyd01

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [jboyd01]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

- how to install a broker - how to sync a broker - refactor concepts section

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Mar 28, 2019

k8s-ci-robot requested review from jboyd01 and MHBauer March 28, 2019 22:28

jboyd01 reviewed Mar 29, 2019

View reviewed changes

jberkhahn force-pushed the cleanup_docs branch from b808e48 to bee7343 Compare March 29, 2019 21:06

jberkhahn commented Apr 1, 2019

View reviewed changes

Add Tasks section to docs

85c5558

- how to install a broker - how to sync a broker - refactor concepts section

jberkhahn force-pushed the cleanup_docs branch from bee7343 to 85c5558 Compare April 1, 2019 23:56

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Apr 1, 2019

MHBauer approved these changes Apr 8, 2019

View reviewed changes

k8s-ci-robot assigned MHBauer Apr 8, 2019

k8s-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Apr 8, 2019

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 9, 2019

k8s-ci-robot merged commit 96583d3 into kubernetes-retired:master Apr 9, 2019

viviyww pushed a commit to viviyww/service-catalog that referenced this pull request May 10, 2019

Add Tasks section to docs (kubernetes-retired#2587)

c12ff66

- how to install a broker - how to sync a broker - refactor concepts section

cblecker unassigned MHBauer Jun 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Tasks section to docs #2587

Add Tasks section to docs #2587

jberkhahn commented Mar 28, 2019

jberkhahn commented Mar 28, 2019

jboyd01 left a comment

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jberkhahn Mar 29, 2019

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jboyd01 Mar 29, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019

jberkhahn Apr 1, 2019 •

edited

Loading

MHBauer commented Apr 1, 2019

jberkhahn commented Apr 1, 2019

jberkhahn commented Apr 2, 2019

jberkhahn commented Apr 8, 2019

MHBauer left a comment

jboyd01 commented Apr 9, 2019

k8s-ci-robot commented Apr 9, 2019


		## [Install a Broker](./install_broker.md)

		How to add a broker to your catalog. This will make the services that broker


		## [Sync a Broker](./sync_broker.md)

		How to re-sync a broker that is already added to your catalog. When a broker's

Add Tasks section to docs #2587

Add Tasks section to docs #2587

Conversation

jberkhahn commented Mar 28, 2019

jberkhahn commented Mar 28, 2019

jboyd01 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

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

jberkhahn Apr 1, 2019 • edited Loading

Choose a reason for hiding this comment

MHBauer commented Apr 1, 2019

jberkhahn commented Apr 1, 2019

jberkhahn commented Apr 2, 2019

jberkhahn commented Apr 8, 2019

MHBauer left a comment

Choose a reason for hiding this comment

jboyd01 commented Apr 9, 2019

k8s-ci-robot commented Apr 9, 2019

jberkhahn Apr 1, 2019 •

edited

Loading