Quick Starts for Console #360
Conversation
openshift-ci-robot
added
the
do-not-merge/work-in-progress
There was a problem hiding this comment.
Thanks @jhadvig. Since this differs from current designs, we'd need to work with @alimobrem and @openshift/team-ux-review to see if this is an acceptable compromise.
If we're already linking outside of console for these guides, is there a reason we wouldn't link to official OpenShift docs as opposed to a GitHub markdown file?
| 1. Add additional `ConsoleLinkLocation` type to the `ConsoleLink` [API](https://github.com/openshift/api/blob/master/console/v1/types_console_link.go#L65-L74) named `WorkflowGuide`. | ||
| 2. If `ConsoleLinkLocation` type is set to `WorkflowGuide`, it will be possible to define a `WorkflowGuideSpec` with following fields: | ||
| * Section - string - Defines area of interest, e.g. `operators`. | ||
| * Admin - bool - Defines if the Workflow Guide is cluster admin oriented (user has to have cluster admin permisions). |
There was a problem hiding this comment.
We should be precise about the exact access review we are checking here. We also have environments where users who aren't cluster-admin can still install operators, so this might need to be more nuanced.
There was a problem hiding this comment.
Thinking about this now it might be a good idea to be have the link agnostic on the user permissions. Since the links will be rendered in:
- element that represents start of given workflow (either what UX team is proposing or what I was)
- list of Guides
- ...
It shouldn't really matter I think since if user sees the element for starting a particular workflow then he will also see the link for the tour. Otherwise he would only see it in the list of all the Guides.
The Admin field was just for filtering purposes really. meaning which Guides we wanna show when user lists the Guides Dev Console and which for Admin Console, to only show relevant Guides.
Dont think that rendering links for the Guides, either linking to our docs or GH should cause any security issues
| 2. For linking the OpenShift Console and the Workflow Guides `ConsoleLinks` CRD will be used. To suite the need following extension of the `ConsoleLinks` is needed: | ||
| 1. Add additional `ConsoleLinkLocation` type to the `ConsoleLink` [API](https://github.com/openshift/api/blob/master/console/v1/types_console_link.go#L65-L74) named `WorkflowGuide`. | ||
| 2. If `ConsoleLinkLocation` type is set to `WorkflowGuide`, it will be possible to define a `WorkflowGuideSpec` with following fields: | ||
| * Section - string - Defines area of interest, e.g. `operators`. |
There was a problem hiding this comment.
We might want a well-defined list of values and validation to avoid creating separate sections based on small differences like Operators vs operators vs operator.
There was a problem hiding this comment.
definitely! I was thinking to use the names top section of the left navbar:
- Operators
- Workloads
- Serverless
- ...
- User Management
- Administration
- Other (?!)
|
|
||
| In order for the user to see what resources need to be created in terms of a specific Workflow Guide, we will display list of those resources in a right sidebar similar to the proposed [Solution Explorer](https://marvelapp.com/236ge4ig/screen/69628466). Each of the resource items will be prefixed with an icon which will indicate if the resource exists or not. | ||
|
|
||
| For the Resource Check we will need to define a new CRD that will contain list of resources. For each resource, following fields will need to be defined: |
There was a problem hiding this comment.
I'd inline this directly in WorkflowGuideSpec since presumably this only applies to a single guide.
There was a problem hiding this comment.
Yeah, I was thinking about that or maybe create a new CRD that would combine the API of WorkflowGuide and ResourceCheck, but that kinda felt like a dup of the ConsoleLinks so I've decoupled it.
Anyway makes sense 👍
| ### Implementation Details | ||
|
|
||
| 1. GitHub will be used creating and storing the Workflow Guides. GitHub provides rich markdown options, including images and videos, which will come handy in the process of creating a Workflow Guide. Since we have storage limits in ETCD, it's for the best to use a technology that both storest the content and provides rich markdown. Also by using GitHub we solve the issue with Workflow Guides versioning. | ||
| 2. For linking the OpenShift Console and the Workflow Guides `ConsoleLinks` CRD will be used. To suite the need following extension of the `ConsoleLinks` is needed: |
There was a problem hiding this comment.
Worth noting that ConsoleLink is cluster-scoped, so all guides would be cluster-scoped.
There was a problem hiding this comment.
Right, but as mention above, not sure if thats an issue, since they should be present in wanted elements or the list of Guides
| * **Extenstion:**: ResourceCheckName - string - Defines the name of the `ResourceCheck` CR. | ||
|
|
||
| 3. RedHat supported Workflow Guides will be places in new `openshift/workflow-guides` repository. Each root folder in the repository will be named after area of interest (e.g. top items from the left navigation menu - Operators, Workloads, Serverless, ..., Administration). | ||
| 4. The `openshift/workflow-guides` repository will also contain a `manifests/` root folder that will contain all yaml for all the official Workflow Guides `ConsoleLinks` CRs. All the manifests will be copied into the `console-operator` image upon it's build. Alternativly there could be a small `workflow-guides-operator` that will be: |
There was a problem hiding this comment.
All the manifests will be copied into the
console-operatorimage upon it's build.
We probably need to vendor them into the repo for repeatable builds.
There was a problem hiding this comment.
yes will have to.
Or we could have a dedicated operator that would take care of that and also updates.. and possibly other tasks (TBDefined..)
| 6. All Workflow Guides will be listed available in a separate page that will be accessible from Help Menu. | ||
|  | ||
| 7. For different areas of interest, the links for Workflow Guides will need to be handles separately: | ||
| * Operators - CVS of the operator that has a Workflow Guide published will contain `console.openshift.io/workflow-guide: <console-link-name>` annotation. Upon the operator installation an "Workflow Guide" link will appear next to the `Install` button. |
There was a problem hiding this comment.
Is the intent for console to list CSVs in the current namespace in addition to ConsoleLink to build one list of guides?
There was a problem hiding this comment.
no, this is only related to the Operator Hub page where we use the operator's CSV for rendering it in a tile. The CSV could contain mentioned annotation in order to link to a particular ConsoleLink CR.
Im only mention ing the list of the Guides since the UX team was proposing some kind of their list and that could actually be a separate page where user could list though all the Guides
| * Kind - string - Kind of the resource. | ||
| * Name - string - Name of the resource. | ||
| * Namespace - string - Namespace of the resource. (Optional) | ||
| * CurrentNamespace - bool - Indicates whether the resource should be check in user's current namespace. If set will be honored instead of the `Namespace` field. (Optional) |
There was a problem hiding this comment.
Should we just assume the current namespace if no namespace is provided?
There was a problem hiding this comment.
right but there are also non-namespaced resources, which might need to be referenced.?
|
|
||
| #### Air Gapped Environments | ||
|
|
||
| If we decide to suppport this case we should have a `workflow-guides-operator`. It's image will contain all the official Workflow Guides. Upon `workflow-guides-operator` image build `openshift/workflow-guides` repository will be cloned into the image so it contains all the official Workflow Guides. The `workflow-guides-operator` will run a pod with a small server that would handle serving of the Workflow Guides. |
There was a problem hiding this comment.
I don't know that we need to worry about the browser being disconnected in these environments. As I understand, it's requests that come from inside the cluster to the outside that we need to worry about. Browser links to GitHub are probably OK.
There was a problem hiding this comment.
oh, then I guess this is not an issue then
|
FYI @christianvogt |
not at all, we dont put any restrictions on the link URL AFAIK |
openshift-ci-robot
removed
the
do-not-merge/work-in-progress
|
@spadgett I've update the enhancement. Still finishing the CRD yaml. |
|
Updated the PR with CRD. Added the "Check your work" feature to both the enhancement doc and CRD. |
|
@jhadvig @christianvogt have you guys thought of how we will determine the featured Tours which are available on the Dev Side? Also wondering if we are considering "types" - the initial mocks showed blogs in the getting started experience. @alimobrem we should probably connect to see if this is something we'd like to do in the future, so it can be considered early. |
@serenamarie125 makes sense to have an additional field in the |
| - displayName | ||
| - introduction | ||
| - tasks | ||
| properties: |
There was a problem hiding this comment.
The tour needs an image property.
| about: | ||
| description: about introduces the Guided Tour purpose | ||
| type: string | ||
| usability: |
There was a problem hiding this comment.
Would we want more flexibility that comes from a single markdown long description?
|
@jhadvig We're going to need some rbac checks to determine if the tour should be made available to the user or not. |
enhancements/console/guided-tours.md
Outdated
| * Introduce CRD format that will be used for writing Guided Tours. | ||
| * Introduce default storage for Guided Tours. | ||
| * Introduce mechanism how to connect different parts of OpenShift Console (Operators, Workloads, ...) with the Guided Tours. | ||
|
|
There was a problem hiding this comment.
I am not clear on this goal, how is this goal achieved?
enhancements/console/guided-tours.md
Outdated
| #### Story 4 | ||
|
|
||
| As a operator creator I want to provide operator consumers with a guide on how to install and user the my operator. | ||
|
|
There was a problem hiding this comment.
All these stories have different personas repeating the need for a guide. Do we know why these personas need a guide? Is there a UX study that helps understand why our current UI can not guide them through? Have we exhausted the easier/cheaper alternates to fix it on our UIs?
There was a problem hiding this comment.
All these stories have different personas repeating the need for a guide. Do we know why these personas need a guide? Is there a UX study that helps understand why our current UI can not guide them through?
I think this is a question to @beanh66
Have we exhausted the easier/cheaper alternates to fix it on our UIs?
yes, my first suggestion was to store the GuidedTours in a single GitHub repository (eg. openshfit/guieded-tours) and use the ConsoleLinks to link particular Console's workflows to them.
Other option was to have the GuidedTours in OpenShift's docs and use iframe to show them in the Console, but we decided not to go that road
| that is offered to the user by completing the Guided Tour | ||
| type: string | ||
| tasks: | ||
| type: array |
There was a problem hiding this comment.
I am not sure why tasks needs to be this structured. Each task could essentially be a single markdown. There is no automated checks, execution of tasks, progress monitoring. I can not think of a reason why we need this structure other than some marginal control over rendering.
It would have been great if we could have more improved capabilities like ability to link to parts of console, copy commands. Define criteria to follow progress.
There was a problem hiding this comment.
Yeah makes sense to drop the structuring and keep it simple
My question was based on the fact that we feature 3 tours on the Add page, but link out to the Guided Tours page to see "the rest". Re: which tours are shown on the Guided Tour page, they've got to be based on privileges - I assume that someone who has no privileges to view the OperatorHub will not "see" the tours about installing Operators. @alimobrem I think this is what was discussed, right? |
jhadvig
force-pushed
the
workflow-guides
branch
3 times, most recently
from
388ec94
to
d99db01
Compare
|
Update the proposal based on @christianvogt and @gorkem feedback. |
|
@jhadvig Guided Tours feature is now renamed to 'Quick Starts'. And |
enhancements/console/guided-tours.md
Outdated
| 2. Make users understand what are the steps needed to achieve their goals. | ||
| 3. Provide API for writing Guided Tours. | ||
| 4. Provide new CRD format for writing the Guided Tours. | ||
| 5. Have a storage for the Guided Tours. |
There was a problem hiding this comment.
What do you mean by "storage" here?
There was a problem hiding this comment.
Place where the openshift own Quick Starts will be stored(ideally a repository in openshift org)
There was a problem hiding this comment.
I'd call this a repository for quick starts instead of storage.
It's worth mentioning this is only needed for out-of-the-box quick starts like those describing how to install an operator. Once the operator is installed, it can add its own quick starts.
enhancements/console/guided-tours.md
Outdated
|
|
||
| 1. Provide a mechanism to display user guides for various workflows. | ||
| 2. Make users understand what are the steps needed to achieve their goals. | ||
| 3. Provide API for writing Guided Tours. |
There was a problem hiding this comment.
Is this API something separate from the CRD?
There was a problem hiding this comment.
no that should be the CRD
There was a problem hiding this comment.
OK, I'd remove (3) since you mention the CRD just below. Otherwise it sounds like we're proposing a plugin API in addition to the CRD.
enhancements/console/guided-tours.md
Outdated
| 6. All Guided Tours will be listed available in a separate page that will be accessible from Help Menu. | ||
|  | ||
| 7. For different areas of interest, the links for Guided Tour will need to be handles separately: | ||
| * Operators - CVS of the operator that has a Guided Tours published will contain `console.openshift.io/guided-tour: <guided-tour-name>` annotation. Upon the operator installation an "Guided Tour" link will appear next to the `Install` button. |
enhancements/console/guided-tours.md
Outdated
| GuidedTours CR for [Explore Serverless](https://marvelapp.com/236ge4ig/screen/69908905): | ||
| ``` | ||
| apiVersion: console.openshift.io/v1 | ||
| kind: GuidedTours |
There was a problem hiding this comment.
Kind should be singular, GuidedTour (although I know you're working on changing the name anyway)
enhancements/console/guided-tours.md
Outdated
| 3. `console-operator` will import all the existing Guided Tours CRs from the `openshift/guided-tours` repository into the `/manifest` directory, so that the CVO can: | ||
| * create them if the CR doesn't exists. | ||
| * update the CRs upon the cluster update (since CVO is doing `apply`). | ||
| 4. `console-operator` will check for older `GuidedTours` CR versions and remove those that doesn't match the cluster major version, which indicates that new version is not available. |
There was a problem hiding this comment.
Do you mean the cluster minor version? (The y version in 4.y.z?)
We might want to support a semver version range here so one tour CR can be used for multiple OpenShift versions.
enhancements/console/guided-tours.md
Outdated
|
|
||
| ### Third party Guided Tours | ||
|
|
||
| Third party Guided Tours will need to be created manually on the cluster. |
There was a problem hiding this comment.
It's not necessarily manual. It can be created by an operator when installed.
enhancements/console/guided-tours.md
Outdated
|
|
||
| 1. In order to provide mechanism to discribe a Guided Tour, new CRD named `GuidedTours` will be created. | ||
| 2. A new `openshift/guided-tours` repository will be created which will contain all supported Guided Tours. | ||
| 3. `console-operator` will import all the existing Guided Tours CRs from the `openshift/guided-tours` repository into the `/manifest` directory, so that the CVO can: |
There was a problem hiding this comment.
Will we have a way to provide different tours for different OpenShift versions?
There was a problem hiding this comment.
Dont think that it makes sense to have multiple QuickStart versions for a single Console version. I think the model here should be 1:1. Thats where I was aiming with the version field on the CRD
There was a problem hiding this comment.
OK, are you proposing to vendor in all guided tours and filter them in the client by version?
I was thinking we would have release-* branches like in the tours repo, and the operator would just vendor from the appropriate branch. (We still may need the version property to filter tours installed by operators.)
enhancements/console/guided-tours.md
Outdated
| metadata: | ||
| name: explore-serverless | ||
| spec: | ||
| version: 2.6 |
There was a problem hiding this comment.
What is version referring to here? The version of the operator?
There was a problem hiding this comment.
Sorry for the confusion here. version field should correspond to a Console version for which the CR should be used.
There was a problem hiding this comment.
OK, thanks. The number threw me off because it doesn't look like an OpenShift version. I would change this to something like 4.7.
|
@christianvogt @spadgett comments addressed |
enhancements/console/quict-starts.md
Outdated
|
|
||
| #### Story 4 | ||
|
|
||
| As a operator creator I want to provide operator consumers with a guide on how to install and user the my operator. |
There was a problem hiding this comment.
Is there room here to mention a good content authoring experience, too?
And is it possible that tour creators might be quite different from more general "operator creators?"
enhancements/console/quict-starts.md
Outdated
| * ...TBD | ||
|
|
||
|
|
||
| QuickStarts CR for [Explore Serverless](https://marvelapp.com/236ge4ig/screen/69908905): |
There was a problem hiding this comment.
What would the full version of this look like? The tour content is truncated.
There was a problem hiding this comment.
Here is full version https://github.com/openshift/console/pull/5983/files
There was a problem hiding this comment.
@jhadvig Thanks! Has thought been given to externalizing the tour content specifically, so that it might be managed kind of like CCS' modularized documentation?
|
@christianvogt @nemesis09 @spadgett @serenamarie125 I've updated the PR based on the discussion on the Slack and the QuickStarts implementation PR. One thing that I think we need to sort out is whether the review, taskHelp, recapitulation should not be optional? I have an impression that they should be optional in case of a lightweight QS.
|
@jhadvig I agree. I think it's better to have |
|
@rohitkrai03 thanks for review. PR update. PTAL cc'ing @spadgett @serenamarie125 |
| description: introduction describes the purpose and usability of | ||
| the Quick Start. (includes markdown) | ||
| type: string | ||
| tasks: |
There was a problem hiding this comment.
I see the tour content library getting really big, really quickly. That means effort duplication, staleness + accuracy problems, translation pains, etc.
Could this definition support external content sources (say, OCP docs modules so that tour tasks could be single sourced?
There was a problem hiding this comment.
Could this definition support external content sources ...
@maxwelldb not sure what you mean by this. Do you suggest to import the fields from different CRDs ?
There was a problem hiding this comment.
Potentially, yeah, or text from elsewhere.
Picture a generic operator installation tour that really only needs a specific name and maybe a configuration task to be complete.
Being able to single source content like that prevents loads of duplicated effort.
jhadvig
force-pushed
the
workflow-guides
branch
from
d577755
to
d8ecd87
Compare
|
@christianvogt @rohitkrai03 @spadgett @serenamarie125 I've updated the PR with the |
|
lgtm |
| @@ -0,0 +1,173 @@ | |||
| apiVersion: apiextensions.k8s.io/v1beta1 | |||
There was a problem hiding this comment.
I'm not sure we want to check in the CRD since it will drift from what we have in openshift/api over time. We can cover that during API review.
enhancements/console/quick-starts.md
Outdated
| ### Implementation Details | ||
|
|
||
| 1. In order to provide mechanism to discribe a Quick Start, new CRD named `QuickStarts` will be created. | ||
| 2. A new `openshift/quick-tours` repository will be created which will contain all supported Quick Starts. The `openshift/quick-tours` repository will have `release-*` branches. |
enhancements/console/quick-starts.md
Outdated
| 3. `console-operator` will import all the existing Quick Starts CRs from appropriate branch of the `openshift/quick-starts` repository into the `/manifest` directory, so that the CVO can: | ||
| * create them if the CR doesn't exists. | ||
| * update the CRs upon the cluster update (since CVO is doing `apply`). | ||
| 4. `console-operator` will be resposible for removing older `QuickStarts` versions, based on their CRs `spec.version` field that will be in semver format. If the semver version range won't match the cluster version the `console-operator` will remove the CR. |
There was a problem hiding this comment.
Is this necessarily? It seems like we can handle versioning by having release-* branches in the quick-starts repository and just vendoring the right version. I'm not sure we need a version range in the quick start resource itself.
There was a problem hiding this comment.
So field was mainly added, so the operator can get rid of old QuickStarts, since after the cluster update they wont be deleted from the cluster.
Also I think it cant hurt, for the QuickStart CR to know whats it's version.
There was a problem hiding this comment.
Hey @jhadvig. I'm still unclear. The new quick start for the current version should just replace the old one since they have the same name. In that case, the operator doesn't need to do anything.
If we need to remove a quick start entirely, I think we might have to hard-code that special case in the operator for one release. I wouldn't expect this to happen often.
There was a problem hiding this comment.
ok! makes sense, will remove.
enhancements/console/quick-starts.md
Outdated
|
|
||
| #### Quick Start icon | ||
|
|
||
| Each Quick Start CR can contain an icon that is specified in the `spec.icon` field. This field is either an URL of the Package Manifest that contains icon, or a base64 encoded image that are used as Quick Start's icon |
There was a problem hiding this comment.
I don't think we should ask quick start authors to build a URL to a package manifest icon. That's error prone and is really an internal implementation detail that could change over time.
There was a problem hiding this comment.
Wasn't sure with it either but that's it it the outcome of the conversation I had vit @rohitkrai03 and @christianvogt.
Do you propose to cover just the base64 encoded image ?
There was a problem hiding this comment.
If we want to support this, I'd suggest a specific API for referencing an operator icon by package manifest name.
enhancements/console/quick-starts.md
Outdated
|
|
||
| ### Third party Quick Starts | ||
|
|
||
| Third party Quick Starts will need to be created manually on the cluster, or upon operator installation. |
There was a problem hiding this comment.
I'd make it clear that it's the operator itself that creates these after installation.
There was a problem hiding this comment.
How about?
### Installation
`console-operator` is responsible for installing supported Quick Starts at the end of the cluster provisioning process. Third party Quick Starts will need to be created manually on the cluster.
There was a problem hiding this comment.
I was thinking something like
| Third party Quick Starts will need to be created manually on the cluster, or upon operator installation. | |
| Third party Quick Starts will need to be created by an operator after it's installed or manually by a cluster administrator. |
jhadvig
force-pushed
the
workflow-guides
branch
from
d8ecd87
to
abb180b
Compare
|
@spadgett @christianvogt @serenamarie125 I've update the PR. Should be good to go now 👍 |
jhadvig
force-pushed
the
workflow-guides
branch
3 times, most recently
from
98e94d9
to
a51f739
Compare
|
@spadgett removed the CRD. PTAL |
jhadvig
force-pushed
the
workflow-guides
branch
from
a51f739
to
3645e55
Compare
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: jhadvig, spadgett 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:
Approvers can indicate their approval by writing |
openshift-ci-robot
added
the
approved
Introducing the Workflow Guides enhancement for the OpenShift Console. The approach is different then the suggested Guided Tours. Main difference is that the Guides are not hosted by the OpenShift platform, but just linked to a GitHub repository. By utilising GitHubs markdown, guide creators will have a proper tool for creating a step by step guide for different area of interests (operators, workloads, ...).
Stories:
@openshift/team-ux-review @spadgett @alimobrem