Add documentation for container checkpointing feature (KEP 2008)

[adrianreber]

Pull request for KEP 2008:

• Add Forensic Container Checkpointing KEP enhancements#1990
• Forensic Container Checkpointing enhancements#2008
• Minimal checkpointing support kubernetes#104907

[netlify]

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	7db58a5
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/6242ae38d9c15e0008161012

[k8s-ci-robot]

Welcome @adrianreber!

It looks like this is your first PR to kubernetes/website 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/website has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[nate-double-u]

/assign

[sftim]

@adrianreber thanks for this

Given that the feature is only available by directly interacting with a kubelet via HTTP, I suggest you start by writing a reference page about how to checkpoint a container via that API (to go inside https://kubernetes.io/docs/reference/node/).

I suggest that you document the body, or perhaps query string (I haven't looked) for an HTTP request that triggers a checkpoint. You should also document the local paths that the kubelet writes to (as per the existing PR), and the format of the checkpoint image.

At this stage, I wouldn't add any concept page. You could however link to that reference page from https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/). You might think it'd be better to link from the container page, and maybe eventually we would. For this early feature I want readers interested in checkpointing to be clear that you have to have a Pod in order to checkpoint one of its containers.

Please avoid linking to a KEP except for further reading at the end of a page. The aim of documentation is so that readers don't need to refer to the source code or the KEP.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please ask for approval from nate-double-u after the PR has been reviewed.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• content/en/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sftim]

An example of how we document API operations:
https://kubernetes.io/docs/reference/kubernetes-api/policy-resources/resource-quota-v1/#Operations

You don't have to match that style exactly; however, it'd be helpful if any new reference docs are broadly along those lines.

[adrianreber]

@sftim Thanks for your ideas. Will try to rework this PR.

[adrianreber]

@sftim I was thinking a bit more about your suggestions.

My understanding is that I should document the API, that make sense. Should I not include any general information about checkpointing as currently in this PR in the concept page. If I should not include it in a concept page, should it be somewhere else? Next to the API documentation or not at all?

[sftim]

Should I not include any general information about checkpointing as currently in this PR in the concept page. If I should not include it in a concept page, should it be somewhere else? Next to the API documentation or not at all?

I recommend being a little more terse - it's OK in reference documentation to say that the actual checkpointing implementation depends on the container runtime (which I believe is true) and to define only what CRI expects from that implementation.
Eg:

• format of checkpoint archive
• the archive path that the kubelet passes to the container runtime via CRI

As an example, I'd expect that you'd keep:

Checkpointing a container is the functionality to create a stateful copy of a running container. The stateful copy of the container can be moved to another system and after restore the container will continue to run at exactly the same point it was checkpointed. The concept of checkpointing a container and restoring a container can be seen as pausing and unpausing a container with the possibility to transfer the container to another system between pausing and unpausing.

Unless someone writes a blog about it, though, there'd be no mention yet of the term “forensic” in that initial reference page (related: I'd assume that it's not very useful to take such evidence to a court of law and then have to explain that the feature that generated it is still alpha). All that should change if / when the checkpointing feature is scheduled to move to beta; we want production-quality docs for beta features.

[sftim]

Thanks @adrianreber

I hope all these suggestions are useful. I haven't explained all of them in detail; feel free to query anything you're not sure about.

Feedback was incorporated

[sftim]

/retitle Add documentation for container checkpointing feature (KEP 2008)

[sftim]

Also: you're well ahead of the deadline! Nice work in getting reviewable changes in this early.

[adrianreber]

Thanks for your suggestions. I tried to include all of them.

[tengqm]

/hold

@adrianreber Feel free to remove the hold when the upstream changes are merged.

[sftim]

/unhold

[nate-double-u]

/sig node
Could someone from @kubernetes/sig-node-pr-reviews take a look at this? (or suggest someone else for a tech review?)

[nate-double-u]

Just following up, could someone from @kubernetes/sig-node-pr-reviews take a look at this? (or suggest someone else for a tech review?)

[sftim]

Previews:

• Feature Gates
• Kubelet Checkpoint API

[tengqm]

@sftim Why remove the hold? The upstream change kubernetes/kubernetes#104907 is still under review. The hold was to avoid accidental merge of this PR. Am I missing something?

[sftim]

Oops. I saw that a PR was merged - but it was the KEP, not the code.
/hold

[k8s-ci-robot]

@adrianreber: PR needs rebase.

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.

[adrianreber]

Closing as it was dropped from 1.24

[nate-double-u]

/milestone clear