Skip to content

Commit

Permalink
Guided Tours for Console
Browse files Browse the repository at this point in the history
  • Loading branch information
jhadvig committed Jun 18, 2020
1 parent dcad3a2 commit 191ef01
Show file tree
Hide file tree
Showing 2 changed files with 168 additions and 175 deletions.
168 changes: 168 additions & 0 deletions enhancements/console/guided-tours.md
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.
175 changes: 0 additions & 175 deletions enhancements/console/workflow-guides.md

This file was deleted.

0 comments on commit 191ef01

Please sign in to comment.