SRVCLI-259: Add docs on using offline services with the kn CLI #32671

rh-max · 2021-05-20T13:51:20Z

Add docs on using kn CLI in the offline mode

For versions 4.6+

https://issues.redhat.com/browse/SRVCLI-259

https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html#using-offline-services

netlify · 2021-05-20T13:56:45Z

✔️ Deploy Preview for osdocs ready!

🔨 Explore the source changes: 9fab681

🔍 Inspect the deploy log: https://app.netlify.com/sites/osdocs/deploys/60be3f0106094000084b15ae

😎 Browse the preview: https://deploy-preview-32671--osdocs.netlify.app

rh-max · 2021-05-20T13:58:29Z

@dsimansk @abrennan89 Could you PTAL? Note that based on David's bug report, I have not included the command that modifies an offline service.
@dsimansk Is this a technology preview?
@abrennan89 The current placement is questionable, but I couldn't find a better place. Should I leave it here, subject to the upcoming restructuring?

https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html#using-kn-cli-in-offline-mode

dsimansk · 2021-05-20T14:23:49Z

@dsimansk Is this a technology preview?

We call it "experimental" in the upstream to have a bit of soak time and potential window to take compatibility-breaking changes. IMO it sound all right to have a note that it's technology preview feature in our docs. @rhuss any objections to call offline mode TP?

rh-max · 2021-05-20T15:12:56Z

@mvinkler Could you please review these docs?

abrennan89 · 2021-05-20T15:27:16Z

@mvinkler Could you please review these docs?

@rh-max he's on sick leave I think so someone else may need to take a look for QE.

I think a better place for this would be under / after the serverless applications topic here: https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html

Only this module https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/cli_reference/kn-offline-services.html#creating-an-offline-service_kn-offline-services really belongs in the CLI guide I think, and it can live in the kn service page https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/cli_reference/kn-services-ref.html since it's a kn service command.

This one isn't a blocker for 1.15.0 FYI, so I'd make the release notes higher priority probably and come back to it if you're pushed for time.

rh-max · 2021-05-26T09:25:51Z

@mvinkler Could you please review these docs?

@rh-max he's on sick leave I think so someone else may need to take a look for QE.

I think a better place for this would be under / after the serverless applications topic here: https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html

Only this module https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/cli_reference/kn-offline-services.html#creating-an-offline-service_kn-offline-services really belongs in the CLI guide I think, and it can live in the kn service page https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/cli_reference/kn-services-ref.html since it's a kn service command.

This one isn't a blocker for 1.15.0 FYI, so I'd make the release notes higher priority probably and come back to it if you're pushed for time.

@abrennan89 Thanks. I think [1] is a good location.

However, I think it's better to not split modules/kn-service-offline-about.adoc and modules/kn-service-offline-create.adoc. So I have put both into [1]. The reasons being:

Splitting the concept and the procedure, especially to reside in different sections inside serverless/ reduces usability of the docs.
Everything that's currently in [1] is a procedure. So I'd rather not put a bare concept there. A procedure prepended by a concept, however, is fine.
modules/kn-service-offline-create.adoc isn't so much a reference as it is a user story. So the initial placement in serverless/cli-reference/ was really just a temporary parking. It should be in a more user story-oriented part of the docs, such as [1].

[1] https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html

rh-max · 2021-05-26T09:27:21Z

@dsimansk The built docs for review now reside at:
https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html#using-offline-services

serverless/knative_serving/serverless-applications.adoc

modules/kn-service-offline-create.adoc

modules/kn-service-offline-about.adoc

modules/kn-service-offline-create.adoc

jrangelramos

qe review. looks good to me with minor suggestions.

In time, as a suggestion I think it would be nice to show (as a step 5.) the actual service creation in a cluster using the descriptor created. but I leave it up to you, wdyt?

$ kn service create -f test/ksvc/event-display.yaml 
Creating service 'event-display' in namespace 'test':

  0.058s The Route is still working to reflect the latest desired specification.
  0.098s ...
  0.168s Configuration "event-display" is waiting for a Revision to become ready.
 23.377s ...
 23.419s Ingress has not yet been reconciled.
 23.534s Waiting for load balancer to be ready
 23.723s Ready to serve.

Service 'event-display' created to latest revision 'event-display-00001' is available at URL:

modules/kn-service-offline-about.adoc

modules/kn-service-offline-create.adoc

rh-max · 2021-06-01T10:15:01Z

qe review. looks good to me with minor suggestions.

In time, as a suggestion I think it would be nice to show (as a step 5.) the actual service creation in a cluster using the descriptor created. but I leave it up to you, wdyt?
$ kn service create -f test/ksvc/event-display.yaml 
Creating service 'event-display' in namespace 'test':

  0.058s The Route is still working to reflect the latest desired specification.
  0.098s ...
  0.168s Configuration "event-display" is waiting for a Revision to become ready.
 23.377s ...
 23.419s Ingress has not yet been reconciled.
 23.534s Waiting for load balancer to be ready
 23.723s Ready to serve.

Service 'event-display' created to latest revision 'event-display-00001' is available at URL:

Good idea, I've included this as the last step.

rh-max · 2021-06-01T10:19:00Z

@dsimansk @jrangelramos I've implemented your feedback, which resulted in some more rewrites. I'd appreciate you having a look at the changes. No need for actual QE testing, @jrangelramos, I have not changed the commands.
Diff: cfe0ac7
Preview: https://deploy-preview-32671--osdocs.netlify.app/openshift-enterprise/latest/serverless/knative_serving/serverless-applications.html#using-kn-cli-in-offline-mode

modules/kn-service-offline-create.adoc

jrangelramos · 2021-06-01T14:50:46Z

QE Approved

dsimansk

Thanks Max looks good to me. I like the updated introduction listing with the use cases. 👍

/lgtm

rh-max · 2021-06-01T16:01:14Z

Thanks @dsimansk and @jrangelramos for your work on this!

abrennan89 · 2021-06-01T18:50:01Z

@rh-max please ensure that you're adding labels if you can and following the guidelines wrt titles etc for PRs. There was an email forwarded to us about this from Vikram / Cheryl.

lbarbeevargas

Great job on this new section for offline mode! I added some feedback and considerations per the OCP guidelines and ISG. Please let me know if you have any questions about my comments.

modules/kn-service-offline-about.adoc

modules/kn-service-offline-create.adoc

openshift-ci · 2021-06-02T14:10:29Z

New changes are detected. LGTM label has been removed.

rh-max · 2021-06-02T22:16:47Z

@lbarbeevargas Thanks for the review 👍 , all suggestions implemented. Provided you, or anyone else, has no more feedback, let's consider this ready.
At the moment, this should NOT be merged. I'll let you know.

serverless/knative_serving/serverless-applications.adoc

modules/kn-service-offline-create.adoc

serverless/knative_serving/serverless-applications.adoc

modules/kn-service-offline-about.adoc

abrennan89

Some final updates, otherwise lgtm

abrennan89

lgtm!

Add Technology Preview note for using offline services Improve feature name in TP note Move Using offline services to serverless/knative_serving Fix section nesting level Numerous improvements Add missing output line Numerous stylistic improvements s/the offline mode/offline mode/ Lowercase "Continuous Integration" Co-authored-by: Ashleigh Brennan <abrennan@redhat.com> Minor markup and wording fixes

abrennan89 · 2021-06-07T15:48:19Z

/cherrypick enterprise-4.6

abrennan89 · 2021-06-07T15:48:30Z

/cherrypick enterprise-4.7

abrennan89 · 2021-06-07T15:48:36Z

/cherrypick enterprise-4.8

openshift-cherrypick-robot · 2021-06-07T15:48:59Z

@abrennan89: new pull request created: #33157

Details

In response to this:

/cherrypick enterprise-4.6

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.

openshift-cherrypick-robot · 2021-06-07T15:49:09Z

@abrennan89: new pull request created: #33158

Details

In response to this:

/cherrypick enterprise-4.7

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.

openshift-cherrypick-robot · 2021-06-07T15:49:15Z

@abrennan89: new pull request created: #33159

Details

In response to this:

/cherrypick enterprise-4.8

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.

openshift-ci bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 20, 2021

openshift-ci bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 24, 2021

rh-max force-pushed the srvls-offline-services branch from d2ba6f7 to 99b26a8 Compare May 26, 2021 08:00

openshift-ci bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 26, 2021

dsimansk suggested changes May 26, 2021

View reviewed changes

jrangelramos reviewed May 27, 2021

View reviewed changes

modules/kn-service-offline-about.adoc Outdated Show resolved Hide resolved

modules/kn-service-offline-create.adoc Outdated Show resolved Hide resolved

modules/kn-service-offline-create.adoc Outdated Show resolved Hide resolved

dsimansk reviewed Jun 1, 2021

View reviewed changes

modules/kn-service-offline-create.adoc Outdated Show resolved Hide resolved

dsimansk approved these changes Jun 1, 2021

View reviewed changes

openshift-ci bot assigned dsimansk Jun 1, 2021

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Jun 1, 2021

lbarbeevargas added the serverless Label for all Serverless PRs label Jun 1, 2021

abrennan89 added branch/enterprise-4.6 branch/enterprise-4.7 branch/enterprise-4.8 labels Jun 1, 2021

abrennan89 added this to the Next Release milestone Jun 1, 2021

lbarbeevargas reviewed Jun 1, 2021

View reviewed changes

lbarbeevargas added the peer-review-done Signifies that the peer review team has reviewed this PR label Jun 1, 2021

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Jun 2, 2021