kabanero-io / docs Goto Github PK

We need a Kabanero overview describing the architecture, components, and workflows. It should include a description of the development process from both Champ's and Jane's POV.

See: https://github.com/kabanero-io/kabanero-operator/wiki/Todd's-input-for-the-Kabanero-operator

Rather than have a guide for each collection, we decided to write guides that covered the developer experience of using different collections with either:

• Appsody CLI
• VS Code
• Eclipse

The microprofile and Spring guides explain how to use these collections with the Appsody CLI.
#48 will cover using Nodejs-express with VS Code

This issue needs to cover using a collection with the Eclipse IDE.

Suggest we either go for one of the other Nodejs collections, or OpenLiberty when ready.

For MVP, we need a Guide describing the "SpringBoot" Collection.
SpringBoot contains the following:

Spring on OpenLiberty (only experimental phase - not required)
Spring on Tomcat
Need to determine if we need one Guide or two separate guides.

Enhance the script to do the following after the initial istio and kabanero pod setup:

1. git clone https://github.com/appsody/tekton-example as part of this one script too
2. cd tekton-example
3. oc project kabanero
4. kubectl apply -f appsody-service-account.yaml
5. kubectl apply -f appsody-cluster-role-binding.yaml
6. automate editing and apply of docker secrets, also have script prompt for docker credentials:

apiVersion: v1
kind: Secret
metadata:
  name: my-docker-secret
  annotations:
    tekton.dev/docker-0: https://index.docker.io/v1/ 
type: kubernetes.io/basic-auth
stringData:
  username: <your docker userid>
  password: <your docker password>

kubectl apply -f my-docker-secret.yaml

7. kubectl edit serviceaccount appsody-sa
   add:

secrets:
- name: my-docker-secret

8. kubectl apply -f appsody-build-task.yaml
9. kubectl apply -f appsody-build-pipeline.yaml
10. Write to appsody-pipeline-resources.yaml (prompt for docker id and github id):

params:
  - name: url
    value: index.docker.io/your-userid/my-appsody-image
    type: image

spec:
  params:
  - name: revision
    value: master
  - name: url
    value: https://github.com/your-userid/appsody-test-project

kubectl apply -f appsody-pipeline-resources.yaml

11. kubectl apply -f appsody-pipeline-run.yaml

https://www.eclipse.org/codewind/docindex.html

The Codewind documentation requires review and updating.
Need to ensure:

1. Is it accurate for both Kabanero and Cloud Pak for Apps.
2. Tag any content that applies only to Kabanero or only to CP4Apps.
3. Provide content for additional Guides for Codewind - perhaps we could include a Guide for "Using Codewind with Kabanero" and "Using Codewind with IBM Cloud Pak for Apps"?

The README suggests creating directories under /ref/ that correspond to the category of document you are writing ....... if there isn't one that's suitable, create one.

@bschrammIBM - do you have a view on what categories should be created, based on your doc plan?

E.g.

• installation
• guides
• ref

It might be better to start with a structure that writers can contribute to, rather than people creating their own without a good understanding of the overall doc content?

@alohr51 - I also think we need some guidance on front matter. All docs currently written are in the /ref/general directory and have the following front matter:

:page-layout: general-reference
:page-type: general
:page-title: Kabanero Collections
:linkattrs:

Presumably this front matter is used to organise the doc on the website? How would this front matter change based on the location of the doc under /ref please? Might be worth adding a few notes to the README.

In the docs
https://github.com/kabanero-io/docs/blob/master/ref/general/kabanero-foundation-setup.adoc

The command

kubectl apply -f appsody-service-account.yaml

Should have the -n to be sure the sa is created in the correct namespace and not in the current context namespace which it can be default or myproject

In addition since the doc is using oc it should use oc instead of kubectl

I proposed the command should be

oc apply -f appsody-service-account.yaml -n kabanero

The scripts moved to https://github.com/kabanero-io/kabanero-foundation/tree/master/scripts which makes more sense for them.

Update the foundation setup doc to point to the new scripts location and then update the website and remove the docs here in the docs repo as they will no longer be moved.

The installation script for Kabanero Foundation provided here: https://github.com/kabanero-io/kabanero-foundation/tree/master/scripts needs better documentation.

The following issues have been described:

1. A key aspect missing in the kabanero foundation instructions is that the registry must be secured via SSL and knative-serving has to be aware (or made aware) of the signing cert for the registry. From @nastacio For whatever it is worth, if using MacOS (and possibly Ubuntu 18) , I wrote a script to automate all the steps I took and it completes successfully every time on minishift:
   https://gist.github.com/nastacio/df810a53066c34b9242e603ad5ba3b66

2. See #32

3. There are links to OKD documentation and the request is to provide examples or more specifics for what is needed. The links are:
   See more about Configuring Your Inventory File https://docs.okd.io/3.11/install/configuring_inventory_file.html
   See more about the Internal Registry
   https://docs.okd.io/3.11/install_config/registry/index.html

I tried to install Tekton sample through scripts and it failed to deploy. Here is the message that I get.

Pipeline kabanero/appsody-build-pipeline can't be found:pipeline.tekton.dev "appsody-build-pipeline" not found

We need a place with process information for the wider team on guide creation, with template(s) and process, possibly similar to what they have in OpenLiberty: https://github.com/OpenLiberty/draft-guides-template

Document how to install Codewind locally.
There are installation instructions in the Codewind docs here:
https://www.eclipse.org/codewind/installlocally.html
There are installation instructions on kabanero.io website here:
https://kabanero.io/developer/ide/
There are new instructions included in the proposed Getting Started flow.
Review and update these instructions to be complete and accurate.

This could go in a "Working with Pipelines Guide" or as part of the Collections guide.
https://github.com/mnuttall/experimental/blob/docs.for.54/webhooks-extension/docs/GettingStarted.md

Management CLI + Appsody CLI (may be on OpenShift)
Need the installation instructions for this use case, for both local installation and on OpenShift.

The kAppNav tool is part of the kabanero release.
It is the open source version of Application Navigator https://www.ibm.com/support/knowledgecenter/en/SS7K4U_9.0.5/com.ibm.websphere.zseries.doc/ae/ccld_appnav.html
The engineering contact is: Chris Vignola
See https://github.com/kappnav/README

Need the installation instructions for this use case. This covers installation for all components running on Kube on local data center or any public cloud.

• Todd installs this by first installing OKD/OCP 
• Then runs the Kab operator

We need a Guide for how to work with the pre-packaged Eclipse MicroProfile collection. Eclipse MicroProfile is included in the MVP release. Here is a very rough outline for how to document the pre-packaged collections:

• "A Kabanero Collection provides guides for developers, templates for simplicity and consistency of developing applications, a runtime in a certified base container image infused with expertise for Kubernetes deployments, and an integrated toolchain for developing with modern tools. Eclipse MicroProfile is a set of APIs used to optimize Java applications for a microservices architecture. With this stack, you can deliver microservices based upon the Eclipse MicroProfile specifications. Build and run high-quality applications with Open Liberty runtime, which includes OpenJDK with container-optimizations in OpenJ9."  (taken from the Kabanero.io website) 

• Add more information for how Collections are used, what the prerequisites are for the Collection, how it can be customized, etc.

• Components in the Eclipse MP Collection - Describe the functionality of the components. [OpenLiberty, Operators, Prometheus (Grafana?), Tekton]

• How to use a Collection for coding standards and pipelines (Champ)

• How to use a Collection for development (Jane)

• How to set up serverless

• Ideas for how to document collections?

Post MVP - we need a guide for "Working with Collections"

There are 3 opensource NodeJS Collections for MVP:

NodeJS
NodeJS Express
NodeJS LoopBack
These require a Guide, either one guide for all 3 or one guide per collection.

Updated 18th November:

• This issue is for the Nodejs Express collection guide.
• guide must be identical to the MicroProfile and Spring Boot guides already published, replacing the elements unique to this collection.

When using a Tekton webhook to trigger pipelines installed with Kabanero, the last task is the monitor-result-task, which may fail in some cases.
This might also cause the webhook pod to be in the "Error" state. The following failures of monitor-result-task in the TaskRun view can be
disregarded at this time; they do not impact the application deployment:

• error creating GitHub client: error parsing PR number: pulls
• IOError: [Errno 2] No such file or directory: '/workspace/pull-request/pr.json'

https://github.com/ibm-cloud-architecture/Learning-Kabanero-101

There is a site developed by Garage team that duplicates some of the info in the Guides.
We need to cross-check the two sources to be sure they are consistent.
Perhaps we can link to Learning-Kabanero-101 in the Guides.

See https://github.com/ibm-cloud-architecture/Learning-Kabanero-101/issues

@Charlotte-Holt and I were discussing which "tags" to use in the collections guides to keep things consistent. We thought it would be a good idea to create an issue so that this can be tracked. Having too many tags might be problematic (assuming they are used as a filter), so capturing them allows others to re-use the tags, where appropriate, rather than creating new ones.

Edit this description to add the tag names you have used, and re-use any that are appropriate:

• collection
• nodejs
• express
• Java
• MicroProfile
• Spring
• Spring Boot
• Tomcat
• Appsody
• CLI

There are two source documents that need to be incorporated into a Guide.
https://github.com/fwji/openshift-logging - This applies to collections running on OpenLiberty.
https://github.com/fwji/openshift-monitoring applies to all collections running on OpenShift/OKD

The logging info could be part of the OpenLiberty Guide.
The monitoring applies to all collections.

Need to determine whether this warrants a separate "Configuring logging and monitoring" Guide.

The initial collection curation support for "Champ -- Enterprise Architect" has dropped in the 0.1.0 release of the collections. The team supporting collections are documenting that experience with this issue: kabanero-io/kabanero-collection#51. This needs to make its way to formal documentation and the kabanero-io champ collection try it experience.

On the page:
https://kabanero.io/operations/kabanero-foundation-setup/
There is a link to OKD Install Instructions which takes you to https://docs.okd.io/latest/getting_started/administrators.html.

More specifics on what part of instructions are needed or not needed would be helpful.

This page: https://kabanero.io/architect/

Has empowering developer s with

But should say empowering developers with

A generic outline for what sort of topics need to be covered in the Guides for the Collections is needed to start the writing effort.

We now have Guides that are published on the stage site for kabanero.io. @ralanlittle please review and provide feedback to improve the content.

When trying to diagnose a user issue, it was not apparent to the user how to validate what Kabanero repository and collections were used, and active for this Kabanero instance.

There are two ways: Via the Kanbanero landing page extension in the OKD console, and displaying the configured kabanero CR using the oc cli:

oc get kabanero -n kabanero -o yaml

The above example assumes the configured Kabanero instance is installed in the kabanero namespace.

@davco01a commented on Mon Sep 23 2019

On this page, in the Installation section:

https://kabanero.io/docs/ref/general/installing-kabanero-foundation.html

I don't see any mention of copying and modifying:

https://github.com/kabanero-io/kabanero-operator/blob/master/config/samples/full.yaml

prior to running the install-kabanero-foundation.sh script

@mtamboli commented on Mon Sep 23 2019

Step 3 (which is added recently) of the following doc assumes that the updates are being made to full.yaml. None of the Kabanero install docs talk about how this file is used. https://github.com/kabanero-io/docs/blob/master/ref/general/collection-building.adoc

@bschrammIBM commented on Tue Sep 24 2019

I opened #103 to track this update in the /docs repo.

@alohr51 commented on Tue Sep 24 2019

@bschrammIBM is #103 a duplicate issue of this? We should try to not duplicate issues. You can move/transfer this issue to the docs repo if that was your goal (bottom right of this issue)

@kaczyns commented on Tue Sep 24 2019

This page:
https://kabanero.io/docs/ref/general/installing-kabanero-foundation.html
reads to me like a basic getting started / install page. I think that if we try to talk about modifying the default kabanero yaml here it will be confusing for the people that just want to get started. Maybe we could say at the end of the install script section something like:

"This will install Kabanero with default settings using the default collections (link to collections). If you would like to use a different set of collections, see here (link to doc about how to curate the collection)".

That seems like a compromise to me between keeping the page simple for new folks, but also reminding experienced users that they have some editing to do if they want to deploy an Nth Kabanero using collections that they've already curated.

@mtamboli commented on Tue Sep 24 2019

@kaczyns I agree with your comment above to keep the default install simple. But my understanding is that you still need to do some customization (full.yaml git updates for security) before installing Kabanero to be able to use Kabanero CLI later. Can that be done easily later if user wants to use Kabanero CLI?

@kaczyns commented on Tue Sep 24 2019

@mtamboli My understanding is that you can't use the CLI until you've cloned and curated the collections, because Champ will be unable to add himself as an admin to the kabanero-io hosted collections. I don't think there is a reason to customize the configuration (full.yaml) until Champ has curated the collections, and at that time the following things need to be updated:

1. URL of the collection
2. Github org that the admins for the collection are in
3. Github team(s) that admin the colleciton
4. API URL of the github where the org/teams are

It's pretty easy, the user can either edit the Kind: Kabanero that the install produced, on their cluster, or they can delete it and create a new one using the full.yaml as a model. Editing is as simple as oc edit kabanero kabanero (the default name) and then a text editor pops up and they change the url, etc. Or they could edit it in the OKD console.

@mtamboli commented on Tue Sep 24 2019

That helps! So it is matter of getting the documentation at the appropriate place. So collection curation and GitHub setup as part of that is a pre-req for Kabanero CLI? So Install doc can just provide links to those as you mentioned.

@davco01a commented on Thu Sep 26 2019

@mtamboli @kaczyns It may be simple to oc edit kabanero kabanero, but agree with Monica in lieu of clear, sequenced documentation on cloning the index.yaml, copy and modifying full.yaml, setting up git teams and members located in one central, relevant place, it will be a mystery to consumers who want to be able to actually use the functionality of the Kabanero CLI

corresponds to

Publish the Kabanero-management CLI documentation from https://github.com/kabanero-io/kabanero-command-line/README.md

It should be under a Docs>Reference tab.

@mtamboli wants the following edit on this page:
For openshift_master_default_subdomain=my.openshift.master.default.subdomain ./install-kabanero-foundation.sh

surround my.openshift.master.default.subdomain in brackets to indicate it is a variable,
as follows:
openshift_master_default_subdomain=<my.openshift.master.default.subdomain> ./install-kabanero-foundation.sh

This will indicate that the user should enter the name of their subdomain, not the actual words. A line can be added that says "Replace <my.openshift.master.default.subdomain> with the name of your subdomain." to make it super-clear.

Based on feedback from Emily Jiang, the following updates need to be made to https://kabanero.io/guides/collection-microprofile/.

1. (Optional) If you have an enterprise-specific Kabanero Collection Hub, you need the URL to your index file.
   I have no idea what to do with the above sentence. What URL, which index file?

2. Project Structure: link is broken (https://github.com/kabanero-io/guide-collection-microprofile/blob/master/img/guide/microprofile-project-layout.png)

3. Under the section "Creating and updating the application"
   It sounds like you are teaching the user how to fix the error instead of guiding them to populate JAX-RS resources with their business logic. I think it is better to say something like:
   Now it is time to create your business logic. The first thing to do is to add a REST endpoint.

We have a what's new doc that is tied to the website. It will notify website users only once whenever this file is updated with a new version in the front matter

Need this to be updated https://github.com/kabanero-io/docs/blob/master/ref/general/whats-new.md

Install script "install-kabanero-foundation.sh" need to be updated

1. Please update Kabanero install script to reflect latest Kabanero release.
   KABANERO_BRANCH="${KABANERO_BRANCH:-0.1.0}

2. Install script was failing with these errors:

the namespace from the provided object "knative-sources" does not match the namespace "kabanero". You must pass '--namespace=knative-sources' to perform this operation.
the namespace from the provided object "knative-sources" does not match the namespace "kabanero". You must pass '--namespace=knative-sources' to perform this operation.
the namespace from the provided object "knative-sources" does not match the namespace "kabanero". You must pass '--namespace=knative-sources' to perform this operation.
unable to recognize "https://github.com/kabanero-io/kabanero-operator/releases/download/0.1.0/kabanero-operators.yaml": no matches for kind "Config" in version "operator.tekton.dev/v1alpha1"

To workaround above issue, had to remove -n Kabanero from the following command:
oc apply -n kabanero-f https://github.com/kabanero-io/kabanero-operator/releases/download/0.1.0/kabanero-operators.yaml

oc get pods

NAME                                           READY     STATUS    RESTARTS   AGE
kabanero-operator-bf65d8b85-4rfr7              1/1       Running   0          2h
knative-eventing-operator-67cdf5dc9f-fntk6     1/1       Running   0          2h
knative-serving-operator-b64558bbc-blsnq       1/1       Running   0          2h
openshift-pipelines-operator-cfc786cc7-tnkvz   1/1       Running   0          2h
tekton-dashboard-66788444c8-8vh2r              1/1       Running   0          1h
webhooks-extension-d7b4745d6-9tlcx             1/1       Running   0          1h

There are lots of files in the docs repository that don't seem to make any sense to me (at least) ... it seems like there are in here through a project copy of OpenLiberty.

See kabanero-io/kabanero-foundation#82 for updates needed to the https://kabanero.io/docs/ref/general/installing-kabanero-foundation.html page.

In the docs https://github.com/kabanero-io/docs/blob/master/ref/general/kabanero-foundation-setup.adoc#setting-up-the-example-appsody-pipeline
they refer to use the following example https://github.com/appsody/tekton-example.git

The knative service yaml specify imagePull
https://github.com/chilanti/appsody-test-build/blob/master/appsody-service.yaml#L11-L12

image: dev.local/appsody-build-test
imagePullPolicy: Never

Having any string for image is ok and using Never makes sense when working with loading the image locally not using a remote registry.

But the example is using tekton and pushing to a registry, having Never the image will never be downloaded and the Pod fails to run.

Maybe it would be good to have the example on the this docs repo.

I fix the problem by setting the imagePullPolicy to Always or not being presented should also work.

We are in the midst of trying to manually produce the 0.0.2 release of Kabanero until we have a formal release process defined. I don't think we want to define a 1.0.0 release because that implies a level that is GA. We likely need to actually delete the 1.0.0 release that is defined in this repository, and we should replace it with a 0.0.2 when we are ready to cut the release.

When we cut a release we need a way to version the docs for that release. What is our strategy and plan to do that?

After installing Kabanero, the steps documented below are needed before Champ can use the CLI. This needs to be incorporated either in the install scripts, as a post-install script, or included in website doc

https://github.com/kabanero-io/kabanero-security/wiki/Setting-up-the-CLI-backend-app

Jane/Developer starts with appsody which has concept of stacks. CLI example talks about Kabanero collections. At this point, Jane only knows about stacks. We need some explanation on how collections are extension of stacks and so appsody can work with collection repository too.
This explanation also needed for champ doc

FYI, @groeges

This is the Appsody CLI, it sets the default hub url to the Kabanero public hub. The hub can be changed to point to Champ’s hub (or manually use the CLI to change it).
There are current instructions on the Kabanero.io website:
https://kabanero.io/developer/cli/

There are new instructions included in the proposed Getting Started flow.
These instructions need to be reviewed and updated.

Some work in progress notes: https://github.com/kabanero-io/docs/wiki/uninstall-Kabanero

Provide more details about using nip.io when working locally

For example for minishift you can tell user to use the ip address from the ocp console ui

oc console

Locally the browser will open for example https://192.168.64.4:8443/console
Use this value of the ip address 192.168.64 and append .nip.io this will be the value to use for subdomain

openshift_master_default_subdomain=192.168.64.4.nip.io ./install-kabanero-foundation.sh