-
Notifications
You must be signed in to change notification settings - Fork 471
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
168 additions
and
175 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,168 @@ | ||
--- | ||
title: guided-tours | ||
authors: | ||
- "@jhadvig" | ||
reviewers: | ||
- "@spadgett" | ||
- "@alimobrem" | ||
- "@pweil" | ||
approvers: | ||
- "@spadgett" | ||
creation-date: 2020-06-02 | ||
last-updated: 2020-06-18 | ||
status: provisional | ||
see-also: | ||
- "https://issues.redhat.com/browse/CONSOLE-2255" | ||
- "https://issues.redhat.com/browse/CONSOLE-2232" | ||
- "https://issues.redhat.com/browse/SRVLS-262" | ||
--- | ||
|
||
# Guided Tours | ||
|
||
## Release Signoff Checklist | ||
|
||
- [ ] Enhancement is `implementable` | ||
- [ ] Design details are appropriately documented from clear requirements | ||
- [ ] Test plan is defined | ||
- [ ] Graduation criteria for dev preview, tech preview, GA | ||
- [ ] User-facing documentation is created in [openshift-docs](https://github.com/openshift/openshift-docs/) | ||
|
||
## Open Questions [optional] | ||
|
||
## Summary | ||
|
||
OpenShift's Serverless team has proposed an idea to create a "Guided Tours" | ||
mechanism which introduces users to various ways of interacting with serverless | ||
in the Console. Guided Tours should be a mechanism we can use to vastly improve | ||
our customer's initial user experience on a empty cluster or with all various | ||
workflows: | ||
|
||
The goal of this proposal is to define a lightweight mechanism for OpenShift's | ||
Console component, to guide users thought various workflows, and help them | ||
understand the steps neccesary to get the desired outcome: | ||
|
||
* Install operator | ||
* Deployment of showcase application | ||
* Cluster settings | ||
* Networking | ||
* ... | ||
|
||
In order to achieve the desired outcome user needs to create a set of resources, | ||
that are dependent on each other. | ||
|
||
For Guided Tours we need a mechanism for their creation and publishment. | ||
|
||
## Motivation | ||
|
||
Help users with their understanding the principles of their workflows by | ||
guiding them though the necessary steps. | ||
|
||
### Goals | ||
|
||
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. | ||
4. Provide new CRD format for writing the Guided Tours. | ||
5. Have a storage for the Guided Tours. | ||
|
||
## Proposal | ||
|
||
* 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. | ||
|
||
### User Stories | ||
|
||
#### Story 1 | ||
|
||
As an administrator of an OpenShift cluster, I need a guide to walk me through how to install OpenShift Serverless modules (Serving and Eventing) in a cluster. | ||
|
||
#### Story 2 | ||
|
||
As an administrator of an OpenShift cluster, I need a guide to walk me through how to update an OpenShift cluster. | ||
|
||
#### Story 3 | ||
|
||
As a developer, I need a guide to walk me through how to deploy an existing application as a serverless workload. | ||
|
||
#### Story 4 | ||
|
||
As a operator creator I want to provide operator consumers with a guide on how to install and user the my operator. | ||
|
||
### Implementation Details | ||
|
||
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: | ||
* create them if the CR doenst 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. | ||
5. Steps in the Guided Tours will support basic markdown thats already in use in the OpenShift's Console. | ||
6. All Guided Tours will be listed available in a separate page that will be accessible from Help Menu. | ||
![help-menu](https://raw.githubusercontent.com/jhadvig/images/master/help-menu.png) | ||
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. | ||
![operators](https://raw.githubusercontent.com/jhadvig/images/master/operators.png) | ||
* ...TBD | ||
|
||
|
||
GuidedTours CR for [Explore Serverless](https://marvelapp.com/236ge4ig/screen/69908905): | ||
``` | ||
apiVersion: console.openshift.io/v1 | ||
kind: GuidedTours | ||
metadata: | ||
name: explore-serverless | ||
spec: | ||
version: 2.6 | ||
name: Explore Serverless | ||
followingGuidedTour: serverless-application | ||
duration: 10 | ||
description: Install the Serverless Operator to enable containers, microservices and functions to run "serverless" | ||
prerequisites: Release requisites if any Install X numver of resources. | ||
introduction: | ||
about: Redhat OpenShift Serverless is a service based on the open source Knative project. It provides ... | ||
explanations: | ||
- title: Run anywhere | ||
description: Use Kubernetes and OpenShift to build, scale ... | ||
- title: Integrate with legacy | ||
description: Build modern, serverless applications and support legacy apps through event sources... | ||
... | ||
tasks: | ||
- title: Install Serverless Operator | ||
description: The OperatorHub is where you can find a catalogof available Operators to install on your cluster | ||
steps: | ||
- Visit the OperatorHub and search for the OpenShift Serverless Operator. Complete the installation ... | ||
- You can easily search for the Operator on your cluster using the filter at the top of the page. | ||
- ... | ||
- When OpenShift Serverless Operator appears in your Installed Operator list, ... | ||
- title: Create knative-serving API | ||
description: The first CR we'll create is knative-serving | ||
explanations: | ||
- title: Serving | ||
description: Offers a request-driven model that serves containerized worloads ... | ||
steps: | ||
- Go to the project dropdown and create a project. | ||
- ... | ||
- Check that the form has already specified the namespace ... | ||
- title: create knative-eventing API | ||
description: The second CR we'll create is knative-eventing | ||
explanations: | ||
- title: Eventing | ||
description: Common infrastructure for consuming and producing events to stimulate applications. | ||
steps: | ||
- Go to the project dropdown and create a project. | ||
- ... | ||
- Check that the form has already specified the namespace ... | ||
``` | ||
|
||
#### Check your work | ||
|
||
TBD. Post 4.6 | ||
|
||
#### Air Gapped Environments | ||
|
||
Since the supported Guided Tours CRs will be part of the `console-operator`'s manifests, they will be distributed together with image. | ||
|
||
### Third party Guided Tours | ||
|
||
Third party Guided Tours will need to be created manually on the cluster. |
This file was deleted.
Oops, something went wrong.