projectriff / projectriff.io Goto Github PK

Should we include uninstall instructions for the previous version, seems a bit heavy handed to have to delete the environment and recreate it. There are some notes here: https://github.com/projectriff/charts/tree/v0.4.0#uninstall

Looks like some headers begin with a lowercase letter while others start with an uppercase letter. We should make this consistent.

Followup to #189
I think we need a note about how to install Helm (copy from demo?) if we suggest using Helm to install Kafka.

see

• Kind docs at https://kind.sigs.k8s.io/
• fats clusters/kind

should still include the screenshots of the generated files, but prefer the riff commands in the actual instructions

Change the helm commands to use kapp equivalents

• release blogpost
• set v0.5.0 as the default docs version (rename v0.5.0-snapshot)
• add new v0.6.x-snapshot docs version

Publishing on netlify will enable automatic publishing whenever we push to master.
It will also give us better support for redirects, and avoid having to push to the gh-pages branch which is problematic.

• verify that netlify does not impose any cookies.
• verify that netlify will maintain https certs for custom domains on non-netlify nameservers
• figure out how to transition DNS from gh-pages to netlify with minimal downtime

i have verified that the following steps would work - the process is simple, but it will result in some amount of downtime - so performing it after hours would be better.

• change DNS CNAMEs for both projectriff.io and www.projectriff.io to point to projectriff.netlify.com
• in Netlify site settings, add custom domain for projectriff.io - this will auto-add www.projectriff.io.
• Netlify will immediately try to auto-provision the letsencrypt cert and this will succeed once the DNS pointers to netlify.com are in place (and the old github.io CNAMEs are no long er being served from cache)

netlify docs
The alternative, to avoid zero downtime, would be to self-provision our own certs for the custom domain on netlify, and then, after transitioning DNS, switch to their letsencrypt automation. I have not tested this approach.

In file _docs/010-getting-started-on-minikube.md
the riff create node command fails as it assumes namespace 'test' exists.

riff create node --name square --input numbers --filepath .

the following works.
riff create node --namespace default --name square --input numbers --filepath .

For Docker for Desktop I typically install the primary ingress controller with LoadBalancer since that seems to work fine and the service can be accessed on localhost at port 80 and I can add entries in /etc/hosts for my deployed knative services. This only works for a single LoadBalancer though, so not sure if we want to rely ion that for these instructions.

Currently each getting started doc includes a step the provides the command to install the latest release of each invoker. This means that each doc will need to be updated when a new invoker version is released.

Minimally, we should create an include so there is a single place to update. Even better would be to make that include data driven so it can automatically have the latest install command.

All we have at the moment is a summary paragraph.

We're moving away from invokers that need to be installed into the cluster in favor of buildpacks. Our pages for each invoker still include instructions to install the invoker which isn't relevant in riff 0.1.x. We should remove all references to installing invokers and instead focus on the programming model enabled by each language invoker.

#6 will track the updates for the content of each invoker page, this issue represents the shift of the core site information architecture, Jekyll templates/metadata, etc.

(moved here from projectriff/riff#331)
from: @dsyer

Maybe if some of the output of the commands was shown in the docs it would be easier to know if you are going wrong?

We're no longer showing next-post and previous-post nav buttons and the list on the left doesn't include older posts, so it's actually very hard to navigate between older blog posts

e.g. https://projectriff.io/blog/2017/12/07/springone-platform-keynote-2017

i would suggest either showing the whole list of posts on the left or adding next/prev navigation.

"Sidecars connect functions with event brokers." seems a bit dated, we should replace the middle image/text with something that is more up-to-date.

It's too hard for users to find docs about writing riff functions in each supported language.

How about incorporating README content e.g. from the
node invoker and other invoker repos?

The 0.26.0 version of minikube uses kubeadm as the default bootstrapper and that enables RBAC by default. Release notes for 0.26.0: kubernetes/minikube#2660

We should change all docs to be RBAC only.

For minikube this would be fine when using 0.26.0 or older versions with --bootstrapper=kubeadm. That bootstrapper is the default from 0.26.0 and on.

On GKE this will work fine with 1.8.x versions since they by default have legacy auth disabled and use RBAC, it also works with older versions like 1.7.14-gke.1 with legacy auth enabled.

The dropdown arrows are wrapping weirdly
Maybe shorten the text for this a little.

Need to update the docs. I got it working by removing the cluster-signing-cert-file and cluster-signing-key-file settings. Might want to update the k8s version as well since we are modifying the docs.

Include a note that Legacy Authorization enabled controls RBAC

There is no single URL to give users who want to get started with riff. The best single page right now is the home page which is focused on the latest announcements rather than getting started. The getting started pages are focused on specific k8s installs and assume you already picked which type of cluster to use.

Even what would typically be a neutral landing page like projectriff.io/docs redirects to GKE.

Users trying out streaming with v0.5 should be able to install, create a streaming function, deploy it as a streaming processor, and observe the results of processing streams.

The last step is currently missing in https://projectriff.io/docs/v0.5/runtimes/streaming

One solution would be to deploy dev-utils to "watch" the input and output streams.

We have guides for Minikube and GKE, but there are many, many other k8s platforms. We should have a BYOK (bring your own kubernetes) option for people who generally know how to create and manage a cluster, but want to get up and running with riff.

make cli depends on VERSION file.
Bump to v0.6 when updated v0.6-snapshot CLI docs become available.

See: https://content.pivotal.io/blog/why-serverless-matters-to-your-enterprise-a-look-at-common-use-cases-plus-a-quick-tutorial-with-riff-and-kubernetes

This is to be consistent with the riff docs - projectriff/riff#371

We need an easy place to list all known invokers, whether created by the riff team or another party.

The java invoker docs currently show a boot function before a plain function. The concepts build better in the inverse. Consider swapping the order

We currently have getting-started guides and some content in the riff project plus various other docs/notes. We should gather it all in a more comprehensive reference doc.

The docs (https://projectriff.io/docs/v0.5/runtimes/core) do not seem to define what a deployer is or what its purpose is. There are some hints that when you create a deployer, you also get a service. There needs to be a definition and some description of how it would be used.

We should document the different types of builds:

• Functions
• Applications
• Containers

Add "Next" version to sidebar, with new pages for next release.

Project riff is an open source project, but the more prominent link to the source is in the footer. GitHub is the only means we have for interacting with the community, we should celebrate it instead of burying the link.

While projectriff/node-function-invoker#74 is not fixed, we should remove the explicit --artifact in the documentation for now.

The behavior of each runtime will vary a good bit. We should avoid attempting to document everything for each cluster and instead link off to docs dedicated to specific languages and runtimes.

The high level doc flow should be something like:

1. pick a cluster environment
2. bootstrap a cluster
3. install riff into the cluster
4. pick a language
5. create a function
6. pick a runtime
7. deploy the function
8. invoke the function
9. cleanup all the things

This would also avoid the following:

warning package.json: No license field

Knative Serving 0.12 requires k8s 1.15+. riff should also require 1.15+ across the board.

Docs readers who click on items in the sidebar which are not near the top, lose their position because the sidebar does not maintain scroll poisition across clicks.

This issue has also been raised and a workaround proposed in docusaurus.

How to invoke a running function will vary depending on the runtime. We should push that knowledge into the docs for the runtimes rather then attempting to do it in the language specific docs.

Depends on #93

The docs currently state:

At of riff 0.5.x, the only available kind of Provider available is KafkaProvider, which maps each riff stream to a Kafka topic.

This is no longer true:

Usage:
  riff streaming [command]

Available Commands:
  inmemory-provider (experimental) in-memory stream provider
  kafka-provider    (experimental) kafka stream provider
  processor         (experimental) processors apply functions to messages on streams
  pulsar-provider   (experimental) pulsar stream provider
  stream            (experimental) streams of messages

Some instructions are macOS only, we should add the appropriate suggestions for Linux and Windows as well