kabanero-io / docs Goto Github PK
View Code? Open in Web Editor NEWKabanero documentation. This repo will be archived soon.
Home Page: https://kabanero.io/docs/
License: Apache License 2.0
Kabanero documentation. This repo will be archived soon.
Home Page: https://kabanero.io/docs/
License: Apache License 2.0
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.
Rather than have a guide for each collection, we decided to write guides that covered the developer experience of using different collections with either:
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:
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
secrets:
- name: my-docker-secret
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
https://www.eclipse.org/codewind/docindex.html
The Codewind documentation requires review and updating.
Need to ensure:
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.
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:
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
See #32
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
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.
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:
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:
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:
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/.
(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?
Project Structure: link is broken (https://github.com/kabanero-io/guide-collection-microprofile/blob/master/img/guide/microprofile-project-layout.png)
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
Please update Kabanero install script to reflect latest Kabanero release.
KABANERO_BRANCH="${KABANERO_BRANCH:-0.1.0}
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.