Add initial IBM Cloud Functions examples #20
Conversation
|
@mrutkows thanks. Will try to review next week. |
|
@mrutkows thanks for the update, let me know once its complete, I'll hold of reviewing until then. |
|
@mhdawson After some delay to track down an issue... I believe it is now ready for a review. Please note that I updated the top-level README to alphabetize the listed technpologies and move gcr to what I believe is the correct category. |
| # this work for additional information regarding copyright ownership. | ||
| # The ASF licenses this file to You under the Apache License, Version 2.0 | ||
| # (the "License"); you may not use this file except in compliance with | ||
| # the License. You may obtain a copy of the License at |
There was a problem hiding this comment.
This part of the licence does not seem quite right.
There was a problem hiding this comment.
unless the README.md is a copy from somewhere else ?
|
|
||
| ### ZIP action | ||
|
|
||
| The NodeJS runtime, where your function executes, has a [fixed list of installed NPM modules](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-runtimes#openwhisk_ref_javascript_environments). If you require more NPM modules, you can ZIP them with your action code. |
There was a problem hiding this comment.
I think what I understand later is that you zip up some files, but that does not necessarily include the npm modules themselves but instead a package.json file that list the dependencies. I think the current wording might confuse people into thinking the zip will include the npm modules.
There was a problem hiding this comment.
Nevermind reading again I see the npm modules are zipped up.
| * [Hello HTML](#hello-html) - *create HTML content* | ||
| * [Using query parameters](#using-query-parameters) | ||
| * [Atomic SVG](#atomic-svg) - *create SVG content* | ||
| * [Sequencing actions](sequences.md#sequencing-actions) - *easily create sequences of existing actions* |
There was a problem hiding this comment.
Seems a bit strange that all of the sections except this one are in the doc if you read through it.
There was a problem hiding this comment.
Seems a bit strange that all of the sections except this one are in the doc if you read through it.
Yeah, Sequences are bordering on an intermediate topic... had hoped to eventually make sequences.md into a second chapter dedicated to higher order examples. Plus I had it already as a separate file and wanted to add it at the last minute at the end of the day I had reserved to complete these.
There was a problem hiding this comment.
@mhdawson FYI, found time at the end of last week to move the content from sequences.md to README.md ... latest commit reflects this.
|
|
||
| If you like using ICF, you can sign-up for the *free*, self-study [Cognitve Class.ai](https://cognitiveclass.ai/) course and get [Acclaim badge](https://www.youracclaim.com/org/ibm/badge/serverless-computing-using-cloud-functions-developer-i) certified: | ||
| * [Serverless Computing using Cloud Functions - Developer I course](https://cognitiveclass.ai/courses/serverless-computing-using-cloud-functions-developer-1) | ||
|
|
There was a problem hiding this comment.
Would it also make sense to add a reference to the full docs here as well ?
There was a problem hiding this comment.
Would it also make sense to add a reference to the full docs here as well ?
If I find time, I would love to do a follow-on PR that sets up the readme to introduce a few more advanced topic examples and can add more canonical links (including granular ones for each use case where possible).
|
@mhdawson Thanks for the find... changed the license headers to vanilla Apache 2 boilerplate for the two markdown files. |
| 7. Invoke the action with parameters (block for `-r` result): | ||
|
|
||
| ```bash | ||
| ic fn action invoke namegen -p race human -p gender female -r |
There was a problem hiding this comment.
| ic fn action invoke namegen -p race human -p gender female -r | |
| ibmcloud fn action invoke namegen -p race human -p gender female -r |
There was a problem hiding this comment.
@rodion-arr Thanks for finding the last CLI command alias ;)
Co-authored-by: Rodion Abdurakhimov <[email protected]>
Co-authored-by: Rodion Abdurakhimov <[email protected]>
Co-authored-by: Rodion Abdurakhimov <[email protected]>
Co-authored-by: Rodion Abdurakhimov <[email protected]>
|
Retargeted to |
There was a problem hiding this comment.
I've gone through and provided edits to this PR as it stands for completeness, though I don't think it can land how it currently exists.
The intent of this repository is to provide git clone-able full code examples of projects that use Node.js. This is a strong and comprehensive tutorial, but that specific content is outside of the scope of the nodejs/examples repository.
Ideally, I'd really love to see the various examples provided within moved into directories that follow a similar structure to cli/yargs/countEntriesInDirectory where I could git clone and then deploy it with the prose parts of each section in the README of the directory where the code exists as it would be if it were "final" and prod ready. Additionally, going above and beyond, having the deployment commands as npm scripts would be super awesome.
Ideally, this request won't be a ton of additional work - you've got a bunch of examples here, they just need to be effectively built out as actual projects and committed as such in addition to refactoring them out of the README once they've been projectized.
cloud/README.md
Outdated
| - Cloud-specific (AWS, GCP, Azure, IBM Cloud, DigitalOcean, Alibaba Cloud, Oracle Cloud) | ||
| - Tiny Clouds (Netlify, Now, Glitch, CloudFlare Workers, Heroku, Surge, Begin) | ||
| - Containers (Docker, Google Cloud Run) | ||
| - Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework) |
There was a problem hiding this comment.
Feedback:
- Google Cloud Run is built on top of Knative, which is "serverless". I'd prefer to leave Google Cloud Run here rather than in containers. Containers are an implementation detail of them rather than the whole thing.
- Please restore the original order of Serverless Framework and OpenFaaS being first.
- I'd prefer to not link directly to specific example sections since this is supposed to be a list of examples rather than what we've got.
- Please remove "MS" - Azure Functions is the name of the platform. There are zero places where anything by Microsoft is prefixed by "MS".
There was a problem hiding this comment.
Feedback:
* Google Cloud Run is built on top of Knative, which is "serverless". I'd prefer to leave Google Cloud Run here rather than in containers. Containers are an implementation detail of them rather than the whole thing.
Will revert GCR back; made this change since it is not billed as a Serverless solution/platform despite using Knative underneath (from GCR product page: "Fully managed compute platform for deploying and scaling containerized applications quickly and securely.") and there is only one mention of serverless on
* Please restore the original order of Serverless Framework and OpenFaaS being first.
Alphabetical by service/project provider (company) seems to be the most fair way to list; is there a reason to give preference to these 2 solutions?
* I'd prefer to not link directly to specific example sections since this is supposed to be a list of examples rather
Being the first to submit content, had no guidance and assumed "links" are good and that this "cloud" readme would shape up to an index into the specific examples. Will remove.
- Please remove "MS" - Azure Functions is the name of the platform. There are zero places where anything by Microsoft is prefixed by "MS".
Did this simply to preserve the alphabetical (fairness). From Azure one can infer MS of course...
cloud/README.md
Outdated
| - Containers (Docker, Google Cloud Run) | ||
| - Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework) | ||
| - Orchestration (Kubernetes, OpenShift, Terraform) | ||
| - Cloud-specific (Alibaba Cloud, AWS, DigitalOcean, GCP, IBM Cloud, MS Azure, Oracle Cloud) |
cloud/README.md
Outdated
| - Serverless (AWS Lambda, Google Cloud Functions, [IBM Cloud Functions](serverless/ibm-cloud-functions/README.md), MS Azure Functions, OpenFaaS, Serverless Framework) | ||
| - Orchestration (Kubernetes, OpenShift, Terraform) | ||
| - Cloud-specific (Alibaba Cloud, AWS, DigitalOcean, GCP, IBM Cloud, MS Azure, Oracle Cloud) | ||
| - Edge / Tiny Clouds (Begin, CloudFlare Workers, Glitch, Heroku, Netlify, Now, Surge) |
There was a problem hiding this comment.
If we want to do Edge, I'd say that should be a different line item since AFAIK each of the major clouds also all have their own Edge Compute services.
I would classify CloudFlare Workers within the category it's been added to here, but Edge is a loaded term that I think in the context of Cloud has a much more common term.
There was a problem hiding this comment.
If we want to do Edge, I'd say that should be a different line item since AFAIK each of the major clouds also all have their own Edge Compute services.
I would classify CloudFlare Workers within the category it's been added to here, but Edge is a loaded term that I think in the context of Cloud has a much more common term.
Please know that I did not add these entries (they existed already) and I did it since whenever we talk about the future of Serverless Edge computing is a primary direction and CloudFlare is the prime example always referenced.
| <!-- | ||
| # | ||
| # Copyright [2020] [IBM Corporation] | ||
| # | ||
| # Licensed under the Apache License, Version 2.0 (the "License"); | ||
| # you may not use this file except in compliance with the License. | ||
| # You may obtain a copy of the License at | ||
| # | ||
| # http://www.apache.org/licenses/LICENSE-2.0 | ||
| # | ||
| # Unless required by applicable law or agreed to in writing, software | ||
| # distributed under the License is distributed on an "AS IS" BASIS, | ||
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| # See the License for the specific language governing permissions and | ||
| # limitations under the License. | ||
| # | ||
| --> | ||
|
|
||
| <!-- | ||
| # Contributors: | ||
| # - Matt Rutkowski, IBM | ||
| --> |
There was a problem hiding this comment.
The code in this repository is already licensed as MIT. I'd prefer to not dual-license or sub-license files within the repository.
There was a problem hiding this comment.
The code in this repository is already licensed as MIT. I'd prefer to not dual-license or sub-license files within the repository.
The majority of this content is copied from a public repo. licensed under Apache 2.
|
|
||
| # IBM Cloud Functions using Node.js | ||
|
|
||
| These examples will show you how to take Node.js functions and deploy and run them within the IBM Cloud Functions (ICF) Serverless platform. Further examples will show you how to take advantage of some of ICF's built-in features to easily realize the true power of Serverless against some of its top use cases. |
There was a problem hiding this comment.
Serverless platform. Further
Please use single spaces after periods.
| ```bash | ||
| ibmcloud fn action create split funcs.js --main split | ||
| ``` | ||
|
|
||
| ```bash | ||
| ibmcloud fn action create reverse funcs.js --main reverse | ||
| ``` | ||
|
|
||
| ```bash | ||
| ibmcloud fn action create join funcs.js --main join | ||
| ``` |
There was a problem hiding this comment.
Please remove the four-space indent.
| The function `split` takes the single string `hello world` and splits it into a JSON map of the individual `strings` using the space character as the delimiter. | ||
|
|
||
| ```bash | ||
| ibmcloud fn action invoke split --result --param text "Hello world" | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Sample output:</summary> | ||
| ```json | ||
| { | ||
| "words": [ | ||
| "Hello", | ||
| "world" | ||
| ] | ||
| } | ||
| ``` | ||
| </details> | ||
|
|
||
| The function `reverse` takes a JSON array of `strings` and reverses the characters in each. | ||
|
|
||
| ```bash | ||
| ibmcloud fn action invoke reverse --result --param words '["hello", "world"]' | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Sample output:</summary> | ||
| ```json | ||
| { | ||
| "words": [ | ||
| "olleh", | ||
| "dlrow" | ||
| ] | ||
| } | ||
| ``` | ||
| </details> | ||
|
|
||
| The function `join` takes the JSON array of `strings` and concatenates them back into a space-delimited string. | ||
|
|
||
| ```bash | ||
| ibmcloud fn action invoke join --result --param words '["hello", "world"]' | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Sample output:</summary> | ||
| ```json | ||
| { | ||
| "text": "hello world" | ||
| } | ||
| ``` | ||
| </details> |
There was a problem hiding this comment.
Please remove the four-space indent.
There was a problem hiding this comment.
Please remove the four-space indent.
I need this to preserve code snippets and paragraphs to be included under the numbered bullets as intended.
| ```bash | ||
| ibmcloud fn action create reverse_words --sequence split,reverse,join | ||
| ``` |
There was a problem hiding this comment.
Please remove the four-space indent.
There was a problem hiding this comment.
Please remove the four-space indent.
I need this to preserve code snippets to be included under the numbered bullets as intended.
| ```bash | ||
| ibmcloud fn action invoke reverse_words --result --param text "hello world" | ||
| ``` | ||
|
|
||
| ```json | ||
| { | ||
| "text": "olleh dlrow" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Please remove the four-space indent.
There was a problem hiding this comment.
Please remove the four-space indent.
I need this to preserve code snippets to be included under the numbered bullets as intended.
| - By convention, the `main` function is called. You can always alias "main" to any function in your `.js` file. | ||
| - **No build step**. Runtimes for all supported languages are already deployed in ICF server clusters waiting for your function to be deployed and invoked. | ||
| - **Node.js runtime inferred**. The Node.js runtime was inferred via the function's `.js` extension. ICF will always use the latest supported Node.js runtime version unless you explicitly set another version with the `--kind` flag. | ||
| - **Package dependencies as ZIP files**. Complex actions can be constructed by packaging required NPM modules within a ZIP file. |
|
@bnb I need (irony) inline html (only) to allow for large output to be hidden unless the developer cares to compare their output to a sample. Otherwise, we want to hide it (as a dropdown) to not clutter the actual CLI commands and make the README appear overly long and complicated.
|
|
@bnb if we can update the linter to allow so the README looks clean and if I add subdirs. (1 per each unique example (.js, and .json if applicable) is that enough?
|
|
Functional .js snippets and supporting .json now in separate subdirs (1 per unique example). |
|
Please note that the README instructs still asks the developer to create the functional files wherever they happen to be in their terminal... If the expectation (not clear to me) is that the developer would clone this entire repo., then one could provide directory relative instructions, but had assumed developers would "pick and choose" which tech/examples they would try and not require them to clone the entire repo. which could get quite large given the scope being planned |
|
@bnb when you get a moment, let's discuss this. If there is anything else needed, I can do so, otherwise, it should be good to go? Thanks!!! ❤️ |
|
@joesepi was planning on taking a look next week when I'm back from OOO 👍🏻 |
| <!-- | ||
| Copyright 2020 IBM Corporation | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | ||
| --> | ||
|
|
||
| <!-- | ||
| # Contributors: | ||
| # - Matt Rutkowski, IBM | ||
| --> |
There was a problem hiding this comment.
This license header shouldn't be here since the code is in an open-source repo in the Node.js GitHub organization that's already permissibly licensed.
|
@joesepi it looks like a lot of the feedback I've given previously in the PR (specifically in the README) hasn't been addressed 😬 So, being totally upfront: the content in the README is really good and too comprehensive/tutorial-esque for this repository. My recommendation here would be to strip out the README here and put it into an article that we publish once this PR is merged and replace the current README that's more along the lines of a typical OSS project REAMDE that you'd expect to see on GitHub / npm. This is an example specific to IBM Cloud Functions, and here are a few generic examples of the style I'm talking about. More than happy to help how I can on this - pairing, advice, etc. |
|
Okay. That makes sense. I'll look at this as soon as I can and help get it over the finish line. I like the idea of a blog post too. |
First drop of of NodeJS examples for IBM Cloud Functions (ICF) with background info. seeking to address issue #15.
Please feel free to assign the issue to me, as well as this PR.