CRD versioning Public Documentation #8834
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mbohlool
added
the
do-not-merge/hold
|
Deploy preview for kubernetes-io-vnext-staging processing. Built with commit 8e5dc60 https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/5b2433edb13fb12a880b3d57 |
k8s-ci-robot
added
the
size/L
k8s-ci-robot
added
the
cncf-cla: yes
|
I rebased to resolve conflicts. |
k8s-ci-robot
added
size/XL
mbohlool
changed the title
k8s-ci-robot
added
size/XXL
k8s-ci-robot
added
size/L
|
/cc @sttts Please take a look. |
|
/cc @liggitt please take a look |
|
@mbohlool: GitHub didn't allow me to request PR reviews from the following users: a, look, please, take. Note that only kubernetes members and repo collaborators can review this PR, and authors cannot review their own PRs. In response to this:
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. |
|
When this is ready for docs review, please edit the title to remove the Placeholder text, and remove the hold. |
sttts
reviewed
Jun 7, 2018
| {{% /capture %}} | ||
|
|
||
| {{% capture body %}} | ||
| Kubernetes standard API types has versioning to let developers extend them and roll out new features. To extend kubernetes with |
There was a problem hiding this comment.
two times "extend" with a different context. For the first one: to let developer evolve APIs without breaking backwards compatibility.
sttts
reviewed
Jun 7, 2018
| Kubernetes standard API types has versioning to let developers extend them and roll out new features. To extend kubernetes with | ||
| Custom Resources, you should be able to do the same by supporting multiple versions of Custom Resources. CustomResourceDefinition API supports a `versions` field that can be used to list all versions for that object. Note that previous `version` field is deprecated and optional but if it is not empty, it must be the first item in the `versions` field. | ||
|
|
||
| For example, a CustomResourceDefinition with two versions would look like this: |
sttts
reviewed
Jun 7, 2018
| Served: true | ||
| # One and only one version must be marked as storage version. | ||
| storage: true | ||
| - Name: v2 |
There was a problem hiding this comment.
would use v1beta1 instead. v1 and v2 are probably not the prime examples for versions without conversions.
sttts
reviewed
Jun 7, 2018
| - ct | ||
| ``` | ||
|
|
||
| If you save the above definition to `my-versioned-crontab.yaml` and create it: |
There was a problem hiding this comment.
I don't get this one.
There was a problem hiding this comment.
expected a "If ..., then ..." sentence.
|
I just rebased and pushed 3 new commits:
PTAL |
added 2 commits
June 15, 2018 14:43
|
I think this is in good shape. Removing the hold and approving. PTAL and lgtm or provide more feedback. Preview at https://deploy-preview-8834--kubernetes-io-vnext-staging.netlify.com/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning/ and sibling topics. Note the reorganization of the TOC. /hold cancel |
k8s-ci-robot
removed
the
do-not-merge/hold
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: mistyhacks The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
sttts
reviewed
Jun 18, 2018
| @@ -103,20 +107,20 @@ Use a custom resource (CRD or Aggregated API) if most of the following apply: | |||
|
|
|||
| Kubernetes provides two ways to add custom resources to your cluster: | |||
|
|
|||
| - [Custom Resource Definitions](/docs/concepts/api-extension/custom-resources/) (CRDs) are easier to use: they do not require any programming in some cases. | |||
| - CRDs are simple and do not always require programming. | |||
There was a problem hiding this comment.
nit: CRDs are simple and can be created without any programming
sttts
reviewed
Jun 18, 2018
| The algorithm used for sorting the versions is designed to sort versions in the | ||
| same way that the Kubernetes project sorts Kubernetes versions. Versions start with a | ||
| `v` followed by a number, an optional `beta` or `alpha` designation, and | ||
| optional additional versioning information. Broadly, a version string might look |
There was a problem hiding this comment.
The third part must be a numeric version as well.
sttts
reviewed
Jun 18, 2018
| When an object is written, it is persisted at the version designated as the | ||
| storage version at the time of the write. If the storage version changes, | ||
| existing objects are never converted automatically. However, newly-created | ||
| or updated objects are created at the new storage version. It is possible for an |
sttts
reviewed
Jun 18, 2018
| When you read an object, you specify the version as part of the path. If you | ||
| specify a version that is different from the object's persisted version, | ||
| Kubernetes returns the object to you at the version you requested, but does not | ||
| modify the persisted object. You can request an object at any version that is |
There was a problem hiding this comment.
"modify" here is ambigious: a) the persisted object is not changed "on disk" b) it is returned without any conversion
sttts
reviewed
Jun 18, 2018
| storage at version `v1beta1` | ||
| 2. You add version `v1` to your CustomResourceDefinition and designate it as | ||
| the storage version. | ||
| 3. You read your object at version `v1beta`, then you read the object again at |
sttts
reviewed
Jun 18, 2018
| version `v1`. Both returned objects are identical except for the apiVersion | ||
| field. | ||
| 4. You create a new object. It is persisted in storage at version `v1`. You now | ||
| have two objects, one of which is at `v1beta`, and the other of which is at |
sttts
reviewed
Jun 18, 2018
|
|
||
| To illustrate this, consider the following hypothetical series of events: | ||
|
|
||
| 1. The storage version is `v1beta`. You create an object. It is persisted in |
|
Lgtm after the typos and nits are fixed. Well done! |
|
/lgtm |
k8s-ci-robot
added
the
lgtm
|
@zparnold lgtm is counter-productive if there are a number of typos. Will you create a follow-up PR to fix them? |
|
|
Thanks @nikhita. |
mdlinville
pushed a commit
that referenced
this pull request
Jun 20, 2018
* CRD versioning Public Documentation * Copyedit Signed-off-by: Misty Stanley-Jones <[email protected]> * Address feedback * More rewrites * Address feedback * Update main CRD page in light of versioning * Reorg CRD docs * Further reorg * Tweak title
mdlinville
pushed a commit
that referenced
this pull request
Jun 27, 2018
* CRD versioning Public Documentation * Copyedit Signed-off-by: Misty Stanley-Jones <[email protected]> * Address feedback * More rewrites * Address feedback * Update main CRD page in light of versioning * Reorg CRD docs * Further reorg * Tweak title
mdlinville
pushed a commit
that referenced
this pull request
Jun 27, 2018
* CRD versioning Public Documentation * Copyedit Signed-off-by: Misty Stanley-Jones <[email protected]> * Address feedback * More rewrites * Address feedback * Update main CRD page in light of versioning * Reorg CRD docs * Further reorg * Tweak title
k8s-ci-robot
pushed a commit
that referenced
this pull request
Jun 27, 2018
* Seperate priority and preemption (#8144) * Doc about PID pressure condition. (#8211) * Doc about PID pressure condition. Signed-off-by: Da K. Ma <[email protected]> * "so" -> "too" * Update version selector for 1.11 * StorageObjectInUseProtection is GA (#8291) * Feature gate: StorageObjectInUseProtection is GA Update feature gate reference for 1.11 * Trivial commit to re-trigger Netlify * CRIContainerLogRotation is Beta in 1.11 (#8665) * Seperate priority and preemption (#8144) * CRIContainerLogRotation is Beta in 1.11 xref: kubernetes/kubernetes#64046 * Bring StorageObjectInUseProtection feature to GA (#8159) * StorageObjectInUseProtection is GA (#8291) * Feature gate: StorageObjectInUseProtection is GA Update feature gate reference for 1.11 * Trivial commit to re-trigger Netlify * Bring StorageObjectInUseProtection feature to GA StorageObjectInUseProtection is Beta in K8s 1.10. It's brought to GA in K8s 1.11. * Fixed typo and added feature state tags. * Remove KUBE_API_VERSIONS doc (#8292) The support to the KUBER_API_VERSIONS environment variable is completely dropped (no deprecation). This PR removes the related doc in release-1.11. xref: kubernetes/kubernetes#63165 * Remove InitialResources from admission controllers (#8293) The feature (was experimental) is dropped in 1.11. xref: kubernetes/kubernetes#58784 * Remove docs related to in-tree support to GPU (#8294) * Remove docs related to in-tree support to GPU The in-tree support to GPU is completely removed in release 1.11. This PR removes the related docs in release-1.11 branch. xref: kubernetes/kubernetes#61498 * Update content updated by PR to Hugo syntax Signed-off-by: Misty Stanley-Jones <[email protected]> * Update the doc about extra volume in kubeadm config (#8453) Signed-off-by: Xianglin Gao <[email protected]> * Update CRD Subresources for 1.11 (#8519) * coredns: update notes in administer-cluster/coredns.md (#8697) CoreDNS is installed by default in 1.11. Add notes on how to install kube-dns instead. Update notes about CoreDNS->CoreDNS upgrades as in 1.11 the Corefile is retained. Add example on upgrading from kube-dns to CoreDNS. * kubeadm-alpha: CoreDNS related changes (#8727) Update note about CoreDNS feature gate. This change also updates a tab as a kubeadm sub-command will change. It looks for a new generated file: generated/kubeadm_alpha_phase_addon_coredns.md instead of: generated/kubeadm_alpha_phase_addon_kube-dns.md * Update cloud controller manager docs to beta 1.11 (#8756) * Update cloud controller manager docs to beta 1.11 * Use Hugo shortcode for feature state * kubeadm-upgrade: include new command `kubeadm upgrade diff` (#8617) Also: - Include note that this was added in 1.11. - Modify the note about upgrade guidance. * independent: update CoreDNS mentions for kubeadm (#8753) Give CoreDNS instead of kube-dns examples in: - docs/setup/independent/create-cluster-kubeadm.md - docs/setup/independent/troubleshooting-kubeadm.md * update 1.11 --server-print info (#8870) * update 1.11 --server-print info * Copyedit * Mark ExpandPersistentVolumes feature to beta (#8778) * Update version selector for 1.11 * Mark ExpandPersistentVolumes Beta xref: kubernetes/kubernetes#64288 * fix shortcode, add placeholder files to fix deploy failures (#8874) * declare ipvs ga (#8850) * kubeadm: update info about CoreDNS in kubeadm-init.md (#8728) Add info to install kube-dns instead of CoreDNS, as CoreDNS is the default DNS server in 1.11. Add notes that kubeadm config images can be used to list and pull the required images in 1.11. * kubeadm: update implementation-details.md about CoreDNS (#8829) - Replace examples from kube-dns to CoreDNS - Add notes about the CoreDNS feature gate status in 1.11 - Add note that the service name for CoreDNS is also called `kube-dns` * Update block device support for 1.11 (#8895) * Update block device support for 1.11 * Copyedits * Fix typo 'fiber channel' (#8957) Signed-off-by: Misty Stanley-Jones <[email protected]> * kubeadm-upgrade: add the 'node [config]' sub-command (#8960) - Add includes for the generated pages - Include placeholder generated pages * kubeadm-init: update the example for the MasterConfiguration (#8958) - include godocs link for MasterConfiguration - include example MasterConfiguration - add note that `kubeadm config print-default` can be used * kubeadm-config: include new commands (#8862) Add notes and includes for these new commands in 1.11: - kubeadm config print-default - kubeadm config migrate - kubeadm config images list - kubeadm config images pull Include placeholder generated files for the above. * administer-cluster/coredns: include more changes (#8985) It was requested that for this page a couple of methods should be outlined: - manual installation for CoreDNS explained at the Kubernetes section of the GitHub project for CoreDNS - installation and upgrade via kubeadm Make the above changes and also add a section "About CoreDNS". This commit also lowercases a section title. * Update CRD subresources doc for 1.11 (#8918) * Add docs for volume expansion and online resizing (#8896) * Add docs for volume expansion going beta * Copyedit * Address feedback * Update exec plugin docs with TLS credentials (#8826) * Update exec plugin docs with TLS credentials kubernetes/kubernetes#61803 implements TLS client credential support for 1.11. * Copyedit * More copyedits for clarification * Additional copyedit * Change token->credential * NodeRestriction admission prevents kubelet taint removal (#8911) * dns-custom-namerserver: break down the page into mutliple sections (#8900) * dns-custom-namerserver: break down the page into mutliple sections This page is currently about kube-dns and is a bit outdated. Introduce the heading `# Customizing kube-dns`. Introduce a separate section about CoreDNS. * Copyedits, fix headings for customizing DNS Hey Lubomir, I coypedited pretty heavily because this workflow is so much easier for docs and because I'm trying to help improve everything touching kubeadm as much as possible. But there's one outstanding issue wrt headings and intro content: you can't add a heading 1 to a topic to do what you wanted to do. The page title in the front matter is rendered as a heading 1 and everything else has to start at heading 2. (We still need to doc this better in the docs contributing content, I know.) Instead, I think we need to rewrite the top-of-page intro content to explain better the relationship between kube-dns and CoreDNS. I'm happy to write something, but I thought I'd push this commit first so you can see what I'm doing. Hope it's all clear -- ping here or on Slack with any questions ~ Jennifer * Interim fix for talking about CoreDNS * Fix CoreDNS details * PSP readOnly hostPath (#8898) * Add documentation for crictl (#8880) * Add documentation for crictl * Copyedit Signed-off-by: Misty Stanley-Jones <[email protected]> * Final copyedit * VolumeSubpathEnvExpansion alpha feature (#8835) * Note that Heapster is deprecated (#8827) * Note that Heapster is deprecated This notes that Heapster is deprecated, and migrates the relevant docs to talk about metrics-server or other solutions by default. * Copyedits and improvements Signed-off-by: Misty Stanley-Jones <[email protected]> * Address feedback * fix shortcode to troubleshoot deploy (#9057) * update dynamic kubelet config docs for v1.11 (#8766) * update dynamic kubelet config docs for v1.11 * Substantial copyedit * Address feedback * Reference doc for kubeadm (release-1.11) (#9044) * Reference doc for kubeadm (release-1.11) * fix shortcode to troubleshoot deploy (#9057) * Reference doc for kube-components (release-1.11) (#9045) * Reference doc for kube-components (release-1.11) * Update cloud-controller-manager.md * fix shortcode to troubleshoot deploy (#9057) * Documentation on lowercasing kubeadm init apiserver SANs (#9059) * Documentation on lowercasing kubeadm init apiserver SANs * fix shortcode to troubleshoot deploy (#9057) * Clarification in dynamic Kubelet config doc (#9061) * Promote sysctls to Beta (#8804) * Promote sysctls to Beta * Copyedits Signed-off-by: Misty Stanley-Jones <[email protected]> * Review comments * Address feedback * More feedback * kubectl reference docs for 1.11 (#9080) * Update Kubernetes API 1.11 ref docs (#8977) * Update v1alpha1 to v1beta1. * Adjust left nav for 1.11 ref docs. * Trim list of old ref docs. * Update Federation API ref docs for 1.11. (#9064) * Update Federation API ref docs for 1.11. * Add titles. * Update definitions.html * CRD versioning Public Documentation (#8834) * CRD versioning Public Documentation * Copyedit Signed-off-by: Misty Stanley-Jones <[email protected]> * Address feedback * More rewrites * Address feedback * Update main CRD page in light of versioning * Reorg CRD docs * Further reorg * Tweak title * CSI documentation update for raw block volume support (#8927) * CSI documetation update for raw block volume support * minor edits for "CSI raw block volume support" Some small grammar and style nits. * minor CSIBlockVolume edits * Update kubectl component ref page for 1.11. (#9094) * Update kubectl component ref page for 1.11. * Add title. Replace stevepe with username. * crd versioning doc: fix nits (#9142) * Update `DynamicKubeletConfig` feature to beta (#9110) xref: kubernetes/kubernetes#64275 * Documentation for dynamic volume limits based on node type (#8871) * add cos for storage limits * Update docs specific for aws and gce * fix some minor things * Update storage-limits.md * Add k8s version to feature-state shortcode * The Doc update for ScheduleDaemonSetPods (#8842) Signed-off-by: Da K. Ma <[email protected]> * Update docs related to PersistentVolumeLabel admission control (#9109) The said admission controller is disabled by default in 1.11 (kubernetes/kubernetes#64326) and scheduled to be removed in future release. * client exec auth: updates for 1.11 (#9154) * Updates HA kubeadm docs (#9066) * Updates HA kubeadm docs Signed-off-by: Chuck Ha <[email protected]> * kubeadm HA - Add stacked control plane steps * ssh instructions and some typos in the bash scripts Signed-off-by: Chuck Ha <[email protected]> * Fix typos and copypasta errors * Fix rebase issues * Integrate more changes Signed-off-by: Chuck Ha <[email protected]> * copyedits, layout and formatting fixes * final copyedits * Adds a sanity check for load balancer connection Signed-off-by: Chuck Ha <[email protected]> * formatting fixes, copyedits * fix typos, formatting * Document the Pod Ready++ feature (#9180) Closes: #9107 Xref: kubernetes/kubernetes#64057 * Mention 'KubeletPluginsWatcher' feature (#9177) * Mention 'KubeletPluginsWatcher' feature This feature is more developers oriented than users oriented, so simply mention it in the feature gate should be fine. In future, when the design doc is migrated from Google doc to the kubernetes/community repo, we can add links to it for users who want to dig deeper. Closes: #9108 Xref: kubernetes/kubernetes#63328, kubernetes/kubernetes#64605 * Copyedit * Amend dynamic volume list docs (#9181) The dynamic volume list feature has been documented but the feature gate related was not there yet. Closes: #9105 * Document for service account projection (#9182) This adds docs for the service account projection feature. Xref: kubernetes/kubernetes#63819, kubernetes/community#1973 Closes: #9102 * Update pod priority and preemption user docs (#9172) * Update pod priority and preemption user docs * Copyedit * Documentation on setting node name with Kubeadm (#8925) * Documentation on setting node name with Kubeadm * copyedit * Add kubeadm upgrade docs for 1.11 (#9089) * Add kubeadm upgrade docs for 1.11 * Initial docs review feedback * Add 1-11 to outline * Fix formatting on tab blocks * Move file to correct location * Add `kubeadm upgrade node config` step * Overzealous ediffing * copyedit, fix lists and headings * clarify --force flag for fixing bad state * Get TOML ready for 1.11 release * Blog post for 1.11 release (#9254) * Blog post for 1.11 release * Update 2018-06-26-kubernetes-1.11-release-announcement.md * Update 2018-06-26-kubernetes-1.11-release-announcement.md * Update 2018-06-26-kubernetes-1.11-release-announcement.md
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Documentation for CRD Versioning feature kubernetes/enhancements#544
Note: The PR is not ready for review. Just created as a placeholder.