Document adding a new runtime kind. #3837

rabbah · 2018-07-03T16:35:40Z

Description

We have received contributions to add PHP, Go, Ruby (#3725) and on the Apache dev list a new runtime for Ballerina.

This PR documents the steps required to add a new runtime to this repo so that it is available to the OpenWhisk deployment. Comments appreciated and welcome, particularly from those who have contributed runtimes recently (@sciabarracom @remore @akrabat).

cc @csantanapr

I'm happy to accept additional improvements to this write up via pull requests and all contributions will receive due credit.

Related issue and scope

I opened an issue to propose and discuss this change (#????)

My changes affect the following components

Types of changes

Bug fix (generally a non-breaking change which closes an issue).
Enhancement or new feature (adds new functionality).
Breaking change (a bug fix or enhancement which changes existing behavior).

Checklist:

I signed an Apache CLA.
I reviewed the style guides and followed the recommendations (Travis CI will check :).
I added tests to cover my changes.
My changes require further changes to the documentation.
I updated the documentation where necessary.

rabbah · 2018-07-03T16:49:24Z

docs/actions-new.md

+packages and third party dependencies is the same from the OpenWhisk platform which is language
+and runtime agnostic.
+
+The canonical unit of execution is a container which implements a specific interface:


we'll need to document this interface...

Would be good to express the required interface in a precise way.

Now digressing a bit ... Going forward I would like to prototype a way where runtime implementations are passed a URL of the attachment and they directly pull the attachment from storage instead of invoker acting as a proxy. For e.g. each runtime can just package curl and upon receiving the url just do a get via curl and stream it to file system. This would be more of optional capability supported by runtime.

So should we have some kind of versioning of the interface now where Invoker can detect what all a runtime t supports and based on that talks to it in a compatible way. For e.g. one way to implement the above change would be to add some capability attribute in runtime manifest and then based on that use a different approach (say use /init/v2) to talk to runtime.

a reason we haven't documented the interface was to retain the ability to make breaking changes... but maybe that ship has sailed. so i've gone ahead and added it here... might be the first time we really make this official.

akrabat · 2018-07-03T17:05:38Z

docs/actions-swift.md

+    return [ "greeting" : "Hello \(name)!" ]
+  } else {
+    return [ "greeting" : "Hello stranger!" ]
+  }


I think that the Swift source code should be indented 4 spaces as per The Swift Programming Language book.

codecov-io · 2018-07-03T17:15:52Z

Codecov Report

Merging #3837 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff           @@
##           master   #3837   +/-   ##
======================================
  Coverage    74.6%   74.6%           
======================================
  Files         138     138           
  Lines        6465    6465           
  Branches      406     406           
======================================
  Hits         4823    4823           
  Misses       1642    1642

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 545161b...efd3df3. Read the comment docs.

remore · 2018-07-05T08:10:21Z

In addition to this proposal, I have one more thing I have to add here: although I believe the current Ruby Runtime should be functionally acceptable (as test suites including canonical test suite passed), however I still don't fully figure out how following input variables except for the "value" key are processed after /run method returns the result:

# An example input values to /run endpoint
  {
    "activation_id":    "91f9fa332a424e35b9fa332a423e35fd",
    "action_name":      "/guest/myAction",
    "deadline":         "1526980345727",
    "api_key":          "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP",
    "value":            {\"message\":\"hello\"},
    "namespace":        "guest"
  }

Any pointer or reference for this might be also helpful for anyone new to here like me. Except for this, I don't think there is any missing parts necessary for runtime development.

mpmunasinghe · 2018-07-06T05:38:52Z

docs/actions-new.md

+└── tests
+    └── src              # tests suits...
+        └── ...          # ... which extend canonical interface plus additional runtime specific tests
+```


Should we add gradle - docker.gradle into the runtime repository structure as well.

if you use the docker skeleton repo as the starting point, you'll inherit the gradle build including the docker.gradle settings --- these are meant to help with failing docker commands.

rabbah · 2018-07-06T05:47:21Z

@remore take a look at the latest commits - do they help?

dgrove-oss

One awkward sentence, but otherwise seems fine. I'll hold off merging to give you a chance to edit it.

dgrove-oss · 2018-07-07T00:12:26Z

docs/actions-new.md

+OpenWhisk supports [several languages and runtimes](actions.md#languages-and-runtimes) but
+there may be other languages or runtimes that are important for your organization, for which
+you want tighter integration with the platform. Adding a new language, or runtime with bespoke
+packages and third party dependencies is the same from the OpenWhisk platform which is language


Something off in this sentence. Here's an attempt to maybe fix it..

Adding a new language, or runtime with bespoke packages and third party dependencies, is the same as a supported language from the perspective of the OpenWhisk platform which is language

Thanks for the feedback - I attempted a rewording in the last commit.

remore · 2018-07-08T01:45:53Z

@rabbah It looks more than perfect to me. Thank you for this definitive and informative write-up. This will for sure give us decent understanding to get started to develop language runtime.

Document the steps required to add a new runtime kind to the main repo so that it is available to the OpenWhisk deployment.

rabbah force-pushed the docs branch from 4c38c49 to 7c15487 Compare July 3, 2018 16:37

rabbah commented Jul 3, 2018

View reviewed changes

rabbah added documentation review Review for this PR has been requested and yet needs to be done. labels Jul 3, 2018

rabbah force-pushed the docs branch from 6df9799 to 4e5208e Compare July 3, 2018 16:54

akrabat reviewed Jul 3, 2018

View reviewed changes

rabbah force-pushed the docs branch from 4e5208e to 41860e1 Compare July 3, 2018 17:09

remore mentioned this pull request Jul 5, 2018

add a few footnotes rabbah/openwhisk#11

Closed

rabbah force-pushed the docs branch 4 times, most recently from 8e6dd0a to 2fba6ed Compare July 6, 2018 04:42

mpmunasinghe reviewed Jul 6, 2018

View reviewed changes

rabbah assigned dgrove-oss Jul 6, 2018

dgrove-oss approved these changes Jul 7, 2018

View reviewed changes

rabbah added 7 commits July 7, 2018 10:42

Document adding a new runtime kind.

a3226bd

Fix count.

3c90499

White space formatting.

740d52e

Add init/run/logs protocol.

ae3d798

Add note about testing.

55931dc

Add example of manifest entry and required test action.

2787295

Word-smithing and spell check.

efd3df3

rabbah force-pushed the docs branch from 2fba6ed to efd3df3 Compare July 7, 2018 15:21

dgrove-oss merged commit 9c05de4 into apache:master Jul 7, 2018

BillZong pushed a commit to BillZong/openwhisk that referenced this pull request Nov 18, 2019

Document adding a new runtime kind. (apache#3837)

a6fa598

Document the steps required to add a new runtime kind to the main repo so that it is available to the OpenWhisk deployment.

Document adding a new runtime kind. #3837

Document adding a new runtime kind. #3837

Uh oh!

Conversation

rabbah commented Jul 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issue and scope

My changes affect the following components

Types of changes

Checklist:

Uh oh!

rabbah Jul 3, 2018

Choose a reason for hiding this comment

Uh oh!

chetanmeh Jul 4, 2018

Choose a reason for hiding this comment

Uh oh!

rabbah Jul 5, 2018

Choose a reason for hiding this comment

Uh oh!

akrabat Jul 3, 2018

Choose a reason for hiding this comment

Uh oh!

codecov-io commented Jul 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

remore commented Jul 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mpmunasinghe Jul 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rabbah Jul 6, 2018

Choose a reason for hiding this comment

Uh oh!

rabbah commented Jul 6, 2018

Uh oh!

dgrove-oss left a comment

Choose a reason for hiding this comment

Uh oh!

dgrove-oss Jul 7, 2018

Choose a reason for hiding this comment

Uh oh!

rabbah Jul 7, 2018

Choose a reason for hiding this comment

Uh oh!

remore commented Jul 8, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

rabbah commented Jul 3, 2018 •

edited

Loading

codecov-io commented Jul 3, 2018 •

edited

Loading

remore commented Jul 5, 2018 •

edited

Loading

mpmunasinghe Jul 6, 2018 •

edited

Loading