-
Notifications
You must be signed in to change notification settings - Fork 14.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add glossary term for CRD #6594
Conversation
Custom Resource Definition, that replaces Third Party Resources.
Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). 📝 Please follow instructions at https://github.com/kubernetes/kubernetes/wiki/CLA-FAQ to sign the CLA. It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.
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. I understand the commands that are listed here. |
@Bubblemelon you need to sign the Linux Foundation CLA. Also check the Travis build error -- looks as though there's some munged syntax in your commit. (Haven't looked at it yet ...) |
I have just finished signing the cla terms and agreements. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Difficult to make this one short, complete, and accurate, but check out individual line comments for some suggestions.
- fundamental | ||
- operation | ||
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
short description should be a fragment. When we automatically add it to a docs topic, the first part is automatically added. So should start "The representation of ..."
But ... this is also pretty thin as a short description. You can customize a K8s cluster lots o' ways -- what makes a CRD different? (Feel free to ping on Slack if you have questions)
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. | ||
long-description: > | ||
A resource definition that defines the endpoint in the Kubernetes API that stores a collection of API objects of a certain kind that is specified. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This suggests that you need to add a CRD to be able to call an existing endpoint. But in fact you write a CRD to create custom resources (so that you don't have to write a whole custom K8s API server). If you want to do some more research, here's a great blog post by one of my Heptio colleagues: https://blog.heptio.com/an-introduction-to-extending-kubernetes-with-customresourcedefinitions-76deb675b27a
This is a super tricky term and concept, so bonus points for tackling it!
Oh, and the munged syntax I think is with the tag location. |
Hello @Bradamant3, thanks for giving the the heads up. There's some silly formating errors. :) |
Minor formating error
Deploy preview ready! Built with commit 312d686 https://deploy-preview-6594--kubernetes-io-master-staging.netlify.com |
turns out the id: key is necessary ! |
missing id key
Hi @Bradamant3 , mind giving me clues on how to pass this travis-ci check ? |
deleted aka key
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK, looks as though you've got the file happy in the build. Now take a look at the line-specific review comments from my first review -- let me know if anything isn't clear.
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. | ||
long-description: > | ||
A resource definition that defines the endpoint in the Kubernetes API that stores a collection of API objects of a certain kind that is specified. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that is specified
reads awkwardly, probably can be removed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
okay noted!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Bubblemelon Thanks for submitting this PR! 🎉
Left a bunch of comments but the PR is awesome as-is. 😄
@@ -0,0 +1,10 @@ | |||
id: Custom Resource Definition |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CustomResourceDefinition is one word.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done ! 😄
@@ -0,0 +1,10 @@ | |||
id: Custom Resource Definition | |||
name: Custom Resource Definition |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CustomResourceDefinition is one word.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
name: Custom Resource Definition | ||
tags: | ||
- fundamental | ||
- operation |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also extension
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
tags: | ||
- fundamental | ||
- operation | ||
full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This link mainly talks about TPRs. Please link to https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done 😃
- operation | ||
full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/ | ||
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Something like: An API object that provides a way of extending the Kubernetes API by defining custom objects.
?
Would prefer to use the word "API object" to stay consistent with Deployment
, Service
, etc. Also, because it is an API object. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The trouble with "API object" in this context is that an object is created from a call to a resource. Which, in this case, is a resource created by the CRD. (The core docs page on CRDs is confusing here, and makes a muddle out of "endpoint", "resource", "object".) There's no easy solution here, I'm afraid. Also, short description still needs to be made a fragment.
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. | ||
long-description: > | ||
A resource definition that defines the endpoint in the Kubernetes API that stores a collection of API objects of a certain kind that is specified. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Something like: Creating a CustomResourceDefinition creates a new RESTful API endpoint which can be used to create and manage custom resources.
?
We should also have a glossary term for custom resources (and we could link it here). Most users who search for CRDs also search for custom resources.
tags: | ||
- fundamental | ||
- operation | ||
full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would also add aka
below this. See https://github.com/kubernetes/website/blob/master/_data/glossary/_example.yml#L4.
Points under aka
:
- CRD
- Formerly known as Third Party Resource (TPR)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, related
below aka
. See https://github.com/kubernetes/website/blob/master/_data/glossary/_example.yml#L8.
Points under related
:
- id for the glossary of custom resources (please create a dummy link here, we can add the glossary for custom resources later)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @nikhita ! Thanks for providing all these great suggestions. The _example.yml was particularly helpful. 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll leave the related section aside for now until someone responds to your request on this issue. However I would agree that custom resources should have its own glossary definition 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll leave the related section aside for now until someone responds to your request on this issue.
Sure, makes sense. 👍
@Bubblemelon Can you update the PR title to say something like |
Made a minor edit to "name" and "id" and added "aka" section, but should require a "related" section. The related section may have the Custom Resource term, but there is currently no glossary term for Custom Resource.
@Bubblemelon Thanks for making the changes! 😄 Can you also update the description? I think we can use custom objects even without mentioning the glossary term for custom resources. But I would like someone from the docs team to comment if this fine. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still needs some more work. This is a difficult item -- kudos for taking it on!
- operation | ||
full-link: docs/tasks/access-kubernetes-api/migrate-third-party-resource/ | ||
short-description: > | ||
A custom resource definition is the representation of a customization of a particular Kubernetes installation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The trouble with "API object" in this context is that an object is created from a call to a resource. Which, in this case, is a resource created by the CRD. (The core docs page on CRDs is confusing here, and makes a muddle out of "endpoint", "resource", "object".) There's no easy solution here, I'm afraid. Also, short description still needs to be made a fragment.
/lgtm |
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Bradamant3 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 |
need to merge and make more changes in new PR
* Add files via upload Custom Resource Definition, that replaces Third Party Resources. * Update customresourcedefinition.yaml Minor formating error * Update customresourcedefinition.yaml missing id key * Update customresourcedefinition.yaml deleted aka key * Update customresourcedefinition.yaml Made a minor edit to "name" and "id" and added "aka" section, but should require a "related" section. The related section may have the Custom Resource term, but there is currently no glossary term for Custom Resource.
* Add files via upload Custom Resource Definition, that replaces Third Party Resources. * Update customresourcedefinition.yaml Minor formating error * Update customresourcedefinition.yaml missing id key * Update customresourcedefinition.yaml deleted aka key * Update customresourcedefinition.yaml Made a minor edit to "name" and "id" and added "aka" section, but should require a "related" section. The related section may have the Custom Resource term, but there is currently no glossary term for Custom Resource.
This resolves part of issue #5993, adding Custom Resource Definition replacing Third Party Resource.
This change is![Reviewable](https://camo.githubusercontent.com/2d899f4291d07d3cd2fa4aaae1e3b243f164c23fce87d30a589ace0d496a444c/68747470733a2f2f72657669657761626c652e6b756265726e657465732e696f2f7265766965775f627574746f6e2e737667)