Point the old bootstrapping tutorial URL at new StatefulSet docs

[janetkuo]

cc @bprashanth @erictune @foxish @kow3ns @enisoc @kubernetes/sig-apps

This change is

[0xmichalis]

Shouldn't we fix terminationGracePeriod for these fixtures not to be zero?

[janetkuo]

Done

[enisoc]

Is the main purpose of this tutorial to teach users how to run a VM-like workload? Or is it to demonstrate StatefulSet patterns? If it's the latter, I think there will be a lot of overlap with #1722 which uses the same patterns, but for MySQL.

[janetkuo]

@enisoc the main purpose of this tutorial is teaching users how Kubenetes + pods are different from VMs, based on http://kubernetes.io/docs/user-guide/petset/bootstrapping/, and deprecating the bootstrapping guide

[enisoc]

OK in that case I'll try to minimize overlap in my tutorial.

[smarterclayton]

This is not necessarily new to this change, but the topic of this item is "VM-style workload" but nothing in the first 40 lines explains why that is. A sentence in the overview or objectives that explains how the title relates to what is being shown would be good.

[steveperry-53]

I'm starting a writing review now.

[steveperry-53]

See this commit for suggested changes.

[enisoc]

Reviewed 7 of 8 files at r1, 2 of 2 files at r2, 1 of 1 files at r5.
Review status: all files reviewed at latest revision, 10 unresolved discussions, some commit checks failed.

---

_data/tutorials.yml, line 56 at r5 (raw file):

- title: Stateful Applications
  section:
  - title: Running a VM-style workload using Stateful Set

Merge StatefulSet into one word in title and URL.

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 29 at r5 (raw file):

* Learn about the runtime initialization of StatefulSets.

* Run a VM-style workload by using a StatefulSet and a Kubernetes a feature called

Remove extra "a" before "feature".

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 51 at r5 (raw file):

* Your Kubernetes cluster must be running Kubernetes version 1.5 or later.

* Familiarize yourself with the terminology in

Add "the" at the end.

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 73 at r5 (raw file):

To further simulate a VM, a Pod needs a way to initialize its user environment
when the the Pod starts. Also, tools like `kubectl exec` must not be allowed to

Double "the".

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 84 at r5 (raw file):

Instead of guaranteeing that containers will not be restarted, Kubernetes provides
a way to ensure that when a container stops and restarts, all of of the state

Double "of".

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 201 at r5 (raw file):

In this portion of the tutorial, you create a StatefulSet of nginx servers, and
you make one of them a master. The other nginx servers will proxy requests to
the master. See

Add "the" at the end.

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 315 at r5 (raw file):

* Write the config to a `hostPath` volume shared with the parent StatefulSet.

**Important:** In practice all Pods should query their peers for the current

We should elaborate on why this is important, especially since my replicated MySQL tutorial does the opposite. The difference is in this case you're allowing the master to change dynamically, whereas mine requires that the master is always index 0.

---

docs/tutorials/stateful-application/vm-style-workload-using-stateful-set.md, line 323 at r5 (raw file):

{% capture whatsnext %}

* You can deploy some example StatefulSets found

TODO: Add a link to Replicated Stateful Application tutorial.

---

Comments from Reviewable

[enisoc]

Review status: all files reviewed at latest revision, 11 unresolved discussions, some commit checks failed.

---

docs/tutorials/stateful-application/statefulset_vm.yaml, line 36 at r5 (raw file):

                    "/bin/sh",
                    "-c",
                    "for d in usr lib etc; do cp -vnpr /$d/* /${d}mnt; done;"

The overall script should somehow exit with a non-zero error code if the whole process didn't succeed. You don't want to run the real workload if the initialization was incomplete. In Bash you can just add set -e at the beginning of the script. I'm not sure if that's guaranteed to work in whatever /bin/sh refers to.

In general, this approach of trying to merge in potential changes from the image (with cp --no-clobber) after the PVC has been initialized once before is dangerous. Suppose you let everything initialize, then delete a conf.d file that contains default login credentials. A subsequent Pod restart will restore that file, creating a vulnerability. This example also doesn't account for /var being lost between Pod reschedulings, which can cause data loss and other unexpected behavior.

At the least, we should warn that you shouldn't actually do this; it's just a toy example to demonstrate some concepts. A step further would be to do nothing at all if the PVC has ever been initialized before. That would at least be safer, although it means you should never change the image.

Personally my recommendation is to drop this tutorial altogether for now. If there are still concepts we want to teach that aren't covered in other tutorials, we should start over and rethink how to present them in a less misleading way. I suspect I'm in the minority in that so I'll defer to the wisdom of the team.

---

Comments from Reviewable

[janetkuo]

from @enisoc: Personally my recommendation is to drop this tutorial altogether for now.

@erictune @foxish @kow3ns thoughts?

[enisoc]

To summarize: we discussed this offline and agreed to remove the VM-style tutorial for now because our other new StatefulSet tutorials cover the important concepts with use cases that have clearer motivations.

This PR will be repurposed to just point the old bootstrapping tutorial URL at new StatefulSet docs.

[janetkuo]

PR & title updated, PTAL

[foxish]

LGTM

[devin-donnelly]

@janetkuo, @enisoc, @foxish, @erictune, @kow3ns: I think we should absolutely add this note at the top of the documentation, but not delete the doc itself--it still applies to 1.4 users.

[steveperry-53]

If we're going to say this document is deprecated but can still apply, then we need to keep the content of the document.

[devin-donnelly]

Yep. I'm suggesting below that we do not actually delete the content.

[enisoc]

@devin-donnelly I think it would make sense to keep the doc if it was helping 1.4 users to maintain existing PetSets (like if it was a Task page describing how to do a manual rolling update), but to me the point of this particular doc is encouraging users to adopt PetSet for new use cases. Since PetSet is deprecated, our plan was to discourage against creating new PetSets and instead recommend upgrading to 1.5+ and using StatefulSets.

[devin-donnelly]

@enisoc I understand. The only users I feel like we might miss are those that don't want to risk upgrading off 1.4 but still want to use PetSet (despite it being Alpha). I don't know if there are a lot of those users out there; any insight?

[devin-donnelly]

@enisoc After a close reading, I strike my objection. Is there existing documentation that's a more basic "PetSet Guide" that needs to be marked as deprecated, however?

[steveperry-53]

@janetkuo Would you like to squash commits before we merge this?

[enisoc]

@devin-donnelly Yeah I think user-guide/petset fits your description for the basic guide that should probably be kept with just a deprecation warning at the top.

[enisoc]

existing*

[enisoc]

And should we link "migrate ..." directly to the PetSet upgrade task?

[devin-donnelly]

Done and done.

[enisoc]

I didn't see a PR yet for the above so created #1874

[devin-donnelly]

I'll go ahead and merge this.