Documentation items that are not as clear as they could be

[cliffbdf]

I am reading "Getting Started with Nulecule”, and it is quite unclear to me. I am a longtime user of docker but new to kubernettes, atomic, and nulecule. If these things are unclear to me, then they are probably unclear to others who are new to nulecule and kubernettes. The confusing items are,

1. "In the Nulecule file, create one or more lists of things under graph."

What can “things” be? Containers? Nulecule apps (whataever that means)? Dockerfiles? What is the “space” that “things” represents?

1. "Remote sources are other Nulecule applications."

What is a “nulecule application”? Is it a sest of containers deployed via a nulecule file? It is not clear what is meant by this.

1. "Each provider will have a key specifying the provider."

What is a “provider”? Is the range of values for “provider” { docker, kubernettes }? What else can it be? And are the providers plugins that are installed? Or are they built into nulecule? What are they?

1. "Put all of the provider files into a directory structure that corresponds to the provider artifacts section in the Nulecule file."

What are “provider artifacts”? In the example they are shown as “pod.json” and “service.json” - are these terms defined by kubernettes? If so, perhaps saying that would provide the context and be very helpful.

Thanks!

Very best,

Cliff

[cdrage]

Hi @cliffbdf !

To be honest, the Nulecule spec documentation is lacking in terms of developer experience. Recently we've done a complete overhaul of our implementation AtomicApp here: atomicapp both projects documentation is interchangeable as our implementation is 1-1 integration of the spec.

Feel free to have a look at our starting guide and our Nulecule file-format guide here: atomicapp :)

Without furtherado however! I'll answer your original questions!

1. The "list of things" is a list of "Nulecules" or containerized applications. See https://github.com/projectatomic/atomicapp/blob/master/docs/nulecule.md for a full example (at the bottom) which lists each atomicapp container.
2. A "Nulecule application" is a packaged application. For example. If you would like to deploy a containerized Gitlab application that requires a datbase you can inherit a mysql nulecule app which already has kubernetes artifacts as well as Docker run commands already integrated for deployment.
3. Each "provider" has a list of files which are the references artifacts / template files. For example:

    artifacts:
      docker:
        - file://artifacts/docker/hello-apache-pod_run
      kubernetes:
        - file://artifacts/kubernetes/hello-apache-pod.json
      openshift:
        - inherit:
          - kubernetes
      marathon:
        - file://artifacts/marathon/helloapache.json

4 . See question 3 :)

We expect to update the Nulecule docs soon to be similar / as good as atomicapp's.

[cliffbdf]

Thank you! This is very helpful!!

On Mar 14, 2016, at 10:35 AM, Charlie Drage notifications@github.com wrote:

Hi @cliffbdf https://github.com/cliffbdf !

To be honest, the Nulecule spec documentation is lacking in terms of developer experience. Recently we've done a complete overhaul of our implementation AtomicApp here: atomicapp https://github.com/projectatomic/atomicapp both projects documentation is interchangeable as our implementation is 1-1 integration of the spec.

Feel free to have a look at our starting guide and our Nulecule file-format guide here: atomicapp https://github.com/projectatomic/atomicapp :)

Without furtherado however! I'll answer your original questions!

The "list of things" is a list of "Nulecules" or containerized applications. See https://github.com/projectatomic/atomicapp/blob/master/docs/nulecule.md https://github.com/projectatomic/atomicapp/blob/master/docs/nulecule.md for a full example (at the bottom) which lists each atomicapp container.

A "Nulecule application" is a packaged application. For example. If you would like to deploy a containerized Gitlab application that requires a datbase you can inherit a mysql nulecule app which already has kubernetes artifacts as well as Docker run commands already integrated for deployment.

Each "provider" has a list of files which are the references artifacts / template files. For example:

artifacts:
  docker:
    - file://artifacts/docker/hello-apache-pod_run
  kubernetes:
    - file://artifacts/kubernetes/hello-apache-pod.json
  openshift:
    - inherit:
      - kubernetes
  marathon:
    - file://artifacts/marathon/helloapache.json

See question 3 :) We expect to update the Nulecule docs soon to be similar / as good as atomicapp https://github.com/projectatomic/atomicapp's.

— Reply to this email directly or view it on GitHub https://github.com/projectatomic/nulecule/issues/202#issuecomment-196337594.

[goern]

@cdrage would you like to put your comment into the README (in parts or as a whole)?

[cliffbdf]

Sure! Actually, what I can offer to do is to augment the README.md with a little more explanation on these things. I am very practiced at writing things clearly (have written four technical books) so clear writing is what I can offer - although the current README is actually pretty clear - it just needs a little more explanation of some things.

On Mar 17, 2016, at 4:16 PM, Christoph Görn notifications@github.com wrote:

@cdrage https://github.com/cdrage would you like to put your comment into the README (in parts or as a whole)?

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/projectatomic/nulecule/issues/202#issuecomment-198064764