proposal: revamp examples

[aogier]

Hi, being a beginner in using this client, I'd like more working examples as they are of invaluable value. Unfortunately this is not the case at the moment because various issues:

• code seems broken/obsolete and definitely not tested (for example spec = client.V1PodSpec() in examples/notebooks/create_configmap.ipynb raise a ValueError)
• despite notebooks/README.md, not every playbook can be run inside a pod because the config loading machinery being used (load_kube vs load_cluster)
• not every examples/ script is available as a python notebook so it's not straightforward to run it under a jupyter pod (which is imho a great idea)

This in my opinion steeps up learning curve or at least does not help new users (as I also am) as it could.

What I'm proposing is:

1. rewrite/renew examples as a jupyter notebook, exploiting this technology in order to ease code development/maintenance
2. make scripts configuration automatically aware of the environment so we can run examples inside or outside a pod. It is a common pattern to ship docs/examples facilities just for the sake of simplicity:

   # examples/load_config.py
   
   from kubernetes import config
   
   # Silly example! It could be better testing for env vars or files
   # and then working/failing accordingly
   try:
       config.load_incluster_config()
   except:
       config.load_kube_config()

3. automatically generate plain python example scripts with jupyter nbconvert so we dev on notebooks but we don't give up on distributing plain scripts
4. put everything under CI using jupyter nbconvert --execute

What do you think? I saw good efforts from other users too (ping @djkonro, @tomplus), could we maybe coordinate on this one?

Thanks in advance, regards!

[tomplus]

Sure, I can help. BTW it's not easy to execute tests under CI pipeline. It'll require to spin up minkube or something similar.

[aogier]

Hi @tomplus, great !

As of now I thought we could move along several axis:

• fixing current notebooks so that they works, ideally either inside or outside a cluster, ideally on py2 and py3. I'v begun something here
• validating CI setup this project already use with tox, /scripts/kube-init.sh can bootstrap the parts we need on travis
• porting every example to notebooks, fixing code if needed
• porting k8s tutorials to notebooks
• scripting various tools:
  • notebook -> script conversion (investigate jupyter processors because output format isn't that cool, also we could put an header etc)
  • for every official documentation source update (eg. tutorials), have something that warn about it so we can update things if needed. As long as every is on github that should be easy

What do you think ? Other ideas ? If you want to work on any of the above let me know

ciao !

[tomplus]

To be honest I prefer scripts rather than notebooks. Scripts can be easily adopted to my code, I can play with them without installing other tools, I can write my own script using an example as a base script etc. On the other hand, notebooks are more explanatory and work great as tutorials (I like your idea to porting k8s tutorials).

Definitely all examples should work and some of them can be tested in CI. I wasn't aware that current Travis runs e2e tests with script/kube-init.sh - it's nice.

[aogier]

I understand your point, and after all I also prefer my IDE rather than the web based jupyter :P

Anyway, I'd like to use notebook because that:

• notebooks are a super-neat way for testing this client from inside a cluster, I mean see at examples/notebooks/docker, you have a ready to go pod you can apply and you don't even need to prepare a local virtualenv ... woww 💃 🍾
• notebook can produce plain scripts via nbconvert, so at the end of the day whoever need/want plain scripts will have them under /examples and they will be happy. And this is in fact something I ultimately want to do.

So why choose a single "source" format ? Basically I don't want any effort to be wasted because scattering, at the moment we have a cartesian product of:

• type: notebooks, scripts (we solve that through conversion)
• supported env: inside cluster, outside cluster (we solve that through a facility)

we also have a Markdown example ! And they're all good, and precious to a noob like me because examples -> people inclusion, so I'd like to try to consolidate a single source of awesomeness without letting anyone behind :)

What do you think ? I think there's plenty of space for doing something genuine and neat :)

[aogier]

@tomplus FYI we have notebooks running and validating under travis (apart btw the rollback one bc #491), kube-init.sh wrapped implementation here via travis/tox, job here 😎

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.