Move tutorial contents out of examples repo

[ahmetb]

The tutorials are now migrated to kubernetes.io website. Setting up redirection
pointers from the README files here to keep maintaining these tutorials at a
single place.

/assign @jeffmendoza
cc: @sebgoa

Fixes #12.

Signed-off-by: Ahmet Alp Balkan ahmetb@google.com

[jeffmendoza]

Looks like the tutorials on k8s.io are pointing to kubernetes/examples. https://kubernetes.io/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/ and https://kubernetes.io/docs/tutorials/stateful-application/cassandra/

# clone the example repository
git clone https://github.com/kubernetes/examples
cd examples

Those should have the config files on the website, and use commands such as:

kubectl create -f https://k8s.io/docs/tutorials/stateful-application/web.yaml

I can't get that to work for some reason, maybe some jekyll configs need to be updated, should return the file: https://github.com/kubernetes/kubernetes.github.io/blob/master/docs/tutorials/stateful-application/web.yaml

[jeffmendoza]

Oh, now I see that you are just removing the text, and leaving the config files here. Is there a reason why? What is the latest?

[ahmetb]

@jeffmendoza We moved examples/ directory from the main repository for cleanup (there's still a lot of things in staging/ folder) however the main purpose of this repo is to contain source files, Dockerfiles and manifests for tutorials.

The problem with README.md files for tutorials is that we have to bounce visitors off k8s.io website to this GitHub repository to follow the tutorials. That is not particularly optimal, and also this further separates the contents of the tutorial vs the source code that builds the example app/image.

I am still trying to figure out how we can sync the manifest files between the text (that's now in docs repository) and the actual source (this repository). But it did not seem urgent enough as most tutorials currently do a copy-paste of the file contents. In the short term, we need to sync those files periodically to the docs repo (we can add a script to the docs repo) and use some sort of {% includecode %} directive.

[jeffmendoza]

Yes, makes sense to put the tutorial text on the website. Why not put the source/dockerfiles/manifests in the website repo as well?

See https://kubernetes.io/docs/tasks/run-application/run-stateless-application-deployment/ it uses {% include code.html language="yaml" file="deployment.yaml" ghlink="/docs/tasks/run-application/deployment.yaml" %} and the command kubectl create -f https://k8s.io/docs/tasks/run-application/deployment.yaml

[ahmetb]

We probably moved too fast with the urge to get the examples out of the main repo. I suppose having manifests and quoted in the tutorial hosted on the docs repo makes sense. However, not so much for the Dockerfiles and other source files.

We can use this area to set up automated/periodical builds on the sample images used in tutorials. We would be less flexible to do as such on the docs repo. (Not to mention, source code/Dockerfile that is not quoted in the tutorial probably just doesn't belong there.)

[sebgoa]

honestly a lot of users will come straight up to the github repo kubernetes/examples and look for the manifest directly.

if you move the manifest to the docs site (it might make the integration with docs better), it will hide that manifests in the docs repo structure.

I am not sure about removing the READMEs entirely here either, because that leaves manifests in there without a README at all.

[sebgoa]

I think that whatever is in this /examples repo should be standalone.

If docs wants to have an auto build that fetches examples from here I think that would be great.

The maintained examples live here and docs automatically pulls the README and manifest from here to deploy docs site in prod.

my 2 cts.

[ahmetb]

honestly a lot of users will come straight up to the github repo kubernetes/examples and look for the manifest directly.

It's a bit hard to believe people just come to kubernetes/examples repo directly given the repo is new.

Historically the examples/ directory has been getting a lot of traffic, probably because k8s.io/docs/samples (which I recently deleted) was listing all examples and sending all the traffic to here.

The maintained examples live here and docs automatically pulls the README and manifest from here to deploy docs site in prod.

I see that standalone repo would be really neat, but creating an import process, just for 3 tutorials sounds like an overkill/overhead. This would introduce more process/scripts to the docs repository. Not to mention, we probably would have to post-process the imported .md files and process them for relative links etc (or make all links absolute).

For https://k8s.io/docs/tasks, we have been even checking in the .yaml files to the docs repo (as that's the only place they're used) and it worked fine.

[jeffmendoza]

The cleanup of examples has been really helpful. Historically the examples have not had a clear direction, either educational or demonstrative. Now we can move the educational examples to be more integrated with the website, and the pure examples should be recreated as Helm charts.

As far as where the manifests for tutorials on the website live, I'm ok with here or in the website repo, as long as it's consistent.

[ahmetb]

Closing this in favor of a new plan:

• We will add a update-imported-tutorials script to the docs repo.
• Tutorials will be imported from this repository and will be maintained here.
• Tutorials in this repository will not use relative links. All links must work on k8s.io website.
• README.md files are mainly meant to be consumed on k8s.io website, so we'll add a notice them here pointing users to the website.
• The script will do some postprocessing (such as removing the redirection notice, adding the DO NOT UPDATE notice and the Jekyll-formatted title:)